@learncard/lca-api-service 1.4.0 → 1.5.0

package/src/models/EscrowHold.ts

@@ -1,14 +1,44 @@
-import { createHash, randomBytes, randomUUID } from 'crypto';
+import { createHash, createHmac, randomBytes } from 'crypto';
 import { z } from 'zod';
 import type { Collection } from 'mongodb';
 import mongodb from '@mongo';
 import { environment } from '@environment';
-import { AuthProviderMappingValidator, type AuthProviderMapping } from './UserKey';
+import {
+    AuthProviderMappingValidator,
+    EscrowEnvelopeValidator,
+    type AuthProviderMapping,
+} from './UserKey';
 
 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;
+// Opaque JSON validated for shape, not signature authenticity. Preserve signed extensions.
+export const EscrowHoldRecordValidator = z
+    .object({
+        hold: z
+            .object({
+                holdId: z.string().min(1),
+                did: z.string().min(1),
+                shareVersion: z.number().int().positive(),
+                blobHash: z.string().regex(/^[0-9a-f]{64}$/),
+                enrollmentEpoch: z.number().int().positive(),
+                releasePolicy: z.enum(['hold', 'pin']),
+                clientEphemeralPublicKey: z.string().min(1),
+                createdLo: z.number().int().nonnegative(),
+                createdHi: z.number().int().nonnegative(),
+                policyVersion: z.number().int().positive(),
+                signature: z.string().min(1),
+            })
+            .passthrough(),
+        holdDurationMs: z.number().int().nonnegative(),
+        ledgerSeq: z.number().int().nonnegative(),
+    })
+    .passthrough();
 export const EscrowHoldValidator = z.object({
+    // Required for new holds before escrow production launch. Raw Mongo reads can
+    // still return legacy rows without it; cancellation/release must check at runtime.
+    holdRecord: EscrowHoldRecordValidator,
     _id: z.string().uuid(),
     authProvider: AuthProviderMappingValidator,
     primaryDid: z.string(),
@@ -20,19 +50,44 @@ export const EscrowHoldValidator = z.object({
     releasePolicy: z.enum(['hold', 'pin']).default('hold'),
     cancelReason: z.enum(['pin-mismatch', 'pin-locked', 'superseded', 'release-failed']).optional(),
     cancelledAt: z.date().optional(),
-    cancelledBy: z.enum(['did', 'system']).optional(),
+    enclaveCancelPendingAt: z.date().optional(),
+    enclaveCancelConfirmedAt: z.date().optional(),
+    enclaveCancelAttempts: z.number().int().nonnegative().optional(),
+    // Retain ciphertext for revocation even after account removal or re-enrollment.
+    enclaveEnvelope: EscrowEnvelopeValidator.optional(),
+    cancelledBy: z.enum(['did', 'system', 'link']).optional(),
     completedAt: z.date().optional(),
     clientEphemeralPublicKey: z.string().min(1).max(512),
     resumeTokenHash: z.string().regex(/^[0-9a-f]{64}$/),
+    cancelTokenHash: z
+        .string()
+        .regex(/^[0-9a-f]{64}$/)
+        .optional(),
+    cancelTokenUsedAt: z.date().optional(),
+    cancelTokenHashes: z
+        .array(z.string().regex(/^[0-9a-f]{64}$/))
+        .max(4)
+        .optional(),
+    startedNotificationPending: z.boolean().optional(),
+    reminderClaimedUntil: z.date().optional(),
+    startedNotificationAttemptedAt: z.date().optional(),
+    reminderAttemptedAt: z.date().optional(),
     notifications: z
         .array(
             z.object({
-                kind: z.enum(['started', 'cancelled', 'completed']),
+                kind: z.enum(['started', 'reminder', 'completed', 'cancelled', 'pin-locked']),
                 sentAt: z.date(),
             })
         )
         .default([]),
     requestIp: z.string().optional(),
+    /**
+     * Resolved tenant id (`ResolvedTenant.id`) at the moment `startRecovery`
+     * created this hold. Optional because holds created before this field
+     * existed have none; the reminders job (P5.5) falls back to the default
+     * tenant via the email-templates registry when absent.
+     */
+    tenantId: z.string().optional(),
     createdAt: z.date(),
     updatedAt: z.date(),
 });
@@ -48,6 +103,10 @@ export type CreateEscrowHoldInput = Omit<
     | 'cancelledBy'
     | 'completedAt'
     | 'cancelReason'
+    | 'cancelTokenUsedAt'
+    | 'enclaveCancelPendingAt'
+    | 'enclaveCancelConfirmedAt'
+    | 'enclaveCancelAttempts'
 >;
 
 export const getEscrowHoldsCollection = (): Collection<EscrowHold> =>
@@ -108,13 +167,26 @@ export const createEscrowHoldsIndexes = async (): Promise<void> => {
         collection.createIndex({ 'authProvider.type': 1, 'authProvider.id': 1, status: 1 })
     );
     await runIndexMigrationOperation(() => collection.createIndex({ releaseAfter: 1 }));
+    // Backs findEscrowHoldsDueForReminder's { status:'pending', releaseAfter: {$gt,$lte} } scan.
+    await collection.createIndex(
+        { status: 1, releaseAfter: 1 },
+        { name: 'pending_escrow_hold_reminder_lookup' }
+    );
+    await collection.createIndex(
+        { status: 1, enclaveCancelConfirmedAt: 1, enclaveCancelAttempts: 1, releaseAfter: 1 },
+        { name: 'escrow_enclave_cancel_retry_lookup' }
+    );
+    await collection.createIndex(
+        { primaryDid: 1, status: 1, enclaveCancelConfirmedAt: 1 },
+        { name: 'escrow_enclave_cancel_identity_lookup' }
+    );
 };
 
 export const createEscrowHold = async (input: CreateEscrowHoldInput): Promise<EscrowHold> => {
     const now = new Date();
     const parsed = EscrowHoldValidator.safeParse({
         ...input,
-        _id: randomUUID(),
+        _id: input.holdRecord?.hold?.holdId,
         status: 'pending',
         notifications: [],
         createdAt: now,
@@ -141,6 +213,68 @@ export const findPendingEscrowHoldByAuthProvider = async (
     });
 export const findEscrowHoldById = async (id: string): Promise<EscrowHold | null> =>
     getEscrowHoldsCollection().findOne({ _id: id });
+/** Fail closed across linked providers and enrollment changes until revocation is confirmed. */
+export const hasUnconfirmedEscrowCancellation = async (primaryDid: string): Promise<boolean> =>
+    (await getEscrowHoldsCollection().countDocuments(
+        {
+            primaryDid,
+            status: 'cancelled',
+            enclaveCancelPendingAt: { $exists: true },
+            enclaveCancelConfirmedAt: { $exists: false },
+        },
+        { limit: 1 }
+    )) > 0;
+
+export const findEscrowHoldsPendingEnclaveCancellation = async (
+    limit: number
+): Promise<EscrowHold[]> =>
+    getEscrowHoldsCollection()
+        .find({
+            status: 'cancelled',
+            enclaveCancelPendingAt: { $exists: true },
+            enclaveCancelConfirmedAt: { $exists: false },
+        })
+        .sort({ enclaveCancelAttempts: 1, releaseAfter: 1 })
+        .limit(limit)
+        .toArray();
+
+export const countEscrowCancellationsNearRelease = async (now: Date): Promise<number> =>
+    getEscrowHoldsCollection().countDocuments({
+        status: 'cancelled',
+        enclaveCancelPendingAt: { $exists: true },
+        enclaveCancelConfirmedAt: { $exists: false },
+        releaseAfter: { $lte: new Date(now.getTime() + ESCROW_HOLD_REMINDER_WINDOW_MS) },
+    });
+
+export const recordEscrowEnclaveCancelAttempt = async (id: string): Promise<boolean> => {
+    const result = await getEscrowHoldsCollection().updateOne(
+        {
+            _id: id,
+            status: 'cancelled',
+            enclaveCancelPendingAt: { $exists: true },
+            enclaveCancelConfirmedAt: { $exists: false },
+        },
+        { $inc: { enclaveCancelAttempts: 1 }, $set: { updatedAt: new Date() } }
+    );
+    return result.modifiedCount > 0;
+};
+
+export const confirmEscrowEnclaveCancellation = async (id: string): Promise<void> => {
+    const now = new Date();
+    await getEscrowHoldsCollection().updateOne(
+        {
+            _id: id,
+            status: 'cancelled',
+            enclaveCancelPendingAt: { $exists: true },
+            enclaveCancelConfirmedAt: { $exists: false },
+        },
+        {
+            $set: { enclaveCancelConfirmedAt: now, updatedAt: now },
+            $unset: { enclaveCancelPendingAt: '', enclaveEnvelope: '' },
+        }
+    );
+};
+
 export const cancelEscrowHold = async (
     id: string,
     cancelledBy: 'did' | 'system',
@@ -154,6 +288,8 @@ export const cancelEscrowHold = async (
                 status: 'cancelled',
                 cancelledBy,
                 cancelledAt: now,
+                enclaveCancelPendingAt: now,
+                enclaveCancelAttempts: 0,
                 updatedAt: now,
                 ...(cancelReason ? { cancelReason } : {}),
             },
@@ -161,6 +297,39 @@ export const cancelEscrowHold = async (
         { returnDocument: 'after' }
     );
 };
+/**
+ * Cancels a hold via its single-use cancel-link token. The status transition
+ * and burning the token happen in one conditional update — matching on the
+ * exact `cancelTokenHash` plus `cancelTokenUsedAt` being unset — so two
+ * concurrent clicks on the same link can never both succeed; only the first
+ * `findOneAndUpdate` observes the pre-burn state and wins the CAS.
+ */
+export const cancelEscrowHoldByCancelToken = async (
+    id: string,
+    cancelTokenHash: string
+): Promise<EscrowHold | null> => {
+    const now = new Date();
+    return getEscrowHoldsCollection().findOneAndUpdate(
+        {
+            _id: id,
+            status: 'pending',
+            $or: [{ cancelTokenHash }, { cancelTokenHashes: cancelTokenHash }],
+            cancelTokenUsedAt: { $exists: false },
+        },
+        {
+            $set: {
+                status: 'cancelled',
+                cancelledBy: 'link',
+                cancelledAt: now,
+                enclaveCancelPendingAt: now,
+                enclaveCancelAttempts: 0,
+                cancelTokenUsedAt: now,
+                updatedAt: now,
+            },
+        },
+        { returnDocument: 'after' }
+    );
+};
 export const completeEscrowHold = async (id: string): Promise<EscrowHold | null> => {
     const now = new Date();
     return getEscrowHoldsCollection().findOneAndUpdate(
@@ -215,11 +384,158 @@ export const markClaimedEscrowHoldFailed = async (
                 cancelledBy: 'system',
                 cancelReason: reason,
                 cancelledAt: now,
+                enclaveCancelPendingAt: now,
+                enclaveCancelAttempts: 0,
                 updatedAt: now,
             },
         }
     );
 };
+/** Reopen only our own failed release claim, never another request's terminal row. */
+export const retryClaimedEscrowHold = async (id: string, completedAt: Date): Promise<void> => {
+    try {
+        await getEscrowHoldsCollection().updateOne(
+            { _id: id, status: 'completed', completedAt },
+            { $set: { status: 'pending', updatedAt: new Date() }, $unset: { completedAt: '' } }
+        );
+    } catch (error) {
+        // A replacement hold may have won the pending unique index while we released.
+        if (!(
+            typeof error === 'object' &&
+            error !== null &&
+            'code' in error &&
+            error.code === 11000
+        ))
+            throw error;
+        await markClaimedEscrowHoldFailed(id, 'release-failed', completedAt);
+    }
+};
+
+export const findEscrowHoldsPendingStartNotification = async (
+    limit: number
+): Promise<EscrowHold[]> =>
+    getEscrowHoldsCollection()
+        .find({ status: 'pending', startedNotificationPending: true })
+        .sort({ startedNotificationAttemptedAt: 1, requestedAt: 1 })
+        .limit(limit)
+        .toArray();
+
+export const recordEscrowStartNotificationAttempt = async (
+    id: string,
+    now: Date
+): Promise<void> => {
+    await getEscrowHoldsCollection().updateOne(
+        { _id: id, status: 'pending', startedNotificationPending: true },
+        { $set: { startedNotificationAttemptedAt: now } }
+    );
+};
+/**
+ * Pending, hold-policy holds whose waiting period ends within the next 24h
+ * (and hasn't ended yet) that have never been reminded. `pin`-policy holds
+ * release immediately at creation (`releaseAfter` set to the creation time,
+ * not a future date — see `startRecovery`), so `releaseAfter > now` already
+ * 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`.
+ */
+export const findEscrowHoldsDueForReminder = async (
+    now: Date,
+    limit: number
+): Promise<EscrowHold[]> =>
+    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),
+            },
+            'notifications.kind': { $ne: 'reminder' },
+        })
+        .sort({ reminderAttemptedAt: 1, releaseAfter: 1 })
+        .limit(limit)
+        .toArray();
+
+/** A short delivery lease avoids concurrent sends without recording false success.
+ * A crashed Lambda's lease expires before the next hourly run. */
+export const claimEscrowHoldForReminder = async (
+    id: string,
+    now: Date
+): Promise<EscrowHold | null> =>
+    getEscrowHoldsCollection().findOneAndUpdate(
+        {
+            _id: id,
+            status: 'pending',
+            'notifications.kind': { $ne: 'reminder' },
+            $or: [
+                { reminderClaimedUntil: { $exists: false } },
+                { reminderClaimedUntil: { $lte: now } },
+            ],
+        },
+        {
+            $set: {
+                reminderClaimedUntil: new Date(now.getTime() + 5 * 60_000),
+                reminderAttemptedAt: now,
+                updatedAt: now,
+            },
+        },
+        { returnDocument: 'after' }
+    );
+
+export const releaseEscrowReminderClaim = async (hold: EscrowHold): Promise<void> => {
+    await getEscrowHoldsCollection().updateOne(
+        { _id: hold._id, reminderClaimedUntil: hold.reminderClaimedUntil },
+        { $unset: { reminderClaimedUntil: '' } }
+    );
+};
+
 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. */
