@learncard/lca-api-service 1.4.0 → 1.5.0

package/src/services/delivery/adapters/postmark.adapter.ts

@@ -9,7 +9,11 @@
 import { ServerClient } from 'postmark';
 
 import { renderEmail, resolveBranding } from '@learncard/email-templates';
-import type { TemplateId, TemplateDataMap } from '@learncard/email-templates';
+import type {
+    TemplateId,
+    TemplateDataMap,
+    EscrowHoldCancelledReason,
+} from '@learncard/email-templates';
 
 import { DeliveryService, Notification, isTemplateNotification } from '../delivery.service';
 
@@ -35,6 +39,11 @@ const LOCAL_TEMPLATE_ALIASES: Record<string, TemplateId> = {
     'account-approved': 'account-approved',
     'contact-method-verification': 'contact-method-verification',
     'account-sign-in-changed': 'account-sign-in-changed',
+    'escrow-hold-started': 'escrow-hold-started',
+    'escrow-hold-reminder': 'escrow-hold-reminder',
+    'escrow-hold-released': 'escrow-hold-released',
+    'escrow-hold-cancelled': 'escrow-hold-cancelled',
+    'escrow-pin-locked': 'escrow-pin-locked',
 };
 
 /** Whether the given alias is a sentinel we registered (vs. a real Postmark alias). */
@@ -206,6 +215,39 @@ export class PostmarkAdapter implements DeliveryService {
                     user: model.user as { displayName?: string } | undefined,
                 };
 
+            case 'escrow-hold-started':
+                return {
+                    requestedAt: (model.requestedAt as string) ?? '',
+                    releaseAfter: (model.releaseAfter as string) ?? '',
+                    cancelUrl: (model.cancelUrl as string) ?? '',
+                    deviceHint: model.deviceHint as string | undefined,
+                };
+
+            case 'escrow-hold-reminder':
+                return {
+                    releaseAfter: (model.releaseAfter as string) ?? '',
+                    cancelUrl: (model.cancelUrl as string) ?? '',
+                };
+
+            case 'escrow-hold-released':
+                return {
+                    completedAt: (model.completedAt as string) ?? '',
+                    supportUrl: model.supportUrl as string | undefined,
+                };
+
+            case 'escrow-hold-cancelled':
+                return {
+                    cancelledAt: (model.cancelledAt as string) ?? '',
+                    reason: model.reason as EscrowHoldCancelledReason | undefined,
+                };
+
+            case 'escrow-pin-locked':
+                return {
+                    lockedAt: (model.lockedAt as string) ?? '',
+                    releaseAfter: model.releaseAfter as string | undefined,
+                    cancelUrl: model.cancelUrl as string | undefined,
+                };
+
             default:
                 return model as TemplateDataMap[TemplateId];
         }

package/src/services/escrow-enclave/README.md

@@ -14,19 +14,45 @@ existing host-trusted model, but does not protect against a malicious host eithe
 The API atomically reserves one of ten lifetime attempts before claiming the hold
 and calling the enclave. Failed releases burn the single-use hold. Exhaustion
 disables PIN recovery and cancels pending PIN holds; delayed recovery remains
-available. Successful PIN recovery does not replenish the lifetime budget; authenticated enrollment
-with a new PIN starts a fresh counter. Setting or changing a PIN requires client share
-rotation. Inbox compromise plus a correct PIN guess can recover the account
-(at most 10/1,000,000 for a uniformly random six-digit PIN).
+available. Successful PIN recovery does not replenish the lifetime budget; authenticated
+enrollment with a new PIN starts a fresh counter. Setting or changing a PIN requires
+client share rotation. Inbox compromise plus a correct PIN guess can recover the
+account (at most 10/1,000,000 for a uniformly random six-digit PIN).
+
+Software hold records contain a non-cryptographic signature placeholder and no
+ledger. The factory supplies its configured hold duration (seven days by default);
+PIN holds have zero duration. Mongo remains responsible for single-use/cancellation.
 
 ## Nitro requirement
 
