@learncard/lca-api-service 1.3.2 → 1.5.0

package/src/routes/qr-login.ts

@@ -20,8 +20,9 @@ import crypto from 'crypto';
 
 import { t, openRoute } from '@routes';
 import cache from '@cache';
-import { verifyAuthToken, getContactMethodFromUser, AuthProviderType } from '@helpers/auth.helpers';
-import { findUserKeyByContactMethod } from '@models';
+import { verifyAuthToken, AuthProviderType } from '@helpers/auth.helpers';
+import { findUserKeyByAuthProvider } from '@models';
+import { checkRateLimit } from '@helpers/rateLimit.helpers';
 import { sendPushNotification } from '@helpers/pushNotifications.helpers';
 
 // ---------------------------------------------------------------------------
@@ -40,47 +41,18 @@ const CODE_PREFIX = 'qr-login:code:';
 const RATE_PREFIX = 'qr-login:rate:';
 
 /** Rate limiting */
-const CREATE_RATE_LIMIT = 10;       // max session creations per window
-const CREATE_RATE_WINDOW = 600;     // 10-minute window (seconds)
-const LOOKUP_RATE_LIMIT = 20;       // max lookups per window
-const LOOKUP_RATE_WINDOW = 60;      // 1-minute window (seconds)
-const APPROVE_RATE_LIMIT = 5;       // max approve attempts per session
-const NOTIFY_RATE_LIMIT = 3;        // max notify calls per window
-const NOTIFY_RATE_WINDOW = 300;     // 5-minute window (seconds)
+const CREATE_RATE_LIMIT = 10; // max session creations per window
+const CREATE_RATE_WINDOW = 600; // 10-minute window (seconds)
+const LOOKUP_RATE_LIMIT = 20; // max lookups per window
+const LOOKUP_RATE_WINDOW = 60; // 1-minute window (seconds)
+const APPROVE_RATE_LIMIT = 5; // max approve attempts per session
+const NOTIFY_RATE_LIMIT = 3; // max notify calls per window
+const NOTIFY_RATE_WINDOW = 300; // 5-minute window (seconds)
 
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
 
