@learncard/sss-key-manager 0.2.0 → 0.2.2

package/src/sss-strategy.ts

@@ -43,6 +43,7 @@ import {
     ESCROW_PIN_LOCKED_MESSAGE,
     ESCROW_PIN_MISMATCH_PATTERN,
     ESCROW_PIN_UNAVAILABLE_MESSAGE,
+    type EscrowRecoveryExpectations,
 } from '@learncard/types';
 import {
     validatePin,
@@ -52,6 +53,19 @@ import {
 } from './escrow-pin';
 import { encryptEscrowBlob, generateEscrowKeyPair, openEscrowRelease } from './escrow-crypto';
 import { verifyEnclaveAttestation } from './escrow-attestation';
+import {
+    createEscrowEnrollmentIntent,
+    resolveEscrowEnrollmentAction,
+    verifyEscrowAuthorityState,
+    verifyEscrowEnrollmentCommit,
+    verifyEscrowHoldRecord,
+    verifyEscrowHoldConfirmation,
+    escrowAuthorityMeasurements,
+    type EscrowHoldRecordLike,
+} from './escrow-authority';
+import type { VerifiedEnclaveIdentity, EscrowAuthorityState } from './escrow-authority.types';
+import { EscrowEvidenceError } from './escrow-authority.types';
+import type { EscrowEnvelope } from './escrow-crypto';
 import type { EmailRelayBranding } from './email-relay-crypto';
 
 import {
@@ -354,6 +368,7 @@ interface IdentityRecoverySessionResponse {
         credentialId?: string;
         shareVersion?: number;
     }>;
+    primaryDid: string | null;
 }
 
 interface IdentityRecoveryMaterialResponse {
@@ -973,8 +988,12 @@ export function createSSSStrategy(config: SSSStrategyConfig): SSSKeyDerivationSt
 
     // Capture before any await (including the rotation lock). A forgotten device
     // must not be restored by a late write or by atomic-update rollback.
-    const guardedStorage = (): SSSStorageFunctions => {
+    const guardedStorage = (): SSSStorageFunctions & { assertCurrent: () => void } => {
         const generation = storageGeneration;
+        const assertCurrent = (): void => {
+            if (generation !== storageGeneration)
+                throw new Error('This recovery request was cancelled.');
+        };
         const write = (operation: () => Promise<void>): Promise<void> => {
             if (generation !== storageGeneration) {
                 return Promise.reject(new Error('This recovery request was cancelled.'));
@@ -983,8 +1002,9 @@ export function createSSSStrategy(config: SSSStrategyConfig): SSSKeyDerivationSt
             localWrites.add(pending);
             return pending.finally(() => localWrites.delete(pending));
         };
-        const guarded: SSSStorageFunctions = {
+        const guarded: SSSStorageFunctions & { assertCurrent: () => void } = {
             ...storage,
+            assertCurrent,
             storeDeviceShare: (share, id) => write(() => storage.storeDeviceShare(share, id)),
             storeShareVersion: (version, id) => write(() => storage.storeShareVersion(version, id)),
             clearAllShares: id => write(() => storage.clearAllShares(id)),
@@ -1054,6 +1074,11 @@ export function createSSSStrategy(config: SSSStrategyConfig): SSSKeyDerivationSt
     } | null = null;
 
     let escrowEnrollmentInFlight: Promise<EscrowEnrollmentResult> | undefined;
+    // A stale-blob repair is attempted at most once per strategy instance
+    // (i.e. once per app session); a failed attempt is logged and left for
+    // the next session rather than retried on every subsequent call.
+    let staleEscrowReenrollAttempted = false;
+    let verifiedEscrowEnvelope: EscrowEnvelope | undefined;
 
     // Material from a rotation whose escrow POST failed. Retained in memory so a
     // retry within this session re-posts instead of burning another share version.
@@ -1141,13 +1166,125 @@ export function createSSSStrategy(config: SSSStrategyConfig): SSSKeyDerivationSt
         }
     };
 
-    const fetchVerifiedEnclaveKey = async (): Promise<{ publicKey: string; keyId: string }> => {
+    const fetchVerifiedEnclaveKey = async (): Promise<VerifiedEnclaveIdentity> => {
         if (!config.escrow?.enabled) throw new Error('Escrow enrollment is disabled');
-        const { attestation } = await escrowRequest<{ attestation: unknown }>('/attestation', {
+        const nonce = crypto.getRandomValues(new Uint8Array(32));
+        const nonceHex = Array.from(nonce, byte => byte.toString(16).padStart(2, '0')).join('');
+        const { attestation } = await escrowRequest<{ attestation: unknown }>(
+            `/attestation?nonce=${nonceHex}`,
+            {
+                method: 'GET',
+                headers: buildHeaders('', undefined, tenantId),
+            }
+        );
+        return verifyEnclaveAttestation(attestation, config.escrow.attestation, nonce);
+    };
+
+    /** Shared by the public `getEscrowRecoveryStatus` and [D]'s internal
+     * confirm-time verification, so both read the enclave-signed
+     * `holdRecord` field via this package's own `EscrowHoldStatus` type
+     * rather than the narrower cross-package `KeyDerivationStrategy`
+     * interface (which never exposes it to generic callers). */
+    const fetchEscrowHoldStatus = async (
+        params:
+            | { holdId: string; resumeToken: string }
+            | { token: string; providerType: AuthProviderType }
+    ): Promise<EscrowHoldStatus | null> => {
+        const query = new URLSearchParams(
+            'holdId' in params ? { holdId: params.holdId } : { providerType: params.providerType }
+        );
+        const secret = 'holdId' in params ? params.resumeToken : params.token;
+        const result = await escrowRequest<{ hold: EscrowHoldStatus | null }>(`/status?${query}`, {
             method: 'GET',
-            headers: buildHeaders('', undefined, tenantId),
+            headers: {
+                ...buildHeaders('', undefined, tenantId),
+                'X-Auth-Token': secret,
+            },
+        });
+        return result.hold;
+    };
+
+    const recoveryExpectations = (
+        holdId: string,
+        expected?: EscrowRecoveryExpectations
+    ): EscrowRecoveryExpectations => {
+        if (
+            !expected ||
+            expected.holdId !== holdId ||
+            expected.tenant !== (tenantId ?? 'learncard') ||
+            !expected.did ||
+            !expected.clientEphemeralPublicKey ||
+            !expected.blobHash ||
+            !expected.authorityGeneration ||
+            !expected.holdDigest ||
+            !expected.ledgerPublicKey ||
+            !expected.keyId
+        )
+            throw new EscrowEvidenceError();
+        // Do not let callers mutate the bindings while attestation/network IO is pending.
+        return { ...expected };
+    };
+
+    const verifyPendingHold = async (
+        status: EscrowHoldStatus,
+        expected: EscrowRecoveryExpectations,
+        identity: VerifiedEnclaveIdentity
+    ): Promise<EscrowHoldRecordLike> => {
+        if (
+            !config.escrow ||
+            identity.mode !== 'nitro' ||
+            !identity.authority ||
+            identity.authority.ledgerPublicKey !== expected.ledgerPublicKey ||
+            ![identity.keyId, ...identity.previousKeyIds].includes(expected.keyId) ||
+            status.holdId !== expected.holdId ||
+            !status.holdRecord
+        )
+            throw new EscrowEvidenceError();
+        const record = status.holdRecord;
+        const verified = await verifyEscrowHoldRecord(record, expected, identity, {
+            historical: true,
+            allowedMeasurements: await escrowAuthorityMeasurements(config.escrow.attestation),
+            authorityGeneration: expected.authorityGeneration,
+        });
+        if (
+            verified.holdDigest !== expected.holdDigest ||
+            verified.receipt.keyId !== expected.keyId
+        )
+            throw new EscrowEvidenceError();
+        return record;
+    };
+
+    const fetchAuthorityState = async (
+        token: string,
+        providerType: AuthProviderType,
+        privateKey: string,
+        did: string,
+        signer: DidAuthVpSigner,
+        identity: VerifiedEnclaveIdentity,
+        assertCurrent: () => void
+    ): Promise<EscrowAuthorityState> => {
+        assertCurrent();
+        if (identity.mode !== 'nitro' || !identity.authority)
+            throw new Error('The enclave does not support verified enrollment.');
+        const nonce = Array.from(crypto.getRandomValues(new Uint8Array(32)), byte =>
+            byte.toString(16).padStart(2, '0')
+        ).join('');
+        const vp = await requestFreshDidAuthVp(serverUrl, privateKey, did, signer, tenantId);
+        assertCurrent();
+        const response = await escrowRequest<unknown>('/authority-state', {
+            method: 'POST',
+            headers: buildHeaders(token, vp, tenantId),
+            body: JSON.stringify({ authToken: token, providerType, nonce }),
         });
-        return verifyEnclaveAttestation(attestation, config.escrow.attestation);
+        const result = await verifyEscrowAuthorityState(
+            response,
+            nonce,
+            tenantId ?? 'learncard',
+            did,
+            identity
+        );
+        assertCurrent();
+        return result;
     };
 
     const enrollEscrow = async (
@@ -1158,19 +1295,59 @@ export function createSSSStrategy(config: SSSStrategyConfig): SSSKeyDerivationSt
         shares: SSSShares,
         shareVersion: number,
         signDidAuthVp?: DidAuthVpSigner,
-        verifiedKey?: { publicKey: string; keyId: string },
+        verifiedKey?: VerifiedEnclaveIdentity,
         pinMaterial?: { pinSalt: string; pinVerifier: string },
-        clearPin = false
+        clearPin = false,
+        assertCurrent = guardedStorage().assertCurrent,
+        // P9.1 (attack C): the device's own authenticated-account email + app
+        // locale, bound into both the blob plaintext and the signed intent for
+        // nitro/authority mode. Kept last (after the long-established
+        // `assertCurrent` position) so existing positional callers that pass
+        // `assertCurrent` explicitly are never silently shifted. Only
+        // included in the blob plaintext when this call will resolve to
+        // enroll/replace (see `willCarryPin` below) — Rust rejects a Carry
+        // target blob whose plaintext already carries either field, since
+        // the enclave always fills them in from the source blob instead.
+        recoveryEmail = '',
+        recoveryLanguage = ''
     ): Promise<void> => {
         if (!config.escrow?.enabled) throw new Error('Escrow enrollment is disabled');
         if (!signDidAuthVp) throw new Error('DID proof signing is required for escrow enrollment');
-        const { publicKey, keyId } = verifiedKey ?? (await fetchVerifiedEnclaveKey());
+        const identity = verifiedKey ?? (await fetchVerifiedEnclaveKey());
+        assertCurrent();
+        const { publicKey, keyId } = identity;
+        const authority =
+            config.escrow.attestation.mode === 'nitro'
+                ? await fetchAuthorityState(
+                      token,
+                      providerType,
+                      privateKey,
+                      primaryDid,
+                      signDidAuthVp,
+                      identity,
+                      assertCurrent
+                  )
+                : undefined;
+        // P9.1 (attack C): calls the SAME `resolveEscrowEnrollmentAction` used
+        // by `createEscrowEnrollmentIntent` below, so the blob PLAINTEXT built
+        // here and the signed intent built later always agree on whether this
+        // is a carry — the enclave rejects a Carry target blob whose
+        // plaintext carries a non-null recoveryEmail/recoveryLanguage.
+        const bindsRecoveryContact =
+            !authority ||
+            resolveEscrowEnrollmentAction(
+                authority,
+                pinMaterial ? 'set' : clearPin ? 'clear' : 'automatic'
+            ).bindsRecoveryContact;
         const envelope = await encryptEscrowBlob(
             {
                 recoveryShare: shares.recoveryShare,
                 did: primaryDid,
                 shareVersion,
                 ...(pinMaterial ? { pinVerifier: pinMaterial.pinVerifier } : {}),
+                ...(authority && recoveryEmail && bindsRecoveryContact
+                    ? { recoveryEmail, recoveryLanguage }
+                    : {}),
             },
             publicKey,
             keyId
@@ -1182,7 +1359,20 @@ export function createSSSStrategy(config: SSSStrategyConfig): SSSKeyDerivationSt
             signDidAuthVp,
             tenantId
         );
-        await escrowRequest('', {
+        const signedIntent = authority
+            ? await createEscrowEnrollmentIntent({
+                  state: authority,
+                  target: envelope,
+                  shareVersion,
+                  privateKey,
+                  pinAction: pinMaterial ? 'set' : clearPin ? 'clear' : 'automatic',
+                  recoveryEmail,
+                  recoveryLanguage,
+              })
+            : undefined;
+        assertCurrent();
+        verifiedEscrowEnvelope = undefined;
+        const response = await escrowRequest<unknown>('', {
             method: 'POST',
             headers: buildHeaders(token, vp, tenantId),
             body: JSON.stringify({
@@ -1192,9 +1382,23 @@ export function createSSSStrategy(config: SSSStrategyConfig): SSSKeyDerivationSt
                 shareVersion,
                 enclaveKeyId: keyId,
                 ...(pinMaterial ? { pinSalt: pinMaterial.pinSalt } : {}),
-                ...(clearPin ? { clearPin: true } : {}),
+                ...((signedIntent ? signedIntent.intent.pinAction === 'clear' : clearPin)
+                    ? { clearPin: true }
+                    : {}),
+                ...(signedIntent
+                    ? { signedIntent, sourceEnvelope: authority?.envelope ?? null }
+                    : {}),
             }),
         });
+        if (signedIntent) {
+            const committed = await verifyEscrowEnrollmentCommit(
+                response,
+                signedIntent.intent,
+                identity
+            );
+            assertCurrent();
+            verifiedEscrowEnvelope = committed.envelope ?? undefined;
+        }
     };
 
     const tryEnrollEscrow = async (...args: Parameters<typeof enrollEscrow>): Promise<void> => {
@@ -1215,11 +1419,15 @@ export function createSSSStrategy(config: SSSStrategyConfig): SSSKeyDerivationSt
     const ensureEscrowEnrollmentUnguarded = async (
         self: SSSKeyDerivationStrategy,
         params: Parameters<NonNullable<SSSKeyDerivationStrategy['ensureEscrowEnrollment']>>[0],
-        storage: SSSStorageFunctions,
-        forceRotate = false
+        storage: SSSStorageFunctions & { assertCurrent: () => void },
+        forceRotate = false,
+        allowDisabledEnrollment = false
     ): Promise<EscrowEnrollmentResult> => {
+        let clearPinForEnrollment = forceRotate;
         if (!config.escrow?.enabled) return { enrolled: false, reason: 'disabled' };
         const pin = params.options?.pin;
+        const recoveryEmail = params.options?.recoveryEmail ?? '';
+        const recoveryLanguage = params.options?.recoveryLanguage ?? '';
         if (pin !== undefined) {
             const validation = validatePin(pin);
             if (!validation.ok)
@@ -1230,10 +1438,9 @@ export function createSSSStrategy(config: SSSStrategyConfig): SSSKeyDerivationSt
                 );
         }
         const status = await self.fetchServerKeyStatus(params.token, params.providerType);
+        storage.assertCurrent();
         if (status.escrowOptedOut) return { enrolled: false, reason: 'opted-out' };
-        if (
-            !forceRotate &&
-            pin === undefined &&
+        let currentlyEnrolled =
             status.shareVersion !== null &&
             status.recoveryMethods.some(
                 method =>
@@ -1242,87 +1449,152 @@ export function createSSSStrategy(config: SSSStrategyConfig): SSSKeyDerivationSt
                     (Boolean(method.confirmedAt) ||
                         ('confirmationStatus' in method &&
                             method.confirmationStatus === 'confirmed'))
-            )
-        )
+            );
+        let verifiedKey: VerifiedEnclaveIdentity | undefined;
+        if (config.escrow.attestation.mode === 'nitro') {
+            if (!status.primaryDid || !params.signDidAuthVp)
+                throw new Error('Owner proof signing is required for escrow enrollment.');
+            verifiedKey = await fetchVerifiedEnclaveKey();
+            const current = await fetchAuthorityState(
+                params.token,
+                params.providerType,
+                params.privateKey,
+                status.primaryDid,
+                params.signDidAuthVp,
+                verifiedKey,
+                storage.assertCurrent
+            );
+            if (current.status === 'disabled') {
+                verifiedEscrowEnvelope = undefined;
+                if (!allowDisabledEnrollment) return { enrolled: false, reason: 'opted-out' };
+                // Explicit enable without a new PIN clears the retired verifier.
+                clearPinForEnrollment ||= current.hasPin && pin === undefined;
+            }
+            currentlyEnrolled =
+                currentlyEnrolled &&
+                current.status === 'active' &&
+                current.shareVersion === status.shareVersion &&
+                current.envelope?.keyId === verifiedKey.keyId;
+            if (currentlyEnrolled) verifiedEscrowEnvelope = current.envelope ?? undefined;
+        }
+        // A confirmed enrollment whose sealed blob no longer matches the active
+        // enclave (P6 mode migration/rollback, or a rotated enclave key) still
+        // needs the same rotation a missing enrollment would get — but only one
+        // automatic attempt per session, so a still-unreachable enclave doesn't
+        // retry on every ensureEscrowEnrollment call within the same session.
+        const repairingStaleBlob =
+            pin === undefined &&
+            !clearPinForEnrollment &&
+            currentlyEnrolled &&
+            !!status.escrowStale &&
+            !staleEscrowReenrollAttempted;
+        if (!clearPinForEnrollment && pin === undefined && currentlyEnrolled && !repairingStaleBlob)
             // Automatic repair preserves current enrollment regardless of PIN status.
             // The enclave can carry an existing verifier when shares rotate.
             return { enrolled: true, changed: false };
+        if (repairingStaleBlob) staleEscrowReenrollAttempted = true;
         if (!status.primaryDid) throw new Error('Cannot enroll escrow without a primary DID');
         if (!params.signDidAuthVp) {
             throw new Error('DID proof signing is required for escrow enrollment');
         }
-        if (
-            !forceRotate &&
-            pin === undefined &&
-            unenrolledRotation &&
-            unenrolledRotation.shareVersion === status.shareVersion &&
-            unenrolledRotation.primaryDid === status.primaryDid
-        ) {
-            const retry = unenrolledRotation;
+        try {
+            if (
+                !clearPinForEnrollment &&
+                pin === undefined &&
+                unenrolledRotation &&
+                unenrolledRotation.shareVersion === status.shareVersion &&
+                unenrolledRotation.primaryDid === status.primaryDid
+            ) {
+                const retry = unenrolledRotation;
+                await enrollEscrow(
+                    params.token,
+                    params.providerType,
+                    params.privateKey,
+                    retry.primaryDid,
+                    retry.shares,
+                    retry.shareVersion,
+                    params.signDidAuthVp,
+                    undefined,
+                    undefined,
+                    retry.clearPin,
+                    storage.assertCurrent,
+                    recoveryEmail,
+                    recoveryLanguage
+                );
+                unenrolledRotation = undefined;
+                return { enrolled: true, changed: true, shareVersion: retry.shareVersion };
+            }
+            // Verify the enclave before rotating: a bad attestation must not burn
+            // a share version (and, repeated, the retained auth-share history).
+            verifiedKey ??= await fetchVerifiedEnclaveKey();
+            storage.assertCurrent();
+            const pinSalt = pin !== undefined ? generatePinSalt() : undefined;
+            const pinMaterial =
+                pin !== undefined && pinSalt !== undefined
+                    ? { pinSalt, pinVerifier: await derivePinProof(pin, pinSalt) }
+                    : undefined;
+            const storageId = activeStorageId;
+            const primaryDid = status.primaryDid;
+            const { shares, shareVersion } = await withShareUpdateLock(storage, storageId, () =>
+                persistSharesWithoutLock(
+                    params.privateKey,
+                    serverUrl,
+                    params.token,
+                    params.providerType,
+                    primaryDid,
+                    storage,
+                    storageId,
+                    undefined,
+                    params.signDidAuthVp,
+                    tenantId
+                )
+            );
+            lastEmailShare = shares.emailShare;
+            lastShareVersion = shareVersion;
+            lastServerSnapshot = {
+                currentVersion: shareVersion,
+                resolvedVersion: shareVersion,
+                authShare: shares.authShare,
+                primaryDid: status.primaryDid,
+            };
+            unenrolledRotation = pinMaterial
+                ? undefined
+                : {
+                      shares,
+                      shareVersion,
+                      primaryDid: status.primaryDid,
+                      clearPin: clearPinForEnrollment,
+                  };
             await enrollEscrow(
                 params.token,
                 params.providerType,
                 params.privateKey,
-                retry.primaryDid,
-                retry.shares,
-                retry.shareVersion,
+                status.primaryDid,
+                shares,
+                shareVersion,
                 params.signDidAuthVp,
-                undefined,
-                undefined,
-                retry.clearPin
+                verifiedKey,
+                pinMaterial,
+                clearPinForEnrollment,
+                storage.assertCurrent,
+                recoveryEmail,
+                recoveryLanguage
             );
             unenrolledRotation = undefined;
-            return { enrolled: true, changed: true, shareVersion: retry.shareVersion };
+            return { enrolled: true, changed: true, shareVersion };
+        } catch (err) {
+            // A background repair the caller never asked for must not surface as
+            // a hard failure (mirrors tryEnrollEscrow's existing swallow-and-report
+            // shape); an explicit not-yet-enrolled/PIN/forced rotation still throws.
+            if (!repairingStaleBlob || config.escrow.attestation.mode === 'nitro') throw err;
+            try {
+                if (config.onEscrowError) config.onEscrowError(err);
+                else console.warn('SSS: escrow enrollment failed');
+            } catch {
+                console.warn('SSS: escrow error reporting failed');
+            }
+            return { enrolled: true, changed: false };
         }
-        // Verify the enclave before rotating: a bad attestation must not burn
-        // a share version (and, repeated, the retained auth-share history).
-        const verifiedKey = await fetchVerifiedEnclaveKey();
-        const pinSalt = pin !== undefined ? generatePinSalt() : undefined;
-        const pinMaterial =
-            pin !== undefined && pinSalt !== undefined
-                ? { pinSalt, pinVerifier: await derivePinProof(pin, pinSalt) }
-                : undefined;
-        const storageId = activeStorageId;
-        const primaryDid = status.primaryDid;
-        const { shares, shareVersion } = await withShareUpdateLock(storage, storageId, () =>
-            persistSharesWithoutLock(
-                params.privateKey,
-                serverUrl,
-                params.token,
-                params.providerType,
-                primaryDid,
-                storage,
-                storageId,
-                undefined,
-                params.signDidAuthVp,
-                tenantId
-            )
-        );
-        lastEmailShare = shares.emailShare;
-        lastShareVersion = shareVersion;
-        lastServerSnapshot = {
-            currentVersion: shareVersion,
-            resolvedVersion: shareVersion,
-            authShare: shares.authShare,
-            primaryDid: status.primaryDid,
-        };
-        unenrolledRotation = pinMaterial
-            ? undefined
-            : { shares, shareVersion, primaryDid: status.primaryDid, clearPin: forceRotate };
-        await enrollEscrow(
-            params.token,
-            params.providerType,
-            params.privateKey,
-            status.primaryDid,
-            shares,
-            shareVersion,
-            params.signDidAuthVp,
-            verifiedKey,
-            pinMaterial,
-            forceRotate
-        );
-        unenrolledRotation = undefined;
-        return { enrolled: true, changed: true, shareVersion };
     };
 
     const recordPromotion =
@@ -1364,6 +1636,7 @@ export function createSSSStrategy(config: SSSStrategyConfig): SSSKeyDerivationSt
         // --- User scoping ---
 
         setActiveUser(userId: string): void {
+            verifiedEscrowEnvelope = undefined;
             if (activeStorageId !== `sss-device-share:${userId}`) storageGeneration++;
             activeStorageId = `sss-device-share:${userId}`;
             lastServerSnapshot = null;
@@ -1425,6 +1698,7 @@ export function createSSSStrategy(config: SSSStrategyConfig): SSSKeyDerivationSt
             }
 
             storageGeneration++;
+            verifiedEscrowEnvelope = undefined;
             await Promise.allSettled(localWrites);
             await clearPendingShareCandidates(storage, storageId);
             return storage.clearAllShares(storageId);
@@ -1740,6 +2014,7 @@ export function createSSSStrategy(config: SSSStrategyConfig): SSSKeyDerivationSt
                 maskedRecoveryEmail: data.maskedRecoveryEmail ?? null,
                 escrowOptedOut: data.escrowOptedOut === true,
                 escrowPin: data.escrowPin,
+                escrowStale: data.escrowStale,
                 sssActivationState: data.sssActivationState ?? 'active',
             };
         },
@@ -1810,24 +2085,80 @@ export function createSSSStrategy(config: SSSStrategyConfig): SSSKeyDerivationSt
             if (!config.escrow?.enabled) return { state: 'disabled' };
             const status = await this.fetchServerKeyStatus(params.token, params.providerType);
             if (status.escrowOptedOut) return { state: 'opted-out', escrowPin: status.escrowPin };
-            const state =
+            const confirmedEscrow = status.recoveryMethods.filter(
+                method =>
+                    method.type === 'escrow' &&
+                    (Boolean(method.confirmedAt) ||
+                        ('confirmationStatus' in method &&
+                            method.confirmationStatus === 'confirmed'))
+            );
+            const enrolled =
                 status.shareVersion !== null &&
-                status.recoveryMethods.some(
-                    method =>
-                        method.type === 'escrow' &&
-                        method.shareVersion === status.shareVersion &&
-                        (Boolean(method.confirmedAt) ||
-                            ('confirmationStatus' in method &&
-                                method.confirmationStatus === 'confirmed'))
-                )
-                    ? 'enrolled'
-                    : 'not-enrolled';
-            return { state, escrowPin: status.escrowPin };
+                confirmedEscrow.some(method => method.shareVersion === status.shareVersion);
+            // Previously enrolled accounts must bypass the new-enrollment rollout
+            // even when a rotation succeeded but resealing the escrow blob failed.
+            if (confirmedEscrow.length > 0 && (!enrolled || status.escrowStale))
+                return {
+                    state: 'stale',
+                    escrowPin: status.escrowPin,
+                    staleReason: status.escrowStale,
+                };
+            return { state: enrolled ? 'enrolled' : 'not-enrolled', escrowPin: status.escrowPin };
         },
 
         async disableEscrowRecovery(params): Promise<void> {
+            const assertCurrent = guardedStorage().assertCurrent;
             const status = await this.fetchServerKeyStatus(params.token, params.providerType);
             if (!status.primaryDid) throw new Error('Cannot disable escrow without a primary DID');
+            if (config.escrow?.attestation.mode === 'nitro') {
+                const identity = await fetchVerifiedEnclaveKey();
+                const current = await fetchAuthorityState(
+                    params.token,
+                    params.providerType,
+                    params.privateKey,
+                    status.primaryDid,
+                    params.signDidAuthVp,
+                    identity,
+                    assertCurrent
+                );
+                if (current.status === 'disabled') {
+                    verifiedEscrowEnvelope = undefined;
+                    return;
+                }
+                const signedIntent = await createEscrowEnrollmentIntent({
+                    state: current,
+                    target: null,
+                    shareVersion: current.shareVersion ?? 0,
+                    privateKey: params.privateKey,
+                    pinAction: 'disable',
+                    // Disable always nulls these server-side regardless of input.
+                    recoveryEmail: '',
+                    recoveryLanguage: '',
+                });
+                const vp = await requestFreshDidAuthVp(
+                    serverUrl,
+                    params.privateKey,
+                    status.primaryDid,
+                    params.signDidAuthVp,
+                    tenantId
+                );
+                assertCurrent();
+                const response = await escrowRequest<unknown>('/disable', {
+                    method: 'POST',
+                    headers: buildHeaders(params.token, vp, tenantId),
+                    body: JSON.stringify({
+                        authToken: params.token,
+                        providerType: params.providerType,
+                        optOut: true,
+                        signedIntent,
+                        sourceEnvelope: current.envelope,
+                    }),
+                });
+                await verifyEscrowEnrollmentCommit(response, signedIntent.intent, identity);
+                assertCurrent();
+                verifiedEscrowEnvelope = undefined;
+                return;
+            }
             const vp = await requestFreshDidAuthVp(
                 serverUrl,
                 params.privateKey,
@@ -1869,16 +2200,30 @@ export function createSSSStrategy(config: SSSStrategyConfig): SSSKeyDerivationSt
                         providerType: params.providerType,
                     }),
                 });
-                return ensureEscrowEnrollmentUnguarded(this, params, storage);
+                return ensureEscrowEnrollmentUnguarded(this, params, storage, false, true);
             });
         },
 
         async setEscrowPin({ pin, ...params }): Promise<void> {
             const storage = guardedStorage();
             const result = await withRotationLock(() =>
-                ensureEscrowEnrollmentUnguarded(this, { ...params, options: { pin } }, storage)
+                // P9.1: preserve the caller's recoveryEmail/recoveryLanguage — do
+                // not replace `params.options` wholesale, or nitro enroll/replace
+                // loses its required recovery contact.
+                ensureEscrowEnrollmentUnguarded(
+                    this,
+                    {
+                        ...params,
+                        options: {
+                            pin,
+                            recoveryEmail: params.options?.recoveryEmail,
+                            recoveryLanguage: params.options?.recoveryLanguage,
+                        },
+                    },
+                    storage
+                )
             );
-            if (!result.enrolled) {
+            if (!result.enrolled || !result.changed) {
                 throw new Error('Automatic recovery is not available for this account.');
             }
         },
@@ -1888,7 +2233,7 @@ export function createSSSStrategy(config: SSSStrategyConfig): SSSKeyDerivationSt
             const result = await withRotationLock(() =>
                 ensureEscrowEnrollmentUnguarded(this, params, storage, true)
             );
-            if (!result.enrolled) {
+            if (!result.enrolled || !result.changed) {
                 throw new Error('Automatic recovery is not available for this account.');
             }
         },
@@ -1911,8 +2256,16 @@ export function createSSSStrategy(config: SSSStrategyConfig): SSSKeyDerivationSt
             }
         },
 