-The real Nitro enclave application lives on a separate branch and **must implement
-`carryPinVerifier`** with the same contract before PIN carry is available there:
+In `remote` mode, the enclave-owned reserve → verify → commit ledger is the
+intended security boundary (`services/escrow-enclave-app/src/policy.rs` `release_pin`
+and `ledger.rs` `verify_pin`), pending full P1.8/P3.3 production wiring. The host-owned
+Mongo counter (`reserveEscrowPinAttempt` and related helpers) remains defense-in-depth
+and UX only, not the boundary against a malicious host.
+
+D3 is **rollback detection, not prevention**: see
+`services/escrow-enclave-app/README.md`, "D3: rollback detection, not prevention".
+Do not treat the signed ledger as an independent freshness oracle. Per D13, the
+ledger is enrollment-wide, bounded to 64 records, and shares a ten-lifetime-reservation
+budget across holds for that enrollment.
+
+New holds store the full opaque SignedHoldRecord before returning to callers;
+release and cancellation forward that record rather than unsigned host fields.
+Legacy Mongo rows without a record can still be cancelled locally, but cannot
+release. Local cancellation atomically queues durable enclave revocation. The hourly
+reminders job retries failures; only success confirms revocation. Unconfirmed
+cancellations block new holds for the account and alarm within 24 hours of release
+or while overdue. See `services/escrow-enclave-app/SECURITY.md` for the eventual
+consistency, ambiguous terminal-error, and BLOCKER-ENROLLMENT limitations.
+
+The real Nitro enclave application **implements `carryPinVerifier`** (P8.1/P8.2)
+with the same contract described here:
 
 ```ts
 carryPinVerifier({ sourceEnvelope, targetEnvelope, expectedDid,
-    sourceShareVersion, targetShareVersion }): Promise<{ envelope }>
+    sourceShareVersion, targetShareVersion,
+    sourceEnrollmentEpoch, targetEnrollmentEpoch }): Promise<{ envelope }>
 ```
 
 Decrypt both envelopes inside the enclave. Require both DIDs to equal `expectedDid`,
@@ -46,6 +72,51 @@ lost compare-and-swap falls back to normal PIN-less enrollment with a secret-fre
 Explicit new PIN enrollment is unchanged; explicit removal sends `clearPin: true`
 to bypass carry (it cannot be combined with `pinSalt`).
 
-TODO(escrow-nitro): Move the counter into enclave-internal, replicated state with
-decrement-before-decrypt semantics and rollback protection. Do not reuse the
-host-owned counter as the security boundary for a Nitro implementation.
+`services/escrow-enclave-app/src/wire.rs` implements `carryPinVerifier` as
+`wire::v1::Request::CarryPinVerifier`, dispatched in `src/server.rs` to
+`Policy::carry_pin_verifier` (`src/policy.rs`), and reachable over HTTP at
+`POST /v1/carry-pin-verifier` (emulator: `src/server/http.rs`; production parent:
+`services/escrow-enclave-host`). `RemoteEnclave.carryPinVerifier` (`remoteEnclave.ts`)
+calls that endpoint the same way `verifyEscrowBlob`/`releaseEscrow` do, with zod
+response validation and the same fail-closed error mapping.
+
+`carry_pin_verifier` decrypts/validates/reseals: unlike `createHold`/`release`/
+`cancelHold`, it needs no `EnrollmentSource`, but now requires trusted time to
+sign a destination-genesis Carried record. It can still
+works in `remote` mode today even though every other mutating operation fails
+closed with `Unavailable` under the enclave's BLOCKER-ENROLLMENT gate (see
+`services/escrow-enclave-app/README.md`'s intro paragraph and `SECURITY.md`'s
+"Open Items / Launch Blockers").
+
+**P8.3 / v2**: it observes the source blob's ledger chain and writes the output
+blob's first Carried record before returning ciphertext, so
+the PIN attempt budget itself carries forward across a rotation instead of
+resetting. Tenant, decrypted source DID hash and actual blob hash locate that chain;
+`sourceEnrollmentEpoch` remains a signed record binding, never a chain selector.
+`targetEnrollmentEpoch` binds carry output; rewrap preserves the source epoch.
+The chain is verified with
+the same signature/sequence/binding checks (`Ledger::verify_chain`), and a
+chain that fails that verification is a fail-closed `Ledger`/`Unavailable`
+error, not silently treated as empty. The target's `pinAttemptsFloor` becomes
+`source.pinAttemptsFloor (default 0) + source_chain.attempts_used`, capped at
+the ten-attempt lifetime maximum; a `release_pin` against a blob carrying that
+floor only permits `10 - floor` further local attempts before locking, so a
+carry — including a carry of a carry — never hands out a fresh budget and
+never lowers whatever floor the source blob already had. `pinAttemptsFloor` is
+stripped (like `pinVerifier`) before any release plaintext reaches the client:
+it is enclave/ledger bookkeeping, not client-facing data. Positive floors must
+match the chain's Carried genesis. The independent monitor checks source-head
+accounting on inserts and sweeps. Choosing an older PIN-bearing copy with fewer
+attempts still requires an authenticated current-enrollment authority to prevent.
+Nitro never ran in production; there is no legacy-chain migration.
+
+Software mode (`softwareEnclave.ts`) accepts both epoch fields but
+ignores them: software mode has no enclave ledger to reset in the first place,
+so there is no epoch-scoped budget to carry — its PIN attempt budget is the
+host's `escrowPin.failedAttempts`/`verifiedFailedAttempts` counters in
+MongoDB, which the enroll route already copies forward unchanged on every
+carry, independent of `enrollmentEpoch`.
+
+## Key rotation
+
+When the enclave key is rotated, previous keys are retained as read-only. The `assertFreshEscrowBlob` check allows carry eligibility for blobs sealed under a recognized previous key (stale-but-usable). The `escrowBlobRewrap` job runs periodically to migrate these blobs to the current key, skipping accounts with pending holds. Use `scripts/escrow-blob-mode-report.ts` with `--current-key-id` and `--previous-key-ids` to monitor migration progress.

