@learncard/sss-key-manager 0.2.3 → 0.2.4

package/dist/sss-strategy.d.ts

@@ -14,6 +14,15 @@
  */
 import type { SSSKeyDerivationStrategy, EscrowAttestationPolicy } from './types';
 import type { EmailRelayBranding } from './email-relay-crypto';
+/**
+ * OFF by default. Every input to the uncarryable-PIN inference (recovery methods,
+ * share version, PIN state) comes from lca-api, so a compromised API could forge it
+ * for a healthy PIN account and have the client sign away the PIN path (Custard7's
+ * PR #1815 review). With it off the strategy returns `pin-reset-required` and the
+ * app asks the user to set a new PIN. Enabling it needs an independently trustworthy
+ * recovery signal and security sign-off: POST_RECOVERY_ESCROW_REPAIR_DESIGN.md, Q1.
+ */
+export declare const DEFAULT_AUTO_CLEAR_UNCARRYABLE_PIN = false;
 export interface SSSStorageFunctions {
     storeDeviceShare: (share: string, id?: string) => Promise<void>;
     getDeviceShare: (id?: string) => Promise<string | null>;
@@ -31,6 +40,20 @@ export interface SSSStrategyConfig {
     };
     /** Report enrollment failures without logging recovery material. */
     onEscrowError?: (err: unknown) => void;
+    /**
+     * Nitro repair only: when the signed authority still has a PIN but lca-api holds
+     * no PIN to carry (an identity-recovery rebind deleted it), sign a PIN `clear`
+     * instead of a `carry` that lca-api would reject with PRECONDITION_FAILED.
+     * Defaults to {@link DEFAULT_AUTO_CLEAR_UNCARRYABLE_PIN} (off). Do not enable
+     * without security sign-off: POST_RECOVERY_ESCROW_REPAIR_DESIGN.md, open question Q1.
+     */
+    autoClearUncarryablePin?: boolean;
+    /**
+     * Called once after every committed automatic PIN clear
+     * ({@link SSSStrategyConfig.autoClearUncarryablePin}). Must not throw; defaults
+     * to a console warning. Never receives the DID, email or PIN material.
+     */
+    onEscrowPinAutoCleared?: (event: EscrowPinAutoClearedEvent) => void;
     /** Server URL for key share operations */
     serverUrl: string;
     /** Custom storage functions (defaults to IndexedDB) */
@@ -56,6 +79,14 @@ export interface SSSStrategyConfig {
     tenantId?: string;
 }
 export declare const SERVER_REQUEST_TIMEOUT_MS = 30000;
+/** Telemetry for an automatic post-rebind PIN clear. Carries no DID, email or PIN data. */
+export interface EscrowPinAutoClearedEvent {
+    type: 'escrow.pin.auto_cleared';
+    /** Share version the PIN-free enrollment was committed at. */
+    shareVersion: number;
+    /** Share version the signed authority was still active at (pre-rebind). */
+    authorityShareVersion: number | null;
+}
 /** HTTP failure metadata without potentially sensitive server response text. */
 export declare class EscrowRequestError extends Error {
     readonly status: number;

package/dist/sss-strategy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sss-strategy.d.ts","sourceRoot":"","sources":["../src/sss-strategy.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"sss-strategy.d.ts","sourceRoot":"","sources":["../src/sss-strategy.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@learncard/sss-key-manager",
-    "version": "0.2.3",
+    "version": "0.2.4",
     "description": "Shamir Secret Sharing key manager for LearnCard - replaces Web3Auth SFA",
     "main": "./dist/index.js",
     "module": "./dist/sss-key-manager.esm.js",
@@ -39,7 +39,7 @@
         "vitest": "4.1.11"
     },
     "dependencies": {
-        "@learncard/types": "5.23.2",
+        "@learncard/types": "5.24.0",
         "@noble/ed25519": "^2.0.0",
         "@peculiar/x509": "^2.1.0",
         "@scure/bip39": "^1.2.1",

package/src/index.ts

@@ -177,7 +177,11 @@ export {
     EscrowRequestError,
 } from './sss-strategy';
 
-export type { SSSStorageFunctions, SSSStrategyConfig } from './sss-strategy';
+export type {
+    EscrowPinAutoClearedEvent,
+    SSSStorageFunctions,
+    SSSStrategyConfig,
+} from './sss-strategy';
 
 export {
     generateEphemeralKeypair,

package/src/sss-authority.test.ts

@@ -3,6 +3,7 @@ import { afterEach, describe, expect, it, vi } from 'vitest';
 import { getPublicKeyAsync, verifyAsync } from '@noble/ed25519';
 import {
     createSSSStrategy,
+    formatVersionedEmailShare,
     type SSSStorageFunctions,
     type SSSStrategyConfig,
 } from './sss-strategy';
@@ -78,7 +79,8 @@ const frame = (value: Buffer): Buffer => {
     size.writeUInt32BE(value.length);
     return Buffer.concat([size, value]);
 };
-const response = (value: unknown): Response => new Response(JSON.stringify(value), { status: 200 });
+const response = (value: unknown, status = 200): Response =>
+    new Response(JSON.stringify(value), { status });
 
 const setup = async (legacyEnrolled = false) => {
     const pins = [
@@ -191,6 +193,12 @@ const setup = async (legacyEnrolled = false) => {
         snapshotOnly?: boolean;
         legacySnapshot?: boolean;
         releaseDid?: string;
+        failEnrollment?: boolean;
+        missingPinMetadata?: boolean;
+        /** Server predating `priorEscrowEnrollment` on /keys/auth-share. */
+        oldServer?: boolean;
+        /** A compromised lca-api forging post-rebind status for a healthy account. */
+        forgedRebindStatus?: boolean;
     } = {};
     const signHold = async (record: EscrowHoldRecordLike): Promise<EscrowHoldRecordLike> => {
         const h = record.hold;
@@ -230,10 +238,21 @@ const setup = async (legacyEnrolled = false) => {
                     enrolled = false;
                     return response({ shareVersion: version, expectedShareVersionChecked: true });
                 }
+                if (faults.forgedRebindStatus)
+                    return response({
+                        primaryDid: owner.intent.did,
+                        shareVersion: version + 1,
+                        authShare: { encryptedData: authShare, encryptedDek: '', iv: '' },
+                        recoveryMethods: [],
+                        priorEscrowEnrollment: true,
+                        escrowPin: { state: 'none', enabled: false, attemptsRemaining: 0 },
+                    });
                 return response({
                     primaryDid: owner.intent.did,
                     shareVersion: version,
                     authShare: { encryptedData: authShare, encryptedDek: '', iv: '' },
+                    // Mirror lca-api: only confirmed methods are listed; the rebind's
+                    // `pending` escrow method surfaces only as priorEscrowEnrollment.
                     recoveryMethods: enrolled
                         ? [
                               {
@@ -243,6 +262,12 @@ const setup = async (legacyEnrolled = false) => {
                               },
                           ]
                         : [],
+                    ...(faults.oldServer
+                        ? {}
+                        : { priorEscrowEnrollment: !enrolled && !!faults.missingPinMetadata }),
+                    ...(faults.missingPinMetadata
+                        ? { escrowPin: { state: 'none', enabled: false, attemptsRemaining: 0 } }
+                        : {}),
                 });
             }
             if (path === '/keys/escrow/attestation') return response({ attestation: {} });
@@ -271,6 +296,19 @@ const setup = async (legacyEnrolled = false) => {
                 ).toBe(true);
                 expect(signed.intent.expectedEnrollmentVersion).toBe(state.enrollmentVersion);
                 intents.push(signed);
+                if (faults.failEnrollment) throw new Error('Temporary enrollment outage');
+                // Mirror escrow.enroll: rebind removes Mongo metadata, so carry cannot work.
+                if (
+                    faults.missingPinMetadata &&
+                    state.hasPin &&
+                    signed.intent.pinAction === 'keep'
+                ) {
+                    return response(
+                        { message: 'Set or clear your recovery PIN before continuing.' },
+                        412
+                    );
+                }
+                expect(!!body.clearPin).toBe(signed.intent.pinAction === 'clear');
                 let output: EscrowEnvelope | null = null;
                 if (path === '/keys/escrow') {
                     const plaintext = await decryptEscrowBlob(
@@ -462,7 +500,10 @@ const setup = async (legacyEnrolled = false) => {
                             did: faults.releaseDid ?? owner.intent.did,
                             holdId: pendingHold.hold.holdId,
                             shareVersion: version,
-                            recoveryShare: recoveryShares.recoveryShare,
+                            recoveryShare: state.envelope
+                                ? (await decryptEscrowBlob(state.envelope, keys.privateKey))
+                                      .recoveryShare
+                                : recoveryShares.recoveryShare,
                         },
                         pendingHold.hold.clientEphemeralPublicKey
                     ),
@@ -473,6 +514,22 @@ const setup = async (legacyEnrolled = false) => {
                 });
             }
             if (path === '/keys/escrow/opt-in') return response({ success: true });
+            if (path === '/keys/recovery-session/recover') {
+                return response({
+                    authShare: { encryptedData: authShare },
+                    primaryDid: owner.intent.did,
+                    rebindSessionToken: 'rebind-session',
+                });
+            }
+            if (path === '/keys/recovery-session/rebind') {
+                enrolled = false;
+                faults.missingPinMetadata = true;
+                authShare = (body.authShare as { encryptedData: string }).encryptedData;
+                return response({
+                    shareVersion: ++version,
+                    recoveryMethodsRequireConfirmation: [],
+                });
+            }
             throw new Error('Unexpected test request');
         })
     );
@@ -508,6 +565,7 @@ const setup = async (legacyEnrolled = false) => {
         identity,
         measurements,
         reload: () => createSSSStrategy(config),
+        emailShare: () => formatVersionedEmailShare(recoveryShares.emailShare, version),
         state: () => state,
         advance: () => {
             version++;
@@ -525,6 +583,324 @@ afterEach(() => {
 });
 
 describe('Nitro recovery initiating-client bindings and measurement rollover', () => {
+    it('retries recovered enrollment with clear-PIN intent after failure before enclave mutation', async () => {
+        const f = await setup();
+        await f.strategy.ensureEscrowEnrollment!({
+            ...f.params,
+            options: { ...f.params.options, pin: '135790' },
+        });
+        expect(f.state()).toMatchObject({ status: 'active', hasPin: true });
+        const hold = await f.strategy.startEscrowRecovery!({
+            recoverySessionToken: 'otp-session',
+            expectedDid: owner.intent.did,
+        });
+        await f.strategy.executeRecovery({
+            token: '',
+            providerType: 'firebase',
+            input: { method: 'escrow', ...hold, resumeToken: hold.resumeToken! },
+            didFromPrivateKey: async () => owner.intent.did,
+        });
+        f.faults.failEnrollment = true;
+        await f.strategy.completeIdentityRecovery!(f.params);
+        expect(f.intents.at(-1)?.intent).toMatchObject({ action: 'replace', pinAction: 'clear' });
+        expect(f.state()).toMatchObject({ status: 'active', hasPin: true });
+        const writes = f.calls.filter(call => call === 'PUT:/keys/auth-share').length;
+        f.faults.failEnrollment = false;
+        await expect(
+            f.strategy.ensureEscrowEnrollment!({
+                ...f.params,
+                options: { ...f.params.options, clearPin: true },
+            })
+        ).resolves.toMatchObject({ enrolled: true });
+        expect(f.intents.at(-1)?.intent).toMatchObject({ action: 'replace', pinAction: 'clear' });
+        expect(f.state()).toMatchObject({ status: 'active', hasPin: false });
+        expect(f.calls.filter(call => call === 'PUT:/keys/auth-share')).toHaveLength(writes);
+    });
+    it('treats a successful recovered clear-PIN enrollment as satisfying the repair', async () => {
+        const f = await setup();
+        await f.strategy.ensureEscrowEnrollment!({
+            ...f.params,
+            options: { ...f.params.options, pin: '135790' },
+        });
+        const hold = await f.strategy.startEscrowRecovery!({
+            recoverySessionToken: 'otp-session',
+            expectedDid: owner.intent.did,
+        });
+        await f.strategy.executeRecovery({
+            token: '',
+            providerType: 'firebase',
+            input: { method: 'escrow', ...hold, resumeToken: hold.resumeToken! },
+            didFromPrivateKey: async () => owner.intent.did,
+        });
+        await f.strategy.completeIdentityRecovery!(f.params);
+        expect(f.state()).toMatchObject({ status: 'active', hasPin: false });
+        const writes = f.calls.filter(call => call === 'PUT:/keys/auth-share').length;
+        const intents = f.intents.length;
+        await expect(
+            f.strategy.ensureEscrowEnrollment!({
+                ...f.params,
+                options: { ...f.params.options, clearPin: true },
+            })
+        ).resolves.toMatchObject({ enrolled: true, changed: false });
+        expect(f.calls.filter(call => call === 'PUT:/keys/auth-share')).toHaveLength(writes);
+        expect(f.intents).toHaveLength(intents);
+    });
+    it('repairs a prior enrollment after non-escrow identity recovery outside rollout', async () => {
+        const f = await setup();
+        await f.strategy.ensureEscrowEnrollment!({
+            ...f.params,
+            options: { ...f.params.options, pin: '135790' },
+        });
+        const intents = f.intents.length;
+        await f.strategy.prepareIdentityRecovery!({
+            recoverySessionToken: 'session',
+            input: { method: 'email', emailShare: f.emailShare() },
+            didFromPrivateKey: async () => owner.intent.did,
+        });
+        await expect(f.strategy.completeIdentityRecovery!(f.params)).resolves.toMatchObject({
+            escrowEnrolled: false,
+            escrowRecovery: false,
+        });
+        expect(f.intents).toHaveLength(intents);
+        // Outside rollout the verified authority proves prior enrollment, so the
+        // repair still runs and clears the retired PIN instead of carrying it.
+        await expect(
+            f.strategy.ensureEscrowEnrollment!({
+                ...f.params,
+                options: { ...f.params.options, clearPin: true, requirePriorEnrollment: true },
+            })
+        ).resolves.toMatchObject({ enrolled: true });
+        expect(f.intents.at(-1)?.intent).toMatchObject({ action: 'replace', pinAction: 'clear' });
+        expect(f.state()).toMatchObject({ status: 'active', hasPin: false });
+    });
+    const recoverWithFailedDirectEnrollment = async () => {
+        const f = await setup();
+        await f.strategy.ensureEscrowEnrollment!({
+            ...f.params,
+            options: { ...f.params.options, pin: '135790' },
+        });
+        const hold = await f.strategy.startEscrowRecovery!({
+            recoverySessionToken: 'otp-session',
+            expectedDid: owner.intent.did,
+        });
+        await f.strategy.executeRecovery({
+            token: '',
+            providerType: 'firebase',
+            input: { method: 'escrow', ...hold, resumeToken: hold.resumeToken! },
+            didFromPrivateKey: async () => owner.intent.did,
+        });
+        f.faults.failEnrollment = true;
+        await f.strategy.completeIdentityRecovery!(f.params);
+        f.faults.failEnrollment = false;
+        expect(f.state()).toMatchObject({ status: 'active', hasPin: true });
+        return f;
+    };
+    const writes = (f: { calls: string[] }) =>
+        f.calls.filter(call => call === 'PUT:/keys/auth-share').length;
+    it.each([false, true])(
+        'after a reload, asks for a new PIN instead of rotating or signing (outside rollout: %s)',
+        async requirePriorEnrollment => {
+            const f = await recoverWithFailedDirectEnrollment();
+            const intents = f.intents.length;
+            const before = writes(f);
+            await expect(
+                f.reload().ensureEscrowEnrollment!({
+                    ...f.params,
+                    options: {
+                        ...f.params.options,
+                        ...(requirePriorEnrollment ? { requirePriorEnrollment } : {}),
+                    },
+                })
+            ).resolves.toEqual({ enrolled: false, reason: 'pin-reset-required' });
+            expect(f.intents).toHaveLength(intents);
+            expect(writes(f)).toBe(before);
+            expect(f.state()).toMatchObject({ status: 'active', hasPin: true });
+        }
+    );
+    it('lets the user set a new PIN after a rebind left the old one uncarryable', async () => {
+        const f = await recoverWithFailedDirectEnrollment();
+        const intents = f.intents.length;
+        await f.reload().setEscrowPin!({ ...f.params, pin: '246813' });
+        expect(f.intents.slice(intents).map(signed => signed.intent)).toEqual([
+            // The authority still has the old PIN, so the user's new PIN is a `change`:
+            // a replace with fresh PIN material that needs no carry source in lca-api.
+            expect.objectContaining({ action: 'replace', pinAction: 'change' }),
+        ]);
+        expect(f.state()).toMatchObject({ status: 'active', hasPin: true });
+    });
+    it('signs nothing for a healthy PIN account when lca-api forges rebind status', async () => {
+        const f = await setup();
+        await f.strategy.ensureEscrowEnrollment!({
+            ...f.params,
+            options: { ...f.params.options, pin: '135790' },
+        });
+        expect(f.state()).toMatchObject({ status: 'active', hasPin: true });
+        const intents = f.intents.length;
+        const before = writes(f);
+        f.faults.forgedRebindStatus = true;
+        await expect(f.reload().ensureEscrowEnrollment!(f.params)).resolves.toEqual({
+            enrolled: false,
+            reason: 'pin-reset-required',
+        });
+        expect(f.intents).toHaveLength(intents);
+        expect(writes(f)).toBe(before);
+        expect(f.state()).toMatchObject({ status: 'active', hasPin: true });
+    });
+    it('still clears on forged status when auto-clear is explicitly enabled (needs security sign-off)', async () => {
+        const f = await setup();
+        await f.strategy.ensureEscrowEnrollment!({
+            ...f.params,
+            options: { ...f.params.options, pin: '135790' },
+        });
+        f.faults.forgedRebindStatus = true;
+        await expect(
+            createSSSStrategy({ ...f.config, autoClearUncarryablePin: true })
+                .ensureEscrowEnrollment!(f.params)
+        ).resolves.toMatchObject({ enrolled: true, pinCleared: 'automatic' });
+        expect(f.intents.at(-1)?.intent).toMatchObject({ action: 'replace', pinAction: 'clear' });
+        expect(f.state()).toMatchObject({ hasPin: false });
+    });
+    it.each([false, true])(
+        'with auto-clear opted in, repairs a recovered PIN account by signing a clear (outside rollout: %s)',
+        async requirePriorEnrollment => {
+            const f = await recoverWithFailedDirectEnrollment();
+            const intents = f.intents.length;
+            // Fresh instance: no unenrolledRotation and no clear-PIN intent from the coordinator.
+            await expect(
+                createSSSStrategy({ ...f.config, autoClearUncarryablePin: true })
+                    .ensureEscrowEnrollment!({
+                    ...f.params,
+                    options: {
+                        ...f.params.options,
+                        ...(requirePriorEnrollment ? { requirePriorEnrollment } : {}),
+                    },
+                })
+            ).resolves.toMatchObject({ enrolled: true, changed: true });
+            expect(f.intents.slice(intents).map(signed => signed.intent)).toEqual([
+                expect.objectContaining({ action: 'replace', pinAction: 'clear' }),
+            ]);
+            expect(f.state()).toMatchObject({ status: 'active', hasPin: false });
+        }
+    );
+    it('reports an automatic clear once, without the DID', async () => {
+        const f = await recoverWithFailedDirectEnrollment();
+        const onEscrowPinAutoCleared = vi.fn();
+        await expect(
+            createSSSStrategy({
+                ...f.config,
+                autoClearUncarryablePin: true,
+                onEscrowPinAutoCleared,
+            }).ensureEscrowEnrollment!(f.params)
+        ).resolves.toEqual({
+            enrolled: true,
+            changed: true,
+            shareVersion: expect.any(Number),
+            pinCleared: 'automatic',
+        });
+        expect(onEscrowPinAutoCleared).toHaveBeenCalledTimes(1);
+        expect(onEscrowPinAutoCleared).toHaveBeenCalledWith({
+            type: 'escrow.pin.auto_cleared',
+            shareVersion: expect.any(Number),
+            authorityShareVersion: expect.any(Number),
+        });
+        expect(JSON.stringify(onEscrowPinAutoCleared.mock.calls)).not.toContain(owner.intent.did);
+    });
+    it('does not report a clear the caller asked for as automatic', async () => {
+        const f = await recoverWithFailedDirectEnrollment();
+        const onEscrowPinAutoCleared = vi.fn();
+        const result = await createSSSStrategy({
+            ...f.config,
+            onEscrowPinAutoCleared,
+        }).ensureEscrowEnrollment!({
+            ...f.params,
+            options: { ...f.params.options, clearPin: true },
+        });
+        expect(result).toMatchObject({ enrolled: true, changed: true });
+        expect(result).not.toHaveProperty('pinCleared');
+        expect(f.intents.at(-1)?.intent).toMatchObject({ pinAction: 'clear' });
+        expect(onEscrowPinAutoCleared).not.toHaveBeenCalled();
+    });
+    it('does not clear automatically without rebind evidence from the authority', async () => {
+        const f = await recoverWithFailedDirectEnrollment();
+        const intents = f.intents.length;
+        const onEscrowPinAutoCleared = vi.fn();
+        // An authority already at the server's share version is no rebind.
+        f.state().shareVersion = (
+            await f.reload().fetchServerKeyStatus(f.params.token, f.params.providerType)
+        ).shareVersion;
+        await expect(
+            createSSSStrategy({
+                ...f.config,
+                autoClearUncarryablePin: true,
+                onEscrowPinAutoCleared,
+            }).ensureEscrowEnrollment!(f.params)
+        ).resolves.toEqual({ enrolled: false, reason: 'pin-reset-required' });
+        expect(f.intents).toHaveLength(intents);
+        expect(onEscrowPinAutoCleared).not.toHaveBeenCalled();
+    });
+    it('does not burn a share version after a reload when the authority read fails', async () => {
+        const f = await recoverWithFailedDirectEnrollment();
+        const writes = f.calls.filter(call => call === 'PUT:/keys/auth-share').length;
+        const intents = f.intents.length;
+        f.faults.snapshotNonce = true;
+        await expect(f.reload().ensureEscrowEnrollment!(f.params)).rejects.toThrow();
+        expect(f.calls.filter(call => call === 'PUT:/keys/auth-share')).toHaveLength(writes);
+        expect(f.intents).toHaveLength(intents);
+    });
+    it('reports a leftover pending escrow method as prior enrollment after a reload', async () => {
+        const f = await recoverWithFailedDirectEnrollment();
+        await expect(f.reload().getEscrowEnrollmentState!(f.params)).resolves.toMatchObject({
+            state: 'not-enrolled',
+            priorEscrowMethod: true,
+        });
+    });
+    it('falls back to the confirmed method list on servers without priorEscrowEnrollment', async () => {
+        const f = await recoverWithFailedDirectEnrollment();
+        f.faults.oldServer = true;
+        const state = await f.reload().getEscrowEnrollmentState!(f.params);
+        expect(state).toMatchObject({ state: 'not-enrolled' });
+        expect(state).not.toHaveProperty('priorEscrowMethod');
+    });
+    it('does not enroll a never-enrolled account through prior-enrollment repair', async () => {
+        const f = await setup();
+        await f.strategy.prepareIdentityRecovery!({
+            recoverySessionToken: 'session',
+            input: { method: 'email', emailShare: f.emailShare() },
+            didFromPrivateKey: async () => owner.intent.did,
+        });
+        await f.strategy.completeIdentityRecovery!(f.params);
+        await expect(
+            f.strategy.ensureEscrowEnrollment!({
+                ...f.params,
+                options: { ...f.params.options, clearPin: true, requirePriorEnrollment: true },
+            })
+        ).resolves.toEqual({ enrolled: false, reason: 'not-enrolled' });
+        expect(f.intents).toHaveLength(0);
+        expect(f.state()).toMatchObject({ status: 'empty' });
+    });
+    it('binds recovery contact into the enrollment intent after identity recovery', async () => {
+        const f = await setup();
+        const hold = await f.strategy.startEscrowRecovery!({
+            recoverySessionToken: 'otp-session',
+            expectedDid: owner.intent.did,
+        });
+        await f.strategy.executeRecovery({
+            token: '',
+            providerType: 'firebase',
+            input: { method: 'escrow', ...hold, resumeToken: hold.resumeToken! },
+            didFromPrivateKey: async () => owner.intent.did,
+        });
+        await f.strategy.completeIdentityRecovery!({
+            ...f.params,
+            options: { recoveryEmail: 'recovered@example.com', recoveryLanguage: 'es' },
+        });
+        expect(f.intents.at(-1)?.intent).toMatchObject({
+            recoveryEmail: 'recovered@example.com',
+            recoveryLanguage: 'es',
+            action: 'enroll',
+        });
+        expect(f.state()).toMatchObject({ status: 'active', hasPin: false });
+    });
     const start = (f: Awaited<ReturnType<typeof setup>>) =>
         f.strategy.startEscrowRecovery!({
             token: 'token',

package/src/sss-strategy.test.ts

@@ -223,6 +223,7 @@ describe('escrow strategy', () => {
                     recoveryMethods: methods,
                     escrowOptedOut: optedOut,
                     escrowPin: {
+                        state: !pinSalt ? 'none' : attemptsRemaining > 0 ? 'enabled' : 'locked',
                         enabled: !!pinSalt && attemptsRemaining > 0,
                         attemptsRemaining,
                         ...(pinSalt ? { salt: pinSalt } : {}),
@@ -740,6 +741,33 @@ describe('escrow strategy', () => {
         expect(blob?.pinVerifier).toBeUndefined();
     });
 
+    it('repairs only a prior enrollment when requirePriorEnrollment is set', async () => {
+        const options = { clearPin: true, requirePriorEnrollment: true };
+        await expect(strategy.ensureEscrowEnrollment!({ ...params, options })).resolves.toEqual({
+            enrolled: false,
+            reason: 'not-enrolled',
+        });
+        expect(version).toBe(1);
+        await strategy.ensureEscrowEnrollment!(params);
+        expect(version).toBe(2);
+        await expect(
+            strategy.ensureEscrowEnrollment!({ ...params, options })
+        ).resolves.toMatchObject({ enrolled: true });
+    });
+
+    it('treats a current PIN-free enrollment as satisfying a clear request', async () => {
+        await strategy.ensureEscrowEnrollment!(params);
+        expect(version).toBe(2);
+        await expect(
+            strategy.ensureEscrowEnrollment!({ ...params, options: { clearPin: true } })
+        ).resolves.toEqual({ enrolled: true, changed: false });
+        expect(version).toBe(2);
+        await strategy.setEscrowPin!({ ...params, pin: '135790' });
+        await strategy.ensureEscrowEnrollment!({ ...params, options: { clearPin: true } });
+        expect(version).toBe(4);
+        expect(blob?.pinVerifier).toBeUndefined();
+    });
+
     it.each(['set', 'clear'])('rejects %s PIN when disabled without opting in', async action => {
         config.escrow!.enabled = false;
         await expect(
@@ -792,7 +820,7 @@ describe('escrow strategy', () => {
     it('recovers with a PIN and rotates to hold-only material', async () => {
         await strategy.setEscrowPin!({ ...params, pin: '135790' });
         const recovered = await recoverPin();
-        expect(recovered).toEqual({ privateKey, did });
+        expect(recovered).toEqual({ privateKey, did, escrowEnrolled: true, escrowRecovery: true });
         expect(version).toBe(3);
         expect(blob?.pinVerifier).toBeUndefined();
         expect(await reconstructFromShares([(await storage.getDeviceShare())!, authShare])).toBe(
@@ -811,7 +839,12 @@ describe('escrow strategy', () => {
         expect(burned).toEqual(['escrow-hold']);
         expect(storage.storeDeviceShare).not.toHaveBeenCalled();
         expect(storage.storeShareVersion).not.toHaveBeenCalled();
-        await expect(recoverPin()).resolves.toEqual({ privateKey, did });
+        await expect(recoverPin()).resolves.toEqual({
+            privateKey,
+            did,
+            escrowEnrolled: true,
+            escrowRecovery: true,
+        });
         const starts = calls.filter(call => call.path === '/keys/escrow/recover');
         const completes = calls.filter(call => call.path === '/keys/escrow/complete');
         expect(starts).toHaveLength(2);
@@ -937,14 +970,18 @@ describe('escrow strategy', () => {
 
     it('round trips real crypto, rebinds and persists a new device share', async () => {
         await strategy.ensureEscrowEnrollment!(params);
+        const complete = vi.spyOn(strategy, 'completeIdentityRecovery');
+        const options = { recoveryEmail: 'owner@example.com', recoveryLanguage: 'es' };
         const previous = await storage.getDeviceShare();
         const start = await strategy.startEscrowRecovery!({ token, providerType });
         const recovered = await strategy.executeRecovery({
             ...params,
+            options,
             input: { method: 'escrow', ...start, resumeToken: start.resumeToken! },
             didFromPrivateKey: async key => (key === privateKey ? did : ''),
         });
         expect(recovered.privateKey === privateKey).toBe(true);
+        expect(complete).toHaveBeenCalledWith(expect.objectContaining({ options }));
         expect((await storage.getDeviceShare()) === previous).toBe(false);
         expect(
             (await reconstructFromShares([(await storage.getDeviceShare())!, authShare])) ===
@@ -2032,6 +2069,8 @@ describe('createSSSStrategy', () => {
             await expect(strategy.completeIdentityRecovery!(fixture.params)).resolves.toEqual({
                 privateKey: fixture.privateKey,
                 did: fixture.did,
+                escrowEnrolled: false,
+                escrowRecovery: false,
             });
             expect(fixture.getRebindCalls()).toBe(1);
             expect(vi.mocked(storage.storeDeviceShare).mock.calls.slice(writes)).toEqual([