Skip to content

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

Update VaultKeyServices.ts (#2159)

Leendert de Borst948da609d627
diff --git a/apps/browser-extension/src/utils/VaultKeyService.ts b/apps/browser-extension/src/utils/VaultKeyService.ts
index 7f44a5a3f..b40b5b328 100644
--- a/apps/browser-extension/src/utils/VaultKeyService.ts
+++ b/apps/browser-extension/src/utils/VaultKeyService.ts
@@ -1,10 +1,5 @@
/**
- * VaultKeyService.
- *
- * Client-side helper for the KEK/VEK model. The vault content is encrypted with a random Vault Encryption Key
- * (VEK) that never changes; the server stores the VEK wrapped (AES-256-GCM) with a Key Encryption Key (KEK)
- * derived from the master password. This service resolves which key the rest of the app should use as "the
- * encryption key": the unwrapped VEK for migrated users, or the password-derived key itself for legacy users.
+ * VaultKeyService with client-side helpers for key operations.
*/
import { storage } from 'wxt/utils/storage';
@@ -20,18 +15,14 @@ import { WebApiService } from '@/utils/WebApiService';
export const VAULT_KEY_TYPE_PASSWORD = 'password';
/**
- * How long a fetched password vault key response is reused before hitting the network again. Mirrors the /v2/Status
- * cache: long enough to collapse the repeated probes a single sync cycle makes, short enough that it never spans
- * two user actions.
+ * Short-lived cache of the last successful password vault key response, to avoid unnecessary repeated
+ * network requests.
*/
const VAULT_KEY_CACHE_TTL_MS = 1000;
/**
- * Process-wide (background service worker) cache of the last successful password vault key response.
- *
- * This exists for NOT-yet-migrated users. A migrated device answers "do I have a vault key" from its local encrypted-VEK
- * cache and never probes at all, but a legacy device has nothing to cache, so every caller that asks would otherwise
- * issue its own GET — several per sync across the status check and the push path.
+ * Process-wide (background service worker) cache of the last successful password vault key response, used by
+ * all callers that need to check if the user has a vault key.
*/
let cachedVaultKey: { data: FetchVaultKeyResult; timestamp: number } | null = null;
@@ -39,9 +30,7 @@ let cachedVaultKey: { data: FetchVaultKeyResult; timestamp: number } | null = nu
* Result of resolving the vault encryption key after deriving the password key.
*/
export type ResolvedEncryptionKey = {
- /** The key to use for all vault encryption/decryption: the VEK for migrated users, the derived key for legacy users. */
encryptionKey: string;
- /** The encrypted VEK when the user is on the KEK/VEK model, null for legacy users. */
encryptedVek: string | null;
};
@@ -49,14 +38,12 @@ export type ResolvedEncryptionKey = {
* Result of fetching the vault key from the server.
*/
export type FetchVaultKeyResult = {
- /** False when the server does not implement the VaultKey endpoint at all (older server version, HTTP 404). */
supported: boolean;
- /** The vault key, or null when the user has none (legacy user) or the endpoint is unsupported. */
vaultKey: VaultKeyResponse | null;
};
/**
- * Static helper for fetching, unwrapping, and caching the vault encryption key (VEK).
+ * Static helper for fetching, decrypting, and caching the account-key unlock chain (KEK → AK → VEK + account keypair).
*/
export class VaultKeyService {
/**
@@ -90,56 +77,34 @@ export class VaultKeyService {
}
/**
- * Resolve the vault encryption key right after authentication: fetch the vault key from the server, unwrap the
- * VEK with the password-derived key (KEK), and cache the encrypted VEK for offline unlock. For legacy users
- * (server explicitly reports no vault key) the derived key itself is the encryption key and any stale cached
- * encrypted VEK is cleared.
- * @param derivedKeyBase64 - the password-derived key (the KEK)
- * @param webApi - the API client to use
- * @throws Error with {@link AppErrorCode.VAULT_DECRYPT_FAILED} when the encrypted VEK cannot be unwrapped with the
- * derived key (wrong password, or key material out of sync).
+ * Resolve the vault encryption key right after authentication: fetch the vault key from the server, decrypt
+ * the Account Key with the password-derived key (KEK), and with the AK decrypt the VEK and the account
+ * private key. All encrypted blobs are cached for offline unlock. For legacy users (server explicitly
+ * reports no vault key) the derived key itself is the encryption key and any stale cached chain is cleared.
*/
public static async resolveEncryptionKey(derivedKeyBase64: string, webApi?: WebApiService): Promise<ResolvedEncryptionKey> {
const result = await VaultKeyService.fetchVaultKey(webApi);
if (!result.supported) {
- // Older server: trust the local cache. Legacy accounts have no cached encrypted VEK and use the derived key.
- const cachedEncryptedVek = await storage.getItem(StorageKeys.ENCRYPTED_VEK) as string | null;
- if (!cachedEncryptedVek) {
- return { encryptionKey: derivedKeyBase64, encryptedVek: null };
- }
-
- return { encryptionKey: await VaultKeyService.unwrapOrThrow(cachedEncryptedVek, derivedKeyBase64), encryptedVek: cachedEncryptedVek };
+ // Older server: trust the local cache. Legacy accounts have no cached blob chain and use the derived key.
+ return VaultKeyService.resolveFromLocalCache(derivedKeyBase64);
}
if (!result.vaultKey) {
- await storage.removeItem(StorageKeys.ENCRYPTED_VEK);
+ await storage.removeItems([StorageKeys.ENCRYPTED_VEK, StorageKeys.ENCRYPTED_ACCOUNT_KEY, StorageKeys.ACCOUNT_PUBLIC_KEY, StorageKeys.ENCRYPTED_ACCOUNT_PRIVATE_KEY]);
return { encryptionKey: derivedKeyBase64, encryptedVek: null };
}
- const vek = await VaultKeyService.unwrapOrThrow(result.vaultKey.encryptedVek, derivedKeyBase64);
- await storage.setItem(StorageKeys.ENCRYPTED_VEK, result.vaultKey.encryptedVek);
- return { encryptionKey: vek, encryptedVek: result.vaultKey.encryptedVek };
+ const vek = await VaultKeyService.unwrapChainOrThrow(result.vaultKey, derivedKeyBase64);
+ await VaultKeyService.cacheVaultKeyBlobs(result.vaultKey);
+ return { encryptionKey: vek, encryptedVek: result.vaultKey.encryptedAccountKey };
}
/**
- * Resolve the vault encryption key offline: unwrap the locally cached encrypted VEK with the derived key. For
- * legacy users (no cached encrypted VEK) the derived key itself is returned.
+ * Resolve the vault encryption key offline: decrypt the locally cached blob chain with the derived key. For
+ * legacy users (no cached chain) the derived key itself is returned.
* @param derivedKeyBase64 - the password-derived key
- * @throws Error with {@link AppErrorCode.VAULT_DECRYPT_FAILED} when unwrapping fails (wrong password).
- */
- public static async resolveEncryptionKeyOffline(derivedKeyBase64: string): Promise<string> {
- const encryptedVek = await storage.getItem(StorageKeys.ENCRYPTED_VEK) as string | null;
- if (!encryptedVek) {
- return derivedKeyBase64;
- }
-
- return VaultKeyService.unwrapOrThrow(encryptedVek, derivedKeyBase64);
- }
-
- /**
- * Drop the in-memory vault key response cache. Called when the account is cleared (logout), so a subsequent login
- * as a different user can never be answered from the previous user's response inside the TTL window.
+ * @throws Error with {@link AppErrorCode.VAULT_DECRYPT_FAILED} when decryption fails (wrong password).
*/
public static clearCache(): void {
cachedVaultKey = null;
@@ -147,28 +112,62 @@ export class VaultKeyService {
/**
* Whether this device holds a vault key, i.e. whether the session encryption key is a VEK rather than the raw
- * password-derived key. This is the local source of truth for "am I on the KEK/VEK model": the cache is written
- * by {@link resolveEncryptionKey} on every login and cleared when the server reports no vault key, so it needs no
- * server round-trip. A false answer is only ever stale in one direction (another device migrated since the last
- * login), which the background sync resolves by adopting the remote key before any vault work happens.
+ * password-derived key. This is the local source of truth for "am I on the account-key model": the cache is
+ * written by {@link resolveEncryptionKey} on every login and cleared when the server reports no vault key, so
+ * it needs no server round-trip. A false answer is only ever stale in one direction (another device migrated
+ * since the last login), which the background sync resolves by adopting the remote key before any vault work happens.
*/
public static async hasLocalVaultKey(): Promise<boolean> {
+ if ((await storage.getItem(StorageKeys.ENCRYPTED_ACCOUNT_KEY) as string | null) !== null) {
+ return true;
+ }
+ // Pre-encrypted VEK cache shape (encrypted VEK only), left behind by an older build of this extension.
return (await storage.getItem(StorageKeys.ENCRYPTED_VEK) as string | null) !== null;
}
/**
- * Refresh the local encrypted-VEK cache from the server without needing the KEK.
+ * Refresh the local blob-chain cache from the server without needing the KEK.
* @param webApi - the API client to use
*/
public static async cacheEncryptedVekFromServer(webApi?: WebApiService): Promise<void> {
const result = await VaultKeyService.fetchVaultKey(webApi);
if (result.vaultKey) {
- await storage.setItem(StorageKeys.ENCRYPTED_VEK, result.vaultKey.encryptedVek);
+ await VaultKeyService.cacheVaultKeyBlobs(result.vaultKey);
} else if (result.supported) {
- await storage.removeItem(StorageKeys.ENCRYPTED_VEK);
+ await storage.removeItems([StorageKeys.ENCRYPTED_VEK, StorageKeys.ENCRYPTED_ACCOUNT_KEY, StorageKeys.ACCOUNT_PUBLIC_KEY, StorageKeys.ENCRYPTED_ACCOUNT_PRIVATE_KEY]);
}
}
+ /**
+ * The account private key of the unlocked session (JWK string), or null when the vault is locked or
+ * the account has no keypair yet (legacy account, not migrated to manifest-v1 yet). Used to decrypt shared-manifest VEK grants.
+ */
+ public static async getSessionAccountPrivateKey(): Promise<string | null> {
+ return (await storage.getItem(StorageKeys.ACCOUNT_PRIVATE_KEY)) as string | null;
+ }
+
+ /**
+ * The cached account public key, or null when the account has no keypair yet.
+ */
+ public static async getAccountPublicKey(): Promise<string | null> {
+ return (await storage.getItem(StorageKeys.ACCOUNT_PUBLIC_KEY)) as string | null;
+ }
+
+ /**
+ * Persist the account-key blob chain produced client-side (registration is web-client-only, so this runs on
+ * the account-key migration push) and stage the session private key.
+ * @param blobs - the encrypted Account Key and KEK derivation parameters for the given unlock method.
+ */
+ public static async adoptLocalAccountKeys(blobs: { encryptedAccountKey: string; encryptedVek: string; accountPublicKey: string; encryptedAccountPrivateKey: string; accountPrivateKey: string }): Promise<void> {
+ await storage.setItems([
+ { key: StorageKeys.ENCRYPTED_ACCOUNT_KEY, value: blobs.encryptedAccountKey },
+ { key: StorageKeys.ENCRYPTED_VEK, value: blobs.encryptedVek },
+ { key: StorageKeys.ACCOUNT_PUBLIC_KEY, value: blobs.accountPublicKey },
+ { key: StorageKeys.ENCRYPTED_ACCOUNT_PRIVATE_KEY, value: blobs.encryptedAccountPrivateKey },
+ { key: StorageKeys.ACCOUNT_PRIVATE_KEY, value: blobs.accountPrivateKey },
+ ]);
+ }
+
/**
* Resolve the key to actually use for a local additional unlock method (PIN, mobile QR), upgrading a pre-migration
* stored key (the old KEK) to the VEK when needed.
@@ -184,35 +183,112 @@ export class VaultKeyService {
}
/**
- * Given a key restored from an auxiliary unlock method (PIN, mobile QR), return the key to actually use and whether it was upgraded.
+ * Given a key restored from an auxiliary unlock method (PIN, mobile QR), return the key to actually use and
+ * whether it was upgraded: a stored key that decrypts the cached chain was the old KEK, and the chain's VEK
+ * supersedes it.
* @param storedKey - the key restored from the auxiliary unlock method
*/
private static async upgradeStoredKeyIfNeeded(storedKey: string): Promise<{ key: string; upgraded: boolean }> {
- const encryptedVek = await storage.getItem(StorageKeys.ENCRYPTED_VEK) as string | null;
- if (!encryptedVek) {
+ try {
+ const resolved = await VaultKeyService.resolveFromLocalCache(storedKey);
+ if (resolved.encryptedVek !== null && resolved.encryptionKey !== storedKey) {
+ return { key: resolved.encryptionKey, upgraded: true };
+ }
return { key: storedKey, upgraded: false };
+ } catch {
+ return { key: storedKey, upgraded: false };
+ }
+ }
+
+ /**
+ * Decrypt the locally cached blob chain with the given KEK, staging the session private key when the chain
+ * carries one. Falls back to the pre-encrypted VEK cache shape (a encrypted VEK alone), and to the derived key itself
+ * when nothing is cached (legacy account).
+ * @param derivedKeyBase64 - the password-derived key (the KEK)
+ */
+ private static async resolveFromLocalCache(derivedKeyBase64: string): Promise<ResolvedEncryptionKey> {
+ const encryptedAccountKey = (await storage.getItem(StorageKeys.ENCRYPTED_ACCOUNT_KEY)) as string | null;
+ const encryptedVek = (await storage.getItem(StorageKeys.ENCRYPTED_VEK)) as string | null;
+
+ if (encryptedAccountKey) {
+ const accountKey = await VaultKeyService.unwrapOrThrow(encryptedAccountKey, derivedKeyBase64);
+ const vek = encryptedVek ? await VaultKeyService.unwrapOrThrow(encryptedVek, accountKey) : accountKey;
+ await VaultKeyService.stageSessionPrivateKey(accountKey, (await storage.getItem(StorageKeys.ENCRYPTED_ACCOUNT_PRIVATE_KEY)) as string | null);
+ return { encryptionKey: vek, encryptedVek: encryptedAccountKey };
+ }
+
+ if (encryptedVek) {
+ // Pre-encrypted VEK cache: the VEK was encrypted directly with the KEK.
+ return { encryptionKey: await VaultKeyService.unwrapOrThrow(encryptedVek, derivedKeyBase64), encryptedVek };
}
+ return { encryptionKey: derivedKeyBase64, encryptedVek: null };
+ }
+
+ /**
+ * Decrypt a fresh server response's chain with the KEK: AK first, then the VEK (or the AK itself for a
+ * transitional account where AK ≡ VEK), staging the session private key when the account has a keypair.
+ * @param vaultKey - the server's vault key response
+ * @param derivedKeyBase64 - the password-derived KEK
+ */
+ private static async unwrapChainOrThrow(vaultKey: VaultKeyResponse, derivedKeyBase64: string): Promise<string> {
+ const accountKey = await VaultKeyService.unwrapOrThrow(vaultKey.encryptedAccountKey, derivedKeyBase64);
+ const vek = vaultKey.encryptedVek ? await VaultKeyService.unwrapOrThrow(vaultKey.encryptedVek, accountKey) : accountKey;
+ await VaultKeyService.stageSessionPrivateKey(accountKey, vaultKey.encryptedAccountPrivateKey ?? null);
+ return vek;
+ }
+
+ /**
+ * Decrypt the account private key with the AK into session storage, so pull/grant flows can decrypt shared
+ * VEKs. A chain without a keypair (transitional account) clears any stale session copy instead.
+ * @param accountKeyBase64 - the encrypted Account Key
+ * @param encryptedAccountPrivateKey - the account private key encrypted with the Account Key, or null when the account has none yet
+ */
+ private static async stageSessionPrivateKey(accountKeyBase64: string, encryptedAccountPrivateKey: string | null): Promise<void> {
+ if (!encryptedAccountPrivateKey) {
+ await storage.removeItem(StorageKeys.ACCOUNT_PRIVATE_KEY);
+ return;
+ }
try {
- const vek = await EncryptionUtility.unwrapVaultEncryptionKey(encryptedVek, storedKey);
- return { key: vek, upgraded: true };
+ const privateKeyJwk = await EncryptionUtility.symmetricDecrypt(encryptedAccountPrivateKey, accountKeyBase64);
+ await storage.setItem(StorageKeys.ACCOUNT_PRIVATE_KEY, privateKeyJwk);
} catch {
- return { key: storedKey, upgraded: false };
+ // A stale/corrupt private-key blob must not fail the unlock; grant decryption degrades until the next sync.
+ await storage.removeItem(StorageKeys.ACCOUNT_PRIVATE_KEY);
+ }
+ }
+
+ /**
+ * Persist a server vault-key response's encrypted blobs for offline unlock.
+ * @param vaultKey - the server's vault key response
+ */
+ private static async cacheVaultKeyBlobs(vaultKey: VaultKeyResponse): Promise<void> {
+ await storage.setItem(StorageKeys.ENCRYPTED_ACCOUNT_KEY, vaultKey.encryptedAccountKey);
+ if (vaultKey.encryptedVek) {
+ await storage.setItem(StorageKeys.ENCRYPTED_VEK, vaultKey.encryptedVek);
+ } else {
+ await storage.removeItem(StorageKeys.ENCRYPTED_VEK);
+ }
+ if (vaultKey.accountPublicKey && vaultKey.encryptedAccountPrivateKey) {
+ await storage.setItem(StorageKeys.ACCOUNT_PUBLIC_KEY, vaultKey.accountPublicKey);
+ await storage.setItem(StorageKeys.ENCRYPTED_ACCOUNT_PRIVATE_KEY, vaultKey.encryptedAccountPrivateKey);
+ } else {
+ await storage.removeItems([StorageKeys.ACCOUNT_PUBLIC_KEY, StorageKeys.ENCRYPTED_ACCOUNT_PRIVATE_KEY]);
}
}
/**
- * Unwrap an encrypted VEK, mapping an AES-GCM authentication failure onto the standard decrypt-failed error code so
- * existing wrong-password handling applies.
- * @param encryptedVek - base64(IV ‖ ciphertext ‖ tag) of the encrypted VEK
- * @param kekBase64 - the password-derived KEK
+ * Decrypt an encrypted key blob, mapping an AES-GCM authentication failure onto the standard decrypt-failed
+ * error code so existing wrong-password handling applies.
+ * @param encryptedKey - encrypted key blob
+ * @param decryptingKeyBase64 - the key that decrypts it (the KEK derived from the unlock method)
*/
- private static async unwrapOrThrow(encryptedVek: string, kekBase64: string): Promise<string> {
+ private static async unwrapOrThrow(encryptedKey: string, decryptingKeyBase64: string): Promise<string> {
try {
- return await EncryptionUtility.unwrapVaultEncryptionKey(encryptedVek, kekBase64);
+ return await EncryptionUtility.symmetricDecrypt(encryptedKey, decryptingKeyBase64);
} catch {
- // E-203: unwrap failed, which for the password key type means the entered password is wrong.
- throw new Error(formatErrorWithCode('Failed to unwrap vault encryption key', AppErrorCode.VAULT_DECRYPT_FAILED));
+ // E-203: decrypt failed, which for the password key type means the entered password is wrong.
+ throw new Error(formatErrorWithCode('Failed to decrypt vault encryption key', AppErrorCode.VAULT_DECRYPT_FAILED));
}
}
}