[PM-5692] Extract generators to separate crate

.github/workflows/build-rust-crates.yml

@@ -29,9 +29,10 @@ jobs:
 
         package:
           - bitwarden
-          - bitwarden-crypto
           - bitwarden-api-api
           - bitwarden-api-identity
+          - bitwarden-crypto
+          - bitwarden-generators
 
     steps:
       - name: Checkout

.github/workflows/publish-rust-crates.yml

@@ -34,6 +34,11 @@ on:
         required: true
         default: true
         type: boolean
+      publish_bitwarden-generators:
+        description: "Publish bitwarden-generators crate"
+        required: true
+        default: true
+        type: boolean
 
 defaults:
   run:
@@ -67,6 +72,7 @@ jobs:
           PUBLISH_BITWARDEN_API_API: ${{ github.event.inputs.publish_bitwarden-api-api }}
           PUBLISH_BITWARDEN_API_IDENTITY: ${{ github.event.inputs.publish_bitwarden-api-identity }}
           PUBLISH_BITWARDEN_CRYPTO: ${{ github.event.inputs.publish_bitwarden-crypto }}
+          PUBLISH_BITWARDEN_GENERATORS: ${{ github.event.inputs.publish_bitwarden-generators }}
         run: |
           if [[ "$PUBLISH_BITWARDEN" == "false" ]] && [[ "$PUBLISH_BITWARDEN_API_API" == "false" ]] && [[ "$PUBLISH_BITWARDEN_API_IDENTITY" == "false" ]]; then
             echo "==================================="
@@ -98,6 +104,11 @@ jobs:
             PACKAGES_LIST="$PACKAGES_LIST bitwarden-crypto"
           fi
 
+          if [[ "$PUBLISH_BITWARDEN_GENERATORS" == "true" ]]; then
+            PACKAGES_COMMAND="$PACKAGES_COMMAND -p bitwarden-generators"
+            PACKAGES_LIST="$PACKAGES_LIST bitwarden-generators"
+          fi
+
           echo "Packages command: " $PACKAGES_COMMAND
           echo "Packages list: " $PACKAGES_LIST
 

.github/workflows/version-bump.yml

@@ -14,6 +14,7 @@ on:
           - bitwarden-api-api
           - bitwarden-api-identity
           - bitwarden-crypto
+          - bitwarden-generators
           - bitwarden-json
           - cli
           - napi
@@ -123,6 +124,12 @@ jobs:
         if: ${{ inputs.project == 'bitwarden-crypto' }}
         run: cargo-set-version set-version -p bitwarden-crypto ${{ inputs.version_number }}
 
+      ### bitwarden-generators
+
+      - name: Bump bitwarden-generators crate Version
+        if: ${{ inputs.project == 'bitwarden-generators' }}
+        run: cargo-set-version set-version -p bitwarden-generators ${{ inputs.version_number }}
+
       ### cli
 
       - name: Bump cli Version

crates/bitwarden-generators/Cargo.toml

@@ -0,0 +1,25 @@
+[package]
+name = "bitwarden-generators"
+version = "0.1.0"
+edition = "2021"
+
+
+[features]
+mobile = ["uniffi"] # Mobile-specific features
+
+[dependencies]
+bitwarden-crypto = { path = "../bitwarden-crypto", version = "=0.1.0" }
+rand = ">=0.8.5, <0.9"
+reqwest = { version = ">=0.11, <0.12", features = [
+    "json",
+], default-features = false }
+schemars = { version = ">=0.8.9, <0.9", features = ["uuid1", "chrono"] }
+serde = { version = ">=1.0, <2.0", features = ["derive"] }
+serde_json = ">=1.0.96, <2.0"
+thiserror = ">=1.0.40, <2.0"
+uniffi = { version = "=0.25.2", optional = true }
+
+[dev-dependencies]
+rand_chacha = "0.3.1"
+tokio = { version = "1.35.1", features = ["rt", "macros"] }
+wiremock = "0.5.22"

crates/bitwarden-generators/src/error.rs

