Skip to content

Privacy-first password manager with built-in email aliasing. Fully encrypted and self-hostable.

Refactor account key chain resolving (#2159)

Leendert de Borst827b7dc1f25d
diff --git a/core/rust/src/vault_sync/engine.rs b/core/rust/src/vault_sync/engine.rs
index eea959f54..357a70a65 100644
--- a/core/rust/src/vault_sync/engine.rs
+++ b/core/rust/src/vault_sync/engine.rs
@@ -11,7 +11,7 @@ use super::pull::{self, PulledVault};
use super::push::{self, CanonicalizedSet, PushStatus};
use super::session::Host;
use super::state::{self, Ctx};
-use super::types::{Db, FailureFields, FullSyncResult, LogLevel, MigrateManifestResult, MigrationKind, MigrationStatusResult, OperationResult, SessionOutcome, StatusCheckResult, StatusResponse, SyncOperation, SyncRequest};
+use super::types::{Db, FailureFields, FullSyncResult, LogLevel, MigrateManifestResult, MigrationKind, MigrationStatusResult, OperationResult, ResolveVaultKeyResult, SessionOutcome, StatusCheckResult, StatusResponse, SyncOperation, SyncRequest};
use super::{db, http, keys, legacy, version};
use crate::crypto;
@@ -44,6 +44,10 @@ pub(crate) async fn run(host: Host, request: SyncRequest) -> Value {
let result = status_check(&mut ctx).await;
finish(&ctx, result)
}
+ SyncOperation::ResolveVaultKey => {
+ let result = resolve_vault_key(&mut ctx).await;
+ finish(&ctx, result)
+ }
}
}
@@ -196,7 +200,11 @@ async fn run_sync_preflight(ctx: &mut Ctx) -> SyncResult<Preflight> {
// A changed server salt means the password was changed elsewhere, which warrants a logout.
assert_salt_unchanged(ctx, status.srp_salt.as_deref()).await?;
- if needs_pull && !keys::adopt_remote_vault_key_if_needed(ctx).await? {
+ // The session key is the VEK (or a legacy account's KEK) by contract; the host resolved it at login. The one
+ // case the sync has to catch itself: this device holds no chain because the account was still legacy when it
+ // logged in, and another device created the hierarchy since. That shows up as a revision change, so a pull
+ // (or a push about to hit the server) is where it is checked.
+ if (needs_pull || ctx.is_dirty) && !keys::has_local_vault_key(&ctx.host).await? && !keys::adopt_hierarchy_created_elsewhere(ctx).await? {
return Ok(Preflight::Finish(logout(LogoutReason::PasswordChanged)));
}
@@ -343,7 +351,7 @@ async fn apply_server_directed_changes(ctx: &mut Ctx, status: &StatusResponse) -
let key = ctx.encryption_key()?;
let bytes = db::export(&ctx.host, Db::Local).await?;
- let stored = state::store_vault(&ctx.host, &state::encrypt_vault_blob(&bytes, &key)?, true, None, None).await?;
+ let stored = ctx.store_vault(&state::encrypt_vault_blob(&bytes, &key)?, true, None, None).await?;
let was_dirty = ctx.is_dirty;
ctx.is_dirty = true;
ctx.mutation_sequence = stored.mutation_sequence;
@@ -365,7 +373,7 @@ async fn materialized_vault_result(ctx: &mut Ctx, pulled: &PulledVault) -> SyncR
/// Store a pulled vault as the local one and only then commit its revisions as the local truth. A store the host
/// refuses (a mutation raced the pull) re-runs the sync instead, which is the returned flow.
async fn commit_pulled_vault(ctx: &mut Ctx, pulled: &PulledVault) -> SyncResult<Option<Flow>> {
- let stored = state::store_vault(&ctx.host, &pulled.encrypted_vault, false, Some(ctx.mutation_sequence), Some(pulled.revision)).await?;
+ let stored = ctx.store_vault(&pulled.encrypted_vault, false, Some(ctx.mutation_sequence), Some(pulled.revision)).await?;
if !stored.success {
ctx.log("[VaultSync] Mutation detected during sync, re-syncing...").await;
return Ok(Some(Flow::Resync { outdated: false }));
@@ -472,12 +480,9 @@ async fn migration_status(ctx: &mut Ctx) -> MigrationStatusResult {
if schema == SchemaState::LegacyChain {
return Ok(MigrationKind::None);
}
- match keys::fetch_vault_key(&ctx.host).await {
- Ok(Some(_)) => {
- keys::adopt_remote_vault_key_if_needed(ctx).await?;
- }
- Ok(None) => {}
- Err(error) => ctx.warn(format!("[ManifestMigration] Vault key probe failed, classifying from local state: {}", error)).await,
+ if !keys::has_local_vault_key(&ctx.host).await? {
+ // A hierarchy another device created since this device logged in classifies as no migration at all.
+ keys::adopt_hierarchy_created_elsewhere(ctx).await?;
}
if !keys::has_local_vault_key(&ctx.host).await? {
return Ok(MigrationKind::StorageFormatUpgrade);
@@ -503,7 +508,7 @@ async fn migrate_manifest(ctx: &mut Ctx) -> MigrateManifestResult {
if schema == SchemaState::LegacyChain {
return Err(SyncError::LegacyUpgradePending);
}
- if !keys::adopt_remote_vault_key_if_needed(ctx).await? {
+ if !keys::has_local_vault_key(&ctx.host).await? && !keys::adopt_hierarchy_created_elsewhere(ctx).await? {
return Err(SyncError::KeyOutOfSync);
}
let needs_schema_migration = schema == SchemaState::Stale;
@@ -513,7 +518,7 @@ async fn migrate_manifest(ctx: &mut Ctx) -> MigrateManifestResult {
}
if needs_schema_migration {
let migrated_bytes = legacy::migrate_vault_to_current_schema(ctx).await?;
- let stored = state::store_vault(&ctx.host, &state::encrypt_vault_blob(&migrated_bytes, &encryption_key)?, true, None, None).await?;
+ let stored = ctx.store_vault(&state::encrypt_vault_blob(&migrated_bytes, &encryption_key)?, true, None, None).await?;
ctx.mutation_sequence = stored.mutation_sequence;
ctx.is_dirty = true;
ctx.vault_changed = true;
@@ -543,6 +548,17 @@ async fn migrate_manifest(ctx: &mut Ctx) -> MigrateManifestResult {
}
}
+/// The login-time key resolution; see `keys::resolve_vault_key`.
+async fn resolve_vault_key(ctx: &mut Ctx) -> ResolveVaultKeyResult {
+ match keys::resolve_vault_key(ctx).await {
+ Ok(has_vault_key) => ResolveVaultKeyResult { success: true, has_vault_key, encryption_key: ctx.encryption_key.clone(), ..Default::default() },
+ Err(error) => {
+ ctx.warn(format!("[VaultSync] Key resolution failed: {}", error)).await;
+ ResolveVaultKeyResult { failure: (&error).into(), ..Default::default() }
+ }
+ }
+}
+
/// A lightweight status check: does the server hold newer state, and does the session still stand.
async fn status_check(ctx: &mut Ctx) -> StatusCheckResult {
let checked: SyncResult<StatusCheckResult> = async {
diff --git a/core/rust/src/vault_sync/keys.rs b/core/rust/src/vault_sync/keys.rs
index 9fe707c16..897f973ce 100644
--- a/core/rust/src/vault_sync/keys.rs
+++ b/core/rust/src/vault_sync/keys.rs
@@ -116,15 +116,81 @@ pub(crate) async fn open_shared_manifest_veks(ctx: &Ctx) -> SyncResult<HashMap<S
Ok(veks)
}
-/// Adopt a server-side vault key this device does not know about yet (another device performed the KEK/VEK
-/// migration while this one held the old password-derived key). False only when this device's key matches
-/// neither the KEK nor the VEK, which requires a re-login.
-pub(crate) async fn adopt_remote_vault_key_if_needed(ctx: &mut Ctx) -> SyncResult<bool> {
- if has_local_vault_key(&ctx.host).await? {
- return Ok(true);
+/// The cached account-key chain, when this device holds one.
+async fn cached_chain(host: &Host) -> SyncResult<Option<(String, String)>> {
+ let Some(encrypted_account_key) = state::get::<String>(host, state::ENCRYPTED_ACCOUNT_KEY).await? else { return Ok(None) };
+ let Some(encrypted_vek) = state::get::<String>(host, state::ENCRYPTED_VEK).await? else { return Ok(None) };
+ Ok(Some((encrypted_account_key, encrypted_vek)))
+}
+
+/// Whether the transport reached the server and got an answer other than an auth or version refusal.
+fn is_server_unreachable(error: &SyncError) -> bool {
+ matches!(error, SyncError::Network(_) | SyncError::Timeout(_) | SyncError::Http { .. })
+}
+
+/// Clear the cached key chain: the account has none (legacy), so the password-derived key is the vault key.
+async fn clear_cached_chain(host: &Host) -> SyncResult<()> {
+ for key in [state::ENCRYPTED_ACCOUNT_KEY, state::ENCRYPTED_VEK, state::ACCOUNT_PUBLIC_KEY, state::ENCRYPTED_ACCOUNT_PRIVATE_KEY] {
+ state::remove(host, key).await?;
+ }
+ Ok(())
+}
+
+/// Open a key chain with the password-derived key: the VEK becomes the session key and the private key is staged.
+async fn open_chain(ctx: &mut Ctx, encrypted_account_key: &str, encrypted_vek: &str, encrypted_private_key: Option<&str>, kek: &str) -> SyncResult<()> {
+ let (vek, account_key) = crypto::resolve_vault_encryption_key(encrypted_account_key, encrypted_vek, kek).map_err(|_| SyncError::VaultDecryptFailed("the password-derived key does not open the account key chain".to_string()))?;
+ ctx.set_encryption_key(vek.to_string());
+ stage_account_private_key(ctx, &account_key, encrypted_private_key).await;
+ Ok(())
+}
+
+/// The login-time key resolution (the `resolveVaultKey` operation). The request carries the password-derived key
+/// (KEK); the account's key chain is fetched from the server (the cached one stands in when the server cannot be
+/// reached or predates the endpoint), opened with the KEK, cached for offline unlock, and the VEK becomes the
+/// session key. An account without a chain is a sqlite-blob legacy account whose KEK is the vault key itself; its
+/// hierarchy is created later by the migration push. Returns whether the account has a chain.
+pub(crate) async fn resolve_vault_key(ctx: &mut Ctx) -> SyncResult<bool> {
+ let kek = ctx.encryption_key()?;
+ let fetched = http::get::<VaultKeyGetResponse>(&ctx.host, "VaultKey/Password", false).await;
+ ctx.vault_key_probed = true;
+ match fetched {
+ Ok(response) => match response.vault_key {
+ Some(vault_key) if vault_key.encrypted_vek.is_some() => {
+ let encrypted_vek = vault_key.encrypted_vek.clone().unwrap_or_default();
+ open_chain(ctx, &vault_key.encrypted_account_key, &encrypted_vek, vault_key.encrypted_account_private_key.as_deref(), &kek).await?;
+ cache_vault_key_blobs(&ctx.host, &vault_key).await?;
+ ctx.log("[VaultSync] Opened the account's key chain; the session key is the VEK.").await;
+ Ok(true)
+ }
+ _ => {
+ clear_cached_chain(&ctx.host).await?;
+ ctx.log("[VaultSync] The account has no key chain yet (legacy vault); the password-derived key is the vault key.").await;
+ Ok(false)
+ }
+ },
+ Err(error) if is_server_unreachable(&error) => {
+ ctx.warn(format!("[VaultSync] Could not fetch the key chain, opening the cached one: {}", error)).await;
+ let Some((encrypted_account_key, encrypted_vek)) = cached_chain(&ctx.host).await? else { return Ok(false) };
+ let encrypted_private_key = state::get::<String>(&ctx.host, state::ENCRYPTED_ACCOUNT_PRIVATE_KEY).await?;
+ open_chain(ctx, &encrypted_account_key, &encrypted_vek, encrypted_private_key.as_deref(), &kek).await?;
+ Ok(true)
+ }
+ Err(error) => Err(error),
}
- let Some(session_key) = ctx.encryption_key.clone() else { return Ok(true) };
+}
+/// The cross-device race: this device holds no key chain (it logged in while the account was still a legacy
+/// vault), and another device may have created the hierarchy since. Probes the server once per run; when the
+/// hierarchy exists, the stored vault is brought under the VEK and the session key swapped, which the host adopts
+/// through the store command. Callers gate this on the absence of a cached chain and on a sync that pulls or
+/// pushes: another device's migration shows up as a revision change, so that is when it becomes visible.
+/// False only when the session key does not open the server's chain, which requires a re-login.
+pub(crate) async fn adopt_hierarchy_created_elsewhere(ctx: &mut Ctx) -> SyncResult<bool> {
+ if ctx.vault_key_probed {
+ return Ok(true);
+ }
+ ctx.vault_key_probed = true;
+ let session_key = ctx.encryption_key()?;
let vault_key = match fetch_vault_key(&ctx.host).await {
Ok(result) => result,
Err(error) => {
@@ -136,27 +202,45 @@ pub(crate) async fn adopt_remote_vault_key_if_needed(ctx: &mut Ctx) -> SyncResul
let Some(encrypted_vek) = vault_key.encrypted_vek.clone() else { return Ok(true) };
let adopted: SyncResult<()> = async {
- let (vek, _account_key) = crypto::resolve_vault_encryption_key(&vault_key.encrypted_account_key, &encrypted_vek, &session_key)?;
- if let Some(encrypted_vault) = state::load_vault(&ctx.host).await? {
- let plaintext = state::decrypt_vault_blob(&encrypted_vault, &session_key)?;
- let re_encrypted = crypto::symmetric_encrypt_bytes(&plaintext, &vek)?;
- state::store_vault_with_key(&ctx.host, &re_encrypted, false, None, None, Some(vek.to_string())).await?;
- }
- re_encrypt_shared_manifest_records(ctx, &vek).await?;
+ let (vek, account_key) = crypto::resolve_vault_encryption_key(&vault_key.encrypted_account_key, &encrypted_vek, &session_key)?;
+ adopt_vek(ctx, &session_key, &vek).await?;
cache_vault_key_blobs(&ctx.host, &vault_key).await?;
- ctx.set_encryption_key(vek.to_string());
+ stage_account_private_key(ctx, &account_key, vault_key.encrypted_account_private_key.as_deref()).await;
Ok(())
}
.await;
match adopted {
Ok(()) => {
- ctx.log("[VaultSync] Adopted vault key created by another client; session key swapped to the VEK.").await;
+ ctx.log("[VaultSync] Another device created the account's key hierarchy; adopted it and swapped the session key to the VEK.").await;
Ok(true)
}
Err(error) => {
- ctx.warn(format!("[VaultSync] Session key matches neither the KEK nor the VEK, forcing re-login: {}", error)).await;
+ ctx.warn(format!("[VaultSync] The session key does not open the key hierarchy the server holds, forcing re-login: {}", error)).await;
Ok(false)
}
}
}
+
+/// Swap the session key for the VEK: re-encrypt the stored vault and the shared-manifest records under it, then
+/// report it to the host.
+async fn adopt_vek(ctx: &mut Ctx, old_key: &str, vek: &str) -> SyncResult<()> {
+ if let Some(encrypted_vault) = state::load_vault(&ctx.host).await? {
+ let plaintext = state::decrypt_vault_blob(&encrypted_vault, old_key)?;
+ let re_encrypted = crypto::symmetric_encrypt_bytes(&plaintext, vek)?;
+ state::store_vault_with_key(&ctx.host, &re_encrypted, false, None, None, Some(vek.to_string())).await?;
+ }
+ re_encrypt_shared_manifest_records(ctx, vek).await?;
+ ctx.set_encryption_key(vek.to_string());
+ Ok(())
+}
+
+/// Open the account private key with the Account Key and stage it for the grant flows of this run. A chain without
+/// a keypair, or one whose private key does not open, leaves grant decryption to the personal manifest's key rows.
+async fn stage_account_private_key(ctx: &mut Ctx, account_key: &str, encrypted_private_key: Option<&str>) {
+ let Some(encrypted) = encrypted_private_key.filter(|e| !e.is_empty()) else { return };
+ match crypto::symmetric_decrypt(encrypted, account_key) {
+ Ok(private_key) => ctx.set_account_private_key(private_key),
+ Err(error) => ctx.warn(format!("[VaultSync] The cached account private key did not open; shared grants fall back to the vault's key rows. {}", error)).await,
+ }
+}
diff --git a/core/rust/src/vault_sync/mod.rs b/core/rust/src/vault_sync/mod.rs
index a4a55efc8..33c743ef5 100644
--- a/core/rust/src/vault_sync/mod.rs
+++ b/core/rust/src/vault_sync/mod.rs
@@ -20,4 +20,4 @@ mod tests;
pub use errors::{ErrorCode, Failure, LogoutReason, SyncError};
pub use session::SyncSession;
-pub use types::{Command, CommandKind, Db, FullSyncResult, HttpMethod, LogLevel, MigrateManifestResult, MigrationKind, MigrationStatusResult, SessionOutcome, SessionUpdates, SqlStatement, StatusCheckResult, SyncOperation, SyncRequest};
+pub use types::{Command, CommandKind, Db, FullSyncResult, HttpMethod, LogLevel, MigrateManifestResult, MigrationKind, MigrationStatusResult, ResolveVaultKeyResult, SessionOutcome, SessionUpdates, SqlStatement, StatusCheckResult, SyncOperation, SyncRequest};
diff --git a/core/rust/src/vault_sync/push.rs b/core/rust/src/vault_sync/push.rs
index 1414b3f38..75cc0d2f8 100644
--- a/core/rust/src/vault_sync/push.rs
+++ b/core/rust/src/vault_sync/push.rs
@@ -173,10 +173,10 @@ async fn resolve_bucket_write_keys(ctx: &Ctx, personal_vek: &str) -> SyncResult<
*/
/// Upload the stored vault: bucket-only when every pending mutation is bucket-scoped, full otherwise. Fails
-/// with `KeyOutOfSync` when the session key matches neither the server's KEK nor its VEK.
+/// with `KeyOutOfSync` when the session key does not open a hierarchy another device created meanwhile.
pub(crate) async fn upload_vault(ctx: &mut Ctx, cache: Option<(u64, CanonicalizedSet)>, force_full_write: bool, create_vault_key: bool) -> SyncResult<UploadOutcome> {
let mutation_seq_at_start = ctx.mutation_sequence;
- if !keys::adopt_remote_vault_key_if_needed(ctx).await? {
+ if !keys::has_local_vault_key(&ctx.host).await? && !keys::adopt_hierarchy_created_elsewhere(ctx).await? {
return Err(SyncError::KeyOutOfSync);
}
@@ -253,8 +253,7 @@ async fn upload_new_vault_to_server(ctx: &mut Ctx, cached: Option<CanonicalizedS
let key_after = ctx.encryption_key()?;
if vault_pruned || key_after != key_before {
let bytes = db::export(&ctx.host, Db::Local).await?;
- let new_key = if key_after != key_before { Some(key_after.clone()) } else { None };
- state::store_vault_with_key(&ctx.host, &state::encrypt_vault_blob(&bytes, &key_after)?, false, None, None, new_key).await?;
+ ctx.store_vault(&state::encrypt_vault_blob(&bytes, &key_after)?, false, None, None).await?;
ctx.vault_changed = true;
}
Ok((status, vault_pruned))
diff --git a/core/rust/src/vault_sync/state.rs b/core/rust/src/vault_sync/state.rs
index da5fa5c04..1b8df7570 100644
--- a/core/rust/src/vault_sync/state.rs
+++ b/core/rust/src/vault_sync/state.rs
@@ -24,6 +24,7 @@ pub(crate) struct Ctx {
pub updates: SessionUpdates,
pub vault_changed: bool,
pub schema: Option<SchemaInfo>,
+ pub vault_key_probed: bool,
has_local_vault: bool,
}
@@ -45,6 +46,7 @@ impl Ctx {
updates: SessionUpdates::default(),
vault_changed: false,
schema: None,
+ vault_key_probed: false,
has_local_vault: false,
host,
request,
@@ -76,6 +78,11 @@ impl Ctx {
self.account_private_key = Some(key);
}
+ /// Persist the at-rest vault blob.
+ pub async fn store_vault(&self, encrypted_blob: &str, mark_dirty: bool, expected_mutation_seq: Option<u64>, revision: Option<i64>) -> SyncResult<StoreOutcome> {
+ store_vault_with_key(&self.host, encrypted_blob, mark_dirty, expected_mutation_seq, revision, self.updates.encryption_key.clone()).await
+ }
+
/// The current schema.
pub async fn schema(&mut self) -> SyncResult<SchemaInfo> {
if let Some(schema) = &self.schema {
@@ -154,11 +161,6 @@ pub(crate) async fn load_vault(host: &Host) -> SyncResult<Option<String>> {
Ok(stored.encrypted_blob.filter(|blob| !blob.is_empty()))
}
-/// Persist the at-rest vault blob through the host.
-pub(crate) async fn store_vault(host: &Host, encrypted_blob: &str, mark_dirty: bool, expected_mutation_seq: Option<u64>, revision: Option<i64>) -> SyncResult<StoreOutcome> {
- store_vault_with_key(host, encrypted_blob, mark_dirty, expected_mutation_seq, revision, None).await
-}
-
/// Persist the at-rest vault blob, telling the host the (new) key it is encrypted under.
pub(crate) async fn store_vault_with_key(host: &Host, encrypted_blob: &str, mark_dirty: bool, expected_mutation_seq: Option<u64>, revision: Option<i64>, encryption_key: Option<String>) -> SyncResult<StoreOutcome> {
host.call(Command::VaultStore { encrypted_blob: encrypted_blob.to_string(), mark_dirty, encryption_key, expected_mutation_seq, revision }).await
diff --git a/core/rust/src/vault_sync/types.rs b/core/rust/src/vault_sync/types.rs
index 4ce3a4262..e1a8a39d0 100644
--- a/core/rust/src/vault_sync/types.rs
+++ b/core/rust/src/vault_sync/types.rs
@@ -20,6 +20,8 @@ pub enum SyncOperation {
MigrateManifest,
/// Run a status check.
StatusCheck,
+ /// Open the account's key chain with the password-derived key right after login; see `ResolveVaultKeyResult`.
+ ResolveVaultKey,
}
/// Sync request.
@@ -184,6 +186,28 @@ impl OperationResult for MigrateManifestResult {
}
}
+/// Outcome of the login-time key resolution: the vault key the host stores as its session key (the VEK behind
+/// the account's key chain, or the password-derived key itself for a legacy account without a chain).
+#[derive(Debug, Clone, Default, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct ResolveVaultKeyResult {
+ pub success: bool,
+ /// Whether the account has a key chain (false: legacy vault, the migration push creates one).
+ pub has_vault_key: bool,
+ #[serde(skip_serializing_if = "Option::is_none")]
+ pub encryption_key: Option<String>,
+ #[serde(flatten)]
+ pub failure: FailureFields,
+ #[serde(flatten)]
+ pub session: SessionOutcome,
+}
+
+impl OperationResult for ResolveVaultKeyResult {
+ fn session_mut(&mut self) -> &mut SessionOutcome {
+ &mut self.session
+ }
+}
+
/// Outcome of the lightweight status check.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]