bitwarden_core/client/

internal.rs

use std::sync::{Arc, OnceLock, RwLock};

use bitwarden_crypto::KeyStore;
#[cfg(any(feature = "internal", feature = "secrets"))]
use bitwarden_crypto::SymmetricCryptoKey;
#[cfg(feature = "internal")]
use bitwarden_crypto::{
    EncString, Kdf, MasterKey, PinKey, UnsignedSharedKey, safe::PasswordProtectedKeyEnvelope,
};
use bitwarden_state::registry::StateRegistry;
#[cfg(feature = "internal")]
use tracing::{debug, info, instrument};

use crate::{
    DeviceType, UserId, auth::auth_tokens::TokenHandler, client::login_method::LoginMethod,
    error::UserIdAlreadySetError, key_management::KeyIds,
};
#[cfg(any(feature = "internal", feature = "secrets"))]
use crate::{OrganizationId, client::encryption_settings::EncryptionSettings};
#[cfg(feature = "internal")]
use crate::{
    client::{
        encryption_settings::EncryptionSettingsError, flags::Flags, login_method::UserLoginMethod,
    },
    error::NotAuthenticatedError,
    key_management::{
        MasterPasswordUnlockData, SecurityState, V2UpgradeToken,
        account_cryptographic_state::WrappedAccountCryptographicState,
    },
};

#[allow(missing_docs)]
pub struct ApiConfigurations {
    pub identity_client: bitwarden_api_identity::apis::ApiClient,
    pub api_client: bitwarden_api_api::apis::ApiClient,
    pub identity_config: bitwarden_api_identity::Configuration,
    pub api_config: bitwarden_api_api::Configuration,
    pub device_type: DeviceType,
}

impl std::fmt::Debug for ApiConfigurations {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("ApiConfigurations")
            .field("device_type", &self.device_type)
            .finish_non_exhaustive()
    }
}

impl ApiConfigurations {
    pub(crate) fn new(
        identity_config: bitwarden_api_identity::Configuration,
        api_config: bitwarden_api_api::Configuration,
        device_type: DeviceType,
    ) -> Arc<Self> {
        let identity = Arc::new(identity_config.clone());
        let api = Arc::new(api_config.clone());
        let identity_client = bitwarden_api_identity::apis::ApiClient::new(&identity);
        let api_client = bitwarden_api_api::apis::ApiClient::new(&api);
        Arc::new(Self {
            identity_client,
            api_client,
            identity_config,
            api_config,
            device_type,
        })
    }

    pub(crate) fn get_key_connector_client(
        self: &Arc<Self>,
        key_connector_url: String,
    ) -> bitwarden_api_key_connector::apis::ApiClient {
        let api = self.api_config.clone();

        let key_connector = bitwarden_api_base::Configuration {
            base_path: key_connector_url,
            client: api.client,
        };

        bitwarden_api_key_connector::apis::ApiClient::new(&Arc::new(key_connector))
    }
}

#[allow(missing_docs)]
pub struct InternalClient {
    pub(crate) user_id: OnceLock<UserId>,
    #[allow(
        unused,
        reason = "This is not used directly by SM, but it's used via the middleware"
    )]
    pub(crate) token_handler: Arc<dyn TokenHandler>,
    #[allow(
        unused,
        reason = "This is not used directly by SM, but it's used via the middleware"
    )]
    pub(crate) login_method: Arc<RwLock<Option<Arc<LoginMethod>>>>,

    #[cfg(feature = "internal")]
    pub(super) flags: RwLock<Flags>,

    pub(super) api_configurations: Arc<ApiConfigurations>,

    /// Reqwest client useable for external integrations like email forwarders, HIBP.
    #[allow(unused)]
    pub(crate) external_http_client: reqwest::Client,

    pub(super) key_store: KeyStore<KeyIds>,
    #[cfg(feature = "internal")]
    pub(crate) security_state: RwLock<Option<SecurityState>>,

    // TODO(PM-31876): Remove once Flags are migrated to Setting, which will add an in-crate
    // read path and satisfy the dead_code lint without suppression.
    #[allow(dead_code)]
    pub(crate) state_registry: StateRegistry,
}

impl InternalClient {
    /// Load feature flags. This is intentionally a collection and not the internal `Flag` enum as
    /// we want to avoid changes in feature flags from being a breaking change.
    #[cfg(feature = "internal")]
    #[expect(clippy::unused_async)]
    pub async fn load_flags(&self, flags: std::collections::HashMap<String, bool>) {
        *self.flags.write().expect("RwLock is not poisoned") = Flags::load_from_map(flags);
    }

    /// Retrieve the active feature flags.
    #[cfg(feature = "internal")]
    #[expect(clippy::unused_async)]
    pub async fn get_flags(&self) -> Flags {
        self.flags.read().expect("RwLock is not poisoned").clone()
    }

