@learncard/sss-key-manager 0.1.23 → 0.2.0

package/src/critical-paths.test.ts

@@ -9,7 +9,9 @@
  * Run these tests before any release that touches SSS code.
  */
 
-import { describe, it, expect } from 'vitest';
+import 'fake-indexeddb/auto';
+import { describe, it, expect, vi } from 'vitest';
+import { createSSSStrategy } from './sss-strategy';
 
 import { splitPrivateKey, reconstructFromShares, SSS_THRESHOLD } from './sss';
 import { generateEd25519PrivateKey, encryptWithPassword, decryptWithPassword } from './crypto';
@@ -20,6 +22,54 @@ import {
 } from './recovery-phrase';
 
 describe('Critical: Key must NEVER be lost', () => {
+    it('recovers a fresh account from encrypted IndexedDB after the auth-share reply is lost', async () => {
+        const config = { serverUrl: 'https://test.invalid/api' };
+        const strategy = createSSSStrategy(config);
+        strategy.setActiveUser!('indexeddb-lost-response');
+        const privateKey = await generateEd25519PrivateKey();
+        const expectedDid = 'did:key:test-owner';
+        let authShare = '';
+        const fetchMock = vi.spyOn(globalThis, 'fetch').mockImplementation(async (_url, init) => {
+            if (init?.method === 'PUT') {
+                authShare = JSON.parse(String(init.body)).authShare.encryptedData;
+                throw new TypeError('Lost reply');
+            }
+            return new Response(
+                JSON.stringify({ authShare, shareVersion: 1, primaryDid: expectedDid })
+            );
+        });
+
+        try {
+            await expect(
+                strategy.atomicUpdateShares!({
+                    token: 'token',
+                    providerType: 'firebase',
+                    privateKey,
+                    did: expectedDid,
+                })
+            ).rejects.toMatchObject({ rolledBack: false });
+
+            const reloaded = createSSSStrategy(config);
+            reloaded.setActiveUser!('indexeddb-lost-response');
+            expect(await reloaded.hasLocalKey()).toBe(true);
+            const result = await reloaded.reconcileShares!({
+                token: 'token',
+                providerType: 'firebase',
+                expectedDid,
+                didFromPrivateKey: async key =>
+                    key === privateKey ? expectedDid : 'did:key:wrong',
+            });
+            expect(result).toEqual({ privateKey, did: expectedDid });
+            expect(await reloaded.getLocalShareVersion!()).toBe(1);
+            expect(await reconstructFromShares([(await reloaded.getLocalKey())!, authShare])).toBe(
+                privateKey
+            );
+        } finally {
+            fetchMock.mockRestore();
+            await strategy.clearLocalKeys();
+        }
+    });
+
     describe('Share split verification (fuzz test)', () => {
         it('should verify all 6 share combinations reconstruct the key (100 iterations)', async () => {
             for (let i = 0; i < 100; i++) {

package/src/email-relay-crypto.test.ts

@@ -0,0 +1,87 @@
+import { beforeAll, describe, expect, it } from 'vitest';
+
+import { bufferToBase64 } from './crypto';
+import {
+    decryptEmailRelayPayload,
+    encryptEmailRelayPayload,
+    generateEmailRelayConfirmationCode,
+} from './email-relay-crypto';
+
+describe('email relay encryption', () => {
+    let publicKeyBase64 = '';
+    let privateKeyBase64 = '';
+
+    beforeAll(async () => {
+        const keyPair = await crypto.subtle.generateKey(
+            { name: 'ECDH', namedCurve: 'P-256' },
+            true,
+            ['deriveBits']
+        );
+        const [publicKey, privateKey] = await Promise.all([
+            crypto.subtle.exportKey('spki', keyPair.publicKey),
+            crypto.subtle.exportKey('pkcs8', keyPair.privateKey),
+        ]);
+
+        publicKeyBase64 = bufferToBase64(publicKey);
+        privateKeyBase64 = bufferToBase64(privateKey);
+    });
+
+    it('sends no raw recovery key and round-trips with the relay private key', async () => {
+        const recoveryKey = `0001${'ab'.repeat(48)}`;
+        const confirmationCode = '483920';
+        const envelope = await encryptEmailRelayPayload(
+            {
+                targetEmail: 'Recovery@Example.com',
+                recoveryKey,
+                confirmationCode,
+                branding: { brandName: 'Test Tenant', fromDomain: 'example.com' },
+            },
+            publicKeyBase64,
+            'test-key-1'
+        );
+
+        expect(JSON.stringify(envelope)).not.toContain(recoveryKey);
+        expect(JSON.stringify(envelope)).not.toContain(confirmationCode);
+        await expect(decryptEmailRelayPayload(envelope, privateKeyBase64)).resolves.toEqual({
+            version: 1,
+            targetEmail: 'recovery@example.com',
+            recoveryKey,
+            confirmationCode,
+            branding: { brandName: 'Test Tenant', fromDomain: 'example.com' },
+        });
+    });
+
+    it('authenticates envelope metadata and ciphertext', async () => {
+        const envelope = await encryptEmailRelayPayload(
+            {
+                targetEmail: 'recovery@example.com',
+                recoveryKey: `0002${'cd'.repeat(48)}`,
+                confirmationCode: '123456',
+            },
+            publicKeyBase64,
+            'test-key-1'
+        );
+
+        await expect(
+            decryptEmailRelayPayload({ ...envelope, keyId: 'other-key' }, privateKeyBase64)
+        ).rejects.toThrow();
+
+        const lastCharacter = envelope.ciphertext.at(-1);
+        const tamperedCiphertext = `${envelope.ciphertext.slice(0, -1)}${
+            lastCharacter === 'A' ? 'B' : 'A'
+        }`;
+
+        await expect(
+            decryptEmailRelayPayload(
+                { ...envelope, ciphertext: tamperedCiphertext },
+                privateKeyBase64
+            )
+        ).rejects.toThrow();
+    });
+
+    it('generates exactly six decimal digits', () => {
+        const codes = Array.from({ length: 100 }, generateEmailRelayConfirmationCode);
+
+        expect(codes.every(code => /^\d{6}$/.test(code))).toBe(true);
+    });
+});

package/src/email-relay-crypto.ts

@@ -0,0 +1,293 @@
+/**
+ * Browser-compatible encryption for recovery-key delivery.
+ *
+ * This is an HPKE-style construction using Web Crypto primitives:
+ * ephemeral P-256 ECDH, HKDF-SHA-256, and AES-256-GCM. The relay public key
+ * is pinned in tenant/runtime configuration; only the isolated relay has the
+ * matching PKCS#8 private key.
+ */
+
+import { base64ToBuffer, bufferToBase64 } from './crypto';
+
+export const EMAIL_RELAY_ENVELOPE_VERSION = 1 as const;
+export const EMAIL_RELAY_ALGORITHM = 'P-256-HKDF-SHA256-AES-256-GCM' as const;
+
+const encodeUtf8 = (value: string): Uint8Array<ArrayBuffer> => {
+    const bytes = new TextEncoder().encode(value);
+    const copy = new Uint8Array(new ArrayBuffer(bytes.byteLength));
+    copy.set(bytes);
+    return copy;
+};
+
+const EMAIL_RELAY_INFO = encodeUtf8('learncard-email-relay-v1');
+const SIX_DIGIT_CODE_RANGE = 900_000;
+const UINT32_RANGE = 0x1_0000_0000;
+const MAX_UNBIASED_UINT32 = Math.floor(UINT32_RANGE / SIX_DIGIT_CODE_RANGE) * SIX_DIGIT_CODE_RANGE;
+
+export interface EmailRelayBranding {
+    brandName?: string;
+    logoUrl?: string;
+    logoAlt?: string;
+    primaryColor?: string;
+    primaryTextColor?: string;
+    supportEmail?: string;
+    websiteUrl?: string;
+    appUrl?: string;
+    fromDomain?: string;
+    copyrightHolder?: string;
+}
+
+export interface EmailRelayPlaintext {
+    version: typeof EMAIL_RELAY_ENVELOPE_VERSION;
+    targetEmail: string;
+    recoveryKey: string;
+    confirmationCode: string;
+    branding?: EmailRelayBranding;
+}
+
+export interface EmailRelayEnvelope {
+    version: typeof EMAIL_RELAY_ENVELOPE_VERSION;
+    algorithm: typeof EMAIL_RELAY_ALGORITHM;
+    keyId: string;
+    ephemeralPublicKey: string;
+    salt: string;
+    iv: string;
+    ciphertext: string;
+}
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+    typeof value === 'object' && value !== null && !Array.isArray(value);
+
+const requireString = (
+    record: Record<string, unknown>,
+    key: string,
+    options: { min?: number; max: number; pattern?: RegExp }
+): string => {
+    const value = record[key];
+
+    if (
+        typeof value !== 'string' ||
+        value.length < (options.min ?? 1) ||
+        value.length > options.max ||
+        (options.pattern && !options.pattern.test(value))
+    ) {
+        throw new Error(`Invalid email relay ${key}`);
+    }
+
+    return value;
+};
+
+const parseBranding = (value: unknown): EmailRelayBranding | undefined => {
+    if (value === undefined) return undefined;
+    if (!isRecord(value)) throw new Error('Invalid email relay branding');
+
+    const branding: EmailRelayBranding = {};
+    const keys = [
+        'brandName',
+        'logoUrl',
+        'logoAlt',
+        'primaryColor',
+        'primaryTextColor',
+        'supportEmail',
+        'websiteUrl',
+        'appUrl',
+        'fromDomain',
+        'copyrightHolder',
+    ] as const;
+
+    for (const key of keys) {
+        const field = value[key];
+
+        if (field === undefined) continue;
+        if (typeof field !== 'string' || field.length > 2_048) {
+            throw new Error(`Invalid email relay branding.${key}`);
+        }
+
+        branding[key] = field;
+    }
+
+    return branding;
+};
+
+/** Validate an untrusted encrypted envelope before attempting decryption. */
+export const parseEmailRelayEnvelope = (value: unknown): EmailRelayEnvelope => {
+    if (!isRecord(value)) throw new Error('Invalid email relay envelope');
+    if (value.version !== EMAIL_RELAY_ENVELOPE_VERSION) {
+        throw new Error('Unsupported email relay envelope version');
+    }
+    if (value.algorithm !== EMAIL_RELAY_ALGORITHM) {
+        throw new Error('Unsupported email relay algorithm');
+    }
+
+    return {
+        version: EMAIL_RELAY_ENVELOPE_VERSION,
+        algorithm: EMAIL_RELAY_ALGORITHM,
+        keyId: requireString(value, 'keyId', {
+            max: 128,
+            pattern: /^[A-Za-z0-9._-]+$/,
+        }),
+        ephemeralPublicKey: requireString(value, 'ephemeralPublicKey', { max: 256 }),
+        salt: requireString(value, 'salt', { max: 128 }),
+        iv: requireString(value, 'iv', { max: 64 }),
+        ciphertext: requireString(value, 'ciphertext', { max: 16_384 }),
+    };
+};
+
+/** Validate decrypted relay plaintext and copy only recognized fields. */
+export const parseEmailRelayPlaintext = (value: unknown): EmailRelayPlaintext => {
+    if (!isRecord(value) || value.version !== EMAIL_RELAY_ENVELOPE_VERSION) {
+        throw new Error('Invalid email relay plaintext');
+    }
+
+    return {
+        version: EMAIL_RELAY_ENVELOPE_VERSION,
+        targetEmail: requireString(value, 'targetEmail', {
+            max: 320,
+            pattern: /^[^\s@]+@[^\s@]+\.[^\s@]+$/,
+        })
+            .trim()
+            .toLowerCase(),
+        recoveryKey: requireString(value, 'recoveryKey', {
+            min: 5,
+            max: 4_096,
+            pattern: /^[0-9a-f]+$/i,
+        }),
+        confirmationCode: requireString(value, 'confirmationCode', {
+            max: 6,
+            pattern: /^\d{6}$/,
+        }),
+        branding: parseBranding(value.branding),
+    };
+};
+
+const getAad = (
+    envelope: Pick<EmailRelayEnvelope, 'version' | 'algorithm' | 'keyId'>
+): Uint8Array<ArrayBuffer> =>
+    encodeUtf8(`${envelope.version}|${envelope.algorithm}|${envelope.keyId}`);
+
+const deriveAesKey = async (
+    sharedSecret: ArrayBuffer,
+    salt: Uint8Array<ArrayBuffer>,
+    usage: KeyUsage
+): Promise<CryptoKey> => {
+    const keyMaterial = await crypto.subtle.importKey('raw', sharedSecret, 'HKDF', false, [
+        'deriveKey',
+    ]);
+
+    return crypto.subtle.deriveKey(
+        { name: 'HKDF', hash: 'SHA-256', salt, info: EMAIL_RELAY_INFO },
+        keyMaterial,
+        { name: 'AES-GCM', length: 256 },
+        false,
+        [usage]
+    );
+};
+
+/** Generate a uniformly distributed six-digit confirmation code in the browser. */
+export const generateEmailRelayConfirmationCode = (): string => {
+    const random = new Uint32Array(1);
+    let value: number;
+
+    do {
+        crypto.getRandomValues(random);
+        value = random[0] ?? UINT32_RANGE;
+    } while (value >= MAX_UNBIASED_UINT32);
+
+    return String(100_000 + (value % SIX_DIGIT_CODE_RANGE));
+};
+
+/** Encrypt a complete recovery-email payload to a pinned relay SPKI public key. */
+export const encryptEmailRelayPayload = async (
+    input: Omit<EmailRelayPlaintext, 'version'>,
+    publicKeyBase64: string,
+    keyId: string
+): Promise<EmailRelayEnvelope> => {
+    const plaintext = parseEmailRelayPlaintext({
+        ...input,
+        version: EMAIL_RELAY_ENVELOPE_VERSION,
+    });
+    const normalizedKeyId = keyId.trim();
+
+    if (!publicKeyBase64.trim()) throw new Error('Email relay public key is not configured');
+    if (!/^[A-Za-z0-9._-]{1,128}$/.test(normalizedKeyId)) {
+        throw new Error('Email relay key ID is not configured');
+    }
+
+    const recipientPublicKey = await crypto.subtle.importKey(
+        'spki',
+        base64ToBuffer(publicKeyBase64.trim()).buffer as ArrayBuffer,
+        { name: 'ECDH', namedCurve: 'P-256' },
+        false,
+        []
+    );
+    const ephemeralKeyPair = await crypto.subtle.generateKey(
+        { name: 'ECDH', namedCurve: 'P-256' },
+        true,
+        ['deriveBits']
+    );
+    const sharedSecret = await crypto.subtle.deriveBits(
+        { name: 'ECDH', public: recipientPublicKey },
+        ephemeralKeyPair.privateKey,
+        256
+    );
+    const salt = crypto.getRandomValues(new Uint8Array(32));
+    const iv = crypto.getRandomValues(new Uint8Array(12));
+    const aesKey = await deriveAesKey(sharedSecret, salt, 'encrypt');
+    const envelopeMetadata = {
+        version: EMAIL_RELAY_ENVELOPE_VERSION,
+        algorithm: EMAIL_RELAY_ALGORITHM,
+        keyId: normalizedKeyId,
+    };
+    const ciphertext = await crypto.subtle.encrypt(
+        { name: 'AES-GCM', iv, additionalData: getAad(envelopeMetadata) },
+        aesKey,
+        encodeUtf8(JSON.stringify(plaintext))
+    );
+    const ephemeralPublicKey = await crypto.subtle.exportKey('raw', ephemeralKeyPair.publicKey);
+
+    return {
+        ...envelopeMetadata,
+        ephemeralPublicKey: bufferToBase64(ephemeralPublicKey),
+        salt: bufferToBase64(salt.buffer),
+        iv: bufferToBase64(iv.buffer),
+        ciphertext: bufferToBase64(ciphertext),
+    };
+};
+
+/** Decrypt an envelope using the relay's PKCS#8 P-256 private key. */
+export const decryptEmailRelayPayload = async (
+    value: unknown,
+    privateKeyBase64: string
+): Promise<EmailRelayPlaintext> => {
+    const envelope = parseEmailRelayEnvelope(value);
+    const privateKey = await crypto.subtle.importKey(
+        'pkcs8',
+        base64ToBuffer(privateKeyBase64.trim()).buffer as ArrayBuffer,
+        { name: 'ECDH', namedCurve: 'P-256' },
+        false,
+        ['deriveBits']
+    );
+    const ephemeralPublicKey = await crypto.subtle.importKey(
+        'raw',
+        base64ToBuffer(envelope.ephemeralPublicKey).buffer as ArrayBuffer,
+        { name: 'ECDH', namedCurve: 'P-256' },
+        false,
+        []
+    );
+    const sharedSecret = await crypto.subtle.deriveBits(
+        { name: 'ECDH', public: ephemeralPublicKey },
+        privateKey,
+        256
+    );
+    const salt = base64ToBuffer(envelope.salt);
+    const iv = base64ToBuffer(envelope.iv);
+    const aesKey = await deriveAesKey(sharedSecret, salt, 'decrypt');
+    const decrypted = await crypto.subtle.decrypt(
+        { name: 'AES-GCM', iv, additionalData: getAad(envelope) },
+        aesKey,
+        base64ToBuffer(envelope.ciphertext)
+    );
+    const parsed: unknown = JSON.parse(new TextDecoder().decode(decrypted));
+
+    return parseEmailRelayPlaintext(parsed);
+};

package/src/escrow-attestation.test.ts

@@ -0,0 +1,85 @@
+import { beforeAll, describe, expect, it } from 'vitest';
+import { generateEscrowKeyPair } from './escrow-crypto';
+import { verifyEnclaveAttestation } from './escrow-attestation';
+
+describe('verifyEnclaveAttestation', () => {
+    let publicKey: string;
+    beforeAll(async () => {
+        publicKey = (await generateEscrowKeyPair()).publicKey;
+    });
+    const attestation = () => ({
+        mode: 'software',
+        keyId: 'test-key',
+        publicKey,
+        measurements: {},
+        document: 'e30=',
+        issuedAt: new Date().toISOString(),
+    });
+
+    it('accepts a pinned software key with surrounding whitespace', async () => {
+        await expect(
+            verifyEnclaveAttestation(
+                { ...attestation(), publicKey: ` ${publicKey}\n` },
+                { mode: 'software', pinnedPublicKeys: [`\n${publicKey} `] }
+            )
+        ).resolves.toEqual({ mode: 'software', keyId: 'test-key', publicKey });
+    });
+    it('rejects an unknown key', async () => {
+        await expect(
+            verifyEnclaveAttestation(attestation(), {
+                mode: 'software',
+                pinnedPublicKeys: [(await generateEscrowKeyPair()).publicKey],
+            })
+        ).rejects.toThrow('not trusted');
+    });
+    it('rejects nitro under software policy', async () => {
+        await expect(
+            verifyEnclaveAttestation(
+                { ...attestation(), mode: 'nitro' },
+                { mode: 'software', pinnedPublicKeys: [publicKey] }
+            )
+        ).rejects.toThrow('mode mismatch');
+    });
+    it.each(['software', 'nitro'])(
+        'fails closed under nitro policy (%s attestation)',
+        async mode => {
+            await expect(
+                verifyEnclaveAttestation(
+                    { ...attestation(), mode },
+                    { mode: 'nitro', pinnedMeasurements: [] }
+                )
+            ).rejects.toThrow('Nitro attestation verification is not implemented yet');
+        }
+    );
+    it.each([
+        { publicKey: 'e30=' },
+        { publicKey: 'not-base64' },
+        { keyId: 'invalid/key' },
+        { mode: 'unknown' },
+        { measurements: [] },
+        { measurements: { unknown: 'value' } },
+        { document: 3 },
+        { issuedAt: 'not-a-date' },
+        { extra: true },
+    ])('rejects malformed attestation %j', async overrides => {
+        await expect(
+            verifyEnclaveAttestation(
+                { ...attestation(), ...overrides },
+                { mode: 'software', pinnedPublicKeys: [publicKey] }
+            )
+        ).rejects.toThrow();
+    });
+    it('rejects SPKI on another curve', async () => {
+        const pair = await crypto.subtle.generateKey({ name: 'ECDH', namedCurve: 'P-384' }, true, [
+            'deriveBits',
+        ]);
+        const spki = await crypto.subtle.exportKey('spki', pair.publicKey);
+        const key = btoa(String.fromCharCode(...new Uint8Array(spki)));
+        await expect(
+            verifyEnclaveAttestation(
+                { ...attestation(), publicKey: key },
+                { mode: 'software', pinnedPublicKeys: [key] }
+            )
+        ).rejects.toThrow();
+    });
+});

package/src/escrow-attestation.ts

@@ -0,0 +1,64 @@
+import { base64ToBuffer, bufferToBase64 } from './crypto';
+import type { EscrowAttestationPolicy } from './types';
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+    typeof value === 'object' && value !== null && !Array.isArray(value);
+
+const normalizePublicKey = (value: string): string => {
+    const trimmed = value.trim();
+    if (
+        !trimmed ||
+        trimmed.length > 512 ||
+        !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(trimmed)
+    ) {
+        throw new Error('Invalid escrow attestation public key');
+    }
+    return bufferToBase64(base64ToBuffer(trimmed).buffer);
+};
+
+/** Parse untrusted attestation data and enforce an explicit enclave trust policy. */
+export const verifyEnclaveAttestation = async (
+    attestation: unknown,
+    policy: EscrowAttestationPolicy
+): Promise<{ publicKey: string; keyId: string; mode: 'software' | 'nitro' }> => {
+    const fields = ['mode', 'keyId', 'publicKey', 'measurements', 'document', 'issuedAt'];
+    if (
+        !isRecord(attestation) ||
+        Object.keys(attestation).some(key => !fields.includes(key)) ||
+        (attestation.mode !== 'software' && attestation.mode !== 'nitro') ||
+        typeof attestation.keyId !== 'string' ||
+        !/^[A-Za-z0-9._-]{1,128}$/.test(attestation.keyId) ||
+        typeof attestation.publicKey !== 'string' ||
+        !isRecord(attestation.measurements) ||
+        Object.entries(attestation.measurements).some(
+            ([key, value]) =>
+                !['imageSha384', 'pcr0', 'pcr1', 'pcr2'].includes(key) ||
+                typeof value !== 'string' ||
+                !value ||
+                value.length > 1024
+        ) ||
+        typeof attestation.document !== 'string' ||
+        !attestation.document ||
+        attestation.document.length > 65536 ||
+        typeof attestation.issuedAt !== 'string' ||
+        !Number.isFinite(Date.parse(attestation.issuedAt))
+    ) {
+        throw new Error('Invalid escrow attestation');
+    }
+    const publicKey = normalizePublicKey(attestation.publicKey);
+    await crypto.subtle.importKey(
+        'spki',
+        base64ToBuffer(publicKey),
+        { name: 'ECDH', namedCurve: 'P-256' },
+        false,
+        []
+    );
+    if (policy.mode === 'nitro') {
+        throw new Error('Nitro attestation verification is not implemented yet');
+    }
+    if (attestation.mode !== policy.mode) throw new Error('Escrow attestation mode mismatch');
+    if (!policy.pinnedPublicKeys.some(pin => normalizePublicKey(pin) === publicKey)) {
+        throw new Error('Escrow attestation public key is not trusted');
+    }
+    return { publicKey, keyId: attestation.keyId, mode: attestation.mode };
+};