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.tsindex 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));}}}