[PM-24051] MasterPasswordUnlockData model with response mapping and adds it to identity success response model (#376)

## 🎟️ Tracking

https://bitwarden.atlassian.net/browse/PM-24051

## 📔 Objective

Adds `MasterPasswordUnlockData` model with
`MasterPasswordUnlockResponseModel` mapping. This wi
Adds `UserDecryptionOptionsResponseModel` into the identity success
token response. This model includes the master password unlock field.
The `/sync` response model is autogenerated by OpenApi and already
includes user decryption option and the master password unlock fields.
Includes Uniffi and WASM bindings for `MasterPasswordUnlock`.

In further PR's we plan to use the `MasterPasswordUnlock` in
`InitUserCryptoMethod` enum - this is still in discussion.

## ⏰ Reminders before review

- Contributor guidelines followed
- All formatters and local linters executed and passed
- Written new unit and / or integration tests where applicable
- Protected functional changes with optionality (feature flags)
- Used internationalization (i18n) for all UI strings
- CI builds passed
- Communicated to DevOps any deployment requirements
- Updated any necessary documentation (Confluence, contributing docs) or
informed the documentation
  team

## 🦮 Reviewer guidelines

<!-- Suggested interactions but feel free to use (or not) as you desire!
-->

- 👍 (`:+1:`) or similar for great changes
- 📝 (`:memo:`) or ℹ️ (`:information_source:`) for notes or general info
- ❓ (`:question:`) for questions
- 🤔 (`:thinking:`) or 💭 (`:thought_balloon:`) for more open inquiry
that's not quite a confirmed
  issue and could potentially benefit from discussion
- 🎨 (`:art:`) for suggestions / improvements
- ❌ (`:x:`) or ⚠️ (`:warning:`) for more significant problems or
concerns needing attention
- 🌱 (`:seedling:`) or ♻️ (`:recycle:`) for future improvements or
indications of technical debt
- ⛏ (`:pick:`) for minor or nitpick changes

Author: mzieniukbw

crates/bitwarden-core/src/auth/api/response/identity_success_response.rs

@@ -4,6 +4,8 @@ use bitwarden_api_identity::models::KdfType;
 use serde::{Deserialize, Serialize};
 use serde_json::Value;
 
+use crate::auth::api::response::user_decryption_options_response::UserDecryptionOptionsResponseModel;
+
 #[derive(Serialize, Deserialize, Debug, PartialEq)]
 pub(crate) struct IdentityTokenSuccessResponse {
     pub access_token: String,
@@ -35,6 +37,9 @@ pub(crate) struct IdentityTokenSuccessResponse {
     #[serde(rename = "keyConnectorUrl", alias = "KeyConnectorUrl")]
     key_connector_url: Option<String>,
 
+    #[serde(rename = "userDecryptionOptions", alias = "UserDecryptionOptions")]
+    user_decryption_options: Option<UserDecryptionOptionsResponseModel>,
+
     /// Stores unknown api response fields
     extra: Option<HashMap<String, Value>>,
 }
@@ -61,6 +66,7 @@ mod test {
                 force_password_reset: Default::default(),
                 api_use_key_connector: Default::default(),
                 key_connector_url: Default::default(),
+                user_decryption_options: Default::default(),
                 extra: Default::default(),
             }
         }

crates/bitwarden-core/src/auth/api/response/mod.rs

@@ -6,6 +6,7 @@ mod identity_token_response;
 mod identity_two_factor_response;
 pub(crate) mod two_factor_provider_data;
 mod two_factor_providers;
+pub(crate) mod user_decryption_options_response;
 
 pub(crate) use identity_payload_response::*;
 pub(crate) use identity_refresh_response::*;

crates/bitwarden-core/src/auth/api/response/user_decryption_options_response.rs

@@ -0,0 +1,16 @@
+use bitwarden_api_api::models::MasterPasswordUnlockResponseModel;
+use serde::{Deserialize, Serialize};
+
+/// Provides user decryption options used to unlock user's vault.
+/// Currently, only master password unlock is supported.
+#[allow(dead_code)]
+#[derive(Serialize, Deserialize, Debug, PartialEq)]
+pub(crate) struct UserDecryptionOptionsResponseModel {
+    /// Contains information needed to unlock user's vault with master password.
+    /// None when user have no master password.
+    #[serde(
+        rename = "masterPasswordUnlock",
+        skip_serializing_if = "Option::is_none"
+    )]
+    pub(crate) master_password_unlock: Option<MasterPasswordUnlockResponseModel>,
+}

crates/bitwarden-core/src/auth/mod.rs

