@learncard/lca-api-service 1.5.1 → 1.5.3

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

@@ -1,4 +1,15 @@
-import type { EscrowEnvelope } from '@learncard/sss-key-manager';
+import type { EscrowEnvelope, SignedEscrowEnrollmentIntent } from '@learncard/sss-key-manager';
+import type {
+    AuthorityRecord,
+    AuthorityHoldReceipt,
+    AuthorityMutationResult,
+    AuthorityStateResponse,
+} from './authorityContract';
+export interface ApplyEnrollmentInput {
+    signedIntent: SignedEscrowEnrollmentIntent;
+    sourceEnvelope: EscrowEnvelope | null;
+    targetEnvelope: EscrowEnvelope | null;
+}
 // Hold records are independent of host Mongo status and deadlines.
 
 export interface EnclaveAttestation {
@@ -41,11 +52,25 @@ export interface EnclaveCreateHoldInput {
     clientEphemeralPublicKey: string;
 }
 export interface CancelHoldRequest {
+    requestId?: string;
     envelope: EscrowEnvelope;
     hold: EscrowHoldRecord;
     clientEphemeralPublicKey: string;
     expectedDid: string;
 }
+/** P9.1 (attack C): `code` is the one-time code itself (compared against a
+ * stored hash enclave-side), never a proof — unlike `ReleaseRequest.pinProof`. */
+export interface ConfirmHoldRequest extends CancelHoldRequest {
+    code: string;
+}
+export type ResendCodeRequest = CancelHoldRequest;
+/** P9.1 (attack C): system-initiated (lca-api's hourly job) — no envelope or
+ * signed hold, since there is no user action to authenticate. */
+export interface SendReleaseWarningRequest {
+    requestId?: string;
+    holdId: string;
+    expectedDid: string;
+}
 export interface VerifyEscrowBlobInput {
     envelope: EscrowEnvelope;
     expectedDid: string;
@@ -60,6 +85,7 @@ export interface ReleaseRequest extends CancelHoldRequest {
 }
 export interface ReleaseResult {
     sealed: EscrowEnvelope;
+    receipt?: AuthorityRecord;
 }
 export interface CarryPinVerifierInput {
     sourceEnvelope: EscrowEnvelope;
@@ -80,6 +106,12 @@ export interface RewrapEscrowBlobInput {
     sourceEnrollmentEpoch: number;
 }
 export interface EscrowEnclave {
+    /** Remote authority only; software mode must not impersonate signed authority. */
+    getEnrollmentState?(input: {
+        expectedDid: string;
+        nonce: string;
+    }): Promise<AuthorityStateResponse>;
+    applyEnrollmentIntent?(input: ApplyEnrollmentInput): Promise<AuthorityMutationResult>;
     /** `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>;
@@ -91,10 +123,34 @@ export interface EscrowEnclave {
      * `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 }>;
+    rewrapEscrowBlob(
+        input: RewrapEscrowBlobInput
+    ): Promise<{ envelope: EscrowEnvelope; authority?: AuthorityMutationResult }>;
     releaseEscrow(input: ReleaseRequest): Promise<ReleaseResult>;
-    createHold(input: EnclaveCreateHoldInput): Promise<{ holdRecord: EscrowHoldRecord }>;
-    cancelHold(input: CancelHoldRequest): Promise<void>;
+    createHold(input: EnclaveCreateHoldInput): Promise<{
+        holdRecord: EscrowHoldRecord;
+        delivery?: { codeSent: boolean; proof: AuthorityHoldReceipt };
+    }>;
+    getHoldState?(input: {
+        expectedDid: string;
+        hold: EscrowHoldRecord;
+        nonce: string;
+    }): Promise<{ proof: AuthorityRecord }>;
+    cancelHold(input: CancelHoldRequest): Promise<void | { receipt: AuthorityRecord }>;
+    /** P9.1 (attack C): authority (nitro) mode only — software mode never
+     * produces an awaiting-confirmation hold, so it has nothing to confirm.
+     * `confirmedAtMs` is the enclave's authoritative confirmation time
+     * (present on both a fresh confirm and an idempotent retry); callers
+     * must use it instead of a locally-observed clock to compute deadlines. */
+    confirmHold?(
+        input: ConfirmHoldRequest
+    ): Promise<{ receipt: AuthorityHoldReceipt; confirmedAtMs: number }>;
+    resendCode?(input: ResendCodeRequest): Promise<{ receipt: AuthorityRecord }>;
+    /** `releaseWarningSentAtMs` is the enclave's authoritative warning-sent
+     * time, present on both a fresh send and an idempotent retry. */
+    sendReleaseWarning?(
+        input: SendReleaseWarningRequest
+    ): Promise<{ receipt: AuthorityHoldReceipt; releaseWarningSentAtMs: number }>;
 }
 export class EscrowPolicyError extends Error {
     constructor() {
@@ -102,6 +158,12 @@ export class EscrowPolicyError extends Error {
         this.name = 'EscrowPolicyError';
     }
 }
+export class EscrowCodeError extends Error {
+    constructor(public readonly reason: 'codeMismatch' | 'codeExpired' | 'codeLocked') {
+        super(reason);
+        this.name = 'EscrowCodeError';
+    }
+}
 export class EscrowPinMismatchError extends Error {
     constructor() {
         super('Incorrect PIN.');
@@ -115,7 +177,17 @@ export class EscrowBlobError extends Error {
     }
 }
 export class EscrowUnavailableError extends Error {
-    constructor() {
+    constructor(
+        readonly reason:
+            | 'unavailable'
+            | 'ledger'
+            | 'time'
+            | 'transport'
+            | 'invalid_response'
+            | 'invalid_hold'
+            | 'http_refusal'
+            | 'rate_limit' = 'unavailable'
+    ) {
         super('Escrow recovery is not available.');
         this.name = 'EscrowUnavailableError';
     }

package/test/jobs/escrowHoldReminders.spec.ts

@@ -1,5 +1,5 @@
 import { randomUUID } from 'crypto';
-import { beforeAll, afterAll, afterEach, describe, it, expect } from 'vitest';
+import { beforeAll, afterAll, afterEach, beforeEach, describe, it, expect } from 'vitest';
 import { client } from '@mongo';
 import {
     createUserKeysIndexes,
@@ -14,10 +14,14 @@ import {
     generateEscrowResumeToken,
     hashEscrowResumeToken,
     recordEscrowHoldNotification,
+    computeEffectiveReleaseAfter,
+    ESCROW_RELEASE_TIME_MARGIN_MS,
+    ESCROW_RELEASE_WARNING_GAP_MS,
     type AuthProviderMapping,
 } from '@models';
 import {
     __setEscrowEnclaveForTests,
+    getEscrowEnclave,
     notifyEscrowHoldEvent,
 } from '../../src/services/escrow-enclave';
 import { escrowCancelTokenMatches, hashEscrowCancelToken } from '@helpers/escrowCancelToken';
@@ -91,6 +95,12 @@ beforeAll(async () => {
     await createEscrowHoldsIndexes();
 });
 
+// The reminder job scans every due hold (including overdue catch-up), so holds
+// left behind by other spec files sharing this Mongo would be picked up.
+beforeEach(async () => {
+    await getEscrowHoldsCollection().deleteMany({});
+});
+
 afterEach(async () => {
     const ids = seededProviderIds.splice(0);
     if (ids.length === 0) return;
@@ -114,10 +124,11 @@ describe('runEscrowHoldReminders', () => {
         );
         for (const hold of holds) await cancelEscrowHold(hold._id, 'did');
         // These legacy test records lack ciphertext: fail closed, but still rotate
-        // the bounded queue rather than retrying the same first three forever.
+        // the bounded queue rather than retrying the same first ones forever. The
+        // default 15s enclave timeout fits two calls in the job's 30s enclave budget.
         await runEscrowHoldReminders({ now, limit: 200 });
         const firstRun = await Promise.all(holds.map(hold => findEscrowHoldById(hold._id)));
-        expect(firstRun.map(hold => hold?.enclaveCancelAttempts).sort()).toEqual([0, 1, 1, 1]);
+        expect(firstRun.map(hold => hold?.enclaveCancelAttempts).sort()).toEqual([0, 0, 1, 1]);
         const unattempted = firstRun.find(hold => hold?.enclaveCancelAttempts === 0)!;
         await runEscrowHoldReminders({ now, limit: 1 });
         expect((await findEscrowHoldById(unattempted._id))?.enclaveCancelAttempts).toBe(1);
@@ -153,6 +164,187 @@ describe('runEscrowHoldReminders', () => {
         expect(attempts[1]).toBe(reminder._id);
     });
 
+    it('calls the enclave sendReleaseWarning instead of its own reminder notification for an authority-mode hold', async () => {
+        const now = new Date();
+        const hold = await seed(new Date(now.getTime() + HOUR));
+        await getEscrowHoldsCollection().updateOne(
+            { _id: hold._id },
+            { $set: { requiresConfirmation: true, confirmedAt: now } }
+        );
+        const calls: { holdId: string; expectedDid: string }[] = [];
+        // This file has no per-test enclave reset (unlike keys-escrow.spec.ts's
+        // beforeEach): Object.assign mutates the shared software singleton in
+        // place, so it must be cleaned up or it leaks into every later test.
+        const software = getEscrowEnclave() as unknown as Record<string, unknown>;
+        software.sendReleaseWarning = async (params: { holdId: string; expectedDid: string }) => {
+            calls.push(params);
+            return { success: true as const };
+        };
+        try {
+            const notified: string[] = [];
+            const notify: typeof notifyEscrowHoldEvent = async event => {
+                notified.push(event.hold._id);
+                return true;
+            };
+            const result = await runEscrowHoldReminders({ now, notify });
+            expect(result.reminded).toBe(1);
+            expect(calls).toEqual([
+                { holdId: hold.holdRecord.hold.holdId, expectedDid: hold.primaryDid },
+            ]);
+            expect(notified).toHaveLength(0);
+            const stored = await findEscrowHoldById(hold._id);
+            // P2-a: a successful enclave warning is now acknowledged in Mongo
+            // (previously left empty forever, causing a re-send every run).
+            expect(stored?.notifications.map(entry => entry.kind)).toEqual(['reminder']);
+        } finally {
+            delete software.sendReleaseWarning;
+        }
+    });
+
+    it('sends the release warning exactly once across consecutive hourly runs (P2-a)', async () => {
+        const now = new Date();
+        const hold = await seed(new Date(now.getTime() + HOUR));
+        await getEscrowHoldsCollection().updateOne(
+            { _id: hold._id },
+            { $set: { requiresConfirmation: true, confirmedAt: now } }
+        );
+        const calls: { holdId: string; expectedDid: string }[] = [];
+        const software = getEscrowEnclave() as unknown as Record<string, unknown>;
+        software.sendReleaseWarning = async (params: { holdId: string; expectedDid: string }) => {
+            calls.push(params);
+            return { success: true as const };
+        };
+        try {
+            const first = await runEscrowHoldReminders({ now });
+            const secondRun = await runEscrowHoldReminders({ now: new Date(now.getTime() + HOUR) });
+            expect(first.reminded).toBe(1);
+            expect(secondRun.reminded).toBe(0);
+            expect(calls).toHaveLength(1);
+            expect(
+                (await findEscrowHoldById(hold._id))?.notifications.map(entry => entry.kind)
+            ).toEqual(['reminder']);
+        } finally {
+            delete software.sendReleaseWarning;
+        }
+    });
+
+    it('a lost acknowledgment write is safe to retry and eventually stops re-calling the enclave (P2-a)', async () => {
+        const now = new Date();
+        const hold = await seed(new Date(now.getTime() + HOUR));
+        await getEscrowHoldsCollection().updateOne(
+            { _id: hold._id },
+            { $set: { requiresConfirmation: true, confirmedAt: now } }
+        );
+        const calls: { holdId: string; expectedDid: string }[] = [];
+        const software = getEscrowEnclave() as unknown as Record<string, unknown>;
+        software.sendReleaseWarning = async (params: { holdId: string; expectedDid: string }) => {
+            calls.push(params);
+            return {
+                receipt: {
+                    version: 1 as const,
+                    kind: calls.length === 1 ? ('commit' as const) : ('snapshot' as const),
+                    keyId: 'test-key',
+                    measurement: Array.from({ length: 32 }, () => 0),
+                    payload:
+                        calls.length === 1
+                            ? 'AQ=='
+                            : Buffer.from(
+                                  JSON.stringify([
+                                      'learncard-authority-hold-snapshot-v2',
+                                      params.holdId,
+                                      Array.from({ length: 32 }, () => 7),
+                                      'pending',
+                                      now.getTime(),
+                                      now.getTime(),
+                                      'g1',
+                                  ])
+                              ).toString('base64'),
+                    signature: Buffer.alloc(64).toString('base64'),
+                },
+                releaseWarningSentAtMs: now.getTime(),
+            };
+        };
+        try {
+            const first = await runEscrowHoldReminders({ now });
+            expect(first.reminded).toBe(1);
+            expect(calls).toHaveLength(1);
+            // Simulate the acknowledgment write being lost (e.g. a crash right
+            // after a successful enclave call) rather than mocking Mongo, so
+            // this exercises the job's own catch-up path: a real enclave would
+            // not re-send or move its timestamp on this retry (covered by the
+            // Rust-side idempotence test), but lca-api must not get stuck
+            // either, so it retries until its own acknowledgment lands.
+            await getEscrowHoldsCollection().updateOne(
+                { _id: hold._id },
+                { $set: { notifications: [], releaseAfter: hold.releaseAfter } }
+            );
+            const second = await runEscrowHoldReminders({ now });
+            expect(second.reminded).toBe(1);
+            expect(calls).toHaveLength(2);
+            expect(
+                (await findEscrowHoldById(hold._id))?.notifications.map(entry => entry.kind)
+            ).toEqual(['reminder']);
+            const third = await runEscrowHoldReminders({ now });
+            expect(third.reminded).toBe(0);
+            expect(calls).toHaveLength(2);
+        } finally {
+            delete software.sendReleaseWarning;
+        }
+    });
+
+    // [B] A catch-up warning sent well after the 7-day window elapsed (an
+    // outage, or the job simply not running for a while) must advertise an
+    // availability time derived from the LATER gate — the enclave's own
+    // `release_warning_sent_hi_ms + 24h` — not the hold's original,
+    // long-since-passed creation/confirmation-based estimate, which would
+    // otherwise keep telling the client it's ready when the enclave would
+    // still refuse release.
+    it('[B] an overdue warning advances the stored releaseAfter to the warning-based availability time', async () => {
+        const now = new Date();
+        // Confirmed 10 days ago: its own 7-day-plus-margin gate has long
+        // since passed, so only the warning-based gate can be the later one.
+        const confirmedAt = new Date(now.getTime() - 10 * 24 * HOUR);
+        const hold = await seed(new Date(confirmedAt.getTime() + HOUR));
+        await getEscrowHoldsCollection().updateOne(
+            { _id: hold._id },
+            { $set: { requiresConfirmation: true, confirmedAt } }
+        );
+        const releaseWarningSentAtMs = now.getTime();
+        const software = getEscrowEnclave() as unknown as Record<string, unknown>;
+        software.sendReleaseWarning = async () => ({
+            receipt: {
+                version: 1 as const,
+                kind: 'commit' as const,
+                keyId: 'test-key',
+                measurement: Array.from({ length: 32 }, () => 0),
+                payload: 'AQ==',
+                signature: Buffer.alloc(64).toString('base64'),
+            },
+            releaseWarningSentAtMs,
+        });
+        try {
+            const result = await runEscrowHoldReminders({ now });
+            expect(result.reminded).toBe(1);
+            const stored = await findEscrowHoldById(hold._id);
+            const expected = computeEffectiveReleaseAfter({
+                confirmedAtMs: confirmedAt.getTime(),
+                holdDurationMs: hold.holdRecord.holdDurationMs,
+                releaseWarningSentAtMs,
+            });
+            // Sanity: the warning-based gate really is the later one here.
+            expect(expected.getTime()).toBe(
+                releaseWarningSentAtMs +
+                    ESCROW_RELEASE_WARNING_GAP_MS +
+                    ESCROW_RELEASE_TIME_MARGIN_MS
+            );
+            expect(stored?.releaseAfter.getTime()).toBe(expected.getTime());
+            // And specifically later than the original (long-passed) estimate.
+            expect(stored!.releaseAfter.getTime()).toBeGreaterThan(hold.releaseAfter.getTime());
+        } finally {
+            delete software.sendReleaseWarning;
+        }
+    });
+
     it('retries an undelivered start notification with a cancel link', async () => {
         const now = new Date();
         const hold = await seed(new Date(now.getTime() + 7 * 24 * HOUR));