package/src/services/escrow-enclave/__fixtures__/tls/pinned-ca.pem

@@ -0,0 +1,11 @@
+-----BEGIN CERTIFICATE-----
+MIIBnTCCAUKgAwIBAgIUX8sxxI8R2Ee+rvQYnO4eAo9Ink0wCgYIKoZIzj0EAwIw
+GTEXMBUGA1UEAwwOcGlubmVkIHRlc3QgQ0EwIBcNMjYxMDAyMTczMjQ3WhgPMjEy
+NjA5MDgxNzMyNDdaMBkxFzAVBgNVBAMMDnBpbm5lZCB0ZXN0IENBMFkwEwYHKoZI
+zj0CAQYIKoZIzj0DAQcDQgAEfZw7amNFFbLuEIEhlMUMw5zy0OJsUy1eK8jAm6Pf
+QgTg+A/vJXuPwQCcyGyLAnMRkKzLGFEuTFn4WbXhbxXXK6NmMGQwHQYDVR0OBBYE
+FCppqmpr4350poKX2C9Zch+OLIqfMB8GA1UdIwQYMBaAFCppqmpr4350poKX2C9Z
+ch+OLIqfMBIGA1UdEwEB/wQIMAYBAf8CAQAwDgYDVR0PAQH/BAQDAgIEMAoGCCqG
+SM49BAMCA0kAMEYCIQCFW0tlq57l7AkyRMv0QP1FsrDZp+t8TAhpPfBxThtuKQIh
+ALrjfvsSzWNjYeQnuDYOBqB4AadnDE8lvkPdf6d5KDjn
+-----END CERTIFICATE-----

package/src/services/escrow-enclave/__fixtures__/tls/pinned-leaf.key

@@ -0,0 +1,5 @@
+-----BEGIN PRIVATE KEY-----
+MIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQQgdWjP158c+uimIld5
+cyzEEh1k7BU6jfpb7TynI1SLneihRANCAAS1jfWWPshOTRLxqm9JB3u5LjXmC9LC
+tNvWc49A7pYxqlr/cFmVkUkrB8JoFX23r05WmV5ZSvpu62BpGAT4TZQh
+-----END PRIVATE KEY-----

package/src/services/escrow-enclave/__fixtures__/tls/pinned-leaf.pem

@@ -0,0 +1,12 @@
+-----BEGIN CERTIFICATE-----
+MIIBvjCCAWSgAwIBAgIUHI1pe3GtEABXkmHdADf35RMT+4UwCgYIKoZIzj0EAwIw
+GTEXMBUGA1UEAwwOcGlubmVkIHRlc3QgQ0EwIBcNMjYxMDAyMTczMjQ3WhgPMjEy
+NjA5MDgxNzMyNDdaMBQxEjAQBgNVBAMMCWxvY2FsaG9zdDBZMBMGByqGSM49AgEG
+CCqGSM49AwEHA0IABLWN9ZY+yE5NEvGqb0kHe7kuNeYL0sK029Zzj0DuljGqWv9w
+WZWRSSsHwmgVfbevTlaZXllK+m7rYGkYBPhNlCGjgYwwgYkwDAYDVR0TAQH/BAIw
+ADAOBgNVHQ8BAf8EBAMCB4AwEwYDVR0lBAwwCgYIKwYBBQUHAwEwFAYDVR0RBA0w
+C4IJbG9jYWxob3N0MB0GA1UdDgQWBBQ683SeqkVStM5taUD0Xl2iinptHzAfBgNV
+HSMEGDAWgBQqaapqa+N+dKaCl9gvWXIfjiyKnzAKBggqhkjOPQQDAgNIADBFAiEA
+2NydSl5d/JAnib147fmSD97SiIOoYeR0U2TtKSCZOnICICXk+JJ7Zfi7e8orhL4M
+qbFHUur9Li9EysqWauUlZ3Uf
+-----END CERTIFICATE-----

package/src/services/escrow-enclave/__fixtures__/tls/rogue-ca.pem

