Skip to main content

bitwarden_user_crypto_management/key_rotation/
rotate_user_keys.rs

1//! Client implementation for rotating user keys without a password change.
2use bitwarden_api_api::models::RotateUserKeysRequestModel;
3#[cfg(any(feature = "uniffi", feature = "wasm"))]
4use bitwarden_core::key_management::crypto::ReinitUserCryptoRequest;
5use bitwarden_core::key_management::{
6    KeySlotIds, V2UpgradeToken, account_cryptographic_state::WrappedAccountCryptographicState,
7};
8use bitwarden_crypto::{KeyConnectorKey, KeyStore, PublicKey, SymmetricCryptoKey};
9use serde::{Deserialize, Serialize};
10use tracing::info;
11#[cfg(any(feature = "uniffi", feature = "wasm"))]
12use tracing::warn;
13
14use crate::{
15    UserCryptoManagementClient,
16    key_rotation::{
17        RotateUserKeysError,
18        crypto::{
19            account_cryptographic_state_to_wrapped_model, rotate_account_cryptographic_state,
20        },
21        data::{check_for_old_attachments, reencrypt_data},
22        rotation_context::make_rotation_context,
23        sync::{SyncedAccountData, sync_current_account_data},
24        unlock::{ReencryptCommonUnlockDataInput, reencrypt_common_unlock_data},
25        unlock_method::{PrimaryUnlockMethod, reencrypt_unlock_method_data},
26    },
27};
28
29#[derive(Serialize, Deserialize, Clone)]
30#[bitwarden_ffi::wasm_record]
31#[cfg_attr(feature = "uniffi", derive(uniffi::Enum))]
32pub enum KeyRotationMethod {
33    /// Master password user, key rotation without a password change.
34    Password { password: String },
35    /// Key Connector user, key rotation without a password change.
36    KeyConnector { key_connector_url: String },
37    /// TDE user, key rotation without a password change.
38    Tde,
39}
40
41#[derive(Serialize, Deserialize, Clone, PartialEq)]
42#[bitwarden_ffi::wasm_record]
43#[cfg_attr(feature = "uniffi", derive(uniffi::Enum))]
44pub enum UpgradeTokenAction {
45    /// Skip creating and sending an upgrade token to the server.
46    Skip,
47    /// Creates an upgrade token for V1 -> V2 key rotations.
48    /// For V2 -> V2 rotations, no upgrade token is needed.
49    CreateIfNeeded,
50}
51
52#[derive(Serialize, Deserialize, Clone)]
53#[bitwarden_ffi::wasm_record]
54#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
55pub struct RotateUserKeysRequest {
56    pub key_rotation_method: KeyRotationMethod,
57    pub trusted_emergency_access_public_keys: Vec<PublicKey>,
58    /// Organization public keys the user confirmed as trusted. Only needed when the rotation
59    /// shares the new user key for account recovery.
60    pub trusted_organization_public_keys: Vec<PublicKey>,
61    pub upgrade_token_action: UpgradeTokenAction,
62}
63
64#[bitwarden_ffi::wasm_export]
65impl UserCryptoManagementClient {
66    /// Rotates the user's encryption keys without a password change.
67    pub async fn rotate_user_keys(
68        &self,
69        request: RotateUserKeysRequest,
70    ) -> Result<(), RotateUserKeysError> {
71        let api_client = &self.client.internal.get_api_configurations().api_client;
72        let key_store = self.client.internal.get_key_store();
73
74        let sync = sync_current_account_data(api_client)
75            .await
76            .map_err(|_| RotateUserKeysError::Api)?;
77
78        let wrapped_account_cryptographic_state = self
79            .regenerate_public_key_encryption_key_pair_if_needed_with_ciphers(&sync.ciphers)
80            .await
81            .map_err(|_| RotateUserKeysError::Crypto)?
82            .unwrap_or_else(|| sync.wrapped_account_cryptographic_state.clone());
83
84        let key_connector_api_client =
85            if let KeyRotationMethod::KeyConnector { key_connector_url } =
86                &request.key_rotation_method
87            {
88                Some(
89                    self.client
90                        .internal
91                        .get_key_connector_client(key_connector_url.clone()),
92                )
93            } else {
94                None
95            };
96
97        let upgrade = internal_rotate_user_keys(
98            key_store,
99            api_client,
100            &self.client.km_state_bridge(),
101            key_connector_api_client.as_ref(),
102            request,
103            wrapped_account_cryptographic_state,
104            sync,
105        )
106        .await?;
107
108        if let Some(upgrade) = upgrade {
109            self.apply_v2_upgrade(upgrade).await;
110        }
111
112        Ok(())
113    }
114}
115
116impl UserCryptoManagementClient {
117    /// Moves this unlocked client from the V1 user key to the V2 key it just rotated to. Without
118    /// this the SDK keeps the V1 key in memory until the next sync, while state already holds V2.
119    #[cfg(any(feature = "uniffi", feature = "wasm"))]
120    async fn apply_v2_upgrade(&self, upgrade: V2Upgrade) {
121        let result = self
122            .client
123            .crypto()
124            .reinit_user_crypto(ReinitUserCryptoRequest {
125                account_cryptographic_state: upgrade.account_cryptographic_state,
126                upgrade_token: upgrade.upgrade_token,
127            })
128            .await;
129
130        // The server already rotated, so failing the call would make the client retry a
131        // rotation that cannot be repeated. The next sync re-initializes the client.
132        if let Err(e) = result {
133            warn!(error = ?e, "Failed to apply the V2 upgrade to the rotating client");
134        }
135    }
136
137    #[cfg(not(any(feature = "uniffi", feature = "wasm")))]
138    async fn apply_v2_upgrade(&self, _upgrade: V2Upgrade) {}
139}
140
141/// What a V1 to V2 rotation hands the rotating client to re-initialize itself from.
142#[cfg_attr(not(any(feature = "uniffi", feature = "wasm")), allow(dead_code))]
143struct V2Upgrade {
144    account_cryptographic_state: WrappedAccountCryptographicState,
145    upgrade_token: V2UpgradeToken,
146}
147
148/// Data that needs to be written to local state after the key rotation
149/// was successfully posted to the server
150struct StateUpdate {
151    user_key: SymmetricCryptoKey,
152    account_cryptographic_state: WrappedAccountCryptographicState,
153    upgrade_token: Option<V2UpgradeToken>,
154}
155
156#[bitwarden_logging::instrument(name = "rotate_user_keys", level = "info", err)]
157async fn internal_rotate_user_keys(
158    key_store: &KeyStore<KeySlotIds>,
159    api_client: &bitwarden_api_api::apis::ApiClient,
160    state_bridge: &bitwarden_core::key_management::state_bridge::StateBridgeClient,
161    key_connector_api_client: Option<&bitwarden_api_key_connector::apis::ApiClient>,
162    request: RotateUserKeysRequest,
163    wrapped_account_cryptographic_state: WrappedAccountCryptographicState,
164    sync: SyncedAccountData,
165) -> Result<Option<V2Upgrade>, RotateUserKeysError> {
166    // Fail early if any cipher has old attachments that would become irrecoverable
167    check_for_old_attachments(&sync.ciphers)?;
168
169    // For Key Connector users, fetch the existing KC key from the KC server.
170    // This must happen before the synchronous key store scope below.
171    let key_connector_key = if matches!(
172        request.key_rotation_method,
173        KeyRotationMethod::KeyConnector { .. }
174    ) {
175        let key_connector_client =
176            key_connector_api_client.ok_or(RotateUserKeysError::KeyConnectorApi)?;
177        info!("Fetching Key Connector key for key rotation");
178        let response = key_connector_client
179            .user_keys_api()
180            .get_user_key()
181            .await
182            .map_err(|_| RotateUserKeysError::KeyConnectorApi)?;
183        let key_connector_key =
184            KeyConnectorKey::try_from(response).map_err(|_| RotateUserKeysError::Crypto)?;
185        Some(key_connector_key)
186    } else {
187        None
188    };
189
190    // Create a separate scope so that the mutable context is not held across the await point
191    let (post_request, state_bridge_update) = {
192        let mut ctx = key_store.context_mut();
193
194        let rotation_context = make_rotation_context(
195            &sync,
196            request.trusted_organization_public_keys.as_slice(),
197            request.trusted_emergency_access_public_keys.as_slice(),
198            request.upgrade_token_action.clone(),
199            &mut ctx,
200        )?;
201
202        info!("Rotating account cryptographic state for user key rotation");
203        let wrapped_account_cryptographic_state = rotate_account_cryptographic_state(
204            &wrapped_account_cryptographic_state,
205            &rotation_context.current_user_key_id,
206            &rotation_context.new_user_key_id,
207            &mut ctx,
208        )
209        .map_err(|_| RotateUserKeysError::Crypto)?;
210        let wrapped_account_cryptographic_state_request_model =
211            account_cryptographic_state_to_wrapped_model(
212                &wrapped_account_cryptographic_state,
213                &rotation_context.new_user_key_id,
214                &mut ctx,
215            )
216            .map_err(|_| RotateUserKeysError::Crypto)?;
217
218        info!("Re-encrypting account data for user key rotation");
219        let account_data_model = reencrypt_data(
220            sync.folders.as_slice(),
221            sync.ciphers.as_slice(),
222            sync.sends.as_slice(),
223            rotation_context.current_user_key_id,
224            rotation_context.new_user_key_id,
225            &mut ctx,
226        )
227        .map_err(|_| RotateUserKeysError::Crypto)?;
228
229        info!("Re-encrypting account primary unlock method for user key rotation");
230        let unlock_method_input = PrimaryUnlockMethod::from_key_rotation_method(
231            request.key_rotation_method,
232            &sync,
233            key_connector_key,
234        )?;
235        let unlock_method_data = reencrypt_unlock_method_data(
236            unlock_method_input,
237            rotation_context.new_user_key_id,
238            &mut ctx,
239        )
240        .map_err(|_| RotateUserKeysError::Crypto)?;
241
242        info!("Re-encrypting account common unlock data for user key rotation");
243        let common_unlock_data = reencrypt_common_unlock_data(
244            ReencryptCommonUnlockDataInput {
245                trusted_organization_keys: rotation_context.v1_organization_memberships,
246                trusted_emergency_access_keys: rotation_context.v1_emergency_access_memberships,
247                webauthn_credentials: sync.passkeys,
248                trusted_devices: sync.trusted_devices,
249            },
250            rotation_context.current_user_key_id,
251            rotation_context.new_user_key_id,
252            rotation_context.creates_v2_upgrade_token,
253            &mut ctx,
254        )
255        .map_err(|_| RotateUserKeysError::Crypto)?;
256
257        (
258            RotateUserKeysRequestModel {
259                wrapped_account_cryptographic_state: Box::new(
260                    wrapped_account_cryptographic_state_request_model,
261                ),
262                account_data: Box::new(account_data_model),
263                unlock_data: Box::new(common_unlock_data.clone()),
264                unlock_method_data: Box::new(unlock_method_data),
265                // Only V2 (COSE-encoded) user keys carry a key id; V1 keys omit the fields. The
266                // server rejects the rotation if `old_user_key_id` is not the user's current key
267                // id.
268                old_user_key_id: ctx
269                    .get_symmetric_key_id(rotation_context.current_user_key_id)
270                    .map(|id| id.to_string()),
271                new_user_key_id: ctx
272                    .get_symmetric_key_id(rotation_context.new_user_key_id)
273                    .map(|id| id.to_string()),
274            },
275            StateUpdate {
276                #[allow(deprecated)]
277                user_key: ctx
278                    .dangerous_get_symmetric_key(rotation_context.new_user_key_id)
279                    .map_err(|_| RotateUserKeysError::Crypto)?
280                    .to_owned(),
281                account_cryptographic_state: wrapped_account_cryptographic_state,
282                upgrade_token: common_unlock_data
283                    .v2_upgrade_token
284                    .clone()
285                    .map(|t| (*t).try_into())
286                    .transpose()
287                    .map_err(|_| RotateUserKeysError::Crypto)?,
288            },
289        )
290    };
291
292    info!("Posting rotated user account keys and data to server");
293    api_client
294        .accounts_key_management_api()
295        .rotate_user_keys(Some(post_request))
296        .await
297        .map_err(|_| RotateUserKeysError::Api)?;
298    info!("Successfully rotated user account keys and data");
299
300    let Some(upgrade_token) = state_bridge_update.upgrade_token else {
301        return Ok(None);
302    };
303
304    info!("Writing new cryptographic data to state");
305    state_bridge
306        .set_account_cryptographic_state(&state_bridge_update.account_cryptographic_state)
307        .await;
308    state_bridge.set_v2_upgrade_token(&upgrade_token).await;
309    state_bridge
310        .set_user_key(&state_bridge_update.user_key)
311        .await;
312    // Important: A full sync MUST be triggered after the key rotation to make sure all unlock
313    // methods are accurate
314
315    Ok(Some(V2Upgrade {
316        account_cryptographic_state: state_bridge_update.account_cryptographic_state,
317        upgrade_token,
318    }))
319}
320
321#[cfg(test)]
322mod tests {
323    use std::str::FromStr;
324
325    use bitwarden_api_api::{apis::ApiClient, models::UnlockMethod};
326    use bitwarden_core::{
327        Client,
328        key_management::{
329            KeySlotIds, PrivateKeySlotId, SymmetricKeySlotId,
330            account_cryptographic_state::WrappedAccountCryptographicState,
331            state_bridge::{StateBridgeClient, test_support::InMemoryStateBridge},
332        },
333    };
334    use bitwarden_crypto::{
335        Decryptable, EncString, Kdf, KeyStore, PublicKeyEncryptionAlgorithm, SymmetricKeyAlgorithm,
336        UnsignedSharedKey,
337    };
338    use bitwarden_vault::{Attachment, Cipher, CipherType};
339    use chrono::DateTime;
340
341    use super::*;
342    use crate::key_rotation::{
343        partial_rotateable_keyset::PartialRotateableKeyset, unlock::V1OrganizationMembership,
344    };
345
346    fn make_state_bridge() -> StateBridgeClient {
347        let client = Client::new(None);
348        let bridge = client.km_state_bridge();
349        bridge.register_bridge(Box::new(InMemoryStateBridge::default()));
350        bridge
351    }
352
353    fn make_test_key_store_and_synced_data() -> (KeyStore<KeySlotIds>, SyncedAccountData) {
354        let store: KeyStore<KeySlotIds> = KeyStore::default();
355        let wrapped_private_key = {
356            let mut ctx = store.context_mut();
357            let user_key = ctx.make_symmetric_key(SymmetricKeyAlgorithm::Aes256CbcHmac);
358            let _ = ctx.persist_symmetric_key(user_key, SymmetricKeySlotId::User);
359            let private_key = ctx.make_private_key(PublicKeyEncryptionAlgorithm::RsaOaepSha1);
360            ctx.wrap_private_key(SymmetricKeySlotId::User, private_key)
361                .unwrap()
362        };
363
364        let sync = SyncedAccountData {
365            wrapped_account_cryptographic_state: WrappedAccountCryptographicState::V1 {
366                private_key: wrapped_private_key,
367            },
368            folders: vec![],
369            ciphers: vec![],
370            sends: vec![],
371            emergency_access_memberships: vec![],
372            organization_memberships: vec![],
373            trusted_devices: vec![],
374            passkeys: vec![],
375            kdf_and_salt: Some((
376                Kdf::PBKDF2 {
377                    iterations: std::num::NonZeroU32::new(600000).unwrap(),
378                },
379                "test_salt".to_string(),
380            )),
381        };
382
383        (store, sync)
384    }
385
386    /// Builds a V1 account that is enrolled in account recovery for a single organization.
387    fn make_test_key_store_and_synced_data_with_organization()
388    -> (KeyStore<KeySlotIds>, SyncedAccountData) {
389        let (store, mut sync) = make_test_key_store_and_synced_data();
390        {
391            let mut ctx = store.context_mut();
392            let organization_private_key =
393                ctx.make_private_key(PublicKeyEncryptionAlgorithm::RsaOaepSha1);
394            sync.organization_memberships = vec![V1OrganizationMembership {
395                organization_id: uuid::Uuid::new_v4(),
396                name: "Test Org".to_string(),
397                public_key: ctx
398                    .get_public_key(organization_private_key)
399                    .expect("public key should exist"),
400            }];
401        }
402
403        (store, sync)
404    }
405
406    fn make_test_key_store_and_synced_data_with_trusted_devices()
407    -> (KeyStore<KeySlotIds>, SyncedAccountData, Vec<u8>) {
408        let store: KeyStore<KeySlotIds> = KeyStore::default();
409        let (trusted_device_keyset, wrapped_private_key, public_key) = {
410            let mut ctx = store.context_mut();
411            let user_key = ctx.make_symmetric_key(SymmetricKeyAlgorithm::Aes256CbcHmac);
412            let _ = ctx.persist_symmetric_key(user_key, SymmetricKeySlotId::User);
413            let (trusted_device_keyset, device_private_key) =
414                PartialRotateableKeyset::make_test_keyset(SymmetricKeySlotId::User, &mut ctx);
415            let _ = ctx.persist_private_key(device_private_key, PrivateKeySlotId::UserPrivateKey);
416            let wrapped_private_key = ctx
417                .wrap_private_key(SymmetricKeySlotId::User, PrivateKeySlotId::UserPrivateKey)
418                .unwrap();
419            (
420                trusted_device_keyset,
421                wrapped_private_key,
422                ctx.get_public_key(PrivateKeySlotId::UserPrivateKey)
423                    .expect("Retrieving the public key should work."),
424            )
425        };
426
427        let sync = SyncedAccountData {
428            wrapped_account_cryptographic_state: WrappedAccountCryptographicState::V1 {
429                private_key: wrapped_private_key,
430            },
431            folders: vec![],
432            ciphers: vec![],
433            sends: vec![],
434            emergency_access_memberships: vec![],
435            organization_memberships: vec![],
436            trusted_devices: vec![trusted_device_keyset],
437            passkeys: vec![],
438            kdf_and_salt: Some((
439                Kdf::PBKDF2 {
440                    iterations: std::num::NonZeroU32::new(600000).unwrap(),
441                },
442                "test_salt".to_string(),
443            )),
444        };
445
446        (
447            store,
448            sync,
449            public_key
450                .to_der()
451                .expect("Generating DER serialization should work")
452                .to_vec(),
453        )
454    }
455
456    #[tokio::test]
457    async fn test_rotate_user_keys_tde_success_rotates_common_unlock_data() {
458        let (key_store, sync, public_key_der) =
459            make_test_key_store_and_synced_data_with_trusted_devices();
460        let key_store_clone = key_store.clone();
461
462        let api_client = ApiClient::new_mocked(|mock| {
463            mock.accounts_key_management_api
464                .expect_rotate_user_keys()
465                .once()
466                .returning(move |req| {
467                    let req = req.expect("request body should be present");
468                    assert_eq!(req.unlock_method_data.unlock_method, UnlockMethod::Tde);
469                    assert!(req.unlock_method_data.master_password_unlock_data.is_none());
470                    assert!(
471                        req.unlock_method_data
472                            .key_connector_key_wrapped_user_key
473                            .is_none()
474                    );
475
476                    let device_unlock_data = req
477                        .unlock_data
478                        .device_key_unlock_data
479                        .expect("device unlock data should be present");
480                    assert_eq!(device_unlock_data.len(), 1);
481                    let rotated_device = &device_unlock_data[0];
482
483                    let encrypted_user_key: UnsignedSharedKey = rotated_device
484                        .encrypted_user_key
485                        .parse()
486                        .expect("encrypted user key should parse");
487                    let encrypted_public_key: EncString = rotated_device
488                        .encrypted_public_key
489                        .parse()
490                        .expect("encrypted public key should parse");
491                    let mut ctx = key_store_clone.context_mut();
492                    let rotated_user_key_id = encrypted_user_key
493                        .decapsulate(PrivateKeySlotId::UserPrivateKey, &mut ctx)
494                        .expect("rotated device user key should decapsulate");
495                    let decrypted_public_key: Vec<u8> = encrypted_public_key
496                        .decrypt(&mut ctx, rotated_user_key_id)
497                        .expect("rotated device public key should decrypt");
498                    assert_eq!(decrypted_public_key, public_key_der);
499                    Ok(())
500                });
501        });
502
503        let state_bridge = make_state_bridge();
504        let result = internal_rotate_user_keys(
505            &key_store,
506            &api_client,
507            &state_bridge,
508            None,
509            RotateUserKeysRequest {
510                key_rotation_method: KeyRotationMethod::Tde,
511                trusted_organization_public_keys: vec![],
512                trusted_emergency_access_public_keys: vec![],
513                upgrade_token_action: UpgradeTokenAction::Skip,
514            },
515            sync.wrapped_account_cryptographic_state.clone(),
516            sync,
517        )
518        .await;
519
520        assert!(result.is_ok());
521        if let ApiClient::Mock(mut mock) = api_client {
522            mock.accounts_key_management_api.checkpoint();
523        }
524    }
525
526    #[tokio::test]
527    async fn test_rotate_user_keys_master_password_success() {
528        let (key_store, sync) = make_test_key_store_and_synced_data();
529        let api_client = ApiClient::new_mocked(|mock| {
530            mock.accounts_key_management_api
531                .expect_rotate_user_keys()
532                .once()
533                .returning(|_| Ok(()));
534        });
535
536        let state_bridge = make_state_bridge();
537        let result = internal_rotate_user_keys(
538            &key_store,
539            &api_client,
540            &state_bridge,
541            None,
542            RotateUserKeysRequest {
543                key_rotation_method: KeyRotationMethod::Password {
544                    password: "test_password".to_string(),
545                },
546                trusted_organization_public_keys: vec![],
547                trusted_emergency_access_public_keys: vec![],
548                upgrade_token_action: UpgradeTokenAction::Skip,
549            },
550            sync.wrapped_account_cryptographic_state.clone(),
551            sync,
552        )
553        .await;
554
555        assert!(result.is_ok());
556        if let ApiClient::Mock(mut mock) = api_client {
557            mock.accounts_key_management_api.checkpoint();
558        }
559    }
560
561    #[tokio::test]
562    async fn test_rotate_user_keys_post_api_failure_returns_api_error() {
563        let (key_store, sync) = make_test_key_store_and_synced_data();
564        let api_client = ApiClient::new_mocked(|mock| {
565            mock.accounts_key_management_api
566                .expect_rotate_user_keys()
567                .once()
568                .returning(|_| {
569                    Err(serde_json::Error::io(std::io::Error::other("API error")).into())
570                });
571        });
572
573        let state_bridge = make_state_bridge();
574        let result = internal_rotate_user_keys(
575            &key_store,
576            &api_client,
577            &state_bridge,
578            None,
579            RotateUserKeysRequest {
580                key_rotation_method: KeyRotationMethod::Password {
581                    password: "test_password".to_string(),
582                },
583                trusted_organization_public_keys: vec![],
584                trusted_emergency_access_public_keys: vec![],
585                upgrade_token_action: UpgradeTokenAction::Skip,
586            },
587            sync.wrapped_account_cryptographic_state.clone(),
588            sync,
589        )
590        .await;
591
592        assert!(matches!(result, Err(RotateUserKeysError::Api)));
593        if let ApiClient::Mock(mut mock) = api_client {
594            mock.accounts_key_management_api.checkpoint();
595        }
596    }
597
598    #[tokio::test]
599    async fn test_rotate_user_keys_upgrade_token_action_skip_omits_token() {
600        let (key_store, sync) = make_test_key_store_and_synced_data();
601        let api_client = ApiClient::new_mocked(|mock| {
602            mock.accounts_key_management_api
603                .expect_rotate_user_keys()
604                .once()
605                .returning(|req| {
606                    let req = req.expect("request body should be present");
607                    assert!(
608                        req.unlock_data.v2_upgrade_token.is_none(),
609                        "upgrade_token_action Skip, should omit the v2_upgrade_token"
610                    );
611                    Ok(())
612                });
613        });
614
615        let state_bridge = make_state_bridge();
616        let result = internal_rotate_user_keys(
617            &key_store,
618            &api_client,
619            &state_bridge,
620            None,
621            RotateUserKeysRequest {
622                key_rotation_method: KeyRotationMethod::Password {
623                    password: "test_password".to_string(),
624                },
625                trusted_organization_public_keys: vec![],
626                trusted_emergency_access_public_keys: vec![],
627                upgrade_token_action: UpgradeTokenAction::Skip,
628            },
629            sync.wrapped_account_cryptographic_state.clone(),
630            sync,
631        )
632        .await;
633
634        assert!(result.is_ok());
635        if let ApiClient::Mock(mut mock) = api_client {
636            mock.accounts_key_management_api.checkpoint();
637        }
638    }
639
640    #[tokio::test]
641    async fn test_rotate_user_keys_upgrade_token_action_create_if_needed_includes_token() {
642        let (key_store, sync) = make_test_key_store_and_synced_data();
643        let api_client = ApiClient::new_mocked(|mock| {
644            mock.accounts_key_management_api
645                .expect_rotate_user_keys()
646                .once()
647                .returning(|req| {
648                    let req = req.expect("request body should be present");
649                    assert!(
650                        req.unlock_data.v2_upgrade_token.is_some(),
651                        "upgrade_token_action CreateIfNeeded, should include a v2_upgrade_token for V1 -> V2 rotations"
652                    );
653                    Ok(())
654                });
655        });
656
657        let state_bridge = make_state_bridge();
658        let result = internal_rotate_user_keys(
659            &key_store,
660            &api_client,
661            &state_bridge,
662            None,
663            RotateUserKeysRequest {
664                key_rotation_method: KeyRotationMethod::Password {
665                    password: "test_password".to_string(),
666                },
667                trusted_organization_public_keys: vec![],
668                trusted_emergency_access_public_keys: vec![],
669                upgrade_token_action: UpgradeTokenAction::CreateIfNeeded,
670            },
671            sync.wrapped_account_cryptographic_state.clone(),
672            sync,
673        )
674        .await;
675
676        assert!(result.is_ok());
677        if let ApiClient::Mock(mut mock) = api_client {
678            mock.accounts_key_management_api.checkpoint();
679        }
680    }
681
682    #[tokio::test]
683    async fn test_rotate_user_keys_writes_state_when_upgrade_token_present() {
684        let (key_store, sync) = make_test_key_store_and_synced_data();
685        let api_client = ApiClient::new_mocked(|mock| {
686            mock.accounts_key_management_api
687                .expect_rotate_user_keys()
688                .once()
689                .returning(|_| Ok(()));
690        });
691
692        let state_bridge = make_state_bridge();
693        assert!(state_bridge.get_v2_upgrade_token().await.is_none());
694        assert!(
695            state_bridge
696                .get_account_cryptographic_state()
697                .await
698                .is_none()
699        );
700        assert!(state_bridge.get_user_key().await.is_none());
701
702        let result = internal_rotate_user_keys(
703            &key_store,
704            &api_client,
705            &state_bridge,
706            None,
707            RotateUserKeysRequest {
708                key_rotation_method: KeyRotationMethod::Password {
709                    password: "test_password".to_string(),
710                },
711                trusted_organization_public_keys: vec![],
712                trusted_emergency_access_public_keys: vec![],
713                upgrade_token_action: UpgradeTokenAction::CreateIfNeeded,
714            },
715            sync.wrapped_account_cryptographic_state.clone(),
716            sync,
717        )
718        .await;
719
720        assert!(result.is_ok());
721        assert!(
722            state_bridge.get_v2_upgrade_token().await.is_some(),
723            "state bridge should hold the v2 upgrade token after V1 -> V2 rotation"
724        );
725        assert!(
726            state_bridge
727                .get_account_cryptographic_state()
728                .await
729                .is_some(),
730            "state bridge should hold the rotated account cryptographic state"
731        );
732        assert!(
733            state_bridge.get_user_key().await.is_some(),
734            "state bridge should hold the rotated user key"
735        );
736        if let ApiClient::Mock(mut mock) = api_client {
737            mock.accounts_key_management_api.checkpoint();
738        }
739    }
740
741    #[tokio::test]
742    async fn test_rotate_user_keys_skips_state_writes_when_no_upgrade_token() {
743        let (key_store, sync) = make_test_key_store_and_synced_data();
744        let api_client = ApiClient::new_mocked(|mock| {
745            mock.accounts_key_management_api
746                .expect_rotate_user_keys()
747                .once()
748                .returning(|_| Ok(()));
749        });
750
751        let state_bridge = make_state_bridge();
752        let result = internal_rotate_user_keys(
753            &key_store,
754            &api_client,
755            &state_bridge,
756            None,
757            RotateUserKeysRequest {
758                key_rotation_method: KeyRotationMethod::Password {
759                    password: "test_password".to_string(),
760                },
761                trusted_organization_public_keys: vec![],
762                trusted_emergency_access_public_keys: vec![],
763                upgrade_token_action: UpgradeTokenAction::Skip,
764            },
765            sync.wrapped_account_cryptographic_state.clone(),
766            sync,
767        )
768        .await;
769
770        assert!(result.is_ok());
771        assert!(
772            state_bridge.get_v2_upgrade_token().await.is_none(),
773            "without an upgrade token, the state bridge must not be written"
774        );
775        assert!(
776            state_bridge
777                .get_account_cryptographic_state()
778                .await
779                .is_none()
780        );
781        assert!(state_bridge.get_user_key().await.is_none());
782        if let ApiClient::Mock(mut mock) = api_client {
783            mock.accounts_key_management_api.checkpoint();
784        }
785    }
786
787    #[tokio::test]
788    async fn test_rotate_user_keys_old_attachments_returns_error() {
789        let (key_store, mut sync) = make_test_key_store_and_synced_data();
790        let enc_string = "2.STIyTrfDZN/JXNDN9zNEMw==|NDLum8BHZpPNYhJo9ggSkg==|UCsCLlBO3QzdPwvMAWs2VVwuE6xwOx/vxOooPObqnEw=";
791
792        // Add a cipher with an old attachment (key is None)
793        sync.ciphers = vec![Cipher {
794            partial_data: None,
795            id: None,
796            organization_id: None,
797            folder_id: None,
798            collection_ids: vec![],
799            r#type: CipherType::Login,
800            login: None,
801            identity: None,
802            card: None,
803            secure_note: None,
804            ssh_key: None,
805            bank_account: None,
806            drivers_license: None,
807            passport: None,
808            favorite: false,
809            reprompt: Default::default(),
810            organization_use_totp: false,
811            edit: false,
812            permissions: None,
813            view_password: false,
814            name: Some(enc_string.parse().unwrap()),
815            revision_date: DateTime::from_str("2024-01-01T00:00:00Z").unwrap(),
816            archived_date: None,
817            creation_date: DateTime::from_str("2024-01-01T00:00:00Z").unwrap(),
818            attachments: Some(vec![Attachment {
819                id: None,
820                url: None,
821                size: None,
822                size_name: None,
823                file_name: None,
824                key: None, // Old attachment - no per-attachment key
825            }]),
826            fields: None,
827            key: None,
828            notes: None,
829            local_data: None,
830            password_history: None,
831            deleted_date: None,
832            data: None,
833        }];
834
835        let api_client = ApiClient::new_mocked(|mock| {
836            // Rotation API should never be called
837            mock.accounts_key_management_api
838                .expect_rotate_user_keys()
839                .never();
840        });
841
842        let state_bridge = make_state_bridge();
843        let result = internal_rotate_user_keys(
844            &key_store,
845            &api_client,
846            &state_bridge,
847            None,
848            RotateUserKeysRequest {
849                key_rotation_method: KeyRotationMethod::Password {
850                    password: "test_password".to_string(),
851                },
852                trusted_organization_public_keys: vec![],
853                trusted_emergency_access_public_keys: vec![],
854                upgrade_token_action: UpgradeTokenAction::Skip,
855            },
856            sync.wrapped_account_cryptographic_state.clone(),
857            sync,
858        )
859        .await;
860
861        assert!(matches!(result, Err(RotateUserKeysError::OldAttachments)));
862        if let ApiClient::Mock(mut mock) = api_client {
863            mock.accounts_key_management_api.checkpoint();
864        }
865    }
866
867    #[tokio::test]
868    async fn test_rotate_user_keys_key_connector_success() {
869        let (key_store, sync) = make_test_key_store_and_synced_data();
870
871        let key_connector_key = KeyConnectorKey::make();
872        let key_connector_api_client = bitwarden_api_key_connector::apis::ApiClient::new_mocked(
873            |mock| {
874                let key_connector_key_clone = key_connector_key.clone();
875                mock.user_keys_api
876                    .expect_get_user_key()
877                    .once()
878                    .returning(move || {
879                        let encoded: bitwarden_encoding::B64 =
880                            key_connector_key_clone.clone().into();
881                        Ok(
882                            bitwarden_api_key_connector::models::user_key_response_model::UserKeyResponseModel {
883                                key: encoded.to_string(),
884                            },
885                        )
886                    });
887            },
888        );
889
890        let api_client = ApiClient::new_mocked(|mock| {
891            mock.accounts_key_management_api
892                .expect_rotate_user_keys()
893                .once()
894                .returning(|req| {
895                    let req = req.expect("request body should be present");
896                    assert!(
897                        req.unlock_method_data
898                            .key_connector_key_wrapped_user_key
899                            .is_some(),
900                        "key_connector_key_wrapped_user_key should be set for KC rotation"
901                    );
902                    assert!(
903                        req.unlock_method_data.master_password_unlock_data.is_none(),
904                        "master_password_unlock_data should be None for KC rotation"
905                    );
906                    Ok(())
907                });
908        });
909
910        let state_bridge = make_state_bridge();
911        let result = internal_rotate_user_keys(
912            &key_store,
913            &api_client,
914            &state_bridge,
915            Some(&key_connector_api_client),
916            RotateUserKeysRequest {
917                key_rotation_method: KeyRotationMethod::KeyConnector {
918                    key_connector_url: "https://kc.example.com".to_string(),
919                },
920                trusted_organization_public_keys: vec![],
921                trusted_emergency_access_public_keys: vec![],
922                upgrade_token_action: UpgradeTokenAction::Skip,
923            },
924            sync.wrapped_account_cryptographic_state.clone(),
925            sync,
926        )
927        .await;
928
929        assert!(result.is_ok());
930        if let ApiClient::Mock(mut mock) = api_client {
931            mock.accounts_key_management_api.checkpoint();
932        }
933        if let bitwarden_api_key_connector::apis::ApiClient::Mock(mut mock) =
934            key_connector_api_client
935        {
936            mock.user_keys_api.checkpoint();
937        }
938    }
939
940    #[tokio::test]
941    async fn test_rotate_user_keys_key_connector_api_failure() {
942        let (key_store, sync) = make_test_key_store_and_synced_data();
943
944        let key_connector_api_client =
945            bitwarden_api_key_connector::apis::ApiClient::new_mocked(|mock| {
946                mock.user_keys_api
947                    .expect_get_user_key()
948                    .once()
949                    .returning(move || {
950                        Err(bitwarden_api_key_connector::apis::Error::ResponseError(
951                            bitwarden_api_key_connector::apis::ResponseContent {
952                                status: reqwest::StatusCode::INTERNAL_SERVER_ERROR,
953                                content: "Server Error".to_string(),
954                            },
955                        ))
956                    });
957            });
958
959        let api_client = ApiClient::new_mocked(|mock| {
960            mock.accounts_key_management_api
961                .expect_rotate_user_keys()
962                .never();
963        });
964
965        let state_bridge = make_state_bridge();
966        let result = internal_rotate_user_keys(
967            &key_store,
968            &api_client,
969            &state_bridge,
970            Some(&key_connector_api_client),
971            RotateUserKeysRequest {
972                key_rotation_method: KeyRotationMethod::KeyConnector {
973                    key_connector_url: "https://kc.example.com".to_string(),
974                },
975                trusted_organization_public_keys: vec![],
976                trusted_emergency_access_public_keys: vec![],
977                upgrade_token_action: UpgradeTokenAction::Skip,
978            },
979            sync.wrapped_account_cryptographic_state.clone(),
980            sync,
981        )
982        .await;
983
984        assert!(matches!(result, Err(RotateUserKeysError::KeyConnectorApi)));
985        if let ApiClient::Mock(mut mock) = api_client {
986            mock.accounts_key_management_api.checkpoint();
987        }
988        if let bitwarden_api_key_connector::apis::ApiClient::Mock(mut mock) =
989            key_connector_api_client
990        {
991            mock.user_keys_api.checkpoint();
992        }
993    }
994
995    #[tokio::test]
996    async fn test_rotate_user_keys_v1_to_v2_upgrade_defers_organization_account_recovery() {
997        let (key_store, sync) = make_test_key_store_and_synced_data_with_organization();
998        let organization_id = sync.organization_memberships[0].organization_id;
999
1000        let api_client = ApiClient::new_mocked(|mock| {
1001            mock.accounts_key_management_api
1002                .expect_rotate_user_keys()
1003                .once()
1004                .returning(move |req| {
1005                    let req = req.expect("request body should be present");
1006                    assert!(
1007                        req.unlock_data.v2_upgrade_token.is_some(),
1008                        "without the token, admins cannot update account recovery"
1009                    );
1010
1011                    let account_recovery = req
1012                        .unlock_data
1013                        .organization_account_recovery_unlock_data
1014                        .as_ref()
1015                        .expect("account recovery data should be present");
1016                    assert_eq!(account_recovery.len(), 1);
1017                    assert_eq!(account_recovery[0].organization_id, organization_id);
1018                    assert!(
1019                        account_recovery[0].reset_password_key.is_none(),
1020                        "account recovery is left for organization admins to update"
1021                    );
1022                    Ok(())
1023                });
1024        });
1025
1026        let state_bridge = make_state_bridge();
1027        let result = internal_rotate_user_keys(
1028            &key_store,
1029            &api_client,
1030            &state_bridge,
1031            None,
1032            RotateUserKeysRequest {
1033                key_rotation_method: KeyRotationMethod::Password {
1034                    password: "test_password".to_string(),
1035                },
1036                trusted_organization_public_keys: vec![],
1037                trusted_emergency_access_public_keys: vec![],
1038                upgrade_token_action: UpgradeTokenAction::CreateIfNeeded,
1039            },
1040            sync.wrapped_account_cryptographic_state.clone(),
1041            sync,
1042        )
1043        .await;
1044
1045        assert!(result.is_ok());
1046        if let ApiClient::Mock(mut mock) = api_client {
1047            mock.accounts_key_management_api.checkpoint();
1048        }
1049    }
1050
1051    #[tokio::test]
1052    async fn test_rotate_user_keys_v1_to_v2_upgrade_ignores_trusted_organization_public_keys() {
1053        let (key_store, sync) = make_test_key_store_and_synced_data_with_organization();
1054        let organization_public_key = sync.organization_memberships[0].public_key.clone();
1055
1056        let api_client = ApiClient::new_mocked(|mock| {
1057            mock.accounts_key_management_api
1058                .expect_rotate_user_keys()
1059                .once()
1060                .returning(move |req| {
1061                    let req = req.expect("request body should be present");
1062                    let account_recovery = req
1063                        .unlock_data
1064                        .organization_account_recovery_unlock_data
1065                        .as_ref()
1066                        .expect("account recovery data should be present");
1067                    assert_eq!(account_recovery.len(), 1);
1068                    assert!(
1069                        account_recovery[0].reset_password_key.is_none(),
1070                        "trusting a key does not change who updates account recovery"
1071                    );
1072                    Ok(())
1073                });
1074        });
1075
1076        let state_bridge = make_state_bridge();
1077        let result = internal_rotate_user_keys(
1078            &key_store,
1079            &api_client,
1080            &state_bridge,
1081            None,
1082            RotateUserKeysRequest {
1083                key_rotation_method: KeyRotationMethod::Password {
1084                    password: "test_password".to_string(),
1085                },
1086                // Older callers may still send organization keys. That must keep working.
1087                trusted_organization_public_keys: vec![organization_public_key],
1088                trusted_emergency_access_public_keys: vec![],
1089                upgrade_token_action: UpgradeTokenAction::CreateIfNeeded,
1090            },
1091            sync.wrapped_account_cryptographic_state.clone(),
1092            sync,
1093        )
1094        .await;
1095
1096        assert!(result.is_ok());
1097        if let ApiClient::Mock(mut mock) = api_client {
1098            mock.accounts_key_management_api.checkpoint();
1099        }
1100    }
1101
1102    #[tokio::test]
1103    async fn test_rotate_user_keys_untrusted_organization_without_upgrade_token_returns_error() {
1104        let (key_store, sync) = make_test_key_store_and_synced_data_with_organization();
1105
1106        let api_client = ApiClient::new_mocked(|mock| {
1107            mock.accounts_key_management_api
1108                .expect_rotate_user_keys()
1109                .never();
1110        });
1111
1112        let state_bridge = make_state_bridge();
1113        let result = internal_rotate_user_keys(
1114            &key_store,
1115            &api_client,
1116            &state_bridge,
1117            None,
1118            RotateUserKeysRequest {
1119                key_rotation_method: KeyRotationMethod::Password {
1120                    password: "test_password".to_string(),
1121                },
1122                trusted_organization_public_keys: vec![],
1123                trusted_emergency_access_public_keys: vec![],
1124                upgrade_token_action: UpgradeTokenAction::Skip,
1125            },
1126            sync.wrapped_account_cryptographic_state.clone(),
1127            sync,
1128        )
1129        .await;
1130
1131        assert!(matches!(result, Err(RotateUserKeysError::UntrustedKey)));
1132        if let ApiClient::Mock(mut mock) = api_client {
1133            mock.accounts_key_management_api.checkpoint();
1134        }
1135    }
1136}