    #[cfg(feature = "internal")]
    #[expect(clippy::unused_async)]
    pub(crate) async fn get_login_method(&self) -> Option<UserLoginMethod> {
        let lm = self.login_method.read().expect("RwLock is not poisoned");
        match lm.as_deref()? {
            LoginMethod::User(ulm) => Some(ulm.clone()),
            #[allow(unreachable_patterns)]
            _ => None,
        }
    }

    #[cfg(any(feature = "internal", feature = "secrets"))]
    #[expect(clippy::unused_async)]
    pub(crate) async fn set_login_method(&self, login_method: LoginMethod) {
        use tracing::debug;

        debug!(?login_method, "setting login method.");
        *self.login_method.write().expect("RwLock is not poisoned") = Some(Arc::new(login_method));
    }

    #[cfg(any(feature = "internal", feature = "secrets"))]
    pub(crate) async fn set_tokens(
        &self,
        token: String,
        refresh_token: Option<String>,
        expires_in: u64,
    ) {
        self.token_handler
            .set_tokens(token, refresh_token, expires_in)
            .await;
    }

    #[allow(missing_docs)]
    #[cfg(feature = "internal")]
    #[expect(clippy::unused_async)]
    pub async fn get_kdf(&self) -> Result<Kdf, NotAuthenticatedError> {
        match self
            .login_method
            .read()
            .expect("RwLock is not poisoned")
            .as_deref()
        {
            Some(LoginMethod::User(
                UserLoginMethod::Username { kdf, .. } | UserLoginMethod::ApiKey { kdf, .. },
            )) => Ok(kdf.clone()),
            _ => Err(NotAuthenticatedError),
        }
    }

    pub fn get_key_connector_client(
        &self,
        key_connector_url: String,
    ) -> bitwarden_api_key_connector::apis::ApiClient {
        self.api_configurations
            .get_key_connector_client(key_connector_url)
    }

    /// Get the `ApiConfigurations` containing API clients and configurations for making requests to
    /// the Bitwarden services.
    pub fn get_api_configurations(&self) -> Arc<ApiConfigurations> {
        self.api_configurations.clone()
    }

    #[allow(missing_docs)]
    #[cfg(feature = "internal")]
    pub fn get_http_client(&self) -> &reqwest::Client {
        &self.external_http_client
    }

    #[allow(missing_docs)]
    pub fn get_key_store(&self) -> &KeyStore<KeyIds> {
        &self.key_store
    }

    /// Returns the security version of the user.
    /// `1` is returned for V1 users that do not have a signed security state.
    /// `2` or greater is returned for V2 users that have a signed security state.
    #[cfg(feature = "internal")]
    pub fn get_security_version(&self) -> u64 {
        self.security_state
            .read()
            .expect("RwLock is not poisoned")
            .as_ref()
            .map_or(1, |state| state.version())
    }

    #[allow(missing_docs)]
    pub fn init_user_id(&self, user_id: UserId) -> Result<(), UserIdAlreadySetError> {
        let set_uuid = self.user_id.get_or_init(|| user_id);

        // Only return an error if the user_id is already set to a different value,
        // as we want an SDK client to be tied to a single user_id.
        // If it's the same value, we can just do nothing.
        if *set_uuid != user_id {
            Err(UserIdAlreadySetError)
        } else {
            Ok(())
        }
    }

    #[allow(missing_docs)]
    pub fn get_user_id(&self) -> Option<UserId> {
        self.user_id.get().copied()
    }

    #[cfg(feature = "internal")]
    #[instrument(err, skip_all)]
    pub(crate) fn initialize_user_crypto_key_connector_key(
        &self,
        master_key: MasterKey,
        user_key: EncString,
        account_crypto_state: WrappedAccountCryptographicState,
        upgrade_token: &Option<V2UpgradeToken>,
    ) -> Result<(), EncryptionSettingsError> {
        let user_key = master_key.decrypt_user_key(user_key)?;
        self.initialize_user_crypto_decrypted_key(user_key, account_crypto_state, upgrade_token)
    }

