@learncard/sss-key-manager 0.1.23 → 0.2.0

package/src/escrow-pin.test.ts

@@ -0,0 +1,119 @@
+import { describe, expect, it } from 'vitest';
+
+import { base64ToBuffer, bufferToBase64, bytesToHex, deriveKeyFromPassword } from './crypto';
+import {
+    ESCROW_PIN_MAX_ATTEMPTS,
+    PIN_MAX_LENGTH,
+    PIN_MIN_LENGTH,
+    constantTimeEqualHex,
+    derivePinProof,
+    generatePinSalt,
+    normalizePin,
+    validatePin,
+} from './escrow-pin';
+
+describe('escrow PIN rules', () => {
+    it('exports the policy limits', (): void => {
+        expect(PIN_MIN_LENGTH).toBe(6);
+        expect(PIN_MAX_LENGTH).toBe(12);
+        expect(ESCROW_PIN_MAX_ATTEMPTS).toBe(10);
+    });
+
+    it.each([
+        [' 135790\n', '135790'],
+        ['13-57 90abc', '135790'],
+        ['１３５７９０', '135790'],
+        ['¹³⁵⁷⁹⁰', '135790'],
+        ['001357', '001357'],
+        ['abc! ', ''],
+    ])('normalizes %j to %j', (raw, expected): void => {
+        expect(normalizePin(raw)).toBe(expected);
+    });
+
+    it.each(['', 'abc', '13579', '1357902468135', '１２３４５'])(
+        'rejects invalid normalized length %j',
+        (pin): void => {
+            expect(validatePin(pin)).toEqual({ ok: false, reason: 'length' });
+        }
+    );
+
+    it.each([
+        '123456',
+        '654321',
+        '000000',
+        '111111',
+        '121212',
+        '112233',
+        '123123',
+        '696969',
+        '123321',
+        '999999999999',
+        '2222222',
+        '012345',
+        '2345678',
+        '0123456789',
+        '9876543210',
+        '8765432',
+        '１２３４５６',
+        ' 12-12-12 ',
+    ])('rejects trivial PIN %j', (pin): void => {
+        expect(validatePin(pin)).toEqual({ ok: false, reason: 'trivial' });
+    });
+
+    it.each(['135790', '001357', '135790246813', '1234568', '6543217', '１３５７９０'])(
+        'accepts nontrivial PIN %j',
+        (pin): void => {
+            expect(validatePin(pin)).toEqual({ ok: true });
+        }
+    );
+});
+
+describe('escrow PIN proof', () => {
+    it('generates independent 16-byte base64 salts', (): void => {
+        const salt = generatePinSalt();
+        expect(base64ToBuffer(salt)).toHaveLength(16);
+        expect(bufferToBase64(base64ToBuffer(salt).buffer)).toBe(salt);
+        expect(generatePinSalt()).not.toBe(salt);
+    });
+
+    it('is deterministic, normalized, salt-sensitive and uses the default password KDF', async (): Promise<void> => {
+        const saltBytes = new Uint8Array(16).fill(1);
+        const salt = bufferToBase64(saltBytes.buffer);
+        const proof = await derivePinProof('135790', salt);
+        expect(proof).toMatch(/^[0-9a-f]{64}$/);
+        expect(await derivePinProof(' １３-５７９０ ', salt)).toBe(proof);
+        expect(proof).toBe(bytesToHex(await deriveKeyFromPassword('135790', saltBytes)));
+        expect(
+            await derivePinProof('135790', bufferToBase64(new Uint8Array(16).fill(2).buffer))
+        ).not.toBe(proof);
+        expect(await derivePinProof('135791', salt)).not.toBe(proof);
+    });
+
+    it.each([0, 15, 17])('rejects a %i-byte salt', async (length): Promise<void> => {
+        await expect(
+            derivePinProof('135790', bufferToBase64(new Uint8Array(length).buffer))
+        ).rejects.toThrow('salt length');
+    });
+
+    it('rejects malformed base64', async (): Promise<void> => {
+        await expect(derivePinProof('135790', '!')).rejects.toThrow();
+    });
+});
+
+describe('constantTimeEqualHex', () => {
+    it.each([
+        ['ab'.repeat(32), 'ab'.repeat(32), true],
+        ['AB'.repeat(32), 'ab'.repeat(32), true],
+        ['00', '00', true],
+        ['00'.repeat(32), `01${'00'.repeat(31)}`, false],
+        ['00'.repeat(32), `${'00'.repeat(31)}01`, false],
+        ['00', '0000', false],
+        ['', '', false],
+        ['a', 'a', false],
+        ['gg', 'gg', false],
+        ['0g', '00', false],
+        ['00', '0g', false],
+    ])('compares %j and %j', (a, b, expected): void => {
+        expect(constantTimeEqualHex(a, b)).toBe(expected);
+    });
+});

