Skip to main content

bitwarden_core/client/
rehydration.rs

1use std::sync::Arc;
2
3use bitwarden_state::registry::StateRegistry;
4
5use super::Client;
6use crate::{
7    UserId,
8    auth::auth_tokens::TokenHandler,
9    client::{
10        ClientBuilder, get_host_platform_info,
11        persisted_state::{ACCOUNT_CRYPTO_STATE, BASE_URLS, BaseUrls, USER_EMAIL, USER_ID},
12    },
13    key_management::account_cryptographic_state::WrappedAccountCryptographicState,
14};
15
16/// Errors that can occur during client rehydration.
17#[derive(Debug, thiserror::Error)]
18pub enum RehydrationError {
19    /// A persisted value was missing, or reading or writing it failed.
20    #[error("State access error: {0}")]
21    State(#[from] bitwarden_state::PersistedValueError),
22}
23
24/// Data required to populate a [`StateRegistry`] via [`Client::save_to_state`].
25///
26/// Contains the values the auth flow does not yet persist automatically. Once the auth crate
27/// handles persistence directly, this type will be removed.
28pub struct SaveStateData {
29    /// The authenticated user's ID.
30    pub user_id: UserId,
31    /// The authenticated user's email.
32    pub email: String,
33    /// The base API URLs for the user's server.
34    pub urls: BaseUrls,
35    /// The user's wrapped account cryptographic state.
36    pub crypto_state: WrappedAccountCryptographicState,
37}
38
39impl Client {
40    /// Populates a [`StateRegistry`] with the state required for [`Client::load_from_state`].
41    ///
42    /// Call this after a successful login to persist the values that the auth flow does not yet
43    /// write automatically. Once the auth crate handles persistence directly, this will be removed.
44    pub async fn save_to_state(
45        data: SaveStateData,
46        reg: &StateRegistry,
47    ) -> Result<(), RehydrationError> {
48        reg.value::<BASE_URLS>().set(data.urls).await?;
49        reg.value::<USER_ID>().set(data.user_id).await?;
50        reg.value::<USER_EMAIL>().set(data.email).await?;
51        reg.value::<ACCOUNT_CRYPTO_STATE>()
52            .set(data.crypto_state)
53            .await?;
54        Ok(())
55    }
56
57    /// Reconstruct a locked Client from a populated StateRegistry.
58    ///
59    /// Does NOT unlock the vault.
60    pub async fn load_from_state(
61        token_handler: Arc<dyn TokenHandler>,
62        registry: StateRegistry,
63    ) -> Result<Self, RehydrationError> {
64        let base_urls: BaseUrls = registry.value::<BASE_URLS>().get().await?;
65
66        let user_id: UserId = registry.value::<USER_ID>().get().await?;
67
68        let settings =
69            get_host_platform_info().to_client_settings(base_urls.api_url, base_urls.identity_url);
70
71        let client = ClientBuilder::new()
72            .with_settings(settings)
73            .with_token_handler(token_handler)
74            .with_state(registry)
75            .build();
76
77        client
78            .internal
79            .init_user_id(user_id)
80            .await
81            .expect("user ID cannot already be set on a freshly built client");
82
83        // Refresh feature flags from /config if the cached set is missing or stale (TTL 1h).
84        // Failure is non-fatal — an offline client continues with the previously persisted flags.
85        if let Err(e) = client.flags().fetch(false).await {
86            tracing::warn!(
87                "Failed to refresh feature flags on startup; using previously stored flags: {e}"
88            );
89        }
90
91        Ok(client)
92    }
93}
94
95#[cfg(test)]
96mod tests {
97    use std::sync::{Arc, Once};
98
99    use bitwarden_crypto::{
100        KeyStore, PublicKeyEncryptionAlgorithm, SignatureAlgorithm, SymmetricKeyAlgorithm,
101    };
102    use bitwarden_state::{PersistedValueError, registry::StateRegistry};
103
104    use super::*;
105    use crate::{
106        DeviceType, HostPlatformInfo, UserId,
107        auth::auth_tokens::NoopTokenHandler,
108        client::persisted_state::{ACCOUNT_CRYPTO_STATE, BASE_URLS, BaseUrls, USER_EMAIL, USER_ID},
109        key_management::{
110            KeySlotIds, SecurityState,
111            account_cryptographic_state::WrappedAccountCryptographicState,
112        },
113    };
114
115    static INIT: Once = Once::new();
116
117    fn ensure_platform_info() {
118        INIT.call_once(|| {
119            crate::init_host_platform_info(HostPlatformInfo {
120                user_agent: "rehydration-tests".to_string(),
121                device_type: DeviceType::SDK,
122                device_identifier: None,
123                bitwarden_client_version: None,
124                bitwarden_package_type: None,
125            });
126        });
127    }
128
129    fn test_user_id() -> UserId {
130        "d5b1fde2-a1e3-4c5b-9e0f-1a2b3c4d5e6f".parse().unwrap()
131    }
132
133    fn test_base_urls() -> BaseUrls {
134        // Use an invalid port so flag loading fails fast
135        BaseUrls {
136            identity_url: "http://127.0.0.1:1".to_string(),
137            api_url: "http://127.0.0.1:1".to_string(),
138        }
139    }
140
141    fn test_crypto_state() -> WrappedAccountCryptographicState {
142        let store: KeyStore<KeySlotIds> = KeyStore::default();
143        let mut ctx = store.context_mut();
144        let user_key = ctx.make_symmetric_key(SymmetricKeyAlgorithm::XAes256Gcm);
145        let private_key_id = ctx.make_private_key(PublicKeyEncryptionAlgorithm::RsaOaepSha1);
146        let signing_key_id = ctx.make_signing_key(SignatureAlgorithm::Ed25519);
147        let signed_public_key = ctx
148            .make_signed_public_key(private_key_id, signing_key_id)
149            .unwrap();
150        let security_state = SecurityState::new();
151        let signed_security_state = security_state.sign(signing_key_id, &mut ctx).unwrap();
152        let wrapped_private = ctx.wrap_private_key(user_key, private_key_id).unwrap();
153        let wrapped_signing = ctx.wrap_signing_key(user_key, signing_key_id).unwrap();
154        WrappedAccountCryptographicState::V2 {
155            private_key: wrapped_private,
156            signed_public_key,
157            signing_key: wrapped_signing,
158            security_state: signed_security_state,
159        }
160    }
161
162    fn test_email() -> String {
163        "[email protected]".to_string()
164    }
165
166    fn test_save_data() -> SaveStateData {
167        SaveStateData {
168            user_id: test_user_id(),
169            email: test_email(),
170            urls: test_base_urls(),
171            crypto_state: test_crypto_state(),
172        }
173    }
174
175    #[tokio::test]
176    async fn save_to_state_writes_all_values() {
177        let reg = StateRegistry::new_with_memory_db();
178        let data = test_save_data();
179        let expected_user_id = data.user_id;
180        let expected_email = data.email.clone();
181        let expected_urls_identity = data.urls.identity_url.clone();
182        let expected_urls_api = data.urls.api_url.clone();
183
184        Client::save_to_state(data, &reg).await.unwrap();
185
186        // Read back each value directly from the registry.
187        let base_urls: BaseUrls = reg.value::<BASE_URLS>().get().await.unwrap();
188        assert_eq!(base_urls.identity_url, expected_urls_identity);
189        assert_eq!(base_urls.api_url, expected_urls_api);
190
191        let user_id: UserId = reg.value::<USER_ID>().get().await.unwrap();
192        assert_eq!(user_id, expected_user_id);
193
194        let email: String = reg.value::<USER_EMAIL>().get().await.unwrap();
195        assert_eq!(email, expected_email);
196
197        let crypto_state: WrappedAccountCryptographicState =
198            reg.value::<ACCOUNT_CRYPTO_STATE>().get().await.unwrap();
199        assert!(
200            matches!(crypto_state, WrappedAccountCryptographicState::V2 { .. }),
201            "Expected V2 crypto state"
202        );
203    }
204
205    #[tokio::test]
206    async fn load_from_state_restores_user_id() {
207        ensure_platform_info();
208
209        let reg = StateRegistry::new_with_memory_db();
210        let data = test_save_data();
211        let expected_user_id = data.user_id;
212
213        Client::save_to_state(data, &reg).await.unwrap();
214
215        let token_handler: Arc<dyn TokenHandler> = Arc::new(NoopTokenHandler);
216        let client = Client::load_from_state(token_handler, reg).await.unwrap();
217
218        assert_eq!(
219            client.internal.get_user_id(),
220            Some(expected_user_id),
221            "Restored client should have the saved user ID"
222        );
223    }
224
225    #[tokio::test]
226    async fn load_from_state_missing_base_urls_returns_error() {
227        ensure_platform_info();
228
229        let reg = StateRegistry::new_with_memory_db();
230        // Registry is empty no values written.
231
232        let token_handler: Arc<dyn TokenHandler> = Arc::new(NoopTokenHandler);
233        let result = Client::load_from_state(token_handler, reg).await;
234
235        assert!(matches!(
236            result,
237            Err(RehydrationError::State(PersistedValueError::ValueNotFound(
238                "base_urls"
239            )))
240        ));
241    }
242
243    #[tokio::test]
244    async fn load_from_state_missing_user_id_returns_error() {
245        ensure_platform_info();
246
247        let reg = StateRegistry::new_with_memory_db();
248        // Write only BASE_URLS, omit USER_ID.
249        reg.value::<BASE_URLS>()
250            .set(test_base_urls())
251            .await
252            .unwrap();
253
254        let token_handler: Arc<dyn TokenHandler> = Arc::new(NoopTokenHandler);
255        let result = Client::load_from_state(token_handler, reg).await;
256
257        assert!(matches!(
258            result,
259            Err(RehydrationError::State(PersistedValueError::ValueNotFound(
260                "user_id"
261            )))
262        ));
263    }
264}