@learncard/lca-api-service 1.5.1 → 1.5.2

package/src/routes/escrow.ts

@@ -1,4 +1,10 @@
-import { timingSafeEqual, randomUUID } from 'crypto';
+import { timingSafeEqual, randomUUID, randomBytes } from 'crypto';
+import {
+    AuthorityCommitValidator,
+    AuthorityHoldReceiptValidator,
+    AuthorityStateResponseValidator,
+    SignedEnrollmentIntentValidator,
+} from '../services/escrow-enclave/authorityContract';
 import { z } from 'zod';
 import { TRPCError } from '@trpc/server';
 import { ESCROW_PIN_MAX_ATTEMPTS } from '@learncard/sss-key-manager';
@@ -42,10 +48,15 @@ import {
     hasUnconfirmedEscrowCancellation,
     cancelEscrowHoldByCancelToken,
     completeEscrowHold,
+    recordEscrowHoldConfirmation,
+    recordEscrowReleaseReceipt,
     hasCompletedEscrowHoldForVersion,
     expireStaleEscrowHolds,
     hashEscrowResumeToken,
     generateEscrowResumeToken,
+    computeEffectiveReleaseAfter,
+    ESCROW_RELEASE_TIME_MARGIN_MS,
+    EscrowHoldRecordValidator,
     type EscrowHold,
     type MongoUserKeyType,
     type AuthProviderMapping,
@@ -78,9 +89,6 @@ 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.';
 
@@ -192,6 +200,14 @@ const holdStatusValidator = z.object({
     releasePolicy: z.enum(['hold', 'pin']),
     cancelledAt: z.string().optional(),
     completedAt: z.string().optional(),
+    // P9.1 (attack C): lets the client decide whether to show the
+    // code-entry step; `confirmed` only ever appears once `requiresConfirmation` does.
+    requiresConfirmation: z.boolean().optional(),
+    confirmed: z.boolean().optional(),
+    // [D] Opaque enclave-signed SignedHoldRecord (authority/nitro mode only).
+    // The client independently verifies this (verifyEscrowHoldRecord) before
+    // trusting any field inside it — see escrow-authority.ts.
+    holdRecord: EscrowHoldRecordValidator.optional(),
 });
 
 const serializeHold = (hold: EscrowHold): z.infer<typeof holdStatusValidator> => ({
@@ -202,6 +218,10 @@ const serializeHold = (hold: EscrowHold): z.infer<typeof holdStatusValidator> =>
     releasePolicy: hold.releasePolicy ?? 'hold',
     ...(hold.cancelledAt ? { cancelledAt: hold.cancelledAt.toISOString() } : {}),
     ...(hold.completedAt ? { completedAt: hold.completedAt.toISOString() } : {}),
+    ...(hold.requiresConfirmation
+        ? { requiresConfirmation: true, confirmed: Boolean(hold.confirmedAt) }
+        : {}),
+    ...(hold.holdRecord ? { holdRecord: hold.holdRecord } : {}),
 });
 
 const resumeTokenMatches = (hold: EscrowHold, token: string): boolean => {
@@ -317,6 +337,85 @@ const statusInput = z
         { message: 'Provide exactly one identity proof.' }
     );
 
+const removalInput = AuthInputValidator.extend({
+    optOut: z.boolean(),
+    signedIntent: SignedEnrollmentIntentValidator.optional(),
+    sourceEnvelope: EscrowEnvelopeValidator.optional(),
+}).strict();
+const removalOutput = successValidator.extend({ receipt: AuthorityCommitValidator.optional() });
+
+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);
+    assertDidOwner(userKey, 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.',
+        });
+    }
+    let receipt;
+    if (isEscrowRemoteMode()) {
+        const enclave = getEscrowEnclave();
+        const signed = input.signedIntent;
+        if (
+            !signed ||
+            !enclave.applyEnrollmentIntent ||
+            signed.intent.action !== 'disable' ||
+            signed.intent.did !== did ||
+            signed.intent.tenant !== tenant.id
+        )
+            throw new TRPCError({
+                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,
+            })
+        );
+        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.',
+        });
+    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 });
+        }
+    }
+    return { success: true, ...(receipt ? { receipt } : {}) };
+};
+
 export const escrowRouter = t.router({
     getAttestation: openRoute
         .meta({ openapi: { method: 'GET', path: '/keys/escrow/attestation', tags: ['Keys'] } })
@@ -363,6 +462,25 @@ export const escrowRouter = t.router({
             };
         }),
 
+    getAuthorityState: didAndChallengeRoute
+        .meta({ openapi: { method: 'POST', path: '/keys/escrow/authority-state', tags: ['Keys'] } })
+        .input(AuthInputValidator.extend({ nonce: z.string().regex(/^[0-9a-f]{64}$/) }).strict())
+        .output(AuthorityStateResponseValidator)
+        .mutation(async ({ input, ctx }) => {
+            const { authProvider } = await verifyAndGetContactMethod(input);
+            const userKey = await requireUserKey(authProvider);
+            assertDidOwner(userKey, ctx.user.did);
+            const enclave = getEscrowEnclave();
+            if (!isEscrowRemoteMode() || !enclave.getEnrollmentState)
+                throw new TRPCError({ code: 'PRECONDITION_FAILED', message: unavailableMessage });
+            const result = await enclaveOperation(() =>
+                enclave.getEnrollmentState!({ expectedDid: ctx.user.did, nonce: input.nonce })
+            );
+            if (result.state.did !== ctx.user.did || result.state.tenant !== ctx.tenant.id)
+                throw new TRPCError({ code: 'FORBIDDEN', message: invalidMessage });
+            return result;
+        }),
+
     enroll: didAndChallengeRoute
         .meta({ openapi: { method: 'POST', path: '/keys/escrow', tags: ['Keys'] } })
         .input(
@@ -372,9 +490,17 @@ export const escrowRouter = t.router({
                 enclaveKeyId: EscrowBlobValidator.shape.enclaveKeyId,
                 pinSalt: EscrowPinSaltValidator.optional(),
                 clearPin: z.boolean().optional(),
+                signedIntent: SignedEnrollmentIntentValidator.optional(),
+                sourceEnvelope: EscrowEnvelopeValidator.nullable().optional(),
             }).strict()
         )
-        .output(successValidator.extend({ shareVersion: z.number() }))
+        .output(
+            successValidator.extend({
+                shareVersion: z.number(),
+                envelope: EscrowEnvelopeValidator.optional(),
+                receipt: AuthorityCommitValidator.optional(),
+            })
+        )
         .mutation(async ({ input, ctx }) => {
             const { authProvider } = await verifyAndGetContactMethod(input);
             const userKey = await requireUserKey(authProvider);
@@ -391,6 +517,111 @@ export const escrowRouter = t.router({
                     message: 'Key material changed; please retry.',
                 });
             }
+            if (isEscrowRemoteMode()) {
+                const enclave = getEscrowEnclave();
+                const signed = input.signedIntent;
+                if (!signed || !enclave.applyEnrollmentIntent || !enclave.getEnrollmentState)
+                    throw new TRPCError({
+                        code: 'BAD_REQUEST',
+                        message: 'Signed enrollment intent is required.',
+                    });
+                const intent = signed.intent;
+                if (
+                    intent.did !== ctx.user.did ||
+                    intent.tenant !== ctx.tenant.id ||
+                    intent.action === 'disable' ||
+                    intent.shareVersion !== input.shareVersion ||
+                    !!input.pinSalt !==
+                        (intent.pinAction === 'set' || intent.pinAction === 'change') ||
+                    !!input.clearPin !== (intent.pinAction === 'clear')
+                )
+                    throw new TRPCError({ code: 'BAD_REQUEST', message: invalidMessage });
+                const current = await enclaveOperation(() =>
+                    enclave.getEnrollmentState!({
+                        expectedDid: ctx.user.did,
+                        nonce: randomBytes(32).toString('hex'),
+                    })
+                );
+                if (
+                    current.state.enrollmentVersion !== intent.expectedEnrollmentVersion ||
+                    current.state.authorityGeneration !== intent.authorityGeneration
+                )
+                    throw new TRPCError({
+                        code: 'CONFLICT',
+                        message: 'Automatic recovery changed; please refresh.',
+                    });
+                const preservePin = intent.pinAction === 'keep' && current.state.hasPin;
+                const oldBlob = userKey.escrowBlob;
+                const oldPin = userKey.escrowPin;
+                if (
+                    preservePin &&
+                    (!oldBlob || !oldPin || oldBlob.blobHash !== intent.sourceBlobIdentity)
+                )
+                    throw new TRPCError({
+                        code: 'PRECONDITION_FAILED',
+                        message: 'Set or clear your recovery PIN before continuing.',
+                    });
+                const attestation = await enclaveOperation(() => enclave.getAttestation());
+                if (
+                    attestation.mode !== 'nitro' ||
+                    input.envelope.keyId !== attestation.keyId ||
+                    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(
+                    authProvider,
+                    {
+                        envelope: result.envelope,
+                        enclaveKeyId: result.envelope.keyId,
+                        enclaveMode: 'nitro',
+                        measurements: attestation.measurements,
+                        shareVersion: input.shareVersion,
+                        createdAt: new Date(),
+                        authorityGeneration: result.authorityGeneration,
+                        enrollmentVersion: result.enrollmentVersion,
+                        commitReceipt: result.receipt,
+                    },
+                    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)
+                    throw new TRPCError({
+                        code: 'CONFLICT',
+                        message: 'Automatic recovery changed; refresh its authoritative state.',
+                    });
+                return {
+                    success: true as const,
+                    shareVersion: input.shareVersion,
+                    envelope: result.envelope,
+                    receipt: result.receipt,
+                };
+            }
+            if (input.signedIntent)
+                throw new TRPCError({
+                    code: 'PRECONDITION_FAILED',
+                    message: 'Signed authority operations require remote mode.',
+                });
             const attestation = await enclaveOperation(() => getEscrowEnclave().getAttestation());
             if (
                 input.enclaveKeyId !== attestation.keyId ||
@@ -490,42 +721,15 @@ export const escrowRouter = t.router({
     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 };
-        }),
+        .output(removalOutput)
+        .mutation(({ input, ctx }) => removeEscrow(input, ctx.user.did, ctx.tenant)),
+
+    // Signed capabilities and encrypted sources belong in a body, never a DELETE query URL.
+    disable: didAndChallengeRoute
+        .meta({ openapi: { method: 'POST', path: '/keys/escrow/disable', tags: ['Keys'] } })
+        .input(removalInput.extend({ signedIntent: SignedEnrollmentIntentValidator }))
+        .output(removalOutput)
+        .mutation(({ input, ctx }) => removeEscrow(input, ctx.user.did, ctx.tenant)),
 
     optIn: didAndChallengeRoute
         .meta({ openapi: { method: 'POST', path: '/keys/escrow/opt-in', tags: ['Keys'] } })
@@ -544,7 +748,14 @@ export const escrowRouter = t.router({
         .input(startInput)
         .output(
             holdStatusValidator
-                .pick({ holdId: true, requestedAt: true, releaseAfter: true, releasePolicy: true })
+                .pick({
+                    holdId: true,
+                    requestedAt: true,
+                    releaseAfter: true,
+                    releasePolicy: true,
+                    requiresConfirmation: true,
+                    holdRecord: true,
+                })
                 .extend({
                     status: z.literal('pending'),
                     resumeToken: z.string().nullable(),
@@ -654,6 +865,13 @@ export const escrowRouter = t.router({
             }
             const resumeToken = generateEscrowResumeToken();
             const cancelToken = generateEscrowCancelToken();
+            // P9.1 (attack C): `confirmHold` is defined only by the remote
+            // (nitro/authority) backend. A Hold-policy hold there always goes
+            // through the enclave's own code-then-confirmation email flow, so
+            // lca-api's own Mongo-recipient-sourced 'started' notification is
+            // suppressed entirely rather than racing/duplicating it.
+            const isAuthorityManagedHold =
+                input.releasePolicy === 'hold' && Boolean(getEscrowEnclave().confirmHold);
             const { holdRecord } = await enclaveOperation(() =>
                 getEscrowEnclave().createHold({
                     envelope: userKey.escrowBlob!.envelope,
@@ -690,7 +908,8 @@ export const escrowRouter = t.router({
                     clientEphemeralPublicKey: input.clientEphemeralPublicKey,
                     resumeTokenHash: hashEscrowResumeToken(resumeToken),
                     cancelTokenHash: hashEscrowCancelToken(cancelToken),
-                    startedNotificationPending: true,
+                    startedNotificationPending: !isAuthorityManagedHold,
+                    requiresConfirmation: isAuthorityManagedHold,
                     requestIp: ctx.clientIp,
                     tenantId: ctx.tenant?.id,
                 });
@@ -727,13 +946,15 @@ export const escrowRouter = t.router({
                     message: 'Recovery could not be started.',
                 });
             }
-            await notifyEscrowHoldEvent({
-                kind: 'started',
-                hold,
-                userKey,
-                cancelToken,
-                tenant: ctx.tenant,
-            });
+            if (!isAuthorityManagedHold) {
+                await notifyEscrowHoldEvent({
+                    kind: 'started',
+                    hold,
+                    userKey,
+                    cancelToken,
+                    tenant: ctx.tenant,
+                });
+            }
             return {
                 ...serializeHold(hold),
                 status: 'pending' as const,
@@ -742,6 +963,102 @@ export const escrowRouter = t.router({
             };
         }),
 
+    // P9.1 (attack C): no DID session exists yet at this point in the flow
+    // (same stage as completeRecovery) — resumeToken is the only credential.
+    // The enclave is the sole source of truth for the code; this route never
+    // reads or stores it, only relays the guess and its enclave-returned result.
+    confirmRecovery: openRoute
+        .meta({ openapi: { method: 'POST', path: '/keys/escrow/confirm', tags: ['Keys'] } })
+        .input(resumeInput.extend({ code: z.string().regex(/^[0-9]{8}$/) }))
+        .output(successValidator.extend({ receipt: AuthorityHoldReceiptValidator.optional() }))
+        .mutation(async ({ input }) => {
+            if (isEscrowReleaseKillSwitchEnabled()) {
+                throw new TRPCError({ code: 'PRECONDITION_FAILED', message: killSwitchMessage });
+            }
+            const hold = await findEscrowHoldById(input.holdId);
+            if (
+                !hold ||
+                !resumeTokenMatches(hold, input.resumeToken) ||
+                hold.status !== 'pending'
+            ) {
+                throw new TRPCError({ code: 'FORBIDDEN', message: invalidMessage });
+            }
+            const userKey = await findUserKeyByAuthProvider(
+                hold.authProvider.type,
+                hold.authProvider.id
+            );
+            const envelope = hold.enclaveEnvelope ?? userKey?.escrowBlob?.envelope;
+            if (!hold.holdRecord || !envelope) {
+                throw new TRPCError({ code: 'FORBIDDEN', message: invalidMessage });
+            }
+            const confirmHold = getEscrowEnclave().confirmHold;
+            if (!confirmHold) throw new TRPCError({ code: 'FORBIDDEN', message: invalidMessage });
+            const { receipt, confirmedAtMs } = await enclaveOperation(() =>
+                confirmHold({
+                    envelope,
+                    hold: hold.holdRecord!,
+                    clientEphemeralPublicKey: hold.clientEphemeralPublicKey,
+                    expectedDid: hold.primaryDid,
+                    code: input.code,
+                })
+            );
+            // enclaveOperation re-throws on a code mismatch (the enclave
+            // itself returns an error there); reaching this line means the
+            // code matched. releaseAfter is recomputed from the enclave's
+            // own authoritative confirmation time (`confirmedAtMs`), never a
+            // locally observed `now` — a retried confirm (lost response,
+            // idempotent snapshot) must not add another day on top of a
+            // confirmation that already happened [A2].
+            await recordEscrowHoldConfirmation(
+                hold._id,
+                new Date(confirmedAtMs),
+                computeEffectiveReleaseAfter({
+                    confirmedAtMs,
+                    holdDurationMs: hold.holdRecord.holdDurationMs,
+                })
+            );
+            // [D] Returned so the client can verify this confirmation
+            // commits to the SAME hold it started (verifyEscrowHoldConfirmation).
+            return { success: true as const, receipt };
+        }),
+
+    resendRecoveryCode: openRoute
+        .meta({ openapi: { method: 'POST', path: '/keys/escrow/resend', tags: ['Keys'] } })
+        .input(resumeInput)
+        .output(successValidator)
+        .mutation(async ({ input }) => {
+            if (isEscrowReleaseKillSwitchEnabled()) {
+                throw new TRPCError({ code: 'PRECONDITION_FAILED', message: killSwitchMessage });
+            }
+            const hold = await findEscrowHoldById(input.holdId);
+            if (
+                !hold ||
+                !resumeTokenMatches(hold, input.resumeToken) ||
+                hold.status !== 'pending'
+            ) {
+                throw new TRPCError({ code: 'FORBIDDEN', message: invalidMessage });
+            }
+            const userKey = await findUserKeyByAuthProvider(
+                hold.authProvider.type,
+                hold.authProvider.id
+            );
+            const envelope = hold.enclaveEnvelope ?? userKey?.escrowBlob?.envelope;
+            if (!hold.holdRecord || !envelope) {
+                throw new TRPCError({ code: 'FORBIDDEN', message: invalidMessage });
+            }
+            const resendCode = getEscrowEnclave().resendCode;
+            if (!resendCode) throw new TRPCError({ code: 'FORBIDDEN', message: invalidMessage });
+            await enclaveOperation(() =>
+                resendCode({
+                    envelope,
+                    hold: hold.holdRecord!,
+                    clientEphemeralPublicKey: hold.clientEphemeralPublicKey,
+                    expectedDid: hold.primaryDid,
+                })
+            );
+            return { success: true as const };
+        }),
+
     getStatus: openRoute
         .meta({ openapi: { method: 'GET', path: '/keys/escrow/status', tags: ['Keys'] } })
         .input(statusInput)
@@ -973,6 +1290,7 @@ export const escrowRouter = t.router({
                 try {
                     return {
                         result: await getEscrowEnclave().releaseEscrow({
+                            requestId: hold._id,
                             envelope: (reserved ?? userKey).escrowBlob!.envelope,
                             hold: hold.holdRecord,
                             clientEphemeralPublicKey: hold.clientEphemeralPublicKey,
@@ -986,7 +1304,7 @@ export const escrowRouter = t.router({
                     // 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)
+                    if (reserved && hold.holdRecord.hold.policyVersion !== 2)
                         await refundEscrowPinAttempt(
                             hold.authProvider,
                             hold.shareVersion,
@@ -1047,6 +1365,8 @@ export const escrowRouter = t.router({
                 });
             }
             const { sealed } = release.result;
+            if (release.result.receipt)
+                await recordEscrowReleaseReceipt(hold._id, release.result.receipt);
             // A successful evaluation also consumes the lifetime budget; do not
             // erase other requests' reservations or replenish guesses here.
             const authShare = await enclaveOperation(async () =>

package/src/routes/index.ts

@@ -167,7 +167,7 @@ export const createContext = async (
 // request, this strips anything secret-shaped before it can leave the
 // process.
 const SECRET_FIELD_RE =
-    /share|token|seed|recoverykey|blob|envelope|sealed|ephemeral|resumetoken|pinproof|pinverifier/i;
+    /share|token|seed|recoverykey|blob|envelope|sealed|ephemeral|resumetoken|pinproof|pinverifier|signedintent|receipt|authoritystateproof/i;
 
 /**
  * Recursively replaces values whose key matches SECRET_FIELD_RE with

package/src/routes/keys.ts

@@ -349,6 +349,10 @@ export const keysRouter = t.router({
                 recoverySessionToken: RecoverySessionTokenValidator,
                 recoveryMethods: z.array(RecoveryMethodResponseValidator),
                 escrowPin: EscrowPinStatusValidator,
+                // Same source as the key-status `primaryDid` (getAuthShare): lets
+                // the client bind a no-provider Nitro escrow hold start/restart to
+                // the verified account without a signed-in identity proof.
+                primaryDid: z.string().nullable(),
             })
         )
         .mutation(async ({ input }) => {
@@ -407,6 +411,7 @@ export const keysRouter = t.router({
                 recoverySessionToken,
                 recoveryMethods,
                 escrowPin: getEscrowPinStatus(userKey),
+                primaryDid: userKey.primaryDid ?? null,
             };
         }),
 

package/src/services/escrow-enclave/README.md

@@ -25,6 +25,37 @@ PIN holds have zero duration. Mongo remains responsible for single-use/cancellat
 
 ## Nitro requirement
 
+### Authority protocol (PR 2 item e)
+
+Remote enrollment/removal now requires the account's signed intent; failures never
+fall back to unsigned or PIN-less enrollment. `/v1/apply-enrollment` verifies intent
+inside the enclave and returns the persisted, potentially resealed envelope plus a
+commit receipt. Mongo caches that returned envelope and authoritative generation,
+enrollment version and epoch—not the submitted ciphertext or a Mongo-derived epoch.
+Signed disablement uses `POST /keys/escrow/disable` so authorization and ciphertext
+stay in a request body, not DELETE query parameters. The legacy DELETE endpoint
+remains available only to software mode.
+The cache update is conditional; losing it does not roll back the authority commit.
+
+`/v1/enrollment-state` returns fresh nonce-bound signed state. The authenticated API
+route is `POST /keys/escrow/authority-state`; clients must verify the signature and
+nonce against an attested ledger key. API validators check shapes, not enclave trust.
+`/v1/authority-rewrap` requires delegated rewrap authorization. The background job
+reconciles a previously persisted output via fresh state if the earlier response was
+lost. No state is bootstrapped from Mongo or the legacy ledger.
+
+Policy-v2 holds retain the opaque signed record; release and cancellation return
+Commit artifacts. Cancellation confirmation persists that receipt before clearing
+`enclaveCancelPendingAt`. Old pending holds remain cancellable after rotation or
+disablement. Release attempts use a stable hold-bound request ID; ambiguous v2
+evaluations never refund the host's defense-in-depth counter. The authoritative
+counter is always in the enclave's conditional store.
+
+Do not roll out until client signing/verification and the independent authority
+monitor are integrated. Email confirmation remains PR 3; notifications are unchanged.
+
+### Legacy protocol background (unconfigured/compatibility path)
+
 In `remote` mode, the enclave-owned reserve → verify → commit ledger is the
 intended security boundary (`services/escrow-enclave-app/src/policy.rs` `release_pin`
 and `ledger.rs` `verify_pin`), pending full P1.8/P3.3 production wiring. The host-owned