@@ -0,0 +1,11 @@
+-----BEGIN CERTIFICATE-----
+MIIBmzCCAUCgAwIBAgIUL3KTPKqBu6PunDVaswtgh4DSsMcwCgYIKoZIzj0EAwIw
+GDEWMBQGA1UEAwwNcm9ndWUgdGVzdCBDQTAgFw0yNjEwMDIxNzMyNDdaGA8yMTI2
+MDkwODE3MzI0N1owGDEWMBQGA1UEAwwNcm9ndWUgdGVzdCBDQTBZMBMGByqGSM49
+AgEGCCqGSM49AwEHA0IABJELPnDkTrlV1JvqGnw49Y1Ieq9X5LtRvk2YAi82u0dP
+HKVAz/VDg6mjDZE0iCksMbySnMi21U15OCR9euVXgeujZjBkMB0GA1UdDgQWBBR4
+j+2A3mYxGVN4wh5A+n7KgYrg/jAfBgNVHSMEGDAWgBR4j+2A3mYxGVN4wh5A+n7K
+gYrg/jASBgNVHRMBAf8ECDAGAQH/AgEAMA4GA1UdDwEB/wQEAwICBDAKBggqhkjO
+PQQDAgNJADBGAiEA2wS9nA9hRhvnq+bkfpahBQqRucjapHUii6ifKFPRW6kCIQDY
+WBdfGkXMxHO3SAdWn7Os/bCTfzIfGSTf1RirYu0mxw==
+-----END CERTIFICATE-----

package/src/services/escrow-enclave/__fixtures__/tls/rogue-leaf.key

@@ -0,0 +1,5 @@
+-----BEGIN PRIVATE KEY-----
+MIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQQg5M9NiEz2zo+9wmbb
+tUhG80uMcB12+M/+hk5lZFEH/UmhRANCAAQKfZQnflrAA6jmVBNSe1WnPxDkQOkv
+RksIG/Iw0afcYucz6V33V1suoyAzWgEdMI7ZvoCMKBPUZxckdZ+nElFx
+-----END PRIVATE KEY-----

package/src/services/escrow-enclave/__fixtures__/tls/rogue-leaf.pem

@@ -0,0 +1,12 @@
+-----BEGIN CERTIFICATE-----
+MIIBvTCCAWOgAwIBAgIUIEjECAktIlQDeXXVSVMtVFKkd5IwCgYIKoZIzj0EAwIw
+GDEWMBQGA1UEAwwNcm9ndWUgdGVzdCBDQTAgFw0yNjEwMDIxNzMyNDdaGA8yMTI2
+MDkwODE3MzI0N1owFDESMBAGA1UEAwwJbG9jYWxob3N0MFkwEwYHKoZIzj0CAQYI
+KoZIzj0DAQcDQgAECn2UJ35awAOo5lQTUntVpz8Q5EDpL0ZLCBvyMNGn3GLnM+ld
+91dbLqMgM1oBHTCO2b6AjCgT1GcXJHWfpxJRcaOBjDCBiTAMBgNVHRMBAf8EAjAA
+MA4GA1UdDwEB/wQEAwIHgDATBgNVHSUEDDAKBggrBgEFBQcDATAUBgNVHREEDTAL
+gglsb2NhbGhvc3QwHQYDVR0OBBYEFO6h+RmT2lYntPXdm74FuKlCr/WJMB8GA1Ud
+IwQYMBaAFHiP7YDeZjEZU3jCHkD6fsqBiuD+MAoGCCqGSM49BAMCA0gAMEUCIAsT
++CdriQ451QTzoudLSc5yITnlStq5DH5O5AqYDSijAiEAwiV+2jn2WsWjnoFDcrNm
+zQQxmsZf1EofwSpxmH9t3Ks=
+-----END CERTIFICATE-----

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

