@learncard/lca-api-service 1.3.2 → 1.5.0

package/src/routes/escrow.ts

@@ -0,0 +1,1073 @@
+import { timingSafeEqual, randomUUID } from 'crypto';
+import { z } from 'zod';
+import { TRPCError } from '@trpc/server';
+import { ESCROW_PIN_MAX_ATTEMPTS } from '@learncard/sss-key-manager';
+import {
+    ESCROW_PIN_LOCKED_MESSAGE,
+    ESCROW_PIN_UNAVAILABLE_MESSAGE,
+    escrowPinMismatchMessage,
+} from '@learncard/types';
+import cache from '@cache';
+import { environment, isEscrowReleaseKillSwitchEnabled } from '@environment';
+import { t, openRoute, didAndChallengeRoute, type Context } from '@routes';
+import { createRecoverySession } from '@cache/recoverySessions';
+import { decryptAuthShare } from '@helpers/shareEncryption.helpers';
+import {
+    generateEscrowCancelToken,
+    hashEscrowCancelToken,
+    escrowCancelTokenMatches,
+} from '@helpers/escrowCancelToken';
+import {
+    EscrowEnvelopeValidator,
+    EscrowBlobValidator,
+    EscrowPinSaltValidator,
+    reserveEscrowPinAttempt,
+    refundEscrowPinAttempt,
+    recordEscrowPinFailure,
+    disableEscrowPin,
+    markClaimedEscrowHoldFailed,
+    retryClaimedEscrowHold,
+    ServerEncryptedShareValidator,
+    findUserKeyByAuthProvider,
+    findAuthShareByVersion,
+    isRecoveryMethodConfirmed,
+    setEscrowBlobByAuthProvider,
+    clearEscrowByAuthProvider,
+    setEscrowOptInByAuthProvider,
+    createEscrowHold,
+    createEscrowHoldsIndexes,
+    findPendingEscrowHoldByAuthProvider,
+    findEscrowHoldById,
+    cancelEscrowHold,
+    hasUnconfirmedEscrowCancellation,
+    cancelEscrowHoldByCancelToken,
+    completeEscrowHold,
+    hasCompletedEscrowHoldForVersion,
+    expireStaleEscrowHolds,
+    hashEscrowResumeToken,
+    generateEscrowResumeToken,
+    type EscrowHold,
+    type MongoUserKeyType,
+    type AuthProviderMapping,
+} from '@models';
+import {
+    AuthInputValidator,
+    AuthProviderTypeValidator,
+    RecoverySessionTokenValidator,
+    verifyAndGetContactMethod,
+    requireUserKey,
+    assertDidOwner,
+    requireRecoverySession,
+} from './keys';
+import {
+    getEscrowEnclave,
+    getEscrowHoldDurationMs,
+    getEscrowHoldRestartMinAgeMs,
+    isEscrowRemoteMode,
+    activeEscrowClientMode,
+    getEnclaveAttestationIdentity,
+    notifyEscrowHoldEvent,
+    EscrowPolicyError,
+    EscrowBlobError,
+    EscrowUnavailableError,
+    EscrowPinMismatchError,
+} from '../services/escrow-enclave';
+
+import { cancelHoldInEnclave } from '../services/escrow-enclave/cancellation';
+const unavailableMessage = 'Automatic recovery is not available for this account.';
+const killSwitchMessage = 'Automatic recovery is temporarily unavailable. Please try again later.';
+const invalidMessage = 'This recovery request is no longer valid.';
+const staleEscrowMessage = 'Automatic recovery needs to be set up again on a signed-in device.';
+// Roughtime's release lower bound can lag its creation upper bound. Advertise
+// an additional minute, and still allow retries when trusted time is unavailable.
+const ESCROW_RELEASE_TIME_MARGIN_MS = 60_000;
+// Keep throttling distinct: clients reserve the locked message for lifetime PIN exhaustion.
+const pinThrottledMessage = 'Please wait before trying again.';
+
+// Follow qr-login's Redis INCR/EXPIRE per-IP limiter. keys.ts has only OTP-specific limits.
+const limitPinCompletion = async (
+    clientIp: string | undefined,
+    operation: 'start' | 'complete' = 'complete'
+): Promise<void> => {
+    const redis = cache.redis ?? cache.node;
+    const key = `escrow:pin-${operation}:${clientIp ?? 'unknown'}`;
+    const count = await redis.incr(key);
+    if (count === 1) await redis.expire(key, 60);
+    if (count > 20)
+        throw new TRPCError({
+            code: 'TOO_MANY_REQUESTS',
+            message: pinThrottledMessage,
+        });
+};
+
+// Same Redis INCR/EXPIRE per-IP shape as limitPinCompletion, scoped under its
+// own key so cancel-link attempts never share (or exhaust) the PIN budget.
+const limitCancelLinkAttempts = async (clientIp: string | undefined): Promise<void> => {
+    const redis = cache.redis ?? cache.node;
+    const key = `escrow:cancel-link:${clientIp ?? 'unknown'}`;
+    const count = await redis.incr(key);
+    if (count === 1) await redis.expire(key, 60);
+    if (count > 20)
+        throw new TRPCError({
+            code: 'TOO_MANY_REQUESTS',
+            message: pinThrottledMessage,
+        });
+};
+
+const lockPin = async (
+    hold: EscrowHold,
+    userKey: MongoUserKeyType,
+    tenant: Context['tenant']
+): Promise<void> => {
+    const disabled = await disableEscrowPin(
+        hold.authProvider,
+        hold.shareVersion,
+        userKey.escrowBlob?.envelope.ciphertext
+    );
+    // Always burn this request, but never disable/cancel a replacement enrollment.
+    const cancelled = await cancelEscrowHold(hold._id, 'system', 'pin-locked');
+    if (cancelled) {
+        await cancelHoldInEnclave(cancelled, userKey);
+        await notifyEscrowHoldEvent({ kind: 'cancelled', hold: cancelled, userKey, tenant });
+    }
+    if (!disabled) return;
+    // The pin-locked notice's cancel link must point at the account's still-open
+    // waiting-period hold (if any) — `hold` itself is already terminal by this
+    // point, so a link rooted there could never authorize a cancel.
+    let activeHold: EscrowHold | undefined;
+    for (const provider of userKey.authProviders) {
+        activeHold = (await findPendingEscrowHoldByAuthProvider(provider, 'hold')) ?? undefined;
+        if (activeHold) break;
+    }
+    // One lockout notice per lock event, not per cancelled hold below — the PIN
+    // capability is account-wide, not per-hold.
+    await notifyEscrowHoldEvent({ kind: 'pin-locked', hold, userKey, tenant, activeHold });
+    for (const provider of userKey.authProviders) {
+        const pending = await findPendingEscrowHoldByAuthProvider(provider, 'pin');
+        if (pending?.releasePolicy === 'pin' && pending.shareVersion === hold.shareVersion) {
+            const cancelled = await cancelEscrowHold(pending._id, 'system', 'pin-locked');
+            if (cancelled) {
+                await cancelHoldInEnclave(cancelled, userKey);
+                await notifyEscrowHoldEvent({
+                    kind: 'cancelled',
+                    hold: cancelled,
+                    userKey,
+                    tenant,
+                });
+            }
+        }
+    }
+};
+let holdIndexes: Promise<void> | undefined;
+
+// Lambda and in-process callers do not run docker-entry's index initialization.
+const ensureHoldIndexes = async (): Promise<void> => {
+    holdIndexes ??= createEscrowHoldsIndexes().catch(() => {
+        holdIndexes = undefined;
+        throw new TRPCError({
+            code: 'INTERNAL_SERVER_ERROR',
+            message: 'Recovery could not be started.',
+        });
+    });
+    await holdIndexes;
+};
+const successValidator = z.object({ success: z.literal(true) });
+const cancelByLinkInput = z
+    .object({
+        holdId: z.string().uuid(),
+        token: z.string().regex(/^[0-9a-f]{64}$/),
+    })
+    .strict();
+const resumeInput = z
+    .object({
+        holdId: z.string().uuid(),
+        resumeToken: z.string().min(1).max(512),
+    })
+    .strict();
+const holdStatusValidator = z.object({
+    holdId: z.string(),
+    status: z.enum(['pending', 'cancelled', 'completed', 'expired']),
+    requestedAt: z.string(),
+    releaseAfter: z.string(),
+    releasePolicy: z.enum(['hold', 'pin']),
+    cancelledAt: z.string().optional(),
+    completedAt: z.string().optional(),
+});
+
+const serializeHold = (hold: EscrowHold): z.infer<typeof holdStatusValidator> => ({
+    holdId: hold._id,
+    status: hold.status,
+    requestedAt: hold.requestedAt.toISOString(),
+    releaseAfter: hold.releaseAfter.toISOString(),
+    releasePolicy: hold.releasePolicy ?? 'hold',
+    ...(hold.cancelledAt ? { cancelledAt: hold.cancelledAt.toISOString() } : {}),
+    ...(hold.completedAt ? { completedAt: hold.completedAt.toISOString() } : {}),
+});
+
+const resumeTokenMatches = (hold: EscrowHold, token: string): boolean => {
+    const actual = Buffer.from(hashEscrowResumeToken(token), 'hex');
+    const expected = Buffer.from(hold.resumeTokenHash, 'hex');
+    return actual.length === expected.length && timingSafeEqual(actual, expected);
+};
+
+const hasConfirmedEscrow = (userKey: MongoUserKeyType, version: number): boolean =>
+    userKey.recoveryMethods.some(
+        method =>
+            method.type === 'escrow' &&
+            method.shareVersion === version &&
+            isRecoveryMethodConfirmed(userKey, method)
+    );
+
+/** Never propagate enclave internals (or cryptographic payloads) into tRPC errors. */
+const enclaveOperation = async <T>(
+    operation: () => Promise<T>,
+    enrolling = false,
+    policyMessage = invalidMessage
+): Promise<T> => {
+    try {
+        return await operation();
+    } catch (error) {
+        if (error instanceof EscrowUnavailableError) {
+            throw new TRPCError({
+                code: 'PRECONDITION_FAILED',
+                message: 'Escrow recovery is not available.',
+            });
+        }
+        if (error instanceof EscrowPolicyError) {
+            throw new TRPCError({ code: 'FORBIDDEN', message: policyMessage });
+        }
+        if (enrolling && error instanceof EscrowBlobError) {
+            throw new TRPCError({
+                code: 'BAD_REQUEST',
+                message: 'Invalid automatic recovery material.',
+            });
+        }
+        throw new TRPCError({
+            code: 'INTERNAL_SERVER_ERROR',
+            message: 'Recovery material could not be released.',
+        });
+    }
+};
+
+// A stored blob is stale when it was sealed for a different enclave backend
+// (P6 software<->nitro migration/rollback) or a since-rotated enclave key
+// (measurement rotation). Never forward a stale blob to createHold/releaseEscrow
+// UNLESS the blob's keyId is a recognised previous key (P9.1/P9.2): the enclave
+// can still decrypt/release it, so only an UNKNOWN keyId blocks the operation.
+const assertFreshEscrowBlob = (blob: {
+    enclaveMode: 'software' | 'nitro';
+    enclaveKeyId: string;
+}): Promise<void> =>
+    enclaveOperation(
+        async () => {
+            if (blob.enclaveMode !== activeEscrowClientMode()) throw new EscrowPolicyError();
+            // Fail-closed identity lookup: uses a warm cache when available,
+            // otherwise makes a real (normally-timed-out) enclave call and lets
+            // failure propagate — never treats an unreachable enclave as fresh.
+            const identity = await getEnclaveAttestationIdentity();
+            if (
+                blob.enclaveKeyId !== identity.keyId &&
+                !identity.previousKeyIds.includes(blob.enclaveKeyId)
+            ) {
+                throw new EscrowPolicyError();
+            }
+        },
+        false,
+        staleEscrowMessage
+    );
+
+// Strict objects with exclusive proof fields also remain compatible with OpenAPI's
+// object-only parameter generation (unlike a top-level Zod union).
+const startInput = z
+    .object({
+        clientEphemeralPublicKey: z.string().min(1).max(512),
+        releasePolicy: z.enum(['hold', 'pin']).default('hold'),
+        restart: z.boolean().optional(),
+        authToken: z.string().optional(),
+        providerType: AuthProviderTypeValidator.optional(),
+        recoverySessionToken: RecoverySessionTokenValidator.optional(),
+    })
+    .strict()
+    .refine(
+        input =>
+            input.recoverySessionToken !== undefined
+                ? input.authToken === undefined && input.providerType === undefined
+                : input.authToken !== undefined && input.providerType !== undefined,
+        { message: 'Provide exactly one identity proof.' }
+    );
+
+// P0-4: this is a GET route, so neither the resume token nor the provider
+// token may travel in the query string (proxy/ALB access logs). Raw-fetch
+// callers send whichever secret applies as the X-Auth-Token header
+// (ctx.providerToken); the optional input fields exist only for native tRPC
+// callers whose batch link always POSTs.
+const statusInput = z
+    .object({
+        holdId: z.string().uuid().optional(),
+        resumeToken: z.string().min(1).max(512).optional(),
+        authToken: z.string().optional(),
+        providerType: AuthProviderTypeValidator.optional(),
+    })
+    .strict()
+    .refine(
+        input =>
+            input.holdId !== undefined
+                ? input.authToken === undefined && input.providerType === undefined
+                : input.resumeToken === undefined && input.providerType !== undefined,
+        { message: 'Provide exactly one identity proof.' }
+    );
+
+export const escrowRouter = t.router({
+    getAttestation: openRoute
+        .meta({ openapi: { method: 'GET', path: '/keys/escrow/attestation', tags: ['Keys'] } })
+        .input(
+            z
+                .object({
+                    nonce: z
+                        .string()
+                        .regex(/^[0-9a-f]{64}$/i)
+                        .optional(),
+                })
+                .strict()
+        )
+        .output(
+            z.object({
+                attestation: z.object({
+                    mode: z.enum(['software', 'nitro']),
+                    keyId: z.string(),
+                    previousKeyIds: z.array(z.string()).optional(),
+                    publicKey: z.string(),
+                    measurements: EscrowBlobValidator.shape.measurements,
+                    document: z.string(),
+                    issuedAt: z.string(),
+                }),
+                holdDurationMs: z.number(),
+            })
+        )
+        .query(async ({ input }) => {
+            // Nitro attestation is only meaningful bound to a fresh client nonce
+            // (sss-key-manager always sends one: GET .../attestation?nonce=<64 hex>);
+            // the software backend has no freshness story and never required one.
+            if (isEscrowRemoteMode() && !input.nonce) {
+                throw new TRPCError({
+                    code: 'BAD_REQUEST',
+                    message: 'A nonce is required for attestation.',
+                });
+            }
+            const nonce = input.nonce
+                ? Uint8Array.from(Buffer.from(input.nonce, 'hex'))
+                : undefined;
+            return {
+                attestation: await enclaveOperation(() => getEscrowEnclave().getAttestation(nonce)),
+                holdDurationMs: getEscrowHoldDurationMs(),
+            };
+        }),
+
+    enroll: didAndChallengeRoute
+        .meta({ openapi: { method: 'POST', path: '/keys/escrow', tags: ['Keys'] } })
+        .input(
+            AuthInputValidator.extend({
+                envelope: EscrowEnvelopeValidator,
+                shareVersion: z.number().int().positive(),
+                enclaveKeyId: EscrowBlobValidator.shape.enclaveKeyId,
+                pinSalt: EscrowPinSaltValidator.optional(),
+                clearPin: z.boolean().optional(),
+            }).strict()
+        )
+        .output(successValidator.extend({ shareVersion: z.number() }))
+        .mutation(async ({ input, ctx }) => {
+            const { authProvider } = await verifyAndGetContactMethod(input);
+            const userKey = await requireUserKey(authProvider);
+            assertDidOwner(userKey, ctx.user.did);
+            if (userKey.escrowOptedOutAt) {
+                throw new TRPCError({
+                    code: 'CONFLICT',
+                    message: 'Automatic recovery is turned off for this account.',
+                });
+            }
+            if (input.shareVersion !== userKey.shareVersion) {
+                throw new TRPCError({
+                    code: 'CONFLICT',
+                    message: 'Key material changed; please retry.',
+                });
+            }
+            const attestation = await enclaveOperation(() => getEscrowEnclave().getAttestation());
+            if (
+                input.enclaveKeyId !== attestation.keyId ||
+                input.envelope.keyId !== attestation.keyId
+            ) {
+                throw new TRPCError({
+                    code: 'BAD_REQUEST',
+                    message: 'Invalid automatic recovery key.',
+                });
+            }
+            const verification = await enclaveOperation(
+                () =>
+                    getEscrowEnclave().verifyEscrowBlob({
+                        envelope: input.envelope,
+                        expectedDid: ctx.user.did,
+                        expectedShareVersion: input.shareVersion,
+                    }),
+                true
+            );
+            if (
+                !verification.ok ||
+                verification.hasPin !== !!input.pinSalt ||
+                (input.clearPin && input.pinSalt)
+            ) {
+                throw new TRPCError({
+                    code: 'BAD_REQUEST',
+                    message: 'Invalid automatic recovery material.',
+                });
+            }
+            const blob = {
+                envelope: input.envelope,
+                enclaveKeyId: attestation.keyId,
+                enclaveMode: attestation.mode,
+                measurements: attestation.measurements,
+                shareVersion: input.shareVersion,
+                createdAt: new Date(),
+            };
+            let stored;
+            const oldBlob = userKey.escrowBlob;
+            const oldPin = userKey.escrowPin;
+            if (!input.pinSalt && !input.clearPin && oldPin) {
+                if (
+                    oldBlob &&
+                    !oldPin.disabledAt &&
+                    oldPin.shareVersion === oldBlob.shareVersion &&
+                    // P9.2: carry from the current key OR a still-accepted previous
+                    // key (deliberate rotation / lost-sealed-key recovery) — only a
+                    // fully unrecognised keyId drops the PIN (see assertFreshEscrowBlob).
+                    (oldBlob.enclaveKeyId === attestation.keyId ||
+                        (attestation.previousKeyIds ?? []).includes(oldBlob.enclaveKeyId)) &&
+                    input.shareVersion > oldBlob.shareVersion &&
+                    // A released blob's PIN is retired: it was just used, or the user forgot it.
+                    !(await hasCompletedEscrowHoldForVersion(authProvider, oldBlob.shareVersion))
+                ) {
+                    try {
+                        const carried = await getEscrowEnclave().carryPinVerifier({
+                            sourceEnvelope: oldBlob.envelope,
+                            targetEnvelope: input.envelope,
+                            expectedDid: ctx.user.did,
+                            sourceShareVersion: oldBlob.shareVersion,
+                            targetShareVersion: input.shareVersion,
+                            sourceEnrollmentEpoch: oldBlob.enrollmentEpoch,
+                            targetEnrollmentEpoch: oldBlob.enrollmentEpoch + 1,
+                        });
+                        stored = await setEscrowBlobByAuthProvider(
+                            authProvider,
+                            { ...blob, envelope: carried.envelope },
+                            input.shareVersion,
+                            undefined,
+                            { blob: oldBlob, pin: oldPin }
+                        );
+                    } catch {
+                        // Never log enclave errors: a backend could include decrypted material.
+                        console.warn('[LCA escrow/enroll] PIN carry failed; enrolling without PIN');
+                    }
+                }
+                if (!stored) {
+                    console.warn(
+                        '[LCA escrow/enroll] PIN carry unavailable; enrolling without PIN'
+                    );
+                }
+            }
+            stored ??= await setEscrowBlobByAuthProvider(
+                authProvider,
+                blob,
+                input.shareVersion,
+                input.pinSalt ? { salt: input.pinSalt } : undefined
+            );
+            if (!stored)
+                throw new TRPCError({
+                    code: 'CONFLICT',
+                    message: 'Key material changed; please retry.',
+                });
+            return { success: true as const, shareVersion: input.shareVersion };
+        }),
+
+    remove: didAndChallengeRoute
+        .meta({ openapi: { method: 'DELETE', path: '/keys/escrow', tags: ['Keys'] } })
+        .input(AuthInputValidator.extend({ optOut: z.boolean() }).strict())
+        .output(successValidator)
+        .mutation(async ({ input, ctx }) => {
+            const { authProvider } = await verifyAndGetContactMethod(input);
+            const userKey = await requireUserKey(authProvider);
+            assertDidOwner(userKey, ctx.user.did);
+            if (
+                input.optOut &&
+                !userKey.recoveryMethods.some(
+                    method =>
+                        method.type !== 'escrow' &&
+                        method.shareVersion === userKey.shareVersion &&
+                        isRecoveryMethodConfirmed(userKey, method)
+                )
+            ) {
+                throw new TRPCError({
+                    code: 'PRECONDITION_FAILED',
+                    message:
+                        'Set up another recovery method before turning off automatic recovery.',
+                });
+            }
+            await clearEscrowByAuthProvider(authProvider, { optOut: input.optOut });
+            for (const policy of ['hold', 'pin'] as const) {
+                const pending = await findPendingEscrowHoldByAuthProvider(authProvider, policy);
+                const cancelled = pending && (await cancelEscrowHold(pending._id, 'did'));
+                if (cancelled) {
+                    await cancelHoldInEnclave(cancelled, userKey);
+                    await notifyEscrowHoldEvent({
+                        kind: 'cancelled',
+                        hold: cancelled,
+                        userKey,
+                        tenant: ctx.tenant,
+                    });
+                }
+            }
+            return { success: true as const };
+        }),
+
+    optIn: didAndChallengeRoute
+        .meta({ openapi: { method: 'POST', path: '/keys/escrow/opt-in', tags: ['Keys'] } })
+        .input(AuthInputValidator.strict())
+        .output(successValidator)
+        .mutation(async ({ input, ctx }) => {
+            const { authProvider } = await verifyAndGetContactMethod(input);
+            const userKey = await requireUserKey(authProvider);
+            assertDidOwner(userKey, ctx.user.did);
+            await setEscrowOptInByAuthProvider(authProvider);
+            return { success: true as const };
+        }),
+
+    startRecovery: openRoute
+        .meta({ openapi: { method: 'POST', path: '/keys/escrow/recover', tags: ['Keys'] } })
+        .input(startInput)
+        .output(
+            holdStatusValidator
+                .pick({ holdId: true, requestedAt: true, releaseAfter: true, releasePolicy: true })
+                .extend({
+                    status: z.literal('pending'),
+                    resumeToken: z.string().nullable(),
+                    pinSalt: EscrowPinSaltValidator.optional(),
+                })
+        )
+        .mutation(async ({ input, ctx }) => {
+            if (isEscrowReleaseKillSwitchEnabled()) {
+                throw new TRPCError({
+                    code: 'PRECONDITION_FAILED',
+                    message: killSwitchMessage,
+                });
+            }
+            let authProvider: AuthProviderMapping;
+            if (input.releasePolicy === 'pin') await limitPinCompletion(ctx.clientIp, 'start');
+            if (input.recoverySessionToken !== undefined) {
+                try {
+                    authProvider = await requireRecoverySession(
+                        input.recoverySessionToken,
+                        'recover'
+                    );
+                } catch (error) {
+                    if (!(error instanceof TRPCError) || error.code !== 'UNAUTHORIZED') throw error;
+                    throw new TRPCError({ code: 'NOT_FOUND', message: unavailableMessage });
+                }
+            } else {
+                ({ authProvider } = await verifyAndGetContactMethod({
+                    authToken: input.authToken!,
+                    providerType: input.providerType!,
+                }));
+            }
+            const userKey = await findUserKeyByAuthProvider(authProvider.type, authProvider.id);
+            if (
+                !userKey?.escrowBlob ||
+                userKey.escrowOptedOutAt ||
+                !hasConfirmedEscrow(userKey, userKey.escrowBlob.shareVersion)
+            ) {
+                throw new TRPCError({ code: 'NOT_FOUND', message: unavailableMessage });
+            }
+            if (await hasUnconfirmedEscrowCancellation(userKey.primaryDid)) {
+                throw new TRPCError({
+                    code: 'PRECONDITION_FAILED',
+                    message: killSwitchMessage,
+                });
+            }
+            await assertFreshEscrowBlob(userKey.escrowBlob);
+            const now = new Date();
+            if (
+                input.releasePolicy === 'pin' &&
+                (!userKey.escrowPin ||
+                    userKey.escrowPin.disabledAt ||
+                    userKey.escrowPin.shareVersion !== userKey.shareVersion)
+            ) {
+                throw new TRPCError({
+                    code: 'FORBIDDEN',
+                    message: ESCROW_PIN_UNAVAILABLE_MESSAGE,
+                });
+            }
+            await expireStaleEscrowHolds(now);
+            await ensureHoldIndexes();
+            // Policies coexist; reuse waiting holds only while their material is current.
+            const pending = await findPendingEscrowHoldByAuthProvider(
+                authProvider,
+                input.releasePolicy
+            );
+            if (
+                pending &&
+                input.releasePolicy === 'hold' &&
+                (pending.releasePolicy ?? 'hold') === 'hold' &&
+                pending.shareVersion === userKey.escrowBlob.shareVersion
+            ) {
+                if (!input.restart)
+                    return {
+                        ...serializeHold(pending),
+                        status: 'pending' as const,
+                        resumeToken: null,
+                    };
+                const minAge = getEscrowHoldRestartMinAgeMs();
+                if (now.getTime() - pending.requestedAt.getTime() < minAge) {
+                    const retryAfter = new Date(
+                        pending.requestedAt.getTime() + minAge
+                    ).toISOString();
+                    throw new TRPCError({
+                        code: 'TOO_MANY_REQUESTS',
+                        message: `A recovery request was started recently. Try again after ${retryAfter}.`,
+                    });
+                }
+            }
+            if (pending) {
+                const cancelled = await cancelEscrowHold(pending._id, 'system', 'superseded');
+                if (cancelled) {
+                    await cancelHoldInEnclave(cancelled, userKey);
+                    await notifyEscrowHoldEvent({
+                        kind: 'cancelled',
+                        hold: cancelled,
+                        userKey,
+                        reason: 'superseded',
+                        tenant: ctx.tenant,
+                    });
+                }
+            }
+            if (await hasUnconfirmedEscrowCancellation(userKey.primaryDid)) {
+                throw new TRPCError({
+                    code: 'PRECONDITION_FAILED',
+                    message: killSwitchMessage,
+                });
+            }
+            const resumeToken = generateEscrowResumeToken();
+            const cancelToken = generateEscrowCancelToken();
+            const { holdRecord } = await enclaveOperation(() =>
+                getEscrowEnclave().createHold({
+                    envelope: userKey.escrowBlob!.envelope,
+                    holdId: randomUUID(),
+                    expectedDid: userKey.primaryDid,
+                    expectedShareVersion: userKey.escrowBlob!.shareVersion,
+                    enrollmentEpoch: userKey.escrowBlob!.enrollmentEpoch,
+                    releasePolicy: input.releasePolicy,
+                    clientEphemeralPublicKey: input.clientEphemeralPublicKey,
+                })
+            );
+            let hold: EscrowHold;
+            try {
+                hold = await createEscrowHold({
+                    holdRecord,
+                    authProvider,
+                    enclaveEnvelope: userKey.escrowBlob.envelope,
+                    primaryDid: userKey.primaryDid,
+                    shareVersion: userKey.escrowBlob.shareVersion,
+                    identityProofType:
+                        input.recoverySessionToken !== undefined
+                            ? 'recovery-session'
+                            : 'auth-token',
+                    requestedAt: now,
+                    releaseAfter:
+                        input.releasePolicy === 'pin'
+                            ? now
+                            : new Date(
+                                  holdRecord.hold.createdHi +
+                                      holdRecord.holdDurationMs +
+                                      ESCROW_RELEASE_TIME_MARGIN_MS
+                              ),
+                    releasePolicy: input.releasePolicy,
+                    clientEphemeralPublicKey: input.clientEphemeralPublicKey,
+                    resumeTokenHash: hashEscrowResumeToken(resumeToken),
+                    cancelTokenHash: hashEscrowCancelToken(cancelToken),
+                    startedNotificationPending: true,
+                    requestIp: ctx.clientIp,
+                    tenantId: ctx.tenant?.id,
+                });
+            } catch (error) {
+                if (
+                    typeof error === 'object' &&
+                    error !== null &&
+                    'code' in error &&
+                    error.code === 11000
+                ) {
+                    const raced = await findPendingEscrowHoldByAuthProvider(
+                        authProvider,
+                        input.releasePolicy
+                    );
+                    if (
+                        raced &&
+                        !input.restart &&
+                        input.releasePolicy === 'hold' &&
+                        (raced.releasePolicy ?? 'hold') === 'hold' &&
+                        raced.shareVersion === userKey.escrowBlob.shareVersion
+                    )
+                        return {
+                            ...serializeHold(raced),
+                            status: 'pending' as const,
+                            resumeToken: null,
+                        };
+                    throw new TRPCError({
+                        code: 'CONFLICT',
+                        message: 'Recovery state changed; please retry.',
+                    });
+                }
+                throw new TRPCError({
+                    code: 'INTERNAL_SERVER_ERROR',
+                    message: 'Recovery could not be started.',
+                });
+            }
+            await notifyEscrowHoldEvent({
+                kind: 'started',
+                hold,
+                userKey,
+                cancelToken,
+                tenant: ctx.tenant,
+            });
+            return {
+                ...serializeHold(hold),
+                status: 'pending' as const,
+                resumeToken,
+                ...(input.releasePolicy === 'pin' ? { pinSalt: userKey.escrowPin!.salt } : {}),
+            };
+        }),
+
+    getStatus: openRoute
+        .meta({ openapi: { method: 'GET', path: '/keys/escrow/status', tags: ['Keys'] } })
+        .input(statusInput)
+        .output(z.object({ hold: holdStatusValidator.nullable() }))
+        .query(async ({ input, ctx }) => {
+            await expireStaleEscrowHolds(new Date());
+            let hold: EscrowHold | null;
+            if (input.holdId !== undefined) {
+                const resumeToken = input.resumeToken || ctx.providerToken || '';
+                hold = resumeToken ? await findEscrowHoldById(input.holdId) : null;
+                if (hold && !resumeTokenMatches(hold, resumeToken)) hold = null;
+            } else {
+                const { authProvider } = await verifyAndGetContactMethod({
+                    authToken: input.authToken || ctx.providerToken || '',
+                    providerType: input.providerType!,
+                });
+                hold = await findPendingEscrowHoldByAuthProvider(authProvider, 'hold');
+            }
+            return { hold: hold ? serializeHold(hold) : null };
+        }),
+
+    cancelRecovery: didAndChallengeRoute
+        .meta({ openapi: { method: 'POST', path: '/keys/escrow/cancel', tags: ['Keys'] } })
+        .input(AuthInputValidator.strict())
+        .output(successValidator.extend({ cancelled: z.boolean() }))
+        .mutation(async ({ input, ctx }) => {
+            const { authProvider } = await verifyAndGetContactMethod(input);
+            const userKey = await requireUserKey(authProvider);
+            assertDidOwner(userKey, ctx.user.did);
+            const pending = await findPendingEscrowHoldByAuthProvider(authProvider, 'hold');
+            const hold = pending && (await cancelEscrowHold(pending._id, 'did'));
+            if (hold) {
+                await cancelHoldInEnclave(hold, userKey);
+                await notifyEscrowHoldEvent({
+                    kind: 'cancelled',
+                    hold,
+                    userKey,
+                    tenant: ctx.tenant,
+                });
+            }
+            return { success: true as const, cancelled: Boolean(hold) };
+        }),
+
+    // No DID auth is possible from an email link, so this is deliberately an
+    // openRoute guarded only by the single-use cancelToken. Every failure
+    // path — missing hold, wrong token, already used, not pending — returns
+    // the identical { cancelled: false } shape so a link can't be used to
+    // probe hold state (mirrors resumeToken's uniform-failure behaviour in
+    // getStatus/completeRecovery above).
+    cancelRecoveryByLink: openRoute
+        .meta({ openapi: { method: 'POST', path: '/keys/escrow/cancel-link', tags: ['Keys'] } })
+        .input(cancelByLinkInput)
+        .output(z.object({ cancelled: z.boolean() }))
+        .mutation(async ({ input, ctx }) => {
+            await limitCancelLinkAttempts(ctx.clientIp);
+            const hold = await findEscrowHoldById(input.holdId);
+            if (!hold || !escrowCancelTokenMatches(hold, input.token)) return { cancelled: false };
+            const cancelled = await cancelEscrowHoldByCancelToken(
+                hold._id,
+                hashEscrowCancelToken(input.token)
+            );
+            if (!cancelled) return { cancelled: false };
+            const userKey = await findUserKeyByAuthProvider(
+                cancelled.authProvider.type,
+                cancelled.authProvider.id
+            );
+            await cancelHoldInEnclave(cancelled, userKey);
+            if (userKey) {
+                await notifyEscrowHoldEvent({
+                    kind: 'cancelled',
+                    hold: cancelled,
+                    userKey,
+                    tenant: ctx.tenant,
+                });
+            }
+            return { cancelled: true };
+        }),
+
+    completeRecovery: openRoute
+        .meta({ openapi: { method: 'POST', path: '/keys/escrow/complete', tags: ['Keys'] } })
+        .input(
+            resumeInput.extend({
+                pinProof: z
+                    .string()
+                    .regex(/^[0-9a-f]{64}$/i)
+                    .optional(),
+            })
+        )
+        .output(
+            z.object({
+                sealedShare: EscrowEnvelopeValidator,
+                authShare: ServerEncryptedShareValidator,
+                primaryDid: z.string(),
+                shareVersion: z.number(),
+                rebindSessionToken: RecoverySessionTokenValidator,
+            })
+        )
+        .mutation(async ({ input, ctx }) => {
+            if (isEscrowReleaseKillSwitchEnabled()) {
+                throw new TRPCError({
+                    code: 'PRECONDITION_FAILED',
+                    message: killSwitchMessage,
+                });
+            }
+            if (input.pinProof !== undefined) await limitPinCompletion(ctx.clientIp);
+            const hold = await findEscrowHoldById(input.holdId);
+            if (!hold || !resumeTokenMatches(hold, input.resumeToken)) {
+                throw new TRPCError({
+                    code: 'FORBIDDEN',
+                    message: 'This recovery request is invalid.',
+                });
+            }
+            if (hold.status === 'cancelled') {
+                throw new TRPCError({
+                    code: 'FORBIDDEN',
+                    message: 'This recovery request was cancelled.',
+                });
+            }
+            // Legacy Mongo rows can predate the required creation-time record.
+            if (hold.status !== 'pending' || !hold.holdRecord)
+                throw new TRPCError({ code: 'FORBIDDEN', message: invalidMessage });
+            const now = new Date();
+            if (now < hold.releaseAfter) {
+                throw new TRPCError({
+                    code: 'FORBIDDEN',
+                    message: 'This recovery request is still in its waiting period.',
+                });
+            }
+            const userKey = await findUserKeyByAuthProvider(
+                hold.authProvider.type,
+                hold.authProvider.id
+            );
+            if (
+                !userKey?.escrowBlob ||
+                userKey.escrowOptedOutAt ||
+                userKey.escrowBlob.shareVersion !== hold.shareVersion ||
+                !hasConfirmedEscrow(userKey, hold.shareVersion)
+            ) {
+                throw new TRPCError({ code: 'FORBIDDEN', message: invalidMessage });
+            }
+            await assertFreshEscrowBlob(userKey.escrowBlob);
+            const encryptedAuthShare = findAuthShareByVersion(userKey, hold.shareVersion);
+            if (!encryptedAuthShare || !environment.SEED) {
+                throw new TRPCError({ code: 'FORBIDDEN', message: invalidMessage });
+            }
+            const expectedCiphertext = userKey.escrowBlob.envelope.ciphertext;
+            const reserved =
+                hold.releasePolicy === 'pin'
+                    ? await reserveEscrowPinAttempt(
+                          hold.authProvider,
+                          hold.shareVersion,
+                          expectedCiphertext
+                      )
+                    : undefined;
+            if (reserved === null) {
+                const current = await findUserKeyByAuthProvider(
+                    hold.authProvider.type,
+                    hold.authProvider.id
+                );
+                if (
+                    !current?.escrowPin ||
+                    current.escrowPin.disabledAt ||
+                    current.escrowPin.shareVersion !== hold.shareVersion ||
+                    current.shareVersion !== hold.shareVersion ||
+                    current.escrowBlob?.envelope.ciphertext !== expectedCiphertext
+                ) {
+                    throw new TRPCError({
+                        code: 'FORBIDDEN',
+                        message: ESCROW_PIN_UNAVAILABLE_MESSAGE,
+                    });
+                }
+                if (current.escrowPin.failedAttempts >= ESCROW_PIN_MAX_ATTEMPTS) {
+                    throw new TRPCError({
+                        code: 'TOO_MANY_REQUESTS',
+                        message: pinThrottledMessage,
+                    });
+                }
+                throw new TRPCError({
+                    code: 'CONFLICT',
+                    message: 'Recovery state changed; please retry.',
+                });
+            }
+            // Claim the pending hold BEFORE releasing secrets. The enclave receives the
+            // pending snapshot whose CAS we won; transient refusals reopen only our claim.
+            let completed: Awaited<ReturnType<typeof completeEscrowHold>> = null;
+            try {
+                completed = await completeEscrowHold(hold._id);
+                if (!completed) {
+                    throw new TRPCError({
+                        code: 'CONFLICT',
+                        message: 'Recovery state changed; please retry.',
+                    });
+                }
+                // Revalidate after the claim so a rotation/removal cannot release the old snapshot.
+                const current = await findUserKeyByAuthProvider(
+                    hold.authProvider.type,
+                    hold.authProvider.id
+                );
+                if (
+                    !current?.escrowBlob ||
+                    current.escrowOptedOutAt ||
+                    current.shareVersion !== userKey.shareVersion ||
+                    current.escrowBlob.shareVersion !== hold.shareVersion ||
+                    current.escrowBlob.envelope.ciphertext !== expectedCiphertext ||
+                    !hasConfirmedEscrow(current, hold.shareVersion)
+                ) {
+                    throw new TRPCError({ code: 'FORBIDDEN', message: invalidMessage });
+                }
+            } catch (error) {
+                // No enclave evaluation occurred, including when Mongo throws rather
+                // than returning a lost CAS. Refund before any fallible hold cleanup.
+                if (reserved)
+                    await refundEscrowPinAttempt(
+                        hold.authProvider,
+                        hold.shareVersion,
+                        expectedCiphertext
+                    );
+                if (completed) {
+                    await markClaimedEscrowHoldFailed(
+                        hold._id,
+                        'release-failed',
+                        completed.completedAt!
+                    );
+                    await cancelHoldInEnclave(hold, userKey);
+                }
+                throw error;
+            }
+            const release = await enclaveOperation(async () => {
+                try {
+                    return {
+                        result: await getEscrowEnclave().releaseEscrow({
+                            envelope: (reserved ?? userKey).escrowBlob!.envelope,
+                            hold: hold.holdRecord,
+                            clientEphemeralPublicKey: hold.clientEphemeralPublicKey,
+                            expectedDid: userKey.primaryDid,
+                            now,
+                            pinProof: input.pinProof,
+                        }),
+                        mismatch: false as const,
+                    };
+                } catch (error) {
+                    // Keep the typed mismatch inside the wrapper; never expose enclave internals.
+                    if (hold.releasePolicy === 'pin' && error instanceof EscrowPinMismatchError)
+                        return { mismatch: true as const };
+                    if (reserved)
+                        await refundEscrowPinAttempt(
+                            hold.authProvider,
+                            hold.shareVersion,
+                            expectedCiphertext
+                        );
+                    // Policy includes "not yet releasable"; time/ledger/transport
+                    // refusals map to unavailable. Only malformed blobs are terminal.
+                    // Retries still require the enclave's single-use ledger.
+                    if (error instanceof EscrowBlobError) {
+                        await markClaimedEscrowHoldFailed(
+                            hold._id,
+                            'release-failed',
+                            completed.completedAt!
+                        );
+                        await cancelHoldInEnclave(hold, userKey);
+                    } else {
+                        await retryClaimedEscrowHold(hold._id, completed.completedAt!);
+                    }
+                    throw error;
+                }
+            });
+            if (release.mismatch) {
+                const failed = await recordEscrowPinFailure(
+                    hold.authProvider,
+                    hold.shareVersion,
+                    expectedCiphertext
+                );
+                const attemptsRemaining =
+                    ESCROW_PIN_MAX_ATTEMPTS -
+                    (failed?.escrowPin?.failedAttempts ?? reserved!.escrowPin!.failedAttempts);
+                const locked = !!failed?.escrowPin?.disabledAt;
+                const cancelReason = locked ? 'pin-locked' : 'pin-mismatch';
+                await markClaimedEscrowHoldFailed(hold._id, cancelReason, completed.completedAt!);
+                await cancelHoldInEnclave(hold, userKey);
+                await notifyEscrowHoldEvent({
+                    kind: 'cancelled',
+                    hold: {
+                        ...completed,
+                        status: 'cancelled',
+                        cancelledBy: 'system',
+                        cancelReason,
+                        cancelledAt: new Date(),
+                    },
+                    userKey,
+                    tenant: ctx.tenant,
+                });
+                if (locked) {
+                    await lockPin(hold, userKey, ctx.tenant);
+                    throw new TRPCError({
+                        code: 'TOO_MANY_REQUESTS',
+                        message: ESCROW_PIN_LOCKED_MESSAGE,
+                    });
+                }
+                // No structured error-data convention exists: the client parses this exact text.
+                throw new TRPCError({
+                    code: 'FORBIDDEN',
+                    message: escrowPinMismatchMessage(attemptsRemaining),
+                });
+            }
+            const { sealed } = release.result;
+            // A successful evaluation also consumes the lifetime budget; do not
+            // erase other requests' reservations or replenish guesses here.
+            const authShare = await enclaveOperation(async () =>
+                decryptAuthShare(encryptedAuthShare, environment.SEED)
+            );
+            const rebindSessionToken = await createRecoverySession({
+                scope: 'rebind',
+                authProvider: hold.authProvider,
+            });
+            await notifyEscrowHoldEvent({
+                kind: 'completed',
+                hold: completed,
+                userKey,
+                tenant: ctx.tenant,
+            });
+            return {
+                sealedShare: sealed,
+                authShare,
+                primaryDid: userKey.primaryDid,
+                shareVersion: hold.shareVersion,
+                rebindSessionToken,
+            };
+        }),
+});