@learncard/sss-key-manager 0.2.2 → 0.2.4

package/src/sss-strategy.ts

@@ -59,6 +59,7 @@ import {
     verifyEscrowAuthorityState,
     verifyEscrowEnrollmentCommit,
     verifyEscrowHoldRecord,
+    verifyEscrowCodeDelivery,
     verifyEscrowHoldConfirmation,
     escrowAuthorityMeasurements,
     type EscrowHoldRecordLike,
@@ -107,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>;
@@ -124,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;
 
@@ -192,13 +219,25 @@ 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 {
-    constructor(public readonly status: number) {
+    constructor(
+        public readonly status: number,
+        public readonly reason?: 'codeMismatch' | 'codeExpired' | 'codeLocked'
+    ) {
         super('Escrow request failed');
         this.name = 'EscrowRequestError';
     }
@@ -1061,6 +1100,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;
@@ -1099,6 +1140,22 @@ export function createSSSStrategy(config: SSSStrategyConfig): SSSKeyDerivationSt
         });
         // Never propagate response bodies or status text that could contain secrets.
         if (!response.ok) {
+            if (path === '/confirm' && response.status === 403) {
+                const body: unknown = await response.json().catch(() => undefined);
+                const reason =
+                    body &&
+                    typeof body === 'object' &&
+                    'message' in body &&
+                    typeof body.message === 'string'
+                        ? body.message
+                        : undefined;
+                throw new EscrowRequestError(
+                    response.status,
+                    reason === 'codeMismatch' || reason === 'codeExpired' || reason === 'codeLocked'
+                        ? reason
+                        : undefined
+                );
+            }
             if (!pinAttempt && path === '/recover' && response.status === 429) {
                 const body: unknown = await response.json().catch(() => undefined);
                 const message =
@@ -1401,10 +1458,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 {
@@ -1413,9 +1471,30 @@ 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 (
         self: SSSKeyDerivationStrategy,
         params: Parameters<NonNullable<SSSKeyDerivationStrategy['ensureEscrowEnrollment']>>[0],
@@ -1423,7 +1502,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 ?? '';
@@ -1450,7 +1530,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.');
@@ -1464,6 +1552,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' };
@@ -1476,7 +1567,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
@@ -1499,7 +1634,7 @@ export function createSSSStrategy(config: SSSStrategyConfig): SSSKeyDerivationSt
         }
         try {
             if (
-                !clearPinForEnrollment &&
+                !forceRotate &&
                 pin === undefined &&
                 unenrolledRotation &&
                 unenrolledRotation.shareVersion === status.shareVersion &&
@@ -1516,13 +1651,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).
@@ -1581,7 +1716,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
@@ -2016,6 +2151,9 @@ export function createSSSStrategy(config: SSSStrategyConfig): SSSKeyDerivationSt
                 escrowPin: data.escrowPin,
                 escrowStale: data.escrowStale,
                 sssActivationState: data.sssActivationState ?? 'active',
+                ...(typeof data.priorEscrowEnrollment === 'boolean'
+                    ? { priorEscrowEnrollment: data.priorEscrowEnrollment }
+                    : {}),
             };
         },
 
@@ -2103,7 +2241,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> {
@@ -2200,7 +2350,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 };
             });
         },
 
@@ -2334,6 +2497,9 @@ export function createSSSStrategy(config: SSSStrategyConfig): SSSKeyDerivationSt
                     ledgerPublicKey: identity.authority.ledgerPublicKey,
                     keyId: verified.receipt.keyId,
                 };
+                result.codeSent = result.delivery
+                    ? await verifyEscrowCodeDelivery(result.delivery, expectations, identity)
+                    : undefined;
             }
             // Never accept a server-supplied expectations object, even in software mode.
             return { ...result, clientEphemeralPrivateKey: pair.privateKey, expectations };
@@ -2455,6 +2621,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;
@@ -2542,11 +2709,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;
@@ -3272,6 +3445,7 @@ export function createSSSStrategy(config: SSSStrategyConfig): SSSKeyDerivationSt
                     recoveryShare,
                     authShare,
                     rebindSessionToken: material.rebindSessionToken,
+                    fromEscrow: false,
                 };
 
                 return { privateKey, did: material.primaryDid };
@@ -3442,22 +3616,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 ---

package/src/types.ts

@@ -104,6 +104,11 @@ export interface EscrowHoldStatus {
 
 /** Persist these secrets securely until completion; a null token means an existing hold. */
 export type EscrowRecoveryStart = EscrowHoldStatus & {
+    codeSent?: boolean;
+    delivery?: {
+        codeSent: boolean;
+        proof: import('./escrow-authority.types').EscrowAuthorityRecord;
+    };
     /** Persist with the secrets, never rebuild from server status. Required for Nitro resume. */
     expectations?: import('@learncard/types').EscrowRecoveryExpectations;
     resumeToken: string | null;