-/**
- * Check and increment a rate-limit counter in Redis.
- * Returns true if the request is allowed, false if rate-limited.
- *
- * Uses atomic INCR + EXPIRE to avoid TOCTOU races where two concurrent
- * requests could both read the same counter value and both pass.
- */
-const checkRateLimit = async (
-    key: string,
-    maxAttempts: number,
-    windowSeconds: number
-): Promise<boolean> => {
-    const fullKey = `${RATE_PREFIX}${key}`;
-    const redis = cache.redis ?? cache.node;
-
-    // INCR is atomic — returns the new value after incrementing.
-    // If the key doesn't exist, Redis creates it with value 1.
-    const current = await redis.incr(fullKey);
-
-    // First request for this window — set the TTL
-    if (current === 1) {
-        await redis.expire(fullKey, windowSeconds);
-    }
-
-    if (current > maxAttempts) return false;
-
-    return true;
-};
-
 const generateSessionId = (): string => crypto.randomUUID();
 
 const generateShortCode = (): string => {
@@ -149,7 +121,14 @@ export const qrLoginRouter = t.router({
             // Rate limit by IP — max 10 sessions per 10 minutes
             const clientIp = ctx.clientIp ?? 'unknown';
 
-            if (!(await checkRateLimit(`create:${clientIp}`, CREATE_RATE_LIMIT, CREATE_RATE_WINDOW))) {
+            if (
+                !(await checkRateLimit(
+                    `create:${clientIp}`,
+                    CREATE_RATE_LIMIT,
+                    CREATE_RATE_WINDOW,
+                    RATE_PREFIX
+                ))
+            ) {
                 throw new Error('Too many session requests. Please try again later.');
             }
 
@@ -215,7 +194,14 @@ export const qrLoginRouter = t.router({
             if (/^\d{8}$/.test(input.lookup)) {
                 const clientIp = ctx.clientIp ?? 'unknown';
 
-                if (!(await checkRateLimit(`lookup:${clientIp}`, LOOKUP_RATE_LIMIT, LOOKUP_RATE_WINDOW))) {
+                if (
+                    !(await checkRateLimit(
+                        `lookup:${clientIp}`,
+                        LOOKUP_RATE_LIMIT,
+                        LOOKUP_RATE_WINDOW,
+                        RATE_PREFIX
+                    ))
+                ) {
                     throw new Error('Too many lookup attempts. Please try again later.');
                 }
             }
@@ -281,7 +267,14 @@ export const qrLoginRouter = t.router({
         .output(z.object({ success: z.boolean() }))
         .mutation(async ({ input, ctx: _ctx }) => {
             // Rate limit approve attempts per session to prevent brute-force
-            if (!(await checkRateLimit(`approve:${input.sessionId}`, APPROVE_RATE_LIMIT, SESSION_TTL_SECONDS))) {
+            if (
+                !(await checkRateLimit(
+                    `approve:${input.sessionId}`,
+                    APPROVE_RATE_LIMIT,
+                    SESSION_TTL_SECONDS,
+                    RATE_PREFIX
+                ))
+            ) {
                 throw new Error('Too many approve attempts for this session.');
             }
 
@@ -326,7 +319,7 @@ export const qrLoginRouter = t.router({
                 method: 'POST',
                 path: '/qr-login/notify',
                 tags: ['QR Login'],
-                summary: 'Send a device link push notification to the user\'s other devices',
+                summary: "Send a device link push notification to the user's other devices",
             },
         })
         .input(
@@ -347,21 +340,26 @@ export const qrLoginRouter = t.router({
         .output(z.object({ sent: z.boolean(), deviceCount: z.number() }))
         .mutation(async ({ input, ctx: _ctx }) => {
             // Rate limit notify calls per session
-            if (!(await checkRateLimit(`notify:${input.sessionId}`, NOTIFY_RATE_LIMIT, NOTIFY_RATE_WINDOW))) {
+            if (
+                !(await checkRateLimit(
+                    `notify:${input.sessionId}`,
+                    NOTIFY_RATE_LIMIT,
+                    NOTIFY_RATE_WINDOW,
+                    RATE_PREFIX
+                ))
+            ) {
                 return { sent: false, deviceCount: 0 };
             }
 
             // Verify the auth token and get the user
-            const user = await verifyAuthToken(input.authToken, input.providerType as AuthProviderType);
-
-            const contactMethod = getContactMethodFromUser(user);
-
-            if (!contactMethod) {
-                throw new Error('User must have an email or phone number');
-            }
-
-            // Look up the user's DID from their key record
-            const userKey = await findUserKeyByContactMethod(contactMethod);
+            const user = await verifyAuthToken(
+                input.authToken,
+                input.providerType as AuthProviderType
+            );
+
+            // Provider identity is immutable; a recycled contact method must
+            // never receive notifications for a previous owner's DID.
+            const userKey = await findUserKeyByAuthProvider(input.providerType, user.id);
 
             if (!userKey?.primaryDid) {
                 return { sent: false, deviceCount: 0 };

package/src/routes/signing-authority.ts

@@ -8,7 +8,7 @@ import {
     getSigningAuthorityForDid,
 } from '@accesslayer/signing-authority/read';
 
-import { t, didAndChallengeRoute } from '@routes';
+import { t, didAndChallengeRoute, authorizedDidRoute } from '@routes';
 
 import { SigningAuthorityResponseValidator } from '@models';
 import type { MongoSigningAuthorityType } from '@models';
@@ -62,6 +62,44 @@ export const signingAuthorityRouter = t.router({
                 });
             }
 
+            return getSigningAuthorityWithEndpoint(
+                { ...signingAuthority, did: signingAuthority.did },
+                ctx.domain
+            );
+        }),
+    ensureManagedSigningAuthority: authorizedDidRoute
+        .meta({
+            openapi: {
+                protect: true,
+                method: 'POST',
+                path: '/signing-authority/managed',
+                tags: ['Signing Authority'],
+                summary: 'Get or create a managed Signing Authority',
+                description:
+                    'Trusted-service route that returns the named signing authority for ownerDid, creating it if needed',
+            },
+        })
+        .input(z.object({ name: z.string().min(1), ownerDid: z.string().min(1) }))
+        .output(SigningAuthorityResponseValidator)
+        .mutation(async ({ input, ctx }) => {
+            const { name, ownerDid } = input;
+
+            // A concurrent caller can win the unique (ownerDid, name) insert, so re-read on failure.
+            const signingAuthority =
+                (await getSigningAuthorityForDid(ownerDid, name)) ??
+                (await createSigningAuthorityForDID(ownerDid, name).then(createdId =>
+                    createdId
+                        ? getSigningAuthorityById(createdId)
+                        : getSigningAuthorityForDid(ownerDid, name)
+                ));
+
+            if (!signingAuthority?.did) {
+                throw new TRPCError({
+                    code: 'INTERNAL_SERVER_ERROR',
+                    message: 'Managed Signing Authority could not be created.',
+                });
+            }
+
             return getSigningAuthorityWithEndpoint(
                 { ...signingAuthority, did: signingAuthority.did },
                 ctx.domain

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';
 
@@ -34,6 +38,12 @@ const LOCAL_TEMPLATE_ALIASES: Record<string, TemplateId> = {
     'guardian-approval': 'guardian-approval',
     '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). */
@@ -166,9 +176,13 @@ export class PostmarkAdapter implements DeliveryService {
                     recipient: model.recipient as { name?: string } | undefined,
                 };
 
+            case 'account-sign-in-changed':
+                return {};
+
             case 'recovery-key':
                 return {
                     recoveryKey: (model.recoveryKey as string) ?? '',
+                    confirmationCode: (model.confirmationCode as string) ?? '',
                 };
 
             case 'endorsement-request':
@@ -201,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

@@ -0,0 +1,122 @@
+# Escrow release policies
+
+The same sealed recovery material supports a delayed `hold` policy and an optional
+immediate `pin` policy. PIN verification and release are a single enclave operation;
+a PIN hold cannot release without a matching proof, even after its release time.
+The verifier is never stored in plaintext in MongoDB, logged, or included in the
+release payload. A leaked database alone does not expose an offline PIN oracle.
+
+## Software-mode trust boundary
+
+The software enclave runs in the host process: the host already controls its keys,
+clock, and execution. A host-owned MongoDB attempt counter does not weaken that
+existing host-trusted model, but does not protect against a malicious host either.
+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).
+
+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
+
+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,
+    sourceEnrollmentEpoch, targetEnrollmentEpoch }): Promise<{ envelope }>
+```
+
+Decrypt both envelopes inside the enclave. Require both DIDs to equal `expectedDid`,
+both versions to match their expected versions, a strictly increasing target version,
+a source PIN verifier, and no target verifier. Reject mismatches with `EscrowBlobError`
+(`Invalid escrow payload.`). Seal target plaintext plus the source verifier to the
+current enclave key with fresh ephemeral key and IV, using the existing envelope
+format. Never return or log plaintext or the verifier.
+
+Enrollment attempts carry only for PIN-less requests with an unlocked PIN matching
+the previous blob's version and current enclave key. Persistence compares the complete
+old `escrowBlob` and `escrowPin` subdocuments, auth-provider identity, current share
+version, and absent opt-out marker atomically. This guards salt, counters, lock state,
+and ciphertext against concurrent changes. Carry preserves salt, enabledAt and both
+attempt counters, changing only the PIN share version. Unavailable/failed carry or a
+lost compare-and-swap falls back to normal PIN-less enrollment with a secret-free warning.
+Explicit new PIN enrollment is unchanged; explicit removal sends `clearPin: true`
+to bypass carry (it cannot be combined with `pinSalt`).
+
+`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;
+    }
+};