@learncard/sss-key-manager 0.1.24 → 0.2.1

package/src/escrow-nitro-attestation.test.ts

@@ -0,0 +1,204 @@
+// @vitest-environment node
+import { readFileSync, readdirSync } from 'node:fs';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { decode, encode } from 'cborg';
+import { base64ToBuffer, bufferToBase64 } from './crypto';
+import { NitroAttestationError, verifyNitroAttestationDocument } from './escrow-nitro-attestation';
+import { verifyEnclaveAttestation } from './escrow-attestation';
+import manifest from './__fixtures__/nitro-attestation/manifest.json';
+import type { EscrowAttestationPolicy } from './types';
+
+const directory = new URL('./__fixtures__/nitro-attestation/', import.meta.url);
+const fixture = (name: string): string =>
+    readFileSync(new URL(`${name}.cbor.b64`, directory), 'utf8').trim();
+const nonce = Uint8Array.from(manifest.nonceHex.match(/../g)!, byte => parseInt(byte, 16));
+const measurement = { pcr0: manifest.pcrs[0], pcr1: manifest.pcrs[1], pcr2: manifest.pcrs[2] };
+const policy: Extract<EscrowAttestationPolicy, { mode: 'nitro' }> = {
+    mode: 'nitro',
+    pinnedMeasurements: [measurement],
+    rootCertificateSha256: manifest.rootSha256,
+};
+const options = { expectedNonce: nonce, policy, now: manifest.nowMs };
+const reasonMap: Record<string, string> = {
+    'debug PCRs': 'debug',
+    'missing intermediate': 'chain',
+    'root pin': 'root',
+};
+
+describe('FakeNsm Nitro attestation', () => {
+    afterEach(() => vi.restoreAllMocks());
+    it('covers every committed document fixture', () => {
+        expect(
+            readdirSync(directory)
+                .filter(file => file.endsWith('.cbor.b64'))
+                .sort()
+        ).toEqual(
+            Object.keys(manifest.cases)
+                .map(name => `${name}.cbor.b64`)
+                .sort()
+        );
+    });
+    for (const [name, testCase] of Object.entries(manifest.cases)) {
+        it(name, async () => {
+            const expectedNonce =
+                'nonceHex' in testCase
+                    ? Uint8Array.from(testCase.nonceHex.match(/../g)!, byte => parseInt(byte, 16))
+                    : nonce;
+            const result = verifyNitroAttestationDocument(fixture(name), {
+                ...options,
+                expectedNonce,
+            });
+            if (testCase.accept) {
+                await expect(result).resolves.toMatchObject({
+                    escrowPublicKeySpkiB64: manifest.userDataBase64,
+                    timestamp: manifest.timestamp,
+                    pcrs: manifest.pcrs,
+                    previousKeyIds:
+                        'previousKeyIds' in testCase
+                            ? testCase.previousKeyIds
+                            : manifest.previousKeyIds,
+                });
+            } else if ('reason' in testCase) {
+                await expect(result).rejects.toMatchObject({
+                    name: 'NitroAttestationError',
+                    reason: reasonMap[testCase.reason] ?? testCase.reason,
+                });
+            }
+        });
+    }
+    it('accepts an optional outer tag 18', async () => {
+        const tagged = new Uint8Array([0xd2, ...base64ToBuffer(fixture('valid'))]);
+        await expect(
+            verifyNitroAttestationDocument(bufferToBase64(tagged.buffer), options)
+        ).resolves.toBeDefined();
+    });
+    it('rejects cross-combinations of pinned tuples', async () => {
+        await expect(
+            verifyNitroAttestationDocument(fixture('valid'), {
+                ...options,
+                policy: {
+                    ...policy,
+                    pinnedMeasurements: [
+                        { ...measurement, pcr1: 'ff'.repeat(48) },
+                        { ...measurement, pcr0: 'ff'.repeat(48) },
+                    ],
+                },
+            })
+        ).rejects.toMatchObject({ reason: 'pcr' });
+    });
+    it('rejects legacy image-only pins', async () => {
+        await expect(
+            verifyNitroAttestationDocument(fixture('valid'), {
+                ...options,
+                policy: {
+                    ...policy,
+                    pinnedMeasurements: [{ imageSha384: measurement.pcr0 }],
+                },
+            })
+        ).rejects.toMatchObject({ reason: 'pcr' });
+    });
+    it('rejects unknown algorithms before signature verification', async () => {
+        const cose: unknown[] = decode(base64ToBuffer(fixture('valid')), { useMaps: true });
+        cose[0] = encode(new Map([[1, -7]]));
+        await expect(
+            verifyNitroAttestationDocument(
+                bufferToBase64(new Uint8Array(encode(cose)).buffer),
+                options
+            )
+        ).rejects.toMatchObject({ reason: 'alg' });
+    });
+    it('rejects the fake root under the default AWS pin', async () => {
+        await expect(
+            verifyNitroAttestationDocument(fixture('valid'), {
+                ...options,
+                policy: {
+                    mode: 'nitro',
+                    pinnedMeasurements: [measurement],
+                },
+            })
+        ).rejects.toMatchObject({ reason: 'root' });
+    });
+    it('enforces clock skew and configurable freshness', async () => {
+        await expect(
+            verifyNitroAttestationDocument(fixture('valid'), {
+                ...options,
+                now: manifest.timestamp - 60001,
+            })
+        ).rejects.toMatchObject({ reason: 'freshness' });
+        await expect(
+            verifyNitroAttestationDocument(fixture('valid'), {
+                ...options,
+                policy: { ...policy, maxAgeMs: 999 },
+            })
+        ).rejects.toMatchObject({ reason: 'freshness' });
+    });
+    it('returns typed CBOR errors', async () => {
+        await expect(verifyNitroAttestationDocument('bad!', options)).rejects.toBeInstanceOf(
+            NitroAttestationError
+        );
+        await expect(verifyNitroAttestationDocument('bad!', options)).rejects.toMatchObject({
+            reason: 'cbor',
+        });
+    });
+    it('binds the wrapper public key to user_data, ignoring unsigned measurements', async () => {
+        vi.spyOn(Date, 'now').mockReturnValue(manifest.nowMs);
+        const attestation = {
+            mode: 'nitro',
+            keyId: manifest.keyId,
+            previousKeyIds: manifest.previousKeyIds,
+            publicKey: manifest.userDataBase64,
+            document: fixture('valid'),
+            measurements: { pcr0: 'untrusted' },
+            issuedAt: new Date(manifest.nowMs).toISOString(),
+        };
+        await expect(verifyEnclaveAttestation(attestation, policy, nonce)).resolves.toEqual({
+            mode: 'nitro',
+            keyId: manifest.keyId,
+            previousKeyIds: manifest.previousKeyIds,
+            publicKey: manifest.userDataBase64,
+        });
+        await expect(
+            verifyEnclaveAttestation({ ...attestation, publicKey: 'e30=' }, policy, nonce)
+        ).rejects.toMatchObject({ reason: 'user-data' });
+        await expect(verifyEnclaveAttestation(attestation, policy)).rejects.toMatchObject({
+            reason: 'nonce',
+        });
+    });
+    // P9.2: the plaintext wire `keyId` — what a client actually seals new
+    // envelopes to — must exactly match what is bound inside the signed
+    // document; a divergent (tampered, or simply stale) plaintext keyId is
+    // rejected the same way a wrong public key is.
+    it('rejects a keyId that diverges from the signed document', async () => {
+        vi.spyOn(Date, 'now').mockReturnValue(manifest.nowMs);
+        const attestation = {
+            mode: 'nitro',
+            keyId: 'not-the-attested-key',
+            previousKeyIds: manifest.previousKeyIds,
+            publicKey: manifest.userDataBase64,
+            document: fixture('valid'),
+            measurements: {},
+            issuedAt: new Date(manifest.nowMs).toISOString(),
+        };
+        await expect(verifyEnclaveAttestation(attestation, policy, nonce)).rejects.toMatchObject({
+            reason: 'user-data',
+        });
+    });
+    // P9.2: the plaintext wire field must exactly match what is bound inside
+    // the signed document — a divergent (tampered, or simply stale) plaintext
+    // previousKeyIds is rejected the same way a wrong public key is.
+    it('rejects a previousKeyIds that diverges from the signed document', async () => {
+        vi.spyOn(Date, 'now').mockReturnValue(manifest.nowMs);
+        const attestation = {
+            mode: 'nitro',
+            keyId: manifest.keyId,
+            previousKeyIds: ['not-the-attested-list'],
+            publicKey: manifest.userDataBase64,
+            document: fixture('valid'),
+            measurements: {},
+            issuedAt: new Date(manifest.nowMs).toISOString(),
+        };
+        await expect(verifyEnclaveAttestation(attestation, policy, nonce)).rejects.toMatchObject({
+            reason: 'user-data',
+        });
+    });
+});

