@learncard/lca-api-service 1.4.0 → 1.5.1

package/src/services/escrow-enclave/remoteEnclave.ts

@@ -0,0 +1,263 @@
+import { Agent } from 'node:https';
+import axios from 'axios';
+import { z } from 'zod';
+import {
+    ESCROW_ALGORITHM,
+    ESCROW_ENVELOPE_VERSION,
+    type EscrowEnvelope,
+} from '@learncard/sss-key-manager';
+import {
+    EscrowBlobError,
+    EscrowPinMismatchError,
+    EscrowPolicyError,
+    EscrowUnavailableError,
+    type CarryPinVerifierInput,
+    type EnclaveAttestation,
+    type EscrowEnclave,
+    type ReleaseRequest,
+    type ReleaseResult,
+    type RewrapEscrowBlobInput,
+    type VerifyEscrowBlobInput,
+    type VerifyEscrowBlobResult,
+} from './types';
+
+// Mirrors services/escrow-enclave-app/src/wire.rs camelCase field names exactly,
+// minus the vsock wire's `method` tag (the HTTP paths below take its place).
+const measurementsValidator = z.object({
+    imageSha384: z.string().optional(),
+    pcr0: z.string().optional(),
+    pcr1: z.string().optional(),
+    pcr2: z.string().optional(),
+});
+
+const attestResponseValidator = z.object({
+    mode: z.enum(['software', 'nitro']),
+    keyId: z.string(),
+    // Optional/defaulted (not required, unlike the host's own wire.rs field) so
+    // a not-yet-upgraded host during a rolling deploy still parses; P9.1.
+    previousKeyIds: z.array(z.string()).optional().default([]),
+    publicKey: z.string(),
+    measurements: measurementsValidator,
+    document: z.string(),
+    issuedAt: z.string(),
+});
+
+const envelopeValidator = z.object({
+    version: z.literal(ESCROW_ENVELOPE_VERSION),
+    algorithm: z.literal(ESCROW_ALGORITHM),
+    keyId: z.string(),
+    ephemeralPublicKey: z.string(),
+    salt: z.string(),
+    iv: z.string(),
+    ciphertext: z.string(),
+});
+
+const verifyBlobResponseValidator = z.union([
+    z.object({ ok: z.literal(true), hasPin: z.boolean() }),
+    z.object({ ok: z.literal(false), hasPin: z.boolean(), reason: z.string() }),
+]);
+
+const carryPinVerifierResponseValidator = z.object({ envelope: envelopeValidator });
+const rewrapEscrowBlobResponseValidator = z.object({ envelope: envelopeValidator });
+
+// Opaque SignedHoldRecord JSON: validate shape while preserving signed extensions.
+const holdRecordValidator = z
+    .object({
+        hold: z
+            .object({
+                holdId: z.string().min(1),
+                did: z.string().min(1),
+                shareVersion: z.number().int().positive(),
+                blobHash: z.string().regex(/^[0-9a-f]{64}$/),
+                enrollmentEpoch: z.number().int().positive(),
+                releasePolicy: z.enum(['hold', 'pin']),
+                clientEphemeralPublicKey: z.string().min(1),
+                createdLo: z.number().int().nonnegative(),
+                createdHi: z.number().int().nonnegative(),
+                policyVersion: z.number().int().positive(),
+                signature: z.string().min(1),
+            })
+            .passthrough(),
+        holdDurationMs: z.number().int().nonnegative(),
+        ledgerSeq: z.number().int().nonnegative(),
+    })
+    .passthrough();
+const validatedHold = (hold: ReleaseRequest['hold']): ReleaseRequest['hold'] => {
+    if (!holdRecordValidator.safeParse(hold).success) throw new EscrowUnavailableError();
+    return hold;
+};
+const releaseResponseValidator = z.object({ sealed: envelopeValidator });
+
+const errorCodeValidator = z.enum([
+    'policy',
+    'pinMismatch',
+    'blob',
+    'unavailable',
+    'ledger',
+    'time',
+]);
+const errorResponseValidator = z.object({ code: errorCodeValidator, message: z.string() });
+
+const errorForCode = (code: z.infer<typeof errorCodeValidator>): Error => {
+    if (code === 'policy') return new EscrowPolicyError();
+    if (code === 'pinMismatch') return new EscrowPinMismatchError();
+    if (code === 'blob') return new EscrowBlobError();
+    return new EscrowUnavailableError(); // 'unavailable' | 'ledger' | 'time'
+};
+
+export interface RemoteEnclaveTransportResponse {
+    status: number;
+    data: unknown;
+}
+
+export interface RemoteEnclaveTransport {
+    post(
+        url: string,
+        body: unknown,
+        config: { headers: Record<string, string>; timeout: number }
+    ): Promise<RemoteEnclaveTransportResponse>;
+}
+
+/** With `caPem`, the connection trusts only that CA (system roots are not consulted). */
+export const createHttpTransport = (caPem?: string): RemoteEnclaveTransport => {
+    const httpsAgent = caPem ? new Agent({ ca: caPem, keepAlive: true }) : undefined;
+    return {
+        post: async (url, body, config) => {
+            const response = await axios.post(url, body, {
+                ...config,
+                httpsAgent,
+                validateStatus: () => true,
+            });
+            return { status: response.status, data: response.data };
+        },
+    };
+};
+
+export interface RemoteEnclaveConfig {
+    /** Origin of the enclave-host parent service (P3.3), e.g. `https://escrow.internal`. */
+    baseUrl: string;
+    token: string;
+    timeoutMs: number;
+    /** Private CA pinned for this host (see enclaveTrustAnchors.ts); system roots otherwise. */
+    caPem?: string;
+    /** Injectable for tests; defaults to a real HTTP (axios) transport. */
+    transport?: RemoteEnclaveTransport;
+}
+
+/**
+ * `EscrowEnclave` backend for `ESCROW_ENCLAVE_MODE=remote`: an HTTP client to the
+ * enclave-host parent service fronting a real Nitro Enclave. See issues.md
+ * "P4.1 report" for the full contract (paths, bodies, error format).
+ *
+ * Fail-closed: any transport failure (network error, timeout, non-2xx without a
+ * recognized error code, or a response failing its zod schema) becomes
+ * `EscrowUnavailableError`. Request/response bodies (sealed envelopes, PIN
+ * proofs) are never logged anywhere in this module.
+ */
+export const createRemoteEnclave = (config: RemoteEnclaveConfig): EscrowEnclave => {
+    const transport = config.transport ?? createHttpTransport(config.caPem);
+
+    const call = async <T>(path: string, body: unknown, validator: z.ZodType<T>): Promise<T> => {
+        let status: number;
+        let data: unknown;
+        try {
+            const response = await transport.post(`${config.baseUrl}${path}`, body, {
+                headers: { Authorization: `Bearer ${config.token}` },
+                timeout: config.timeoutMs,
+            });
+            status = response.status;
+            data = response.data;
+        } catch {
+            throw new EscrowUnavailableError();
+        }
+        if (status < 200 || status >= 300) {
+            const parsedError = errorResponseValidator.safeParse(data);
+            if (parsedError.success) throw errorForCode(parsedError.data.code);
+            throw new EscrowUnavailableError();
+        }
+        const parsed = validator.safeParse(data);
+        if (!parsed.success) throw new EscrowUnavailableError();
+        return parsed.data;
+    };
+
+    return {
+        getAttestation: (nonce?: Uint8Array): Promise<EnclaveAttestation> =>
+            call('/v1/attest', { nonce: Array.from(nonce ?? []) }, attestResponseValidator),
+        verifyEscrowBlob: (input: VerifyEscrowBlobInput): Promise<VerifyEscrowBlobResult> =>
+            call(
+                '/v1/verify-blob',
+                {
+                    envelope: input.envelope,
+                    expectedDid: input.expectedDid,
+                    expectedShareVersion: input.expectedShareVersion,
+                },
+                verifyBlobResponseValidator
+            ),
+        carryPinVerifier: (input: CarryPinVerifierInput): Promise<{ envelope: EscrowEnvelope }> =>
+            call(
+                '/v1/carry-pin-verifier',
+                {
+                    sourceEnvelope: input.sourceEnvelope,
+                    targetEnvelope: input.targetEnvelope,
+                    expectedDid: input.expectedDid,
+                    sourceShareVersion: input.sourceShareVersion,
+                    targetShareVersion: input.targetShareVersion,
+                    sourceEnrollmentEpoch: input.sourceEnrollmentEpoch,
+                    targetEnrollmentEpoch: input.targetEnrollmentEpoch,
+                },
+                carryPinVerifierResponseValidator
+            ),
+        rewrapEscrowBlob: (input: RewrapEscrowBlobInput): Promise<{ envelope: EscrowEnvelope }> =>
+            call(
+                '/v1/rewrap-escrow-blob',
+                {
+                    envelope: input.envelope,
+                    expectedDid: input.expectedDid,
+                    expectedShareVersion: input.expectedShareVersion,
+                    sourceEnrollmentEpoch: input.sourceEnrollmentEpoch,
+                },
+                rewrapEscrowBlobResponseValidator
+            ),
+        createHold: async input => ({
+            holdRecord: await call(
+                '/v1/create-hold',
+                {
+                    envelope: input.envelope,
+                    holdId: input.holdId,
+                    expectedDid: input.expectedDid,
+                    expectedShareVersion: input.expectedShareVersion,
+                    enrollmentEpoch: input.enrollmentEpoch,
+                    releasePolicy: input.releasePolicy,
+                    clientEphemeralPublicKey: input.clientEphemeralPublicKey,
+                },
+                holdRecordValidator
+            ),
+        }),
+        cancelHold: async input => {
+            await call(
+                '/v1/cancel-hold',
+                {
+                    envelope: input.envelope,
+                    hold: validatedHold(input.hold),
+                    clientEphemeralPublicKey: input.clientEphemeralPublicKey,
+                    expectedDid: input.expectedDid,
+                },
+                z.object({ ok: z.literal(true) })
+            );
+        },
+        releaseEscrow: async (input: ReleaseRequest): Promise<ReleaseResult> => {
+            validatedHold(input.hold);
+            return call(
+                '/v1/release',
+                {
+                    envelope: input.envelope,
+                    hold: input.hold,
+                    clientEphemeralPublicKey: input.clientEphemeralPublicKey,
+                    expectedDid: input.expectedDid,
+                    ...(input.pinProof !== undefined ? { pinProof: input.pinProof } : {}),
+                },
+                releaseResponseValidator
+            );
+        },
+    };
+};

