@learncard/lca-api-service 1.4.0 → 1.5.1

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

@@ -1,4 +1,6 @@
 import { timingSafeEqual } from 'crypto';
+import { escrowBlobIdentity } from './blobIdentity';
+import type { EnclaveCreateHoldInput, EscrowHoldRecord, CancelHoldRequest } from './types';
 import {
     decryptEscrowBlob,
     encryptEscrowBlob,
@@ -18,25 +20,72 @@ import {
     type ReleaseRequest,
     type ReleaseResult,
     type CarryPinVerifierInput,
+    type RewrapEscrowBlobInput,
 } from './types';
 
 export interface SoftwareEnclaveConfig {
     privateKeys: Record<string, string>;
     activeKeyId: string;
+    /** Supplied by the factory to match its configured host-trusted waiting period. */
+    holdDurationMs?: number;
 }
 
 /** In-process backend for development; host time is not an attested clock. */
 export class SoftwareEnclave implements EscrowEnclave {
     private readonly privateKeys: ReadonlyMap<string, string>;
     private readonly activeKeyId: string;
-
+    private readonly holdDurationMs: number;
     constructor(config: SoftwareEnclaveConfig) {
         this.privateKeys = new Map(Object.entries(config.privateKeys));
         this.activeKeyId = config.activeKeyId;
         if (!this.privateKeys.has(this.activeKeyId)) throw new EscrowUnavailableError();
+        // Match the factory configuration without a circular import; default is seven days.
+        this.holdDurationMs = config.holdDurationMs ?? 7 * 24 * 60 * 60 * 1000;
     }
-
-    async getAttestation(): Promise<EnclaveAttestation> {
+    async createHold(input: EnclaveCreateHoldInput): Promise<{ holdRecord: EscrowHoldRecord }> {
+        const blob = await this.decrypt(input.envelope);
+        if (
+            blob.did !== input.expectedDid ||
+            blob.shareVersion !== input.expectedShareVersion ||
+            !Number.isInteger(input.enrollmentEpoch) ||
+            input.enrollmentEpoch <= 0 ||
+            (input.releasePolicy === 'pin' && !blob.pinVerifier)
+        )
+            throw new EscrowPolicyError();
+        const blobHash = escrowBlobIdentity(input.envelope);
+        const now = Date.now();
+        return {
+            holdRecord: {
+                hold: {
+                    holdId: input.holdId,
+                    did: blob.did,
+                    shareVersion: input.expectedShareVersion,
+                    blobHash,
+                    enrollmentEpoch: input.enrollmentEpoch,
+                    releasePolicy: input.releasePolicy,
+                    clientEphemeralPublicKey: input.clientEphemeralPublicKey,
+                    createdLo: now,
+                    createdHi: now,
+                    policyVersion: 1,
+                    // Non-cryptographic placeholder: software mode trusts the host entirely.
+                    signature: 'software-mode-unsigned',
+                },
+                holdDurationMs: input.releasePolicy === 'pin' ? 0 : this.holdDurationMs,
+                ledgerSeq: 0,
+            },
+        };
+    }
+    async cancelHold(input: CancelHoldRequest): Promise<void> {
+        const blob = await this.decrypt(input.envelope);
+        if (
+            blob.did !== input.expectedDid ||
+            blob.did !== input.hold.hold.did ||
+            input.clientEphemeralPublicKey !== input.hold.hold.clientEphemeralPublicKey
+        )
+            throw new EscrowPolicyError();
+        // Development only: Mongo owns cancellation; there is no software enclave ledger.
+    }
+    async getAttestation(_nonce?: Uint8Array): Promise<EnclaveAttestation> {
         try {
             const subtle = globalThis.crypto.subtle;
             const key = await subtle.importKey(
@@ -62,6 +111,12 @@ export class SoftwareEnclave implements EscrowEnclave {
             const description = {
                 mode: 'software' as const,
                 keyId: this.activeKeyId,
+                // P9.1 software-enclave equivalent: every OTHER configured key is
+                // already decrypt-eligible in `decrypt()` below (keyed lookup by
+                // envelope keyId, not restricted to `activeKeyId`) — this just
+                // advertises that existing behaviour the same way the Nitro
+                // backend advertises its `ESCROW_PREVIOUS_KEY_IDS`.
+                previousKeyIds: [...this.privateKeys.keys()].filter(id => id !== this.activeKeyId),
                 publicKey,
                 issuedAt: new Date().toISOString(),
             };
@@ -98,7 +153,17 @@ export class SoftwareEnclave implements EscrowEnclave {
         return { ok: true, hasPin: !!blob.pinVerifier };
     }
 
-    /** Transfer only the verifier; recovery material remains sealed within the enclave. */
+    /**
+     * Transfer only the verifier; recovery material remains sealed within the enclave.
+     *
+     * `input.sourceEnrollmentEpoch` is intentionally unused: software mode has no
+     * enclave ledger to reset in the first place, so there is no epoch-scoped PIN
+     * attempt budget to carry. The PIN attempt budget here is `escrowPin.failedAttempts`
+     * / `verifiedFailedAttempts` in MongoDB (see routes/escrow.ts), which the enroll
+     * route already copies forward unchanged on every carry, independent of
+     * `enrollmentEpoch` — so software mode never had the epoch-reset bug this field
+     * exists to fix in remote/nitro mode.
+     */
     async carryPinVerifier(input: CarryPinVerifierInput) {
         const source = await this.decrypt(input.sourceEnvelope);
         const target = await this.decrypt(input.targetEnvelope);
@@ -122,19 +187,40 @@ export class SoftwareEnclave implements EscrowEnclave {
         };
     }
 
+    /**
+     * Software-mode equivalent of the Nitro enclave's `rewrap_escrow_blob`
+     * (P9.3): moves a blob sealed under any OTHER configured key onto the
+     * active key, unchanged otherwise. Mirrors its refusal shape — an
+     * envelope already under `activeKeyId` has nothing to migrate, and
+     * `decrypt()` already throws `EscrowBlobError` for a keyId this backend
+     * was never configured with, so both collapse into the same generic
+     * error. `sourceEnrollmentEpoch` is unused for the same reason
+     * `carryPinVerifier` ignores it above: no enclave ledger here, so no
+     * epoch-scoped PIN attempt budget to carry.
+     */
+    async rewrapEscrowBlob(input: RewrapEscrowBlobInput) {
+        const parsed = parseEscrowEnvelope(input.envelope);
+        if (parsed.keyId === this.activeKeyId) throw new EscrowBlobError();
+        const blob = await this.decrypt(input.envelope);
+        if (blob.did !== input.expectedDid || blob.shareVersion !== input.expectedShareVersion)
+            throw new EscrowBlobError();
+        const attestation = await this.getAttestation();
+        return {
+            envelope: await encryptEscrowBlob(blob, attestation.publicKey, attestation.keyId),
+        };
+    }
+
     async releaseEscrow(input: ReleaseRequest): Promise<ReleaseResult> {
-        const { hold } = input;
+        const { hold } = input.hold;
         if (
-            hold.status !== 'pending' ||
             input.clientEphemeralPublicKey !== hold.clientEphemeralPublicKey ||
-            !((input.now ?? new Date()).getTime() >= hold.releaseAfter.getTime())
-        ) {
+            !((input.now ?? new Date()).getTime() >= hold.createdHi + input.hold.holdDurationMs)
+        )
             throw new EscrowPolicyError();
-        }
         const blob = await this.decrypt(input.envelope);
         if (
             blob.did !== input.expectedDid ||
-            blob.did !== hold.primaryDid ||
+            blob.did !== hold.did ||
             blob.shareVersion !== hold.shareVersion
         )
             throw new EscrowPolicyError();
@@ -156,7 +242,7 @@ export class SoftwareEnclave implements EscrowEnclave {
                         recoveryShare: blob.recoveryShare,
                         did: blob.did,
                         shareVersion: blob.shareVersion,
-                        holdId: hold._id,
+                        holdId: hold.holdId,
                     },
                     input.clientEphemeralPublicKey
                 ),

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

@@ -1,36 +1,60 @@
 import type { EscrowEnvelope } from '@learncard/sss-key-manager';
-import type { EscrowHold } from '../../models/EscrowHold';
+// Hold records are independent of host Mongo status and deadlines.
 
 export interface EnclaveAttestation {
     mode: 'software' | 'nitro';
     keyId: string;
+    /** P9.1: retired keyIds the enclave still accepts for decrypt only (never
+     * for sealing output). Empty/absent means no previous key is configured. */
+    previousKeyIds?: string[];
     publicKey: string;
     measurements: { imageSha384?: string; pcr0?: string; pcr1?: string; pcr2?: string };
     document: string;
     issuedAt: string;
 }
-export type EscrowHoldForEnclave = Pick<
-    EscrowHold,
-    | '_id'
-    | 'status'
-    | 'releaseAfter'
-    | 'releasePolicy'
-    | 'primaryDid'
-    | 'shareVersion'
-    | 'clientEphemeralPublicKey'
->;
-export interface VerifyEscrowBlobInput {
+export interface EscrowHoldRecord {
+    [key: string]: unknown;
+    hold: {
+        [key: string]: unknown;
+        holdId: string;
+        did: string;
+        shareVersion: number;
+        blobHash: string;
+        enrollmentEpoch: number;
+        releasePolicy: 'hold' | 'pin';
+        clientEphemeralPublicKey: string;
+        createdLo: number;
+        createdHi: number;
+        policyVersion: number;
+        signature: string;
+    };
+    holdDurationMs: number;
+    ledgerSeq: number;
+}
+export interface EnclaveCreateHoldInput {
     envelope: EscrowEnvelope;
+    holdId: string;
     expectedDid: string;
     expectedShareVersion: number;
+    enrollmentEpoch: number;
+    releasePolicy: 'hold' | 'pin';
+    clientEphemeralPublicKey: string;
 }
-export type VerifyEscrowBlobResult =
-    { ok: true; hasPin: boolean } | { ok: false; hasPin: boolean; reason: string };
-export interface ReleaseRequest {
+export interface CancelHoldRequest {
     envelope: EscrowEnvelope;
-    hold: EscrowHoldForEnclave;
+    hold: EscrowHoldRecord;
     clientEphemeralPublicKey: string;
     expectedDid: string;
+}
+export interface VerifyEscrowBlobInput {
+    envelope: EscrowEnvelope;
+    expectedDid: string;
+    expectedShareVersion: number;
+}
+export type VerifyEscrowBlobResult =
+    { ok: true; hasPin: boolean } | { ok: false; hasPin: boolean; reason: string };
+export interface ReleaseRequest extends CancelHoldRequest {
+    /** Development-only host clock; never forwarded by the remote backend. */
     now?: Date;
     pinProof?: string;
 }
@@ -43,12 +67,34 @@ export interface CarryPinVerifierInput {
     expectedDid: string;
     sourceShareVersion: number;
     targetShareVersion: number;
+    /** Signed source-record binding; blob hash, not epoch, selects the chain. */
+    sourceEnrollmentEpoch: number;
+    /** Signed binding for the output blob's first Carried record. */
+    targetEnrollmentEpoch: number;
+}
+export interface RewrapEscrowBlobInput {
+    envelope: EscrowEnvelope;
+    expectedDid: string;
+    expectedShareVersion: number;
+    /** Source and destination record binding. Rewrap preserves this epoch. */
+    sourceEnrollmentEpoch: number;
 }
 export interface EscrowEnclave {
-    getAttestation(): Promise<EnclaveAttestation>;
+    /** `nonce` binds a nitro attestation to one client-generated challenge (64 hex chars,
+     * decoded to bytes); the software backend has no freshness story and ignores it. */
+    getAttestation(nonce?: Uint8Array): Promise<EnclaveAttestation>;
     verifyEscrowBlob(input: VerifyEscrowBlobInput): Promise<VerifyEscrowBlobResult>;
     carryPinVerifier(input: CarryPinVerifierInput): Promise<{ envelope: EscrowEnvelope }>;
+    /** P9.3: migrates a copy sealed under a recognised PREVIOUS key onto the
+     * CURRENT key (same did/shareVersion/recoveryShare/pinVerifier), so a
+     * previous key can eventually be retired. Refuses (generic
+     * `EscrowBlobError`) unless the envelope's own keyId is a recognised
+     * previous key — never the current key (nothing to migrate) or an
+     * unknown one. */
+    rewrapEscrowBlob(input: RewrapEscrowBlobInput): Promise<{ envelope: EscrowEnvelope }>;
     releaseEscrow(input: ReleaseRequest): Promise<ReleaseResult>;
+    createHold(input: EnclaveCreateHoldInput): Promise<{ holdRecord: EscrowHoldRecord }>;
+    cancelHold(input: CancelHoldRequest): Promise<void>;
 }
 export class EscrowPolicyError extends Error {
     constructor() {