@learncard/lca-api-service 1.6.1 → 1.6.3

package/src/routes/escrow.ts

@@ -5,7 +5,13 @@ import {
     AuthorityHoldReceiptValidator,
     AuthorityStateResponseValidator,
     SignedEnrollmentIntentValidator,
+    type AuthorityMutationResult,
 } from '../services/escrow-enclave/authorityContract';
+import { escrowBlobIdentity } from '../services/escrow-enclave/blobIdentity';
+import {
+    isDefiniteAuthorityRefusal,
+    settleEscrowEnrollmentLease,
+} from '../services/escrow-enclave/enrollmentLease';
 import { z } from 'zod';
 import { TRPCError } from '@trpc/server';
 import { ESCROW_PIN_MAX_ATTEMPTS } from '@learncard/sss-key-manager';
@@ -29,7 +35,13 @@ import {
     EscrowBlobValidator,
     EscrowPinSaltValidator,
     reserveEscrowPinAttempt,
+    releaseEscrowPinCompare,
     refundEscrowPinAttempt,
+    claimEscrowEnrollmentLease,
+    commitEscrowEnrollmentLease,
+    releaseEscrowEnrollmentLease,
+    ESCROW_ENROLLMENT_LEASE_TTL_MS,
+    type EscrowEnrollmentLease,
     recordEscrowPinFailure,
     disableEscrowPin,
     markClaimedEscrowHoldFailed,
@@ -61,6 +73,7 @@ import {
     type EscrowHold,
     type MongoUserKeyType,
     type AuthProviderMapping,
+    getSecurityEpoch,
 } from '@models';
 import {
     AuthInputValidator,
@@ -69,7 +82,8 @@ import {
     verifyAndGetContactMethod,
     requireUserKey,
     assertDidOwner,
-    requireRecoverySession,
+    requireRecoverySessionRecord,
+    getRecoverySessionEpoch,
 } from './keys';
 import {
     getEscrowEnclave,
@@ -93,6 +107,9 @@ const invalidMessage = 'This recovery request is no longer valid.';
 const staleEscrowMessage = 'Automatic recovery needs to be set up again on a signed-in device.';
 // Keep throttling distinct: clients reserve the locked message for lifetime PIN exhaustion.
 const pinThrottledMessage = 'Please wait before trying again.';
+// A PIN-operation lease is held (TOO_MANY_REQUESTS: clients treat it as "try again").
+const escrowBusyMessage = 'Automatic recovery is being updated. Please try again in a moment.';
+const escrowChangedMessage = 'Automatic recovery changed; please refresh.';
 
 // Follow qr-login's Redis INCR/EXPIRE per-IP limiter. keys.ts has only OTP-specific limits.
 const limitPinCompletion = async (
@@ -350,14 +367,114 @@ const removalInput = AuthInputValidator.extend({
 }).strict();
 const removalOutput = successValidator.extend({ receipt: AuthorityCommitValidator.optional() });
 
+/**
+ * Settle a lease left behind by a crashed or lost request before the account is used
+ * again (the "next request touching the account" leg of the reconciliation). A live
+ * lease is returned untouched for the caller to refuse.
+ */
+const settleExpiredEscrowLease = async (
+    authProvider: AuthProviderMapping,
+    userKey: MongoUserKeyType
+): Promise<MongoUserKeyType> => {
+    const lease = userKey.escrowEnrollmentLease;
+    if (!lease || lease.expiresAt > new Date()) return userKey;
+    await enclaveOperation(() =>
+        settleEscrowEnrollmentLease(authProvider, userKey.primaryDid, lease, {
+            releaseIfUncommitted: true,
+        })
+    );
+    return (await findUserKeyByAuthProvider(authProvider.type, authProvider.id)) ?? userKey;
+};
+
+/** Refuse, before the authority is called, while another PIN operation holds the lease. */
+const assertNoLiveEscrowLease = (userKey: MongoUserKeyType): void => {
+    if (userKey.escrowEnrollmentLease)
+        throw new TRPCError({ code: 'CONFLICT', message: escrowBusyMessage });
+};
+
+/**
+ * Send an owner-signed intent to the authority under the account's PIN-operation
+ * lease and persist its result. The lease is claimed first (atomically conditioned on
+ * the blob and PIN the caller validated and on no PIN compare in flight), so no
+ * compare can advance the authority's operation revision while the intent is
+ * evaluated. The final write is conditioned on the lease, not on PIN charges. Any
+ * failure after the authority may have committed is reconciled against its state.
+ */
+const applyEnrollmentIntentUnderLease = async (input: {
+    authProvider: AuthProviderMapping;
+    userKey: MongoUserKeyType;
+    lease: Omit<EscrowEnrollmentLease, 'id' | 'expiresAt' | 'sourceBlobHash'>;
+    requireOptedIn: boolean;
+    apply: () => Promise<AuthorityMutationResult>;
+}): Promise<AuthorityMutationResult> => {
+    const { authProvider, userKey } = input;
+    const lease: EscrowEnrollmentLease = {
+        ...input.lease,
+        id: randomUUID(),
+        expiresAt: new Date(Date.now() + ESCROW_ENROLLMENT_LEASE_TTL_MS),
+        sourceBlobHash: userKey.escrowBlob?.blobHash ?? null,
+    };
+    const claimed = await claimEscrowEnrollmentLease(authProvider, {
+        lease,
+        expectedBlob: userKey.escrowBlob,
+        expectedPin: userKey.escrowPin,
+        requireOptedIn: input.requireOptedIn,
+    });
+    // A guess reserved or resolved since the read, a compare still in flight, or
+    // another lease: nothing has been sent to the authority.
+    if (!claimed) throw new TRPCError({ code: 'CONFLICT', message: escrowChangedMessage });
+    const result = await enclaveOperation(async () => {
+        try {
+            return await input.apply();
+        } catch (error) {
+            // A definite refusal never committed. Anything else (timeout, lost or
+            // malformed response) may have: adopt a visible commit, else keep the
+            // lease until it expires so a late commit is still settled. Even when the
+            // commit is adopted the request still fails: without the authority's
+            // receipt (it refuses a replayed request id) the client cannot verify it,
+            // and re-reads the authority's state instead.
+            if (isDefiniteAuthorityRefusal(error))
+                await releaseEscrowEnrollmentLease(authProvider, lease.id);
+            else
+                await settleEscrowEnrollmentLease(authProvider, userKey.primaryDid, lease, {
+                    releaseIfUncommitted: false,
+                }).catch(() => undefined);
+            throw error;
+        }
+    });
+    const committed = await commitEscrowEnrollmentLease(authProvider, lease, {
+        envelope: result.envelope,
+        authorityGeneration: result.authorityGeneration,
+        enrollmentVersion: result.enrollmentVersion,
+        enrollmentEpoch: result.enrollmentEpoch,
+        receipt: result.receipt,
+    }).catch(() => null);
+    if (committed) return result;
+    // The authority committed but the lease's write missed (lost lease, transient
+    // Mongo failure): converge to the authority rather than leave the old blob.
+    const settled = await settleEscrowEnrollmentLease(authProvider, userKey.primaryDid, lease, {
+        received: result,
+        releaseIfUncommitted: false,
+    }).catch(() => 'kept' as const);
+    if (settled === 'adopted') return result;
+    throw new TRPCError({
+        code: 'CONFLICT',
+        message: 'Automatic recovery changed; refresh its authoritative state.',
+    });
+};
+
 const removeEscrow = async (
     input: z.infer<typeof removalInput>,
     did: string,
     tenant: Context['tenant']
 ): Promise<z.infer<typeof removalOutput>> => {
     const { authProvider } = await verifyAndGetContactMethod(input);
-    const userKey = await requireUserKey(authProvider);
+    let userKey = await requireUserKey(authProvider);
     assertDidOwner(userKey, did);
+    if (isEscrowRemoteMode()) {
+        userKey = await settleExpiredEscrowLease(authProvider, userKey);
+        assertNoLiveEscrowLease(userKey);
+    }
     if (
         input.optOut &&
         !userKey.recoveryMethods.some(
@@ -387,30 +504,41 @@ const removeEscrow = async (
                 code: 'BAD_REQUEST',
                 message: 'Signed disable intent is required.',
             });
-        const result = await enclaveOperation(() =>
-            enclave.applyEnrollmentIntent!({
-                signedIntent: signed,
-                sourceEnvelope: input.sourceEnvelope ?? userKey.escrowBlob?.envelope ?? null,
-                targetEnvelope: null,
-            })
-        );
+        const sourceEnvelope = input.sourceEnvelope ?? userKey.escrowBlob?.envelope ?? null;
+        // Same PIN-operation lease as enroll: a compare cannot land between the intent
+        // and the Mongo clear, and a lost result is reconciled from the authority.
+        const result = await applyEnrollmentIntentUnderLease({
+            authProvider,
+            userKey,
+            lease: {
+                action: 'disable',
+                pinAction: signed.intent.pinAction,
+                pin: 'clear',
+                optOut: input.optOut,
+                shareVersion: userKey.shareVersion,
+                authorityGeneration: signed.intent.authorityGeneration,
+                expectedEnrollmentVersion: signed.intent.expectedEnrollmentVersion,
+                enrollmentEpoch: signed.intent.enrollmentEpoch,
+                measurements: userKey.escrowBlob?.measurements ?? {},
+            },
+            requireOptedIn: false,
+            apply: () =>
+                enclave.applyEnrollmentIntent!({
+                    signedIntent: signed,
+                    sourceEnvelope,
+                    targetEnvelope: null,
+                }),
+        });
         receipt = result.receipt;
     } else if (input.signedIntent)
         throw new TRPCError({
             code: 'PRECONDITION_FAILED',
             message: 'Signed authority operations require remote mode.',
         });
-    const cleared = await clearEscrowByAuthProvider(authProvider, {
-        optOut: input.optOut,
-        ...(isEscrowRemoteMode()
-            ? { expected: { blob: userKey.escrowBlob, pin: userKey.escrowPin } }
-            : {}),
-    });
-    if (!cleared)
-        throw new TRPCError({
-            code: 'CONFLICT',
-            message: 'Automatic recovery changed; please refresh.',
-        });
+    else {
+        const cleared = await clearEscrowByAuthProvider(authProvider, { optOut: input.optOut });
+        if (!cleared) throw new TRPCError({ code: 'CONFLICT', message: escrowChangedMessage });
+    }
     for (const policy of ['hold', 'pin'] as const) {
         const pending = await findPendingEscrowHoldByAuthProvider(authProvider, policy);
         const cancelled = pending && (await cancelEscrowHold(pending._id, 'did'));
@@ -422,6 +550,49 @@ const removeEscrow = async (
     return { success: true, ...(receipt ? { receipt } : {}) };
 };
 
+/**
+ * Validate a same-PIN refresh's `expectedPinCharges` (E) against the current PIN and
+ * convert it to the stored counters for the write's compare-and-set. Rejected with
+ * CONFLICT when a wrong entry or another reservation has landed since the client's
+ * check, so the refresh never wipes a recorded or in-flight guess.
+ *
+ * `wrongAttempts` may be non-zero (own-typos rule, approved 2026-11-03): the client
+ * sends it only when every recorded wrong entry is one it submitted itself in the same
+ * sign-in flow. lca-api cannot tell whose entries they are; it only guarantees that
+ * nothing changed since the client's check, so a foreign entry still blocks the write.
+ */
+const resolveExpectedPinCharges = (
+    input: {
+        pinSalt?: string | undefined;
+        clearPin?: boolean | undefined;
+        expectedPinCharges?: { attemptsRemaining: number; wrongAttempts: number } | undefined;
+    },
+    userKey: MongoUserKeyType
+): { failedAttempts: number; verifiedFailedAttempts: number } | undefined => {
+    const expected = input.expectedPinCharges;
+    if (!expected) return undefined;
+    if (!input.pinSalt || input.clearPin)
+        throw new TRPCError({
+            code: 'BAD_REQUEST',
+            message: 'Invalid automatic recovery material.',
+        });
+    const pin = userKey.escrowPin;
+    const failedAttempts = ESCROW_PIN_MAX_ATTEMPTS - expected.attemptsRemaining;
+    if (
+        failedAttempts < 0 ||
+        expected.wrongAttempts > failedAttempts ||
+        !pin ||
+        pin.disabledAt ||
+        pin.failedAttempts !== failedAttempts ||
+        pin.verifiedFailedAttempts !== expected.wrongAttempts
+    )
+        throw new TRPCError({
+            code: 'CONFLICT',
+            message: 'Recovery PIN attempts changed; please retry.',
+        });
+    return { failedAttempts, verifiedFailedAttempts: expected.wrongAttempts };
+};
+
 export const escrowRouter = t.router({
     getAttestation: openRoute
         .meta({ openapi: { method: 'GET', path: '/keys/escrow/attestation', tags: ['Keys'] } })
@@ -479,6 +650,9 @@ export const escrowRouter = t.router({
             const enclave = getEscrowEnclave();
             if (!isEscrowRemoteMode() || !enclave.getEnrollmentState)
                 throw new TRPCError({ code: 'PRECONDITION_FAILED', message: unavailableMessage });
+            // Clients compare this state with Mongo's blob; settle a crashed lease first so
+            // they see the converged copy. Best effort: the state read below still decides.
+            await settleExpiredEscrowLease(authProvider, userKey).catch(() => undefined);
             const result = await enclaveOperation(() =>
                 enclave.getEnrollmentState!({ expectedDid: ctx.user.did, nonce: input.nonce })
             );
@@ -498,6 +672,19 @@ export const escrowRouter = t.router({
                 clearPin: z.boolean().optional(),
                 signedIntent: SignedEnrollmentIntentValidator.optional(),
                 sourceEnvelope: EscrowEnvelopeValidator.nullable().optional(),
+                /**
+                 * Same-PIN budget refresh after a PIN sign-in (E): the PIN status the
+                 * client saw right after its release. The new PIN is written only while
+                 * the current PIN still shows exactly these charges (no wrong entry and
+                 * no other reservation since), otherwise CONFLICT.
+                 */
+                expectedPinCharges: z
+                    .object({
+                        attemptsRemaining: z.number().int().nonnegative(),
+                        wrongAttempts: z.number().int().nonnegative(),
+                    })
+                    .strict()
+                    .optional(),
             }).strict()
         )
         .output(
@@ -509,8 +696,12 @@ export const escrowRouter = t.router({
         )
         .mutation(async ({ input, ctx }) => {
             const { authProvider } = await verifyAndGetContactMethod(input);
-            const userKey = await requireUserKey(authProvider);
+            let userKey = await requireUserKey(authProvider);
             assertDidOwner(userKey, ctx.user.did);
+            if (isEscrowRemoteMode()) {
+                userKey = await settleExpiredEscrowLease(authProvider, userKey);
+                assertNoLiveEscrowLease(userKey);
+            }
             if (userKey.escrowOptedOutAt) {
                 throw new TRPCError({
                     code: 'CONFLICT',
@@ -523,6 +714,7 @@ export const escrowRouter = t.router({
                     message: 'Key material changed; please retry.',
                 });
             }
+            const expectedPinCharges = resolveExpectedPinCharges(input, userKey);
             if (isEscrowRemoteMode()) {
                 const enclave = getEscrowEnclave();
                 const signed = input.signedIntent;
@@ -574,47 +766,40 @@ export const escrowRouter = t.router({
                     input.enclaveKeyId !== attestation.keyId
                 )
                     throw new TRPCError({ code: 'BAD_REQUEST', message: invalidMessage });
-                const result = await enclaveOperation(() =>
-                    enclave.applyEnrollmentIntent!({
-                        signedIntent: signed,
-                        sourceEnvelope:
-                            input.sourceEnvelope === undefined
-                                ? current.state.envelope
-                                : input.sourceEnvelope,
-                        targetEnvelope: input.envelope,
-                    })
-                );
-                if (!result.envelope)
-                    throw new TRPCError({
-                        code: 'SERVICE_UNAVAILABLE',
-                        message: unavailableMessage,
-                    });
-                const stored = await setEscrowBlobByAuthProvider(
+                // The lease is claimed on the blob and PIN read above, which
+                // `resolveExpectedPinCharges` validated: a same-PIN refresh whose charges
+                // moved since, or that races a compare still in flight, is refused here
+                // with nothing sent to the authority.
+                const result = await applyEnrollmentIntentUnderLease({
                     authProvider,
-                    {
-                        envelope: result.envelope,
-                        enclaveKeyId: result.envelope.keyId,
-                        enclaveMode: 'nitro',
-                        measurements: attestation.measurements,
+                    userKey,
+                    lease: {
+                        action: intent.action,
+                        pinAction: intent.pinAction,
+                        pin: input.pinSalt ? 'fresh' : preservePin ? 'keep' : 'clear',
+                        ...(input.pinSalt ? { pinSalt: input.pinSalt } : {}),
                         shareVersion: input.shareVersion,
-                        createdAt: new Date(),
-                        authorityGeneration: result.authorityGeneration,
-                        enrollmentVersion: result.enrollmentVersion,
-                        commitReceipt: result.receipt,
+                        authorityGeneration: current.state.authorityGeneration,
+                        expectedEnrollmentVersion: current.state.enrollmentVersion,
+                        expectedPinGeneration: current.state.pinGeneration,
+                        enrollmentEpoch: intent.enrollmentEpoch,
+                        measurements: attestation.measurements,
                     },
-                    input.shareVersion,
-                    input.pinSalt ? { salt: input.pinSalt } : undefined,
-                    preservePin && oldBlob && oldPin ? { blob: oldBlob, pin: oldPin } : undefined,
-                    {
-                        enrollmentEpoch: result.enrollmentEpoch,
-                        expectedBlob: oldBlob,
-                        expectedPin: oldPin,
-                    }
-                );
-                if (!stored)
+                    requireOptedIn: true,
+                    apply: () =>
+                        enclave.applyEnrollmentIntent!({
+                            signedIntent: signed,
+                            sourceEnvelope:
+                                input.sourceEnvelope === undefined
+                                    ? current.state.envelope
+                                    : input.sourceEnvelope,
+                            targetEnvelope: input.envelope,
+                        }),
+                });
+                if (!result.envelope)
                     throw new TRPCError({
-                        code: 'CONFLICT',
-                        message: 'Automatic recovery changed; refresh its authoritative state.',
+                        code: 'SERVICE_UNAVAILABLE',
+                        message: unavailableMessage,
                     });
                 return {
                     success: true as const,
@@ -680,7 +865,11 @@ export const escrowRouter = t.router({
                         (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))
+                    // Releases before the PIN was (re-)set do not count: PIN sign-in keeps the
+                    // share version and re-sets the PIN, and that fresh PIN must carry.
+                    !(await hasCompletedEscrowHoldForVersion(authProvider, oldBlob.shareVersion, {
+                        completedAfter: oldPin.enabledAt,
+                    }))
                 ) {
                     try {
                         const carried = await getEscrowEnclave().carryPinVerifier({
@@ -714,7 +903,10 @@ export const escrowRouter = t.router({
                 authProvider,
                 blob,
                 input.shareVersion,
-                input.pinSalt ? { salt: input.pinSalt } : undefined
+                input.pinSalt ? { salt: input.pinSalt } : undefined,
+                undefined,
+                undefined,
+                expectedPinCharges
             );
             if (!stored)
                 throw new TRPCError({
@@ -780,13 +972,17 @@ export const escrowRouter = t.router({
                 });
             }
             let authProvider: AuthProviderMapping;
+            // Epoch of the recovery session, when started from one (lost-login recovery).
+            let recoverSessionEpoch: number | undefined;
             if (input.releasePolicy === 'pin') await limitPinCompletion(ctx.clientIp, 'start');
             if (input.recoverySessionToken !== undefined) {
                 try {
-                    authProvider = await requireRecoverySession(
+                    const session = await requireRecoverySessionRecord(
                         input.recoverySessionToken,
                         'recover'
                     );
+                    authProvider = session.authProvider;
+                    recoverSessionEpoch = getRecoverySessionEpoch(session);
                 } catch (error) {
                     if (!(error instanceof TRPCError) || error.code !== 'UNAUTHORIZED') throw error;
                     throw new TRPCError({ code: 'NOT_FOUND', message: unavailableMessage });
@@ -797,14 +993,25 @@ export const escrowRouter = t.router({
                     providerType: input.providerType!,
                 }));
             }
-            const userKey = await findUserKeyByAuthProvider(authProvider.type, authProvider.id);
+            let userKey = await findUserKeyByAuthProvider(authProvider.type, authProvider.id);
+            // A crashed PIN operation may have committed a new copy at the authority: adopt
+            // it before a hold is bound to the old one.
+            if (userKey && isEscrowRemoteMode())
+                userKey = await settleExpiredEscrowLease(authProvider, userKey);
             if (
                 !userKey?.escrowBlob ||
                 userKey.escrowOptedOutAt ||
-                !hasConfirmedEscrow(userKey, userKey.escrowBlob.shareVersion)
+                !hasConfirmedEscrow(userKey, userKey.escrowBlob.shareVersion) ||
+                // A recovery session minted before a revoke or wiping rebind is stale.
+                (recoverSessionEpoch !== undefined &&
+                    recoverSessionEpoch !== getSecurityEpoch(userKey))
             ) {
                 throw new TRPCError({ code: 'NOT_FOUND', message: unavailableMessage });
             }
+            // A PIN operation is at the authority: a hold created now would be bound to
+            // the copy its intent is replacing. Retryable, nothing created.
+            if (userKey.escrowEnrollmentLease)
+                throw new TRPCError({ code: 'TOO_MANY_REQUESTS', message: escrowBusyMessage });
             if (await hasUnconfirmedEscrowCancellation(userKey.primaryDid)) {
                 throw new TRPCError({
                     code: 'PRECONDITION_FAILED',
@@ -1198,10 +1405,12 @@ export const escrowRouter = t.router({
                     message: 'This recovery request is still in its waiting period.',
                 });
             }
-            const userKey = await findUserKeyByAuthProvider(
+            let userKey = await findUserKeyByAuthProvider(
                 hold.authProvider.type,
                 hold.authProvider.id
             );
+            if (userKey && isEscrowRemoteMode())
+                userKey = await settleExpiredEscrowLease(hold.authProvider, userKey);
             if (
                 !userKey?.escrowBlob ||
                 userKey.escrowOptedOutAt ||
@@ -1210,25 +1419,57 @@ export const escrowRouter = t.router({
             ) {
                 throw new TRPCError({ code: 'FORBIDDEN', message: invalidMessage });
             }
+            // A PIN operation is at the authority: comparing now would move its operation
+            // revision under the intent. Nothing is charged; the client retries.
+            if (hold.releasePolicy === 'pin' && userKey.escrowEnrollmentLease)
+                throw new TRPCError({ code: 'TOO_MANY_REQUESTS', message: escrowBusyMessage });
+            // The authority binds a hold to the exact copy it was created on and refuses
+            // it against any other (a PIN operation committed since the hold started).
+            // Refuse before reserving, so a stale hold never charges a guess Mongo-side
+            // that the authority never counts.
+            if (
+                isEscrowRemoteMode() &&
+                hold.releasePolicy === 'pin' &&
+                hold.holdRecord.hold.blobHash !== escrowBlobIdentity(userKey.escrowBlob.envelope)
+            )
+                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;
+            // Marks this compare in flight until the authority answers, so no
+            // PIN-operation lease can be claimed under it.
+            const compareId = randomUUID();
             const reserved =
                 hold.releasePolicy === 'pin'
                     ? await reserveEscrowPinAttempt(
                           hold.authProvider,
                           hold.shareVersion,
-                          expectedCiphertext
+                          expectedCiphertext,
+                          compareId
                       )
                     : undefined;
+            // Best effort: the authority has answered by now, so a failed release must not
+            // replace the route's own outcome or skip its cleanup. The marker's TTL
+            // stops it blocking a lease for longer than that.
+            const releaseCompare = async (): Promise<void> => {
+                if (reserved)
+                    await releaseEscrowPinCompare(hold.authProvider, compareId).catch(
+                        () => undefined
+                    );
+            };
             if (reserved === null) {
                 const current = await findUserKeyByAuthProvider(
                     hold.authProvider.type,
                     hold.authProvider.id
                 );
+                if (current?.escrowEnrollmentLease)
+                    throw new TRPCError({
+                        code: 'TOO_MANY_REQUESTS',
+                        message: escrowBusyMessage,
+                    });
                 if (
                     !current?.escrowPin ||
                     current.escrowPin.disabledAt ||
@@ -1281,12 +1522,14 @@ export const escrowRouter = t.router({
             } catch (error) {
                 // No enclave evaluation occurred, including when Mongo throws rather
                 // than returning a lost CAS. Refund before any fallible hold cleanup.
-                if (reserved)
+                if (reserved) {
                     await refundEscrowPinAttempt(
                         hold.authProvider,
                         hold.shareVersion,
                         expectedCiphertext
                     );
+                    await releaseCompare();
+                }
                 if (completed) {
                     await markClaimedEscrowHoldFailed(
                         hold._id,
@@ -1323,6 +1566,9 @@ export const escrowRouter = t.router({
                             hold.shareVersion,
                             expectedCiphertext
                         );
+                    // A transport failure may still reach the authority: keep the
+                    // compare marked until its TTL. Any answer settles it now.
+                    if (!(error instanceof EscrowUnavailableError)) await releaseCompare();
                     // 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.
@@ -1345,6 +1591,7 @@ export const escrowRouter = t.router({
                     hold.shareVersion,
                     expectedCiphertext
                 );
+                await releaseCompare();
                 const attemptsRemaining =
                     ESCROW_PIN_MAX_ATTEMPTS -
                     (failed?.escrowPin?.failedAttempts ?? reserved!.escrowPin!.failedAttempts);
@@ -1364,6 +1611,12 @@ export const escrowRouter = t.router({
                     userKey,
                     tenant: ctx.tenant,
                 });
+                // The record changed under this compare (re-enrolled, rotated or disabled
+                // elsewhere), so no wrong entry was recorded for it. Never answer
+                // "Incorrect PIN." here: clients count those as their own recorded entries
+                // (own-typos rule), and an unrecorded one would later excuse a real guess.
+                if (!failed)
+                    throw new TRPCError({ code: 'CONFLICT', message: escrowChangedMessage });
                 if (locked) {
                     await lockPin(hold, userKey, ctx.tenant);
                     throw new TRPCError({
@@ -1377,6 +1630,7 @@ export const escrowRouter = t.router({
                     message: escrowPinMismatchMessage(attemptsRemaining),
                 });
             }
+            await releaseCompare();
             const { sealed } = release.result;
             if (release.result.receipt)
                 await recordEscrowReleaseReceipt(hold._id, release.result.receipt);
@@ -1388,9 +1642,25 @@ export const escrowRouter = t.router({
             const rebindSessionToken = await createRecoverySession({
                 scope: 'rebind',
                 authProvider: hold.authProvider,
+                // Bound to the epoch read above for this release, for every policy: a
+                // revoke or wiping rebind after this point makes the token unusable.
+                securityEpoch: getSecurityEpoch(userKey),
+                // Only a PIN release may sign in without rotating (keys.completePinSignIn).
+                ...(hold.releasePolicy === 'pin'
+                    ? {
+                          origin: 'pin-release' as const,
+                          primaryDid: userKey.primaryDid,
+                          shareVersion: hold.shareVersion,
+                      }
+                    : {}),
             });
+            // A PIN release signs a new device in without signing anything out, so the
+            // owner gets the "Not you? Secure your account" notice instead of the plain
+            // recovery confirmation. Sent here, at the only point the server sees a
+            // successful PIN proof, so the client can neither skip nor forge it. Fail-open
+            // with a bounded budget (notifyEscrowHoldEvent never throws).
             await notifyEscrowHoldEvent({
-                kind: 'completed',
+                kind: hold.releasePolicy === 'pin' ? 'pin-sign-in' : 'completed',
                 hold: completed,
                 userKey,
                 tenant: ctx.tenant,