@learncard/sss-key-manager 0.1.24 → 0.2.1

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,90 @@
+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',
+            previousKeyIds: [],
+            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(mode === 'software' ? 'mode mismatch' : 'nonce');
+        }
+    );
+    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,125 @@
+import { base64ToBuffer, bufferToBase64 } from './crypto';
+import type { EscrowAttestationPolicy } from './types';
+import { NitroAttestationError, verifyNitroAttestationDocument } from './escrow-nitro-attestation';
+
+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,
+    nonce?: Uint8Array
+): Promise<{
+    publicKey: string;
+    keyId: string;
+    /** P9.1: retired keyIds still accepted for decrypt. In nitro mode this is
+     * the value bound inside the signed attestation document, cross-checked
+     * against the plaintext field below — never the plaintext alone. */
+    previousKeyIds: string[];
+    mode: 'software' | 'nitro';
+}> => {
+    const isKeyId = (value: unknown): value is string =>
+        typeof value === 'string' && /^[A-Za-z0-9._-]{1,128}$/.test(value);
+    const fields = [
+        'mode',
+        'keyId',
+        'previousKeyIds',
+        'publicKey',
+        'measurements',
+        'document',
+        'issuedAt',
+    ];
+    if (
+        !isRecord(attestation) ||
+        Object.keys(attestation).some(key => !fields.includes(key)) ||
+        (attestation.mode !== 'software' && attestation.mode !== 'nitro') ||
+        !isKeyId(attestation.keyId) ||
+        (attestation.previousKeyIds !== undefined &&
+            (!Array.isArray(attestation.previousKeyIds) ||
+                attestation.previousKeyIds.length > 3 ||
+                !attestation.previousKeyIds.every(isKeyId))) ||
+        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 plaintextPreviousKeyIds = attestation.previousKeyIds ?? [];
+    if (attestation.mode !== policy.mode) throw new Error('Escrow attestation mode mismatch');
+    if (policy.mode === 'nitro') {
+        if (!nonce) throw new NitroAttestationError('nonce');
+        const verified = await verifyNitroAttestationDocument(attestation.document, {
+            expectedNonce: nonce,
+            policy,
+        });
+        try {
+            if (normalizePublicKey(attestation.publicKey) !== verified.escrowPublicKeySpkiB64) {
+                throw new NitroAttestationError('user-data');
+            }
+        } catch {
+            throw new NitroAttestationError('user-data');
+        }
+        // The wire JSON's `keyId` — the value a client actually seals new
+        // envelopes to — must match what is bound inside the signed document
+        // whenever the document carries one (legacy user_data never did, so
+        // there is nothing to cross-check there; keep today's behaviour).
+        if (verified.keyId !== undefined && verified.keyId !== attestation.keyId) {
+            throw new NitroAttestationError('user-data');
+        }
+        // Likewise the wire JSON's `previousKeyIds` must exactly match what is
+        // bound inside the signed document — never trust the plaintext value alone.
+        if (
+            plaintextPreviousKeyIds.length !== verified.previousKeyIds.length ||
+            !plaintextPreviousKeyIds.every((id, index) => id === verified.previousKeyIds[index])
+        ) {
+            throw new NitroAttestationError('user-data');
+        }
+        return {
+            publicKey: verified.escrowPublicKeySpkiB64,
+            keyId: attestation.keyId,
+            previousKeyIds: verified.previousKeyIds,
+            mode: 'nitro',
+        };
+    }
+    const publicKey = normalizePublicKey(attestation.publicKey);
+    await crypto.subtle.importKey(
+        'spki',
+        base64ToBuffer(publicKey),
+        { name: 'ECDH', namedCurve: 'P-256' },
+        false,
+        []
+    );
+    if (!policy.pinnedPublicKeys.some(pin => normalizePublicKey(pin) === publicKey)) {
+        throw new Error('Escrow attestation public key is not trusted');
+    }
+    return {
+        publicKey,
+        keyId: attestation.keyId,
+        previousKeyIds: plaintextPreviousKeyIds,
+        mode: attestation.mode,
+    };
+};