@learncard/sss-key-manager 0.1.24 → 0.2.0

package/src/sss-strategy.test.ts

@@ -15,25 +15,63 @@
  * - Custom storage injection
  */
 
-import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { describe, it, expect, vi, beforeAll, beforeEach, afterEach } from 'vitest';
 
 import {
     createSSSStrategy,
     formatVersionedEmailShare,
+    IdentityRecoverySessionConsumedError,
     parseVersionedEmailShare,
+    selectRecoveryPhraseChallengeIndices,
+    withRotationLock,
+    readPendingShareCandidates,
+    writePendingShareCandidates,
+    PENDING_WRITE_EXPIRY_MS,
 } from './sss-strategy';
 import { reconstructFromShares } from './sss';
-import { splitAndVerify } from './atomic-operations';
-import { shareToRecoveryPhrase, recoveryPhraseToShare } from './recovery-phrase';
+import { AtomicUpdateError, splitAndVerify, verifyStoredShares } from './atomic-operations';
+import {
+    shareToRecoveryPhrase,
+    recoveryPhraseToShare,
+    buildRecoveryPhraseChallengeOptions,
+} from './recovery-phrase';
+import { bufferToBase64 } from './crypto';
+import { decryptEmailRelayPayload, type EmailRelayEnvelope } from './email-relay-crypto';
 
 import type { SSSStorageFunctions } from './sss-strategy';
 import type { SSSKeyDerivationStrategy } from './types';
+import type { EscrowBlobPlaintext, EscrowReleasePlaintext } from './escrow-crypto';
+import { generateEscrowKeyPair, decryptEscrowBlob, sealEscrowRelease } from './escrow-crypto';
+import * as passkey from './passkey';
+import { derivePinProof } from './escrow-pin';
 
 // ---------------------------------------------------------------------------
 // In-memory storage mock
 // ---------------------------------------------------------------------------
 
 const DEFAULT_KEY = 'device';
+const TEST_RELAY_KEY_ID = 'sss-strategy-test-key';
+let testRelayPublicKey = '';
+let testRelayPrivateKey = '';
+
+beforeAll(async () => {
+    const keyPair = await crypto.subtle.generateKey({ name: 'ECDH', namedCurve: 'P-256' }, true, [
+        'deriveBits',
+    ]);
+    const [publicKey, privateKey] = await Promise.all([
+        crypto.subtle.exportKey('spki', keyPair.publicKey),
+        crypto.subtle.exportKey('pkcs8', keyPair.privateKey),
+    ]);
+
+    testRelayPublicKey = bufferToBase64(publicKey);
+    testRelayPrivateKey = bufferToBase64(privateKey);
+});
+
+const getTestRelayConfig = () => ({
+    escrowRelayPublicKey: testRelayPublicKey,
+    escrowRelayKeyId: TEST_RELAY_KEY_ID,
+    emailBranding: { brandName: 'Test LearnCard', fromDomain: 'example.com' },
+});
 
 const createMemoryStorage = (): SSSStorageFunctions & {
     _store: Map<string, string>;
@@ -58,6 +96,11 @@ const createMemoryStorage = (): SSSStorageFunctions & {
             return store.has(id ?? DEFAULT_KEY);
         }),
 
