@learncard/sss-key-manager 0.2.3 → 0.2.5

package/src/sss-strategy.test.ts

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

package/src/sss-strategy.ts

@@ -108,6 +108,16 @@ const SSS_DB_NAME = 'lcb-sss-keys';
 const DEFAULT_DEVICE_SHARE_ID = 'sss-device-share';
 const MAX_RECONCILIATION_HISTORY = 5;
 
+/**
+ * OFF by default. Every input to the uncarryable-PIN inference (recovery methods,
+ * share version, PIN state) comes from lca-api, so a compromised API could forge it
+ * for a healthy PIN account and have the client sign away the PIN path (Custard7's
+ * PR #1815 review). With it off the strategy returns `pin-reset-required` and the
+ * app asks the user to set a new PIN. Enabling it needs an independently trustworthy
+ * recovery signal and security sign-off: POST_RECOVERY_ESCROW_REPAIR_DESIGN.md, Q1.
+ */
+export const DEFAULT_AUTO_CLEAR_UNCARRYABLE_PIN = false;
+
 export interface SSSStorageFunctions {
     storeDeviceShare: (share: string, id?: string) => Promise<void>;
     getDeviceShare: (id?: string) => Promise<string | null>;
@@ -125,6 +135,22 @@ export interface SSSStrategyConfig {
     /** Report enrollment failures without logging recovery material. */
     onEscrowError?: (err: unknown) => void;
 
+    /**
+     * Nitro repair only: when the signed authority still has a PIN but lca-api holds
+     * no PIN to carry (an identity-recovery rebind deleted it), sign a PIN `clear`
+     * instead of a `carry` that lca-api would reject with PRECONDITION_FAILED.
+     * Defaults to {@link DEFAULT_AUTO_CLEAR_UNCARRYABLE_PIN} (off). Do not enable
+     * without security sign-off: POST_RECOVERY_ESCROW_REPAIR_DESIGN.md, open question Q1.
+     */
+    autoClearUncarryablePin?: boolean;
+
+    /**
+     * Called once after every committed automatic PIN clear
+     * ({@link SSSStrategyConfig.autoClearUncarryablePin}). Must not throw; defaults
+     * to a console warning. Never receives the DID, email or PIN material.
+     */
+    onEscrowPinAutoCleared?: (event: EscrowPinAutoClearedEvent) => void;
+
     /** Server URL for key share operations */
     serverUrl: string;
 
@@ -193,9 +219,18 @@ const describeHttpStatus = (response: Response): string =>
     response.statusText ? `${response.status} ${response.statusText}` : `${response.status}`;
 
 type EscrowEnrollmentResult =
-    | { enrolled: false; reason: 'disabled' | 'opted-out' }
+    | { enrolled: false; reason: 'disabled' | 'opted-out' | 'not-enrolled' | 'pin-reset-required' }
     | { enrolled: true; changed: false }
-    | { enrolled: true; changed: true; shareVersion: number };
+    | { enrolled: true; changed: true; shareVersion: number; pinCleared?: 'automatic' };
+
+/** Telemetry for an automatic post-rebind PIN clear. Carries no DID, email or PIN data. */
+export interface EscrowPinAutoClearedEvent {
+    type: 'escrow.pin.auto_cleared';
+    /** Share version the PIN-free enrollment was committed at. */
+    shareVersion: number;
+    /** Share version the signed authority was still active at (pre-rebind). */
+    authorityShareVersion: number | null;
+}
 
 /** HTTP failure metadata without potentially sensitive server response text. */
 export class EscrowRequestError extends Error {
@@ -208,6 +243,14 @@ export class EscrowRequestError extends Error {
     }
 }
 
+/** Independently generated splits can reuse a share's final-byte x-coordinate. */
+export class DuplicateShareCoordinateError extends Error {
+    constructor() {
+        super('Stored shares have the same coordinate and cannot be combined');
+        this.name = 'DuplicateShareCoordinateError';
+    }
+}
+
 const fetchAuthShareRaw = async (
     serverUrl: string,
     token: string,
@@ -1065,6 +1108,8 @@ export function createSSSStrategy(config: SSSStrategyConfig): SSSKeyDerivationSt
               recoveryShare: string;
               authShare: string;
               rebindSessionToken: string;
+              /** Recovered from an existing escrow enrollment (hold or PIN), not another method. */
+              fromEscrow: boolean;
               rebind?: { shares: SSSShares; storageId: string | undefined; attempted: boolean };
           }
         | undefined;
@@ -1421,10 +1466,11 @@ export function createSSSStrategy(config: SSSStrategyConfig): SSSKeyDerivationSt
         }
     };
 