@@ -0,0 +1,42 @@
+import { describe, expect, it } from 'vitest';
+import vectors from '../../../../../../packages/sss-key-manager/src/__fixtures__/escrow-vectors.json';
+import { escrowBlobIdentity } from './blobIdentity';
+
+const P256_P = BigInt('0xffffffff00000001000000000000000000000000ffffffffffffffffffffffff');
+
+const negatePoint = (base64: string): string => {
+    const point = Buffer.from(base64, 'base64');
+    const y = BigInt(`0x${point.subarray(33).toString('hex')}`);
+    const negated = Buffer.from((P256_P - y).toString(16).padStart(64, '0'), 'hex');
+    return Buffer.concat([point.subarray(0, 33), negated]).toString('base64');
+};
+
+describe('escrowBlobIdentity', () => {
+    const [first] = vectors.blobs;
+    if (!first) throw new Error('escrow-vectors.json has no blobs');
+    const { envelope } = first;
+
+    it('matches the enclave golden vector', () => {
+        expect(escrowBlobIdentity(envelope)).toBe(
+            '8090217ef11060bfa380c4a4b26d76a64811216176ecb60749652fabf3b09425'
+        );
+    });
+
+    it('is unchanged when the ephemeral point is negated', () => {
+        const twin = { ...envelope, ephemeralPublicKey: negatePoint(envelope.ephemeralPublicKey) };
+        expect(twin.ephemeralPublicKey).not.toBe(envelope.ephemeralPublicKey);
+        expect(escrowBlobIdentity(twin)).toBe(escrowBlobIdentity(envelope));
+    });
+
+    it('changes when the ciphertext changes', () => {
+        const ciphertext = Buffer.from(envelope.ciphertext, 'base64');
+        ciphertext.writeUInt8(ciphertext.readUInt8(0) ^ 1, 0);
+        expect(
+            escrowBlobIdentity({ ...envelope, ciphertext: ciphertext.toString('base64') })
+        ).not.toBe(escrowBlobIdentity(envelope));
+    });
+
+    it('rejects malformed envelopes', () => {
+        expect(() => escrowBlobIdentity({ ...envelope, ephemeralPublicKey: 'BA==' })).toThrow();
+    });
+});

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

@@ -0,0 +1,55 @@
+import { createHash } from 'crypto';
+
+export interface EscrowEnvelopeFields {
+    version: number;
+    algorithm: string;
+    keyId: string;
+    ephemeralPublicKey: string;
+    salt: string;
+    iv: string;
+    ciphertext: string;
+}
+
+const DOMAIN = Buffer.from('learncard-escrow-blob-id-v1\0', 'utf8');
+
+const lengthPrefixed = (field: Buffer): Buffer => {
+    const length = Buffer.alloc(8);
+    length.writeBigUInt64BE(BigInt(field.length));
+    return Buffer.concat([length, field]);
+};
+
+/**
+ * Mirrors `escrow_blob_identity` in services/escrow-enclave-app/src/crypto.rs.
+ *
+ * ECDH uses only the x-coordinate, so an envelope and its negated-point twin
+ * decrypt identically. Hashing decoded bytes with only the point's x-coordinate
+ * gives both the same identity, and neutralises base64/JSON serialization aliases.
+ */
+export const escrowBlobIdentity = (envelope: EscrowEnvelopeFields): string => {
+    const point = Buffer.from(envelope.ephemeralPublicKey, 'base64');
+    const salt = Buffer.from(envelope.salt, 'base64');
+    const iv = Buffer.from(envelope.iv, 'base64');
+    const ciphertext = Buffer.from(envelope.ciphertext, 'base64');
+    if (
+        envelope.version !== 1 ||
+        point.length !== 65 ||
+        point[0] !== 4 ||
+        salt.length !== 32 ||
+        iv.length !== 12 ||
+        ciphertext.length < 16
+    )
+        throw new Error('Invalid escrow payload');
+
+    const hash = createHash('sha256').update(DOMAIN);
+    for (const field of [
+        Buffer.from([1]),
+        Buffer.from(envelope.algorithm, 'utf8'),
+        Buffer.from(envelope.keyId, 'utf8'),
+        point.subarray(1, 33),
+        salt,
+        iv,
+        ciphertext,
+    ])
+        hash.update(lengthPrefixed(field));
+    return hash.digest('hex');
+};

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

@@ -0,0 +1,59 @@
+import * as Sentry from '@sentry/serverless';
+import {
+    confirmEscrowEnclaveCancellation,
+    recordEscrowEnclaveCancelAttempt,
+    ESCROW_HOLD_REMINDER_WINDOW_MS,
+    type EscrowHold,
+    type MongoUserKeyType,
+} from '@models';
+import { getEscrowEnclave } from './index';
+import { escrowBlobIdentity } from './blobIdentity';
+
+/** No provider identities, ciphertexts, tokens or transport error details in logs. */
+export const logEscrowCancellationPending = (urgent: boolean): void => {
+    const message = urgent
+        ? 'Escrow enclave cancellation unconfirmed within 24h of release or overdue'
+        : 'Escrow enclave cancellation pending retry';
+    if (urgent) console.error('[escrow-cancellation]', message);
+    else console.warn('[escrow-cancellation]', message);
+    try {
+        Sentry.captureMessage(message, urgent ? 'error' : 'warning');
+    } catch {
+        console.error('[escrow-cancellation] cancellation alert delivery failed');
+    }
+};
+
+/** Mongo cancellation is authoritative for the API; only a positive enclave reply confirms revocation. */
+export const cancelHoldInEnclave = async (
+    hold: EscrowHold,
+    userKey?: MongoUserKeyType | null,
+    now = new Date()
+): Promise<boolean> => {
+    try {
+        if (!(await recordEscrowEnclaveCancelAttempt(hold._id))) return true;
+        const envelope = hold.enclaveEnvelope ?? userKey?.escrowBlob?.envelope;
+        // Never cancel using a replacement enrollment or fabricate a legacy signed record.
+        if (
+            !hold.holdRecord ||
+            !envelope ||
+            escrowBlobIdentity(envelope) !== hold.holdRecord.hold.blobHash
+        ) {
+            throw new Error('Cancellation material unavailable');
+        }
+        await getEscrowEnclave().cancelHold({
+            envelope,
+            hold: hold.holdRecord,
+            clientEphemeralPublicKey: hold.clientEphemeralPublicKey,
+            expectedDid: hold.primaryDid,
+        });
+        await confirmEscrowEnclaveCancellation(hold._id);
+        return true;
+    } catch {
+        // Policy/unknown/terminal errors are ambiguous, not proof of cancellation.
+        // Includes lost success replies and BLOCKER-ENROLLMENT's Unavailable.
+        logEscrowCancellationPending(
+            hold.releaseAfter.getTime() <= now.getTime() + ESCROW_HOLD_REMINDER_WINDOW_MS
+        );
+        return false;
+    }
+};

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

