Credential Rotation

Overview

Credential rotation here means changing the Master Password while keeping the same database file. The application re-wraps the Vault Key (DEK) at rest and refreshes the hardware-bound session. It does not re-encrypt every user record: those ciphertexts are tied to the Vault Key, which is not rotated by this flow.

In standard key management terms, this flow rotates the source material (the Master Password and vaultSalt) to generate a new KEK, which is then used to produce updated Wrapped Keys (master_password.vaultKey and session.token).

How It Works

When you update your Master Password, useAuthStore.changeMasterPassword performs the following:

1. Verify and Unlock

The current Master Password is checked against the bcrypt hash. The stored vaultKey is unwrapped to recover the raw Vault Key (the secret used for record encryption).

2. Re-wrap the Vault Key

A new bcrypt hash is generated for the new password and a new vaultSalt is generated specifically for scrypt key derivation. The Vault Key is wrapped again with AES-256-GCM under a KEK derived via scrypt from the new password and the new vaultSalt. The master_password document is updated with the new hash, vaultSalt, and vaultKey.

3. Refresh the Session

A new session.token is written: the Vault Key is wrapped for hardware-bound auto-unlock using the updated vaultSalt, so "Stay Signed In" continues to work.

4. User Records

Entries of type password, totp, and token are not bulk re-encrypted during this flow. Their ciphertext was always keyed by the Vault Key; changing the Master Password only changes how that Vault Key is wrapped in master_password and in the session document.

Security Considerations

• Credential Rotation: Changing the Master Password protects future access to the live vault.db file. However, since this is a local-first application, an attacker with a previous copy of the database file can still unlock it using the old password. Treat database file copies as sensitive secrets.
• No Automatic Backup: Changing the password does not create a backup by itself. Users should perform a portable JSON export before rotation to ensure data safety.
• Memory: After a successful change, the Vault Key remains in memory until logout or process exit, consistent with a normal unlocked session.

Summary

Credential rotation updates the password hash and the wrapped copies of the Vault Key. Record-level ciphertext remains valid because the underlying Vault Key is unchanged; only the wrapped copies stored in master_password and the hardware-bound session.token are updated.