-    const tryEnrollEscrow = async (...args: Parameters<typeof enrollEscrow>): Promise<void> => {
-        if (!config.escrow?.enabled) return;
+    const tryEnrollEscrow = async (...args: Parameters<typeof enrollEscrow>): Promise<boolean> => {
+        if (!config.escrow?.enabled) return false;
         try {
             await enrollEscrow(...args);
+            return true;
         } catch (err) {
             // A reporting callback must not turn a successful rotation into a failure.
             try {
@@ -1433,7 +1479,28 @@ export function createSSSStrategy(config: SSSStrategyConfig): SSSKeyDerivationSt
             } catch {
                 console.warn('SSS: escrow error reporting failed');
             }
+            return false;
+        }
+    };
+
+    /** Report a committed automatic PIN clear so the caller can prompt for a new PIN. */
+    const withAutoClear = (
+        shareVersion: number,
+        autoClearedFrom: { authorityShareVersion: number | null } | undefined
+    ): EscrowEnrollmentResult => {
+        if (!autoClearedFrom) return { enrolled: true, changed: true, shareVersion };
+        try {
+            const event: EscrowPinAutoClearedEvent = {
+                type: 'escrow.pin.auto_cleared',
+                shareVersion,
+                authorityShareVersion: autoClearedFrom.authorityShareVersion,
+            };
+            if (config.onEscrowPinAutoCleared) config.onEscrowPinAutoCleared(event);
+            else console.warn('SSS: escrow PIN cleared automatically', event);
+        } catch {
+            console.warn('SSS: escrow event reporting failed');
         }
+        return { enrolled: true, changed: true, shareVersion, pinCleared: 'automatic' };
     };
 
     const ensureEscrowEnrollmentUnguarded = async (
@@ -1443,7 +1510,8 @@ export function createSSSStrategy(config: SSSStrategyConfig): SSSKeyDerivationSt
         forceRotate = false,
         allowDisabledEnrollment = false
     ): Promise<EscrowEnrollmentResult> => {
-        let clearPinForEnrollment = forceRotate;
+        let clearPinForEnrollment = forceRotate || params.options?.clearPin === true;
+        let autoClearedFrom: { authorityShareVersion: number | null } | undefined;
         if (!config.escrow?.enabled) return { enrolled: false, reason: 'disabled' };
         const pin = params.options?.pin;
         const recoveryEmail = params.options?.recoveryEmail ?? '';
@@ -1470,7 +1538,15 @@ export function createSSSStrategy(config: SSSStrategyConfig): SSSKeyDerivationSt
                         ('confirmationStatus' in method &&
                             method.confirmationStatus === 'confirmed'))
             );
+        if (
+            params.options?.requirePriorEnrollment &&
+            config.escrow.attestation.mode !== 'nitro' &&
+            !status.recoveryMethods.some(method => method.type === 'escrow')
+        )
+            return { enrolled: false, reason: 'not-enrolled' };
         let verifiedKey: VerifiedEnclaveIdentity | undefined;
+        // Locked, stale or unknown PIN state never satisfies a clear request.
+        let hasPin = status.escrowPin?.state !== 'none';
         if (config.escrow.attestation.mode === 'nitro') {
             if (!status.primaryDid || !params.signDidAuthVp)
                 throw new Error('Owner proof signing is required for escrow enrollment.');
@@ -1484,6 +1560,9 @@ export function createSSSStrategy(config: SSSStrategyConfig): SSSKeyDerivationSt
                 verifiedKey,
                 storage.assertCurrent
             );
+            // The signed authority survives the identity rebind that drops Mongo's blob.
+            if (params.options?.requirePriorEnrollment && current.status === 'empty')
+                return { enrolled: false, reason: 'not-enrolled' };
             if (current.status === 'disabled') {
                 verifiedEscrowEnvelope = undefined;
                 if (!allowDisabledEnrollment) return { enrolled: false, reason: 'opted-out' };
@@ -1496,7 +1575,51 @@ export function createSSSStrategy(config: SSSStrategyConfig): SSSKeyDerivationSt
                 current.shareVersion === status.shareVersion &&
                 current.envelope?.keyId === verifiedKey.keyId;
             if (currentlyEnrolled) verifiedEscrowEnvelope = current.envelope ?? undefined;
+            hasPin = current.hasPin;
+            // After an identity-recovery rebind lca-api has no PIN left to carry, so an
+            // automatic carry/keep can only fail.
+            const uncarryablePin =
+                !clearPinForEnrollment &&
+                current.status === 'active' &&
+                current.hasPin &&
+                pin === undefined &&
+                !currentlyEnrolled &&
+                status.escrowPin?.state === 'none';
+            // Opt-in only (design doc Q1): sign a clear instead. Rebind evidence: the
+            // signed authority is still active at an older share version, and lca-api
+            // lists no confirmed escrow method at any version. All but the authority
+            // are lca-api claims, so this is forgeable by a compromised API.
+            if (
+                uncarryablePin &&
+                (config.autoClearUncarryablePin ?? DEFAULT_AUTO_CLEAR_UNCARRYABLE_PIN) &&
+                current.shareVersion !== null &&
+                status.shareVersion !== null &&
+                current.shareVersion < status.shareVersion &&
+                !status.recoveryMethods.some(
+                    method =>
+                        method.type === 'escrow' &&
+                        (Boolean(method.confirmedAt) ||
+                            ('confirmationStatus' in method &&
+                                method.confirmationStatus === 'confirmed'))
+                )
+            ) {
+                clearPinForEnrollment = true;
+                autoClearedFrom = { authorityShareVersion: current.shareVersion };
+            } else if (uncarryablePin) {
+                // Never rotate or sign here: only a user-chosen PIN (`set`) resolves it.
+                return { enrolled: false, reason: 'pin-reset-required' };
+            }
         }