+export const recordEscrowHoldNotification = async (
+    holdId: string,
+    kind: EscrowHold['notifications'][number]['kind']
+): Promise<void> => {
+    const now = new Date();
+    await getEscrowHoldsCollection().updateOne(
+        { _id: holdId, 'notifications.kind': { $ne: kind } },
+        {
+            $push: { notifications: { kind, sentAt: now } },
+            $set: {
+                updatedAt: now,
+                ...(kind === 'started' ? { startedNotificationPending: false } : {}),
+            },
+        }
+    );
+};
+
+/**
+ * Adds a retry-stable, domain-separated token without revoking earlier links.
+ * HMAC allows delivery retries without storing plaintext or exhausting the
+ * bounded hash set. The original random hash remains valid until terminal.
+ * At most four additional hashes (plus the legacy original) are accepted;
+ * never evict a previously delivered link, even after a server seed rotation.
+ */
+export const rotateEscrowCancelToken = async (holdId: string): Promise<string | null> => {
+    const token = createHmac('sha256', environment.SEED)
+        .update(`escrow-cancel-notification:v1:${holdId}`)
+        .digest('hex');
+    const cancelTokenHash = createHash('sha256').update(token).digest('hex');
+    const now = new Date();
+    const result = await getEscrowHoldsCollection().findOneAndUpdate(
+        {
+            _id: holdId,
+            status: 'pending',
+            $or: [
+                { cancelTokenHashes: cancelTokenHash },
+                { 'cancelTokenHashes.3': { $exists: false } },
+            ],
+        },
+        { $addToSet: { cancelTokenHashes: cancelTokenHash }, $set: { updatedAt: now } },
+        { returnDocument: 'after' }
+    );
+    return result ? token : null;
+};

