@learncard/sss-key-manager 0.1.24 → 0.2.1

package/src/escrow-vectors.test.ts

@@ -0,0 +1,198 @@
+// @vitest-environment node
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import { expect, it } from 'vitest';
+import { base64ToBuffer } from './crypto';
+
+import {
+    decryptEscrowBlob,
+    ESCROW_BLOB_INFO,
+    ESCROW_RELEASE_INFO,
+    encryptEscrowBlob,
+    generateEscrowKeyPair,
+    openEscrowRelease,
+    sealEscrowRelease,
+} from './escrow-crypto';
+import type { EscrowBlobPlaintext, EscrowEnvelope, EscrowReleasePlaintext } from './escrow-crypto';
+
+type KeyPair = Awaited<ReturnType<typeof generateEscrowKeyPair>>;
+interface Vectors {
+    // Public test-only keys, never used for real recovery data.
+    enclave: KeyPair;
+    client: KeyPair;
+    blobs: { plaintext: EscrowBlobPlaintext; envelope: EscrowEnvelope }[];
+    releases: { plaintext: EscrowReleasePlaintext; envelope: EscrowEnvelope }[];
+}
+
+it('decrypts shared TS/Rust escrow vectors (ESCROW_WRITE_VECTORS=1 regenerates)', async () => {
+    const directory = fileURLToPath(new URL('./__fixtures__/', import.meta.url));
+    const path = fileURLToPath(new URL('./__fixtures__/escrow-vectors.json', import.meta.url));
+
+    if (process.env.ESCROW_WRITE_VECTORS === '1') {
+        const enclave = await generateEscrowKeyPair();
+        const client = await generateEscrowKeyPair();
+        const inputs = [
+            { recoveryShare: 'ABCDE', did: 'did:example:legacy', shareVersion: 1 },
+            {
+                recoveryShare: `0001${'AB'.repeat(48)}`,
+                did: 'did:example:pin',
+                shareVersion: 42,
+                pinVerifier: 'CD'.repeat(32),
+            },
+            {
+                recoveryShare: 'ef'.repeat(2048),
+                did: `did:${'x'.repeat(2042)}😀`,
+                shareVersion: 9_007_199_254_740_992,
+            },
+        ];
+        const blobs = await Promise.all(
+            inputs.map(async (input, index) => {
+                const envelope = await encryptEscrowBlob(
+                    input,
+                    enclave.publicKey,
+                    `test-key.${index}`
+                );
+                return {
+                    plaintext: await decryptEscrowBlob(envelope, enclave.privateKey),
+                    envelope,
+                };
+            })
+        );
+        const releases = await Promise.all(
+            inputs.slice(0, 2).map(async (input, index) => {
+                const envelope = await sealEscrowRelease(
+                    { ...input, holdId: `hold-${index}.test_1` },
+                    client.publicKey
+                );
+                return {
+                    plaintext: await openEscrowRelease(envelope, client.privateKey),
+                    envelope,
+                };
+            })
+        );
+        const vectors: Vectors = { enclave, client, blobs, releases };
+        await mkdir(directory, { recursive: true });
+        await writeFile(path, `${JSON.stringify(vectors, null, 4)}\n`);
+    }
+
+    const vectors: Vectors = JSON.parse(await readFile(path, 'utf8'));
+    expect(vectors.blobs).toHaveLength(3);
+    expect(vectors.releases).toHaveLength(2);
+    for (const { plaintext, envelope } of vectors.blobs) {
+        await expect(decryptEscrowBlob(envelope, vectors.enclave.privateKey)).resolves.toEqual(
+            plaintext
+        );
+    }
+    for (const { plaintext, envelope } of vectors.releases) {
+        await expect(openEscrowRelease(envelope, vectors.client.privateKey)).resolves.toEqual(
+            plaintext
+        );
+    }
+});
+
+// Independent WebCrypto decryption exposes raw JSON before the production validator
+// normalizes it, so a numeric 1.0 cannot silently satisfy the integral-token assertion.
+const decryptRawJson = async (
+    envelope: EscrowEnvelope,
+    privateKey: string,
+    info: string
+): Promise<string> => {
+    const recipient = await crypto.subtle.importKey(
+        'pkcs8',
+        base64ToBuffer(privateKey),
+        { name: 'ECDH', namedCurve: 'P-256' },
+        false,
+        ['deriveBits']
+    );
+    const ephemeral = await crypto.subtle.importKey(
+        'raw',
+        base64ToBuffer(envelope.ephemeralPublicKey),
+        { name: 'ECDH', namedCurve: 'P-256' },
+        false,
+        []
+    );
+    const shared = await crypto.subtle.deriveBits(
+        { name: 'ECDH', public: ephemeral },
+        recipient,
+        256
+    );
+    const material = await crypto.subtle.importKey('raw', shared, 'HKDF', false, ['deriveKey']);
+    const key = await crypto.subtle.deriveKey(
+        {
+            name: 'HKDF',
+            hash: 'SHA-256',
+            salt: base64ToBuffer(envelope.salt),
+            info: new TextEncoder().encode(info),
+        },
+        material,
+        { name: 'AES-GCM', length: 256 },
+        false,
+        ['decrypt']
+    );
+    const plaintext = await crypto.subtle.decrypt(
+        {
+            name: 'AES-GCM',
+            iv: base64ToBuffer(envelope.iv),
+            additionalData: new TextEncoder().encode(
+                `${envelope.version}|${envelope.algorithm}|${envelope.keyId}`
+            ),
+        },
+        key,
+        base64ToBuffer(envelope.ciphertext)
+    );
+    return new TextDecoder().decode(plaintext);
+};
+
+it('opens Rust blobs and releases in WebCrypto and emits integral JSON share versions', async () => {
+    const ts: Vectors = JSON.parse(
+        await readFile(
+            fileURLToPath(new URL('./__fixtures__/escrow-vectors.json', import.meta.url)),
+            'utf8'
+        )
+    );
+    const rust: Omit<Vectors, 'client'> = JSON.parse(
+        await readFile(
+            fileURLToPath(new URL('./__fixtures__/escrow-vectors-rust.json', import.meta.url)),
+            'utf8'
+        )
+    );
+    expect(rust.blobs).toHaveLength(2);
+    expect(rust.releases).toHaveLength(2);
+
+    // Import Rust SPKI as well as PKCS#8, and verify the two exports describe one key.
+    const publicKey = await crypto.subtle.importKey(
+        'spki',
+        base64ToBuffer(rust.enclave.publicKey),
+        { name: 'ECDH', namedCurve: 'P-256' },
+        true,
+        []
+    );
+    const privateKey = await crypto.subtle.importKey(
+        'pkcs8',
+        base64ToBuffer(rust.enclave.privateKey),
+        { name: 'ECDH', namedCurve: 'P-256' },
+        true,
+        ['deriveBits']
+    );
+    const publicJwk = await crypto.subtle.exportKey('jwk', publicKey);
+    expect(await crypto.subtle.exportKey('jwk', privateKey)).toMatchObject({
+        crv: 'P-256',
+        x: publicJwk.x,
+        y: publicJwk.y,
+    });
+
+    for (const { plaintext, envelope } of rust.blobs) {
+        await expect(decryptEscrowBlob(envelope, rust.enclave.privateKey)).resolves.toEqual(
+            plaintext
+        );
+        const raw = await decryptRawJson(envelope, rust.enclave.privateKey, ESCROW_BLOB_INFO);
+        expect(raw).toMatch(new RegExp(`"shareVersion":${plaintext.shareVersion}[,}]`));
+        expect(JSON.parse(raw)).toEqual(plaintext);
+    }
+    for (const { plaintext, envelope } of rust.releases) {
+        await expect(openEscrowRelease(envelope, ts.client.privateKey)).resolves.toEqual(plaintext);
+        const raw = await decryptRawJson(envelope, ts.client.privateKey, ESCROW_RELEASE_INFO);
+        expect(raw).toMatch(new RegExp(`"shareVersion":${plaintext.shareVersion}[,}]`));
+        expect(JSON.parse(raw)).toEqual(plaintext);
+    }
+});

