diff --git a/browser/data-browser/src/helpers/agentStorage.test.ts b/browser/data-browser/src/helpers/agentStorage.test.ts index 9dc8e0fbf7..0e13a15f11 100644 --- a/browser/data-browser/src/helpers/agentStorage.test.ts +++ b/browser/data-browser/src/helpers/agentStorage.test.ts @@ -3,10 +3,15 @@ import { Agent } from '@tomic/react'; /** In-memory stand-in for IndexedDB, so we can inspect exactly what got stored. */ const store = new Map(); +/** Extra latency on every write, for tests that race a slow sign-in. */ +let writeDelayMs = 0; vi.mock('idb-keyval', () => ({ get: async (key: string) => store.get(key), - set: async (key: string, value: unknown) => void store.set(key, value), + set: async (key: string, value: unknown) => { + if (writeDelayMs) await new Promise(r => setTimeout(r, writeDelayMs)); + store.set(key, value); + }, del: async (key: string) => void store.delete(key), keys: async () => [...store.keys()], })); @@ -17,11 +22,13 @@ const { readPreviousIdentities, saveAgentToIDB, } = await import('./agentStorage'); +const { waitForSessionDbKey } = await import('./localDbKey'); const AGENT_IDB_KEY = 'atomic.agent'; const AGENT_FALLBACK_KEY = 'atomic.agent.fallback'; const SESSION_KEY_PREFIX = 'atomic.clientdb.session-key.'; const WRAPPED_KEY_PREFIX = 'atomic.clientdb.wrapped-key.'; +const WRAPPED_KEY_V2_PREFIX = 'atomic.clientdb.wrapped-key-v2.'; async function makeSecret(): Promise { const keys = await Agent.generateKeyPair(); @@ -49,6 +56,22 @@ describe('agent key storage', () => { beforeEach(() => store.clear()); afterEach(() => store.clear()); + it('announces a sign-in before its first await, so the database opener waits for it', async () => { + const secret = await makeSecret(); + const order: string[] = []; + // A sign-in slower than the opener's own patience, as one that loads the + // wasm bundle on a cold page is. + writeDelayMs = 300; + // What callers do: set the agent (which starts the opener), then save. + const saving = saveAgentToIDB(secret).then(() => order.push('saved')); + const opening = waitForSessionDbKey('atomic:agent:test', 100).then(() => + order.push('opened'), + ); + await Promise.all([saving, opening]).finally(() => (writeDelayMs = 0)); + + expect(order).toEqual(['saved', 'opened']); + }); + it('never stores a readable private key where Web Crypto is available', async () => { await saveAgentToIDB(await makeSecret()); @@ -94,6 +117,7 @@ describe('agent key storage', () => { store.set(AGENT_FALLBACK_KEY, { privateKey: 'x', subject: 'y' }); store.set(`${SESSION_KEY_PREFIX}fingerprint`, 'session-copy'); store.set(`${WRAPPED_KEY_PREFIX}fingerprint`, 'wrapped-copy'); + store.set(`${WRAPPED_KEY_V2_PREFIX}fingerprint`, 'wrapped-copy-v2'); await saveAgentToIDB(undefined); @@ -105,6 +129,7 @@ describe('agent key storage', () => { // ...while the wrapped copy survives, so the owning agent's cache becomes // readable again on their next sign-in rather than being wiped. expect(store.has(`${WRAPPED_KEY_PREFIX}fingerprint`)).toBe(true); + expect(store.has(`${WRAPPED_KEY_V2_PREFIX}fingerprint`)).toBe(true); }); }); diff --git a/browser/data-browser/src/helpers/agentStorage.ts b/browser/data-browser/src/helpers/agentStorage.ts index 196078234b..8ba597f229 100644 --- a/browser/data-browser/src/helpers/agentStorage.ts +++ b/browser/data-browser/src/helpers/agentStorage.ts @@ -1,12 +1,18 @@ import { Agent, + decodeSecret, SubtleCryptoProvider, JSCryptoProvider, legacySubjectFromSecret, } from '@tomic/react'; import { del, get, set } from 'idb-keyval'; import { adoptAgentOnDevice } from './adoptAgent'; -import { clearSessionDbKeys, ensureDbKeyOnSignIn } from './localDbKey'; +import { + clearSessionDbKeys, + ensureDbKeyOnSignIn, + trackDbKeySignIn, + type SignInCredentials, +} from './localDbKey'; const AGENT_IDB_KEY = 'atomic.agent'; @@ -177,7 +183,15 @@ export async function saveAgentToIDB( } if (typeof keyPairOrSecret === 'string') { - await storeSecret(keyPairOrSecret); + const stored = storeSecret(keyPairOrSecret); + // Announced before anything is awaited: callers often set the agent first, + // and the database opener that event starts must know a sign-in is about + // to deliver this agent's key (see `waitForSessionDbKey`). + const signingIn = subjectOfSecret(keyPairOrSecret); + + if (signingIn) trackDbKeySignIn(signingIn, stored); + + await stored; // The device now holds this agent; its node should sign as this agent too. // Best-effort and last, so a node that isn't up yet can't block sign-in. @@ -212,6 +226,18 @@ export async function saveAgentToIDB( } satisfies StoredAgent); } +/** + * The agent subject a secret signs in as (the same one `storeSecret` stores), + * or undefined when the secret cannot be read. + */ +function subjectOfSecret(secret: string): string | undefined { + try { + return decodeSecret(secret).subject; + } catch { + return undefined; + } +} + /** Persist the agent's key, preferring a non-extractable keypair. */ async function storeSecret(secret: string): Promise { // The secret is a base64-encoded JSON containing { privateKey, subject }. @@ -245,7 +271,10 @@ async function storeSecret(secret: string): Promise { } satisfies StoredAgent); await del(AGENT_FALLBACK_KEY); - await ensureLocalDbKey(resolvedSubject, decoded.privateKey); + await ensureLocalDbKey(resolvedSubject, { + privateKey: decoded.privateKey, + vaultProof, + }); return; } catch { @@ -269,7 +298,10 @@ async function storeSecret(secret: string): Promise { // Drop a keypair from a previous account, so it can't be loaded instead. await del(AGENT_IDB_KEY); - await ensureLocalDbKey(newSubject, decoded.privateKey); + await ensureLocalDbKey(newSubject, { + privateKey: decoded.privateKey, + vaultProof, + }); } } @@ -280,10 +312,10 @@ async function storeSecret(secret: string): Promise { */ async function ensureLocalDbKey( subject: string, - privateKey: string, + credentials: SignInCredentials, ): Promise { try { - await ensureDbKeyOnSignIn(subject, privateKey); + await ensureDbKeyOnSignIn(subject, credentials); } catch (e) { console.warn('Failed to prepare local database key:', e); } diff --git a/browser/data-browser/src/helpers/initClientDb.ts b/browser/data-browser/src/helpers/initClientDb.ts index 338c776b34..b2559503f1 100644 --- a/browser/data-browser/src/helpers/initClientDb.ts +++ b/browser/data-browser/src/helpers/initClientDb.ts @@ -8,6 +8,7 @@ import { getOrCreateSessionDbKey, getSessionDbKey, hasWrappedDbKey, + waitForSessionDbKey, } from './localDbKey'; import { wasmJsUrl } from './wasmUrls'; @@ -109,7 +110,7 @@ async function dbNameForAgent(agentSubject: string): Promise { * The encryption key for an agent's database, preferring the active-session * record. A wrapped record without a session record means a sign-in is * unwrapping it right now (`ensureDbKeyOnSignIn` runs alongside the - * AgentChanged event) — wait for that instead of generating a fresh key that + * AgentChanged event, announced by `trackDbKeySignIn`) — wait for that instead of generating a fresh key that * couldn't open the existing encrypted file. * * Returns null when there is a wrapped record but no session key, which means @@ -126,12 +127,9 @@ async function resolveDbKey(agentSubject: string): Promise { if (existing) return existing; if (await hasWrappedDbKey(agentSubject)) { - for (let attempt = 0; attempt < 30; attempt++) { - await new Promise(resolve => setTimeout(resolve, 100)); - const key = await getSessionDbKey(agentSubject); + const key = await waitForSessionDbKey(agentSubject); - if (key) return key; - } + if (key) return key; // The sign-in never delivered the key (e.g. an agent restored from a // non-extractable keypair, where no secret enters JS). diff --git a/browser/data-browser/src/helpers/localDbKey.persistence.test.ts b/browser/data-browser/src/helpers/localDbKey.persistence.test.ts index e50f966b37..76c7a51529 100644 --- a/browser/data-browser/src/helpers/localDbKey.persistence.test.ts +++ b/browser/data-browser/src/helpers/localDbKey.persistence.test.ts @@ -15,14 +15,78 @@ vi.mock('idb-keyval', () => ({ }, })); import { + agentDbFingerprint, + clearSessionDbKeys, + deriveKek, + ensureDbKeyOnSignIn, + generateDbKey, getOrCreateSessionDbKey, getSessionDbKey, - ensureDbKeyOnSignIn, - clearSessionDbKeys, + hasWrappedDbKey, + trackDbKeySignIn, + waitForSessionDbKey, + wrapDbKey, + type DbKeyWrapOps, + type SignInCredentials, } from './localDbKey'; + const subject = 'did:ad:agent:concurrent-key-test'; -const privateKey = btoa(String.fromCharCode(...new Uint8Array(32).fill(7))); + +function b64url(bytes: Uint8Array): string { + return btoa(String.fromCharCode(...bytes)) + .replace(/\+/g, '-') + .replace(/\//g, '_') + .replace(/=+$/, ''); +} + +const credentials: SignInCredentials = { + privateKey: b64url(new Uint8Array(32).fill(7)), + vaultProof: b64url(new Uint8Array(64).fill(3)), +}; +const otherCredentials: SignInCredentials = { + privateKey: b64url(new Uint8Array(32).fill(8)), + vaultProof: b64url(new Uint8Array(64).fill(4)), +}; + +/** + * Stand-in for the wasm `vaultWrapKey` / `vaultUnwrapKey`: keyed on the proof + * and refusing any other, which is the property these tests depend on. The + * real envelope is covered by `secret_envelope.rs` and `wasm/tests/vault.rs`. + */ +const fakeOps: DbKeyWrapOps = { + wrap: (dbKey, proof) => + JSON.stringify({ + format_version: 2, + key: Array.from(dbKey), + proof: Array.from(proof), + }), + unwrap: (envelope, proof) => { + const parsed = JSON.parse(envelope); + + if (parsed.proof.join() !== Array.from(proof).join()) { + throw new Error('no wrapper in this envelope accepted that credential'); + } + + return new Uint8Array(parsed.key); + }, +}; +const withWasm = async () => fakeOps; + +const withoutWasm = async (): Promise => { + throw new Error('failed to fetch /wasm/atomic_wasm.js'); +}; + +async function recordKeys() { + const fingerprint = await agentDbFingerprint(subject); + + return { + v1: `atomic.clientdb.wrapped-key.${fingerprint}`, + v2: `atomic.clientdb.wrapped-key-v2.${fingerprint}`, + }; +} + beforeEach(() => records.clear()); + describe('persistent local database keys', () => { it('concurrent database openers receive the same persisted key', async () => { const keys = await Promise.all( @@ -30,14 +94,161 @@ describe('persistent local database keys', () => { ); for (const key of keys) expect(key).toEqual(await getSessionDbKey(subject)); }); + it('concurrent sign-in and database initialization preserve the key across sign-out', async () => { const [openedWith, signedInWith] = await Promise.all([ getOrCreateSessionDbKey(subject), - ensureDbKeyOnSignIn(subject, privateKey), - ensureDbKeyOnSignIn(subject, privateKey), + ensureDbKeyOnSignIn(subject, credentials, withWasm), + ensureDbKeyOnSignIn(subject, credentials, withWasm), ]); expect(signedInWith).toEqual(openedWith); await clearSessionDbKeys(); - expect(await ensureDbKeyOnSignIn(subject, privateKey)).toEqual(openedWith); + expect(await ensureDbKeyOnSignIn(subject, credentials, withWasm)).toEqual( + openedWith, + ); + }); + + it('writes new keys only in the v2 envelope scheme', async () => { + const { v1, v2 } = await recordKeys(); + await ensureDbKeyOnSignIn(subject, credentials, withWasm); + + expect(records.has(v1)).toBe(false); + expect(records.get(v2)).toMatchObject({ version: 2 }); + expect(await hasWrappedDbKey(subject)).toBe(true); + }); + + it('opens a legacy v1 record, rewraps it as v2 and keeps v1 for rollbacks', async () => { + const { v1, v2 } = await recordKeys(); + const legacyKey = generateDbKey(); + const legacyRecord = await wrapDbKey( + await deriveKek(credentials.privateKey, subject), + legacyKey, + ); + records.set(v1, legacyRecord); + + // Signed out: no session key, only the old-format wrapped record. + expect(await ensureDbKeyOnSignIn(subject, credentials, withWasm)).toEqual( + legacyKey, + ); + expect(await getSessionDbKey(subject)).toEqual(legacyKey); + expect(records.get(v1)).toEqual(legacyRecord); + expect(records.get(v2)).toMatchObject({ version: 2 }); + + // The next sign-in reads the v2 record, even with v1 gone. + records.delete(v1); + await clearSessionDbKeys(); + expect(await ensureDbKeyOnSignIn(subject, credentials, withWasm)).toEqual( + legacyKey, + ); + }); + + it('does not hand the key to a different secret', async () => { + const original = await ensureDbKeyOnSignIn(subject, credentials, withWasm); + await clearSessionDbKeys(); + + expect( + await ensureDbKeyOnSignIn(subject, otherCredentials, withWasm), + ).not.toEqual(original); + }); + + it('does not open a legacy v1 record with a different secret', async () => { + const { v1 } = await recordKeys(); + const legacyKey = generateDbKey(); + records.set( + v1, + await wrapDbKey( + await deriveKek(credentials.privateKey, subject), + legacyKey, + ), + ); + + expect( + await ensureDbKeyOnSignIn(subject, otherCredentials, withWasm), + ).not.toEqual(legacyKey); + }); + + it('keeps a v2 record when wasm cannot load, and opens it on the next try', async () => { + const { v2 } = await recordKeys(); + const original = await ensureDbKeyOnSignIn(subject, credentials, withWasm); + const stored = records.get(v2); + await clearSessionDbKeys(); + + await expect( + ensureDbKeyOnSignIn(subject, credentials, withoutWasm), + ).rejects.toThrow(/wasm/); + expect(records.get(v2)).toEqual(stored); + expect(await getSessionDbKey(subject)).toBeUndefined(); + + expect(await ensureDbKeyOnSignIn(subject, credentials, withWasm)).toEqual( + original, + ); + }); + + it('falls back to a v1 record without wasm, then migrates it', async () => { + const { v1, v2 } = await recordKeys(); + const original = await ensureDbKeyOnSignIn( + subject, + credentials, + withoutWasm, + ); + + expect(records.get(v1)).toMatchObject({ version: 1 }); + expect(records.has(v2)).toBe(false); + + await clearSessionDbKeys(); + expect(await ensureDbKeyOnSignIn(subject, credentials, withWasm)).toEqual( + original, + ); + expect(records.get(v2)).toMatchObject({ version: 2 }); + }); + + it('recovers from a corrupt v2 record through the v1 record', async () => { + const { v1, v2 } = await recordKeys(); + const legacyKey = generateDbKey(); + records.set( + v1, + await wrapDbKey( + await deriveKek(credentials.privateKey, subject), + legacyKey, + ), + ); + records.set(v2, { version: 2, envelope: '{"not":"an envelope"}' }); + + expect(await ensureDbKeyOnSignIn(subject, credentials, withWasm)).toEqual( + legacyKey, + ); + expect( + fakeOps.unwrap( + (records.get(v2) as { envelope: string }).envelope, + new Uint8Array(64).fill(3), + ), + ).toEqual(legacyKey); + }); + + it('a database opener waits for a sign-in whose wasm loads slowly', async () => { + const original = await ensureDbKeyOnSignIn(subject, credentials, withWasm); + await clearSessionDbKeys(); + + // Signing in again after sign-out: the wrapped record is there and the + // session key is not. The app attaches the database as soon as the agent + // is set, while the sign-in is still fetching the wasm bundle it needs to + // unwrap the v2 record. On a cold page that takes seconds, longer than the + // opener's own patience (scaled down here). + const slowWasm = () => + new Promise(resolve => + setTimeout(() => resolve(fakeOps), 600), + ); + const signIn = ensureDbKeyOnSignIn(subject, credentials, slowWasm); + trackDbKeySignIn(subject, signIn); + + expect(await waitForSessionDbKey(subject, 200)).toEqual(original); + expect(await signIn).toEqual(original); + }); + + it('a database opener gives up without a sign-in in flight', async () => { + await ensureDbKeyOnSignIn(subject, credentials, withWasm); + await clearSessionDbKeys(); + + expect(await waitForSessionDbKey(subject, 200)).toBeUndefined(); }); }); diff --git a/browser/data-browser/src/helpers/localDbKey.ts b/browser/data-browser/src/helpers/localDbKey.ts index 13a0bcafb5..bd372ce9bc 100644 --- a/browser/data-browser/src/helpers/localDbKey.ts +++ b/browser/data-browser/src/helpers/localDbKey.ts @@ -10,24 +10,39 @@ import { del, get, keys, set, update } from 'idb-keyval'; * 32 bytes. Exists only while that agent is the device's active session and * is deleted on sign-out. This is what lets a page reload reopen the * encrypted DB without re-entering the secret. - * - **Wrapped record** (`atomic.clientdb.wrapped-key.`): the - * DbKey encrypted (AES-GCM) under a KEK derived from the agent's private - * key. Survives sign-out; only someone who signs in with the agent secret - * can unwrap it, so the same agent regains their cache on re-login. + * - **Wrapped record**: the DbKey encrypted under the agent's credential. + * Survives sign-out; only someone who signs in with the agent secret can + * unwrap it, so the same agent regains their cache on re-login. + * + * ## Wrapped record versions + * + * - **v2** (`atomic.clientdb.wrapped-key-v2.`, written today): a + * `SecretEnvelope` from `atomic_lib::vault::secret_envelope` with one + * agent-secret wrapper — the same scheme, KEK derivation (BLAKE3 over the + * agent's vault proof) and XChaCha20-Poly1305 AEAD as the drive vault keys + * `vaultWrapKey` stores in the control plane. Needs the wasm bundle. + * - **v1** (`atomic.clientdb.wrapped-key.`, legacy): AES-GCM + * under an HKDF-SHA256 KEK derived from the raw Ed25519 private key. Read on + * sign-in and rewrapped into v2. Never deleted by the migration, so a + * rollback to a build that only knows v1 still opens the cache; it is only + * written as a fallback when the wasm bundle cannot load, so the DbKey is + * never left without a wrapped copy. */ const SESSION_KEY_PREFIX = 'atomic.clientdb.session-key.'; const WRAPPED_KEY_PREFIX = 'atomic.clientdb.wrapped-key.'; +const WRAPPED_KEY_V2_PREFIX = 'atomic.clientdb.wrapped-key-v2.'; const DB_KEY_BYTES = 32; const IV_BYTES = 12; const WRAP_FORMAT_VERSION = 1; +const WRAP_FORMAT_VERSION_V2 = 2; -// KEK derivation domain separation. Bump the salt version if the scheme ever -// changes; old wrapped records then simply fail to unwrap and are regenerated. +// v1 KEK derivation domain separation. Frozen: v1 is read-only legacy. const KEK_SALT = 'atomic.clientdb.kek.v1'; const KEK_INFO_PREFIX = 'clientdb-key-wrap:'; +/** Legacy v1 wrapped record (AES-GCM). */ export interface WrappedDbKeyRecord { version: number; /** AES-GCM IV, base64. */ @@ -36,6 +51,30 @@ export interface WrappedDbKeyRecord { wrapped: string; } +/** v2 wrapped record: a `SecretEnvelope` JSON with an agent-secret wrapper. */ +export interface WrappedDbKeyRecordV2 { + version: 2; + envelope: string; +} + +/** + * The wasm envelope operations v2 records use: `vaultWrapKey` / + * `vaultUnwrapKey`, the same calls that wrap drive vault keys. + */ +export interface DbKeyWrapOps { + wrap(dbKey: Uint8Array, vaultProof: Uint8Array): string; + /** Throws when the proof does not open the envelope. */ + unwrap(envelope: string, vaultProof: Uint8Array): Uint8Array; +} + +/** What a sign-in has in hand to open (or create) the wrapped record. */ +export interface SignInCredentials { + /** The raw Ed25519 private key, base64url; opens legacy v1 records. */ + privateKey: string; + /** The agent's vault proof (`Agent.vaultProofFromSecret`), base64url. */ + vaultProof: string; +} + function bytesToBase64(bytes: Uint8Array): string { let binary = ''; @@ -99,7 +138,7 @@ export async function agentDbFingerprint( } /** - * Derive the key-encryption-key for wrapping an agent's DbKey: HKDF-SHA256 + * Legacy v1: derive the key-encryption-key for wrapping an agent's DbKey: HKDF-SHA256 * over the agent's raw Ed25519 private key, bound to the agent subject via * the info parameter. */ @@ -129,7 +168,10 @@ export async function deriveKek( ); } -/** Encrypt a DbKey under the KEK, producing the persistable wrapped record. */ +/** + * Legacy v1: encrypt a DbKey under the KEK. Only written when the wasm bundle + * that v2 needs cannot load. + */ export async function wrapDbKey( kek: CryptoKey, dbKey: Uint8Array, @@ -151,7 +193,7 @@ export async function wrapDbKey( } /** - * Decrypt a wrapped record back into the raw DbKey. Throws on a wrong KEK + * Legacy v1: decrypt a wrapped record back into the raw DbKey. Throws on a wrong KEK * (AES-GCM auth-tag failure) or a malformed record. */ export async function unwrapDbKey( @@ -181,11 +223,14 @@ export function generateDbKey(): Uint8Array { return randomBytes(DB_KEY_BYTES); } -/** Whether a durable wrapped DbKey record exists for this agent. */ +/** Whether a durable wrapped DbKey record (either version) exists. */ export async function hasWrappedDbKey(agentSubject: string): Promise { const fingerprint = await agentDbFingerprint(agentSubject); - return (await get(WRAPPED_KEY_PREFIX + fingerprint)) !== undefined; + return ( + (await get(WRAPPED_KEY_V2_PREFIX + fingerprint)) !== undefined || + (await get(WRAPPED_KEY_PREFIX + fingerprint)) !== undefined + ); } /** Raw DbKey for the active session, or undefined if none stored. */ @@ -199,6 +244,64 @@ export async function getSessionDbKey( | undefined; } +/** + * Sign-ins that are preparing an agent's DbKey right now, by agent subject. + * Settles (never rejects) when that sign-in is done, whatever its outcome. + */ +const signInsInFlight = new Map>(); + +/** + * Announce that `work` — a sign-in that ends in {@link ensureDbKeyOnSignIn} — + * will put this agent's session key in place, so a database opener waits for + * it instead of giving up. Call it before the first `await` of the sign-in: + * the opener runs as soon as the agent is set, which can be before the + * sign-in even starts. + */ +export function trackDbKeySignIn( + agentSubject: string, + work: Promise, +): void { + const settled = work.then( + () => undefined, + () => undefined, + ); + signInsInFlight.set(agentSubject, settled); + void settled.then(() => { + if (signInsInFlight.get(agentSubject) === settled) { + signInsInFlight.delete(agentSubject); + } + }); +} + +/** + * The session key for a database whose wrapped record exists but whose + * session record does not yet: a sign-in is unwrapping it. Waits for a sign-in + * announced through {@link trackDbKeySignIn} however long it takes — a v2 + * record needs the wasm bundle, which on a cold page takes seconds — and + * otherwise polls for up to `timeoutMs` (a sign-in in another tab, or one that + * was not announced). Undefined when no key appeared. + */ +export async function waitForSessionDbKey( + agentSubject: string, + timeoutMs = 3_000, +): Promise { + for (let waited = 0; waited < timeoutMs; waited += 100) { + const inFlight = signInsInFlight.get(agentSubject); + + if (inFlight) { + await inFlight; + } else { + await new Promise(resolve => setTimeout(resolve, 100)); + } + + const key = await getSessionDbKey(agentSubject); + + if (key) return key; + } + + return undefined; +} + /** * Get the existing session key or generate+store a fresh one (used when a DB * must open before any secret is available). @@ -225,40 +328,181 @@ export async function getOrCreateSessionDbKey( return dbKey; } +function decodeVaultProof(vaultProof: string): Uint8Array { + const proof = base64urlToBytes(vaultProof); + + if (proof.length !== 64) { + throw new Error( + `Expected a 64-byte vault proof, got ${proof.length} bytes.`, + ); + } + + return proof; +} + +/** + * Sign-in awaits this, so a wasm fetch that never settles must not hang it. + * Timing out counts as "wasm did not load": nothing is discarded. + */ +const WRAP_OPS_LOAD_TIMEOUT_MS = 20_000; + +function withTimeout(promise: Promise, ms: number): Promise { + return new Promise((resolve, reject) => { + const timer = setTimeout( + () => reject(new Error(`timed out after ${ms}ms`)), + ms, + ); + + promise.then( + value => { + clearTimeout(timer); + resolve(value); + }, + error => { + clearTimeout(timer); + reject(error); + }, + ); + }); +} + +async function loadDefaultWrapOps(): Promise { + const { loadVaultKeyOps } = await import('./managed/vaultKeyOps'); + const ops = await loadVaultKeyOps(); + + return { wrap: ops.vaultWrapKey, unwrap: ops.vaultUnwrapKey }; +} + +/** + * Wrap into v2, and prove the envelope opens to the same key before it is + * stored: a record that cannot be read back is worse than none. + */ +function wrapDbKeyV2( + ops: DbKeyWrapOps, + proof: Uint8Array, + dbKey: Uint8Array, +): WrappedDbKeyRecordV2 { + const envelope = ops.wrap(dbKey, proof); + const reopened = ops.unwrap(envelope, proof); + + if ( + reopened.length !== dbKey.length || + reopened.some((byte, i) => byte !== dbKey[i]) + ) { + throw new Error('v2 DbKey envelope did not reopen to the same key'); + } + + return { version: WRAP_FORMAT_VERSION_V2, envelope }; +} + /** * Called at sign-in, when the raw secret is available. * - * - A wrapped record exists → unwrap it and write it as the session record, - * restoring access to the cache from before sign-out. + * - A v2 record exists → unwrap it into the session record. + * - Only a v1 record exists → unwrap it, then rewrap it as v2 (the v1 record + * stays for rollbacks). * - Only a session record exists (pre-feature upgrade) → wrap it so it also * survives the next sign-out. - * - Neither exists → generate a fresh DbKey and store both records. + * - Nothing exists → generate a fresh DbKey and store both records. * - * A wrapped record that fails to unwrap (corrupt, or wrapped under a - * different key) is discarded and replaced via the generate path — the cache - * it protected is unreadable either way. + * A record that fails to unwrap (corrupt, or wrapped under a different key) is + * discarded and the next version down is tried; with none left a fresh key is + * generated — the cache it protected is unreadable either way. A v2 record is + * never discarded because the wasm bundle failed to load: that throws and + * leaves every record in place, so the next sign-in can retry. */ export async function ensureDbKeyOnSignIn( agentSubject: string, - privateKeyBase64url: string, + credentials: SignInCredentials, + loadWrapOps: () => Promise = loadDefaultWrapOps, ): Promise { const fingerprint = await agentDbFingerprint(agentSubject); - const kek = await deriveKek(privateKeyBase64url, agentSubject); - const wrappedRecord = (await get(WRAPPED_KEY_PREFIX + fingerprint)) as - | WrappedDbKeyRecord - | undefined; + const proof = decodeVaultProof(credentials.vaultProof); + const v2Key = WRAPPED_KEY_V2_PREFIX + fingerprint; + const v1Key = WRAPPED_KEY_PREFIX + fingerprint; + + let ops: DbKeyWrapOps | undefined; + let opsError: unknown; + + try { + ops = await withTimeout(loadWrapOps(), WRAP_OPS_LOAD_TIMEOUT_MS); + } catch (e) { + opsError = e; + } + + const v2Record = (await get(v2Key)) as WrappedDbKeyRecordV2 | undefined; + + if (v2Record) { + if (!ops) { + throw new Error( + 'Cannot unwrap the local database key: the wasm bundle did not load.', + { cause: opsError }, + ); + } - if (wrappedRecord) { try { - const dbKey = await unwrapDbKey(kek, wrappedRecord); + const dbKey = ops.unwrap(v2Record.envelope, proof); + + if (dbKey.length !== DB_KEY_BYTES) { + throw new Error('Wrapped DbKey envelope held the wrong length'); + } + await set(SESSION_KEY_PREFIX + fingerprint, dbKey); return dbKey; } catch (e) { - console.warn('Discarding wrapped DbKey record that failed to unwrap:', e); - await del(WRAPPED_KEY_PREFIX + fingerprint); + console.warn('Discarding v2 DbKey record that failed to unwrap:', e); + await del(v2Key); } - } else { + } + + if (!ops) { + console.warn( + 'Local database key falls back to the legacy wrapping: wasm did not load.', + opsError, + ); + } + + // Only v1 needs it, and it needs WebCrypto: derived on demand. + const kek = () => deriveKek(credentials.privateKey, agentSubject); + + /** Store the wrapped copy: v2 when possible, v1 only without wasm. */ + const persistWrapped = async (dbKey: Uint8Array) => { + if (ops) { + await set(v2Key, wrapDbKeyV2(ops, proof, dbKey)); + } else { + await set(v1Key, await wrapDbKey(await kek(), dbKey)); + } + }; + + const v1Record = (await get(v1Key)) as WrappedDbKeyRecord | undefined; + + if (v1Record) { + let dbKey: Uint8Array | undefined; + + try { + dbKey = await unwrapDbKey(await kek(), v1Record); + } catch (e) { + console.warn('Discarding v1 DbKey record that failed to unwrap:', e); + await del(v1Key); + } + + if (dbKey) { + // Session first: the cache opens even if the rewrap below fails. + await set(SESSION_KEY_PREFIX + fingerprint, dbKey); + + if (ops) { + try { + await set(v2Key, wrapDbKeyV2(ops, proof, dbKey)); + } catch (e) { + // The v1 record still holds the key; the next sign-in retries. + console.warn('Failed to rewrap DbKey as v2:', e); + } + } + + return dbKey; + } + } else if (!v2Record) { // Pre-feature upgrade: a session key exists from before wrapped records // did. Wrap it now so this agent's cache survives a sign-out. const sessionKey = (await get(SESSION_KEY_PREFIX + fingerprint)) as @@ -266,17 +510,14 @@ export async function ensureDbKeyOnSignIn( | undefined; if (sessionKey) { - await set( - WRAPPED_KEY_PREFIX + fingerprint, - await wrapDbKey(kek, sessionKey), - ); + await persistWrapped(sessionKey); return sessionKey; } } const dbKey = await getOrCreateSessionDbKey(agentSubject); - await set(WRAPPED_KEY_PREFIX + fingerprint, await wrapDbKey(kek, dbKey)); + await persistWrapped(dbKey); return dbKey; } diff --git a/browser/data-browser/src/helpers/managed/vaultKeyOps.ts b/browser/data-browser/src/helpers/managed/vaultKeyOps.ts index 6bed076dd6..5c3676b7b7 100644 --- a/browser/data-browser/src/helpers/managed/vaultKeyOps.ts +++ b/browser/data-browser/src/helpers/managed/vaultKeyOps.ts @@ -1,3 +1,4 @@ +import { wasmBinaryUrl, wasmJsUrl } from '../wasmUrls'; import type { VaultKeyOps } from './vault'; /** @@ -12,7 +13,7 @@ import type { VaultKeyOps } from './vault'; * store has exactly one writer. */ type VaultWasmModule = { - default: () => Promise; + default: (init?: { module_or_path: string }) => Promise; vaultGenerateKey: () => Uint8Array; vaultProofMessage: () => Uint8Array; vaultWrapKey: (driveKey: Uint8Array, agentSecret: Uint8Array) => string; @@ -24,14 +25,21 @@ let modulePromise: Promise | null = null; async function loadVaultWasm(): Promise { if (!modulePromise) { modulePromise = (async () => { - const url = `${window.location.origin}/wasm/atomic_wasm.js`; + // Versioned like every other load of this pair (see `wasmUrls.ts`): + // sign-in now waits on this, and an unversioned url can be served an + // older build's cached glue or binary. const wasmModule = (await import( - /* @vite-ignore */ url + /* @vite-ignore */ wasmJsUrl() )) as VaultWasmModule; - await wasmModule.default(); + await wasmModule.default({ module_or_path: wasmBinaryUrl() }); return wasmModule; - })(); + })().catch(error => { + // A failed fetch must not stick for the page's lifetime: the next + // sign-in retries it. + modulePromise = null; + throw error; + }); } return modulePromise; diff --git a/browser/e2e/tests/integration-workspace.spec.ts b/browser/e2e/tests/integration-workspace.spec.ts index c71f5df41a..0558f18377 100644 --- a/browser/e2e/tests/integration-workspace.spec.ts +++ b/browser/e2e/tests/integration-workspace.spec.ts @@ -1,7 +1,84 @@ -import { test, expect } from '@playwright/test'; +import { test, expect, type Page } from '@playwright/test'; import { before, openWorkspaceDialog, waitForSynced } from './test-utils'; test.beforeEach(before); +/** + * Diagnostics for the local-database key (#1767): which `keyval-store` records + * exist, never their values. Session keys are reduced to a 4-byte SHA-256 + * prefix, enough to see whether the key changed across a reload. Logged and + * attached so a CI failure shows which records were there. + */ +async function dumpDbKeyRecords(page: Page, label: string): Promise { + const report = await page.evaluate(async () => { + const hex = (bytes: ArrayBuffer | Uint8Array, length: number) => + Array.from(new Uint8Array(bytes).slice(0, length)) + .map(byte => byte.toString(16).padStart(2, '0')) + .join(''); + const sha256 = (bytes: Uint8Array) => + crypto.subtle.digest('SHA-256', new Uint8Array(bytes)); + const subject = window.store?.getAgent()?.subject; + const fingerprint = subject + ? hex(await sha256(new TextEncoder().encode(subject)), 8) + : undefined; + const records = await new Promise<[string, unknown][]>( + (resolve, reject) => { + const open = indexedDB.open('keyval-store'); + open.onerror = () => reject(open.error); + + open.onsuccess = () => { + const found: [string, unknown][] = []; + const cursor = open.result + .transaction('keyval') + .objectStore('keyval') + .openCursor(); + cursor.onerror = () => reject(cursor.error); + + cursor.onsuccess = () => { + const current = cursor.result; + + if (!current) { + open.result.close(); + resolve(found); + + return; + } + + found.push([String(current.key), current.value]); + current.continue(); + }; + }; + }, + ); + const keys: string[] = []; + + for (const [key, value] of records) { + keys.push( + key.startsWith('atomic.clientdb.session-key.') && + value instanceof Uint8Array + ? `${key} (sha256 ${hex(await sha256(value), 4)})` + : key, + ); + } + + const hasWrappedDbKey = + !!fingerprint && + records.some( + ([key]) => + key === `atomic.clientdb.wrapped-key-v2.${fingerprint}` || + key === `atomic.clientdb.wrapped-key.${fingerprint}`, + ); + + return { subject, fingerprint, hasWrappedDbKey, keys }; + }); + const text = JSON.stringify({ label, ...report }, null, 2); + // oxlint-disable-next-line no-console -- meant for the CI log + console.log(`[db-key diagnostics] ${text}`); + await test.info().attach(`db-key records: ${label}`, { + body: text, + contentType: 'application/json', + }); +} + test('workspace owns its views and links to separate connection settings', async ({ page, }) => { @@ -254,6 +331,7 @@ test('workspace owns its views and links to separate connection settings', async test('workspace starts automation chat without requiring a connection', async ({ page, }) => { + await dumpDbKeyRecords(page, 'after devDrive'); const table = await page.evaluate(async () => { const resource = await window.store!.newResource({ parent: window.store!.getDrive(), @@ -308,6 +386,7 @@ test('workspace starts automation chat without requiring a connection', async ({ new URL(`/app/show?subject=${encodeURIComponent(automation)}`, page.url()) .href, ); + await dumpDbKeyRecords(page, 'after reload to the automation'); await expect( page.getByRole('tab', { name: 'Automation', exact: true }), ).toBeVisible(); diff --git a/browser/e2e/tests/signout-signin-data.spec.ts b/browser/e2e/tests/signout-signin-data.spec.ts index ed6c812bba..0febcfec29 100644 --- a/browser/e2e/tests/signout-signin-data.spec.ts +++ b/browser/e2e/tests/signout-signin-data.spec.ts @@ -12,7 +12,7 @@ * 1. the resource itself — is the content still readable by the re-signed-in * agent at all; * 2. the local ClientDb encryption key — sign-out deletes the session copy of - * the DbKey and keeps a wrapped copy that only the agent's private key can + * the DbKey and keeps a wrapped copy that only the agent's secret can * unwrap (see `helpers/localDbKey.ts`). If sign-in fails to unwrap it, the * worker generates a fresh key, the old encrypted OPFS file can no longer * be opened, and the cache silently empties even though the server still @@ -66,7 +66,9 @@ const test = base.extend({ }); const SESSION_KEY_PREFIX = 'atomic.clientdb.session-key.'; -const WRAPPED_KEY_PREFIX = 'atomic.clientdb.wrapped-key.'; +// New sign-ins write only the v2 (secret envelope) record; the v1 prefix +// `atomic.clientdb.wrapped-key.` is legacy. +const WRAPPED_KEY_PREFIX = 'atomic.clientdb.wrapped-key-v2.'; /** * Read raw `idb-keyval` records straight out of IndexedDB. diff --git a/lib/src/vault/mod.rs b/lib/src/vault/mod.rs index 028c3a220c..9993d14657 100644 --- a/lib/src/vault/mod.rs +++ b/lib/src/vault/mod.rs @@ -1,14 +1,12 @@ //! Shared crypto for client-side envelope encryption: a random DEK encrypts -//! the protected secret once, wrapped independently per enrolled credential -//! (a generated recovery code today; a WebAuthn PRF wrapper is a planned -//! addition). Consumed today by atomic-saas's recovery-secret backup -//! (`planning/BACKUP_SECURITY.md`); the same module is the intended home for -//! the drive-level Cloud Vault key material later -//! (`planning/CLOUD_VAULT_ARCHITECTURE.md`, Phase 0). +//! the protected secret once, wrapped independently per credential +//! (`secret_envelope`: the agent's vault proof, or a node key). `keys` also +//! carries the Argon2id KDF that the browser's recovery-code backup +//! (`recovery.ts`, stored by atomic-saas) loads through `atomic-wasm`; that +//! backup's envelope format itself lives in TypeScript. //! -//! Nothing here ever runs server-side against real secrets — only the -//! browser (via the `atomic-wasm` bindings) calls these functions. The -//! server only ever stores the opaque output. +//! The drive-level Cloud Vault key material lives here too +//! (`planning/CLOUD_VAULT_ARCHITECTURE.md`). pub mod keys; diff --git a/lib/src/vault/secret_envelope.rs b/lib/src/vault/secret_envelope.rs index fc68d25897..058b04bcdb 100644 --- a/lib/src/vault/secret_envelope.rs +++ b/lib/src/vault/secret_envelope.rs @@ -1,32 +1,32 @@ -//! Envelope v2 — the multi-wrapper protected-secret format from atomic-saas -//! `planning/BACKUP_SECURITY.md`. +//! The protected-secret envelope: a random 32-byte key (or any small secret) +//! sealed so that the server storing it can never read it. //! -//! Not to be confused with `envelope.rs`, which seals vault *objects*. This -//! protects a *secret* — the Ed25519 agent secret, or a `DriveVaultKey` — such -//! that the server storing it can never read it, and the user can open it from -//! more than one independent credential. +//! Not to be confused with `envelope.rs`, which seals vault *objects*, nor with +//! the browser's account-recovery envelope (`recovery.ts`, stored by +//! atomic-saas as `wrapper_type` rows): that one is a separate AES-GCM format +//! with its own recovery-code and passkey wrappers, and it is not read here. //! //! A random DEK encrypts the secret once. The DEK is then wrapped once per -//! registered credential. Adding or removing a credential rewraps a 32-byte -//! key, never the secret itself, which is what makes credential changes cheap -//! and independent of each other. +//! credential. Adding or removing a credential rewraps a 32-byte key, never the +//! secret itself. //! -//! The rule the design exists to enforce: **no human-memorable secret may ever -//! be the sole thing guarding an offline-crackable blob.** v1 wrapped the agent -//! secret with a user-chosen password over PBKDF2, which is an afternoon on one -//! GPU — and because an Ed25519 agent key can never be rotated, that is a -//! harvest-now-crack-later exposure rather than a bounded one. +//! Two credentials exist, because two are used: +//! +//! - [`WrapperKind::AgentSecret`] — the drive vault keys the control plane +//! stores (`vaultWrapKey`), and the browser's local-database key. +//! - [`WrapperKind::NodeKey`] — secrets a node opens unattended (`db.rs`). +//! +//! Recovery-code, password and WebAuthn-PRF wrappers used to live here too. +//! No production path ever wrote one (recovery runs in `recovery.ts`), so they +//! were removed; an envelope carrying a wrapper kind this build does not know +//! still parses, and that wrapper is skipped rather than failing the whole blob. //! //! ## Cipher choice //! -//! XChaCha20-Poly1305 throughout, where `BACKUP_SECURITY.md` sketched AES-GCM. -//! AES-GCM's advantage would be running natively in WebCrypto without WASM, but -//! Argon2id — the KDF behind the mandatory recovery-code wrapper — is precisely -//! the primitive the Web platform lacks, so any unwrap already loads WASM. That -//! leaves one AEAD across vault objects and envelopes instead of two, and no -//! new dependency. - -use super::keys::{argon2id_derive_key, Argon2Params, KEK_LEN}; +//! XChaCha20-Poly1305 throughout: one AEAD across vault objects and envelopes, +//! and 192-bit random nonces, so one KEK can wrap any number of keys. + +use super::keys::KEK_LEN; use crate::errors::AtomicResult; use chacha20poly1305::aead::{Aead, KeyInit}; use chacha20poly1305::{Key, XChaCha20Poly1305, XNonce}; @@ -40,24 +40,11 @@ pub const SECRET_ENVELOPE_VERSION: u32 = 2; const NONCE_LEN: usize = 24; const DEK_LEN: usize = 32; -/// 128 bits. Enough that the recovery code is not the weak link even though it -/// is the one wrapper a human handles. -const RECOVERY_CODE_BYTES: usize = 16; /// How a wrapper's key-encryption key is obtained. #[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)] #[serde(rename_all = "kebab-case")] pub enum WrapperKind { - /// Machine-generated ~128-bit code, stretched with Argon2id. Mandatory: - /// it is the only wrapper that works with no platform account and no - /// hardware, and the safety net when a passkey is lost. - RecoveryCode, - /// A KEK derived by a WebAuthn PRF assertion. The KEK arrives from the - /// browser already derived — WebAuthn is not something Rust performs. - WebauthnPrf, - /// User-chosen password over Argon2id. Supported so product can offer it, - /// deliberately never the only wrapper. - Password, /// A KEK derived from the agent's signature over a fixed message. /// /// The wrapper that means a user manages **no new secret**. Whatever @@ -84,51 +71,20 @@ pub enum WrapperKind { /// A secret wrapped only by a user credential has no unattended path, by /// construction. That is the trade, not a gap to engineer around. NodeKey, -} - -/// Argon2id parameters as stored, so a blob written today stays openable after -/// the defaults are re-tuned. Reading these from the blob rather than from -/// today's constants is what makes that true. -#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)] -pub struct StoredKdfParams { - pub mem_kib: u32, - pub iterations: u32, - pub parallelism: u32, -} - -impl From for StoredKdfParams { - fn from(p: Argon2Params) -> Self { - Self { - mem_kib: p.mem_kib, - iterations: p.iterations, - parallelism: p.parallelism, - } - } -} - -impl From for Argon2Params { - fn from(p: StoredKdfParams) -> Self { - Self { - mem_kib: p.mem_kib, - iterations: p.iterations, - parallelism: p.parallelism, - } - } + /// A kind this build does not know: written by another client, or one of + /// the removed recovery-code / password / webauthn-prf kinds. Kept so the + /// rest of the envelope still opens; never matched by an [`Unlock`]. + #[serde(other)] + Unknown, } /// One credential's route to the DEK. #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] pub struct Wrapper { pub kind: WrapperKind, - /// Stable handle — a WebAuthn credential id, or a label like "recovery - /// code". Lets a UI name what it is about to remove. + /// Stable handle, like "agent-secret". Lets a UI name what it is about to + /// remove. pub id: String, - /// Present for Argon2id-stretched wrappers, absent for PRF. - #[serde(skip_serializing_if = "Option::is_none")] - pub kdf: Option, - /// Argon2id salt, base64. Absent for PRF. - #[serde(skip_serializing_if = "Option::is_none")] - pub salt: Option, pub nonce: String, pub wrapped_dek: String, } @@ -149,45 +105,25 @@ pub struct SecretEnvelope { /// How a caller proves it may open the envelope. pub enum Unlock<'a> { - /// A recovery code or password as typed. Argon2id runs against the salt - /// stored in the matching wrapper. - Secret(&'a str), - /// A KEK the caller already derived, for PRF. + /// The node's own key, for [`WrapperKind::NodeKey`]. Kek([u8; KEK_LEN]), - /// The account's agent secret, as raw bytes. + /// The agent's vault proof (see [`agent_secret_kek`]), as raw bytes. AgentSecret(&'a [u8]), } /// What to add when creating an envelope or registering a credential. pub enum NewWrapper<'a> { - RecoveryCode { - code: &'a str, - }, - Password { - password: &'a str, - }, - WebauthnPrf { - credential_id: String, - kek: [u8; KEK_LEN], - }, - /// Wrap under the account's agent secret. Raw secret bytes, not a KEK — + /// Wrap under the account's agent secret. Raw proof bytes, not a KEK — /// the derivation is this module's business so every caller gets the same /// domain separation. - AgentSecret { - agent_secret: &'a [u8], - }, + AgentSecret { agent_secret: &'a [u8] }, /// Wrap under the node's own key, so the host can open this unattended. - NodeKey { - kek: [u8; KEK_LEN], - }, + NodeKey { kek: [u8; KEK_LEN] }, } impl NewWrapper<'_> { fn kind(&self) -> WrapperKind { match self { - NewWrapper::RecoveryCode { .. } => WrapperKind::RecoveryCode, - NewWrapper::Password { .. } => WrapperKind::Password, - NewWrapper::WebauthnPrf { .. } => WrapperKind::WebauthnPrf, NewWrapper::AgentSecret { .. } => WrapperKind::AgentSecret, NewWrapper::NodeKey { .. } => WrapperKind::NodeKey, } @@ -195,43 +131,19 @@ impl NewWrapper<'_> { fn id(&self) -> String { match self { - NewWrapper::RecoveryCode { .. } => "recovery-code".to_string(), - NewWrapper::Password { .. } => "password".to_string(), - NewWrapper::WebauthnPrf { credential_id, .. } => credential_id.clone(), NewWrapper::AgentSecret { .. } => "agent-secret".to_string(), NewWrapper::NodeKey { .. } => "node-key".to_string(), } } -} - -/// A freshly generated recovery code, in the grouped form shown to the user. -/// -/// Crockford base32: no `I`, `L`, `O` or `U`, so it survives being read aloud, -/// written down and typed back. Grouped in fives for the same reason. -pub fn generate_recovery_code() -> String { - let mut bytes = [0u8; RECOVERY_CODE_BYTES]; - rand::thread_rng().fill_bytes(&mut bytes); - let raw = base32_encode(&bytes); - raw.as_bytes() - .chunks(5) - .map(|c| std::str::from_utf8(c).unwrap_or_default().to_string()) - .collect::>() - .join("-") -} -/// Codes are compared after stripping grouping and case, so a user who types -/// the dashes (or omits them, or shouts it in caps) still gets in. -pub fn normalize_recovery_code(code: &str) -> String { - code.chars() - .filter(|c| c.is_ascii_alphanumeric()) - .map(|c| c.to_ascii_uppercase()) - // Crockford's documented confusables, resolved on input. - .map(|c| match c { - 'I' | 'L' => '1', - 'O' => '0', - other => other, - }) - .collect() + fn kek(&self) -> [u8; KEK_LEN] { + match self { + // No KDF: the proof is already a full-strength signature, so + // stretching it would cost time and add nothing. + NewWrapper::AgentSecret { agent_secret } => agent_secret_kek(agent_secret), + NewWrapper::NodeKey { kek } => *kek, + } + } } /// Domain separator for the agent-derived KEK. @@ -262,28 +174,6 @@ pub fn agent_secret_kek(proof: &[u8]) -> [u8; KEK_LEN] { blake3::derive_key(AGENT_SECRET_CONTEXT, proof) } -const BASE32_ALPHABET: &[u8] = b"0123456789ABCDEFGHJKMNPQRSTVWXYZ"; - -fn base32_encode(bytes: &[u8]) -> String { - let mut out = String::new(); - let mut buffer: u16 = 0; - let mut bits: u8 = 0; - for byte in bytes { - buffer = (buffer << 8) | u16::from(*byte); - bits += 8; - while bits >= 5 { - let index = ((buffer >> (bits - 5)) & 0x1F) as usize; - out.push(BASE32_ALPHABET[index] as char); - bits -= 5; - } - } - if bits > 0 { - let index = ((buffer << (5 - bits)) & 0x1F) as usize; - out.push(BASE32_ALPHABET[index] as char); - } - out -} - fn b64(bytes: &[u8]) -> String { crate::agents::encode_base64(bytes) } @@ -317,43 +207,15 @@ fn unseal(key: &[u8; 32], nonce: &str, ciphertext: &str) -> AtomicResult } fn wrap_dek(dek: &[u8; DEK_LEN], spec: &NewWrapper) -> AtomicResult { - let (kdf, salt, kek) = match spec { - NewWrapper::RecoveryCode { code } | NewWrapper::Password { password: code } => { - let params = Argon2Params::default(); - let mut salt_bytes = [0u8; 16]; - rand::thread_rng().fill_bytes(&mut salt_bytes); - let kek = - argon2id_derive_key(normalize_for(spec, code).as_bytes(), &salt_bytes, params) - .map_err(|e| format!("failed to stretch credential: {e}"))?; - (Some(params.into()), Some(b64(&salt_bytes)), kek) - } - NewWrapper::WebauthnPrf { kek, .. } => (None, None, *kek), - // No KDF: the agent secret is already a full-strength random key, so - // stretching it would cost time and add nothing. - NewWrapper::AgentSecret { agent_secret } => (None, None, agent_secret_kek(agent_secret)), - NewWrapper::NodeKey { kek } => (None, None, *kek), - }; - - let (nonce, wrapped_dek) = seal(&kek, dek)?; + let (nonce, wrapped_dek) = seal(&spec.kek(), dek)?; Ok(Wrapper { kind: spec.kind(), id: spec.id(), - kdf, - salt, nonce, wrapped_dek, }) } -/// Recovery codes are normalized before stretching; passwords are not, because -/// a password's exact bytes are what the user chose. -fn normalize_for(spec: &NewWrapper, secret: &str) -> String { - match spec { - NewWrapper::RecoveryCode { .. } => normalize_recovery_code(secret), - _ => secret.to_string(), - } -} - impl SecretEnvelope { /// Protect `secret` under the given credentials. /// @@ -394,21 +256,7 @@ impl SecretEnvelope { for wrapper in &self.wrappers { let kek = match (unlock, wrapper.kind) { - (Unlock::Secret(secret), WrapperKind::RecoveryCode | WrapperKind::Password) => { - let (Some(kdf), Some(salt)) = (wrapper.kdf, wrapper.salt.as_ref()) else { - continue; - }; - let normalized = if wrapper.kind == WrapperKind::RecoveryCode { - normalize_recovery_code(secret) - } else { - (*secret).to_string() - }; - match argon2id_derive_key(normalized.as_bytes(), &unb64(salt)?, kdf.into()) { - Ok(kek) => kek, - Err(_) => continue, - } - } - (Unlock::Kek(kek), WrapperKind::WebauthnPrf | WrapperKind::NodeKey) => *kek, + (Unlock::Kek(kek), WrapperKind::NodeKey) => *kek, (Unlock::AgentSecret(secret), WrapperKind::AgentSecret) => agent_secret_kek(secret), _ => continue, }; @@ -436,6 +284,7 @@ impl SecretEnvelope { /// with it. The server never can — it holds ciphertext — but the rule /// belongs in the format, not in the storage layer's good intentions. pub fn add_wrapper(&mut self, unlock: &Unlock, spec: &NewWrapper) -> AtomicResult<()> { + self.refuse_rewrite_with_unknown_wrappers()?; let dek = self.recover_dek(unlock)?; let new_id = spec.id(); if self.wrappers.iter().any(|w| w.id == new_id) { @@ -449,6 +298,7 @@ impl SecretEnvelope { /// blob nobody can ever open, which is indistinguishable from having /// deleted the secret except that it looks like a backup still exists. pub fn remove_wrapper(&mut self, id: &str) -> AtomicResult<()> { + self.refuse_rewrite_with_unknown_wrappers()?; if self.wrappers.len() <= 1 { return Err("cannot remove the only wrapper: the secret would be unrecoverable".into()); } @@ -464,6 +314,19 @@ impl SecretEnvelope { self.wrappers.iter().any(|w| w.kind == kind) } + /// An unknown wrapper parses as [`WrapperKind::Unknown`], and writing the + /// envelope back would store that placeholder instead of its real kind, + /// breaking whichever client wrote it. Editing is left to that client. + fn refuse_rewrite_with_unknown_wrappers(&self) -> AtomicResult<()> { + if self.has_kind(WrapperKind::Unknown) { + return Err( + "this envelope has a wrapper kind this build does not know; refusing to rewrite it" + .into(), + ); + } + Ok(()) + } + fn check_version(&self) -> AtomicResult<()> { if self.format_version != SECRET_ENVELOPE_VERSION { return Err(format!( @@ -491,41 +354,25 @@ impl SecretEnvelope { mod tests { use super::*; - /// Argon2id at production settings is intentionally slow; tests use the - /// cheap parameters the KDF module already reserves for this. - fn fast_params() -> Argon2Params { - Argon2Params { - mem_kib: 8 * 1024, - iterations: 1, - parallelism: 1, - } - } - - /// Build an envelope with cheap KDF params by rewriting them after - /// creation is not possible (the KEK depends on them), so tests that need - /// speed construct wrappers directly through the same code path with - /// patched defaults would be fragile. Instead these tests accept the real - /// cost for the few cases that need a code wrapper, and use PRF wrappers - /// (no KDF) everywhere else. - fn prf(id: &str, byte: u8) -> NewWrapper<'static> { - NewWrapper::WebauthnPrf { - credential_id: id.to_string(), + fn node(byte: u8) -> NewWrapper<'static> { + NewWrapper::NodeKey { kek: [byte; KEK_LEN], } } const SECRET: &[u8] = b"an ed25519 agent secret"; + const PROOF: &[u8] = &[7u8; 64]; #[test] - fn round_trips_through_a_prf_wrapper() { - let envelope = SecretEnvelope::create(SECRET, &[prf("passkey-a", 1)]).unwrap(); + fn round_trips_through_a_node_key_wrapper() { + let envelope = SecretEnvelope::create(SECRET, &[node(1)]).unwrap(); let opened = envelope.unwrap_secret(&Unlock::Kek([1; KEK_LEN])).unwrap(); assert_eq!(opened, SECRET); } #[test] fn the_secret_is_not_in_the_blob() { - let envelope = SecretEnvelope::create(SECRET, &[prf("passkey-a", 1)]).unwrap(); + let envelope = SecretEnvelope::create(SECRET, &[node(1)]).unwrap(); let json = envelope.to_json().unwrap(); assert!(!json.contains("ed25519 agent secret")); assert!(!json.as_bytes().windows(SECRET.len()).any(|w| w == SECRET)); @@ -533,11 +380,18 @@ mod tests { #[test] fn any_registered_credential_opens_it() { - // The point of the design: two independent routes to one secret. - let envelope = - SecretEnvelope::create(SECRET, &[prf("passkey-a", 1), prf("passkey-b", 2)]).unwrap(); + let envelope = SecretEnvelope::create( + SECRET, + &[ + NewWrapper::AgentSecret { + agent_secret: PROOF, + }, + node(2), + ], + ) + .unwrap(); assert_eq!( - envelope.unwrap_secret(&Unlock::Kek([1; KEK_LEN])).unwrap(), + envelope.unwrap_secret(&Unlock::AgentSecret(PROOF)).unwrap(), SECRET ); assert_eq!( @@ -548,73 +402,31 @@ mod tests { #[test] fn an_unregistered_credential_does_not() { - let envelope = SecretEnvelope::create(SECRET, &[prf("passkey-a", 1)]).unwrap(); + let envelope = SecretEnvelope::create(SECRET, &[node(1)]).unwrap(); assert!(envelope.unwrap_secret(&Unlock::Kek([9; KEK_LEN])).is_err()); - } - - #[test] - fn a_recovery_code_opens_it() { - let code = generate_recovery_code(); - let envelope = - SecretEnvelope::create(SECRET, &[NewWrapper::RecoveryCode { code: &code }]).unwrap(); - assert_eq!( - envelope.unwrap_secret(&Unlock::Secret(&code)).unwrap(), - SECRET - ); + // A node key never opens an agent wrapper, even with matching bytes. assert!(envelope - .unwrap_secret(&Unlock::Secret("WRONG-CODE-HERE")) + .unwrap_secret(&Unlock::AgentSecret(&[1; 32])) .is_err()); } - /// A user reading a code off paper will not reproduce the grouping or the - /// case, and Crockford's confusable characters are exactly the ones people - /// mistranscribe. - #[test] - fn recovery_codes_tolerate_how_humans_retype_them() { - let code = generate_recovery_code(); - let envelope = - SecretEnvelope::create(SECRET, &[NewWrapper::RecoveryCode { code: &code }]).unwrap(); - - let no_dashes = code.replace('-', ""); - let lowercased = code.to_lowercase(); - let spaced = code.replace('-', " "); - - for variant in [no_dashes, lowercased, spaced] { - assert_eq!( - envelope.unwrap_secret(&Unlock::Secret(&variant)).unwrap(), - SECRET, - "failed for {variant:?}" - ); - } - } - - #[test] - fn generated_codes_are_unique_and_shaped_for_transcription() { - let a = generate_recovery_code(); - let b = generate_recovery_code(); - assert_ne!(a, b); - // 128 bits of base32 is 26 characters, grouped in fives. - assert_eq!(a.replace('-', "").len(), 26); - assert!(a.contains('-')); - for c in a.chars().filter(|c| *c != '-') { - assert!( - !matches!(c, 'I' | 'L' | 'O' | 'U'), - "confusable character {c} in {a}" - ); - } - } - #[test] fn adding_a_credential_requires_opening_the_envelope_first() { - let mut envelope = SecretEnvelope::create(SECRET, &[prf("passkey-a", 1)]).unwrap(); + let mut envelope = SecretEnvelope::create( + SECRET, + &[NewWrapper::AgentSecret { + agent_secret: PROOF, + }], + ) + .unwrap(); // Someone who cannot open it cannot register themselves into it. assert!(envelope - .add_wrapper(&Unlock::Kek([9; KEK_LEN]), &prf("attacker", 3)) + .add_wrapper(&Unlock::AgentSecret(&[9; 64]), &node(3)) .is_err()); envelope - .add_wrapper(&Unlock::Kek([1; KEK_LEN]), &prf("passkey-b", 2)) + .add_wrapper(&Unlock::AgentSecret(PROOF), &node(2)) .unwrap(); assert_eq!( envelope.unwrap_secret(&Unlock::Kek([2; KEK_LEN])).unwrap(), @@ -624,31 +436,36 @@ mod tests { #[test] fn duplicate_wrapper_ids_are_refused() { - let mut envelope = SecretEnvelope::create(SECRET, &[prf("passkey-a", 1)]).unwrap(); + let mut envelope = SecretEnvelope::create(SECRET, &[node(1)]).unwrap(); assert!(envelope - .add_wrapper(&Unlock::Kek([1; KEK_LEN]), &prf("passkey-a", 5)) + .add_wrapper(&Unlock::Kek([1; KEK_LEN]), &node(5)) .is_err()); } #[test] fn removing_a_credential_leaves_the_others_working() { - let mut envelope = - SecretEnvelope::create(SECRET, &[prf("passkey-a", 1), prf("passkey-b", 2)]).unwrap(); - envelope.remove_wrapper("passkey-a").unwrap(); - assert!(envelope.unwrap_secret(&Unlock::Kek([1; KEK_LEN])).is_err()); + let mut envelope = SecretEnvelope::create( + SECRET, + &[ + NewWrapper::AgentSecret { + agent_secret: PROOF, + }, + node(2), + ], + ) + .unwrap(); + envelope.remove_wrapper("node-key").unwrap(); + assert!(envelope.unwrap_secret(&Unlock::Kek([2; KEK_LEN])).is_err()); assert_eq!( - envelope.unwrap_secret(&Unlock::Kek([2; KEK_LEN])).unwrap(), + envelope.unwrap_secret(&Unlock::AgentSecret(PROOF)).unwrap(), SECRET ); } #[test] fn the_last_credential_cannot_be_removed() { - let mut envelope = SecretEnvelope::create(SECRET, &[prf("passkey-a", 1)]).unwrap(); - let err = envelope - .remove_wrapper("passkey-a") - .unwrap_err() - .to_string(); + let mut envelope = SecretEnvelope::create(SECRET, &[node(1)]).unwrap(); + let err = envelope.remove_wrapper("node-key").unwrap_err().to_string(); assert!(err.contains("unrecoverable"), "{err}"); assert_eq!( envelope.unwrap_secret(&Unlock::Kek([1; KEK_LEN])).unwrap(), @@ -663,8 +480,16 @@ mod tests { #[test] fn survives_json_storage() { - let envelope = - SecretEnvelope::create(SECRET, &[prf("passkey-a", 1), prf("passkey-b", 2)]).unwrap(); + let envelope = SecretEnvelope::create( + SECRET, + &[ + NewWrapper::AgentSecret { + agent_secret: PROOF, + }, + node(2), + ], + ) + .unwrap(); let restored = SecretEnvelope::from_json(&envelope.to_json().unwrap()).unwrap(); assert_eq!(restored, envelope); assert_eq!( @@ -673,6 +498,75 @@ mod tests { ); } + /// The wire names are what the control plane and older builds stored; + /// removing other kinds must not have renamed these. + #[test] + fn wrapper_kinds_keep_their_wire_names() { + let envelope = SecretEnvelope::create( + SECRET, + &[ + NewWrapper::AgentSecret { + agent_secret: PROOF, + }, + node(2), + ], + ) + .unwrap(); + let json = envelope.to_json().unwrap(); + assert!(json.contains(r#""kind":"agent-secret""#), "{json}"); + assert!(json.contains(r#""kind":"node-key""#), "{json}"); + } + + /// An envelope written by a build that still had recovery-code, password + /// and webauthn-prf wrappers (with their `kdf` / `salt` fields) must keep + /// opening through the wrapper this build does understand. + #[test] + fn envelopes_with_removed_wrapper_kinds_still_open() { + let envelope = SecretEnvelope::create( + SECRET, + &[NewWrapper::AgentSecret { + agent_secret: PROOF, + }], + ) + .unwrap(); + let mut value: serde_json::Value = + serde_json::from_str(&envelope.to_json().unwrap()).unwrap(); + let wrappers = value["wrappers"].as_array_mut().unwrap(); + // Wrapper kinds older builds could write; the extra fields are the + // Argon2 ones they carried. Placeholder bytes, not credentials. + const REMOVED_KINDS: [&str; 3] = ["recovery-code", "password", "webauthn-prf"]; + for kind in REMOVED_KINDS { + wrappers.insert( + 0, + serde_json::json!({ + "kind": kind, + "id": kind, + "kdf": {"mem_kib": 65536, "iterations": 3, "parallelism": 1}, + "salt": b64(&[0u8; 16]), + "nonce": b64(&[0u8; NONCE_LEN]), + "wrapped_dek": b64(&[0u8; 3]), + }), + ); + } + + let legacy = SecretEnvelope::from_json(&value.to_string()).unwrap(); + assert_eq!(legacy.wrappers[0].kind, WrapperKind::Unknown); + assert_eq!( + legacy.unwrap_secret(&Unlock::AgentSecret(PROOF)).unwrap(), + SECRET + ); + assert!(legacy + .unwrap_secret(&Unlock::AgentSecret(&[8; 64])) + .is_err()); + + // Writing it back would lose the unknown kinds, so edits are refused. + let mut editable = legacy.clone(); + assert!(editable + .add_wrapper(&Unlock::AgentSecret(PROOF), &node(1)) + .is_err()); + assert!(editable.remove_wrapper(REMOVED_KINDS[0]).is_err()); + } + /// v1 blobs are a different scheme. Refusing them loudly beats appearing to /// support them and returning nonsense. #[test] @@ -684,37 +578,25 @@ mod tests { #[test] fn tampering_with_the_ciphertext_is_detected() { - let mut envelope = SecretEnvelope::create(SECRET, &[prf("passkey-a", 1)]).unwrap(); + let mut envelope = SecretEnvelope::create(SECRET, &[node(1)]).unwrap(); envelope.ciphertext = b64(b"replaced by an attacker"); assert!(envelope.unwrap_secret(&Unlock::Kek([1; KEK_LEN])).is_err()); } - /// A `DriveVaultKey` is protected exactly like an agent secret — the point - /// of building this as a shared module rather than twice. - #[test] - fn protects_a_drive_vault_key_too() { - let drive_key = super::super::dek::DriveVaultKey::generate(1); - let envelope = - SecretEnvelope::create(drive_key.expose_secret(), &[prf("passkey-a", 1)]).unwrap(); - let recovered = envelope.unwrap_secret(&Unlock::Kek([1; KEK_LEN])).unwrap(); - assert_eq!(recovered, drive_key.expose_secret()); - } - /// The whole point of the wrapper: a user who can restore their identity can /// restore their drive keys, with nothing extra to remember. #[test] fn an_agent_secret_opens_the_envelope() { - let agent_secret = b"an ed25519 private key's bytes"; let drive_key = super::super::dek::DriveVaultKey::generate(1); let envelope = SecretEnvelope::create( drive_key.expose_secret(), - &[NewWrapper::AgentSecret { agent_secret }], + &[NewWrapper::AgentSecret { + agent_secret: PROOF, + }], ) .unwrap(); - let recovered = envelope - .unwrap_secret(&Unlock::AgentSecret(agent_secret)) - .unwrap(); + let recovered = envelope.unwrap_secret(&Unlock::AgentSecret(PROOF)).unwrap(); assert_eq!(recovered, drive_key.expose_secret()); } @@ -745,39 +627,7 @@ mod tests { assert_eq!(kek, agent_secret_kek(&agent_secret)); } - /// A drive key wrapped under the agent secret can gain a recovery-code - /// wrapper later without re-encrypting anything — the point of wrapping a - /// DEK rather than the secret. - #[test] - fn a_recovery_code_can_be_added_to_an_agent_wrapped_envelope() { - let agent_secret = b"agent bytes"; - let mut envelope = - SecretEnvelope::create(SECRET, &[NewWrapper::AgentSecret { agent_secret }]).unwrap(); - - let code = generate_recovery_code(); - envelope - .add_wrapper( - &Unlock::AgentSecret(agent_secret), - &NewWrapper::RecoveryCode { code: &code }, - ) - .unwrap(); - - // Both routes now open the same secret. - assert_eq!( - envelope.unwrap_secret(&Unlock::Secret(&code)).unwrap(), - SECRET - ); - assert_eq!( - envelope - .unwrap_secret(&Unlock::AgentSecret(agent_secret)) - .unwrap(), - SECRET - ); - } - - /// Losing the agent secret must not be survivable *through this wrapper* — - /// that is what the second wrapper is for. Pins that the agent wrapper - /// alone genuinely gates on the secret. + /// Losing the agent secret must not be survivable *through this wrapper*. #[test] fn without_the_agent_secret_there_is_no_way_in() { let envelope = SecretEnvelope::create( @@ -788,16 +638,9 @@ mod tests { ) .unwrap(); assert!(envelope.unwrap_secret(&Unlock::Kek([0; KEK_LEN])).is_err()); - assert!(envelope.unwrap_secret(&Unlock::Secret("guess")).is_err()); - } - - #[test] - fn stored_kdf_params_survive_a_defaults_change() { - // Reading params from the blob rather than from today's constants is - // what keeps an old backup openable after the defaults are re-tuned. - let stored: StoredKdfParams = fast_params().into(); - let back: Argon2Params = stored.into(); - assert_eq!(back.mem_kib, fast_params().mem_kib); - assert_eq!(back.iterations, fast_params().iterations); + // The KEK itself is not accepted as a node key either. + assert!(envelope + .unwrap_secret(&Unlock::Kek(agent_secret_kek(b"lost forever"))) + .is_err()); } }