+        deleteDeviceShare: vi.fn(async (id?: string) => {
+            store.delete(id ?? DEFAULT_KEY);
+            versions.delete(id ?? DEFAULT_KEY);
+        }),
+
         clearAllShares: vi.fn(async (id?: string) => {
             if (id) {
                 store.delete(id);
@@ -82,6 +125,784 @@ const createMemoryStorage = (): SSSStorageFunctions & {
 // Tests
 // ---------------------------------------------------------------------------
 
+describe('escrow strategy', () => {
+    let optedOut: boolean;
+    let optOutStatus: number;
+    const privateKey = 'a'.repeat(64);
+    const did = 'did:key:escrow-test';
+    const token = 'provider-secret';
+    const providerType = 'firebase';
+    const signDidAuthVp = async (_key: string, challenge?: string): Promise<string> =>
+        challenge ? `vp-${challenge}` : 'bootstrap';
+    const params = { token, providerType, privateKey, signDidAuthVp };
+    let storage: ReturnType<typeof createMemoryStorage>;
+    let strategy: SSSKeyDerivationStrategy;
+    let config: Parameters<typeof createSSSStrategy>[0];
+    let version: number;
+    let authShare: string;
+    let blob: EscrowBlobPlaintext | undefined;
+    let enclaveKeys: Awaited<ReturnType<typeof generateEscrowKeyPair>>;
+    let clientPublicKey: string;
+    let holdStarted: boolean;
+    let cancelled: boolean;
+    let attestationFailure: boolean;
+    let overrides: Partial<EscrowReleasePlaintext>;
+    let methods: Array<{
+        type: string;
+        createdAt: string;
+        confirmedAt?: string;
+        shareVersion: number;
+    }>;
+    let calls: Array<{ path: string; init?: RequestInit }>;
+    let pinSalt: string | undefined;
+    let attemptsRemaining: number;
+    let holdNumber: number;
+    let releasePolicy: 'hold' | 'pin';
+    let consumed: boolean;
+    let burned: string[];
+    const hold = () => ({
+        holdId: holdNumber <= 1 ? 'escrow-hold' : `escrow-hold-${holdNumber}`,
+        status: cancelled ? 'cancelled' : 'pending',
+        releasePolicy,
+        requestedAt: '2026-01-01T00:00:00.000Z',
+        releaseAfter: '2026-01-08T00:00:00.000Z',
+    });
+    const json = (value: unknown): Response => new Response(JSON.stringify(value), { status: 200 });
+
+    beforeEach(async () => {
+        optedOut = false;
+        optOutStatus = 200;
+        storage = createMemoryStorage();
+        enclaveKeys = await generateEscrowKeyPair();
+        version = 1;
+        authShare = (await splitAndVerify(privateKey)).shares.authShare;
+        blob = undefined;
+        clientPublicKey = '';
+        holdStarted = false;
+        cancelled = false;
+        attestationFailure = false;
+        overrides = {};
+        methods = [];
+        calls = [];
+        pinSalt = undefined;
+        attemptsRemaining = 10;
+        holdNumber = 0;
+        releasePolicy = 'hold';
+        consumed = false;
+        burned = [];
+        config = {
+            serverUrl: 'https://test.example/api',
+            storage,
+            tenantId: 'test-tenant',
+            escrow: {
+                enabled: true,
+                attestation: { mode: 'software', pinnedPublicKeys: [enclaveKeys.publicKey] },
+            },
+            onEscrowError: vi.fn(),
+        };
+        strategy = createSSSStrategy(config);
+        vi.spyOn(globalThis, 'fetch').mockImplementation(async (url, init) => {
+            const parsed = new URL(String(url));
+            const path = parsed.pathname.replace('/api', '');
+            calls.push({ path, init });
+            const body = JSON.parse(String(init?.body ?? '{}'));
+            if (path === '/keys/challenge') return json({ challenge: String(calls.length) });
+            if (path === '/keys/auth-share') {
+                if (init?.method === 'PUT') {
+                    authShare = body.authShare.encryptedData;
+                    version++;
+                    pinSalt = undefined;
+                    return json({ shareVersion: version });
+                }
+                return json({
+                    primaryDid: did,
+                    authShare: { encryptedData: authShare, encryptedDek: '', iv: '' },
+                    shareVersion: version,
+                    recoveryMethods: methods,
+                    escrowOptedOut: optedOut,
+                    escrowPin: {
+                        enabled: !!pinSalt && attemptsRemaining > 0,
+                        attemptsRemaining,
+                        ...(pinSalt ? { salt: pinSalt } : {}),
+                    },
+                });
+            }
+            if (path === '/keys/recovery' || path === '/keys/recovery/confirm')
+                return json({ success: true });
+            if (path === '/keys/escrow/attestation') {
+                if (attestationFailure) return new Response(null, { status: 503 });
+                return json({
+                    attestation: {
+                        mode: 'software',
+                        keyId: 'test',
+                        publicKey: enclaveKeys.publicKey,
+                        measurements: {},
+                        document: 'e30=',
+                        issuedAt: new Date().toISOString(),
+                    },
+                    holdDurationMs: 604800000,
+                });
+            }
+            if (
+                path === '/keys/escrow/opt-in' ||
+                (path === '/keys/escrow' && init?.method === 'DELETE')
+            ) {
+                expect(new Headers(init?.headers).get('Authorization')).toMatch(/^Bearer vp-/);
+                expect(new Headers(init?.headers).get('X-Tenant-Id')).toBe('test-tenant');
+                if (init?.method === 'DELETE') {
+                    expect(body).toEqual({ authToken: token, providerType, optOut: true });
+                    if (optOutStatus !== 200)
+                        return new Response('sensitive server response', { status: optOutStatus });
+                    optedOut = true;
+                    methods = [];
+                } else {
+                    expect(body).toEqual({ authToken: token, providerType });
+                    optedOut = false;
+                }
+                return json({ success: true });
+            }
+            if (path === '/keys/escrow') {
+                expect(new Headers(init?.headers).get('Authorization')).toMatch(/^Bearer vp-/);
+                blob = await decryptEscrowBlob(body.envelope, enclaveKeys.privateKey);
+                pinSalt = body.pinSalt;
+                attemptsRemaining = 10;
+                expect(blob.did).toBe(did);
+                expect(blob.shareVersion).toBe(version);
+                expect(
+                    (await reconstructFromShares([blob.recoveryShare, authShare])) === privateKey
+                ).toBe(true);
+                methods = [
+                    {
+                        type: 'escrow',
+                        createdAt: new Date().toISOString(),
+                        confirmedAt: new Date().toISOString(),
+                        shareVersion: version,
+                    },
+                ];
+                return json({ success: true, shareVersion: version });
+            }
+            if (path === '/keys/escrow/recover') {
+                const requested = body.releasePolicy ?? 'hold';
+                if (holdStarted && !consumed && !cancelled) {
+                    if (requested === 'hold' && releasePolicy === 'hold')
+                        return json({ ...hold(), resumeToken: null });
+                    burned.push(hold().holdId);
+                }
+                holdNumber++;
+                consumed = false;
+                cancelled = false;
+                releasePolicy = requested;
+                clientPublicKey = body.clientEphemeralPublicKey;
+                holdStarted = true;
+                return json({ ...hold(), resumeToken: 'resume-secret', pinSalt });
+            }
+            if (path === '/keys/escrow/status') {
+                if (!parsed.searchParams.has('holdId')) {
+                    expect(parsed.searchParams.has('authToken')).toBe(false);
+                    expect(new Headers(init?.headers).get('X-Auth-Token') === token).toBe(true);
+                }
+                return json({ hold: holdStarted ? hold() : null });
+            }
+            if (path === '/keys/escrow/cancel') {
+                expect(new Headers(init?.headers).get('Authorization')).toMatch(/^Bearer vp-/);
+                const wasCancelled = cancelled;
+                cancelled = true;
+                return json({ success: true, cancelled: !wasCancelled });
+            }
+            if (path === '/keys/escrow/complete') {
+                if (!blob) throw new Error('Test enrollment missing');
+                if (consumed || body.holdId !== hold().holdId)
+                    return new Response(null, { status: 403 });
+                consumed = true;
+                if (releasePolicy === 'pin' && body.pinProof !== blob.pinVerifier) {
+                    attemptsRemaining--;
+                    burned.push(hold().holdId);
+                    cancelled = true;
+                    return new Response(
+                        JSON.stringify({
+                            message:
+                                attemptsRemaining <= 0
+                                    ? 'Too many incorrect PIN attempts. You can still recover by waiting.'
+                                    : `Incorrect PIN. ${attemptsRemaining} attempts left.`,
+                        }),
+                        { status: attemptsRemaining <= 0 ? 429 : 403 }
+                    );
+                }
+                return json({
+                    sealedShare: await sealEscrowRelease(
+                        { ...blob, holdId: hold().holdId, ...overrides },
+                        clientPublicKey
+                    ),
+                    primaryDid: did,
+                    shareVersion: blob.shareVersion,
+                    authShare: { encryptedData: authShare, encryptedDek: '', iv: '' },
+                    rebindSessionToken: 'rebind-secret',
+                });
+            }
+            if (path === '/keys/recovery-session/rebind') {
+                expect(body.recoverySessionToken === 'rebind-secret').toBe(true);
+                expect(new Headers(init?.headers).get('X-Auth-Token') === token).toBe(true);
+                authShare = body.authShare.encryptedData;
+                version++;
+                return json({ shareVersion: version, recoveryMethodsRequireConfirmation: [] });
+            }
+            throw new Error('Unexpected test request');
+        });
+    });
+    afterEach(() => vi.restoreAllMocks());
+
+    it('serializes concurrent rotations so device and server shares stay paired', async () => {
+        const order: string[] = [];
+        let releaseFirst!: () => void;
+        const gate = new Promise<void>(resolve => {
+            releaseFirst = resolve;
+        });
+        const first = withRotationLock(async () => {
+            order.push('first:start');
+            await gate;
+            order.push('first:end');
+        });
+        const second = withRotationLock(async () => {
+            order.push('second:start');
+            order.push('second:end');
+        });
+        await Promise.resolve();
+        expect(order).toEqual(['first:start']);
+        releaseFirst();
+        await Promise.all([first, second]);
+        expect(order).toEqual(['first:start', 'first:end', 'second:start', 'second:end']);
+    });
+
+    it('keeps the lock usable after a rotation rejects', async () => {
+        await expect(withRotationLock(() => Promise.reject(new Error('boom')))).rejects.toThrow(
+            'boom'
+        );
+        await expect(withRotationLock(async () => 'ok')).resolves.toBe('ok');
+    });
+
+    it('concurrent enrollment repairs share one rotation', async () => {
+        const results = await Promise.all([
+            strategy.ensureEscrowEnrollment!(params),
+            strategy.ensureEscrowEnrollment!(params),
+            strategy.ensureEscrowEnrollment!(params),
+        ]);
+        expect(results).toEqual(Array(3).fill({ enrolled: true, changed: true, shareVersion: 2 }));
+        expect(version).toBe(2);
+        expect(calls.filter(call => call.path === '/keys/escrow').length).toBe(1);
+    });
+
+    it('retries a failed escrow post with the same shares instead of rotating again', async () => {
+        const original = vi.mocked(globalThis.fetch).getMockImplementation()!;
+        let failPost = true;
+        vi.spyOn(globalThis, 'fetch').mockImplementation((url, init) => {
+            const path = new URL(String(url)).pathname.replace('/api', '');
+            if (failPost && path === '/keys/escrow' && init?.method === 'POST') {
+                return Promise.resolve(new Response(null, { status: 503 }));
+            }
+            return original(url, init);
+        });
+        await expect(strategy.ensureEscrowEnrollment!(params)).rejects.toMatchObject({
+            status: 503,
+        });
+        expect(version).toBe(2);
+        expect(blob).toBeUndefined();
+        failPost = false;
+        await expect(strategy.ensureEscrowEnrollment!(params)).resolves.toEqual({
+            enrolled: true,
+            changed: true,
+            shareVersion: 2,
+        });
+        expect(version).toBe(2);
+        expect(blob?.shareVersion).toBe(2);
+    });
+
+    it('opts out with a fresh owner proof', async () => {
+        await strategy.disableEscrowRecovery!(params);
+        expect(optedOut).toBe(true);
+        expect(await strategy.getEscrowEnrollmentState!(params)).toMatchObject({
+            state: 'opted-out',
+        });
+    });
+
+    it('does not rotate or enroll during repeated repairs after opt-out', async () => {
+        await strategy.disableEscrowRecovery!(params);
+        calls = [];
+        for (let attempt = 0; attempt < 7; attempt++) {
+            await expect(strategy.ensureEscrowEnrollment!(params)).resolves.toEqual({
+                enrolled: false,
+                reason: 'opted-out',
+            });
+        }
+        expect(version).toBe(1);
+        expect(
+            calls.every(call => call.path === '/keys/auth-share' && call.init?.method === 'POST')
+        ).toBe(true);
+        expect(blob).toBeUndefined();
+    });
+
+    it('sanitizes malformed successful responses', async () => {
+        const originalFetch = vi.mocked(globalThis.fetch).getMockImplementation()!;
+        vi.spyOn(globalThis, 'fetch').mockImplementation((url, init) =>
+            init?.method === 'DELETE'
+                ? Promise.resolve(new Response('sensitive response', { status: 200 }))
+                : originalFetch(url, init)
+        );
+        await expect(strategy.disableEscrowRecovery!(params)).rejects.toMatchObject({
+            name: 'EscrowRequestError',
+            status: 200,
+            message: 'Escrow request failed',
+        });
+    });
+
+    it('exposes the precondition status without exposing the response body', async () => {
+        optOutStatus = 412;
+        await expect(strategy.disableEscrowRecovery!(params)).rejects.toMatchObject({
+            name: 'EscrowRequestError',
+            status: 412,
+            message: 'Escrow request failed',
+        });
+        expect(optedOut).toBe(false);
+    });
+
+    it('opts in then enrolls and reports the current enrollment state', async () => {
+        optedOut = true;
+        await expect(strategy.enableEscrowRecovery!(params)).resolves.toEqual({
+            enrolled: true,
+            changed: true,
+            shareVersion: 2,
+        });
+        expect(blob).toBeDefined();
+        expect(calls.findIndex(call => call.path === '/keys/escrow/opt-in')).toBeLessThan(
+            calls.findIndex(call => call.path === '/keys/escrow')
+        );
+        expect(await strategy.getEscrowEnrollmentState!(params)).toMatchObject({
+            state: 'enrolled',
+        });
+        methods[0].shareVersion = 1;
+        expect(await strategy.getEscrowEnrollmentState!(params)).toMatchObject({
+            state: 'not-enrolled',
+        });
+        methods[0].shareVersion = version;
+        methods[0].confirmedAt = undefined;
+        expect(await strategy.getEscrowEnrollmentState!(params)).toMatchObject({
+            state: 'not-enrolled',
+        });
+    });
+
+    it('reports missing and disabled enrollment without unnecessary requests', async () => {
+        expect(await strategy.getEscrowEnrollmentState!(params)).toMatchObject({
+            state: 'not-enrolled',
+        });
+        const disabled = createSSSStrategy({ ...config, escrow: undefined });
+        calls = [];
+        expect(await disabled.getEscrowEnrollmentState!(params)).toEqual({ state: 'disabled' });
+        expect(calls).toHaveLength(0);
+    });
+
+    it.each(['phrase', 'passkey'] as const)(
+        'enrolls after %s setup only when enabled',
+        async method => {
+            vi.spyOn(passkey, 'isWebAuthnSupported').mockReturnValue(true);
+            vi.spyOn(passkey, 'createPasskeyCredential').mockResolvedValue({
+                credentialId: 'test-credential',
+                publicKey: 'test-public-key',
+            });
+            vi.spyOn(passkey, 'encryptShareWithPasskey').mockResolvedValue({
+                credentialId: 'test-credential',
+                encryptedData: 'encrypted',
+                iv: 'iv',
+            });
+            await strategy.setupRecoveryMethod!({ ...params, input: { method } });
+            expect(blob).toBeDefined();
+            expect(calls.findIndex(call => call.path === '/keys/escrow')).toBeGreaterThan(
+                calls.findIndex(call => call.path === '/keys/recovery')
+            );
+            config.escrow!.enabled = false;
+            calls = [];
+            await strategy.setupRecoveryMethod!({ ...params, input: { method } });
+            expect(calls.some(call => call.path.startsWith('/keys/escrow'))).toBe(false);
+        }
+    );
+    it('keeps rotation successful and reports enrollment fetch failures', async () => {
+        attestationFailure = true;
+        await expect(
+            strategy.setupRecoveryMethod!({ ...params, input: { method: 'phrase' } })
+        ).resolves.toMatchObject({ method: 'phrase' });
+        expect(version).toBe(2);
+        expect(config.onEscrowError).toHaveBeenCalledOnce();
+    });
+    it('fails closed for explicit enrollment with an untrusted attestation', async () => {
+        config.escrow = { enabled: true, attestation: { mode: 'software', pinnedPublicKeys: [] } };
+        await expect(
+            strategy.setupRecoveryMethod!({ ...params, input: { method: 'escrow' } })
+        ).rejects.toThrow('not trusted');
+        expect(blob).toBeUndefined();
+    });
+    it('reports nitro verification failures without failing phrase setup', async () => {
+        config.escrow = { enabled: true, attestation: { mode: 'nitro', pinnedMeasurements: [] } };
+        await strategy.setupRecoveryMethod!({ ...params, input: { method: 'phrase' } });
+        expect(config.onEscrowError).toHaveBeenCalledWith(
+            expect.objectContaining({
+                message: 'Nitro attestation verification is not implemented yet',
+            })
+        );
+    });
+    it('ensure skips current, rotates stale, and makes no requests when disabled', async () => {
+        await expect(strategy.ensureEscrowEnrollment!(params)).resolves.toEqual({
+            enrolled: true,
+            changed: true,
+            shareVersion: 2,
+        });
+        await expect(strategy.ensureEscrowEnrollment!(params)).resolves.toEqual({
+            enrolled: true,
+            changed: false,
+        });
+        version++;
+        await expect(strategy.ensureEscrowEnrollment!(params)).resolves.toEqual({
+            enrolled: true,
+            changed: true,
+            shareVersion: 4,
+        });
+        config.escrow!.enabled = false;
+        calls = [];
+        await expect(strategy.ensureEscrowEnrollment!(params)).resolves.toEqual({
+            enrolled: false,
+            reason: 'disabled',
+        });
+        expect(calls).toHaveLength(0);
+    });
+    it('requires DID verification before attempting PIN recovery', async () => {
+        await expect(
+            strategy.executeRecovery({
+                token,
+                providerType,
+                input: { method: 'escrow-pin', pin: '135790' },
+            })
+        ).rejects.toThrow('DID verification is required');
+        expect(calls).toHaveLength(0);
+        expect(storage.storeDeviceShare).not.toHaveBeenCalled();
+        expect(storage.storeShareVersion).not.toHaveBeenCalled();
+        expect(storage.clearAllShares).not.toHaveBeenCalled();
+        expect(strategy.hasPendingIdentityRecovery!()).toBe(false);
+    });
+    const recoverPin = (pin = '135790') =>
+        strategy.executeRecovery({
+            ...params,
+            input: { method: 'escrow-pin', pin },
+            didFromPrivateKey: async key => (key === privateKey ? did : ''),
+        });
+
+    it('seals the PIN verifier, preserves current enrollment, and forcibly changes/clears PINs', async () => {
+        await strategy.ensureEscrowEnrollment!({ ...params, options: { pin: '135790' } });
+        expect(blob?.pinVerifier).toBe(await derivePinProof('135790', pinSalt!));
+        expect(await strategy.getEscrowEnrollmentState!(params)).toMatchObject({
+            state: 'enrolled',
+            escrowPin: { enabled: true, salt: pinSalt, attemptsRemaining: 10 },
+        });
+        await strategy.ensureEscrowEnrollment!(params);
+        expect(version).toBe(2);
+        const previousSalt = pinSalt;
+        await strategy.setEscrowPin!({ ...params, pin: '246802' });
+        expect(version).toBe(3);
+        expect(pinSalt).not.toBe(previousSalt);
+        expect(blob?.pinVerifier).toBe(await derivePinProof('246802', pinSalt!));
+        calls = [];
+        await strategy.clearEscrowPin!(params);
+        const enrollment = calls.find(call => call.path === '/keys/escrow');
+        expect(JSON.parse(String(enrollment?.init?.body))).toMatchObject({ clearPin: true });
+        expect(version).toBe(4);
+        expect(pinSalt).toBeUndefined();
+        expect(blob?.pinVerifier).toBeUndefined();
+    });
+
+    it.each(['set', 'clear'])('rejects %s PIN when disabled without opting in', async action => {
+        config.escrow!.enabled = false;
+        await expect(
+            action === 'set'
+                ? strategy.setEscrowPin!({ ...params, pin: '135790' })
+                : strategy.clearEscrowPin!(params)
+        ).rejects.toThrow('Automatic recovery is not available for this account.');
+        expect(calls).toHaveLength(0);
+    });
+
+    it.each(['set', 'clear'])(
+        'rejects %s PIN for opted-out accounts without opting in',
+        async action => {
+            vi.spyOn(strategy, 'fetchServerKeyStatus').mockResolvedValue({
+                exists: true,
+                needsMigration: false,
+                primaryDid: did,
+                recoveryMethods: [],
+                escrowOptedOut: true,
+            });
+            await expect(
+                action === 'set'
+                    ? strategy.setEscrowPin!({ ...params, pin: '135790' })
+                    : strategy.clearEscrowPin!(params)
+            ).rejects.toThrow('Automatic recovery is not available for this account.');
+            expect(calls).toHaveLength(0);
+        }
+    );
+
+    it('maps unavailable PIN policy to a typed error', async () => {
+        vi.mocked(fetch).mockResolvedValue(
+            new Response(
+                JSON.stringify({
+                    message: 'PIN recovery is not available for this account.',
+                }),
+                { status: 403 }
+            )
+        );
+        await expect(recoverPin()).rejects.toMatchObject({ name: 'EscrowPinUnavailableError' });
+    });
+
+    it.each(['123', '111111'])('rejects invalid enrollment PIN %s without rotating', async pin => {
+        await expect(
+            strategy.ensureEscrowEnrollment!({ ...params, options: { pin } })
+        ).rejects.toThrow(/PIN/);
+        expect(version).toBe(1);
+        expect(calls).toHaveLength(0);
+    });
+
+    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(version).toBe(3);
+        expect(blob?.pinVerifier).toBeUndefined();
+        expect(await reconstructFromShares([(await storage.getDeviceShare())!, authShare])).toBe(
+            privateKey
+        );
+    });
+
+    it('burns a wrong PIN hold and uses a fresh hold and key for the next call', async () => {
+        await strategy.setEscrowPin!({ ...params, pin: '135790' });
+        vi.mocked(storage.storeDeviceShare).mockClear();
+        vi.mocked(storage.storeShareVersion).mockClear();
+        await expect(recoverPin('246802')).rejects.toMatchObject({
+            name: 'EscrowPinMismatchError',
+            attemptsRemaining: 9,
+        });
+        expect(burned).toEqual(['escrow-hold']);
+        expect(storage.storeDeviceShare).not.toHaveBeenCalled();
+        expect(storage.storeShareVersion).not.toHaveBeenCalled();
+        await expect(recoverPin()).resolves.toEqual({ privateKey, did });
+        const starts = calls.filter(call => call.path === '/keys/escrow/recover');
+        const completes = calls.filter(call => call.path === '/keys/escrow/complete');
+        expect(starts).toHaveLength(2);
+        expect(completes.map(call => JSON.parse(String(call.init?.body)).holdId)).toEqual([
+            'escrow-hold',
+            'escrow-hold-2',
+        ]);
+        expect(JSON.parse(String(starts[0].init?.body)).clientEphemeralPublicKey).not.toBe(
+            JSON.parse(String(starts[1].init?.body)).clientEphemeralPublicKey
+        );
+    });
+
+    it('maps exhaustion to a locked error without retrying', async () => {
+        await strategy.setEscrowPin!({ ...params, pin: '135790' });
+        attemptsRemaining = 1;
+        await expect(recoverPin('246802')).rejects.toMatchObject({ name: 'EscrowPinLockedError' });
+        expect(calls.filter(call => call.path === '/keys/escrow/complete')).toHaveLength(1);
+    });
+
+    it('maps IP throttling to a retryable error and uses a fresh hold on the next call', async () => {
+        await strategy.setEscrowPin!({ ...params, pin: '135790' });
+        const original = vi.mocked(fetch).getMockImplementation()!;
+        const completeIds: string[] = [];
+        vi.mocked(fetch).mockImplementation((url, init) => {
+            if (String(url).endsWith('/complete')) {
+                completeIds.push(JSON.parse(String(init?.body)).holdId);
+                return Promise.resolve(
+                    new Response(
+                        JSON.stringify({
+                            message: 'Please wait before trying again.',
+                        }),
+                        { status: 429 }
+                    )
+                );
+            }
+            return original(url, init);
+        });
+        await expect(recoverPin()).rejects.toMatchObject({ name: 'EscrowPinThrottledError' });
+        expect(completeIds).toHaveLength(1);
+        await expect(recoverPin()).rejects.toMatchObject({ name: 'EscrowPinThrottledError' });
+        expect(completeIds).toEqual(['escrow-hold', 'escrow-hold-2']);
+    });
+
+    it.each([
+        ['Incorrect PIN.', 0],
+        ['Incorrect PIN. nope attempts left.', 0],
+        ['Incorrect PIN. 9007199254740992 attempts left.', 0],
+        ['Incorrect PIN. 10 attempts left.', 0],
+        ['Incorrect PIN. -1 attempts left.', 0],
+        ['Incorrect PIN. 1.5 attempts left.', 0],
+        ['Incorrect PIN. 9 attempts left.', 9],
+        ['Incorrect PIN. 0 attempts left.', 0],
+    ])('bounds remaining attempts in %s', async (message, expected) => {
+        await strategy.setEscrowPin!({ ...params, pin: '135790' });
+        const original = vi.mocked(fetch).getMockImplementation()!;
+        vi.mocked(fetch).mockImplementation((url, init) =>
+            String(url).endsWith('/complete')
+                ? Promise.resolve(new Response(JSON.stringify({ message }), { status: 403 }))
+                : original(url, init)
+        );
+        await expect(recoverPin()).rejects.toMatchObject({
+            name: 'EscrowPinMismatchError',
+            attemptsRemaining: expected,
+        });
+    });
+
+    it.each([{ did: 'did:key:other' }, { holdId: 'other' }, { shareVersion: 99 }])(
+        'rejects PIN release binding mismatch %j',
+        async mismatch => {
+            await strategy.setEscrowPin!({ ...params, pin: '135790' });
+            overrides = mismatch;
+            await expect(recoverPin()).rejects.toThrow('does not match');
+            expect(version).toBe(2);
+        }
+    );
+
+    it.each([true, false])('forwards only an enabled restart flag (%s)', async restart => {
+        await strategy.ensureEscrowEnrollment!(params);
+        await strategy.startEscrowRecovery!({ token, providerType, options: { restart } });
+        const call = vi.mocked(fetch).mock.calls.find(([url]) => String(url).endsWith('/recover'));
+        const body = JSON.parse(String(call?.[1]?.body));
+        if (restart) expect(body.restart).toBe(true);
+        else expect(body).not.toHaveProperty('restart');
+    });
+
+    it.each(['2026-09-17T00:00:00.000Z', undefined])(
+        'maps restart throttling with retry time %s',
+        async retryAfter => {
+            vi.mocked(fetch).mockResolvedValueOnce(
+                new Response(
+                    JSON.stringify({
+                        message: retryAfter
+                            ? `A recovery request was started recently. Try again after ${retryAfter}.`
+                            : 'Please wait.',
+                    }),
+                    { status: 429 }
+                )
+            );
+            await expect(
+                strategy.startEscrowRecovery!({ token, providerType, options: { restart: true } })
+            ).rejects.toMatchObject({ name: 'EscrowHoldRestartThrottledError', retryAfter });
+        }
+    );
+
+    it('supersedes a pending hold for each PIN attempt and supports hold fallback', async () => {
+        await strategy.setEscrowPin!({ ...params, pin: '135790' });
+        const first = await strategy.startEscrowRecovery!({ token, providerType });
+        const second = await strategy.startEscrowRecovery!({
+            token,
+            providerType,
+            options: { releasePolicy: 'pin' },
+        });
+        const third = await strategy.startEscrowRecovery!({
+            token,
+            providerType,
+            options: { releasePolicy: 'pin' },
+        });
+        const fallback = await strategy.startEscrowRecovery!({ token, providerType });
+        expect(burned).toEqual([first.holdId, second.holdId, third.holdId]);
+        expect(fallback.releasePolicy).toBe('hold');
+        expect(fallback.resumeToken).toBeTruthy();
+    });
+
+    it('round trips real crypto, rebinds and persists a new device share', async () => {
+        await strategy.ensureEscrowEnrollment!(params);
+        const previous = await storage.getDeviceShare();
+        const start = await strategy.startEscrowRecovery!({ token, providerType });
+        const recovered = await strategy.executeRecovery({
+            ...params,
+            input: { method: 'escrow', ...start, resumeToken: start.resumeToken! },
+            didFromPrivateKey: async key => (key === privateKey ? did : ''),
+        });
+        expect(recovered.privateKey === privateKey).toBe(true);
+        expect((await storage.getDeviceShare()) === previous).toBe(false);
+        expect(
+            (await reconstructFromShares([(await storage.getDeviceShare())!, authShare])) ===
+                privateKey
+        ).toBe(true);
+        expect(version).toBe(3);
+        expect(blob?.shareVersion).toBe(3);
+        expect(strategy.hasPendingIdentityRecovery!()).toBe(false);
+        expect(calls.some(call => call.path === '/keys/recovery-session/rebind')).toBe(true);
+        const reEnrollment = calls.filter(call => call.path === '/keys/escrow').at(-1);
+        expect(JSON.parse(String(reEnrollment?.init?.body))).toMatchObject({ clearPin: true });
+    });
+    it('lets the server carry the PIN after a non-escrow recovery', async () => {
+        await strategy.ensureEscrowEnrollment!({ ...params, options: { pin: '135790' } });
+        const setup = await strategy.setupRecoveryMethod!({
+            ...params,
+            input: { method: 'phrase' },
+        });
+        if (setup.method !== 'phrase') throw new Error('expected phrase setup');
+        calls = [];
+
+        await strategy.executeRecovery({
+            ...params,
+            input: { method: 'phrase', phrase: setup.phrase },
+            didFromPrivateKey: async key => (key === privateKey ? did : ''),
+        });
+
+        const reEnrollment = calls.filter(call => call.path === '/keys/escrow').at(-1);
+        expect(reEnrollment).toBeDefined();
+        expect(JSON.parse(String(reEnrollment?.init?.body)).clearPin).toBeUndefined();
+    });
+    it('keeps the OTP-style pending state until a replacement login completes rebind', async () => {
+        await strategy.ensureEscrowEnrollment!(params);
+        const start = await strategy.startEscrowRecovery!({
+            recoverySessionToken: 'otp-session',
+            tenantId: 'other-tenant',
+        });
+        await strategy.executeRecovery({
+            token: '',
+            providerType,
+            input: { method: 'escrow', ...start, resumeToken: start.resumeToken! },
+            didFromPrivateKey: async () => did,
+        });
+        expect(strategy.hasPendingIdentityRecovery!()).toBe(true);
+        expect(version).toBe(2);
+        await strategy.completeIdentityRecovery!(params);
+        expect(version).toBe(3);
+        expect(strategy.hasPendingIdentityRecovery!()).toBe(false);
+    });
+    it.each([{ did: 'did:key:other' }, { holdId: 'wrong-hold' }, { shareVersion: 999 }])(
+        'rejects release binding mismatch %j',
+        async mismatch => {
+            await strategy.ensureEscrowEnrollment!(params);
+            const start = await strategy.startEscrowRecovery!({ token, providerType });
+            overrides = mismatch;
+            await expect(
+                strategy.executeRecovery({
+                    ...params,
+                    input: { method: 'escrow', ...start, resumeToken: start.resumeToken! },
+                    didFromPrivateKey: async () => did,
+                })
+            ).rejects.toThrow('does not match');
+            expect(version).toBe(2);
+            expect(strategy.hasPendingIdentityRecovery!()).toBe(false);
+        }
+    );
+    it('supports both status proofs, existing holds and fresh-proof cancellation', async () => {
+        expect(await strategy.getEscrowRecoveryStatus!({ token, providerType })).toBeNull();
+        const first = await strategy.startEscrowRecovery!({ token, providerType });
+        const again = await strategy.startEscrowRecovery!({ token, providerType });
+        expect(again.resumeToken).toBeNull();
+        expect(again.clientEphemeralPrivateKey).toBeTruthy();
+        expect(
+            await strategy.getEscrowRecoveryStatus!({
+                holdId: first.holdId,
+                resumeToken: first.resumeToken!,
+            })
+        ).toEqual(hold());
+        expect(await strategy.getEscrowRecoveryStatus!({ token, providerType })).toEqual(hold());
+        await expect(strategy.cancelEscrowRecovery!(params)).resolves.toEqual({ cancelled: true });
+    });
+});
+
 describe('createSSSStrategy', () => {
     let strategy: SSSKeyDerivationStrategy;
     let storage: ReturnType<typeof createMemoryStorage>;
@@ -125,8 +946,10 @@ describe('createSSSStrategy', () => {
 
         it('has optional methods', () => {
             expect(typeof strategy.markMigrated).toBe('function');
+            expect(typeof strategy.activate).toBe('function');
             expect(typeof strategy.verifyKeys).toBe('function');
             expect(typeof strategy.setupRecoveryMethod).toBe('function');
+            expect(typeof strategy.confirmRecoveryMethod).toBe('function');
             expect(typeof strategy.getAvailableRecoveryMethods).toBe('function');
             expect(typeof strategy.setActiveUser).toBe('function');
             expect(typeof strategy.getLocalShareVersion).toBe('function');
@@ -166,6 +989,23 @@ describe('createSSSStrategy', () => {
             expect(await strategy.getLocalKey()).toBeNull();
         });
 
+        it('preserves unresolved unscoped candidates while removing only the stale main share and version', async () => {
+            await strategy.storeLocalKey('stale-main');
+            await strategy.storeLocalShareVersion!(4);
+            await writePendingShareCandidates(storage, [
+                { share: 'unresolved-device-share', createdAt: Date.now() },
+            ]);
+
+            await strategy.clearLocalKeys({ preservePending: true });
+
+            expect(await storage.getDeviceShare()).toBeNull();
+            expect(await strategy.getLocalShareVersion!()).toBeNull();
+            expect(await readPendingShareCandidates(storage)).toEqual([
+                { share: 'unresolved-device-share', createdAt: expect.any(Number) },
+            ]);
+            expect(await strategy.getLocalKey()).toBe('unresolved-device-share');
+        });
+
         it('delegates to the injected storage with undefined id when no active user', async () => {
             await strategy.storeLocalKey('delegated-share');
 
@@ -263,6 +1103,40 @@ describe('createSSSStrategy', () => {
             expect(await strategy.hasLocalKey()).toBe(true);
             expect(await strategy.getLocalKey()).toBe('share-a');
         });
+
+        it('preserves only the active account pending candidates on automatic cleanup', async () => {
+            strategy.setActiveUser!('user-a');
+            await strategy.storeLocalKey('stale-a');
+            await strategy.storeLocalShareVersion!(2);
+            const pendingA = [{ share: 'pending-a', createdAt: Date.now() }];
+            await writePendingShareCandidates(storage, pendingA, 'sss-device-share:user-a');
+
+            strategy.setActiveUser!('user-b');
+            await strategy.storeLocalKey('share-b');
+            await strategy.storeLocalShareVersion!(3);
+            const pendingB = [{ share: 'pending-b', createdAt: Date.now() }];
+            await writePendingShareCandidates(storage, pendingB, 'sss-device-share:user-b');
+
+            strategy.setActiveUser!('user-a');
+            await strategy.clearLocalKeys({ preservePending: true });
+            expect(await storage.getDeviceShare('sss-device-share:user-a')).toBeNull();
+            expect(await strategy.getLocalShareVersion!()).toBeNull();
+            expect(await strategy.getLocalKey()).toBe('pending-a');
+            expect(await readPendingShareCandidates(storage, 'sss-device-share:user-a')).toEqual(
+                pendingA
+            );
+            expect(await readPendingShareCandidates(storage, 'sss-device-share:user-b')).toEqual(
+                pendingB
+            );
+
+            await strategy.clearLocalKeys();
+            expect(await readPendingShareCandidates(storage, 'sss-device-share:user-a')).toEqual(
+                []
+            );
+            strategy.setActiveUser!('user-b');
+            expect(await strategy.getLocalKey()).toBe('share-b');
+            expect(await strategy.getLocalShareVersion!()).toBe(3);
+        });
     });
 
     // -----------------------------------------------------------------------
@@ -493,6 +1367,12 @@ describe('createSSSStrategy', () => {
                     );
                 }
 
+                if (urlStr.includes('/keys/auth-share') && method === 'PUT') {
+                    return new Response(JSON.stringify({ success: true, shareVersion: 43 }), {
+                        status: 200,
+                    });
+                }
+
                 return new Response(null, { status: 200 });
             });
 
@@ -503,7 +1383,7 @@ describe('createSSSStrategy', () => {
                 didFromPrivateKey: async () => 'did:key:zCorrect',
             });
 
-            expect(storage.storeShareVersion).toHaveBeenCalledWith(42, undefined);
+            expect(storage.storeShareVersion).toHaveBeenCalledWith(43, undefined);
         });
 
         it('defaults to shareVersion 1 when server response omits it', async () => {
@@ -523,13 +1403,19 @@ describe('createSSSStrategy', () => {
                             primaryDid: 'did:key:zCorrect',
                             recoveryMethods: [],
                             keyProvider: 'sss',
-                            // no shareVersion field
+                            shareVersion: 1, // The PUT response below omits the version.
                         }),
                         { status: 200 }
                     );
                 }
 
-                return new Response(null, { status: 200 });
+                if (urlStr.includes('/keys/auth-share') && method === 'PUT') {
+                    return new Response(JSON.stringify({ success: true }), { status: 200 });
+                }
+
+                return new Response(JSON.stringify({ success: true, shareVersion: 2 }), {
+                    status: 200,
+                });
             });
 
             await strategy.executeRecovery({
@@ -588,6 +1474,7 @@ describe('createSSSStrategy', () => {
             expect(status.needsMigration).toBe(false);
             expect(status.primaryDid).toBeNull();
             expect(status.authShare).toBeNull();
+            expect(status.sssActivationState).toBeNull();
         });
 
         it('parses server response with string authShare', async () => {
@@ -611,6 +1498,7 @@ describe('createSSSStrategy', () => {
             expect(status.authShare).toBe('raw-auth-share-string');
             expect(status.recoveryMethods).toHaveLength(1);
             expect(status.shareVersion).toBeNull(); // no shareVersion in response
+            expect(status.sssActivationState).toBe('active');
         });
 
         it('parses server response with object authShare (encrypted envelope)', async () => {
@@ -689,6 +1577,10 @@ describe('createSSSStrategy', () => {
 
             // shareVersion should be persisted locally
             expect(storage.storeShareVersion).toHaveBeenCalledWith(3, undefined);
+
+            const requestBody = JSON.parse(fetchSpy.mock.calls[0]![1]?.body as string);
+            expect(requestBody.sssActivationState).toBe('provisional');
+            expect(requestBody.sssActivationState).not.toBe('active');
         });
 
         it('throws on server error', async () => {
@@ -733,6 +1625,34 @@ describe('createSSSStrategy', () => {
         });
     });
 
+    describe('activate', () => {
+        it('sends POST to /keys/activate', async () => {
+            const fetchSpy = vi
+                .spyOn(globalThis, 'fetch')
+                .mockResolvedValueOnce(new Response(null, { status: 200 }));
+
+            await strategy.activate!('token', 'firebase', 'did-auth-vp');
+
+            expect(fetchSpy).toHaveBeenCalledWith(
+                'http://test-server:5100/api/keys/activate',
+                expect.objectContaining({
+                    method: 'POST',
+                    headers: expect.objectContaining({ Authorization: 'Bearer did-auth-vp' }),
+                })
+            );
+        });
+
+        it('throws on server error', async () => {
+            vi.spyOn(globalThis, 'fetch').mockResolvedValueOnce(
+                new Response(null, { status: 409, statusText: 'Conflict' })
+            );
+
+            await expect(strategy.activate!('token', 'firebase')).rejects.toThrow(
+                'Failed to activate SSS key'
+            );
+        });
+    });
+
     // -----------------------------------------------------------------------
     // getPreservedStorageKeys
     // -----------------------------------------------------------------------
@@ -790,6 +1710,12 @@ describe('createSSSStrategy', () => {
                     );
                 }
 
+                if (urlStr.includes('/keys/auth-share') && method === 'PUT') {
+                    return new Response(JSON.stringify({ success: true, shareVersion: 2 }), {
+                        status: 200,
+                    });
+                }
+
                 return new Response(null, { status: 200 });
             });
 
@@ -835,20 +1761,19 @@ describe('createSSSStrategy', () => {
             expect(result.privateKey).toBe(originalKey);
             expect(result.did).toBe('did:key:zCorrect');
 
-            // No rotateShares — recovery share is stored as device share directly,
-            // so no PUT to /keys/auth-share (preserves existing recovery methods).
+            // Recovery rotates through atomicRecovery so device + auth advance together.
             const putCalls = fetchCalls.filter(
                 c => c.url.includes('/keys/auth-share') && c.method === 'PUT'
             );
 
-            expect(putCalls).toHaveLength(0);
+            expect(putCalls).toHaveLength(1);
 
-            // Verify the recovery share is now the device share and can reconstruct
+            // Verify the fresh device share reconstructs with the fresh auth share.
             const storedDevice = await strategy.getLocalKey();
-            expect(storedDevice).toBe(localKey);
+            const storedAuth = JSON.parse(putCalls[0]!.body).authShare.encryptedData;
+            expect(await strategy.reconstructKey(storedDevice!, storedAuth)).toBe(originalKey);
 
-            // Verify shareVersion was stored (server returned shareVersion: 1)
-            expect(storage.storeShareVersion).toHaveBeenCalledWith(1, undefined);
+            expect(storage.storeShareVersion).toHaveBeenCalledWith(2, undefined);
         });
 
         it('retry after stale share still works (server not corrupted)', async () => {
@@ -879,43 +1804,368 @@ describe('createSSSStrategy', () => {
             expect(result.privateKey).toBe(originalKey);
             expect(result.did).toBe('did:key:zCorrect');
 
-            // No PUT calls at all — recovery no longer rotates shares
+            // Only the successful retry rotates shares; the stale attempt never writes.
             const putCalls = fetchCalls.filter(
                 c => c.url.includes('/keys/auth-share') && c.method === 'PUT'
             );
 
-            expect(putCalls).toHaveLength(0);
+            expect(putCalls).toHaveLength(1);
         });
     });
 
-    // -----------------------------------------------------------------------
-    // Cross-device recovery with older shareVersion (regression tests)
-    //
-    // Scenario: Device A is at v3, Device B has v2. Device A loses its share
-    // and recovers via Device B. Device B sends its v2 device share + version.
-    // Device A must request the v2 auth share from the server (stored in
-    // previousAuthShares) and reconstruct successfully.
-    // -----------------------------------------------------------------------
+    describe('lost login identity recovery', () => {
+        const prepareRebind = async () => {
+            const privateKey = 'ab'.repeat(32);
+            const did = 'did:key:rebind-test';
+            const { shares } = await splitAndVerify(privateKey);
+            const storageId = 'sss-device-share:rebind-user';
+            const pendingId = `sss-pending-share:${storageId}`;
+            strategy.setActiveUser!('rebind-user');
+            await storage.storeDeviceShare(shares.deviceShare, storageId);
+            await storage.storeShareVersion(1, storageId);
+            let serverShare = shares.authShare;
+            let version = 1;
+            let outcome: 'lost' | 'rejected' | 'uncommitted' | 'success' = 'lost';
+            let rebindCalls = 0;
+            const postedShares: string[] = [];
+            const json = (data: unknown) => new Response(JSON.stringify(data), { status: 200 });
+            vi.spyOn(globalThis, 'fetch').mockImplementation(async (url, init) => {
+                const path = new URL(String(url)).pathname;
+                if (path.endsWith('/recovery-session/recover')) {
+                    return json({
+                        authShare: { encryptedData: shares.authShare },
+                        primaryDid: did,
+                        rebindSessionToken: 'one-shot-token',
+                    });
+                }
+                if (path.endsWith('/keys/challenge')) return json({ challenge: 'challenge' });
+                if (path.endsWith('/keys/auth-share')) {
+                    expect(JSON.parse(String(init?.body)).authToken).toBe('new-sign-in');
+                    return json({
+                        authShare: { encryptedData: serverShare },
+                        shareVersion: version,
+                    });
+                }
+                if (path.endsWith('/recovery-session/rebind')) {
+                    rebindCalls++;
+                    const body = JSON.parse(String(init?.body));
+                    postedShares.push(body.authShare.encryptedData);
+                    if (outcome === 'rejected') {
+                        return new Response(JSON.stringify({ message: 'Rebind rejected' }), {
+                            status: 401,
+                        });
+                    }
+                    if (outcome === 'uncommitted') throw new TypeError('Reply lost');
+                    serverShare = body.authShare.encryptedData;
+                    version = 2;
+                    if (outcome === 'lost') throw new TypeError('Reply lost');
+                    return json({ shareVersion: version });
+                }
+                throw new Error(`Unexpected request: ${path}`);
+            });
+            await strategy.prepareIdentityRecovery!({
+                recoverySessionToken: 'session-token',
+                input: {
+                    method: 'email',
+                    emailShare: formatVersionedEmailShare(shares.emailShare, 1),
+                },
+                didFromPrivateKey: async key => (key === privateKey ? did : ''),
+            });
+            const params = {
+                token: 'new-sign-in',
+                providerType: 'firebase',
+                signDidAuthVp: async () => 'proof',
+            };
+            return {
+                privateKey,
+                did,
+                storageId,
+                pendingId,
+                params,
+                shares,
+                postedShares,
+                setOutcome: (value: typeof outcome) => {
+                    outcome = value;
+                },
+                getServerShare: () => serverShare,
+                getRebindCalls: () => rebindCalls,
+            };
+        };
 
-    describe('recovery via another device with older shareVersion', () => {
-        it('fetchServerKeyStatus sends local shareVersion in the request body', async () => {
-            strategy.setActiveUser!('user-x');
-            await strategy.storeLocalShareVersion!(2);
+        it('reconciles a committed rebind on retry without a new split or another POST', async () => {
+            const fixture = await prepareRebind();
+            await expect(strategy.completeIdentityRecovery!(fixture.params)).rejects.toThrow(
+                'Reply lost'
+            );
+            const candidates = await readPendingShareCandidates(storage, fixture.storageId);
+            expect(candidates).toHaveLength(1);
+            const pending = candidates[0]!.share;
+            expect(await storage.getDeviceShare(fixture.storageId)).toBe(
+                fixture.shares.deviceShare
+            );
+            const writes = vi.mocked(storage.storeDeviceShare).mock.calls.length;
+            await expect(strategy.completeIdentityRecovery!(fixture.params)).resolves.toEqual({
+                privateKey: fixture.privateKey,
+                did: fixture.did,
+            });
+            expect(fixture.getRebindCalls()).toBe(1);
+            expect(vi.mocked(storage.storeDeviceShare).mock.calls.slice(writes)).toEqual([
+                [pending, fixture.storageId],
+            ]);
+            expect(
+                await reconstructFromShares([
+                    (await storage.getDeviceShare(fixture.storageId))!,
+                    fixture.getServerShare(),
+                ])
+            ).toBe(fixture.privateKey);
+            expect(await storage.getShareVersion(fixture.storageId)).toBe(2);
+            expect(await storage.getDeviceShare(fixture.pendingId)).toBeNull();
+            expect(strategy.hasPendingIdentityRecovery!()).toBe(false);
+        });
 
-            const fetchSpy = vi.spyOn(globalThis, 'fetch').mockResolvedValueOnce(
+        it('recovers a committed rebind after reload from the account-scoped pending entry', async () => {
+            const fixture = await prepareRebind();
+            await expect(strategy.completeIdentityRecovery!(fixture.params)).rejects.toThrow(
+                'Reply lost'
+            );
+            const reloaded = createSSSStrategy({ serverUrl: 'https://example.com', storage });
+            reloaded.setActiveUser!('rebind-user');
+            expect(reloaded.hasPendingIdentityRecovery!()).toBe(false);
+            await expect(
+                reloaded.reconcileShares!({
+                    ...fixture.params,
+                    expectedDid: fixture.did,
+                    didFromPrivateKey: async key => (key === fixture.privateKey ? fixture.did : ''),
+                })
+            ).resolves.toEqual({ privateKey: fixture.privateKey, did: fixture.did });
+            expect(
+                await reconstructFromShares([
+                    (await storage.getDeviceShare(fixture.storageId))!,
+                    fixture.getServerShare(),
+                ])
+            ).toBe(fixture.privateKey);
+            expect(await storage.getShareVersion(fixture.storageId)).toBe(2);
+            expect(await storage.getDeviceShare(fixture.pendingId)).toBeNull();
+            expect(fixture.getRebindCalls()).toBe(1);
+        });
+
+        it('surfaces a definitive rejection without destroying the matching active share', async () => {
+            const fixture = await prepareRebind();
+            fixture.setOutcome('rejected');
+            await expect(strategy.completeIdentityRecovery!(fixture.params)).rejects.toThrow(
+                'Rebind rejected'
+            );
+            expect(await storage.getDeviceShare(fixture.pendingId)).toBeNull();
+            expect(await storage.getShareVersion(fixture.storageId)).toBe(1);
+            expect(
+                await reconstructFromShares([
+                    (await storage.getDeviceShare(fixture.storageId))!,
+                    fixture.getServerShare(),
+                ])
+            ).toBe(fixture.privateKey);
+        });
+
+        it('retains the committed pending share when a stale retry read leads to rejection', async () => {
+            const fixture = await prepareRebind();
+            await expect(strategy.completeIdentityRecovery!(fixture.params)).rejects.toThrow(
+                'Reply lost'
+            );
+            const pending = await readPendingShareCandidates(storage, fixture.storageId);
+            expect(pending).toHaveLength(1);
+            vi.mocked(globalThis.fetch).mockResolvedValueOnce(
                 new Response(
                     JSON.stringify({
-                        authShare: 'v2-auth-share',
-                        keyProvider: 'sss',
-                        primaryDid: 'did:key:z123',
-                        recoveryMethods: [],
-                        shareVersion: 3,
+                        authShare: { encryptedData: fixture.shares.authShare },
+                        shareVersion: 1,
                     }),
                     { status: 200 }
                 )
             );
+            fixture.setOutcome('rejected');
+            await expect(strategy.completeIdentityRecovery!(fixture.params)).rejects.toThrow(
+                'Rebind rejected'
+            );
+            expect(await readPendingShareCandidates(storage, fixture.storageId)).toEqual(pending);
+            await strategy.completeIdentityRecovery!(fixture.params);
+            expect(fixture.getRebindCalls()).toBe(2);
+            expect(
+                await reconstructFromShares([
+                    (await storage.getDeviceShare(fixture.storageId))!,
+                    fixture.getServerShare(),
+                ])
+            ).toBe(fixture.privateKey);
+        });
 
-            await strategy.fetchServerKeyStatus('token', 'firebase');
+        it('does not publish recovery success when cancelled during local promotion', async () => {
+            const fixture = await prepareRebind();
+            fixture.setOutcome('success');
+            vi.mocked(storage.storeShareVersion).mockImplementationOnce(async (version, id) => {
+                storage._versions.set(id ?? DEFAULT_KEY, version);
+                strategy.cancelIdentityRecovery!();
+            });
+            await expect(strategy.completeIdentityRecovery!(fixture.params)).rejects.toThrow(
+                'cancelled'
+            );
+            expect(
+                await reconstructFromShares([
+                    (await storage.getDeviceShare(fixture.storageId))!,
+                    fixture.getServerShare(),
+                ])
+            ).toBe(fixture.privateKey);
+        });
+
+        it('reuses the staged split when retrying an uncommitted request', async () => {
+            const fixture = await prepareRebind();
+            fixture.setOutcome('uncommitted');
+            await expect(strategy.completeIdentityRecovery!(fixture.params)).rejects.toThrow(
+                'Reply lost'
+            );
+            const candidates = await readPendingShareCandidates(storage, fixture.storageId);
+            expect(candidates).toHaveLength(1);
+            const pending = candidates[0]!.share;
+            await expect(strategy.completeIdentityRecovery!(fixture.params)).rejects.toThrow(
+                'Reply lost'
+            );
+            expect(await readPendingShareCandidates(storage, fixture.storageId)).toEqual(
+                candidates
+            );
+            fixture.setOutcome('success');
+            await strategy.completeIdentityRecovery!(fixture.params);
+            expect(fixture.postedShares).toHaveLength(3);
+            expect(fixture.postedShares[0]).toBe(fixture.postedShares[1]);
+            expect(fixture.postedShares[0]).toBe(fixture.postedShares[2]);
+            expect(await storage.getDeviceShare(fixture.storageId)).toBe(pending);
+            expect(await reconstructFromShares([pending!, fixture.getServerShare()])).toBe(
+                fixture.privateKey
+            );
+        });
+
+        it.each([false, true])(
+            'preserves unrelated queued candidates when binding (retry: %s)',
+            async retry => {
+                const fixture = await prepareRebind();
+                if (retry) {
+                    fixture.setOutcome('uncommitted');
+                    await expect(
+                        strategy.completeIdentityRecovery!(fixture.params)
+                    ).rejects.toThrow('Reply lost');
+                }
+                const unrelated = (await splitAndVerify(fixture.privateKey)).shares.deviceShare;
+                const candidates = [
+                    ...(await readPendingShareCandidates(storage, fixture.storageId)),
+                    { share: unrelated, createdAt: Date.now() },
+                ];
+                await writePendingShareCandidates(storage, candidates, fixture.storageId);
+                const calls = fixture.getRebindCalls();
+                await expect(strategy.completeIdentityRecovery!(fixture.params)).rejects.toThrow(
+                    'Reconcile the pending share update before binding a sign-in'
+                );
+                expect(fixture.getRebindCalls()).toBe(calls);
+                expect(await readPendingShareCandidates(storage, fixture.storageId)).toEqual(
+                    candidates
+                );
+                expect(await storage.getDeviceShare(fixture.storageId)).toBe(
+                    fixture.shares.deviceShare
+                );
+                expect(await storage.getShareVersion(fixture.storageId)).toBe(1);
+            }
+        );
+
+        it('rejects an invalid phrase before submitting the one-shot session token', async () => {
+            const fetchSpy = vi.spyOn(globalThis, 'fetch');
+
+            await expect(
+                strategy.prepareIdentityRecovery!({
+                    recoverySessionToken: 'recovery-session-token',
+                    input: { method: 'phrase', phrase: 'not a valid recovery phrase' },
+                    didFromPrivateKey: async () => 'did:key:zExpected',
+                })
+            ).rejects.toThrow('Invalid recovery phrase');
+
+            expect(fetchSpy).not.toHaveBeenCalled();
+        });
+
+        it('marks failures after session submission as consumed', async () => {
+            vi.spyOn(globalThis, 'fetch').mockResolvedValueOnce(
+                new Response(JSON.stringify({ message: 'Recovery session expired' }), {
+                    status: 401,
+                    statusText: 'Unauthorized',
+                })
+            );
+
+            await expect(
+                strategy.prepareIdentityRecovery!({
+                    recoverySessionToken: 'recovery-session-token',
+                    input: { method: 'email', emailShare: '0001deadbeef' },
+                    didFromPrivateKey: async () => 'did:key:zExpected',
+                })
+            ).rejects.toBeInstanceOf(IdentityRecoverySessionConsumedError);
+        });
+
+        it('hard-fails a DID mismatch before retaining rebind state or rotating shares', async () => {
+            const originalKey = 'e1f2a3b4c5d6'.padEnd(64, '0');
+            const { localKey, remoteKey } = await strategy.splitKey(originalKey);
+            const fetchSpy = vi.spyOn(globalThis, 'fetch').mockResolvedValueOnce(
+                new Response(
+                    JSON.stringify({
+                        authShare: { encryptedData: remoteKey, encryptedDek: '', iv: '' },
+                        primaryDid: 'did:key:zExpected',
+                        shareVersion: 1,
+                        rebindSessionToken: 'rebind-session-token',
+                    }),
+                    { status: 200 }
+                )
+            );
+
+            await expect(
+                strategy.prepareIdentityRecovery!({
+                    recoverySessionToken: 'recovery-session-token',
+                    input: {
+                        method: 'email',
+                        emailShare: formatVersionedEmailShare(localKey, 1),
+                    },
+                    didFromPrivateKey: async () => 'did:key:zWrong',
+                })
+            ).rejects.toThrow('Recovery produced an incorrect key');
+
+            expect(strategy.hasPendingIdentityRecovery!()).toBe(false);
+            expect(storage.storeDeviceShare).not.toHaveBeenCalled();
+            expect(
+                fetchSpy.mock.calls.some(([url]) =>
+                    String(url).includes('/recovery-session/rebind')
+                )
+            ).toBe(false);
+        });
+    });
+
+    // -----------------------------------------------------------------------
+    // Cross-device recovery with older shareVersion (regression tests)
+    //
+    // Scenario: Device A is at v3, Device B has v2. Device A loses its share
+    // and recovers via Device B. Device B sends its v2 device share + version.
+    // Device A must request the v2 auth share from the server (stored in
+    // previousAuthShares) and reconstruct successfully.
+    // -----------------------------------------------------------------------
+
+    describe('recovery via another device with older shareVersion', () => {
+        it('fetchServerKeyStatus sends local shareVersion in the request body', async () => {
+            strategy.setActiveUser!('user-x');
+            await strategy.storeLocalShareVersion!(2);
+
+            const fetchSpy = vi.spyOn(globalThis, 'fetch').mockResolvedValueOnce(
+                new Response(
+                    JSON.stringify({
+                        authShare: 'v2-auth-share',
+                        keyProvider: 'sss',
+                        primaryDid: 'did:key:z123',
+                        recoveryMethods: [],
+                        shareVersion: 3,
+                    }),
+                    { status: 200 }
+                )
+            );
+
+            await strategy.fetchServerKeyStatus('token', 'firebase');
 
             const requestBody = JSON.parse(fetchSpy.mock.calls[0]![1]?.body as string);
 
@@ -948,9 +2198,8 @@ describe('createSSSStrategy', () => {
         it('full flow: v2 device share from another device reconstructs with v2 auth share from server', async () => {
             // --- Setup: split a key to get a real v2 device/auth pair ---
             const originalKey = 'deadbeef1234'.padEnd(64, '0');
-            const { localKey: v2DeviceShare, remoteKey: v2AuthShare } = await strategy.splitKey(
-                originalKey
-            );
+            const { localKey: v2DeviceShare, remoteKey: v2AuthShare } =
+                await strategy.splitKey(originalKey);
 
             // --- Simulate: Device A receives v2 share via QR recovery ---
             strategy.setActiveUser!('recovering-user');
@@ -1041,9 +2290,8 @@ describe('createSSSStrategy', () => {
             // 3. coordinator.initialize() → fetchServerKeyStatus sends v2
 
             const originalKey = 'cafe0123babe'.padEnd(64, '0');
-            const { localKey: v2DeviceShare, remoteKey: v2AuthShare } = await strategy.splitKey(
-                originalKey
-            );
+            const { localKey: v2DeviceShare, remoteKey: v2AuthShare } =
+                await strategy.splitKey(originalKey);
 
             strategy.setActiveUser!('device-recovery-user');
             await strategy.storeLocalKey(v2DeviceShare);
@@ -1099,6 +2347,7 @@ describe('createSSSStrategy', () => {
                 serverUrl: 'http://test-server:5100/api',
                 storage: emailStorage,
                 enableEmailBackupShare: true,
+                ...getTestRelayConfig(),
             });
         });
 
@@ -1118,12 +2367,14 @@ describe('createSSSStrategy', () => {
 
             await emailStrategy.storeAuthShare('token', 'firebase', remoteKey, 'did:key:z1');
 
-            // Step 2: Send email backup — capture the emailShare from the fetch body
-            let capturedPayload: string | undefined;
+            // Step 2: Send email backup — capture and decrypt as the test relay.
+            let capturedEnvelope: EmailRelayEnvelope | undefined;
+            let capturedConfirmationCode: string | undefined;
 
             vi.spyOn(globalThis, 'fetch').mockImplementationOnce(async (_url, init) => {
                 const body = JSON.parse(init?.body as string);
-                capturedPayload = body.emailShare;
+                capturedEnvelope = body.relayPayload;
+                capturedConfirmationCode = body.confirmationCode;
 
                 return new Response(null, { status: 200 });
             });
@@ -1135,12 +2386,17 @@ describe('createSSSStrategy', () => {
                 'user@test.com'
             );
 
-            expect(capturedPayload).toBeDefined();
+            expect(capturedEnvelope).toBeDefined();
+            const decrypted = await decryptEmailRelayPayload(capturedEnvelope, testRelayPrivateKey);
+            const capturedPayload = decrypted.recoveryKey;
+
+            expect(decrypted.targetEmail).toBe('user@test.com');
+            expect(decrypted.confirmationCode).toBe(capturedConfirmationCode);
             // New format: 4-char hex prefix (e.g. "0005" for version 5)
-            expect(capturedPayload!.slice(0, 4)).toBe('0005');
+            expect(capturedPayload.slice(0, 4)).toBe('0005');
 
             // Strip 4-char version prefix for reconstruction
-            const rawShare = capturedPayload!.slice(4);
+            const rawShare = capturedPayload.slice(4);
 
             // Step 3: Reconstruct from email share + auth share
             const reconstructed = await reconstructFromShares([rawShare, remoteKey]);
@@ -1164,12 +2420,12 @@ describe('createSSSStrategy', () => {
 
             await emailStrategy.storeAuthShare('token', 'firebase', remoteKey, 'did:key:z1');
 
-            // Capture the email share
-            let capturedPayload: string | undefined;
+            // Capture the encrypted relay payload.
+            let capturedEnvelope: EmailRelayEnvelope | undefined;
 
             vi.spyOn(globalThis, 'fetch').mockImplementationOnce(async (_url, init) => {
                 const body = JSON.parse(init?.body as string);
-                capturedPayload = body.emailShare;
+                capturedEnvelope = body.relayPayload;
 
                 return new Response(null, { status: 200 });
             });
@@ -1181,8 +2437,9 @@ describe('createSSSStrategy', () => {
                 'user@test.com'
             );
 
+            const decrypted = await decryptEmailRelayPayload(capturedEnvelope, testRelayPrivateKey);
             // Strip 4-char hex version prefix
-            const rawShare = capturedPayload!.slice(4);
+            const rawShare = decrypted.recoveryKey.slice(4);
 
             // The raw email share must NOT equal the device or auth shares
             // (it's a distinct share from the same split)
@@ -1246,18 +2503,26 @@ describe('createSSSStrategy', () => {
                 'user@test.com'
             );
 
-            // Only one fetch call should have been made — to the email relay
+            // Only one fetch call should have been made — to the lca-api relay proxy.
             expect(fetchCalls).toHaveLength(1);
             expect(fetchCalls[0]!.url).toBe('http://test-server:5100/api/keys/email-backup');
 
-            // The email share must NOT appear in any auth-share or recovery endpoint calls
+            // The email share must not appear in the lca-api-visible request.
             const emailBody = JSON.parse(fetchCalls[0]!.body);
-            const emailPayload = emailBody.emailShare;
 
-            expect(emailPayload).toBeDefined();
-            // 4-char hex version prefix (version 2 = "0002")
-            expect(emailPayload.slice(0, 4)).toBe('0002');
-            expect(emailPayload).not.toBe(remoteKey);
+            expect(emailBody.emailShare).toBeUndefined();
+            expect(emailBody.relayPayload).toBeDefined();
+            expect(emailBody.shareVersion).toBe(2);
+            expect(fetchCalls[0]!.body).not.toContain(remoteKey);
+
+            const decrypted = await decryptEmailRelayPayload(
+                emailBody.relayPayload,
+                testRelayPrivateKey
+            );
+
+            expect(decrypted.recoveryKey.slice(0, 4)).toBe('0002');
+            expect(decrypted.recoveryKey).not.toBe(remoteKey);
+            expect(fetchCalls[0]!.body).not.toContain(decrypted.recoveryKey);
 
             // No calls to storage endpoints
             const storageCalls = fetchCalls.filter(
@@ -1267,7 +2532,7 @@ describe('createSSSStrategy', () => {
             expect(storageCalls).toHaveLength(0);
         });
 
-        it('setupRecoveryMethod re-sends email backup share', async () => {
+        it('setupRecoveryMethod does not silently send a share to the login email', async () => {
             const originalKey = 'c3d4e5f6a1b2'.padEnd(64, '0');
 
             // Split the key first (initial setup)
@@ -1320,25 +2585,11 @@ describe('createSSSStrategy', () => {
                 authUser: { id: 'user-1', providerType: 'firebase', email: 'user@test.com' },
             });
 
-            // Verify email backup share was re-sent
+            // Recovery enrollment is explicit and receipt-confirmed. Rotating
+            // another method must never silently target the login email.
             const emailBackupCall = fetchCalls.find(c => c.url.includes('/keys/email-backup'));
 
-            expect(emailBackupCall).toBeDefined();
-
-            // Verify the re-sent email share + new auth share can reconstruct the key
-            const emailBody = JSON.parse(emailBackupCall!.body);
-            const putAuthCall = fetchCalls.find(
-                c => c.url.includes('/keys/auth-share') && c.body && JSON.parse(c.body).authShare
-            );
-            // putAuthShare wraps as { encryptedData: share, encryptedDek: '', iv: '' }
-            const newAuthShare = JSON.parse(putAuthCall!.body).authShare.encryptedData;
-
-            // Strip 4-char hex version prefix from the emailed share
-            const rawEmailShare = emailBody.emailShare.slice(4);
-
-            const reconstructed = await reconstructFromShares([rawEmailShare, newAuthShare]);
-
-            expect(reconstructed).toBe(originalKey);
+            expect(emailBackupCall).toBeUndefined();
         });
 
         it('emailed share includes the shareVersion prefix from storeAuthShare', async () => {
@@ -1356,12 +2607,12 @@ describe('createSSSStrategy', () => {
 
             await emailStrategy.storeAuthShare('token', 'firebase', 'auth-share', 'did:key:z1');
 
-            // Capture email payload
-            let capturedPayload: string | undefined;
+            // Capture encrypted email payload
+            let capturedEnvelope: EmailRelayEnvelope | undefined;
 
             vi.spyOn(globalThis, 'fetch').mockImplementationOnce(async (_url, init) => {
                 const body = JSON.parse(init?.body as string);
-                capturedPayload = body.emailShare;
+                capturedEnvelope = body.relayPayload;
 
                 return new Response(null, { status: 200 });
             });
@@ -1373,11 +2624,13 @@ describe('createSSSStrategy', () => {
                 'user@test.com'
             );
 
+            const decrypted = await decryptEmailRelayPayload(capturedEnvelope, testRelayPrivateKey);
+
             // New format: 4-char hex prefix (version 7 = "0007")
-            expect(capturedPayload!.slice(0, 4)).toBe('0007');
+            expect(decrypted.recoveryKey.slice(0, 4)).toBe('0007');
         });
 
-        it('setupRecoveryMethod re-sends email share with shareVersion prefix', async () => {
+        it('setupRecoveryMethod does not auto-send email when another method rotates shares', async () => {
             const originalKey = 'f6a1b2c3d4e5'.padEnd(64, '0');
 
             await emailStrategy.splitKey(originalKey);
@@ -1424,13 +2677,7 @@ describe('createSSSStrategy', () => {
 
             const emailCall = fetchCalls.find(c => c.url.includes('/keys/email-backup'));
 
-            expect(emailCall).toBeDefined();
-
-            const emailPayload = JSON.parse(emailCall!.body).emailShare;
-
-            // Should use the version from putAuthShare (5), not fetchAuthShareRaw (4)
-            // New format: 4-char hex prefix "0005"
-            expect(emailPayload.slice(0, 4)).toBe('0005');
+            expect(emailCall).toBeUndefined();
         });
 
         it('email recovery with versioned share fetches matching auth share version', async () => {
@@ -1449,9 +2696,9 @@ describe('createSSSStrategy', () => {
                 const urlStr = typeof url === 'string' ? url : url.toString();
 
                 // fetchAuthShareRaw — capture the requested shareVersion
-                if (urlStr.includes('/keys/auth-share')) {
+                if (urlStr.includes('/keys/auth-share') && (init?.method ?? 'GET') === 'POST') {
                     const body = JSON.parse(init?.body as string);
-                    capturedVersion = body.shareVersion;
+                    if (body.shareVersion !== undefined) capturedVersion = body.shareVersion;
 
                     return new Response(
                         JSON.stringify({
@@ -1464,6 +2711,12 @@ describe('createSSSStrategy', () => {
                     );
                 }
 
+                if (urlStr.includes('/keys/auth-share')) {
+                    return new Response(JSON.stringify({ success: true, shareVersion: 3 }), {
+                        status: 200,
+                    });
+                }
+
                 return new Response(JSON.stringify({ success: true }), { status: 200 });
             });
 
@@ -1490,9 +2743,9 @@ describe('createSSSStrategy', () => {
             vi.spyOn(globalThis, 'fetch').mockImplementation(async (url, init) => {
                 const urlStr = typeof url === 'string' ? url : url.toString();
 
-                if (urlStr.includes('/keys/auth-share')) {
+                if (urlStr.includes('/keys/auth-share') && (init?.method ?? 'GET') === 'POST') {
                     const body = JSON.parse(init?.body as string);
-                    capturedVersion = body.shareVersion;
+                    if (body.shareVersion !== undefined) capturedVersion = body.shareVersion;
 
                     return new Response(
                         JSON.stringify({
@@ -1505,6 +2758,12 @@ describe('createSSSStrategy', () => {
                     );
                 }
 
+                if (urlStr.includes('/keys/auth-share')) {
+                    return new Response(JSON.stringify({ success: true, shareVersion: 256 }), {
+                        status: 200,
+                    });
+                }
+
                 return new Response(JSON.stringify({ success: true }), { status: 200 });
             });
 
@@ -1584,6 +2843,85 @@ describe('createSSSStrategy', () => {
             expect(recoveryBody.encryptedShare).toBeUndefined();
         });
 
+        it('keeps phrase enrollment pending after wrong challenge words and allows retry', async () => {
+            const originalKey = 'abababababab'.padEnd(64, '0');
+            const fetchCalls: { url: string; method: string }[] = [];
+
+            vi.spyOn(globalThis, 'fetch').mockImplementation(async (url, init) => {
+                const urlStr = typeof url === 'string' ? url : url.toString();
+                const method = (init?.method ?? 'GET').toUpperCase();
+
+                fetchCalls.push({ url: urlStr, method });
+
+                if (urlStr.includes('/keys/auth-share') && method === 'POST') {
+                    return new Response(
+                        JSON.stringify({
+                            authShare: 'existing',
+                            primaryDid: 'did:key:z1',
+                            recoveryMethods: [],
+                            shareVersion: 1,
+                        }),
+                        { status: 200 }
+                    );
+                }
+
+                if (urlStr.includes('/keys/auth-share') && method === 'PUT') {
+                    return new Response(JSON.stringify({ success: true, shareVersion: 2 }), {
+                        status: 200,
+                    });
+                }
+
+                return new Response(JSON.stringify({ success: true }), { status: 200 });
+            });
+
+            const result = await emailStrategy.setupRecoveryMethod!({
+                token: 'token',
+                providerType: 'firebase',
+                privateKey: originalKey,
+                input: { method: 'phrase' },
+            });
+
+            expect(result.method).toBe('phrase');
+            if (result.method !== 'phrase') throw new Error('Expected phrase setup result');
+
+            const confirmationsBefore = fetchCalls.filter(call =>
+                call.url.endsWith('/keys/recovery/confirm')
+            ).length;
+
+            await expect(
+                emailStrategy.confirmRecoveryMethod!({
+                    token: 'token',
+                    providerType: 'firebase',
+                    privateKey: originalKey,
+                    input: {
+                        method: 'phrase',
+                        challengeWords: result.challengeWordIndices.map(() => 'wrong'),
+                    },
+                })
+            ).rejects.toThrow('do not match');
+            expect(
+                fetchCalls.filter(call => call.url.endsWith('/keys/recovery/confirm'))
+            ).toHaveLength(confirmationsBefore);
+
+            const phraseWords = result.phrase.split(/\s+/);
+            await expect(
+                emailStrategy.confirmRecoveryMethod!({
+                    token: 'token',
+                    providerType: 'firebase',
+                    privateKey: originalKey,
+                    input: {
+                        method: 'phrase',
+                        challengeWords: result.challengeWordIndices.map(
+                            index => phraseWords[index]!
+                        ),
+                    },
+                })
+            ).resolves.toBeUndefined();
+            expect(
+                fetchCalls.filter(call => call.url.endsWith('/keys/recovery/confirm'))
+            ).toHaveLength(confirmationsBefore + 1);
+        });
+
         it('phrase recovery fetches shareVersion from server to get correct auth share', async () => {
             const originalKey = 'b1b2b3b4b5b6'.padEnd(64, '0');
 
@@ -1619,7 +2957,8 @@ describe('createSSSStrategy', () => {
                 // fetchAuthShareRaw — capture requested shareVersion
                 if (urlStr.includes('/keys/auth-share') && method === 'POST') {
                     const body = JSON.parse(init?.body as string);
-                    authShareRequestVersion = body.shareVersion;
+                    if (body.shareVersion !== undefined)
+                        authShareRequestVersion = body.shareVersion;
 
                     return new Response(
                         JSON.stringify({
@@ -1719,6 +3058,154 @@ describe('createSSSStrategy', () => {
             // No encryptedShare on the server record — the backup file is self-contained
             expect(recoveryBody.encryptedShare).toBeUndefined();
         });
+
+        it('decrypts and checksum-verifies a just-written backup before confirming it', async () => {
+            const originalKey = 'cdcdcdcdcdcd'.padEnd(64, '0');
+            const fetchCalls: string[] = [];
+
+            vi.spyOn(globalThis, 'fetch').mockImplementation(async (url, init) => {
+                const urlStr = typeof url === 'string' ? url : url.toString();
+                const method = (init?.method ?? 'GET').toUpperCase();
+
+                fetchCalls.push(urlStr);
+
+                if (urlStr.includes('/keys/auth-share') && method === 'POST') {
+                    return new Response(
+                        JSON.stringify({
+                            authShare: 'existing',
+                            primaryDid: 'did:key:z1',
+                            recoveryMethods: [],
+                            shareVersion: 1,
+                        }),
+                        { status: 200 }
+                    );
+                }
+
+                if (urlStr.includes('/keys/auth-share') && method === 'PUT') {
+                    return new Response(JSON.stringify({ success: true, shareVersion: 2 }), {
+                        status: 200,
+                    });
+                }
+
+                return new Response(JSON.stringify({ success: true }), { status: 200 });
+            });
+
+            const result = await emailStrategy.setupRecoveryMethod!({
+                token: 'token',
+                providerType: 'firebase',
+                privateKey: originalKey,
+                input: { method: 'backup', password: 'correct-password', did: 'did:key:z1' },
+            });
+
+            if (result.method !== 'backup') throw new Error('Expected backup setup result');
+
+            await expect(
+                emailStrategy.confirmRecoveryMethod!({
+                    token: 'token',
+                    providerType: 'firebase',
+                    privateKey: originalKey,
+                    input: {
+                        method: 'backup',
+                        fileContents: JSON.stringify(result.backupFile),
+                        password: 'wrong-password',
+                    },
+                })
+            ).rejects.toThrow('Incorrect password');
+            expect(fetchCalls.filter(url => url.endsWith('/keys/recovery/confirm'))).toHaveLength(
+                0
+            );
+
+            await expect(
+                emailStrategy.confirmRecoveryMethod!({
+                    token: 'token',
+                    providerType: 'firebase',
+                    privateKey: originalKey,
+                    input: {
+                        method: 'backup',
+                        fileContents: JSON.stringify(result.backupFile),
+                        password: 'correct-password',
+                    },
+                })
+            ).resolves.toBeUndefined();
+            expect(fetchCalls.filter(url => url.endsWith('/keys/recovery/confirm'))).toHaveLength(
+                1
+            );
+        });
+    });
+
+    describe('confirmed recovery-method availability', () => {
+        it('does not synthesize email availability when the feature flag is enabled', async () => {
+            const flaggedStrategy = createSSSStrategy({
+                serverUrl: 'http://test-server:5100/api',
+                storage: createMemoryStorage(),
+                enableEmailBackupShare: true,
+            });
+
+            vi.spyOn(globalThis, 'fetch').mockResolvedValueOnce(
+                new Response(
+                    JSON.stringify({
+                        authShare: 'auth-share',
+                        primaryDid: 'did:key:z1',
+                        keyProvider: 'sss',
+                        shareVersion: 1,
+                        recoveryMethods: [],
+                        sssActivationState: 'provisional',
+                    }),
+                    { status: 200 }
+                )
+            );
+
+            await expect(
+                flaggedStrategy.getAvailableRecoveryMethods!('token', 'firebase')
+            ).resolves.toEqual([]);
+        });
+
+        it('excludes pending records while preserving confirmed and active legacy records', async () => {
+            const confirmedAt = new Date().toISOString();
+            const fetchSpy = vi.spyOn(globalThis, 'fetch');
+
+            fetchSpy.mockResolvedValueOnce(
+                new Response(
+                    JSON.stringify({
+                        recoveryMethods: [
+                            {
+                                type: 'phrase',
+                                createdAt: new Date().toISOString(),
+                                confirmationStatus: 'pending',
+                            },
+                            {
+                                type: 'backup',
+                                createdAt: new Date().toISOString(),
+                                confirmedAt,
+                            },
+                        ],
+                        sssActivationState: 'provisional',
+                    }),
+                    { status: 200 }
+                )
+            );
+
+            const provisionalMethods = await strategy.getAvailableRecoveryMethods!(
+                'token',
+                'firebase'
+            );
+
+            expect(provisionalMethods.map(method => method.type)).toEqual(['backup']);
+
+            fetchSpy.mockResolvedValueOnce(
+                new Response(
+                    JSON.stringify({
+                        recoveryMethods: [{ type: 'phrase', createdAt: new Date().toISOString() }],
+                        sssActivationState: 'active',
+                    }),
+                    { status: 200 }
+                )
+            );
+
+            await expect(
+                strategy.getAvailableRecoveryMethods!('token', 'firebase')
+            ).resolves.toHaveLength(1);
+        });
     });
 
     // -----------------------------------------------------------------------
@@ -1726,11 +3213,12 @@ describe('createSSSStrategy', () => {
     // -----------------------------------------------------------------------
 
     describe('email routing — recovery email vs primary', () => {
-        it('setupRecoveryMethod("email") sends ONLY to recovery email, never to primary', async () => {
+        it('setupRecoveryMethod("email") binds ciphertext to the verified recovery email', async () => {
             const strat = createSSSStrategy({
                 serverUrl: 'http://test-server:5100/api',
                 storage: createMemoryStorage(),
                 enableEmailBackupShare: true,
+                ...getTestRelayConfig(),
             });
 
             const originalKey = 'e1e2e3e4e5e6'.padEnd(64, '0');
@@ -1772,28 +3260,34 @@ describe('createSSSStrategy', () => {
                 token: 'token',
                 providerType: 'firebase',
                 privateKey: originalKey,
-                input: { method: 'email' },
+                input: { method: 'email', email: 'recovery@test.com' },
                 authUser: { id: 'user-1', providerType: 'firebase', email: 'primary@test.com' },
             });
 
             const emailBackupCalls = fetchCalls.filter(c => c.url.includes('/keys/email-backup'));
 
-            // Should be exactly ONE call — to the recovery email endpoint
+            // Should be exactly one call with no raw recovery share.
             expect(emailBackupCalls).toHaveLength(1);
 
             const body = JSON.parse(emailBackupCalls[0]!.body);
+            const decrypted = await decryptEmailRelayPayload(
+                body.relayPayload,
+                testRelayPrivateKey
+            );
 
-            // Must use useRecoveryEmail (server-side routing), NOT an explicit email
-            expect(body.useRecoveryEmail).toBe(true);
-            expect(body.email).toBeUndefined();
+            expect(body.emailShare).toBeUndefined();
+            expect(body.email).toBe('recovery@test.com');
+            expect(decrypted.targetEmail).toBe('recovery@test.com');
+            expect(decrypted.confirmationCode).toBe(body.confirmationCode);
         });
 
-        it('setupRecoveryMethod("phrase") does NOT send to primary when recovery email is configured', async () => {
+        it('setupRecoveryMethod("phrase") does not auto-send email after rotating shares', async () => {
             // Create a strategy and prime hasRecoveryEmail via fetchServerKeyStatus
             const stratWithRecovery = createSSSStrategy({
                 serverUrl: 'http://test-server:5100/api',
                 storage: createMemoryStorage(),
                 enableEmailBackupShare: true,
+                ...getTestRelayConfig(),
             });
 
             const originalKey = 'f1f2f3f4f5f6'.padEnd(64, '0');
@@ -1861,20 +3355,15 @@ describe('createSSSStrategy', () => {
 
             const emailBackupCalls = fetchCalls.filter(c => c.url.includes('/keys/email-backup'));
 
-            // Should re-send exactly once — to the recovery email
-            expect(emailBackupCalls).toHaveLength(1);
-
-            const body = JSON.parse(emailBackupCalls[0]!.body);
-
-            expect(body.useRecoveryEmail).toBe(true);
-            expect(body.email).toBeUndefined();
+            expect(emailBackupCalls).toHaveLength(0);
         });
 
-        it('sendEmailBackupShare routes to recovery email when one is configured', async () => {
+        it('sendEmailBackupShare cryptographically binds the explicit recipient', async () => {
             const stratWithRecovery = createSSSStrategy({
                 serverUrl: 'http://test-server:5100/api',
                 storage: createMemoryStorage(),
                 enableEmailBackupShare: true,
+                ...getTestRelayConfig(),
             });
 
             const originalKey = 'd1d2d3d4d5d6'.padEnd(64, '0');
@@ -1927,10 +3416,15 @@ describe('createSSSStrategy', () => {
                 'primary@test.com'
             );
 
-            // Should route to recovery email, not primary
+            const decrypted = await decryptEmailRelayPayload(
+                capturedBody!.relayPayload,
+                testRelayPrivateKey
+            );
+
             expect(capturedBody).toBeDefined();
-            expect(capturedBody!.useRecoveryEmail).toBe(true);
-            expect(capturedBody!.email).toBeUndefined();
+            expect(capturedBody!.useRecoveryEmail).toBeUndefined();
+            expect(capturedBody!.email).toBe('primary@test.com');
+            expect(decrypted.targetEmail).toBe('primary@test.com');
         });
 
         it('sendEmailBackupShare routes to primary email when no recovery email is configured', async () => {
@@ -1938,6 +3432,7 @@ describe('createSSSStrategy', () => {
                 serverUrl: 'http://test-server:5100/api',
                 storage: createMemoryStorage(),
                 enableEmailBackupShare: true,
+                ...getTestRelayConfig(),
             });
 
             const originalKey = 'a2b3c4d5e6f7'.padEnd(64, '0');
@@ -1980,6 +3475,7 @@ describe('createSSSStrategy', () => {
                 serverUrl: 'http://test-server:5100/api',
                 enableEmailBackupShare: true,
                 storage,
+                ...getTestRelayConfig(),
             });
 
             strat.setActiveUser!('user-with-recovery');
@@ -2039,10 +3535,1046 @@ describe('createSSSStrategy', () => {
         });
     });
 
+    describe('production lifecycle atomicity and reconciliation', () => {
+        const privateKey = '1234567890abcdef'.repeat(4);
+        const expectedDid = 'did:key:zAtomicOwner';
+
+        it('does not clear or cancel an in-flight pending write during automatic cleanup', async () => {
+            strategy.setActiveUser!('account-a');
+            let signalPut!: () => void;
+            let finishPut!: () => void;
+            const putStarted = new Promise<void>(resolve => {
+                signalPut = resolve;
+            });
+            const putFinished = new Promise<void>(resolve => {
+                finishPut = resolve;
+            });
+            vi.spyOn(globalThis, 'fetch').mockImplementation(async (_url, init) => {
+                if (init?.method === 'PUT') {
+                    signalPut();
+                    await putFinished;
+                    return new Response(
+                        JSON.stringify({ shareVersion: 1, expectedShareVersionChecked: true })
+                    );
+                }
+                return new Response(JSON.stringify({ authShare: null, shareVersion: 0 }));
+            });
+            const update = strategy.atomicUpdateShares!({
+                token: 'token',
+                providerType: 'firebase',
+                privateKey,
+                did: expectedDid,
+            });
+            await putStarted;
+            const pending = await readPendingShareCandidates(storage, 'sss-device-share:account-a');
+            expect(pending).toHaveLength(1);
+            await expect(strategy.clearLocalKeys({ preservePending: true })).rejects.toMatchObject({
+                rolledBack: false,
+            });
+            expect(await readPendingShareCandidates(storage, 'sss-device-share:account-a')).toEqual(
+                pending
+            );
+            finishPut();
+            await update;
+            expect(await strategy.getLocalKey()).toBe(pending[0]!.share);
+        });
+
+        it('does not promote an old account pending share after an account switch', async () => {
+            strategy.setActiveUser!('account-a');
+            let authShare = '';
+            vi.spyOn(globalThis, 'fetch').mockImplementation(async (_url, init) => {
+                if (init?.method === 'PUT') {
+                    authShare = JSON.parse(String(init.body)).authShare.encryptedData;
+                    throw new TypeError('Lost reply');
+                }
+                return new Response(JSON.stringify({ authShare, shareVersion: 1 }));
+            });
+            await expect(
+                strategy.atomicUpdateShares!({
+                    token: 'token',
+                    providerType: 'firebase',
+                    privateKey,
+                    did: expectedDid,
+                })
+            ).rejects.toMatchObject({ rolledBack: false });
+            await storage.storeDeviceShare('account-b-share', 'sss-device-share:account-b');
+            await expect(
+                strategy.reconcileShares!({
+                    token: 'token',
+                    providerType: 'firebase',
+                    expectedDid,
+                    didFromPrivateKey: async key => {
+                        strategy.setActiveUser!('account-b');
+                        return key === privateKey ? expectedDid : 'did:key:wrong';
+                    },
+                })
+            ).rejects.toThrow('Active account changed');
+            expect(await strategy.getLocalKey()).toBe('account-b-share');
+            strategy.setActiveUser!('account-a');
+            expect(await strategy.hasLocalKey()).toBe(true);
+            expect(
+                await strategy.reconcileShares!({
+                    token: 'token',
+                    providerType: 'firebase',
+                    expectedDid,
+                    didFromPrivateKey: async key =>
+                        key === privateKey ? expectedDid : 'did:key:wrong',
+                })
+            ).toEqual({ privateKey, did: expectedDid });
+        });
+
+        it('keeps cleanup scoped to its starting account across awaits', async () => {
+            strategy.setActiveUser!('account-a');
+            await strategy.storeLocalKey('account-a-share');
+            await storage.storeDeviceShare('account-b-share', 'sss-device-share:account-b');
+            const clear = storage.clearAllShares;
+            vi.mocked(storage.clearAllShares).mockImplementationOnce(async id => {
+                strategy.setActiveUser!('account-b');
+                storage._store.delete(id!);
+            });
+            await strategy.clearLocalKeys();
+            expect(clear).toHaveBeenLastCalledWith('sss-device-share:account-a');
+            expect(await strategy.getLocalKey()).toBe('account-b-share');
+        });
+
+        it.each([408, 502, 503, 504])(
+            'preserves a committed write when a gateway returns HTTP %s',
+            async status => {
+                let authShare = '';
+                vi.spyOn(globalThis, 'fetch').mockImplementation(async (_url, init) => {
+                    if (init?.method === 'PUT') {
+                        authShare = JSON.parse(String(init.body)).authShare.encryptedData;
+                        return new Response(null, { status });
+                    }
+                    return new Response(JSON.stringify({ authShare, shareVersion: 1 }));
+                });
+                await expect(
+                    strategy.atomicUpdateShares!({
+                        token: 'token',
+                        providerType: 'firebase',
+                        privateKey,
+                        did: expectedDid,
+                    })
+                ).rejects.toMatchObject({ rolledBack: false });
+                expect(
+                    await strategy.reconcileShares!({
+                        token: 'token',
+                        providerType: 'firebase',
+                        expectedDid,
+                        didFromPrivateKey: async key =>
+                            key === privateKey ? expectedDid : 'did:key:wrong',
+                    })
+                ).toEqual({ privateKey, did: expectedDid });
+            }
+        );
+
+        it('does not let an overlapping update or reconciliation overwrite the pending slot', async () => {
+            let releaseWrite: () => void = () => {
+                throw new Error('Write not started');
+            };
+            const blocked = new Promise<void>(resolve => {
+                releaseWrite = resolve;
+            });
+            let writeStarted: () => void = () => {
+                throw new Error('Wait not initialized');
+            };
+            const started = new Promise<void>(resolve => {
+                writeStarted = resolve;
+            });
+            let authShare = '';
+            const fetchMock = vi
+                .spyOn(globalThis, 'fetch')
+                .mockImplementation(async (_url, init) => {
+                    if (init?.method === 'PUT') {
+                        authShare = JSON.parse(String(init.body)).authShare.encryptedData;
+                        writeStarted();
+                        await blocked;
+                        throw new TypeError('Reply lost');
+                    }
+                    return new Response(JSON.stringify({ authShare, shareVersion: 1 }));
+                });
+            const params = {
+                token: 'token',
+                providerType: 'firebase' as const,
+                privateKey,
+                did: expectedDid,
+            };
+            const first = expect(strategy.atomicUpdateShares!(params)).rejects.toMatchObject({
+                rolledBack: false,
+            });
+            await started;
+            const second = createSSSStrategy({ serverUrl: 'http://test-server:5100/api', storage });
+            const reconciliation = {
+                token: 'token',
+                providerType: 'firebase' as const,
+                expectedDid,
+                didFromPrivateKey: async (key: string) =>
+                    key === privateKey ? expectedDid : 'did:key:wrong',
+            };
+            try {
+                await expect(second.atomicUpdateShares!(params)).rejects.toThrow(
+                    'already in progress'
+                );
+                await expect(second.reconcileShares!(reconciliation)).rejects.toThrow(
+                    'already in progress'
+                );
+                expect(
+                    fetchMock.mock.calls.filter(([, init]) => init?.method === 'PUT')
+                ).toHaveLength(1);
+            } finally {
+                releaseWrite();
+                await first;
+            }
+            expect(await second.reconcileShares!(reconciliation)).toEqual({
+                privateKey,
+                did: expectedDid,
+            });
+        });
+
+        it.each([400, 403])(
+            'clears only the pending fresh-account share after HTTP %s rejection',
+            async status => {
+                strategy.setActiveUser!('rejected-user');
+                await storage.storeDeviceShare('other-user-share', 'sss-device-share:other');
+                vi.spyOn(globalThis, 'fetch').mockImplementation(
+                    async (_url, init) =>
+                        new Response(null, { status: init?.method === 'PUT' ? status : 404 })
+                );
+                await expect(
+                    strategy.atomicUpdateShares!({
+                        token: 'token',
+                        providerType: 'firebase',
+                        privateKey,
+                        did: expectedDid,
+                    })
+                ).rejects.toMatchObject({ rolledBack: true });
+                expect(await strategy.hasLocalKey()).toBe(false);
+                expect([...storage._store.values()]).toEqual(['other-user-share']);
+            }
+        );
+
+        it('retains earlier candidates and allows another split while a write remains indeterminate', async () => {
+            const previous = await splitAndVerify(privateKey);
+            await strategy.storeLocalKey(previous.shares.deviceShare);
+            await strategy.storeLocalShareVersion!(1);
+            const fetchMock = vi
+                .spyOn(globalThis, 'fetch')
+                .mockImplementation(async (_url, init) => {
+                    if (init?.method === 'PUT') throw new TypeError('Offline');
+                    return new Response(
+                        JSON.stringify({ authShare: previous.shares.authShare, shareVersion: 1 })
+                    );
+                });
+            const update = {
+                token: 'token',
+                providerType: 'firebase' as const,
+                privateKey,
+                did: expectedDid,
+            };
+            await expect(strategy.atomicUpdateShares!(update)).rejects.toMatchObject({
+                rolledBack: false,
+            });
+            expect(storage._store.size).toBe(2);
+            expect(await strategy.getLocalKey()).toBe(previous.shares.deviceShare);
+            const firstCandidates = await readPendingShareCandidates(storage);
+            await expect(strategy.atomicUpdateShares!(update)).rejects.toMatchObject({
+                rolledBack: false,
+            });
+            const candidates = await readPendingShareCandidates(storage);
+            expect(candidates).toHaveLength(2);
+            expect(candidates[0]).toEqual(firstCandidates[0]);
+            expect(await strategy.getLocalKey()).toBe(previous.shares.deviceShare);
+            expect(fetchMock.mock.calls.filter(([, init]) => init?.method === 'PUT')).toHaveLength(
+                2
+            );
+            fetchMock.mockRejectedValue(new TypeError('Offline'));
+            await expect(
+                strategy.reconcileShares!({
+                    token: 'token',
+                    providerType: 'firebase',
+                    expectedDid,
+                    didFromPrivateKey: async key =>
+                        key === privateKey ? expectedDid : 'did:key:zWrong',
+                })
+            ).rejects.toThrow('Offline');
+            expect(await readPendingShareCandidates(storage)).toEqual(candidates);
+            expect(storage._store.size).toBe(2);
+            await strategy.clearLocalKeys();
+            expect(storage._store.size).toBe(0);
+        });
+
+        const updateParams = {
+            token: 'token',
+            providerType: 'firebase' as const,
+            privateKey,
+            did: expectedDid,
+        };
+        const reconcileParams = {
+            token: 'token',
+            providerType: 'firebase' as const,
+            expectedDid,
+            didFromPrivateKey: async (key: string) =>
+                key === privateKey ? expectedDid : 'did:key:wrong',
+        };
+
+        it('recovers an expired committed candidate from history with no main share and re-splits', async () => {
+            const rotated = await splitAndVerify(privateKey);
+            const history = new Map<number, string>();
+            let version = 0;
+            let authShare: string | null = null;
+            let puts = 0;
+            vi.spyOn(globalThis, 'fetch').mockImplementation(async (_url, init) => {
+                const body = JSON.parse(String(init?.body));
+                if (init?.method === 'PUT') {
+                    expect(body.expectedShareVersion).toBe(version);
+                    if (authShare) history.set(version, authShare);
+                    authShare = body.authShare.encryptedData;
+                    version++;
+                    if (++puts === 1) throw new TypeError('Committed but reply lost');
+                    return new Response(
+                        JSON.stringify({ shareVersion: version, expectedShareVersionChecked: true })
+                    );
+                }
+                return new Response(
+                    JSON.stringify(
+                        version
+                            ? {
+                                  authShare: body.shareVersion
+                                      ? (history.get(body.shareVersion) ?? null)
+                                      : authShare,
+                                  shareVersion: version,
+                              }
+                            : null
+                    )
+                );
+            });
+            await expect(strategy.atomicUpdateShares!(updateParams)).rejects.toMatchObject({
+                rolledBack: false,
+            });
+            expect(await storage.getDeviceShare()).toBeNull();
+            const pending = await readPendingShareCandidates(storage);
+            await writePendingShareCandidates(
+                storage,
+                pending.map(candidate => ({
+                    ...candidate,
+                    createdAt: Date.now() - PENDING_WRITE_EXPIRY_MS - 1,
+                }))
+            );
+            history.set(version, authShare!);
+            authShare = rotated.shares.authShare;
+            version++;
+            expect(await strategy.reconcileShares!(reconcileParams)).toEqual({
+                privateKey,
+                did: expectedDid,
+            });
+            expect(version).toBe(3);
+            expect(await reconstructFromShares([(await strategy.getLocalKey())!, authShare!])).toBe(
+                privateKey
+            );
+            expect(await readPendingShareCandidates(storage)).toEqual([]);
+        });
+
+        it.each([false, true])(
+            'expires unmatched candidates only with complete history (failure=%s)',
+            async failure => {
+                const pending = await splitAndVerify(privateKey);
+                const current = await splitAndVerify(privateKey);
+                const historical = await splitAndVerify(privateKey);
+                const candidates = [
+                    {
+                        share: pending.shares.deviceShare,
+                        createdAt: Date.now() - PENDING_WRITE_EXPIRY_MS - 1,
+                    },
+                ];
+                await writePendingShareCandidates(storage, candidates);
+                vi.spyOn(globalThis, 'fetch').mockImplementation(async (_url, init) => {
+                    const body = JSON.parse(String(init?.body));
+                    if (body.shareVersion && failure) throw new TypeError('History unavailable');
+                    return new Response(
+                        JSON.stringify({
+                            shareVersion: 2,
+                            authShare: body.shareVersion
+                                ? historical.shares.authShare
+                                : current.shares.authShare,
+                        })
+                    );
+                });
+                expect(await strategy.reconcileShares!(reconcileParams)).toBeNull();
+                expect(await readPendingShareCandidates(storage)).toEqual(
+                    failure ? candidates : []
+                );
+            }
+        );
+
+        it.each([false, true])(
+            'survives six delayed writes after an acknowledged seventh (CAS=%s)',
+            async cas => {
+                const delayed: Array<{ authShare: string; base: number }> = [];
+                const history = new Map<number, string>();
+                let version = 0;
+                let authShare: string | null = null;
+                const commit = (share: string, base: number): Response => {
+                    if (cas && base !== version) return new Response(null, { status: 409 });
+                    if (authShare) history.set(version, authShare);
+                    authShare = share;
+                    version++;
+                    for (const old of history.keys()) if (old < version - 5) history.delete(old);
+                    return new Response(
+                        JSON.stringify({
+                            shareVersion: version,
+                            ...(cas ? { expectedShareVersionChecked: true } : {}),
+                        })
+                    );
+                };
+                vi.spyOn(globalThis, 'fetch').mockImplementation(async (_url, init) => {
+                    const body = JSON.parse(String(init?.body));
+                    if (init?.method === 'PUT') {
+                        expect(body.expectedShareVersion).toBe(version);
+                        if (delayed.length < 6) {
+                            delayed.push({
+                                authShare: body.authShare.encryptedData,
+                                base: body.expectedShareVersion,
+                            });
+                            throw new TypeError('Request still in flight');
+                        }
+                        return commit(body.authShare.encryptedData, body.expectedShareVersion);
+                    }
+                    return new Response(
+                        JSON.stringify(
+                            version
+                                ? {
+                                      shareVersion: version,
+                                      authShare: body.shareVersion
+                                          ? (history.get(body.shareVersion) ?? null)
+                                          : authShare,
+                                  }
+                                : null
+                        )
+                    );
+                });
+                for (let i = 0; i < 6; i++)
+                    await expect(strategy.atomicUpdateShares!(updateParams)).rejects.toMatchObject({
+                        rolledBack: false,
+                    });
+                await strategy.atomicUpdateShares!(updateParams);
+                expect(await readPendingShareCandidates(storage)).toHaveLength(6);
+                for (const write of delayed)
+                    expect(commit(write.authShare, write.base).status).toBe(cas ? 409 : 200);
+                const reloaded = createSSSStrategy({
+                    serverUrl: 'http://test-server:5100/api',
+                    storage,
+                });
+                await reloaded.reconcileShares!(reconcileParams);
+                expect(
+                    await reconstructFromShares([(await reloaded.getLocalKey())!, authShare!])
+                ).toBe(privateKey);
+                expect(version).toBe(cas ? 1 : 7);
+            }
+        );
+
+        it('preserves expired candidates when the current auth share has no version', async () => {
+            const previous = await splitAndVerify(privateKey);
+            const candidates = [{ share: previous.shares.deviceShare, createdAt: 0 }];
+            await writePendingShareCandidates(storage, candidates);
+            vi.spyOn(globalThis, 'fetch').mockResolvedValue(
+                new Response(JSON.stringify({ authShare: previous.shares.authShare }))
+            );
+            await expect(strategy.reconcileShares!(reconcileParams)).rejects.toThrow(
+                'valid share version'
+            );
+            expect(await readPendingShareCandidates(storage)).toEqual(candidates);
+        });
+
+        it('does not promote or retry for an account switched during pending resolution', async () => {
+            strategy.setActiveUser!('account-a');
+            let authShare = '';
+            const fetchMock = vi
+                .spyOn(globalThis, 'fetch')
+                .mockImplementation(async (_url, init) => {
+                    if (init?.method === 'PUT') {
+                        authShare = JSON.parse(String(init.body)).authShare.encryptedData;
+                        throw new TypeError('Lost reply');
+                    }
+                    if (authShare) strategy.setActiveUser!('account-b');
+                    return new Response(JSON.stringify({ authShare, shareVersion: 1 }));
+                });
+            await expect(strategy.atomicUpdateShares!(updateParams)).rejects.toMatchObject({
+                rolledBack: false,
+            });
+            const candidates = await readPendingShareCandidates(
+                storage,
+                'sss-device-share:account-a'
+            );
+            await expect(strategy.atomicUpdateShares!(updateParams)).rejects.toThrow(
+                'Active account changed'
+            );
+            expect(await readPendingShareCandidates(storage, 'sss-device-share:account-a')).toEqual(
+                candidates
+            );
+            expect(await strategy.getLocalKey()).toBeNull();
+            expect(fetchMock.mock.calls.filter(([, init]) => init?.method === 'PUT')).toHaveLength(
+                1
+            );
+        });
+
+        it('invalidates an older cached email share when promoting a device-only candidate', async () => {
+            const enabled = createSSSStrategy({
+                serverUrl: 'http://test-server:5100/api',
+                storage,
+                enableEmailBackupShare: true,
+                ...getTestRelayConfig(),
+            });
+            let authShare = '';
+            let version = 0;
+            const fetchMock = vi
+                .spyOn(globalThis, 'fetch')
+                .mockImplementation(async (_url, init) => {
+                    if (init?.method === 'PUT') {
+                        authShare = JSON.parse(String(init.body)).authShare.encryptedData;
+                        if (++version === 2) throw new TypeError('Lost reply');
+                    }
+                    return new Response(JSON.stringify({ authShare, shareVersion: version }));
+                });
+            await enabled.atomicUpdateShares!(updateParams);
+            await expect(enabled.atomicUpdateShares!(updateParams)).rejects.toMatchObject({
+                rolledBack: false,
+            });
+            expect(await enabled.reconcileShares!(reconcileParams)).toEqual({
+                privateKey,
+                did: expectedDid,
+            });
+            const calls = fetchMock.mock.calls.length;
+            await enabled.sendEmailBackupShare!(
+                'token',
+                'firebase',
+                privateKey,
+                'test@example.com'
+            );
+            expect(fetchMock.mock.calls).toHaveLength(calls);
+        });
+
+        it.each([false, true])(
+            'retries a write lost before the server after reload (existing=%s)',
+            async existing => {
+                const previous = await splitAndVerify(privateKey);
+                let authShare = existing ? previous.shares.authShare : null;
+                let version = existing ? 1 : 0;
+                if (existing) {
+                    await strategy.storeLocalKey(previous.shares.deviceShare);
+                    await strategy.storeLocalShareVersion!(version);
+                }
+                let puts = 0;
+                vi.spyOn(globalThis, 'fetch').mockImplementation(async (_url, init) => {
+                    if (init?.method === 'PUT') {
+                        if (++puts === 1) throw new TypeError('Lost before server');
+                        authShare = JSON.parse(String(init.body)).authShare.encryptedData;
+                        return new Response(JSON.stringify({ shareVersion: ++version }));
+                    }
+                    return authShare
+                        ? new Response(JSON.stringify({ authShare, shareVersion: version }))
+                        : new Response(null, { status: 404 });
+                });
+                await expect(strategy.atomicUpdateShares!(updateParams)).rejects.toMatchObject({
+                    rolledBack: false,
+                });
+                const reloaded = createSSSStrategy({
+                    serverUrl: 'http://test-server:5100/api',
+                    storage,
+                });
+                expect(await reloaded.reconcileShares!(reconcileParams)).toBeNull();
+                expect(await readPendingShareCandidates(storage)).toHaveLength(1);
+                await reloaded.atomicUpdateShares!(updateParams);
+                expect(puts).toBe(2);
+                expect(
+                    await reconstructFromShares([(await reloaded.getLocalKey())!, authShare!])
+                ).toBe(privateKey);
+                expect(await readPendingShareCandidates(storage)).toHaveLength(1);
+                expect(await reloaded.getLocalShareVersion!()).toBe(version);
+            }
+        );
+
+        it('promotes the first candidate when it lands after two indeterminate writes', async () => {
+            const writes: string[] = [];
+            let authShare: string | null = null;
+            vi.spyOn(globalThis, 'fetch').mockImplementation(async (_url, init) => {
+                if (init?.method === 'PUT') {
+                    writes.push(JSON.parse(String(init.body)).authShare.encryptedData);
+                    throw new TypeError('In flight');
+                }
+                return authShare
+                    ? new Response(JSON.stringify({ authShare, shareVersion: 1 }))
+                    : new Response(null, { status: 404 });
+            });
+            await expect(strategy.atomicUpdateShares!(updateParams)).rejects.toMatchObject({
+                rolledBack: false,
+            });
+            await expect(strategy.atomicUpdateShares!(updateParams)).rejects.toMatchObject({
+                rolledBack: false,
+            });
+            const candidates = await readPendingShareCandidates(storage);
+            expect(candidates).toHaveLength(2);
+            expect(await strategy.getLocalKey()).toBe(candidates[1]!.share);
+            authShare = writes[0]!;
+            expect(await strategy.reconcileShares!(reconcileParams)).toEqual({
+                privateKey,
+                did: expectedDid,
+            });
+            expect(await strategy.getLocalKey()).toBe(candidates[0]!.share);
+            expect(await readPendingShareCandidates(storage)).toEqual([candidates[1]]);
+        });
+
+        it.each([false, true])(
+            'checks expired candidates before dropping them (matching=%s)',
+            async matching => {
+                const old = await splitAndVerify(privateKey);
+                const live = await splitAndVerify(privateKey);
+                await writePendingShareCandidates(storage, [
+                    {
+                        share: old.shares.deviceShare,
+                        createdAt: Date.now() - PENDING_WRITE_EXPIRY_MS - 1,
+                    },
+                    { share: live.shares.deviceShare, createdAt: Date.now() },
+                ]);
+                vi.spyOn(globalThis, 'fetch').mockResolvedValue(
+                    matching
+                        ? new Response(
+                              JSON.stringify({ authShare: old.shares.authShare, shareVersion: 1 })
+                          )
+                        : new Response(null, { status: 404 })
+                );
+                const result = await strategy.reconcileShares!(reconcileParams);
+                if (matching) {
+                    expect(result).toEqual({ privateKey, did: expectedDid });
+                    expect(await strategy.getLocalKey()).toBe(old.shares.deviceShare);
+                    expect(
+                        (await readPendingShareCandidates(storage)).map(
+                            candidate => candidate.share
+                        )
+                    ).toEqual([live.shares.deviceShare]);
+                } else {
+                    expect(result).toBeNull();
+                    expect(
+                        (await readPendingShareCandidates(storage)).map(
+                            candidate => candidate.share
+                        )
+                    ).toEqual([live.shares.deviceShare]);
+                }
+            }
+        );
+
+        it.each([false, true])(
+            'resolves legacy raw candidates before expiry (matching=%s)',
+            async matching => {
+                const old = await splitAndVerify(privateKey);
+                await storage.storeDeviceShare(
+                    old.shares.deviceShare,
+                    'sss-pending-share:sss-device-share'
+                );
+                expect(await readPendingShareCandidates(storage)).toEqual([
+                    { share: old.shares.deviceShare, createdAt: 0 },
+                ]);
+                vi.spyOn(globalThis, 'fetch').mockResolvedValue(
+                    matching
+                        ? new Response(
+                              JSON.stringify({ authShare: old.shares.authShare, shareVersion: 1 })
+                          )
+                        : new Response(null, { status: 404 })
+                );
+                expect(await strategy.reconcileShares!(reconcileParams)).toEqual(
+                    matching ? { privateKey, did: expectedDid } : null
+                );
+                expect(await readPendingShareCandidates(storage)).toEqual([]);
+                expect(await strategy.getLocalKey()).toBe(matching ? old.shares.deviceShare : null);
+            }
+        );
+
+        it('removes only the new candidate on a definitive rejection', async () => {
+            let puts = 0;
+            vi.spyOn(globalThis, 'fetch').mockImplementation(async (_url, init) => {
+                if (init?.method === 'PUT') {
+                    if (++puts === 1) throw new TypeError('In flight');
+                    return new Response(null, { status: 403 });
+                }
+                return new Response(null, { status: 404 });
+            });
+            await expect(strategy.atomicUpdateShares!(updateParams)).rejects.toMatchObject({
+                rolledBack: false,
+            });
+            const candidates = await readPendingShareCandidates(storage);
+            await expect(strategy.atomicUpdateShares!(updateParams)).rejects.toMatchObject({
+                rolledBack: true,
+            });
+            expect(puts).toBe(2);
+            expect(await readPendingShareCandidates(storage)).toEqual(candidates);
+        });
+
+        it('caps live candidates without deleting them or sending another PUT', async () => {
+            const fetchMock = vi
+                .spyOn(globalThis, 'fetch')
+                .mockImplementation(async (_url, init) => {
+                    if (init?.method === 'PUT') throw new TypeError('In flight');
+                    return new Response(null, { status: 404 });
+                });
+            for (let i = 0; i < 8; i++) {
+                await expect(strategy.atomicUpdateShares!(updateParams)).rejects.toMatchObject({
+                    rolledBack: false,
+                });
+            }
+            const candidates = await readPendingShareCandidates(storage);
+            expect(candidates).toHaveLength(8);
+            await expect(strategy.atomicUpdateShares!(updateParams)).rejects.toMatchObject({
+                phase: 'store_device',
+            });
+            expect(await readPendingShareCandidates(storage)).toEqual(candidates);
+            expect(fetchMock.mock.calls.filter(([, init]) => init?.method === 'PUT')).toHaveLength(
+                8
+            );
+        });
+
+        it.each([false, true])(
+            'recovers a committed lost reply after reload without server history (existing=%s)',
+            async existing => {
+                strategy.setActiveUser!('lost-response-user');
+                if (existing) {
+                    const previous = await splitAndVerify(privateKey);
+                    await strategy.storeLocalKey(previous.shares.deviceShare);
+                    await strategy.storeLocalShareVersion!(1);
+                }
+
+                let committedAuthShare: string | null = null;
+                const version = existing ? 2 : 1;
+                const fetchMock = vi
+                    .spyOn(globalThis, 'fetch')
+                    .mockImplementation(async (_url, init) => {
+                        const body = JSON.parse(String(init?.body));
+                        if (init?.method === 'PUT') {
+                            committedAuthShare = body.authShare.encryptedData;
+                            throw new TypeError('Connection closed after commit');
+                        }
+                        if (body.shareVersion && body.shareVersion !== version) {
+                            return new Response(null, { status: 404 });
+                        }
+                        return new Response(
+                            JSON.stringify({
+                                authShare: committedAuthShare,
+                                primaryDid: expectedDid,
+                                shareVersion: version,
+                            })
+                        );
+                    });
+
+                await expect(
+                    strategy.atomicUpdateShares!({
+                        token: 'token',
+                        providerType: 'firebase',
+                        privateKey,
+                        did: expectedDid,
+                    })
+                ).rejects.toMatchObject({ rolledBack: false });
+
+                const reloaded = createSSSStrategy({
+                    serverUrl: 'http://test-server:5100/api',
+                    storage,
+                });
+                reloaded.setActiveUser!('lost-response-user');
+                expect(await reloaded.hasLocalKey()).toBe(true);
+                await reloaded.fetchServerKeyStatus('token', 'firebase');
+                expect(
+                    await reloaded.reconcileShares!({
+                        token: 'token',
+                        providerType: 'firebase',
+                        expectedDid,
+                        didFromPrivateKey: async key =>
+                            key === privateKey ? expectedDid : 'did:key:zWrong',
+                    })
+                ).toEqual({ privateKey, did: expectedDid });
+                expect(await reloaded.getLocalShareVersion!()).toBe(version);
+                expect(
+                    await reconstructFromShares([
+                        (await reloaded.getLocalKey())!,
+                        committedAuthShare!,
+                    ])
+                ).toBe(privateKey);
+                expect(
+                    fetchMock.mock.calls.filter(([, init]) => init?.method === 'PUT')
+                ).toHaveLength(1);
+            }
+        );
+
+        it.each(['initial setup', 'Web3Auth migration'])(
+            '%s restores the previous device share when the server write fails',
+            async () => {
+                const previous = await splitAndVerify(privateKey);
+
+                await strategy.storeLocalKey(previous.shares.deviceShare);
+                await strategy.storeLocalShareVersion!(4);
+
+                vi.spyOn(globalThis, 'fetch').mockImplementation(async (_url, init) =>
+                    init?.method === 'PUT'
+                        ? new Response(null, { status: 403, statusText: 'Forbidden' })
+                        : new Response(
+                              JSON.stringify({
+                                  authShare: previous.shares.authShare,
+                                  shareVersion: 4,
+                              })
+                          )
+                );
+
+                let thrown: unknown;
+                try {
+                    await strategy.atomicUpdateShares!({
+                        token: 'token',
+                        providerType: 'firebase',
+                        privateKey,
+                        did: expectedDid,
+                    });
+                } catch (error) {
+                    thrown = error;
+                }
+
+                expect(thrown).toBeInstanceOf(AtomicUpdateError);
+                expect((thrown as AtomicUpdateError).rolledBack).toBe(true);
+                expect(await strategy.getLocalKey()).toBe(previous.shares.deviceShare);
+                expect(await strategy.getLocalShareVersion!()).toBe(4);
+            }
+        );
+
+        it('setupRecoveryMethod restores the previous device share when auth-share rotation fails', async () => {
+            const previous = await splitAndVerify(privateKey);
+
+            await strategy.storeLocalKey(previous.shares.deviceShare);
+            await strategy.storeLocalShareVersion!(7);
+
+            vi.spyOn(globalThis, 'fetch').mockImplementation(async (_url, init) => {
+                const method = (init?.method ?? 'GET').toUpperCase();
+
+                if (method === 'POST') {
+                    return new Response(
+                        JSON.stringify({
+                            authShare: previous.shares.authShare,
+                            primaryDid: expectedDid,
+                            recoveryMethods: [],
+                            keyProvider: 'sss',
+                            shareVersion: 7,
+                        }),
+                        { status: 200 }
+                    );
+                }
+
+                return new Response(null, { status: 403, statusText: 'Forbidden' });
+            });
+
+            let thrown: unknown;
+            try {
+                await strategy.setupRecoveryMethod!({
+                    token: 'token',
+                    providerType: 'firebase',
+                    privateKey,
+                    input: { method: 'phrase' },
+                });
+            } catch (error) {
+                thrown = error;
+            }
+
+            expect(thrown).toBeInstanceOf(AtomicUpdateError);
+            expect((thrown as AtomicUpdateError).rolledBack).toBe(true);
+            expect(await strategy.getLocalKey()).toBe(previous.shares.deviceShare);
+            expect(await strategy.getLocalShareVersion!()).toBe(7);
+        });
+
+        it('executeRecovery preserves the previous device share on rejected rotation', async () => {
+            const recoverySource = await splitAndVerify(privateKey);
+            const previousDevice = 'previous-device-share';
+
+            await strategy.storeLocalKey(previousDevice);
+            await strategy.storeLocalShareVersion!(2);
+
+            vi.spyOn(globalThis, 'fetch').mockImplementation(async (_url, init) => {
+                const method = (init?.method ?? 'GET').toUpperCase();
+
+                if (method === 'POST') {
+                    return new Response(
+                        JSON.stringify({
+                            authShare: recoverySource.shares.authShare,
+                            primaryDid: expectedDid,
+                            recoveryMethods: [],
+                            keyProvider: 'sss',
+                            shareVersion: 2,
+                        }),
+                        { status: 200 }
+                    );
+                }
+
+                return new Response(null, { status: 403, statusText: 'Forbidden' });
+            });
+
+            let thrown: unknown;
+            try {
+                await strategy.executeRecovery({
+                    token: 'token',
+                    providerType: 'firebase',
+                    input: {
+                        method: 'email',
+                        emailShare: `0002${recoverySource.shares.emailShare}`,
+                    },
+                    didFromPrivateKey: async key =>
+                        key === privateKey ? expectedDid : 'did:key:zWrong',
+                });
+            } catch (error) {
+                thrown = error;
+            }
+
+            expect(thrown).toBeInstanceOf(AtomicUpdateError);
+            expect((thrown as AtomicUpdateError).rolledBack).toBe(true);
+            expect(await strategy.getLocalKey()).toBe(previousDevice);
+            expect(await strategy.getLocalShareVersion!()).toBe(2);
+        });
+
+        it('repairs an ack-lost server commit on the next login', async () => {
+            const versionOne = await splitAndVerify(privateKey);
+            const server = {
+                currentAuthShare: versionOne.shares.authShare,
+                previousAuthShares: new Map<number, string>(),
+                version: 1,
+                loseNextAck: true,
+            };
+
+            await strategy.storeLocalKey(versionOne.shares.deviceShare);
+            await strategy.storeLocalShareVersion!(1);
+
+            vi.spyOn(globalThis, 'fetch').mockImplementation(async (_url, init) => {
+                const method = (init?.method ?? 'GET').toUpperCase();
+                const body = init?.body ? JSON.parse(String(init.body)) : {};
+
+                if (method === 'PUT') {
+                    server.previousAuthShares.set(server.version, server.currentAuthShare);
+                    server.currentAuthShare = body.authShare.encryptedData;
+                    server.version += 1;
+
+                    if (server.loseNextAck) {
+                        server.loseNextAck = false;
+                        throw new Error('Connection closed after commit');
+                    }
+
+                    return new Response(
+                        JSON.stringify({ success: true, shareVersion: server.version }),
+                        { status: 200 }
+                    );
+                }
+
+                const requestedVersion = body.shareVersion as number | undefined;
+                const authShare = requestedVersion
+                    ? requestedVersion === server.version
+                        ? server.currentAuthShare
+                        : (server.previousAuthShares.get(requestedVersion) ?? null)
+                    : server.currentAuthShare;
+
+                return new Response(
+                    JSON.stringify({
+                        authShare,
+                        primaryDid: expectedDid,
+                        recoveryMethods: [],
+                        keyProvider: 'sss',
+                        shareVersion: server.version,
+                    }),
+                    { status: 200 }
+                );
+            });
+
+            await expect(
+                strategy.atomicUpdateShares!({
+                    token: 'token',
+                    providerType: 'firebase',
+                    privateKey,
+                    did: expectedDid,
+                })
+            ).rejects.toMatchObject({ rolledBack: false });
+
+            expect(await strategy.getLocalKey()).toBe(versionOne.shares.deviceShare);
+            expect(await strategy.getLocalShareVersion!()).toBe(1);
+            expect(server.version).toBe(2);
+
+            const status = await strategy.fetchServerKeyStatus('token', 'firebase');
+            const localShare = await strategy.getLocalKey();
+            const preRepairHealth = await verifyStoredShares(
+                {
+                    getDevice: async () => localShare,
+                    getAuth: async () => status.authShare,
+                },
+                expectedDid,
+                async key => (key === privateKey ? expectedDid : 'did:key:zWrong')
+            );
+
+            expect(preRepairHealth.healthy).toBe(true);
+            expect(status.shareVersion).toBe(2);
+            expect(await strategy.getLocalShareVersion!()).toBe(1);
+
+            const reconciled = await strategy.reconcileShares!({
+                token: 'token',
+                providerType: 'firebase',
+                expectedDid,
+                didFromPrivateKey: async key =>
+                    key === privateKey ? expectedDid : 'did:key:zWrong',
+            });
+
+            expect(reconciled).toEqual({ privateKey, did: expectedDid });
+            expect(server.version).toBe(2);
+            expect(await strategy.getLocalShareVersion!()).toBe(2);
+
+            const repairedDevice = await strategy.getLocalKey();
+            const repairedHealth = await verifyStoredShares(
+                {
+                    getDevice: async () => repairedDevice,
+                    getAuth: async () => server.currentAuthShare,
+                },
+                expectedDid,
+                async key => (key === privateKey ? expectedDid : 'did:key:zWrong')
+            );
+
+            expect(repairedHealth.healthy).toBe(true);
+        });
+    });
+
     // -----------------------------------------------------------------------
     // Versioned email share format edge cases
     // -----------------------------------------------------------------------
 
+    describe('buildRecoveryPhraseChallengeOptions', () => {
+        it('offers the answer plus decoys that never appear in the phrase', async () => {
+            const phrase = await shareToRecoveryPhrase('ab'.repeat(32));
+            const words = phrase.split(' ');
+            const indices = [2, 9];
+
+            const options = await buildRecoveryPhraseChallengeOptions(phrase, indices);
+
+            expect(options).toHaveLength(2);
+            options.forEach((choices, i) => {
+                expect(choices).toHaveLength(6);
+                expect(new Set(choices).size).toBe(6);
+                expect(choices).toContain(words[indices[i]!]);
+                expect(choices.filter(word => words.includes(word))).toEqual([words[indices[i]!]]);
+            });
+        });
+    });
+
+    describe('selectRecoveryPhraseChallengeIndices', () => {
+        it('rejects values in the partial tail before accepting uniform-range values', () => {
+            const randomValues = [0xffff_ffff, 3, 7, 9];
+            const getRandomValues = vi
+                .spyOn(crypto, 'getRandomValues')
+                .mockImplementation(array => {
+                    (array as Uint32Array)[0] = randomValues.shift()!;
+                    return array;
+                });
+
+            const indices = selectRecoveryPhraseChallengeIndices(10, 3);
+
+            expect(indices).toEqual([3, 7, 9]);
+            expect(indices.every(index => index >= 0 && index < 10)).toBe(true);
+            expect(getRandomValues.mock.calls.length).toBeGreaterThan(3);
+        });
+    });
+
     describe('formatVersionedEmailShare / parseVersionedEmailShare', () => {
         it('round-trip: format then parse recovers the original share and version', () => {
             const share = 'abcdef1234567890';