+        getVerifiedEscrowEnvelope(): EscrowEnvelope | null {
+            return verifiedEscrowEnvelope ? { ...verifiedEscrowEnvelope } : null;
+        },
+
         /** Start or explicitly restart a hold with fresh client-bound resume secrets. */
         async startEscrowRecovery(params): Promise<EscrowRecoveryStart> {
+            const expectedDid = params.expectedDid;
+            const nitro = config.escrow?.attestation.mode === 'nitro';
+            if (nitro && (!expectedDid || (params.tenantId ?? tenantId) !== tenantId))
+                throw new EscrowEvidenceError();
             const sessionProof = params.recoverySessionToken !== undefined;
             if (
                 sessionProof
@@ -1942,28 +2295,136 @@ export function createSSSStrategy(config: SSSStrategyConfig): SSSKeyDerivationSt
                 },
                 params.options?.releasePolicy === 'pin'
             );
-            return { ...result, clientEphemeralPrivateKey: pair.privateKey };
+            // [D] Verify the enclave itself committed to creating THIS exact
+            // hold — recipient key, DID and blob identity — before trusting
+            // the response. Skipped for a reported existing hold
+            // (`resumeToken: null`): that response isn't bound to this call's
+            // freshly generated key pair in the first place (see
+            // EscrowRecoveryPanel's `existingHold` display), so there is
+            // nothing of ours to verify it against.
+            let expectations: EscrowRecoveryExpectations | undefined;
+            if (nitro && result.resumeToken !== null) {
+                const identity = await fetchVerifiedEnclaveKey();
+                if (
+                    identity.mode !== 'nitro' ||
+                    !identity.authority ||
+                    !result.holdRecord ||
+                    !expectedDid
+                )
+                    throw new EscrowEvidenceError();
+                const verified = await verifyEscrowHoldRecord(
+                    result.holdRecord,
+                    {
+                        tenant: tenantId ?? 'learncard',
+                        did: expectedDid,
+                        holdId: result.holdId,
+                        clientEphemeralPublicKey: pair.publicKey,
+                        blobHash: result.holdRecord.hold.blobHash,
+                    },
+                    identity
+                );
+                expectations = {
+                    tenant: tenantId ?? 'learncard',
+                    did: expectedDid,
+                    holdId: result.holdId,
+                    clientEphemeralPublicKey: pair.publicKey,
+                    blobHash: result.holdRecord.hold.blobHash,
+                    authorityGeneration: verified.authorityGeneration,
+                    holdDigest: verified.holdDigest,
+                    ledgerPublicKey: identity.authority.ledgerPublicKey,
+                    keyId: verified.receipt.keyId,
+                };
+            }
+            // Never accept a server-supplied expectations object, even in software mode.
+            return { ...result, clientEphemeralPrivateKey: pair.privateKey, expectations };
         },
 
         /** Read hold status; secrets (auth or resume token) never travel in a URL. */
         async getEscrowRecoveryStatus(params): Promise<EscrowHoldStatus | null> {
-            const query = new URLSearchParams(
-                'holdId' in params
-                    ? { holdId: params.holdId }
-                    : { providerType: params.providerType }
-            );
-            const secret = 'holdId' in params ? params.resumeToken : params.token;
-            const result = await escrowRequest<{ hold: EscrowHoldStatus | null }>(
-                `/status?${query}`,
-                {
-                    method: 'GET',
-                    headers: {
-                        ...buildHeaders('', undefined, tenantId),
-                        'X-Auth-Token': secret,
-                    },
+            const expected =
+                config.escrow?.attestation.mode === 'nitro' && 'holdId' in params
+                    ? recoveryExpectations(params.holdId, params.expectations)
+                    : undefined;
+            const status = await fetchEscrowHoldStatus(params);
+            if (expected && status)
+                await verifyPendingHold(status, expected, await fetchVerifiedEnclaveKey());
+            return status;
+        },
+
+        /** Submit the confirmation code emailed by the enclave for an authority-mode hold. */
+        async confirmEscrowRecovery(params): Promise<{ success: true }> {
+            // [D] Fetch and verify the hold record this code is being
+            // confirmed against (the same hold `startEscrowRecovery` already
+            // verified at creation) BEFORE submitting the code, then verify
+            // the confirmation result commits to that SAME hold — a wrong
+            // recipient key, hold id/digest, DID, unsigned/forged record, or
+            // a retry snapshot for a different hold all fail closed here.
+            let pending:
+                | {
+                      identity: VerifiedEnclaveIdentity;
+                      holdRecord: EscrowHoldRecordLike;
+                      expected: EscrowRecoveryExpectations;
+                  }
+                | undefined;
+            if (config.escrow?.attestation.mode === 'nitro') {
+                const expected = recoveryExpectations(params.holdId, params.expectations);
+                if ((params.tenantId ?? tenantId) !== tenantId) throw new EscrowEvidenceError();
+                const identity = await fetchVerifiedEnclaveKey();
+                const status = await fetchEscrowHoldStatus({
+                    holdId: params.holdId,
+                    resumeToken: params.resumeToken,
+                });
+                if (!status?.holdRecord) {
+                    throw new EscrowEvidenceError();
                 }
-            );
-            return result.hold;
+                const holdRecord = await verifyPendingHold(status, expected, identity);
+                pending = { identity, holdRecord, expected };
+            }
+            const confirm = () =>
+                escrowRequest<{ success: true; receipt?: unknown }>('/confirm', {
+                    method: 'POST',
+                    headers: buildHeaders('', undefined, params.tenantId ?? tenantId),
+                    body: JSON.stringify({
+                        holdId: params.holdId,
+                        resumeToken: params.resumeToken,
+                        code: params.code,
+                    }),
+                });
+            const result = await confirm();
+            if (pending) {
+                if (!result.receipt) {
+                    throw new EscrowEvidenceError();
+                }
+                const receipt = await verifyEscrowHoldConfirmation(
+                    result.receipt,
+                    pending.holdRecord,
+                    pending.expected,
+                    pending.identity
+                );
+                // A commit's secret-keyed requestDigest cannot be checked by the
+                // client. Require the idempotent readback snapshot, which exposes
+                // the exact hold digest without exposing an offline code oracle.
+                if (receipt.kind === 'commit') {
+                    const readback = await confirm();
+                    const snapshot = await verifyEscrowHoldConfirmation(
+                        readback.receipt,
+                        pending.holdRecord,
+                        pending.expected,
+                        pending.identity
+                    );
+                    if (snapshot.kind !== 'snapshot') throw new EscrowEvidenceError();
+                }
+            }
+            return { success: true };
+        },
+
+        /** Request a fresh confirmation code for a hold awaiting confirmation. */
+        async resendEscrowRecoveryCode(params): Promise<{ success: true }> {
+            return escrowRequest<{ success: true }>('/resend', {
+                method: 'POST',
+                headers: buildHeaders('', undefined, params.tenantId ?? tenantId),
+                body: JSON.stringify({ holdId: params.holdId, resumeToken: params.resumeToken }),
+            });
         },
 
         /** Cancel a pending hold with a fresh DID-owner proof. */
@@ -2008,9 +2469,23 @@ export function createSSSStrategy(config: SSSStrategyConfig): SSSKeyDerivationSt
                         ? await this.startEscrowRecovery!({
                               token,
                               providerType,
+                              expectedDid: input.expectedDid,
                               options: { releasePolicy: 'pin' },
                           })
                         : input;
+                const expected =
+                    config.escrow?.attestation.mode === 'nitro'
+                        ? recoveryExpectations(start.holdId, start.expectations)
+                        : undefined;
+                if (expected) {
+                    if (!start.resumeToken) throw new EscrowEvidenceError();
+                    const status = await fetchEscrowHoldStatus({
+                        holdId: start.holdId,
+                        resumeToken: start.resumeToken,
+                    });
+                    if (!status) throw new EscrowEvidenceError();
+                    await verifyPendingHold(status, expected, await fetchVerifiedEnclaveKey());
+                }
                 let pinProof: string | undefined;
                 if (input.method === 'escrow-pin') {
                     if (!('pinSalt' in start) || !start.pinSalt || !start.resumeToken)
@@ -2036,6 +2511,11 @@ export function createSSSStrategy(config: SSSStrategyConfig): SSSKeyDerivationSt
                     material.sealedShare,
                     start.clientEphemeralPrivateKey
                 );
+                if (
+                    expected &&
+                    (plaintext.did !== expected.did || plaintext.holdId !== expected.holdId)
+                )
+                    throw new EscrowEvidenceError();
                 if (
                     plaintext.holdId !== start.holdId ||
                     plaintext.did !== material.primaryDid ||
@@ -3073,6 +3553,7 @@ export function createSSSStrategy(config: SSSStrategyConfig): SSSKeyDerivationSt
 
         async cleanup(): Promise<void> {
             storageGeneration++;
+            verifiedEscrowEnvelope = undefined;
             await Promise.allSettled(localWrites);
         },
     };