+        // A current, PIN-free enrollment already satisfies a clear request
+        // (e.g. post-recovery repair after direct enrollment succeeded).
+        if (
+            currentlyEnrolled &&
+            !forceRotate &&
+            pin === undefined &&
+            !hasPin &&
+            !status.escrowStale
+        )
+            clearPinForEnrollment = false;
         // 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
@@ -1519,7 +1642,7 @@ export function createSSSStrategy(config: SSSStrategyConfig): SSSKeyDerivationSt
         }
         try {
             if (
-                !clearPinForEnrollment &&
+                !forceRotate &&
                 pin === undefined &&
                 unenrolledRotation &&
                 unenrolledRotation.shareVersion === status.shareVersion &&
@@ -1536,13 +1659,13 @@ export function createSSSStrategy(config: SSSStrategyConfig): SSSKeyDerivationSt
                     params.signDidAuthVp,
                     undefined,
                     undefined,
-                    retry.clearPin,
+                    clearPinForEnrollment || retry.clearPin,
                     storage.assertCurrent,
                     recoveryEmail,
                     recoveryLanguage
                 );
                 unenrolledRotation = undefined;
-                return { enrolled: true, changed: true, shareVersion: retry.shareVersion };
+                return withAutoClear(retry.shareVersion, autoClearedFrom);
             }
             // Verify the enclave before rotating: a bad attestation must not burn
             // a share version (and, repeated, the retained auth-share history).
@@ -1601,7 +1724,7 @@ export function createSSSStrategy(config: SSSStrategyConfig): SSSKeyDerivationSt
                 recoveryLanguage
             );
             unenrolledRotation = undefined;
-            return { enrolled: true, changed: true, shareVersion };
+            return withAutoClear(shareVersion, autoClearedFrom);
         } catch (err) {
             // A background repair the caller never asked for must not surface as
             // a hard failure (mirrors tryEnrollEscrow's existing swallow-and-report
@@ -1737,6 +1860,16 @@ export function createSSSStrategy(config: SSSStrategyConfig): SSSKeyDerivationSt
         },
 
         async reconstructKey(localKey: string, remoteKey: string): Promise<string> {
+            const coordinate = localKey.slice(-2).toLowerCase();
+            if (
+                localKey.length === remoteKey.length &&
+                /^(?:[0-9a-f]{2}){2,}$/i.test(localKey) &&
+                /^(?:[0-9a-f]{2}){2,}$/i.test(remoteKey) &&
+                coordinate !== '00' &&
+                coordinate === remoteKey.slice(-2).toLowerCase()
+            ) {
+                throw new DuplicateShareCoordinateError();
+            }
             return reconstructFromShares([localKey, remoteKey]);
         },
 
@@ -2036,6 +2169,9 @@ export function createSSSStrategy(config: SSSStrategyConfig): SSSKeyDerivationSt
                 escrowPin: data.escrowPin,
                 escrowStale: data.escrowStale,
                 sssActivationState: data.sssActivationState ?? 'active',
+                ...(typeof data.priorEscrowEnrollment === 'boolean'
+                    ? { priorEscrowEnrollment: data.priorEscrowEnrollment }
+                    : {}),
             };
         },
 
@@ -2123,7 +2259,19 @@ export function createSSSStrategy(config: SSSStrategyConfig): SSSKeyDerivationSt
                     escrowPin: status.escrowPin,
                     staleReason: status.escrowStale,
                 };
