@learncard/sss-key-manager 0.1.23 → 0.2.0

package/src/escrow-crypto.test.ts

@@ -0,0 +1,381 @@
+import { beforeAll, describe, expect, it } from 'vitest';
+
+import { base64ToBuffer, bufferToBase64 } from './crypto';
+import {
+    ESCROW_ALGORITHM,
+    ESCROW_BLOB_INFO,
+    ESCROW_CLIENT_KEY_ID,
+    ESCROW_ENVELOPE_VERSION,
+    ESCROW_RELEASE_INFO,
+    decryptEscrowBlob,
+    encryptEscrowBlob,
+    generateEscrowKeyPair,
+    openEscrowRelease,
+    parseEscrowBlobPlaintext,
+    parseEscrowEnvelope,
+    parseEscrowReleasePlaintext,
+    sealEscrowRelease,
+} from './escrow-crypto';
+import type { EscrowEnvelope } from './escrow-crypto';
+
+const blob = {
+    recoveryShare: `0001${'ab'.repeat(48)}`,
+    did: 'did:key:zTestEscrow',
+    shareVersion: 1,
+};
+const release = { ...blob, holdId: 'hold-1.test_2' };
+const plaintext = { ...blob, version: 1 };
+const releasePlaintext = { ...release, version: 1 };
+
+describe('escrow encryption', () => {
+    let publicKey = '';
+    let privateKey = '';
+    let wrongPrivateKey = '';
+    let blobEnvelope: EscrowEnvelope;
+    let releaseEnvelope: EscrowEnvelope;
+
+    beforeAll(async (): Promise<void> => {
+        ({ publicKey, privateKey } = await generateEscrowKeyPair());
+        wrongPrivateKey = (await generateEscrowKeyPair()).privateKey;
+        blobEnvelope = await encryptEscrowBlob(blob, publicKey, 'enclave-1');
+        releaseEnvelope = await sealEscrowRelease(release, publicKey);
+    });
+
+    it('exports an importable SPKI/PKCS#8 P-256 key pair', async (): Promise<void> => {
+        const importedPublic = await crypto.subtle.importKey(
+            'spki',
+            base64ToBuffer(publicKey),
+            { name: 'ECDH', namedCurve: 'P-256' },
+            true,
+            []
+        );
+        const importedPrivate = await crypto.subtle.importKey(
+            'pkcs8',
+            base64ToBuffer(privateKey),
+            { name: 'ECDH', namedCurve: 'P-256' },
+            true,
+            ['deriveBits']
+        );
+        expect(importedPublic.type).toBe('public');
+        expect(importedPrivate.type).toBe('private');
+        const publicJwk = await crypto.subtle.exportKey('jwk', importedPublic);
+        const privateJwk = await crypto.subtle.exportKey('jwk', importedPrivate);
+        expect(privateJwk).toMatchObject({ crv: 'P-256', x: publicJwk.x, y: publicJwk.y });
+    });
+
+    it('round-trips blobs without exposing the recovery share', async (): Promise<void> => {
+        expect(JSON.stringify(blobEnvelope)).not.toContain(blob.recoveryShare);
+        expect(blobEnvelope).toMatchObject({
+            version: ESCROW_ENVELOPE_VERSION,
+            algorithm: ESCROW_ALGORITHM,
+            keyId: 'enclave-1',
+        });
+        const point = base64ToBuffer(blobEnvelope.ephemeralPublicKey);
+        expect(point.length).toBe(65);
+        expect(point[0]).toBe(4);
+        expect(base64ToBuffer(blobEnvelope.salt).length).toBe(32);
+        expect(base64ToBuffer(blobEnvelope.iv).length).toBe(12);
+        await expect(decryptEscrowBlob(blobEnvelope, privateKey)).resolves.toEqual(plaintext);
+    });
+
+    it('round-trips releases with the client key ID', async (): Promise<void> => {
+        expect(releaseEnvelope.keyId).toBe(ESCROW_CLIENT_KEY_ID);
+        expect(JSON.stringify(releaseEnvelope)).not.toContain(release.recoveryShare);
+        await expect(openEscrowRelease(releaseEnvelope, privateKey)).resolves.toEqual(
+            releasePlaintext
+        );
+    });
+
+    it('uses fresh ephemeral keys, salts, and IVs', async (): Promise<void> => {
+        const other = await encryptEscrowBlob(blob, publicKey, 'enclave-1');
+        for (const field of ['ephemeralPublicKey', 'salt', 'iv', 'ciphertext'] as const) {
+            expect(other[field]).not.toBe(blobEnvelope[field]);
+        }
+    });
+
+    it('round-trips a PIN verifier through the blob and release without changing version', async (): Promise<void> => {
+        const pinVerifier = 'AB'.repeat(32);
+        const envelope = await encryptEscrowBlob({ ...blob, pinVerifier }, publicKey, 'enclave-1');
+        expect(envelope.version).toBe(1);
+        expect(JSON.stringify(envelope)).not.toContain(pinVerifier.toLowerCase());
+        const decrypted = await decryptEscrowBlob(envelope, privateKey);
+        expect(decrypted).toEqual({ ...plaintext, pinVerifier: pinVerifier.toLowerCase() });
+        const sealed = await sealEscrowRelease({ ...decrypted, holdId: release.holdId }, publicKey);
+        expect(sealed.version).toBe(1);
+        await expect(openEscrowRelease(sealed, privateKey)).resolves.toEqual({
+            ...releasePlaintext,
+            pinVerifier: pinVerifier.toLowerCase(),
+        });
+    });
+
+    it.each(['', 'a'.repeat(63), 'a'.repeat(65), 'g'.repeat(64)])(
+        'rejects invalid PIN verifier before encryption %j',
+        async (pinVerifier): Promise<void> => {
+            await expect(
+                encryptEscrowBlob({ ...blob, pinVerifier }, publicKey, 'enclave-1')
+            ).rejects.toThrow('pinVerifier');
+            await expect(sealEscrowRelease({ ...release, pinVerifier }, publicKey)).rejects.toThrow(
+                'pinVerifier'
+            );
+        }
+    );
+
+    it.each(['blob', 'release'] as const)(
+        'rejects wrong keys and tampered %s envelopes',
+        async (kind): Promise<void> => {
+            const envelope = kind === 'blob' ? blobEnvelope : releaseEnvelope;
+            const decrypt = kind === 'blob' ? decryptEscrowBlob : openEscrowRelease;
+            await expect(decrypt(envelope, wrongPrivateKey)).rejects.toThrow();
+            await expect(
+                decrypt({ ...envelope, keyId: 'other-key' }, privateKey)
+            ).rejects.toThrow();
+
+            for (const field of ['ciphertext', 'salt', 'iv'] as const) {
+                const bytes = base64ToBuffer(envelope[field]);
+                bytes[0] = (bytes[0] ?? 0) ^ 1;
+                await expect(
+                    decrypt({ ...envelope, [field]: bufferToBase64(bytes.buffer) }, privateKey)
+                ).rejects.toThrow();
+            }
+            for (const change of [{ version: 2 }, { algorithm: 'AES-GCM' }]) {
+                expect(() => parseEscrowEnvelope({ ...envelope, ...change })).toThrow(
+                    'Unsupported'
+                );
+                await expect(decrypt({ ...envelope, ...change }, privateKey)).rejects.toThrow(
+                    'Unsupported'
+                );
+            }
+        }
+    );
+
+    it('domain-separates blobs and releases even with identical recipient keys and key IDs', async (): Promise<void> => {
+        const envelope = await encryptEscrowBlob(blob, publicKey, ESCROW_CLIENT_KEY_ID);
+        await expect(openEscrowRelease(envelope, privateKey)).rejects.toMatchObject({
+            name: 'OperationError',
+        });
+        await expect(decryptEscrowBlob(releaseEnvelope, privateKey)).rejects.toMatchObject({
+            name: 'OperationError',
+        });
+    });
+
+    it.each(['', ' ', 'not-base64!', 'YWJj'])(
+        'rejects invalid public key %j',
+        async (key): Promise<void> => {
+            await expect(encryptEscrowBlob(blob, key, 'enclave-1')).rejects.toThrow();
+            await expect(sealEscrowRelease(release, key)).rejects.toThrow();
+        }
+    );
+
+    it.each(['', 'bad key', ' key ', 'bad|key', 'bad/key', 'a'.repeat(129)])(
+        'rejects invalid encryption key ID %j',
+        async (keyId): Promise<void> => {
+            await expect(encryptEscrowBlob(blob, publicKey, keyId)).rejects.toThrow('keyId');
+        }
+    );
+
+    it('validates plaintext before importing a recipient key', async (): Promise<void> => {
+        await expect(encryptEscrowBlob({ ...blob, shareVersion: 0 }, '', '')).rejects.toThrow(
+            'shareVersion'
+        );
+        await expect(sealEscrowRelease({ ...release, holdId: '' }, '')).rejects.toThrow('holdId');
+    });
+
+    it.each([
+        {
+            info: ESCROW_BLOB_INFO,
+            input: { ...plaintext, shareVersion: 0 },
+            decrypt: decryptEscrowBlob,
+            error: 'shareVersion',
+        },
+        {
+            info: ESCROW_BLOB_INFO,
+            input: { ...plaintext, pinVerifier: 'a'.repeat(63) },
+            decrypt: decryptEscrowBlob,
+            error: 'pinVerifier',
+        },
+        {
+            info: ESCROW_RELEASE_INFO,
+            input: { ...releasePlaintext, pinVerifier: 'a'.repeat(65) },
+            decrypt: openEscrowRelease,
+            error: 'pinVerifier',
+        },
+        {
+            info: ESCROW_RELEASE_INFO,
+            input: { ...releasePlaintext, holdId: '' },
+            decrypt: openEscrowRelease,
+            error: 'holdId',
+        },
+    ])(
+        'validates plaintext after authenticated decryption ($info)',
+        async ({ info, input, decrypt, error }): Promise<void> => {
+            // Independently construct a valid wire envelope carrying invalid JSON fields.
+            const recipient = await crypto.subtle.importKey(
+                'spki',
+                base64ToBuffer(publicKey),
+                { name: 'ECDH', namedCurve: 'P-256' },
+                false,
+                []
+            );
+            const ephemeral = await crypto.subtle.generateKey(
+                { name: 'ECDH', namedCurve: 'P-256' },
+                true,
+                ['deriveBits']
+            );
+            const secret = await crypto.subtle.deriveBits(
+                { name: 'ECDH', public: recipient },
+                ephemeral.privateKey,
+                256
+            );
+            const material = await crypto.subtle.importKey('raw', secret, 'HKDF', false, [
+                'deriveKey',
+            ]);
+            const salt = crypto.getRandomValues(new Uint8Array(32));
+            const iv = crypto.getRandomValues(new Uint8Array(12));
+            const key = await crypto.subtle.deriveKey(
+                { name: 'HKDF', hash: 'SHA-256', salt, info: new TextEncoder().encode(info) },
+                material,
+                { name: 'AES-GCM', length: 256 },
+                false,
+                ['encrypt']
+            );
+            const ciphertext = await crypto.subtle.encrypt(
+                {
+                    name: 'AES-GCM',
+                    iv,
+                    additionalData: new TextEncoder().encode(`1|${ESCROW_ALGORITHM}|client`),
+                },
+                key,
+                new TextEncoder().encode(JSON.stringify(input))
+            );
+            await expect(
+                decrypt(
+                    {
+                        version: 1,
+                        algorithm: ESCROW_ALGORITHM,
+                        keyId: 'client',
+                        ephemeralPublicKey: bufferToBase64(
+                            await crypto.subtle.exportKey('raw', ephemeral.publicKey)
+                        ),
+                        salt: bufferToBase64(salt.buffer),
+                        iv: bufferToBase64(iv.buffer),
+                        ciphertext: bufferToBase64(ciphertext),
+                    },
+                    privateKey
+                )
+            ).rejects.toThrow(error);
+        }
+    );
+});
+
+describe('escrow parsing', () => {
+    it('accepts legacy plaintext without a PIN verifier', (): void => {
+        expect(parseEscrowBlobPlaintext(plaintext)).toEqual(plaintext);
+        expect(parseEscrowBlobPlaintext(plaintext)).not.toHaveProperty('pinVerifier');
+        expect(parseEscrowReleasePlaintext(releasePlaintext)).toEqual(releasePlaintext);
+    });
+
+    const envelope = {
+        version: 1,
+        algorithm: ESCROW_ALGORITHM,
+        keyId: 'enclave-1',
+        ephemeralPublicKey: 'point',
+        salt: 'salt',
+        iv: 'iv',
+        ciphertext: 'ciphertext',
+    };
+
+    it('copies only recognized fields', (): void => {
+        expect(parseEscrowEnvelope({ ...envelope, extra: true })).toEqual(envelope);
+        expect(parseEscrowBlobPlaintext({ ...releasePlaintext, extra: true })).toEqual(plaintext);
+        expect(parseEscrowReleasePlaintext({ ...releasePlaintext, extra: true })).toEqual(
+            releasePlaintext
+        );
+    });
+
+    it.each([null, undefined, [], 'value', 1])('rejects non-record input %j', (value): void => {
+        expect(() => parseEscrowEnvelope(value)).toThrow();
+        expect(() => parseEscrowBlobPlaintext(value)).toThrow();
+        expect(() => parseEscrowReleasePlaintext(value)).toThrow();
+    });
+
+    it.each([
+        ['keyId', 128],
+        ['ephemeralPublicKey', 256],
+        ['salt', 128],
+        ['iv', 64],
+        ['ciphertext', 16_384],
+    ] as const)('enforces envelope %s bounds and required type', (field, max): void => {
+        for (const value of [undefined, '', 123, 'a'.repeat(max + 1)]) {
+            expect(() => parseEscrowEnvelope({ ...envelope, [field]: value })).toThrow(field);
+        }
+        expect(parseEscrowEnvelope({ ...envelope, [field]: 'a'.repeat(max) })[field]).toHaveLength(
+            max
+        );
+    });
+
+    it.each(['bad key', 'bad|key', 'bad/key'])('rejects bad parsed key ID %j', (keyId): void => {
+        expect(() => parseEscrowEnvelope({ ...envelope, keyId })).toThrow('keyId');
+    });
+
+    it.each([undefined, 0, 2, '1'])('rejects unsupported versions %j', (version): void => {
+        expect(() => parseEscrowEnvelope({ ...envelope, version })).toThrow('Unsupported');
+        expect(() => parseEscrowBlobPlaintext({ ...plaintext, version })).toThrow();
+        expect(() => parseEscrowReleasePlaintext({ ...releasePlaintext, version })).toThrow();
+    });
+
+    it.each([undefined, '', 'other'])('rejects unsupported algorithms %j', (algorithm): void => {
+        expect(() => parseEscrowEnvelope({ ...envelope, algorithm })).toThrow('Unsupported');
+    });
+
+    it.each([
+        ['recoveryShare', undefined],
+        ['recoveryShare', 'abcd'],
+        ['recoveryShare', 'abcgh'],
+        ['recoveryShare', 'a'.repeat(4_097)],
+        ['recoveryShare', 12345],
+        ['did', undefined],
+        ['did', ''],
+        ['did', 'not:did'],
+        ['did', `did:${'a'.repeat(2_045)}`],
+        ['shareVersion', undefined],
+        ['shareVersion', 0],
+        ['shareVersion', -1],
+        ['shareVersion', 1.5],
+        ['shareVersion', '1'],
+        ['shareVersion', NaN],
+        ['shareVersion', Infinity],
+        ['pinVerifier', null],
+        ['pinVerifier', 123],
+        ['pinVerifier', ''],
+        ['pinVerifier', 'a'.repeat(63)],
+        ['pinVerifier', 'a'.repeat(65)],
+        ['pinVerifier', 'g'.repeat(64)],
+    ])('rejects invalid plaintext %s = %j', (field, value): void => {
+        expect(() => parseEscrowBlobPlaintext({ ...plaintext, [field]: value })).toThrow(field);
+        expect(() => parseEscrowReleasePlaintext({ ...releasePlaintext, [field]: value })).toThrow(
+            field
+        );
+    });
+
+    it.each([undefined, '', 'bad hold', 'bad|hold', 'a'.repeat(129), 123])(
+        'rejects invalid hold ID %j',
+        (holdId): void => {
+            expect(() => parseEscrowReleasePlaintext({ ...releasePlaintext, holdId })).toThrow(
+                'holdId'
+            );
+        }
+    );
+
+    it('accepts bounds and normalizes uppercase hex', (): void => {
+        expect(
+            parseEscrowBlobPlaintext({ ...plaintext, recoveryShare: 'ABCDE' }).recoveryShare
+        ).toBe('abcde');
+        const maximum = {
+            ...releasePlaintext,
+            recoveryShare: 'a'.repeat(4_096),
+            did: `did:${'a'.repeat(2_044)}`,
+            holdId: 'a'.repeat(128),
+        };
+        expect(parseEscrowReleasePlaintext(maximum)).toEqual(maximum);
+    });
+});