package/src/escrow-nitro-attestation.ts

@@ -0,0 +1,286 @@
+import 'reflect-metadata';
+import { decode, encode } from 'cborg';
+import {
+    BasicConstraintsExtension,
+    KeyUsagesExtension,
+    KeyUsageFlags,
+    X509Certificate,
+} from '@peculiar/x509';
+import { base64ToBuffer, bufferToBase64 } from './crypto';
+import type { EscrowAttestationPolicy } from './types';
+
+export type NitroAttestationReason =
+    | 'cbor'
+    | 'cose'
+    | 'alg'
+    | 'chain'
+    | 'root'
+    | 'signature'
+    | 'pcr'
+    | 'debug'
+    | 'nonce'
+    | 'freshness'
+    | 'user-data';
+
+/** A fail-closed attestation failure with a stable, non-sensitive reason. */
+export class NitroAttestationError extends Error {
+    constructor(public readonly reason: NitroAttestationReason) {
+        super(`Nitro attestation rejected: ${reason}`);
+        this.name = 'NitroAttestationError';
+    }
+}
+
+const AWS_ROOT_SHA256 = '641a0321a3e244efe456463195d606317ed7cdcc3c1756e09893f3c68f79bb5b';
+type NitroPolicy = Extract<EscrowAttestationPolicy, { mode: 'nitro' }>;
+const fail: (reason: NitroAttestationReason) => never = reason => {
+    throw new NitroAttestationError(reason);
+};
+const hex = (bytes: Uint8Array): string =>
+    Array.from(bytes, byte => byte.toString(16).padStart(2, '0')).join('');
+const bytes = (value: unknown, reason: NitroAttestationReason): Uint8Array =>
+    value instanceof Uint8Array && value.length > 0 ? value : fail(reason);
+const map = (value: unknown, reason: NitroAttestationReason): Map<unknown, unknown> =>
+    value instanceof Map ? value : fail(reason);
+const decodeCbor = (value: Uint8Array): unknown => {
+    try {
+        return decode(value, {
+            useMaps: true,
+            rejectDuplicateMapKeys: true,
+            allowIndefinite: false,
+            allowUndefined: false,
+            allowNaN: false,
+            allowInfinity: false,
+            allowBigInt: false,
+        });
+    } catch {
+        return fail('cbor');
+    }
+};
+
+/**
+ * P9.1: `user_data` is either the legacy raw SPKI DER (older enclave builds,
+ * accepted during the rollout transition), or a canonical CBOR map
+ * `{0: spki bytes, 1: keyId text, 2: previousKeyIds array<text>}` produced by
+ * `server::attest_user_data` in the enclave. Real P-256 SPKI DER always
+ * starts with the SEQUENCE tag `0x30`, which CBOR decodes as a bare negative
+ * integer (major type 1), never a 3-entry map — so requiring BOTH "decodes as
+ * CBOR" AND "is a map with exactly these three well-typed entries" safely
+ * disambiguates without any separate version marker. A non-throwing probe
+ * (unlike `decodeCbor`/`fail`, whose failure IS the production error path
+ * elsewhere in this file): failing to match either check here means "legacy
+ * format", not "malformed attestation".
+ */
+const decodeUserData = (
+    userData: Uint8Array
+): { spki: Uint8Array; keyId: string; previousKeyIds: string[] } | undefined => {
+    let decoded: unknown;
+    try {
+        decoded = decode(userData, {
+            useMaps: true,
+            rejectDuplicateMapKeys: true,
+            allowIndefinite: false,
+            allowUndefined: false,
+            allowNaN: false,
+            allowInfinity: false,
+            allowBigInt: false,
+        });
+    } catch {
+        return undefined;
+    }
+    if (!(decoded instanceof Map) || decoded.size !== 3) return undefined;
+    const spki = decoded.get(0);
+    const keyId = decoded.get(1);
+    const previousKeyIds = decoded.get(2);
+    const isKeyId = (value: unknown): value is string =>
+        typeof value === 'string' && /^[A-Za-z0-9._-]{1,128}$/.test(value);
+    if (
+        !(spki instanceof Uint8Array) ||
+        spki.length === 0 ||
+        !isKeyId(keyId) ||
+        !Array.isArray(previousKeyIds) ||
+        previousKeyIds.length > 3 ||
+        !previousKeyIds.every(isKeyId)
+    ) {
+        return undefined;
+    }
+    return { spki, keyId, previousKeyIds };
+};
+
+/** Verify signed NSM evidence before trusting its P-256 escrow key (not public_key/KMS key). */
+export const verifyNitroAttestationDocument = async (
+    documentB64: string,
+    {
+        expectedNonce,
+        policy,
+        now = Date.now(),
+    }: {
+        expectedNonce: Uint8Array;
+        policy: NitroPolicy;
+        now?: number;
+    }
+): Promise<{
+    escrowPublicKeySpkiB64: string;
+    /** P9.1: the enclave's own current keyId, bound inside this same signed
+     * document. `undefined` for the legacy user_data format, which never
+     * carried a keyId — callers must not silently trust a plaintext keyId in
+     * that case any more than they did before this field existed. */
+    keyId: string | undefined;
+    /** P9.1: retired keyIds the enclave still accepts for decrypt only, bound
+     * inside this same signed document. Empty for the legacy user_data format. */
+    previousKeyIds: string[];
+    pcrs: Record<number, string>;
+    timestamp: number;
+    moduleId: string;
+}> => {
+    let document: Uint8Array;
+    try {
+        if (
+            !documentB64 ||
+            documentB64.length > 65536 ||
+            !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(documentB64)
+        )
+            fail('cbor');
+        document = base64ToBuffer(documentB64);
+    } catch {
+        return fail('cbor');
+    }
+    // Only an outer COSE_Sign1 tag is permitted; tags within headers/payload are rejected.
+    const cose = decodeCbor(document[0] === 0xd2 ? document.subarray(1) : document);
+    if (!Array.isArray(cose) || cose.length !== 4) fail('cose');
+    const [protectedValue, unprotectedValue, payloadValue, signatureValue] = cose;
+    const protectedBytes = bytes(protectedValue, 'cose');
+    const protectedHeader = map(decodeCbor(protectedBytes), 'alg');
+    if (protectedHeader.size !== 1 || protectedHeader.get(1) !== -35) fail('alg');
+    if (map(unprotectedValue, 'cose').size !== 0) fail('cose');
+    const payloadBytes = bytes(payloadValue, 'cose');
+    const signature = bytes(signatureValue, 'signature');
+    if (signature.length !== 96) fail('signature');
+    const payload = map(decodeCbor(payloadBytes), 'cbor');
+    const moduleId = payload.get('module_id');
+    const timestamp = payload.get('timestamp');
+    if (typeof moduleId !== 'string' || !moduleId || payload.get('digest') !== 'SHA384')
+        fail('cbor');
+    if (typeof timestamp !== 'number' || !Number.isSafeInteger(timestamp) || timestamp < 0)
+        fail('freshness');
+    const leafDer = bytes(payload.get('certificate'), 'chain');
+    const bundle = payload.get('cabundle');
+    if (!Array.isArray(bundle) || !bundle.length || bundle.length > 16) fail('chain');
+    const ders = bundle.map(value => bytes(value, 'chain'));
+    const rootHash = hex(
+        new Uint8Array(await crypto.subtle.digest('SHA-256', new Uint8Array(ders[0])))
+    );
+    if (rootHash !== (policy.rootCertificateSha256 ?? AWS_ROOT_SHA256).toLowerCase()) fail('root');
+    let leaf: X509Certificate;
+    try {
+        const chain = [...ders, leafDer].map(der => new X509Certificate(new Uint8Array(der)));
+        for (let i = 0; i < chain.length; i++) {
+            const cert = chain[i];
+            const issuer = chain[Math.max(0, i - 1)];
+            if (
+                !Number.isFinite(now) ||
+                now < cert.notBefore.getTime() ||
+                now > cert.notAfter.getTime() ||
+                cert.issuer !== issuer.subject ||
+                !(await cert.verify({ publicKey: issuer.publicKey, date: new Date(now) }, crypto))
+            )
+                fail('chain');
+            if (i < chain.length - 1) {
+                const constraints = cert.getExtension(BasicConstraintsExtension);
+                const usage = cert.getExtension(KeyUsagesExtension);
+                if (
+                    !constraints?.ca ||
+                    (constraints.pathLength !== undefined &&
+                        chain.length - i - 2 > constraints.pathLength) ||
+                    (usage && !(usage.usages & KeyUsageFlags.keyCertSign))
+                )
+                    fail('chain');
+            }
+        }
+        leaf = chain[chain.length - 1];
+    } catch {
+        return fail('chain');
+    }
+    try {
+        const key = await crypto.subtle.importKey(
+            'spki',
+            leaf.publicKey.rawData,
+            { name: 'ECDSA', namedCurve: 'P-384' },
+            false,
+            ['verify']
+        );
+        const structure = encode(['Signature1', protectedBytes, new Uint8Array(), payloadBytes]);
+        if (
+            !(await crypto.subtle.verify(
+                { name: 'ECDSA', hash: 'SHA-384' },
+                key,
+                new Uint8Array(signature),
+                new Uint8Array(structure)
+            ))
+        )
+            fail('signature');
+    } catch {
+        return fail('signature');
+    }
+    const rawPcrs = map(payload.get('pcrs'), 'pcr');
+    const pcrs: Record<number, string> = {};
+    for (const [index, value] of rawPcrs) {
+        if (typeof index !== 'number' || !Number.isInteger(index) || index < 0 || index > 31)
+            fail('pcr');
+        const pcr = bytes(value, 'pcr');
+        if (pcr.length !== 48) fail('pcr');
+        pcrs[index] = hex(pcr);
+    }
+    if (pcrs[0] === '00'.repeat(48)) fail('debug');
+    if (
+        !policy.pinnedMeasurements.some(
+            pin =>
+                typeof pin.pcr0 === 'string' &&
+                typeof pin.pcr1 === 'string' &&
+                typeof pin.pcr2 === 'string' &&
+                pin.pcr0.toLowerCase() === pcrs[0] &&
+                pin.pcr1.toLowerCase() === pcrs[1] &&
+                pin.pcr2.toLowerCase() === pcrs[2]
+        )
+    )
+        fail('pcr');
+    const nonce = bytes(payload.get('nonce'), 'nonce');
+    if (
+        !(expectedNonce instanceof Uint8Array) ||
+        expectedNonce.length !== 32 ||
+        nonce.length !== expectedNonce.length
+    )
+        fail('nonce');
+    let difference = 0;
+    for (let i = 0; i < nonce.length; i++) difference |= nonce[i] ^ expectedNonce[i];
+    if (difference !== 0) fail('nonce');
+    const maxAge = policy.maxAgeMs ?? 300000;
+    if (
+        !Number.isFinite(maxAge) ||
+        maxAge < 0 ||
+        now - timestamp > maxAge ||
+        timestamp > now + 60000
+    )
+        fail('freshness');
+    const userData = bytes(payload.get('user_data'), 'user-data');
+    const newFormat = decodeUserData(new Uint8Array(userData));
+    const spki = newFormat ? newFormat.spki : userData;
+    try {
+        await crypto.subtle.importKey(
+            'spki',
+            new Uint8Array(spki),
+            { name: 'ECDH', namedCurve: 'P-256' },
+            false,
+            []
+        );
+    } catch {
+        return fail('user-data');
+    }
+    return {
+        escrowPublicKeySpkiB64: bufferToBase64(new Uint8Array(spki).buffer),
+        keyId: newFormat?.keyId,
+        previousKeyIds: newFormat?.previousKeyIds ?? [],
+        pcrs,
+        timestamp,
+        moduleId,
+    };
+};

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;
+};