@learncard/lca-api-service 1.5.1 → 1.5.2

package/src/jobs/escrowBlobRewrap.ts

@@ -7,7 +7,10 @@ import {
     getEnclaveAttestationIdentity,
     getEscrowEnclave,
     isEscrowEnabled,
+    isEscrowRemoteMode,
 } from '../services/escrow-enclave';
+import { randomBytes } from 'crypto';
+import { EscrowUnavailableError } from '../services/escrow-enclave/types';
 
 const DEFAULT_REWRAP_BATCH_LIMIT = 200;
 
@@ -90,7 +93,46 @@ export const runEscrowBlobRewrap = async (
                 skippedPendingHold += 1;
                 continue;
             }
-            const { envelope } = await getEscrowEnclave().rewrapEscrowBlob({
+            const enclave = getEscrowEnclave();
+            if (isEscrowRemoteMode()) {
+                if (!enclave.getEnrollmentState || !blob.authorityGeneration)
+                    throw new EscrowUnavailableError();
+                const snapshot = await enclave.getEnrollmentState({
+                    expectedDid: userKey.primaryDid,
+                    nonce: randomBytes(32).toString('hex'),
+                });
+                const current = snapshot.state;
+                if (
+                    current.status !== 'active' ||
+                    !current.envelope ||
+                    current.authorityGeneration !== blob.authorityGeneration ||
+                    current.did !== userKey.primaryDid ||
+                    current.shareVersion !== blob.shareVersion ||
+                    current.enrollmentEpoch !== blob.enrollmentEpoch
+                )
+                    throw new EscrowUnavailableError();
+                if (current.envelope.keyId === attestation.keyId) {
+                    const stored = await rewrapEscrowBlobByAuthProvider(
+                        authProvider,
+                        blob,
+                        userKey.escrowPin,
+                        current.envelope,
+                        {
+                            enclaveKeyId: attestation.keyId,
+                            enclaveMode: attestation.mode,
+                            measurements: attestation.measurements,
+                        },
+                        {
+                            authorityGeneration: current.authorityGeneration,
+                            enrollmentVersion: current.enrollmentVersion,
+                            stateProof: snapshot.proof,
+                        }
+                    );
+                    if (stored) rewrapped += 1;
+                    continue;
+                }
+            }
+            const { envelope, authority } = await enclave.rewrapEscrowBlob({
                 envelope: blob.envelope,
                 expectedDid: userKey.primaryDid,
                 expectedShareVersion: blob.shareVersion,
@@ -105,7 +147,8 @@ export const runEscrowBlobRewrap = async (
                     enclaveKeyId: attestation.keyId,
                     enclaveMode: attestation.mode,
                     measurements: attestation.measurements,
-                }
+                },
+                authority
             );
             if (stored) rewrapped += 1;
             // else: lost the compare-and-swap race (a concurrent re-enroll,

package/src/jobs/escrowHoldReminders.ts

@@ -9,13 +9,19 @@ import {
     findEscrowHoldsPendingStartNotification,
     releaseEscrowReminderClaim,
     recordEscrowStartNotificationAttempt,
+    recordEscrowHoldNotification,
+    computeEffectiveReleaseAfter,
 } from '@models';
 import { environment } from '@environment';
 import {
     cancelHoldInEnclave,
     logEscrowCancellationPending,
 } from '../services/escrow-enclave/cancellation';
-import { isEscrowEnabled, notifyEscrowHoldEvent } from '../services/escrow-enclave';
+import {
+    getEscrowEnclave,
+    isEscrowEnabled,
+    notifyEscrowHoldEvent,
+} from '../services/escrow-enclave';
 
 // Two queues of ten 3-second deliveries leave half the 120-second Lambda
 // budget for database work. Least-recently-attempted ordering prevents starvation.
@@ -148,6 +154,11 @@ export const runEscrowHoldReminders = async (
         }
     }
 
+    // P9.1 (attack C): `sendReleaseWarning` is defined only by the remote
+    // (nitro/authority) backend — software mode never produces a hold the
+    // enclave itself must warn about, since it has no confirmation step to
+    // have gated release behind in the first place.
+    const sendReleaseWarning = getEscrowEnclave().sendReleaseWarning;
     for (const candidate of candidates) {
         let claimed: Awaited<ReturnType<typeof claimEscrowHoldForReminder>> = null;
         try {
@@ -155,6 +166,44 @@ export const runEscrowHoldReminders = async (
             claimed = await claimEscrowHoldForReminder(candidate._id, now);
             if (!claimed) continue;
 
+            // P9.1 (attack C): an authority-mode Hold-policy hold's security
+            // channel is the enclave's own sealed-blob-sourced email, not this
+            // Mongo-recipient-sourced one, which an attacker who controls the
+            // suppressed-notification side of the threat model could silence
+            // or redirect. send-release-warning both notifies the real owner
+            // and records the timestamp release is independently gated on.
+            if (sendReleaseWarning && claimed.releasePolicy !== 'pin' && claimed.holdRecord) {
+                const { releaseWarningSentAtMs } = await sendReleaseWarning({
+                    holdId: claimed.holdRecord.hold.holdId,
+                    expectedDid: claimed.primaryDid,
+                });
+                // P2-a: the enclave call above is idempotent (a repeat never
+                // resends or moves its recorded timestamp), so persisting
+                // this acknowledgment AFTER it succeeds is safe to retry: if
+                // this write is lost (crash, Mongo failure), the hold stays
+                // selected next run, the enclave call is a no-op, and this
+                // write finally lands. Without it, every run re-called the
+                // enclave for every hold in the 24h window forever.
+                // [B]: also persist the effective availability from the
+                // authoritative confirmation/warning times — a late
+                // (catch-up) warning can push real availability later than
+                // the hold's existing stored `releaseAfter` estimate, which
+                // otherwise keeps advertising an already-passed deadline.
+                await recordEscrowHoldNotification(
+                    claimed._id,
+                    'reminder',
+                    claimed.confirmedAt
+                        ? computeEffectiveReleaseAfter({
+                              confirmedAtMs: claimed.confirmedAt.getTime(),
+                              holdDurationMs: claimed.holdRecord.holdDurationMs,
+                              releaseWarningSentAtMs,
+                          })
+                        : undefined
+                );
+                reminded += 1;
+                continue;
+            }
+
             const userKey = await findUserKeyByAuthProvider(
                 claimed.authProvider.type,
                 claimed.authProvider.id

package/src/models/EscrowHold.ts

@@ -1,5 +1,9 @@
 import { createHash, createHmac, randomBytes } from 'crypto';
 import { z } from 'zod';
+import {
+    AuthorityCommitValidator,
+    type AuthorityRecord,
+} from '../services/escrow-enclave/authorityContract';
 import type { Collection } from 'mongodb';
 import mongodb from '@mongo';
 import { environment } from '@environment';
@@ -13,6 +17,40 @@ export const ESCROW_HOLDS_COLLECTION = 'escrowholds';
 export const ESCROW_HOLD_STALE_WINDOW_MS = 30 * 24 * 60 * 60 * 1000;
 export const ESCROW_HOLD_RESTART_MIN_AGE_MS = environment.ESCROW_HOLD_RESTART_MIN_AGE_MS;
 export const ESCROW_HOLD_REMINDER_WINDOW_MS = 24 * 60 * 60 * 1000;
+// Roughtime's release lower bound can lag its creation/confirmation upper
+// bound (see escrow-enclave-app's D2); advertise an additional minute on top
+// of both enclave release gates below, and still allow retries when trusted
+// time is briefly unavailable.
+export const ESCROW_RELEASE_TIME_MARGIN_MS = 60_000;
+// Mirrors `RELEASE_WARNING_MIN_GAP_MS` in policy/authority.rs.
+export const ESCROW_RELEASE_WARNING_GAP_MS = 24 * 60 * 60 * 1000;
+
+/**
+ * The enclave gates release on BOTH `confirmed_hi_ms + holdDuration` AND
+ * `release_warning_sent_hi_ms + 24h` (see `authority_release_with_receipt`,
+ * policy/authority.rs ~663-671) — a hold is only actually releasable at the
+ * LATER of the two. A warning sent after the 7-day window has already
+ * elapsed (a late/catch-up send, P2-b) pushes real availability later than
+ * `releaseAfter` computed from confirmation alone; callers must recompute
+ * and persist this whenever either authoritative timestamp changes, using
+ * the enclave's own `confirmed_hi_ms`/`release_warning_sent_hi_ms` — never a
+ * locally observed `now` (see [A]/[A2]).
+ */
+export const computeEffectiveReleaseAfter = (params: {
+    confirmedAtMs: number;
+    holdDurationMs: number;
+    releaseWarningSentAtMs?: number;
+}): Date => {
+    const confirmedAvailabilityMs =
+        params.confirmedAtMs + params.holdDurationMs + ESCROW_RELEASE_TIME_MARGIN_MS;
+    const warningAvailabilityMs =
+        params.releaseWarningSentAtMs === undefined
+            ? undefined
+            : params.releaseWarningSentAtMs +
+              ESCROW_RELEASE_WARNING_GAP_MS +
+              ESCROW_RELEASE_TIME_MARGIN_MS;
+    return new Date(Math.max(confirmedAvailabilityMs, warningAvailabilityMs ?? 0));
+};
 // Opaque JSON validated for shape, not signature authenticity. Preserve signed extensions.
 export const EscrowHoldRecordValidator = z
     .object({
@@ -51,6 +89,8 @@ export const EscrowHoldValidator = z.object({
     cancelReason: z.enum(['pin-mismatch', 'pin-locked', 'superseded', 'release-failed']).optional(),
     cancelledAt: z.date().optional(),
     enclaveCancelPendingAt: z.date().optional(),
+    enclaveCancelReceipt: AuthorityCommitValidator.optional(),
+    enclaveReleaseReceipt: AuthorityCommitValidator.optional(),
     enclaveCancelConfirmedAt: z.date().optional(),
     enclaveCancelAttempts: z.number().int().nonnegative().optional(),
     // Retain ciphertext for revocation even after account removal or re-enrollment.
@@ -69,6 +109,14 @@ export const EscrowHoldValidator = z.object({
         .max(4)
         .optional(),
     startedNotificationPending: z.boolean().optional(),
+    // P9.1 (attack C): set at creation only for an authority-mode Hold-policy
+    // hold (the enclave gates its own release on a confirmed email code, not
+    // just this flag). `confirmedAt` is set once `confirmRecovery` succeeds,
+    // at which point `releaseAfter` is also recomputed from the confirmation
+    // time (not the original creation time) so Mongo's own stale-expiry and
+    // reminder-window queries stay consistent with the enclave's real gate.
+    requiresConfirmation: z.boolean().optional(),
+    confirmedAt: z.date().optional(),
     reminderClaimedUntil: z.date().optional(),
     startedNotificationAttemptedAt: z.date().optional(),
     reminderAttemptedAt: z.date().optional(),
@@ -259,7 +307,10 @@ export const recordEscrowEnclaveCancelAttempt = async (id: string): Promise<bool
     return result.modifiedCount > 0;
 };
 
-export const confirmEscrowEnclaveCancellation = async (id: string): Promise<void> => {
+export const confirmEscrowEnclaveCancellation = async (
+    id: string,
+    receipt?: AuthorityRecord
+): Promise<void> => {
     const now = new Date();
     await getEscrowHoldsCollection().updateOne(
         {
@@ -269,12 +320,28 @@ export const confirmEscrowEnclaveCancellation = async (id: string): Promise<void
             enclaveCancelConfirmedAt: { $exists: false },
         },
         {
-            $set: { enclaveCancelConfirmedAt: now, updatedAt: now },
+            $set: {
+                enclaveCancelConfirmedAt: now,
+                updatedAt: now,
+                ...(receipt
+                    ? { enclaveCancelReceipt: AuthorityCommitValidator.parse(receipt) }
+                    : {}),
+            },
             $unset: { enclaveCancelPendingAt: '', enclaveEnvelope: '' },
         }
     );
 };
 
+export const recordEscrowReleaseReceipt = async (
+    id: string,
+    receipt: AuthorityRecord
+): Promise<void> => {
+    await getEscrowHoldsCollection().updateOne(
+        { _id: id, status: 'completed' },
+        { $set: { enclaveReleaseReceipt: AuthorityCommitValidator.parse(receipt) } }
+    );
+};
+
 export const cancelEscrowHold = async (
     id: string,
     cancelledBy: 'did' | 'system',
@@ -330,6 +397,22 @@ export const cancelEscrowHoldByCancelToken = async (
         { returnDocument: 'after' }
     );
 };
+/**
+ * Records a successful confirmRecovery and corrects releaseAfter to the
+ * confirmation time (the enclave's own release gate is confirmation-based,
+ * not creation-based). Never overwrites an already-confirmed row.
+ */
+export const recordEscrowHoldConfirmation = async (
+    id: string,
+    confirmedAt: Date,
+    releaseAfter: Date
+): Promise<EscrowHold | null> =>
+    getEscrowHoldsCollection().findOneAndUpdate(
+        { _id: id, status: 'pending', confirmedAt: { $exists: false } },
+        { $set: { confirmedAt, releaseAfter, updatedAt: confirmedAt } },
+        { returnDocument: 'after' }
+    );
+
 export const completeEscrowHold = async (id: string): Promise<EscrowHold | null> => {
     const now = new Date();
     return getEscrowHoldsCollection().findOneAndUpdate(
@@ -437,7 +520,24 @@ export const recordEscrowStartNotificationAttempt = async (
  * excludes them in practice within a few ms of job execution; the explicit
  * releasePolicy filter documents that exclusion instead of relying on
  * timing alone. Legacy rows predating `releasePolicy` are treated as `hold`,
- * matching `findPendingEscrowHoldByAuthProvider`'s own `$or`.
+ * matching `findPendingEscrowHoldByAuthProvider`'s own `$or`. An
+ * authority-mode hold still awaiting its email confirmation is excluded
+ * outright: its stored `releaseAfter` is only a rough creation-time estimate
+ * until confirmation recomputes it, and the enclave's own
+ * `authority_send_release_warning` would reject a pre-confirmation hold
+ * anyway (see policy/authority.rs), so excluding it here avoids a
+ * predictable, recurring no-op failure every run.
+ *
+ * Deliberately has no `releaseAfter > now` lower bound (catch-up, P2-b): the
+ * mandatory warning gate means release can never complete without a
+ * successfully recorded warning, regardless of how stale Mongo's own
+ * `releaseAfter` estimate is. An outage (SES down, this job not running)
+ * spanning an entire 24h reminder window must not permanently strand the
+ * hold — it stays selected, however overdue, until a warning is finally
+ * recorded (`notifications.kind` gains `'reminder'`). Real availability is
+ * then governed by the enclave's own gate, `release_warning_sent_hi_ms +
+ * 24h` (see `authority_release_with_receipt` in policy/authority.rs), not
+ * by this stale estimate.
  */
 export const findEscrowHoldsDueForReminder = async (
     now: Date,
@@ -446,11 +546,21 @@ export const findEscrowHoldsDueForReminder = async (
     getEscrowHoldsCollection()
         .find({
             status: 'pending',
-            $or: [{ releasePolicy: 'hold' as const }, { releasePolicy: { $exists: false } }],
-            releaseAfter: {
-                $gt: now,
-                $lte: new Date(now.getTime() + ESCROW_HOLD_REMINDER_WINDOW_MS),
-            },
+            $and: [
+                {
+                    $or: [
+                        { releasePolicy: 'hold' as const },
+                        { releasePolicy: { $exists: false } },
+                    ],
+                },
+                {
+                    $or: [
+                        { requiresConfirmation: { $ne: true } },
+                        { confirmedAt: { $exists: true } },
+                    ],
+                },
+            ],
+            releaseAfter: { $lte: new Date(now.getTime() + ESCROW_HOLD_REMINDER_WINDOW_MS) },
             'notifications.kind': { $ne: 'reminder' },
         })
         .sort({ reminderAttemptedAt: 1, releaseAfter: 1 })
@@ -494,10 +604,17 @@ export const hashEscrowResumeToken = (token: string): string =>
     createHash('sha256').update(token).digest('hex');
 export const generateEscrowResumeToken = (): string => randomBytes(32).toString('hex');
 
-/** Appends a delivery record; a missing holdId is a no-op rather than a throw. */
+/**
+ * Appends a delivery record; a missing holdId is a no-op rather than a throw.
+ * `releaseAfter` lets a `'reminder'` notification also persist the hold's
+ * effective availability (see `computeEffectiveReleaseAfter`) — a late
+ * release-warning send can push real availability later than the stored
+ * estimate [B]; omit it for notification kinds with no such recomputation.
+ */
 export const recordEscrowHoldNotification = async (
     holdId: string,
-    kind: EscrowHold['notifications'][number]['kind']
+    kind: EscrowHold['notifications'][number]['kind'],
+    releaseAfter?: Date
 ): Promise<void> => {
     const now = new Date();
     await getEscrowHoldsCollection().updateOne(
@@ -507,6 +624,7 @@ export const recordEscrowHoldNotification = async (
             $set: {
                 updatedAt: now,
                 ...(kind === 'started' ? { startedNotificationPending: false } : {}),
+                ...(releaseAfter ? { releaseAfter } : {}),
             },
         }
     );

package/src/models/UserKey.ts

@@ -1,5 +1,11 @@
 import { z } from 'zod';
 import { escrowBlobIdentity } from '../services/escrow-enclave/blobIdentity';
+import {
+    AuthorityCommitValidator,
+    AuthorityRecordValidator,
+    type AuthorityMutationResult,
+    type AuthorityRecord,
+} from '../services/escrow-enclave/authorityContract';
 import type { Filter } from 'mongodb';
 import { ESCROW_PIN_MAX_ATTEMPTS } from '@learncard/sss-key-manager';
 import { EscrowPinStatusValidator as SharedEscrowPinStatusValidator } from '@learncard/types';
@@ -64,6 +70,12 @@ export const EscrowEnvelopeValidator = z
     .strict();
 
 export const EscrowBlobValidator = z.object({
+    authorityGeneration: z.string().min(1).max(128).optional(),
+    enrollmentVersion: z.number().int().positive().max(Number.MAX_SAFE_INTEGER).optional(),
+    commitReceipt: AuthorityCommitValidator.optional(),
+    authorityStateProof: AuthorityRecordValidator.extend({
+        kind: z.literal('snapshot'),
+    }).optional(),
     enrollmentEpoch: z.number().int().positive(),
     blobHash: z.string().regex(/^[0-9a-f]{64}$/),
     envelope: EscrowEnvelopeValidator,
@@ -738,7 +750,12 @@ export const setEscrowBlobByAuthProvider = async (
     blob: Omit<EscrowBlob, 'enrollmentEpoch' | 'blobHash'>,
     expectedShareVersion: number,
     pin?: { salt: string },
-    carryFrom?: { blob: EscrowBlob; pin: NonNullable<MongoUserKeyType['escrowPin']> }
+    carryFrom?: { blob: EscrowBlob; pin: NonNullable<MongoUserKeyType['escrowPin']> },
+    authority?: {
+        enrollmentEpoch: number;
+        expectedBlob?: EscrowBlob;
+        expectedPin?: MongoUserKeyType['escrowPin'];
+    }
 ): Promise<MongoUserKeyType | null> => {
     const now = new Date();
     const parsed = EscrowBlobValidator.omit({ enrollmentEpoch: true, blobHash: true }).safeParse(
@@ -749,7 +766,7 @@ export const setEscrowBlobByAuthProvider = async (
     const assembled = EscrowBlobValidator.safeParse({
         ...parsed.data,
         blobHash,
-        enrollmentEpoch: 1,
+        enrollmentEpoch: authority?.enrollmentEpoch ?? 1,
     });
     if (!assembled.success) throw new Error('Invalid escrow payload');
     const { enrollmentEpoch: _initialEpoch, ...validated } = assembled.data;
@@ -764,6 +781,12 @@ export const setEscrowBlobByAuthProvider = async (
             shareVersion: expectedShareVersion,
             escrowOptedOutAt: { $exists: false },
             ...(carryFrom ? { escrowBlob: carryFrom.blob, escrowPin: carryFrom.pin } : {}),
+            ...(authority
+                ? {
+                      escrowBlob: authority.expectedBlob ?? { $exists: false },
+                      escrowPin: authority.expectedPin ?? { $exists: false },
+                  }
+                : {}),
         },
         [
             {
@@ -772,9 +795,14 @@ export const setEscrowBlobByAuthProvider = async (
                         $mergeObjects: [
                             { $literal: validated },
                             {
-                                enrollmentEpoch: {
-                                    $add: [{ $ifNull: ['$escrowBlob.enrollmentEpoch', 0] }, 1],
-                                },
+                                enrollmentEpoch: authority
+                                    ? authority.enrollmentEpoch
+                                    : {
+                                          $add: [
+                                              { $ifNull: ['$escrowBlob.enrollmentEpoch', 0] },
+                                              1,
+                                          ],
+                                      },
                             },
                         ],
                     },
@@ -837,7 +865,11 @@ export const rewrapEscrowBlobByAuthProvider = async (
     oldBlob: EscrowBlob,
     oldPin: MongoUserKeyType['escrowPin'],
     newEnvelope: EscrowBlob['envelope'],
-    identity: Pick<EscrowBlob, 'enclaveKeyId' | 'enclaveMode' | 'measurements'>
+    identity: Pick<EscrowBlob, 'enclaveKeyId' | 'enclaveMode' | 'measurements'>,
+    authority?: Pick<AuthorityMutationResult, 'authorityGeneration' | 'enrollmentVersion'> & {
+        receipt?: AuthorityRecord;
+        stateProof?: AuthorityRecord;
+    }
 ): Promise<MongoUserKeyType | null> => {
     const now = new Date();
     const blobHash = escrowBlobIdentity(newEnvelope);
@@ -850,6 +882,14 @@ export const rewrapEscrowBlobByAuthProvider = async (
         blobHash,
         enrollmentEpoch: oldBlob.enrollmentEpoch,
         createdAt: now,
+        ...(authority
+            ? {
+                  authorityGeneration: authority.authorityGeneration,
+                  enrollmentVersion: authority.enrollmentVersion,
+                  commitReceipt: authority.receipt,
+                  authorityStateProof: authority.stateProof,
+              }
+            : {}),
     });
     if (!parsed.success || parsed.data.enclaveKeyId !== parsed.data.envelope.keyId) return null;
     const filter: Filter<MongoUserKeyType> = {
@@ -885,11 +925,22 @@ export const findUserKeysWithEscrowBlobKeyId = async (
 
 export const clearEscrowByAuthProvider = async (
     authProvider: AuthProviderMapping,
-    { optOut }: { optOut: boolean }
+    {
+        optOut,
+        expected,
+    }: { optOut: boolean; expected?: { blob?: EscrowBlob; pin?: MongoUserKeyType['escrowPin'] } }
 ): Promise<MongoUserKeyType | null> => {
     const now = new Date();
     return getUserKeysCollection().findOneAndUpdate(
-        getAuthProviderFilter(authProvider),
+        {
+            ...getAuthProviderFilter(authProvider),
+            ...(expected
+                ? {
+                      escrowBlob: expected.blob ?? { $exists: false },
+                      escrowPin: expected.pin ?? { $exists: false },
+                  }
+                : {}),
+        },
         {
             $unset: { escrowBlob: '', escrowPin: '' },
             $pull: { recoveryMethods: { type: 'escrow' } },