    #[cfg(feature = "internal")]
    #[instrument(err, skip_all, fields(user_id = ?self.get_user_id()))]
    pub(crate) fn initialize_user_crypto_decrypted_key(
        &self,
        user_key: SymmetricCryptoKey,
        account_crypto_state: WrappedAccountCryptographicState,
        upgrade_token: &Option<V2UpgradeToken>,
    ) -> Result<(), EncryptionSettingsError> {
        let mut ctx = self.key_store.context_mut();

        // Add the decrypted key to KeyStore first
        let user_key_id = ctx.add_local_symmetric_key(user_key.clone());

        // Upgrade V1 key to V2 if token is present
        let user_key_id = match (&user_key, upgrade_token) {
            (SymmetricCryptoKey::Aes256CbcHmacKey(_), Some(token)) => {
                info!("V1 user key detected with upgrade token, extracting V2 key");
                token
                    .unwrap_v2(user_key_id, &mut ctx)
                    .map_err(|_| EncryptionSettingsError::InvalidUpgradeToken)?
            }
            (SymmetricCryptoKey::XChaCha20Poly1305Key(_), Some(_)) => {
                debug!("V2 user key already present, ignoring upgrade token");
                user_key_id
            }
            _ => user_key_id,
        };

        // Note: The actual key does not get logged unless the crypto crate has the
        // dangerous-crypto-debug feature enabled, so this is safe
        info!("Setting user key with ID {:?}", user_key_id);
        // The user key gets set to the local context frame here; It then gets persisted to the
        // context when the cryptographic state was unwrapped correctly, so that there is no
        // risk of a partial / incorrect setup.
        account_crypto_state
            .set_to_context(&self.security_state, user_key_id, &self.key_store, ctx)
            .map_err(|_| EncryptionSettingsError::CryptoInitialization)
    }

    #[cfg(feature = "internal")]
    #[instrument(err, skip_all)]
    pub(crate) fn initialize_user_crypto_pin(
        &self,
        pin_key: PinKey,
        pin_protected_user_key: EncString,
        account_crypto_state: WrappedAccountCryptographicState,
        upgrade_token: &Option<V2UpgradeToken>,
    ) -> Result<(), EncryptionSettingsError> {
        let decrypted_user_key = pin_key.decrypt_user_key(pin_protected_user_key)?;
        self.initialize_user_crypto_decrypted_key(
            decrypted_user_key,
            account_crypto_state,
            upgrade_token,
        )
    }

    #[cfg(feature = "internal")]
    #[instrument(err, skip_all)]
    pub(crate) fn initialize_user_crypto_pin_envelope(
        &self,
        pin: String,
        pin_protected_user_key_envelope: PasswordProtectedKeyEnvelope,
        account_crypto_state: WrappedAccountCryptographicState,
        upgrade_token: &Option<V2UpgradeToken>,
    ) -> Result<(), EncryptionSettingsError> {
        // Note: This block ensures the ctx that is created in the block is dropped. Otherwise it
        // would cause a deadlock when initializing the user crypto
        let decrypted_user_key = {
            use bitwarden_crypto::safe::PasswordProtectedKeyEnvelopeNamespace;
            let ctx = &mut self.key_store.context_mut();
            let decrypted_user_key_id = pin_protected_user_key_envelope
                .unseal(&pin, PasswordProtectedKeyEnvelopeNamespace::PinUnlock, ctx)
                .map_err(|_| EncryptionSettingsError::WrongPin)?;

            // Allowing deprecated here, until a refactor to pass the Local key ids to
            // `initialized_user_crypto_decrypted_key`
            #[allow(deprecated)]
            ctx.dangerous_get_symmetric_key(decrypted_user_key_id)?
                .clone()
        };
        self.initialize_user_crypto_decrypted_key(
            decrypted_user_key,
            account_crypto_state,
            upgrade_token,
        )
    }

    #[cfg(feature = "secrets")]
    pub(crate) fn initialize_crypto_single_org_key(
        &self,
        organization_id: OrganizationId,
        key: SymmetricCryptoKey,
    ) {
        EncryptionSettings::new_single_org_key(organization_id, key, &self.key_store);
    }

    #[allow(missing_docs)]
    #[cfg(feature = "internal")]
    pub fn initialize_org_crypto(
        &self,
        org_keys: Vec<(OrganizationId, UnsignedSharedKey)>,
    ) -> Result<(), EncryptionSettingsError> {
        EncryptionSettings::set_org_keys(org_keys, &self.key_store)
    }

    #[cfg(feature = "internal")]
    #[instrument(err, skip_all)]
    pub(crate) fn initialize_user_crypto_master_password_unlock(
        &self,
        password: String,
        master_password_unlock: MasterPasswordUnlockData,
        account_crypto_state: WrappedAccountCryptographicState,
        upgrade_token: &Option<V2UpgradeToken>,
    ) -> Result<(), EncryptionSettingsError> {
        let master_key = MasterKey::derive(
            &password,
            &master_password_unlock.salt,
            &master_password_unlock.kdf,
        )?;
        let user_key =
            master_key.decrypt_user_key(master_password_unlock.master_key_wrapped_user_key)?;
        self.initialize_user_crypto_decrypted_key(user_key, account_crypto_state, upgrade_token)
    }