@@ -9,6 +9,8 @@ use crate::{NotAuthenticatedError, VaultLockedError, WrongPasswordError};
 mod access_token;
 // API is intentionally not visible outside of `auth` as these should be considered private.
 mod api;
+#[cfg(feature = "internal")]
+pub(crate) use api::response::user_decryption_options_response::UserDecryptionOptionsResponseModel;
 #[allow(missing_docs)]
 pub mod auth_client;
 mod jwt_token;

crates/bitwarden-core/src/key_management/master_password.rs

@@ -0,0 +1,310 @@
+use std::num::NonZeroU32;
+
+use bitwarden_api_api::models::{
+    master_password_unlock_response_model::MasterPasswordUnlockResponseModel, KdfType,
+};
+use bitwarden_crypto::{EncString, Kdf};
+use bitwarden_error::bitwarden_error;
+use serde::{Deserialize, Serialize};
+
+use crate::{require, MissingFieldError};
+
+/// Error for master password related operations.
+#[allow(dead_code)]
+#[bitwarden_error(flat)]
+#[derive(Debug, thiserror::Error)]
+pub(crate) enum MasterPasswordError {
+    /// The wrapped encryption key could not be parsed because the encstring is malformed
+    #[error("Wrapped encryption key is malformed")]
+    EncryptionKeyMalformed,
+    /// The KDF data could not be parsed, because it has an invalid value
+    #[error("KDF is malformed")]
+    KdfMalformed,
+    /// The wrapped encryption key or salt fields are missing or KDF data is incomplete
+    #[error(transparent)]
+    MissingField(#[from] MissingFieldError),
+}
+
+/// Represents the data required to unlock with the master password.
+#[allow(dead_code)]
+#[derive(Serialize, Deserialize, Debug)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub(crate) struct MasterPasswordUnlockData {
+    /// The key derivation function used to derive the master key
+    kdf: Kdf,
+    /// The master key wrapped user key
+    master_key_wrapped_user_key: EncString,
+    /// The salt used in the KDF, typically the user's email
+    salt: String,
+}
+
+impl TryFrom<MasterPasswordUnlockResponseModel> for MasterPasswordUnlockData {
+    type Error = MasterPasswordError;
+
+    fn try_from(response: MasterPasswordUnlockResponseModel) -> Result<Self, Self::Error> {
+        let kdf = match response.kdf.kdf_type {
+            KdfType::PBKDF2_SHA256 => Kdf::PBKDF2 {
+                iterations: kdf_parse_nonzero_u32(response.kdf.iterations)?,
+            },
+            KdfType::Argon2id => Kdf::Argon2id {
+                iterations: kdf_parse_nonzero_u32(response.kdf.iterations)?,
+                memory: kdf_parse_nonzero_u32(require!(response.kdf.memory))?,
+                parallelism: kdf_parse_nonzero_u32(require!(response.kdf.parallelism))?,
+            },
+        };
+
+        let master_key_encrypted_user_key = require!(response.master_key_encrypted_user_key);
+        let salt = require!(response.salt);
+
+        Ok(MasterPasswordUnlockData {
+            kdf,
+            master_key_wrapped_user_key: master_key_encrypted_user_key
+                .parse()
+                .map_err(|_| MasterPasswordError::EncryptionKeyMalformed)?,
+            salt,
+        })
+    }
+}
+
+fn kdf_parse_nonzero_u32(value: impl TryInto<u32>) -> Result<NonZeroU32, MasterPasswordError> {
+    value
+        .try_into()
+        .ok()
+        .and_then(NonZeroU32::new)
+        .ok_or(MasterPasswordError::KdfMalformed)
+}
+
+#[cfg(test)]
+mod tests {
+    use bitwarden_api_api::models::{KdfType, MasterPasswordUnlockKdfResponseModel};
+
+    use super::*;
+
+    const TEST_USER_KEY: &str = "2.Q/2PhzcC7GdeiMHhWguYAQ==|GpqzVdr0go0ug5cZh1n+uixeBC3oC90CIe0hd/HWA/pTRDZ8ane4fmsEIcuc8eMKUt55Y2q/fbNzsYu41YTZzzsJUSeqVjT8/iTQtgnNdpo=|dwI+uyvZ1h/iZ03VQ+/wrGEFYVewBUUl/syYgjsNMbE=";
+    const TEST_INVALID_USER_KEY: &str = "-1.8UClLa8IPE1iZT7chy5wzQ==|6PVfHnVk5S3XqEtQemnM5yb4JodxmPkkWzmDRdfyHtjORmvxqlLX40tBJZ+CKxQWmS8tpEB5w39rbgHg/gqs0haGdZG4cPbywsgGzxZ7uNI=";
+    const TEST_SALT: &str = "[email protected]";
+
+    fn create_pbkdf2_response(
+        master_key_encrypted_user_key: Option<String>,
+        salt: Option<String>,
+        iterations: i32,
+    ) -> MasterPasswordUnlockResponseModel {
+        MasterPasswordUnlockResponseModel {
+            kdf: Box::new(MasterPasswordUnlockKdfResponseModel {
+                kdf_type: KdfType::PBKDF2_SHA256,
+                iterations,
+                memory: None,
+                parallelism: None,
+            }),
+            master_key_encrypted_user_key,
+            salt,
+        }
+    }
+
+    #[test]
+    fn test_try_from_master_password_unlock_response_model_pbkdf2_success() {
+        let response = create_pbkdf2_response(
+            Some(TEST_USER_KEY.to_string()),
+            Some(TEST_SALT.to_string()),
+            600_000,
+        );
+
+        let data = MasterPasswordUnlockData::try_from(response).unwrap();
+
+        if let Kdf::PBKDF2 { iterations } = data.kdf {
+            assert_eq!(iterations.get(), 600_000);
+        } else {
+            panic!("Expected PBKDF2 KDF")
+        }
+
+        assert_eq!(data.salt, TEST_SALT);
+        assert_eq!(data.master_key_wrapped_user_key.to_string(), TEST_USER_KEY);
+    }
+
+    #[test]
+    fn test_try_from_master_password_unlock_response_model_argon2id_success() {
+        let response = MasterPasswordUnlockResponseModel {
+            kdf: Box::new(MasterPasswordUnlockKdfResponseModel {
+                kdf_type: KdfType::Argon2id,
+                iterations: 3,
+                memory: Some(64),
+                parallelism: Some(4),
+            }),
+            master_key_encrypted_user_key: Some(TEST_USER_KEY.to_string()),
+            salt: Some(TEST_SALT.to_string()),
+        };
+
+        let data = MasterPasswordUnlockData::try_from(response).unwrap();
+
+        if let Kdf::Argon2id {
+            iterations,
+            memory,
+            parallelism,
+        } = data.kdf
+        {
+            assert_eq!(iterations.get(), 3);
+            assert_eq!(memory.get(), 64);
+            assert_eq!(parallelism.get(), 4);
+        } else {
+            panic!("Expected Argon2id KDF")
+        }
+
+        assert_eq!(data.salt, TEST_SALT);
+        assert_eq!(data.master_key_wrapped_user_key.to_string(), TEST_USER_KEY);
+    }
+
+    #[test]
+    fn test_try_from_master_password_unlock_response_model_invalid_user_key_encryption_kdf_malformed_error(
+    ) {
+        let response = create_pbkdf2_response(
+            Some(TEST_INVALID_USER_KEY.to_string()),
+            Some(TEST_SALT.to_string()),
+            600_000,
+        );
+
+        let result = MasterPasswordUnlockData::try_from(response);
+        assert!(matches!(
+            result,
+            Err(MasterPasswordError::EncryptionKeyMalformed)
+        ));
+    }
+
+    #[test]
+    fn test_try_from_master_password_unlock_response_model_user_key_none_missing_field_error() {
+        let response = create_pbkdf2_response(None, Some(TEST_SALT.to_string()), 600_000);
+
+        let result = MasterPasswordUnlockData::try_from(response);
+        assert!(matches!(
+            result,
+            Err(MasterPasswordError::MissingField(MissingFieldError(
+                "response.master_key_encrypted_user_key"
+            )))
+        ));
+    }
+
+    #[test]
+    fn test_try_from_master_password_unlock_response_model_salt_none_missing_field_error() {
+        let response = create_pbkdf2_response(Some(TEST_USER_KEY.to_string()), None, 600_000);
+
+        let result = MasterPasswordUnlockData::try_from(response);
+        assert!(matches!(
+            result,
+            Err(MasterPasswordError::MissingField(MissingFieldError(
+                "response.salt"
+            )))
+        ));
+    }
+
+    #[test]
+    fn test_try_from_master_password_unlock_response_model_argon2id_kdf_memory_none_missing_field_error(
+    ) {
+        let response = MasterPasswordUnlockResponseModel {
+            kdf: Box::new(MasterPasswordUnlockKdfResponseModel {
+                kdf_type: KdfType::Argon2id,
+                iterations: 3,
+                memory: None,
+                parallelism: Some(4),
+            }),
+            master_key_encrypted_user_key: Some(TEST_USER_KEY.to_string()),
+            salt: Some(TEST_SALT.to_string()),
+        };
+
+        let result = MasterPasswordUnlockData::try_from(response);
+        assert!(matches!(
+            result,
+            Err(MasterPasswordError::MissingField(MissingFieldError(
+                "response.kdf.memory"
+            )))
+        ));
+    }
+
+    #[test]
+    fn test_try_from_master_password_unlock_response_model_argon2id_kdf_memory_zero_kdf_malformed_error(
+    ) {
+        let response = MasterPasswordUnlockResponseModel {
+            kdf: Box::new(MasterPasswordUnlockKdfResponseModel {
+                kdf_type: KdfType::Argon2id,
+                iterations: 3,
+                memory: Some(0),
+                parallelism: Some(4),
+            }),
+            master_key_encrypted_user_key: Some(TEST_USER_KEY.to_string()),
+            salt: Some(TEST_SALT.to_string()),
+        };
+
+        let result = MasterPasswordUnlockData::try_from(response);
+        assert!(matches!(result, Err(MasterPasswordError::KdfMalformed)));
+    }
+
+    #[test]
+    fn test_try_from_master_password_unlock_response_model_argon2id_kdf_parallelism_none_missing_field_error(
+    ) {
+        let response = MasterPasswordUnlockResponseModel {
+            kdf: Box::new(MasterPasswordUnlockKdfResponseModel {
+                kdf_type: KdfType::Argon2id,
+                iterations: 3,
+                memory: Some(64),
+                parallelism: None,
+            }),
+            master_key_encrypted_user_key: Some(TEST_USER_KEY.to_string()),
+            salt: Some(TEST_SALT.to_string()),
+        };
+
+        let result = MasterPasswordUnlockData::try_from(response);
+        assert!(matches!(
+            result,
+            Err(MasterPasswordError::MissingField(MissingFieldError(
+                "response.kdf.parallelism"
+            )))
+        ));
+    }
+
+    #[test]
+    fn test_try_from_master_password_unlock_response_model_argon2id_kdf_parallelism_zero_kdf_malformed_error(
+    ) {
+        let response = MasterPasswordUnlockResponseModel {
+            kdf: Box::new(MasterPasswordUnlockKdfResponseModel {
+                kdf_type: KdfType::Argon2id,
+                iterations: 3,
+                memory: Some(64),
+                parallelism: Some(0),
+            }),
+            master_key_encrypted_user_key: Some(TEST_USER_KEY.to_string()),
+            salt: Some(TEST_SALT.to_string()),
+        };
+
+        let result = MasterPasswordUnlockData::try_from(response);
+        assert!(matches!(result, Err(MasterPasswordError::KdfMalformed)));
+    }
+
+    #[test]
+    fn test_try_from_master_password_unlock_response_model_pbkdf2_kdf_iterations_zero_kdf_malformed_error(
+    ) {
+        let response = create_pbkdf2_response(
+            Some(TEST_USER_KEY.to_string()),
+            Some(TEST_SALT.to_string()),
+            0,
+        );
+
+        let result = MasterPasswordUnlockData::try_from(response);
+        assert!(matches!(result, Err(MasterPasswordError::KdfMalformed)));
+    }
+
+    #[test]
+    fn test_try_from_master_password_unlock_response_model_argon2id_kdf_iterations_zero_kdf_malformed_error(
+    ) {
+        let response = MasterPasswordUnlockResponseModel {
+            kdf: Box::new(MasterPasswordUnlockKdfResponseModel {
+                kdf_type: KdfType::Argon2id,
+                iterations: 0,
+                memory: Some(64),
+                parallelism: Some(4),
+            }),
+            master_key_encrypted_user_key: Some(TEST_USER_KEY.to_string()),
+            salt: Some(TEST_SALT.to_string()),
+        };
+
+        let result = MasterPasswordUnlockData::try_from(response);
+        assert!(matches!(result, Err(MasterPasswordError::KdfMalformed)));
+    }
+}

crates/bitwarden-core/src/key_management/mod.rs

@@ -19,13 +19,17 @@ mod crypto_client;
 #[cfg(feature = "internal")]
 pub use crypto_client::CryptoClient;
 
+#[cfg(feature = "internal")]
+mod master_password;
 #[cfg(feature = "internal")]
 mod non_generic_wrappers;
 #[cfg(feature = "internal")]
 pub(crate) use non_generic_wrappers::*;
 #[cfg(feature = "internal")]
 mod security_state;
 #[cfg(feature = "internal")]
+mod user_decryption;
+#[cfg(feature = "internal")]
 pub use security_state::{SecurityState, SignedSecurityState};
 
 use crate::OrganizationId;