@@ -0,0 +1,34 @@
+/**
+ * Private CAs for enclave-host TLS, pinned per hostname. When a CA is pinned
+ * the remote-enclave transport trusts ONLY that CA (not the system roots), and
+ * nothing else in lca-api trusts it. Changing a trust anchor is a reviewed
+ * code change, never an environment edit.
+ *
+ * Each CA is name-constrained to its single hostname; see
+ * services/escrow-enclave-app/STAGING.md section 4a.
+ */
+const ENCLAVE_TRUST_ANCHORS: Readonly<Record<string, string>> = {
+    // Staging CA, valid until 2029-09-30. SHA-256 1BB676B1B969A916497AB7386A81AEBD
+    // 903469ED4B124685F43513B5FCB9E010; source: SSM
+    // /learncard/escrow-enclave/staging/ca-cert in account 217358003896.
+    'escrow-enclave.staging.internal': `-----BEGIN CERTIFICATE-----
+MIICgTCCAgigAwIBAgIUe/8u9Uy/Y9jD4Aw+cZCIeU/yap0wCgYIKoZIzj0EAwMw
+VDEkMCIGA1UECgwbTGVhcm5pbmcgRWNvbm9teSBGb3VuZGF0aW9uMSwwKgYDVQQD
+DCNMZWFybkNhcmQgRXNjcm93IEVuY2xhdmUgU3RhZ2luZyBDQTAeFw0yNjEwMDEy
+MTI1MDJaFw0yOTA5MzAyMTI1MDJaMFQxJDAiBgNVBAoMG0xlYXJuaW5nIEVjb25v
+bXkgRm91bmRhdGlvbjEsMCoGA1UEAwwjTGVhcm5DYXJkIEVzY3JvdyBFbmNsYXZl
+IFN0YWdpbmcgQ0EwdjAQBgcqhkjOPQIBBgUrgQQAIgNiAARSwi8GmnzoqYadKw9n
+gc7kOMMbimXjF5weA8YCOBhiaNHAxRcYJ0iz1nv74wYt/8x9lvwkFP4IK36i+bdH
+fiu6Oo34LXi3AHBbQvL5A2c2IELil6Cea+ClWtJLfWDu7OOjgZowgZcwHwYDVR0j
+BBgwFoAUybGIxOfLHqqbjDFJ1k28v4aKh4IwEgYDVR0TAQH/BAgwBgEB/wIBADAO
+BgNVHQ8BAf8EBAMCAQYwMQYDVR0eAQH/BCcwJaAjMCGCH2VzY3Jvdy1lbmNsYXZl
+LnN0YWdpbmcuaW50ZXJuYWwwHQYDVR0OBBYEFMmxiMTnyx6qm4wxSdZNvL+GioeC
+MAoGCCqGSM49BAMDA2cAMGQCMGp/wTQLmtB6/GK6hMFaFTA27gXZcxrgJ0Uy+8C0
+Ztl5uoRwN99inHNWv1cnKGdNQgIwSoQgKs8uMnBUcfiB9ZR6xb98z/9athp5pDIE
+/KUv6cNmJtuCgPOJxC+4fVKl8xC3
+-----END CERTIFICATE-----
+`,
+};
+
+export const pinnedEnclaveCa = (baseUrl: string): string | undefined =>
+    ENCLAVE_TRUST_ANCHORS[new URL(baseUrl).hostname];

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

@@ -4,28 +4,155 @@ import {
     parseEscrowPrivateKeys,
     type LcaApiEnvironment,
 } from '@environment';
