@learncard/sss-key-manager 0.2.0 → 0.2.1

package/src/escrow-vectors.test.ts

@@ -0,0 +1,198 @@
+// @vitest-environment node
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import { expect, it } from 'vitest';
+import { base64ToBuffer } from './crypto';
+
+import {
+    decryptEscrowBlob,
+    ESCROW_BLOB_INFO,
+    ESCROW_RELEASE_INFO,
+    encryptEscrowBlob,
+    generateEscrowKeyPair,
+    openEscrowRelease,
+    sealEscrowRelease,
+} from './escrow-crypto';
+import type { EscrowBlobPlaintext, EscrowEnvelope, EscrowReleasePlaintext } from './escrow-crypto';
+
+type KeyPair = Awaited<ReturnType<typeof generateEscrowKeyPair>>;
+interface Vectors {
+    // Public test-only keys, never used for real recovery data.
+    enclave: KeyPair;
+    client: KeyPair;
+    blobs: { plaintext: EscrowBlobPlaintext; envelope: EscrowEnvelope }[];
+    releases: { plaintext: EscrowReleasePlaintext; envelope: EscrowEnvelope }[];
+}
+
+it('decrypts shared TS/Rust escrow vectors (ESCROW_WRITE_VECTORS=1 regenerates)', async () => {
+    const directory = fileURLToPath(new URL('./__fixtures__/', import.meta.url));
+    const path = fileURLToPath(new URL('./__fixtures__/escrow-vectors.json', import.meta.url));
+
+    if (process.env.ESCROW_WRITE_VECTORS === '1') {
+        const enclave = await generateEscrowKeyPair();
+        const client = await generateEscrowKeyPair();
+        const inputs = [
+            { recoveryShare: 'ABCDE', did: 'did:example:legacy', shareVersion: 1 },
+            {
+                recoveryShare: `0001${'AB'.repeat(48)}`,
+                did: 'did:example:pin',
+                shareVersion: 42,
+                pinVerifier: 'CD'.repeat(32),
+            },
+            {
+                recoveryShare: 'ef'.repeat(2048),
+                did: `did:${'x'.repeat(2042)}😀`,
+                shareVersion: 9_007_199_254_740_992,
+            },
+        ];
+        const blobs = await Promise.all(
+            inputs.map(async (input, index) => {
+                const envelope = await encryptEscrowBlob(
+                    input,
+                    enclave.publicKey,
+                    `test-key.${index}`
+                );
+                return {
+                    plaintext: await decryptEscrowBlob(envelope, enclave.privateKey),
+                    envelope,
+                };
+            })
+        );
+        const releases = await Promise.all(
+            inputs.slice(0, 2).map(async (input, index) => {
+                const envelope = await sealEscrowRelease(
+                    { ...input, holdId: `hold-${index}.test_1` },
+                    client.publicKey
+                );
+                return {
+                    plaintext: await openEscrowRelease(envelope, client.privateKey),
+                    envelope,
+                };
+            })
+        );
+        const vectors: Vectors = { enclave, client, blobs, releases };
+        await mkdir(directory, { recursive: true });
+        await writeFile(path, `${JSON.stringify(vectors, null, 4)}\n`);
+    }
+
+    const vectors: Vectors = JSON.parse(await readFile(path, 'utf8'));
+    expect(vectors.blobs).toHaveLength(3);
+    expect(vectors.releases).toHaveLength(2);
+    for (const { plaintext, envelope } of vectors.blobs) {
+        await expect(decryptEscrowBlob(envelope, vectors.enclave.privateKey)).resolves.toEqual(
+            plaintext
+        );
+    }
+    for (const { plaintext, envelope } of vectors.releases) {
+        await expect(openEscrowRelease(envelope, vectors.client.privateKey)).resolves.toEqual(
+            plaintext
+        );
+    }
+});
+
+// Independent WebCrypto decryption exposes raw JSON before the production validator
+// normalizes it, so a numeric 1.0 cannot silently satisfy the integral-token assertion.
+const decryptRawJson = async (
+    envelope: EscrowEnvelope,
+    privateKey: string,
+    info: string
+): Promise<string> => {
+    const recipient = await crypto.subtle.importKey(
+        'pkcs8',
+        base64ToBuffer(privateKey),
+        { name: 'ECDH', namedCurve: 'P-256' },
+        false,
+        ['deriveBits']
+    );
+    const ephemeral = await crypto.subtle.importKey(
+        'raw',
+        base64ToBuffer(envelope.ephemeralPublicKey),
+        { name: 'ECDH', namedCurve: 'P-256' },
+        false,
+        []
+    );
+    const shared = await crypto.subtle.deriveBits(
+        { name: 'ECDH', public: ephemeral },
+        recipient,
+        256
+    );
+    const material = await crypto.subtle.importKey('raw', shared, 'HKDF', false, ['deriveKey']);
+    const key = await crypto.subtle.deriveKey(
+        {
+            name: 'HKDF',
+            hash: 'SHA-256',
+            salt: base64ToBuffer(envelope.salt),
+            info: new TextEncoder().encode(info),
+        },
+        material,
+        { name: 'AES-GCM', length: 256 },
+        false,
+        ['decrypt']
+    );
+    const plaintext = await crypto.subtle.decrypt(
+        {
+            name: 'AES-GCM',
+            iv: base64ToBuffer(envelope.iv),
+            additionalData: new TextEncoder().encode(
+                `${envelope.version}|${envelope.algorithm}|${envelope.keyId}`
+            ),
+        },
+        key,
+        base64ToBuffer(envelope.ciphertext)
+    );
+    return new TextDecoder().decode(plaintext);
+};
+
+it('opens Rust blobs and releases in WebCrypto and emits integral JSON share versions', async () => {
+    const ts: Vectors = JSON.parse(
+        await readFile(
+            fileURLToPath(new URL('./__fixtures__/escrow-vectors.json', import.meta.url)),
+            'utf8'
+        )
+    );
+    const rust: Omit<Vectors, 'client'> = JSON.parse(
+        await readFile(
+            fileURLToPath(new URL('./__fixtures__/escrow-vectors-rust.json', import.meta.url)),
+            'utf8'
+        )
+    );
+    expect(rust.blobs).toHaveLength(2);
+    expect(rust.releases).toHaveLength(2);
+
+    // Import Rust SPKI as well as PKCS#8, and verify the two exports describe one key.
+    const publicKey = await crypto.subtle.importKey(
+        'spki',
+        base64ToBuffer(rust.enclave.publicKey),
+        { name: 'ECDH', namedCurve: 'P-256' },
+        true,
+        []
+    );
+    const privateKey = await crypto.subtle.importKey(
+        'pkcs8',
+        base64ToBuffer(rust.enclave.privateKey),
+        { name: 'ECDH', namedCurve: 'P-256' },
+        true,
+        ['deriveBits']
+    );
+    const publicJwk = await crypto.subtle.exportKey('jwk', publicKey);
+    expect(await crypto.subtle.exportKey('jwk', privateKey)).toMatchObject({
+        crv: 'P-256',
+        x: publicJwk.x,
+        y: publicJwk.y,
+    });
+
+    for (const { plaintext, envelope } of rust.blobs) {
+        await expect(decryptEscrowBlob(envelope, rust.enclave.privateKey)).resolves.toEqual(
+            plaintext
+        );
+        const raw = await decryptRawJson(envelope, rust.enclave.privateKey, ESCROW_BLOB_INFO);
+        expect(raw).toMatch(new RegExp(`"shareVersion":${plaintext.shareVersion}[,}]`));
+        expect(JSON.parse(raw)).toEqual(plaintext);
+    }
+    for (const { plaintext, envelope } of rust.releases) {
+        await expect(openEscrowRelease(envelope, ts.client.privateKey)).resolves.toEqual(plaintext);
+        const raw = await decryptRawJson(envelope, ts.client.privateKey, ESCROW_RELEASE_INFO);
+        expect(raw).toMatch(new RegExp(`"shareVersion":${plaintext.shareVersion}[,}]`));
+        expect(JSON.parse(raw)).toEqual(plaintext);
+    }
+});