    /// Sets the local KDF state for the master password unlock login method.
    /// Salt and user key update is not supported yet.
    #[cfg(feature = "internal")]
    pub async fn set_user_master_password_unlock(
        &self,
        master_password_unlock: MasterPasswordUnlockData,
    ) -> Result<(), NotAuthenticatedError> {
        let new_kdf = master_password_unlock.kdf;

        let login_method = self.get_login_method().await.ok_or(NotAuthenticatedError)?;

        let kdf = self.get_kdf().await?;

        if kdf != new_kdf {
            match login_method {
                UserLoginMethod::Username {
                    client_id, email, ..
                } => {
                    self.set_login_method(LoginMethod::User(UserLoginMethod::Username {
                        client_id,
                        email,
                        kdf: new_kdf,
                    }))
                    .await
                }
                UserLoginMethod::ApiKey {
                    client_id,
                    client_secret,
                    email,
                    ..
                } => {
                    self.set_login_method(LoginMethod::User(UserLoginMethod::ApiKey {
                        client_id,
                        client_secret,
                        email,
                        kdf: new_kdf,
                    }))
                    .await
                }
            };
        }

        Ok(())
    }
}

#[cfg(test)]
mod tests {
    use std::num::NonZeroU32;

    use bitwarden_crypto::{EncString, Kdf, MasterKey};

    use crate::{
        Client,
        client::{UserLoginMethod, test_accounts::test_bitwarden_com_account},
        key_management::MasterPasswordUnlockData,
    };

    const TEST_ACCOUNT_EMAIL: &str = "[email protected]";
    const TEST_ACCOUNT_USER_KEY: &str = "2.Q/2PhzcC7GdeiMHhWguYAQ==|GpqzVdr0go0ug5cZh1n+uixeBC3oC90CIe0hd/HWA/pTRDZ8ane4fmsEIcuc8eMKUt55Y2q/fbNzsYu41YTZzzsJUSeqVjT8/iTQtgnNdpo=|dwI+uyvZ1h/iZ03VQ+/wrGEFYVewBUUl/syYgjsNMbE=";

    #[test]
    fn initializing_user_multiple_times() {
        use super::*;

        let client = Client::new(None);
        let user_id = UserId::new_v4();

        // Setting the user ID for the first time should work.
        assert!(client.internal.init_user_id(user_id).is_ok());
        assert_eq!(client.internal.get_user_id(), Some(user_id));

        // Trying to set the same user_id again should not return an error.
        assert!(client.internal.init_user_id(user_id).is_ok());

        // Trying to set a different user_id should return an error.
        let different_user_id = UserId::new_v4();
        assert!(client.internal.init_user_id(different_user_id).is_err());
    }

    #[tokio::test]
    async fn test_set_user_master_password_unlock_kdf_updated() {
        let new_kdf = Kdf::Argon2id {
            iterations: NonZeroU32::new(4).unwrap(),
            memory: NonZeroU32::new(65).unwrap(),
            parallelism: NonZeroU32::new(5).unwrap(),
        };

        let user_key: EncString = TEST_ACCOUNT_USER_KEY.parse().expect("Invalid user key");
        let email = TEST_ACCOUNT_EMAIL.to_owned();

        let client = Client::init_test_account(test_bitwarden_com_account()).await;

        client
            .internal
            .set_user_master_password_unlock(MasterPasswordUnlockData {
                kdf: new_kdf.clone(),
                master_key_wrapped_user_key: user_key,
                salt: email,
            })
            .await
            .unwrap();

        let kdf = client.internal.get_kdf().await.unwrap();
        assert_eq!(kdf, new_kdf);
    }

    #[tokio::test]
    async fn test_set_user_master_password_unlock_email_and_keys_not_updated() {
        let password = "asdfasdfasdf".to_string();
        let new_email = format!("{}@example.com", uuid::Uuid::new_v4());
        let kdf = Kdf::default_pbkdf2();
        let expected_email = TEST_ACCOUNT_EMAIL.to_owned();

        let (new_user_key, new_encrypted_user_key) = {
            let master_key = MasterKey::derive(&password, &new_email, &kdf).unwrap();
            master_key.make_user_key().unwrap()
        };

        let client = Client::init_test_account(test_bitwarden_com_account()).await;

        client
            .internal
            .set_user_master_password_unlock(MasterPasswordUnlockData {
                kdf,
                master_key_wrapped_user_key: new_encrypted_user_key,
                salt: new_email,
            })
            .await
            .unwrap();

        let login_method = client.internal.get_login_method().await.unwrap();
        match login_method {
            UserLoginMethod::Username { email, .. } => {
                assert_eq!(*email, expected_email);
            }
            _ => panic!("Expected username login method"),
        }

        let user_key = client.crypto().get_user_encryption_key().await.unwrap();

        assert_ne!(user_key, new_user_key.0.to_base64());
    }
}