package/src/escrow-pin.ts

@@ -0,0 +1,83 @@
+import {
+    base64ToBuffer,
+    bufferToBase64,
+    bytesToHex,
+    deriveKeyFromPassword,
+    hexToBytes,
+} from './crypto';
+
+export const PIN_MIN_LENGTH = 6;
+export const PIN_MAX_LENGTH = 12;
+export const ESCROW_PIN_MAX_ATTEMPTS = 10;
+
+const TRIVIAL_PINS = new Set([
+    '123456',
+    '654321',
+    '000000',
+    '111111',
+    '121212',
+    '112233',
+    '123123',
+    '696969',
+    '123321',
+]);
+
+/** Normalize compatibility digits before removing formatting and non-digits. */
+export const normalizePin = (raw: string): string =>
+    raw.trim().normalize('NFKD').replace(/\D/g, '');
+
+/** Validate the normalized PIN, rejecting full-length sequential and repeated digits. */
+export const validatePin = (
+    pin: string
+): { ok: true } | { ok: false; reason: 'length' | 'trivial' } => {
+    const normalized = normalizePin(pin);
+    if (normalized.length < PIN_MIN_LENGTH || normalized.length > PIN_MAX_LENGTH) {
+        return { ok: false, reason: 'length' };
+    }
+
+    if (
+        /^(\d)\1+$/.test(normalized) ||
+        '0123456789'.includes(normalized) ||
+        '9876543210'.includes(normalized) ||
+        TRIVIAL_PINS.has(normalized)
+    ) {
+        return { ok: false, reason: 'trivial' };
+    }
+
+    return { ok: true };
+};
+
+/** Generate a public, random 16-byte salt encoded as standard base64. */
+export const generatePinSalt = (): string =>
+    bufferToBase64(crypto.getRandomValues(new Uint8Array(16)).buffer);
+
+/** Derive the enclave proof using the shared default Argon2id parameters. */
+export const derivePinProof = async (pin: string, pinSaltBase64: string): Promise<string> => {
+    const salt = base64ToBuffer(pinSaltBase64);
+    if (salt.length !== 16) throw new Error('Invalid escrow PIN salt length');
+
+    const key = await deriveKeyFromPassword(normalizePin(pin), salt);
+    try {
+        return bytesToHex(key);
+    } finally {
+        key.fill(0);
+    }
+};
+
+/**
+ * Compare valid hex bytes without an early exit on differing contents.
+ * Format and length are public; JavaScript runtimes cannot guarantee constant-time execution.
+ */
+export const constantTimeEqualHex = (a: string, b: string): boolean => {
+    if (a.length !== b.length || !/^(?:[0-9a-f]{2})+$/i.test(a) || !/^(?:[0-9a-f]{2})+$/i.test(b)) {
+        return false;
+    }
+
+    const aBytes = hexToBytes(a);
+    const bBytes = hexToBytes(b);
+    let difference = 0;
+    for (let i = 0; i < aBytes.length; i++) {
+        difference |= aBytes[i]! ^ bBytes[i]!;
+    }
+    return difference === 0;
+};

package/src/index.ts

@@ -43,6 +43,60 @@ 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 type { EscrowAttestationPolicy, EscrowHoldStatus, EscrowRecoveryStart } from './types';
+export type { EscrowEnrollmentOptions, EscrowEnrollmentState, 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 +114,7 @@ export {
     generateRecoveryPhrase,
     validateRecoveryPhrase,
     countWords,
+    buildRecoveryPhraseChallengeOptions,
 } from './recovery-phrase';
 
 export type { RecoveryPhraseData } from './recovery-phrase';
@@ -71,6 +126,7 @@ export {
     atomicRecovery,
     ShareVerificationError,
     AtomicUpdateError,
+    ShareWriteRejectedError,
 } from './atomic-operations';
 
 export type {
@@ -79,7 +135,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 +185,7 @@ export type {
     AuthProvider,
     AuthUser,
     AuthProviderType,
+    DidAuthVpSigner,
     ContactMethod,
     ContactMethodType,
     RecoveryMethod,
@@ -134,6 +195,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.endsWith('/attestation')) {
+                    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.endsWith('/attestation')) 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();
+        }
+    );
+});