-            return { state: enrolled ? 'enrolled' : 'not-enrolled', escrowPin: status.escrowPin };
+            if (enrolled) return { state: 'enrolled', escrowPin: status.escrowPin };
+            // A rebind leaves escrow methods `pending`, which /keys/auth-share omits but
+            // reports as priorEscrowEnrollment; flag them so the caller can request a
+            // prior-enrollment repair instead of a first-time enrollment. Older servers
+            // lack the field, so fall back to the (confirmed-only) method list.
+            const priorEscrowMethod =
+                status.priorEscrowEnrollment ??
+                status.recoveryMethods.some(method => method.type === 'escrow');
+            return {
+                state: 'not-enrolled',
+                escrowPin: status.escrowPin,
+                ...(priorEscrowMethod ? { priorEscrowMethod: true } : {}),
+            };
         },
 
         async disableEscrowRecovery(params): Promise<void> {
@@ -2220,7 +2368,20 @@ export function createSSSStrategy(config: SSSStrategyConfig): SSSKeyDerivationSt
                         providerType: params.providerType,
                     }),
                 });
-                return ensureEscrowEnrollmentUnguarded(this, params, storage, false, true);
+                const result = await ensureEscrowEnrollmentUnguarded(
+                    this,
+                    params,
+                    storage,
+                    false,
+                    true
+                );
+                // Explicit enable never requests prior-enrollment-only repair.
+                if (result.enrolled) return result;
+                if (result.reason === 'not-enrolled')
+                    throw new Error('Escrow enrollment did not complete');
+                if (result.reason === 'pin-reset-required')
+                    throw new Error('Set a new recovery PIN to turn on automatic recovery.');
+                return { enrolled: false as const, reason: result.reason };
             });
         },
 
@@ -2478,6 +2639,7 @@ export function createSSSStrategy(config: SSSStrategyConfig): SSSKeyDerivationSt
             input: RecoveryInput;
             didFromPrivateKey?: (privateKey: string) => Promise<string>;
             signDidAuthVp?: DidAuthVpSigner;
+            options?: { recoveryEmail?: string; recoveryLanguage?: string };
         }): Promise<RecoveryResult> {
             const storage = guardedStorage();
             const { token, providerType, input, didFromPrivateKey, signDidAuthVp } = params;
@@ -2565,11 +2727,17 @@ export function createSSSStrategy(config: SSSStrategyConfig): SSSKeyDerivationSt
                     recoveryShare: plaintext.recoveryShare,
                     authShare,
                     rebindSessionToken: material.rebindSessionToken,
+                    fromEscrow: true,
                 };
                 // The OTP path uses exactly this pending state and atomic rebind operation.
                 // Without a provider session the caller completes it after signing in.
                 if (!token) return { privateKey, did: material.primaryDid };
-                return this.completeIdentityRecovery!({ token, providerType, signDidAuthVp });
+                return this.completeIdentityRecovery!({
+                    token,
+                    providerType,
+                    signDidAuthVp,
+                    options: params.options,
+                });
             }
 
             let recoveryShare: string;
@@ -3295,6 +3463,7 @@ export function createSSSStrategy(config: SSSStrategyConfig): SSSKeyDerivationSt
                     recoveryShare,
                     authShare,
                     rebindSessionToken: material.rebindSessionToken,
+                    fromEscrow: false,
                 };
 
                 return { privateKey, did: material.primaryDid };
@@ -3465,22 +3634,41 @@ export function createSSSStrategy(config: SSSStrategyConfig): SSSKeyDerivationSt
                 })
             );
 
-            await tryEnrollEscrow(
-                params.token,
-                params.providerType,
-                pending.privateKey,
-                pending.primaryDid,
-                shares,
-                shareVersion,
-                signDidAuthVp,
-                undefined,
-                undefined,
-                true
-            );
+            // Other recovery methods leave enrollment to the caller's rollout gate.
+            const enrolled =
+                pending.fromEscrow &&
+                (await tryEnrollEscrow(
+                    params.token,
+                    params.providerType,
+                    pending.privateKey,
+                    pending.primaryDid,
+                    shares,
+                    shareVersion,
+                    signDidAuthVp,
+                    undefined,
+                    undefined,
+                    true,
+                    storage.assertCurrent,
+                    params.options?.recoveryEmail,
+                    params.options?.recoveryLanguage
+                ));
             if (activeStorageId !== storageId || storageGeneration !== generation) {
                 throw new Error('This recovery request was cancelled.');
             }
-            return { privateKey: pending.privateKey, did: pending.primaryDid };
+            if (!enrolled) {
+                unenrolledRotation = {
+                    shares,
+                    shareVersion,
+                    primaryDid: pending.primaryDid,
+                    clearPin: true,
+                };
+            }
+            return {
+                privateKey: pending.privateKey,
+                did: pending.primaryDid,
+                escrowEnrolled: enrolled,
+                escrowRecovery: pending.fromEscrow,
+            };
         },
 
         // --- Contact method management ---