package/src/index.ts

@@ -43,6 +43,67 @@ export {
     DEFAULT_KDF_PARAMS,
 } from './crypto';
 
+export {
+    EMAIL_RELAY_ALGORITHM,
+    EMAIL_RELAY_ENVELOPE_VERSION,
+    encryptEmailRelayPayload,
+    decryptEmailRelayPayload,
+    generateEmailRelayConfirmationCode,
+    parseEmailRelayEnvelope,
+    parseEmailRelayPlaintext,
+} from './email-relay-crypto';
+
+export type {
+    EmailRelayBranding,
+    EmailRelayEnvelope,
+    EmailRelayPlaintext,
+} from './email-relay-crypto';
+
+export {
+    ESCROW_ENVELOPE_VERSION,
+    ESCROW_ALGORITHM,
+    ESCROW_BLOB_INFO,
+    ESCROW_RELEASE_INFO,
+    ESCROW_CLIENT_KEY_ID,
+    parseEscrowEnvelope,
+    parseEscrowBlobPlaintext,
+    parseEscrowReleasePlaintext,
+    generateEscrowKeyPair,
+    encryptEscrowBlob,
+    decryptEscrowBlob,
+    sealEscrowRelease,
+    openEscrowRelease,
+} from './escrow-crypto';
+
+export type { EscrowEnvelope, EscrowBlobPlaintext, EscrowReleasePlaintext } from './escrow-crypto';
+export { verifyEnclaveAttestation } from './escrow-attestation';
+export { verifyNitroAttestationDocument, NitroAttestationError } from './escrow-nitro-attestation';
+export type { NitroAttestationReason } from './escrow-nitro-attestation';
+export type { EscrowAttestationPolicy, EscrowHoldStatus, EscrowRecoveryStart } from './types';
+export type {
+    EscrowEnrollmentOptions,
+    EscrowEnrollmentState,
+    EscrowBlobStaleReason,
+    EscrowPinStatus,
+} from './types';
+export {
+    EscrowPinMismatchError,
+    EscrowPinLockedError,
+    EscrowPinThrottledError,
+    EscrowHoldRestartThrottledError,
+    EscrowPinUnavailableError,
+} from './types';
+export {
+    PIN_MIN_LENGTH,
+    PIN_MAX_LENGTH,
+    ESCROW_PIN_MAX_ATTEMPTS,
+    normalizePin,
+    validatePin,
+    generatePinSalt,
+    derivePinProof,
+    constantTimeEqualHex,
+} from './escrow-pin';
+
 export {
     createPasskeyCredential,
     deriveKeyFromPasskey,
@@ -60,6 +121,7 @@ export {
     generateRecoveryPhrase,
     validateRecoveryPhrase,
     countWords,
+    buildRecoveryPhraseChallengeOptions,
 } from './recovery-phrase';
 
 export type { RecoveryPhraseData } from './recovery-phrase';
@@ -71,6 +133,7 @@ export {
     atomicRecovery,
     ShareVerificationError,
     AtomicUpdateError,
+    ShareWriteRejectedError,
 } from './atomic-operations';
 
 export type {
@@ -79,7 +142,11 @@ export type {
     StorageOperations,
 } from './atomic-operations';
 
-export { createSSSStrategy } from './sss-strategy';
+export {
+    createSSSStrategy,
+    IdentityRecoverySessionConsumedError,
+    EscrowRequestError,
+} from './sss-strategy';
 
 export type { SSSStorageFunctions, SSSStrategyConfig } from './sss-strategy';
 
@@ -125,6 +192,7 @@ export type {
     AuthProvider,
     AuthUser,
     AuthProviderType,
+    DidAuthVpSigner,
     ContactMethod,
     ContactMethodType,
     RecoveryMethod,
@@ -134,6 +202,7 @@ export type {
     RecoveryResult,
     RecoverySetupInput,
     RecoverySetupResult,
+    RecoveryConfirmationInput,
     PasskeyRecoveryMethod,
     BackupFileRecoveryMethod,
     RecoveryPhraseRecoveryMethod,

package/src/key-manager.ts

@@ -21,11 +21,7 @@ import {
     deleteDeviceShare,
     clearAllShares,
 } from './storage';
-import {
-    encryptWithPassword,
-    decryptWithPassword,
-    generateEd25519PrivateKey,
-} from './crypto';
+import { encryptWithPassword, decryptWithPassword, generateEd25519PrivateKey } from './crypto';
 
 import {
     createPasskeyCredential,
@@ -33,11 +29,9 @@ import {
     decryptShareWithPasskey,
 } from './passkey';
 
-import {
-    shareToRecoveryPhrase,
-    recoveryPhraseToShare,
-} from './recovery-phrase';
+import { shareToRecoveryPhrase, recoveryPhraseToShare } from './recovery-phrase';
 
+/** @deprecated Use `createSSSStrategy` with AuthCoordinator. */
 export class SSSKeyManager implements SSSKeyDerivationProvider {
     readonly name = 'sss';
 
@@ -318,6 +312,7 @@ export class SSSKeyManager implements SSSKeyDerivationProvider {
     }
 }
 
+/** @deprecated Use `createSSSStrategy` with AuthCoordinator. */
 export function createSSSKeyManager(config: SSSKeyManagerConfig): SSSKeyManager {
     return new SSSKeyManager(config);
 }

package/src/qr-login.ts

@@ -55,21 +55,19 @@ export interface QrPayload {
 /** Result of polling — either still waiting or the device share is ready */
 export type PollResult =
     | { status: 'pending' }
-    | { status: 'approved'; deviceShare: string; approverDid: string; accountHint?: string; shareVersion?: number };
+    | {
+          status: 'approved';
+          deviceShare: string;
+          approverDid: string;
+          accountHint?: string;
+          shareVersion?: number;
+      };
 
 // ---------------------------------------------------------------------------
 // API helpers
 // ---------------------------------------------------------------------------
 
-const buildHeaders = (token?: string): Record<string, string> => {
-    const headers: Record<string, string> = { 'Content-Type': 'application/json' };
-
-    if (token) {
-        headers.Authorization = `Bearer ${token}`;
-    }
-
-    return headers;
-};
+const buildHeaders = (): Record<string, string> => ({ 'Content-Type': 'application/json' });
 
 // ---------------------------------------------------------------------------
 // Requester (Device B — the new device)
@@ -180,7 +178,12 @@ export const pollUntilApproved = async (
         onPoll?: (attempt: number) => void;
         signal?: AbortSignal;
     }
-): Promise<{ deviceShare: string; approverDid: string; accountHint?: string; shareVersion?: number }> => {
+): Promise<{
+    deviceShare: string;
+    approverDid: string;
+    accountHint?: string;
+    shareVersion?: number;
+}> => {
     const intervalMs = options?.intervalMs ?? 2000;
     const timeoutMs = options?.timeoutMs ?? 120_000;
 
@@ -211,10 +214,14 @@ export const pollUntilApproved = async (
             const timer = setTimeout(resolve, intervalMs);
 
             if (options?.signal) {
-                options.signal.addEventListener('abort', () => {
-                    clearTimeout(timer);
-                    reject(new Error('QR login polling aborted'));
-                }, { once: true });
+                options.signal.addEventListener(
+                    'abort',
+                    () => {
+                        clearTimeout(timer);
+                        reject(new Error('QR login polling aborted'));
+                    },
+                    { once: true }
+                );
             }
         });
     }

package/src/recovery-phrase.ts

@@ -132,3 +132,43 @@ export function countWords(phrase: string): number {
         .split(/\s+/)
         .filter(w => w.length > 0).length;
 }
+
+/** Uniform random integer in [0, max) without modulo bias. */
+function randomIndex(max: number): number {
+    const limit = 0x1_0000_0000 - (0x1_0000_0000 % max);
+    for (;;) {
+        const value = crypto.getRandomValues(new Uint32Array(1))[0];
+        if (value === undefined) throw new Error('Failed to choose recovery phrase words');
+        if (value < limit) return value % max;
+    }
+}
+
+/**
+ * Builds tap-to-confirm choices for each challenged word: the correct word plus
+ * `optionCount - 1` decoys, shuffled. Decoys never appear anywhere in the phrase,
+ * so a choice can only be right for its own position.
+ */
+export async function buildRecoveryPhraseChallengeOptions(
+    phrase: string,
+    challengeWordIndices: number[],
+    optionCount = 6
+): Promise<string[][]> {
+    const words = phrase.trim().split(/\s+/);
+    const phraseWords = new Set(words);
+    const decoyPool = (await getWordlist()).filter(word => !phraseWords.has(word));
+
+    return challengeWordIndices.map(wordIndex => {
+        const answer = words[wordIndex];
+        if (!answer) throw new Error('Recovery phrase challenge index is out of range');
+
+        const options = new Set<string>([answer]);
+        while (options.size < optionCount) options.add(decoyPool[randomIndex(decoyPool.length)]!);
+
+        const shuffled = [...options];
+        for (let i = shuffled.length - 1; i > 0; i--) {
+            const j = randomIndex(i + 1);
+            [shuffled[i], shuffled[j]] = [shuffled[j]!, shuffled[i]!];
+        }
+        return shuffled;
+    });
+}

package/src/sss-session-writes.test.ts

@@ -0,0 +1,109 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { createSSSStrategy, type SSSStorageFunctions } from './sss-strategy';
+
+vi.mock('./escrow-attestation', () => ({
+    verifyEnclaveAttestation: async () => ({ publicKey: 'test-key', keyId: 'test-key' }),
+}));
+vi.mock('./escrow-crypto', () => ({ encryptEscrowBlob: async () => ({}) }));
+
+const deferred = <T>() => {
+    let resolve!: (value: T) => void;
+    const promise = new Promise<T>(done => {
+        resolve = done;
+    });
+    return { promise, resolve };
+};
+
+const setup = () => {
+    const devices = new Map<string | undefined, string>([[undefined, 'previous-share']]);
+    const storage: SSSStorageFunctions = {
+        getDeviceShare: async id => devices.get(id) ?? null,
+        hasDeviceShare: async id => devices.has(id),
+        storeDeviceShare: vi.fn(async (share, id) => {
+            devices.set(id, share);
+        }),
+        clearAllShares: vi.fn(async id => {
+            devices.delete(id);
+        }),
+        getShareVersion: async () => 1,
+        storeShareVersion: vi.fn(async () => {}),
+    };
+    const strategy = createSSSStrategy({
+        serverUrl: 'https://example.test',
+        storage,
+        escrow: {
+            enabled: true,
+            attestation: { mode: 'software', pinnedPublicKeys: ['test-key'] },
+        },
+    });
+    const enroll = () =>
+        strategy.ensureEscrowEnrollment!({
+            token: 'token',
+            providerType: 'firebase',
+            privateKey: 'a'.repeat(64),
+            signDidAuthVp: async () => 'proof',
+        });
+    return { strategy, storage, enroll };
+};
+
+const response = (body: unknown, status = 200) => new Response(JSON.stringify(body), { status });
+const keyStatus = { primaryDid: 'did:key:test', shareVersion: 1, recoveryMethods: [] };
+
+afterEach(() => {
+    vi.unstubAllGlobals();
+});
+
+describe('session-scoped enrollment writes', () => {
+    it('does not write a device share when attestation resumes after forgetting the device', async () => {
+        const { strategy, storage, enroll } = setup();
+        const started = deferred<void>();
+        const attestation = deferred<Response>();
+        vi.stubGlobal(
+            'fetch',
+            vi.fn(async (url: string) => {
+                if (url.includes('/attestation?nonce=')) {
+                    started.resolve();
+                    return attestation.promise;
+                }
+                return response(keyStatus);
+            })
+        );
+        const pending = enroll();
+        await started.promise;
+        await strategy.clearLocalKeys();
+        attestation.resolve(response({ attestation: {} }));
+        await expect(pending).rejects.toThrow();
+        expect(storage.storeDeviceShare).not.toHaveBeenCalled();
+        expect(await strategy.getLocalKey()).toBeNull();
+    });
+
+    it.each([200, 500])(
+        'blocks late version writes and rollback after server response %s',
+        async status => {
+            const { strategy, storage, enroll } = setup();
+            const started = deferred<void>();
+            const authWrite = deferred<Response>();
+            vi.stubGlobal(
+                'fetch',
+                vi.fn(async (url: string, init?: RequestInit) => {
+                    if (url.endsWith('/auth-share') && init?.method === 'PUT') {
+                        started.resolve();
+                        return authWrite.promise;
+                    }
+                    if (url.endsWith('/challenge')) return response({ challenge: 'nonce' });
+                    if (url.includes('/attestation?nonce=')) return response({ attestation: {} });
+                    return response(keyStatus);
+                })
+            );
+            const pending = enroll();
+            await started.promise;
+            expect(storage.storeDeviceShare).toHaveBeenCalledTimes(1);
+            await strategy.clearLocalKeys();
+            authWrite.resolve(response({ shareVersion: 2 }, status));
+            await expect(pending).rejects.toThrow();
+            expect(storage.storeDeviceShare).toHaveBeenCalledTimes(1);
+            expect(storage.storeShareVersion).not.toHaveBeenCalled();
+            expect(await strategy.getLocalKey()).toBeNull();
+        }
+    );
+});