+import type { EscrowBlobStaleReason } from '@learncard/types';
 import { SoftwareEnclave } from './softwareEnclave';
+import { createRemoteEnclave } from './remoteEnclave';
+import { pinnedEnclaveCa } from './enclaveTrustAnchors';
 import { EscrowUnavailableError, type EscrowEnclave } from './types';
 
 export * from './types';
 export * from './softwareEnclave';
+export * from './remoteEnclave';
 export * from './notifications';
 
 let enclave: EscrowEnclave | undefined;
 let config: LcaApiEnvironment = environment;
 
-export const isEscrowEnabled = (): boolean => Boolean(config.ESCROW_ENCLAVE_MODE);
+// 'software' config validity is enforced at environment-parse time (see
+// config/environment.ts), so reaching that branch always means it's ready.
+// 'remote' config (URL/token) is deliberately NOT required at parse time, so
+// its readiness is checked here instead; missing it fails this closed rather
+// than crashing the whole service at boot.
+export const isEscrowEnabled = (): boolean => {
+    if (config.ESCROW_ENCLAVE_MODE === 'software') {
+        // Serverless injects the actual deploy stage; NODE_ENV often remains development
+        // in Lambda. Unknown deployed stages fail closed, regardless of offline flags.
+        const allowed = config.LAMBDA_STAGE
+            ? ['dev', 'development', 'staging', 'test', 'local'].includes(config.LAMBDA_STAGE)
+            : config.NODE_ENV !== 'production';
+        if (!allowed) console.error('[escrow] Software enclave disabled for this deploy stage');
+        return allowed;
+    }
+    if (config.ESCROW_ENCLAVE_MODE === 'remote') {
+        return Boolean(config.ESCROW_ENCLAVE_REMOTE_URL && config.ESCROW_ENCLAVE_REMOTE_TOKEN);
+    }
+    return false;
+};
+export const isEscrowRemoteMode = (): boolean => config.ESCROW_ENCLAVE_MODE === 'remote';
+// The client-facing attestation mode implied by the server's active backend
+// ('remote' mode always attests as 'nitro' — see remoteEnclave.ts).
+export const activeEscrowClientMode = (): 'software' | 'nitro' =>
+    isEscrowRemoteMode() ? 'nitro' : 'software';
 export const getEscrowHoldDurationMs = (): number => config.ESCROW_HOLD_DURATION_MS;
 export const getEscrowHoldRestartMinAgeMs = (): number => config.ESCROW_HOLD_RESTART_MIN_AGE_MS;
 export const getEscrowEnclave = (): EscrowEnclave => {
     if (!isEscrowEnabled()) throw new EscrowUnavailableError();
     if (enclave) return enclave;
-    if (config.ESCROW_ENCLAVE_MODE !== 'software') throw new EscrowUnavailableError();
-    enclave = new SoftwareEnclave({
-        privateKeys: parseEscrowPrivateKeys(config.ESCROW_ENCLAVE_SOFTWARE_PRIVATE_KEYS_JSON ?? ''),
-        activeKeyId: config.ESCROW_ENCLAVE_ACTIVE_KEY_ID ?? '',
-    });
-    return enclave;
+    if (config.ESCROW_ENCLAVE_MODE === 'software') {
+        enclave = new SoftwareEnclave({
+            privateKeys: parseEscrowPrivateKeys(
+                config.ESCROW_ENCLAVE_SOFTWARE_PRIVATE_KEYS_JSON ?? ''
+            ),
+            activeKeyId: config.ESCROW_ENCLAVE_ACTIVE_KEY_ID ?? '',
+            holdDurationMs: getEscrowHoldDurationMs(),
+        });
+        return enclave;
+    }
+    if (config.ESCROW_ENCLAVE_MODE === 'remote') {
+        const { ESCROW_ENCLAVE_REMOTE_URL: baseUrl, ESCROW_ENCLAVE_REMOTE_TOKEN: token } = config;
+        if (!baseUrl || !token) throw new EscrowUnavailableError();
+        enclave = createRemoteEnclave({
+            baseUrl,
+            token,
+            timeoutMs: config.ESCROW_ENCLAVE_REMOTE_TIMEOUT_MS,
+            caPem: pinnedEnclaveCa(baseUrl),
+        });
+        return enclave;
+    }
+    throw new EscrowUnavailableError();
+};
+
+export type { EscrowBlobStaleReason };
+
+interface EscrowAttestationIdentity {
+    keyId: string;
+    /** P9.1: retired keyIds the enclave still accepts for decrypt only. */
+    previousKeyIds: string[];
+    mode: 'software' | 'nitro';
+}
+interface EscrowAttestationCacheEntry extends EscrowAttestationIdentity {
+    fetchedAt: number;
+}
+
+// Keeps every login's status check off the enclave's critical path (a remote
+// nitro backend can be slow or briefly unreachable; a normal sign-in must
+// never wait on it). TTL and budget are process-local constants, not env
+// config, since neither is an operator-facing tuning knob.
+const ESCROW_ATTESTATION_CACHE_TTL_MS = 5 * 60 * 1000;
+const ESCROW_ATTESTATION_STATUS_BUDGET_MS = 250;
+
+let attestationCache: EscrowAttestationCacheEntry | undefined;
+let attestationRefreshInFlight: Promise<EscrowAttestationIdentity> | undefined;
+
+const isAttestationCacheFresh = (): boolean =>
+    !!attestationCache && Date.now() - attestationCache.fetchedAt < ESCROW_ATTESTATION_CACHE_TTL_MS;
+
+// Single-flight: any number of concurrent cold-cache callers (status checks
+// and release-enforcement checks alike) share one underlying getAttestation()
+// call and its outcome, so a cache-expiry moment never causes a call fan-out
+// to the enclave. Clears the in-flight marker on settle either way so the
+// next cold call starts a fresh fetch; only a successful fetch warms the cache.
+const refreshAttestationCache = (): Promise<EscrowAttestationIdentity> => {
+    attestationRefreshInFlight ??= (async () => {
+        try {
+            const attestation = await getEscrowEnclave().getAttestation();
+            const identity: EscrowAttestationIdentity = {
+                keyId: attestation.keyId,
+                previousKeyIds: attestation.previousKeyIds ?? [],
+                mode: attestation.mode,
+            };
+            attestationCache = { ...identity, fetchedAt: Date.now() };
+            return identity;
+        } finally {
+            attestationRefreshInFlight = undefined;
+        }
+    })();
+    return attestationRefreshInFlight;
+};
+
+/**
+ * Fail-closed identity lookup for release enforcement (startRecovery /
+ * completeRecovery): resolves instantly from a warm cache, otherwise awaits a
+ * real getAttestation() call (subject to the enclave's own normal timeout,
+ * e.g. `ESCROW_ENCLAVE_REMOTE_TIMEOUT_MS`) and lets a failure propagate — a
+ * caller here must never treat an unreachable enclave as "fresh".
+ */
+export const getEnclaveAttestationIdentity = (): Promise<EscrowAttestationIdentity> =>
+    isAttestationCacheFresh() ? Promise.resolve(attestationCache!) : refreshAttestationCache();
+
+// Best-effort status check (used for the client's read-only enrollment state
+// on every sign-in — see routes/keys.ts's getAuthShare — not for release
+// enforcement; see getEnclaveAttestationIdentity above for the fail-closed
+// version). Never awaits the enclave directly: a cold/failed cache still
+// returns "not stale" within ESCROW_ATTESTATION_STATUS_BUDGET_MS, while a
+// background refresh (already in flight, or started here) continues so a
+// later call can see a warm cache.
+export const getEscrowBlobStaleReason = async (blob: {
+    enclaveMode: 'software' | 'nitro';
+    enclaveKeyId: string;
+}): Promise<EscrowBlobStaleReason | undefined> => {
+    if (!isEscrowEnabled()) return undefined;
+    if (blob.enclaveMode !== activeEscrowClientMode()) return 'mode-mismatch';
+    if (isAttestationCacheFresh()) {
+        return blob.enclaveKeyId !== attestationCache!.keyId ? 'key-rotated' : undefined;
+    }
+    const identity = await Promise.race([
+        refreshAttestationCache().catch(() => undefined),
+        new Promise<undefined>(resolve => {
+            setTimeout(() => resolve(undefined), ESCROW_ATTESTATION_STATUS_BUDGET_MS);
+        }),
+    ]);
+    return identity && blob.enclaveKeyId !== identity.keyId ? 'key-rotated' : undefined;
 };
 
 /** Reset both singleton and environment snapshot after test environment changes. */
@@ -33,4 +160,15 @@ export const __setEscrowEnclaveForTests = (replacement: EscrowEnclave | undefine
     if (environment.NODE_ENV !== 'test') throw new EscrowUnavailableError();
     config = parseLcaApiEnvironment(process.env);
     enclave = replacement;
+    attestationCache = undefined;
+    attestationRefreshInFlight = undefined;
+};
+
+/** Invalidate the attestation cache without replacing the enclave singleton
+ * (e.g. to force the next freshness check to re-fetch against the same
+ * enclave, or to isolate tests from each other's cached state). */
+export const __resetEscrowAttestationCacheForTests = (): void => {
+    if (environment.NODE_ENV !== 'test') throw new EscrowUnavailableError();
+    attestationCache = undefined;
+    attestationRefreshInFlight = undefined;
 };