package/src/escrow-crypto.ts

@@ -0,0 +1,319 @@
+/**
+ * Shared escrow wire format: ephemeral P-256 ECDH → HKDF-SHA-256 → AES-256-GCM.
+ * Recipient keys use SPKI/PKCS#8; envelope keys are raw uncompressed P-256 points.
+ * All binary fields use standard base64. Ciphertext includes the 128-bit GCM tag.
+ * Blob and release envelopes use distinct HKDF info strings for domain separation.
+ */
+import { base64ToBuffer, bufferToBase64 } from './crypto';
+
+/** Supported escrow wire-format version. */
+export const ESCROW_ENVELOPE_VERSION = 1 as const;
+/** Cryptographic suite used by escrow envelopes. */
+export const ESCROW_ALGORITHM = 'P-256-HKDF-SHA256-AES-256-GCM' as const;
+/** HKDF info for client-to-enclave escrow blobs. */
+export const ESCROW_BLOB_INFO = 'learncard-escrow-blob-v1';
+/** HKDF info for enclave-to-client release envelopes. */
+export const ESCROW_RELEASE_INFO = 'learncard-escrow-release-v1';
+/** Recipient key identifier used when sealing a release. */
+export const ESCROW_CLIENT_KEY_ID = 'client' as const;
+
+/** Encrypted escrow payload with authenticated version, algorithm, and key ID. */
+export interface EscrowEnvelope {
+    version: typeof ESCROW_ENVELOPE_VERSION;
+    algorithm: typeof ESCROW_ALGORITHM;
+    keyId: string;
+    ephemeralPublicKey: string;
+    salt: string;
+    iv: string;
+    ciphertext: string;
+}
+
+/** Recovery share bound to an identity and a positive share version. */
+export interface EscrowBlobPlaintext {
+    version: typeof ESCROW_ENVELOPE_VERSION;
+    recoveryShare: string;
+    did: string;
+    shareVersion: number;
+    pinVerifier?: string;
+}
+
+/** Released recovery share additionally bound to its recovery hold. */
+export interface EscrowReleasePlaintext extends EscrowBlobPlaintext {
+    holdId: string;
+}
+
+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 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 escrow ${key}`);
+    }
+
+    return value;
+};
+
+/** Validate an untrusted envelope before decryption, copying only recognized fields. */
+export const parseEscrowEnvelope = (value: unknown): EscrowEnvelope => {
+    if (!isRecord(value)) throw new Error('Invalid escrow envelope');
+    if (value.version !== ESCROW_ENVELOPE_VERSION) {
+        throw new Error('Unsupported escrow envelope version');
+    }
+    if (value.algorithm !== ESCROW_ALGORITHM) {
+        throw new Error('Unsupported escrow algorithm');
+    }
+
+    return {
+        version: ESCROW_ENVELOPE_VERSION,
+        algorithm: ESCROW_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 blob plaintext, normalize hex to lowercase, and omit unknown fields. */
+export const parseEscrowBlobPlaintext = (value: unknown): EscrowBlobPlaintext => {
+    if (!isRecord(value) || value.version !== ESCROW_ENVELOPE_VERSION) {
+        throw new Error('Invalid escrow plaintext');
+    }
+    if (
+        typeof value.shareVersion !== 'number' ||
+        !Number.isInteger(value.shareVersion) ||
+        value.shareVersion <= 0
+    ) {
+        throw new Error('Invalid escrow shareVersion');
+    }
+
+    return {
+        version: ESCROW_ENVELOPE_VERSION,
+        recoveryShare: requireString(value, 'recoveryShare', {
+            min: 5,
+            max: 4_096,
+            pattern: /^[0-9a-f]+$/i,
+        }).toLowerCase(),
+        did: requireString(value, 'did', { max: 2_048, pattern: /^did:/ }),
+        shareVersion: value.shareVersion,
+        ...(value.pinVerifier !== undefined
+            ? {
+                  pinVerifier: requireString(value, 'pinVerifier', {
+                      min: 64,
+                      max: 64,
+                      pattern: /^[0-9a-f]{64}$/i,
+                  }).toLowerCase(),
+              }
+            : {}),
+    };
+};
+
+/** Validate release plaintext, including its hold ID, and omit unknown fields. */
+export const parseEscrowReleasePlaintext = (value: unknown): EscrowReleasePlaintext => {
+    const plaintext = parseEscrowBlobPlaintext(value);
+    if (!isRecord(value)) throw new Error('Invalid escrow plaintext');
+
+    return {
+        ...plaintext,
+        holdId: requireString(value, 'holdId', { max: 128, pattern: /^[A-Za-z0-9._-]+$/ }),
+    };
+};
+
+const getAad = (
+    envelope: Pick<EscrowEnvelope, 'version' | 'algorithm' | 'keyId'>
+): Uint8Array<ArrayBuffer> =>
+    encodeUtf8(`${envelope.version}|${envelope.algorithm}|${envelope.keyId}`);
+
+const deriveAesKey = async (
+    sharedSecret: ArrayBuffer,
+    salt: Uint8Array<ArrayBuffer>,
+    usage: KeyUsage,
+    info: string
+): Promise<CryptoKey> => {
+    const keyMaterial = await crypto.subtle.importKey('raw', sharedSecret, 'HKDF', false, [
+        'deriveKey',
+    ]);
+
+    return crypto.subtle.deriveKey(
+        { name: 'HKDF', hash: 'SHA-256', salt, info: encodeUtf8(info) },
+        keyMaterial,
+        { name: 'AES-GCM', length: 256 },
+        false,
+        [usage]
+    );
+};
+
+/** Generate an extractable P-256 ECDH pair as base64 SPKI and PKCS#8 keys. */
+export const generateEscrowKeyPair = async (): Promise<{
+    publicKey: string;
+    privateKey: string;
+}> => {
+    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),
+    ]);
+
+    return { publicKey: bufferToBase64(publicKey), privateKey: bufferToBase64(privateKey) };
+};
+
+const encryptToRecipient = async (
+    plaintextJson: string,
+    spki: string,
+    keyId: string,
+    info: string
+): Promise<EscrowEnvelope> => {
+    if (typeof spki !== 'string' || !spki.trim()) {
+        throw new Error('Escrow public key is not configured');
+    }
+    const recipientKeyId = requireString({ keyId }, 'keyId', {
+        max: 128,
+        pattern: /^[A-Za-z0-9._-]+$/,
+    });
+    const recipientPublicKey = await crypto.subtle.importKey(
+        'spki',
+        base64ToBuffer(spki.trim()),
+        { 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', info);
+    const metadata = {
+        version: ESCROW_ENVELOPE_VERSION,
+        algorithm: ESCROW_ALGORITHM,
+        keyId: recipientKeyId,
+    };
+    const ciphertext = await crypto.subtle.encrypt(
+        { name: 'AES-GCM', iv, additionalData: getAad(metadata) },
+        aesKey,
+        encodeUtf8(plaintextJson)
+    );
+    const ephemeralPublicKey = await crypto.subtle.exportKey('raw', ephemeralKeyPair.publicKey);
+
+    return {
+        ...metadata,
+        ephemeralPublicKey: bufferToBase64(ephemeralPublicKey),
+        salt: bufferToBase64(salt.buffer),
+        iv: bufferToBase64(iv.buffer),
+        ciphertext: bufferToBase64(ciphertext),
+    };
+};
+
+const decryptFromEnvelope = async (
+    value: unknown,
+    pkcs8: string,
+    info: string
+): Promise<unknown> => {
+    const envelope = parseEscrowEnvelope(value);
+    const privateKey = await crypto.subtle.importKey(
+        'pkcs8',
+        base64ToBuffer(pkcs8.trim()),
+        { name: 'ECDH', namedCurve: 'P-256' },
+        false,
+        ['deriveBits']
+    );
+    const ephemeralPublicKey = await crypto.subtle.importKey(
+        'raw',
+        base64ToBuffer(envelope.ephemeralPublicKey),
+        { 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', info);
+    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 parsed;
+};
+
+/** Validate and encrypt a recovery share to the enclave's SPKI public key. */
+export const encryptEscrowBlob = async (
+    input: Omit<EscrowBlobPlaintext, 'version'>,
+    enclavePublicKeySpkiB64: string,
+    keyId: string
+): Promise<EscrowEnvelope> => {
+    const plaintext = parseEscrowBlobPlaintext({ ...input, version: ESCROW_ENVELOPE_VERSION });
+
+    return encryptToRecipient(
+        JSON.stringify(plaintext),
+        enclavePublicKeySpkiB64,
+        keyId,
+        ESCROW_BLOB_INFO
+    );
+};
+
+/** Decrypt and validate a blob using the enclave's PKCS#8 private key. */
+export const decryptEscrowBlob = async (
+    envelope: unknown,
+    enclavePrivateKeyPkcs8B64: string
+): Promise<EscrowBlobPlaintext> =>
+    parseEscrowBlobPlaintext(
+        await decryptFromEnvelope(envelope, enclavePrivateKeyPkcs8B64, ESCROW_BLOB_INFO)
+    );
+
+/** Validate and seal a release to the recovering client's ephemeral SPKI public key. */
+export const sealEscrowRelease = async (
+    input: Omit<EscrowReleasePlaintext, 'version'>,
+    clientEphemeralPublicKeySpkiB64: string
+): Promise<EscrowEnvelope> => {
+    const plaintext = parseEscrowReleasePlaintext({ ...input, version: ESCROW_ENVELOPE_VERSION });
+
+    return encryptToRecipient(
+        JSON.stringify(plaintext),
+        clientEphemeralPublicKeySpkiB64,
+        ESCROW_CLIENT_KEY_ID,
+        ESCROW_RELEASE_INFO
+    );
+};
+
+/** Open and validate a release using the recovering client's ephemeral PKCS#8 private key. */
+export const openEscrowRelease = async (
+    envelope: unknown,
+    clientEphemeralPrivateKeyPkcs8B64: string
+): Promise<EscrowReleasePlaintext> =>
+    parseEscrowReleasePlaintext(
+        await decryptFromEnvelope(envelope, clientEphemeralPrivateKeyPkcs8B64, ESCROW_RELEASE_INFO)
+    );