@@ -0,0 +1,13 @@
+use thiserror::Error;
+
+use crate::{passphrase::PassphraseError, password::PasswordError, username::UsernameError};
+
+#[derive(Debug, Error)]
+pub enum GeneratorError {
+    #[error(transparent)]
+    PassphraseErrors(#[from] PassphraseError),
+    #[error(transparent)]
+    PasswordError(#[from] PasswordError),
+    #[error(transparent)]
+    UsernameError(#[from] UsernameError),
+}

crates/bitwarden-generators/src/lib.rs

@@ -0,0 +1,13 @@
+mod passphrase;
+pub use passphrase::{passphrase, PassphraseGeneratorRequest};
+mod error;
+mod util;
+pub use error::GeneratorError;
+mod password;
+pub use password::{password, PasswordGeneratorRequest};
+mod username;
+pub use username::{username, ForwarderServiceType, UsernameGeneratorRequest};
+mod username_forwarders;
+
+#[cfg(feature = "mobile")]
+uniffi::setup_scaffolding!();

crates/bitwarden/src/tool/generators/passphrase.rs → crates/bitwarden-generators/src/passphrase.rs

@@ -2,8 +2,17 @@
 use rand::{seq::SliceRandom, Rng, RngCore};
 use schemars::JsonSchema;
 use serde::{Deserialize, Serialize};
+use thiserror::Error;
 
-use crate::{error::Result, util::capitalize_first_letter};
+use crate::{error::GeneratorError, util::capitalize_first_letter};
+
+#[derive(Debug, Error)]
+pub enum PassphraseError {
+    #[error("'num_words' must be between {} and {}", minimum, maximum)]
+    InvalidNumWords { minimum: u8, maximum: u8 },
+    #[error("'word_separator' cannot be empty")]
+    EmptyWordSeparator,
+}
 
 /// Passphrase generator request options.
 #[derive(Serialize, Deserialize, Debug, JsonSchema)]
@@ -46,16 +55,19 @@
 
 impl PassphraseGeneratorRequest {
     /// Validates the request and returns an immutable struct with valid options to use with the passphrase generator.
-    fn validate_options(self) -> Result<ValidPassphraseGeneratorOptions> {
+    fn validate_options(self) -> Result<ValidPassphraseGeneratorOptions, PassphraseError> {
         // TODO: Add password generator policy checks
 
         if !(MINIMUM_PASSPHRASE_NUM_WORDS..=MAXIMUM_PASSPHRASE_NUM_WORDS).contains(&self.num_words)
         {
-            return Err(format!("'num_words' must be between {MINIMUM_PASSPHRASE_NUM_WORDS} and {MAXIMUM_PASSPHRASE_NUM_WORDS}").into());
+            return Err(PassphraseError::InvalidNumWords {
+                minimum: MINIMUM_PASSPHRASE_NUM_WORDS,
+                maximum: MAXIMUM_PASSPHRASE_NUM_WORDS,
+            });
         }
 
         if self.word_separator.chars().next().is_none() {
-            return Err("'word_separator' cannot be empty".into());
+            return Err(PassphraseError::EmptyWordSeparator);
         };
 
         Ok(ValidPassphraseGeneratorOptions {
@@ -67,13 +79,8 @@
     }
 }
 
-/// Implementation of the random passphrase generator. This is not accessible to the public API.
-/// See [`ClientGenerator::passphrase`](crate::ClientGenerator::passphrase) for the API function.
-///
-/// # Arguments:
-/// * `options`: Valid parameters used to generate the passphrase. To create it, use
-///     [`PassphraseGeneratorRequest::validate_options`](PassphraseGeneratorRequest::validate_options).
-pub(super) fn passphrase(request: PassphraseGeneratorRequest) -> Result<String> {
+/// Implementation of the random passphrase generator.
+pub fn passphrase(request: PassphraseGeneratorRequest) -> Result<String, GeneratorError> {
     let options = request.validate_options()?;
     Ok(passphrase_with_rng(rand::thread_rng(), options))
 }

crates/bitwarden/src/tool/generators/password.rs → crates/bitwarden-generators/src/password.rs

@@ -3,8 +3,17 @@
 use rand::{distributions::Distribution, seq::SliceRandom, RngCore};
 use schemars::JsonSchema;
 use serde::{Deserialize, Serialize};
+use thiserror::Error;
 
-use crate::error::Result;
+use crate::GeneratorError;
+
+#[derive(Debug, Error)]
+pub enum PasswordError {
+    #[error("No character set enabled")]
+    NoCharacterSetEnabled,
+    #[error("Invalid password length")]
+    InvalidLength,
+}
 
 /// Password generator request options.
 #[derive(Serialize, Deserialize, Debug, JsonSchema)]
@@ -32,7 +41,7 @@
     /// When set, the value must be between 1 and 9. This value is ignored is lowercase is false
     pub min_lowercase: Option<u8>,
     /// The minimum number of uppercase characters in the generated password.
-    /// When set, the value must be between 1 and 9. This value is ignored is uppercase is false  
+    /// When set, the value must be between 1 and 9. This value is ignored is uppercase is false
     pub min_uppercase: Option<u8>,
     /// The minimum number of numbers in the generated password.
     /// When set, the value must be between 1 and 9. This value is ignored is numbers is false
@@ -128,16 +137,16 @@
 
 impl PasswordGeneratorRequest {
     /// Validates the request and returns an immutable struct with valid options to use with the password generator.
-    fn validate_options(self) -> Result<PasswordGeneratorOptions> {
+    fn validate_options(self) -> Result<PasswordGeneratorOptions, PasswordError> {
         // TODO: Add password generator policy checks
 
         // We always have to have at least one character set enabled
         if !self.lowercase && !self.uppercase && !self.numbers && !self.special {
-            return Err("At least one character set must be enabled".into());
+            return Err(PasswordError::NoCharacterSetEnabled);
         }
 
         if self.length < 4 {
-            return Err("A password must be at least 4 characters long".into());
+            return Err(PasswordError::InvalidLength);
         }
 
         // Make sure the minimum values are zero when the character
@@ -159,7 +168,7 @@
         // Check that the minimum lengths aren't larger than the password length
         let minimum_length = min_lowercase + min_uppercase + min_number + min_special;
         if minimum_length > length {
-            return Err("Password length can't be less than the sum of the minimums".into());
+            return Err(PasswordError::InvalidLength);
         }
 
         let lower = (
@@ -208,9 +217,8 @@
     }
 }
 
-/// Implementation of the random password generator. This is not accessible to the public API.
-/// See [`ClientGenerator::password`](crate::ClientGenerator::password) for the API function.
-pub(super) fn password(input: PasswordGeneratorRequest) -> Result<String> {
+/// Implementation of the random password generator.
+pub fn password(input: PasswordGeneratorRequest) -> Result<String, GeneratorError> {
     let options = input.validate_options()?;
     Ok(password_with_rng(rand::thread_rng(), options))
 }

crates/bitwarden/src/tool/generators/username.rs → crates/bitwarden-generators/src/username.rs

@@ -1,9 +1,25 @@
 use bitwarden_crypto::EFF_LONG_WORD_LIST;
 use rand::{distributions::Distribution, seq::SliceRandom, Rng, RngCore};
+use reqwest::StatusCode;
 use schemars::JsonSchema;
 use serde::{Deserialize, Serialize};
+use thiserror::Error;
 
-use crate::{error::Result, util::capitalize_first_letter};
+use crate::{util::capitalize_first_letter, GeneratorError};
+
+#[derive(Debug, Error)]
+pub enum UsernameError {
+    #[error("Invalid API Key")]
+    InvalidApiKey,
+    #[error("Unknown error")]
+    Unknown,
+
+    #[error("Received error message from server: [{}] {}", .status, .message)]
+    ResponseContent { status: StatusCode, message: String },
+
+    #[error(transparent)]
+    Reqwest(#[from] reqwest::Error),
+}
 
 #[derive(Serialize, Deserialize, Debug, JsonSchema)]
 #[serde(rename_all = "camelCase", deny_unknown_fields)]
@@ -85,10 +101,14 @@
 impl ForwarderServiceType {
     // Generate a username using the specified email forwarding service
     // This requires an HTTP client to be passed in, as the service will need to make API calls
-    pub async fn generate(self, http: &reqwest::Client, website: Option<String>) -> Result<String> {
+    pub async fn generate(
+        self,
+        http: &reqwest::Client,
+        website: Option<String>,
+    ) -> Result<String, UsernameError> {
         use ForwarderServiceType::*;
 
-        use crate::tool::generators::username_forwarders::*;
+        use crate::username_forwarders::*;
 
         match self {
             AddyIo {
@@ -107,14 +127,14 @@
     }
 }
 
-/// Implementation of the username generator. This is not accessible to the public API.
-/// See [`ClientGenerator::username`](crate::ClientGenerator::username) for the API function.
+/// Implementation of the username generator.
+///
 /// Note: The HTTP client is passed in as a required parameter for convenience,
 /// as some username generators require making API calls.
-pub(super) async fn username(
+pub async fn username(
     input: UsernameGeneratorRequest,
     http: &reqwest::Client,
-) -> Result<String> {
+) -> Result<String, GeneratorError> {
     use rand::thread_rng;
     use UsernameGeneratorRequest::*;
     match input {
@@ -124,7 +144,7 @@
         } => Ok(username_word(&mut thread_rng(), capitalize, include_number)),
         Subaddress { r#type, email } => Ok(username_subaddress(&mut thread_rng(), r#type, email)),
         Catchall { r#type, domain } => Ok(username_catchall(&mut thread_rng(), r#type, domain)),
-        Forwarded { service, website } => service.generate(http, website).await,
+        Forwarded { service, website } => Ok(service.generate(http, website).await?),
     }
 }