package/src/services/escrow-enclave/softwareEnclave.test.ts

@@ -9,7 +9,7 @@ import {
     EscrowBlobError,
     EscrowPolicyError,
     EscrowPinMismatchError,
-    type EscrowHoldForEnclave,
+    type EscrowHoldRecord,
 } from './types';
 
 describe('software enclave', () => {
@@ -58,6 +58,9 @@ describe('software enclave', () => {
             expectedDid: scenario === 'expected DID' ? 'did:key:other' : did,
             sourceShareVersion: scenario === 'source version' ? 1 : 2,
             targetShareVersion: scenario === 'target version' ? 4 : targetVersion,
+            targetEnrollmentEpoch: 2,
+            // Unused in software mode (see softwareEnclave.ts); any value is fine here.
+            sourceEnrollmentEpoch: 1,
         });
         if (scenario !== 'success') {
             await expect(result).rejects.toBeInstanceOf(EscrowBlobError);
@@ -74,13 +77,21 @@ describe('software enclave', () => {
             pinProof: pinVerifier,
             clientEphemeralPublicKey: client.publicKey,
             hold: {
-                _id: 'carry',
-                status: 'pending',
-                releasePolicy: 'pin',
-                releaseAfter: new Date(0),
-                primaryDid: did,
-                shareVersion: 3,
-                clientEphemeralPublicKey: client.publicKey,
+                hold: {
+                    holdId: 'carry',
+                    did,
+                    shareVersion: 3,
+                    blobHash: 'ab'.repeat(32),
+                    enrollmentEpoch: 1,
+                    releasePolicy: 'pin',
+                    clientEphemeralPublicKey: client.publicKey,
+                    createdLo: 0,
+                    createdHi: 0,
+                    policyVersion: 1,
+                    signature: 'test-signature',
+                },
+                holdDurationMs: 0,
+                ledgerSeq: 0,
             },
         });
         expect(await openEscrowRelease(sealed, client.privateKey)).toEqual({
@@ -90,6 +101,84 @@ describe('software enclave', () => {
         });
     });
 
+    it.each(['success', 'current key', 'unknown key', 'wrong DID', 'wrong version'])(
+        'rewraps an escrow blob sealed under a previous key (P9.3): %s',
+        async scenario => {
+            const current = await generateEscrowKeyPair();
+            const previous = await generateEscrowKeyPair();
+            const client = await generateEscrowKeyPair();
+            const enclave = new SoftwareEnclave({
+                privateKeys: { current: current.privateKey, previous: previous.privateKey },
+                activeKeyId: 'current',
+            });
+            const did = 'did:key:test';
+            const pinVerifier = 'ab'.repeat(32);
+            const target = { recoveryShare: 'ef'.repeat(33), did, shareVersion: 1 };
+            const sourceKeys = scenario === 'current key' ? current : previous;
+            const sourceKeyId = scenario === 'current key' ? 'current' : 'previous';
+            const sourceEnvelope = await encryptEscrowBlob(
+                { ...target, pinVerifier },
+                sourceKeys.publicKey,
+                sourceKeyId
+            );
+            const unknown =
+                scenario === 'unknown key'
+                    ? await encryptEscrowBlob(
+                          target,
+                          (await generateEscrowKeyPair()).publicKey,
+                          'retired-and-removed'
+                      )
+                    : undefined;
+            const result = enclave.rewrapEscrowBlob({
+                envelope: unknown ?? sourceEnvelope,
+                expectedDid: scenario === 'wrong DID' ? 'did:key:other' : did,
+                expectedShareVersion: scenario === 'wrong version' ? 2 : 1,
+                sourceEnrollmentEpoch: 1,
+            });
+            if (scenario !== 'success') {
+                await expect(result).rejects.toBeInstanceOf(EscrowBlobError);
+                return;
+            }
+            const { envelope } = await result;
+            expect(envelope.ciphertext).not.toBe(sourceEnvelope.ciphertext);
+            expect(
+                await enclave.verifyEscrowBlob({
+                    envelope,
+                    expectedDid: did,
+                    expectedShareVersion: 1,
+                })
+            ).toEqual({ ok: true, hasPin: true });
+            const { sealed } = await enclave.releaseEscrow({
+                envelope,
+                expectedDid: did,
+                pinProof: pinVerifier,
+                clientEphemeralPublicKey: client.publicKey,
+                hold: {
+                    hold: {
+                        holdId: 'rewrap',
+                        did,
+                        shareVersion: 1,
+                        blobHash: 'ab'.repeat(32),
+                        enrollmentEpoch: 1,
+                        releasePolicy: 'pin',
+                        clientEphemeralPublicKey: client.publicKey,
+                        createdLo: 0,
+                        createdHi: 0,
+                        policyVersion: 1,
+                        signature: 'test-signature',
+                    },
+                    holdDurationMs: 0,
+                    ledgerSeq: 0,
+                },
+            });
+            expect(await openEscrowRelease(sealed, client.privateKey)).toEqual({
+                ...target,
+                version: 1,
+                holdId: 'rewrap',
+            });
+        }
+    );
+
     it('derives the attestation key, verifies enrollment, and enforces release policy', async () => {
         const keys = await generateEscrowKeyPair();
         const client = await generateEscrowKeyPair();
@@ -102,6 +191,7 @@ describe('software enclave', () => {
         expect(JSON.parse(Buffer.from(attestation.document, 'base64').toString())).toEqual({
             mode: 'software',
             keyId: 'test',
+            previousKeyIds: [],
             publicKey: keys.publicKey,
             issuedAt: attestation.issuedAt,
         });
@@ -121,33 +211,86 @@ describe('software enclave', () => {
                 expectedShareVersion: 1,
             })
         ).toMatchObject({ ok: false });
-        const hold: EscrowHoldForEnclave = {
-            _id: 'test-hold',
-            primaryDid: plaintext.did,
-            shareVersion: 1,
-            status: 'pending',
-            releaseAfter: new Date(1000),
+        const { holdRecord: created } = await enclave.createHold({
+            envelope,
+            holdId: 'test-hold',
+            expectedDid: plaintext.did,
+            expectedShareVersion: 1,
+            enrollmentEpoch: 1,
             releasePolicy: 'hold',
             clientEphemeralPublicKey: client.publicKey,
+        });
+        const hold: EscrowHoldRecord = {
+            ...created,
+            hold: { ...created.hold, createdLo: 0, createdHi: 0 },
+            holdDurationMs: 1000,
+        };
+        expect(created).toMatchObject({
+            hold: {
+                holdId: 'test-hold',
+                did: plaintext.did,
+                shareVersion: 1,
+                enrollmentEpoch: 1,
+                releasePolicy: 'hold',
+                clientEphemeralPublicKey: client.publicKey,
+                createdLo: expect.any(Number),
+                createdHi: expect.any(Number),
+                policyVersion: 1,
+                signature: 'software-mode-unsigned',
+                blobHash: expect.stringMatching(/^[0-9a-f]{64}$/),
+            },
+            holdDurationMs: 604800000,
+            ledgerSeq: 0,
+        });
+        const createInput = {
+            envelope,
+            holdId: 'test-hold',
+            expectedDid: plaintext.did,
+            expectedShareVersion: 1,
+            enrollmentEpoch: 1,
+            releasePolicy: 'hold' as const,
+            clientEphemeralPublicKey: client.publicKey,
         };
+        for (const change of [
+            { expectedDid: 'did:key:other' },
+            { expectedShareVersion: 2 },
+            { enrollmentEpoch: 0 },
+            { releasePolicy: 'pin' as const },
+        ]) {
+            await expect(enclave.createHold({ ...createInput, ...change })).rejects.toBeInstanceOf(
+                EscrowPolicyError
+            );
+        }
+        await expect(
+            enclave.createHold({ ...createInput, envelope: { ...envelope, ciphertext: 'bad' } })
+        ).rejects.toBeInstanceOf(EscrowBlobError);
         const request = {
             envelope,
             hold,
             clientEphemeralPublicKey: client.publicKey,
             expectedDid: plaintext.did,
         };
+        await expect(enclave.cancelHold(request)).resolves.toBeUndefined();
+        for (const change of [
+            { expectedDid: 'did:key:other' },
+            { clientEphemeralPublicKey: keys.publicKey },
+            { hold: { ...hold, hold: { ...hold.hold, did: 'did:key:other' } } },
+        ]) {
+            await expect(enclave.cancelHold({ ...request, ...change })).rejects.toBeInstanceOf(
+                EscrowPolicyError
+            );
+        }
+        await expect(
+            enclave.cancelHold({ ...request, envelope: { ...envelope, ciphertext: 'bad' } })
+        ).rejects.toBeInstanceOf(EscrowBlobError);
         await expect(
             enclave.releaseEscrow({ ...request, now: new Date(999) })
         ).rejects.toBeInstanceOf(EscrowPolicyError);
-        for (const changed of [
-            { status: 'cancelled' as const },
-            { shareVersion: 2 },
-            { primaryDid: 'did:key:wrong' },
-        ]) {
+        for (const changed of [{ shareVersion: 2 }, { did: 'did:key:wrong' }]) {
             await expect(
                 enclave.releaseEscrow({
                     ...request,
-                    hold: { ...hold, ...changed },
+                    hold: { ...hold, hold: { ...hold.hold, ...changed } },
                     now: new Date(1000),
                 })
             ).rejects.toBeInstanceOf(EscrowPolicyError);
@@ -166,7 +309,7 @@ describe('software enclave', () => {
         expect(await openEscrowRelease(released.sealed, client.privateKey)).toEqual({
             ...plaintext,
             version: 1,
-            holdId: hold._id,
+            holdId: hold.hold.holdId,
         });
         await expect(
             enclave.verifyEscrowBlob({
@@ -220,20 +363,29 @@ describe('software enclave', () => {
                     expectedShareVersion: 1,
                 })
             ).toEqual({ ok: true, hasPin: verifier });
+            const createInput = {
+                envelope,
+                holdId: 'pin-hold',
+                expectedDid: plaintext.did,
+                expectedShareVersion: 1,
+                enrollmentEpoch: 1,
+                releasePolicy: policy,
+                clientEphemeralPublicKey: client.publicKey,
+            };
+            if (policy === 'pin' && !verifier) {
+                await expect(enclave.createHold(createInput)).rejects.toBeInstanceOf(
+                    EscrowPolicyError
+                );
+                return;
+            }
+            const { holdRecord } = await enclave.createHold(createInput);
             const request = {
                 envelope,
                 expectedDid: plaintext.did,
                 clientEphemeralPublicKey: client.publicKey,
                 pinProof: proof,
-                hold: {
-                    _id: 'pin-hold',
-                    status: 'pending' as const,
-                    primaryDid: plaintext.did,
-                    shareVersion: 1,
-                    releasePolicy: policy,
-                    releaseAfter: new Date(0),
-                    clientEphemeralPublicKey: client.publicKey,
-                },
+                hold: holdRecord,
+                now: new Date(holdRecord.hold.createdHi + holdRecord.holdDurationMs),
             };
             if (error) await expect(enclave.releaseEscrow(request)).rejects.toBeInstanceOf(error);
             else {
@@ -246,4 +398,53 @@ describe('software enclave', () => {
             }
         }
     );
+
+    // P9.1 software-enclave equivalent: every configured key other than
+    // activeKeyId is already usable for decrypt (verifyEscrowBlob/createHold/
+    // releaseEscrow key the plaintext lookup by the envelope's own keyId, not
+    // by activeKeyId) — this test asserts the attestation now ADVERTISES that
+    // existing capability, and that a blob still sealed under a retired key
+    // decrypts/creates a hold/releases exactly like a current-key blob.
+    it('advertises other configured keys as previousKeyIds and still releases a blob sealed under one', async () => {
+        const active = await generateEscrowKeyPair();
+        const retired = await generateEscrowKeyPair();
+        const client = await generateEscrowKeyPair();
+        const enclave = new SoftwareEnclave({
+            privateKeys: { active: active.privateKey, retired: retired.privateKey },
+            activeKeyId: 'active',
+        });
+        const attestation = await enclave.getAttestation();
+        expect(attestation.keyId).toBe('active');
+        expect(attestation.previousKeyIds).toEqual(['retired']);
+        const plaintext = { recoveryShare: 'cd'.repeat(33), did: 'did:key:test', shareVersion: 1 };
+        const envelope = await encryptEscrowBlob(plaintext, retired.publicKey, 'retired');
+        expect(
+            await enclave.verifyEscrowBlob({
+                envelope,
+                expectedDid: plaintext.did,
+                expectedShareVersion: 1,
+            })
+        ).toEqual({ ok: true, hasPin: false });
+        const { holdRecord } = await enclave.createHold({
+            envelope,
+            holdId: 'retired-key-hold',
+            expectedDid: plaintext.did,
+            expectedShareVersion: 1,
+            enrollmentEpoch: 1,
+            releasePolicy: 'hold',
+            clientEphemeralPublicKey: client.publicKey,
+        });
+        const result = await enclave.releaseEscrow({
+            envelope,
+            hold: holdRecord,
+            expectedDid: plaintext.did,
+            clientEphemeralPublicKey: client.publicKey,
+            now: new Date(holdRecord.hold.createdHi + holdRecord.holdDurationMs),
+        });
+        expect(await openEscrowRelease(result.sealed, client.privateKey)).toEqual({
+            ...plaintext,
+            version: 1,
+            holdId: 'retired-key-hold',
+        });
+    });
 });