package/src/models/UserKey.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { escrowBlobIdentity } from '../services/escrow-enclave/blobIdentity';
 import type { Filter } from 'mongodb';
 import { ESCROW_PIN_MAX_ATTEMPTS } from '@learncard/sss-key-manager';
 import { EscrowPinStatusValidator as SharedEscrowPinStatusValidator } from '@learncard/types';
@@ -63,6 +64,8 @@ export const EscrowEnvelopeValidator = z
     .strict();
 
 export const EscrowBlobValidator = z.object({
+    enrollmentEpoch: z.number().int().positive(),
+    blobHash: z.string().regex(/^[0-9a-f]{64}$/),
     envelope: EscrowEnvelopeValidator,
     enclaveKeyId: z.string().regex(/^[A-Za-z0-9._-]{1,128}$/),
     enclaveMode: z.enum(['software', 'nitro']),
@@ -732,21 +735,29 @@ const getAuthProviderFilter = (authProvider: AuthProviderMapping): Filter<MongoU
 /** Persist verified escrow and its confirmed descriptor atomically. */
 export const setEscrowBlobByAuthProvider = async (
     authProvider: AuthProviderMapping,
-    blob: EscrowBlob,
+    blob: Omit<EscrowBlob, 'enrollmentEpoch' | 'blobHash'>,
     expectedShareVersion: number,
     pin?: { salt: string },
     carryFrom?: { blob: EscrowBlob; pin: NonNullable<MongoUserKeyType['escrowPin']> }
 ): Promise<MongoUserKeyType | null> => {
     const now = new Date();
-    const parsed = EscrowBlobValidator.safeParse(blob);
+    const parsed = EscrowBlobValidator.omit({ enrollmentEpoch: true, blobHash: true }).safeParse(
+        blob
+    );
     if (!parsed.success) throw new Error('Invalid escrow payload');
-    const validated = parsed.data;
+    const blobHash = escrowBlobIdentity(parsed.data.envelope);
+    const assembled = EscrowBlobValidator.safeParse({
+        ...parsed.data,
+        blobHash,
+        enrollmentEpoch: 1,
+    });
+    if (!assembled.success) throw new Error('Invalid escrow payload');
+    const { enrollmentEpoch: _initialEpoch, ...validated } = assembled.data;
     if (
         validated.shareVersion !== expectedShareVersion ||
         validated.enclaveKeyId !== validated.envelope.keyId
-    ) {
+    )
         return null;
-    }
     return getUserKeysCollection().findOneAndUpdate(
         {
             ...getAuthProviderFilter(authProvider),
@@ -757,7 +768,16 @@ export const setEscrowBlobByAuthProvider = async (
         [
             {
                 $set: {
-                    escrowBlob: { $literal: validated },
+                    escrowBlob: {
+                        $mergeObjects: [
+                            { $literal: validated },
+                            {
+                                enrollmentEpoch: {
+                                    $add: [{ $ifNull: ['$escrowBlob.enrollmentEpoch', 0] }, 1],
+                                },
+                            },
+                        ],
+                    },
                     escrowPin: carryFrom
                         ? { $literal: { ...carryFrom.pin, shareVersion: expectedShareVersion } }
                         : pin
@@ -798,6 +818,71 @@ export const setEscrowBlobByAuthProvider = async (
     );
 };
 
+/**
+ * P9.3: migrates an escrow blob sealed under a previous enclave key onto the
+ * current one. Atomic compare-and-swap against the OLD envelope/blob object
+ * AND the unchanged `escrowPin` (read at the same time as `oldBlob`, so ANY
+ * concurrent write to this account since — a re-enroll, a PIN change, an
+ * opt-out — loses the race safely rather than overwriting a stale
+ * assumption), even though this write never touches `escrowPin` itself.
+ * Writes the new envelope under the CURRENT `enclaveKeyId`, a fresh
+ * Rust-order `blobHash` (identical algorithm to `setEscrowBlobByAuthProvider`),
+ * the SAME `enrollmentEpoch` and `shareVersion` — `escrowPin` is left
+ * exactly as read. Lost race (version bump, opt-out, or any other change
+ * since `oldBlob`/`oldPin` were read) -> null, no-op; callers retry on a
+ * later job run rather than treating this as an error.
+ */
+export const rewrapEscrowBlobByAuthProvider = async (
+    authProvider: AuthProviderMapping,
+    oldBlob: EscrowBlob,
+    oldPin: MongoUserKeyType['escrowPin'],
+    newEnvelope: EscrowBlob['envelope'],
+    identity: Pick<EscrowBlob, 'enclaveKeyId' | 'enclaveMode' | 'measurements'>
+): Promise<MongoUserKeyType | null> => {
+    const now = new Date();
+    const blobHash = escrowBlobIdentity(newEnvelope);
+    const parsed = EscrowBlobValidator.safeParse({
+        envelope: newEnvelope,
+        enclaveKeyId: identity.enclaveKeyId,
+        enclaveMode: identity.enclaveMode,
+        measurements: identity.measurements,
+        shareVersion: oldBlob.shareVersion,
+        blobHash,
+        enrollmentEpoch: oldBlob.enrollmentEpoch,
+        createdAt: now,
+    });
+    if (!parsed.success || parsed.data.enclaveKeyId !== parsed.data.envelope.keyId) return null;
+    const filter: Filter<MongoUserKeyType> = {
+        ...getAuthProviderFilter(authProvider),
+        escrowBlob: oldBlob,
+        escrowOptedOutAt: { $exists: false },
+        ...(oldPin ? { escrowPin: oldPin } : { escrowPin: { $exists: false } }),
+    };
+    return getUserKeysCollection().findOneAndUpdate(
+        filter,
+        { $set: { escrowBlob: parsed.data, updatedAt: now } },
+        { returnDocument: 'after' }
+    );
+};
+
+/**
+ * P9.3 migration job candidates: escrow blobs still sealed under any of the
+ * given (previous) enclave keys. Never returns opted-out accounts — escrow
+ * is fully disabled for them, so there is nothing to migrate. Bounded by
+ * `limit`, mirroring `findEscrowHoldsDueForReminder`'s own batch shape.
+ */
+export const findUserKeysWithEscrowBlobKeyId = async (
+    keyIds: string[],
+    limit: number
+): Promise<MongoUserKeyType[]> =>
+    getUserKeysCollection()
+        .find({
+            'escrowBlob.enclaveKeyId': { $in: keyIds },
+            escrowOptedOutAt: { $exists: false },
+        })
+        .limit(limit)
+        .toArray();
+
 export const clearEscrowByAuthProvider = async (
     authProvider: AuthProviderMapping,
     { optOut }: { optOut: boolean }

package/src/models/index.ts

@@ -6,3 +6,4 @@ export * from './Pins';
 export * from './Preferences';
 export * from './UserKey';
 export * from './EscrowHold';
+export * from './AuthSubject';