package/src/index.ts

@@ -77,8 +77,15 @@ export {
 
 export type { EscrowEnvelope, EscrowBlobPlaintext, EscrowReleasePlaintext } from './escrow-crypto';
 export { verifyEnclaveAttestation } from './escrow-attestation';
+export { verifyNitroAttestationDocument, NitroAttestationError } from './escrow-nitro-attestation';
+export type { NitroAttestationReason } from './escrow-nitro-attestation';
 export type { EscrowAttestationPolicy, EscrowHoldStatus, EscrowRecoveryStart } from './types';
-export type { EscrowEnrollmentOptions, EscrowEnrollmentState, EscrowPinStatus } from './types';
+export type {
+    EscrowEnrollmentOptions,
+    EscrowEnrollmentState,
+    EscrowBlobStaleReason,
+    EscrowPinStatus,
+} from './types';
 export {
     EscrowPinMismatchError,
     EscrowPinLockedError,

package/src/sss-session-writes.test.ts

@@ -61,7 +61,7 @@ describe('session-scoped enrollment writes', () => {
         vi.stubGlobal(
             'fetch',
             vi.fn(async (url: string) => {
-                if (url.endsWith('/attestation')) {
+                if (url.includes('/attestation?nonce=')) {
                     started.resolve();
                     return attestation.promise;
                 }
@@ -91,7 +91,7 @@ describe('session-scoped enrollment writes', () => {
                         return authWrite.promise;
                     }
                     if (url.endsWith('/challenge')) return response({ challenge: 'nonce' });
-                    if (url.endsWith('/attestation')) return response({ attestation: {} });
+                    if (url.includes('/attestation?nonce=')) return response({ attestation: {} });
                     return response(keyStatus);
                 })
             );

package/src/sss-strategy.test.ts

@@ -160,6 +160,7 @@ describe('escrow strategy', () => {
     let releasePolicy: 'hold' | 'pin';
     let consumed: boolean;
     let burned: string[];
+    let escrowStale: 'mode-mismatch' | 'key-rotated' | undefined;
     const hold = () => ({
         holdId: holdNumber <= 1 ? 'escrow-hold' : `escrow-hold-${holdNumber}`,
         status: cancelled ? 'cancelled' : 'pending',
@@ -190,6 +191,7 @@ describe('escrow strategy', () => {
         releasePolicy = 'hold';
         consumed = false;
         burned = [];
+        escrowStale = undefined;
         config = {
             serverUrl: 'https://test.example/api',
             storage,
@@ -225,6 +227,7 @@ describe('escrow strategy', () => {
                         attemptsRemaining,
                         ...(pinSalt ? { salt: pinSalt } : {}),
                     },
+                    ...(escrowStale ? { escrowStale } : {}),
                 });
             }
             if (path === '/keys/recovery' || path === '/keys/recovery/confirm')
@@ -266,6 +269,7 @@ describe('escrow strategy', () => {
                 blob = await decryptEscrowBlob(body.envelope, enclaveKeys.privateKey);
                 pinSalt = body.pinSalt;
                 attemptsRemaining = 10;
+                escrowStale = undefined;
                 expect(blob.did).toBe(did);
                 expect(blob.shareVersion).toBe(version);
                 expect(
@@ -480,7 +484,7 @@ describe('escrow strategy', () => {
         });
         methods[0].shareVersion = 1;
         expect(await strategy.getEscrowEnrollmentState!(params)).toMatchObject({
-            state: 'not-enrolled',
+            state: 'stale',
         });
         methods[0].shareVersion = version;
         methods[0].confirmedAt = undefined;
@@ -543,7 +547,7 @@ describe('escrow strategy', () => {
         await strategy.setupRecoveryMethod!({ ...params, input: { method: 'phrase' } });
         expect(config.onEscrowError).toHaveBeenCalledWith(
             expect.objectContaining({
-                message: 'Nitro attestation verification is not implemented yet',
+                message: 'Escrow attestation mode mismatch',
             })
         );
     });
@@ -571,6 +575,77 @@ describe('escrow strategy', () => {
         });
         expect(calls).toHaveLength(0);
     });
+    it('getEscrowEnrollmentState reports stale with a reason when the server flags the blob', async () => {
+        await strategy.ensureEscrowEnrollment!(params);
+        escrowStale = 'mode-mismatch';
+        expect(await strategy.getEscrowEnrollmentState!(params)).toMatchObject({
+            state: 'stale',
+            staleReason: 'mode-mismatch',
+        });
+        escrowStale = 'key-rotated';
+        expect(await strategy.getEscrowEnrollmentState!(params)).toMatchObject({
+            state: 'stale',
+            staleReason: 'key-rotated',
+        });
+    });
+    it('does not trigger the stale-repair path when the server reports no staleness', async () => {
+        await strategy.ensureEscrowEnrollment!(params);
+        calls = [];
+        await expect(strategy.ensureEscrowEnrollment!(params)).resolves.toEqual({
+            enrolled: true,
+            changed: false,
+        });
+        expect(calls.some(call => call.path === '/keys/escrow/attestation')).toBe(false);
+    });
+    it('rotates a stale enrollment through the normal rotation path, at most once per session', async () => {
+        await strategy.ensureEscrowEnrollment!(params);
+        escrowStale = 'mode-mismatch';
+        await expect(strategy.ensureEscrowEnrollment!(params)).resolves.toEqual({
+            enrolled: true,
+            changed: true,
+            shareVersion: 3,
+        });
+        expect(version).toBe(3);
+        expect(blob?.shareVersion).toBe(3);
+        // A real re-enroll clears server-side staleness (the mock's '/keys/escrow'
+        // handler already reset it); force it stale again so this assertion proves
+        // the session-scoped rate limit — not the mock's own healing — stops the retry.
+        escrowStale = 'mode-mismatch';
+        calls = [];
+        await expect(strategy.ensureEscrowEnrollment!(params)).resolves.toEqual({
+            enrolled: true,
+            changed: false,
+        });
+        expect(calls.some(call => call.path === '/keys/escrow/attestation')).toBe(false);
+        expect(version).toBe(3);
+        // A fresh strategy instance (the next app session) attempts the repair again.
+        const nextSession = createSSSStrategy(config);
+        await expect(nextSession.ensureEscrowEnrollment!(params)).resolves.toEqual({
+            enrolled: true,
+            changed: true,
+            shareVersion: 4,
+        });
+        expect(version).toBe(4);
+    });
+    it('swallows a failed automatic stale-blob repair instead of throwing to the caller', async () => {
+        await strategy.ensureEscrowEnrollment!(params);
+        escrowStale = 'key-rotated';
+        attestationFailure = true;
+        await expect(strategy.ensureEscrowEnrollment!(params)).resolves.toEqual({
+            enrolled: true,
+            changed: false,
+        });
+        expect(version).toBe(2);
+        expect(config.onEscrowError).toHaveBeenCalledOnce();
+        vi.mocked(config.onEscrowError!).mockClear();
+        // Still rate-limited to one attempt this session, even though it failed.
+        await expect(strategy.ensureEscrowEnrollment!(params)).resolves.toEqual({
+            enrolled: true,
+            changed: false,
+        });
+        expect(config.onEscrowError).not.toHaveBeenCalled();
+        expect(version).toBe(2);
+    });
     it('requires DID verification before attempting PIN recovery', async () => {
         await expect(
             strategy.executeRecovery({
@@ -585,6 +660,24 @@ describe('escrow strategy', () => {
         expect(storage.clearAllShares).not.toHaveBeenCalled();
         expect(strategy.hasPendingIdentityRecovery!()).toBe(false);
     });
+    it.each(['set', 'clear'] as const)(
+        'rejects explicit %s PIN on a stale account when the enclave is unreachable',
+        async action => {
+            await strategy.ensureEscrowEnrollment!(params);
+            escrowStale = 'key-rotated';
+            attestationFailure = true;
+            await expect(
+                action === 'set'
+                    ? strategy.setEscrowPin!({ ...params, pin: '135790' })
+                    : strategy.clearEscrowPin!(params)
+            ).rejects.toThrow();
+            expect(version).toBe(2);
+            expect(config.onEscrowError).not.toHaveBeenCalled();
+            // Explicit actions must not consume the automatic repair attempt.
+            await strategy.ensureEscrowEnrollment!(params);
+            expect(config.onEscrowError).toHaveBeenCalledOnce();
+        }
+    );
     const recoverPin = (pin = '135790') =>
         strategy.executeRecovery({
             ...params,

package/src/sss-strategy.ts

@@ -1054,6 +1054,10 @@ export function createSSSStrategy(config: SSSStrategyConfig): SSSKeyDerivationSt
     } | null = null;
 
     let escrowEnrollmentInFlight: Promise<EscrowEnrollmentResult> | undefined;
+    // A stale-blob repair is attempted at most once per strategy instance
+    // (i.e. once per app session); a failed attempt is logged and left for
+    // the next session rather than retried on every subsequent call.
+    let staleEscrowReenrollAttempted = false;
 
     // Material from a rotation whose escrow POST failed. Retained in memory so a
     // retry within this session re-posts instead of burning another share version.
@@ -1143,11 +1147,16 @@ export function createSSSStrategy(config: SSSStrategyConfig): SSSKeyDerivationSt
 
     const fetchVerifiedEnclaveKey = async (): Promise<{ publicKey: string; keyId: string }> => {
         if (!config.escrow?.enabled) throw new Error('Escrow enrollment is disabled');
-        const { attestation } = await escrowRequest<{ attestation: unknown }>('/attestation', {
-            method: 'GET',
-            headers: buildHeaders('', undefined, tenantId),
-        });
-        return verifyEnclaveAttestation(attestation, config.escrow.attestation);
+        const nonce = crypto.getRandomValues(new Uint8Array(32));
+        const nonceHex = Array.from(nonce, byte => byte.toString(16).padStart(2, '0')).join('');
+        const { attestation } = await escrowRequest<{ attestation: unknown }>(
+            `/attestation?nonce=${nonceHex}`,
+            {
+                method: 'GET',
+                headers: buildHeaders('', undefined, tenantId),
+            }
+        );
+        return verifyEnclaveAttestation(attestation, config.escrow.attestation, nonce);
     };
 
     const enrollEscrow = async (
@@ -1231,9 +1240,7 @@ export function createSSSStrategy(config: SSSStrategyConfig): SSSKeyDerivationSt
         }
         const status = await self.fetchServerKeyStatus(params.token, params.providerType);
         if (status.escrowOptedOut) return { enrolled: false, reason: 'opted-out' };
-        if (
-            !forceRotate &&
-            pin === undefined &&
+        const currentlyEnrolled =
             status.shareVersion !== null &&
             status.recoveryMethods.some(
                 method =>
@@ -1242,87 +1249,113 @@ export function createSSSStrategy(config: SSSStrategyConfig): SSSKeyDerivationSt
                     (Boolean(method.confirmedAt) ||
                         ('confirmationStatus' in method &&
                             method.confirmationStatus === 'confirmed'))
-            )
-        )
+            );
+        // A confirmed enrollment whose sealed blob no longer matches the active
+        // enclave (P6 mode migration/rollback, or a rotated enclave key) still
+        // needs the same rotation a missing enrollment would get — but only one
+        // automatic attempt per session, so a still-unreachable enclave doesn't
+        // retry on every ensureEscrowEnrollment call within the same session.
+        const repairingStaleBlob =
+            pin === undefined &&
+            !forceRotate &&
+            currentlyEnrolled &&
+            !!status.escrowStale &&
+            !staleEscrowReenrollAttempted;
+        if (!forceRotate && pin === undefined && currentlyEnrolled && !repairingStaleBlob)
             // Automatic repair preserves current enrollment regardless of PIN status.
             // The enclave can carry an existing verifier when shares rotate.
             return { enrolled: true, changed: false };
+        if (repairingStaleBlob) staleEscrowReenrollAttempted = true;
         if (!status.primaryDid) throw new Error('Cannot enroll escrow without a primary DID');
         if (!params.signDidAuthVp) {
             throw new Error('DID proof signing is required for escrow enrollment');
         }
-        if (
-            !forceRotate &&
-            pin === undefined &&
-            unenrolledRotation &&
-            unenrolledRotation.shareVersion === status.shareVersion &&
-            unenrolledRotation.primaryDid === status.primaryDid
-        ) {
-            const retry = unenrolledRotation;
+        try {
+            if (
+                !forceRotate &&
+                pin === undefined &&
+                unenrolledRotation &&
+                unenrolledRotation.shareVersion === status.shareVersion &&
+                unenrolledRotation.primaryDid === status.primaryDid
+            ) {
+                const retry = unenrolledRotation;
+                await enrollEscrow(
+                    params.token,
+                    params.providerType,
+                    params.privateKey,
+                    retry.primaryDid,
+                    retry.shares,
+                    retry.shareVersion,
+                    params.signDidAuthVp,
+                    undefined,
+                    undefined,
+                    retry.clearPin
+                );
+                unenrolledRotation = undefined;
+                return { enrolled: true, changed: true, shareVersion: retry.shareVersion };
+            }
+            // Verify the enclave before rotating: a bad attestation must not burn
+            // a share version (and, repeated, the retained auth-share history).
+            const verifiedKey = await fetchVerifiedEnclaveKey();
+            const pinSalt = pin !== undefined ? generatePinSalt() : undefined;
+            const pinMaterial =
+                pin !== undefined && pinSalt !== undefined
+                    ? { pinSalt, pinVerifier: await derivePinProof(pin, pinSalt) }
+                    : undefined;
+            const storageId = activeStorageId;
+            const primaryDid = status.primaryDid;
+            const { shares, shareVersion } = await withShareUpdateLock(storage, storageId, () =>
+                persistSharesWithoutLock(
+                    params.privateKey,
+                    serverUrl,
+                    params.token,
+                    params.providerType,
+                    primaryDid,
+                    storage,
+                    storageId,
+                    undefined,
+                    params.signDidAuthVp,
+                    tenantId
+                )
+            );
+            lastEmailShare = shares.emailShare;
+            lastShareVersion = shareVersion;
+            lastServerSnapshot = {
+                currentVersion: shareVersion,
+                resolvedVersion: shareVersion,
+                authShare: shares.authShare,
+                primaryDid: status.primaryDid,
+            };
+            unenrolledRotation = pinMaterial
+                ? undefined
+                : { shares, shareVersion, primaryDid: status.primaryDid, clearPin: forceRotate };
             await enrollEscrow(
                 params.token,
                 params.providerType,
                 params.privateKey,
-                retry.primaryDid,
-                retry.shares,
-                retry.shareVersion,
+                status.primaryDid,
+                shares,
+                shareVersion,
                 params.signDidAuthVp,
-                undefined,
-                undefined,
-                retry.clearPin
+                verifiedKey,
+                pinMaterial,
+                forceRotate
             );
             unenrolledRotation = undefined;
-            return { enrolled: true, changed: true, shareVersion: retry.shareVersion };
+            return { enrolled: true, changed: true, shareVersion };
+        } catch (err) {
+            // A background repair the caller never asked for must not surface as
+            // a hard failure (mirrors tryEnrollEscrow's existing swallow-and-report
+            // shape); an explicit not-yet-enrolled/PIN/forced rotation still throws.
+            if (!repairingStaleBlob) throw err;
+            try {
+                if (config.onEscrowError) config.onEscrowError(err);
+                else console.warn('SSS: escrow enrollment failed');
+            } catch {
+                console.warn('SSS: escrow error reporting failed');
+            }
+            return { enrolled: true, changed: false };
         }
-        // Verify the enclave before rotating: a bad attestation must not burn
-        // a share version (and, repeated, the retained auth-share history).
-        const verifiedKey = await fetchVerifiedEnclaveKey();
-        const pinSalt = pin !== undefined ? generatePinSalt() : undefined;
-        const pinMaterial =
-            pin !== undefined && pinSalt !== undefined
-                ? { pinSalt, pinVerifier: await derivePinProof(pin, pinSalt) }
-                : undefined;
-        const storageId = activeStorageId;
-        const primaryDid = status.primaryDid;
-        const { shares, shareVersion } = await withShareUpdateLock(storage, storageId, () =>
-            persistSharesWithoutLock(
-                params.privateKey,
-                serverUrl,
-                params.token,
-                params.providerType,
-                primaryDid,
-                storage,
-                storageId,
-                undefined,
-                params.signDidAuthVp,
-                tenantId
-            )
-        );
-        lastEmailShare = shares.emailShare;
-        lastShareVersion = shareVersion;
-        lastServerSnapshot = {
-            currentVersion: shareVersion,
-            resolvedVersion: shareVersion,
-            authShare: shares.authShare,
-            primaryDid: status.primaryDid,
-        };
-        unenrolledRotation = pinMaterial
-            ? undefined
-            : { shares, shareVersion, primaryDid: status.primaryDid, clearPin: forceRotate };
-        await enrollEscrow(
-            params.token,
-            params.providerType,
-            params.privateKey,
-            status.primaryDid,
-            shares,
-            shareVersion,
-            params.signDidAuthVp,
-            verifiedKey,
-            pinMaterial,
-            forceRotate
-        );
-        unenrolledRotation = undefined;
-        return { enrolled: true, changed: true, shareVersion };
     };
 
     const recordPromotion =
@@ -1740,6 +1773,7 @@ export function createSSSStrategy(config: SSSStrategyConfig): SSSKeyDerivationSt
                 maskedRecoveryEmail: data.maskedRecoveryEmail ?? null,
                 escrowOptedOut: data.escrowOptedOut === true,
                 escrowPin: data.escrowPin,
+                escrowStale: data.escrowStale,
                 sssActivationState: data.sssActivationState ?? 'active',
             };
         },
@@ -1810,19 +1844,25 @@ export function createSSSStrategy(config: SSSStrategyConfig): SSSKeyDerivationSt
             if (!config.escrow?.enabled) return { state: 'disabled' };
             const status = await this.fetchServerKeyStatus(params.token, params.providerType);
             if (status.escrowOptedOut) return { state: 'opted-out', escrowPin: status.escrowPin };
-            const state =
+            const confirmedEscrow = status.recoveryMethods.filter(
+                method =>
+                    method.type === 'escrow' &&
+                    (Boolean(method.confirmedAt) ||
+                        ('confirmationStatus' in method &&
+                            method.confirmationStatus === 'confirmed'))
+            );
+            const enrolled =
                 status.shareVersion !== null &&
-                status.recoveryMethods.some(
-                    method =>
-                        method.type === 'escrow' &&
-                        method.shareVersion === status.shareVersion &&
-                        (Boolean(method.confirmedAt) ||
-                            ('confirmationStatus' in method &&
-                                method.confirmationStatus === 'confirmed'))
-                )
-                    ? 'enrolled'
-                    : 'not-enrolled';
-            return { state, escrowPin: status.escrowPin };
+                confirmedEscrow.some(method => method.shareVersion === status.shareVersion);
+            // Previously enrolled accounts must bypass the new-enrollment rollout
+            // even when a rotation succeeded but resealing the escrow blob failed.
+            if (confirmedEscrow.length > 0 && (!enrolled || status.escrowStale))
+                return {
+                    state: 'stale',
+                    escrowPin: status.escrowPin,
+                    staleReason: status.escrowStale,
+                };
+            return { state: enrolled ? 'enrolled' : 'not-enrolled', escrowPin: status.escrowPin };
         },
 
         async disableEscrowRecovery(params): Promise<void> {
@@ -1878,7 +1918,7 @@ export function createSSSStrategy(config: SSSStrategyConfig): SSSKeyDerivationSt
             const result = await withRotationLock(() =>
                 ensureEscrowEnrollmentUnguarded(this, { ...params, options: { pin } }, storage)
             );
-            if (!result.enrolled) {
+            if (!result.enrolled || !result.changed) {
                 throw new Error('Automatic recovery is not available for this account.');
             }
         },
@@ -1888,7 +1928,7 @@ export function createSSSStrategy(config: SSSStrategyConfig): SSSKeyDerivationSt
             const result = await withRotationLock(() =>
                 ensureEscrowEnrollmentUnguarded(this, params, storage, true)
             );
-            if (!result.enrolled) {
+            if (!result.enrolled || !result.changed) {
                 throw new Error('Automatic recovery is not available for this account.');
             }
         },