@learncard/sss-key-manager 0.2.6 → 0.2.7

package/src/sss-strategy.ts

@@ -29,6 +29,7 @@ import type {
     DidAuthVpSigner,
     EscrowAttestationPolicy,
     EscrowHoldStatus,
+    EscrowPinAttemptContext,
     EscrowRecoveryStart,
     EscrowEnrollmentState,
     RevokeOtherDevicesResult,
@@ -246,6 +247,10 @@ export class EscrowRequestError extends Error {
     }
 }
 
+/** lca-api refused a write because escrow state changed after the caller's reads (409). */
+const isConflictRefusal = (error: unknown): boolean =>
+    error instanceof EscrowRequestError && error.status === 409;
+
 /** Independently generated splits can reuse a share's final-byte x-coordinate. */
 export class DuplicateShareCoordinateError extends Error {
     constructor() {
@@ -1117,7 +1122,7 @@ export function createSSSStrategy(config: SSSStrategyConfig): SSSKeyDerivationSt
                * PIN sign-in awaiting a new login: completion only links that login
                * (no re-split, no history or recovery-method change) at this version.
                */
-              pinKeep?: { shareVersion: number };
+              pinKeep?: { shareVersion: number; pinAttempts?: EscrowPinAttemptContext };
               rebind?: { shares: SSSShares; storageId: string | undefined; attempted: boolean };
           }
         | undefined;
@@ -1814,36 +1819,79 @@ export function createSSSStrategy(config: SSSStrategyConfig): SSSKeyDerivationSt
     };
 
     /**
-     * True unless the server proves no wrong entry is recorded against the current PIN.
-     * A missing count (legacy record, older server, failed lookup) is treated as "wrong
-     * entries recorded", so the same PIN never gets a fresh budget on a guess.
+     * Verified wrong entries recorded against the current PIN, or undefined when the
+     * server cannot prove the count (legacy record, older server, failed lookup). A
+     * status with no PIN counts as zero.
      */
-    const pinHasRecordedWrongAttempts = (escrowPin: unknown): boolean => {
+    const recordedWrongPinAttempts = (escrowPin: unknown): number | undefined => {
         const status = escrowPin as { state?: unknown; wrongAttempts?: unknown } | undefined;
-        if (status?.state === 'none') return false;
-        return typeof status?.wrongAttempts !== 'number' || status.wrongAttempts > 0;
+        if (status?.state === 'none') return 0;
+        const count = status?.wrongAttempts;
+        return typeof count === 'number' && Number.isSafeInteger(count) && count >= 0
+            ? count
+            : undefined;
+    };
+
+    /** A valid, non-negative attempt count from the caller, or undefined. */
+    const attemptCount = (value: unknown): number | undefined =>
+        typeof value === 'number' && Number.isSafeInteger(value) && value >= 0 ? value : undefined;
+
+    /**
+     * Whether a PIN sign-in may treat every wrong entry recorded against the PIN as the
+     * user's own typing (own-typos rule, E; approved 2026-11-03). Requires:
+     * - zero wrong entries when the flow started (`priorWrongAttempts`; unknown counts
+     *   as "some"), and
+     * - every status read during this release showing exactly the wrong entries this
+     *   client submitted in the flow (`ownWrongAttempts`), so a guess from anywhere
+     *   else (more entries) or an unexplained count (fewer, unknown) is never excused.
+     * Without `attempts` (older callers), or when a status shows a different PIN
+     * generation than the flow's (`pinSalt`), no own entries are excused and the prior
+     * count is the one read just before this release: the original #1905 rule.
+     */
+    const pinSignInClean = (
+        observed: unknown[],
+        flowAttempts: EscrowPinAttemptContext | undefined
+    ): { clean: boolean; ownWrongAttempts: number } => {
+        const flowSalt = flowAttempts?.pinSalt;
+        const sameGeneration =
+            typeof flowSalt !== 'string' ||
+            observed.every(status => {
+                const salt = (status as { salt?: unknown } | undefined)?.salt;
+                return typeof salt !== 'string' || salt === flowSalt;
+            });
+        const attempts = sameGeneration ? flowAttempts : undefined;
+        const own = attempts ? attemptCount(attempts.ownWrongAttempts) : 0;
+        if (own === undefined) return { clean: false, ownWrongAttempts: 0 };
+        const prior = attempts
+            ? attemptCount(attempts.priorWrongAttempts)
+            : recordedWrongPinAttempts(observed[0]);
+        const clean =
+            prior === 0 &&
+            observed.length > 0 &&
+            observed.every(status => recordedWrongPinAttempts(status) === own);
+        return { clean, ownWrongAttempts: own };
     };
 
     /**
      * The charges a same-PIN refresh may replace, or undefined when it must not run:
-     * zero wrong entries before AND after this release, and exactly one charge between
+     * the sign-in is clean (see pinSignInClean) and exactly one charge landed between
      * the two reads (this release). Any other charge may be someone else's guess still
      * in flight, so the PIN keeps its reduced budget. The server re-checks these
-     * charges in the write itself (`expectedPinCharges`).
+     * charges in the write itself (`expectedPinCharges`), so a guess landing after
+     * these reads still blocks the refresh.
      */
     const refreshablePinCharges = (
         before: unknown,
-        after: unknown
+        after: unknown,
+        ownWrongAttempts: number
     ): { attemptsRemaining: number; wrongAttempts: number } | undefined => {
         const pre = before as { state?: unknown; attemptsRemaining?: unknown } | undefined;
         const post = after as { state?: unknown; attemptsRemaining?: unknown } | undefined;
-        if (pinHasRecordedWrongAttempts(before) || pinHasRecordedWrongAttempts(after))
-            return undefined;
         if (pre?.state !== 'enabled' || post?.state !== 'enabled') return undefined;
         if (typeof pre.attemptsRemaining !== 'number' || typeof post.attemptsRemaining !== 'number')
             return undefined;
         if (post.attemptsRemaining !== pre.attemptsRemaining - 1) return undefined;
-        return { attemptsRemaining: post.attemptsRemaining, wrongAttempts: 0 };
+        return { attemptsRemaining: post.attemptsRemaining, wrongAttempts: ownWrongAttempts };
     };
 
     /** New salt and verifier for a PIN just proven; undefined when it fails the PIN rules. */
@@ -1916,7 +1964,9 @@ export function createSSSStrategy(config: SSSStrategyConfig): SSSKeyDerivationSt
         },
         pin: string,
         /** PIN status read before this release; undefined when that read failed. */
-        pinBefore: unknown
+        pinBefore: unknown,
+        /** Own-typos context from the caller's PIN sign-in flow (E). */
+        pinAttempts?: EscrowPinAttemptContext
     ): Promise<RecoveryResult> => {
         const storage = guardedStorage();
         const generation = storageGeneration;
@@ -1927,70 +1977,76 @@ export function createSSSStrategy(config: SSSStrategyConfig): SSSKeyDerivationSt
             }
         };
 
-        const { mode, newPinRequired, refreshCharges } = await withShareUpdateLock(
-            storage,
-            storageId,
-            () =>
-                withRotationLock(async () => {
-                    assertActive();
-                    const current = await fetchAuthShareRaw(
-                        serverUrl,
-                        params.token,
-                        params.providerType,
-                        undefined,
-                        tenantId
-                    );
-                    assertActive();
-                    if (
-                        !current ||
-                        current.primaryDid !== released.primaryDid ||
-                        typeof current.shareVersion !== 'number'
-                    ) {
+        const {
+            mode,
+            newPinRequired: newPinRequiredAtRelease,
+            refreshCharges,
+        } = await withShareUpdateLock(storage, storageId, () =>
+            withRotationLock(async () => {
+                assertActive();
+                const current = await fetchAuthShareRaw(
+                    serverUrl,
+                    params.token,
+                    params.providerType,
+                    undefined,
+                    tenantId
+                );
+                assertActive();
+                if (
+                    !current ||
+                    current.primaryDid !== released.primaryDid ||
+                    typeof current.shareVersion !== 'number'
+                ) {
+                    throw new PinSignInStaleError();
+                }
+                let mode: 'kept' | 'deferred-rotation';
+                if (current.shareVersion === released.shareVersion) {
+                    if (authShareToString(current.authShare) !== released.authShare) {
                         throw new PinSignInStaleError();
                     }
-                    let mode: 'kept' | 'deferred-rotation';
-                    if (current.shareVersion === released.shareVersion) {
-                        if (authShareToString(current.authShare) !== released.authShare) {
-                            throw new PinSignInStaleError();
-                        }
-                        mode = 'kept';
-                    } else {
-                        const historical =
-                            current.shareVersion > released.shareVersion
-                                ? await fetchAuthShareRaw(
-                                      serverUrl,
-                                      params.token,
-                                      params.providerType,
-                                      released.shareVersion,
-                                      tenantId
-                                  )
-                                : null;
-                        if (authShareToString(historical?.authShare) !== released.authShare) {
-                            throw new PinSignInStaleError();
-                        }
-                        mode = 'deferred-rotation';
+                    mode = 'kept';
+                } else {
+                    const historical =
+                        current.shareVersion > released.shareVersion
+                            ? await fetchAuthShareRaw(
+                                  serverUrl,
+                                  params.token,
+                                  params.providerType,
+                                  released.shareVersion,
+                                  tenantId
+                              )
+                            : null;
+                    if (authShareToString(historical?.authShare) !== released.authShare) {
+                        throw new PinSignInStaleError();
                     }
-                    assertActive();
-                    await adoptReleasedShare(
-                        storage,
-                        storageId,
-                        released,
-                        released.shareVersion,
-                        current.shareVersion
-                    );
-                    pendingIdentityRecovery = undefined;
-                    // Both reads count: the one after this release (a success never resets the
-                    // count) and the one before it (a legacy record without a verified count
-                    // reports 0 once any release has been reserved, so only the earlier read
-                    // shows that its history is unknown).
-                    return {
-                        mode,
-                        newPinRequired:
-                            pinHasRecordedWrongAttempts(pinBefore) ||
-                            pinHasRecordedWrongAttempts(current.escrowPin),
-                        refreshCharges: refreshablePinCharges(pinBefore, current.escrowPin),
-                    };
-                })
+                    mode = 'deferred-rotation';
+                }
+                assertActive();
+                await adoptReleasedShare(
+                    storage,
+                    storageId,
+                    released,
+                    released.shareVersion,
+                    current.shareVersion
+                );
+                pendingIdentityRecovery = undefined;
+                // Both reads count: the one after this release (a success never resets the
+                // count) and the one before it (a legacy record without a verified count
+                // reports 0 once any release has been reserved, so only the earlier read
+                // shows that its history is unknown). Each must show exactly this flow's
+                // own wrong entries (zero for callers without a flow context).
+                const { clean, ownWrongAttempts } = pinSignInClean(
+                    [pinBefore, current.escrowPin],
+                    pinAttempts
+                );
+                return {
+                    mode,
+                    newPinRequired: !clean,
+                    refreshCharges: clean
+                        ? refreshablePinCharges(pinBefore, current.escrowPin, ownWrongAttempts)
+                        : undefined,
+                };
+            })
         );
 
         // Same PIN, new salt and verifier, enrolled at the same version: a fresh
@@ -2001,26 +2057,29 @@ export function createSSSStrategy(config: SSSStrategyConfig): SSSKeyDerivationSt
         // scheduled.
         let pinRefreshed = false;
         let pinRefreshFailed = false;
+        let newPinRequired = newPinRequiredAtRelease;
         if (mode === 'kept' && !newPinRequired && refreshCharges && params.signDidAuthVp) {
             const pinMaterial = await freshPinMaterial(pin);
-            pinRefreshed =
-                pinMaterial !== undefined &&
-                (await tryEnrollEscrow(
-                    params.token,
-                    params.providerType,
-                    released.privateKey,
-                    released.primaryDid,
-                    { recoveryShare: released.recoveryShare },
-                    released.shareVersion,
-                    params.signDidAuthVp,
-                    undefined,
-                    pinMaterial,
-                    false,
-                    storage.assertCurrent,
-                    params.options?.recoveryEmail,
-                    params.options?.recoveryLanguage,
-                    refreshCharges
-                ));
+            const refresh =
+                pinMaterial === undefined
+                    ? undefined
+                    : await attemptEnrollEscrow(
+                          params.token,
+                          params.providerType,
+                          released.privateKey,
+                          released.primaryDid,
+                          { recoveryShare: released.recoveryShare },
+                          released.shareVersion,
+                          params.signDidAuthVp,
+                          undefined,
+                          pinMaterial,
+                          false,
+                          storage.assertCurrent,
+                          params.options?.recoveryEmail,
+                          params.options?.recoveryLanguage,
+                          refreshCharges
+                      );
+            pinRefreshed = refresh?.enrolled === true;
             // Reported, not swallowed: the PIN keeps (at most) its reduced budget. A commit
             // whose receipt was lost is not confirmed here, so it reports failed too (an
             // under-claim: the budget is in fact full). lca-api either
@@ -2028,6 +2087,21 @@ export function createSSSStrategy(config: SSSStrategyConfig): SSSKeyDerivationSt
             // authority's commit; a copy left behind is caught by ensureEscrowEnrollment's
             // identity check, which never clears the PIN on its own.
             pinRefreshFailed = pinMaterial !== undefined && !pinRefreshed;
+            // A refused refresh usually means the charges moved after our reads, most
+            // likely someone else's entry: re-check before showing the calm sheet. If the
+            // status can't be read, a 409 (charges changed) still counts as a warning.
+            if (pinRefreshFailed) {
+                const latest = await fetchAuthShareRaw(
+                    serverUrl,
+                    params.token,
+                    params.providerType,
+                    undefined,
+                    tenantId
+                ).catch(() => undefined);
+                newPinRequired = latest
+                    ? !pinSignInClean([pinBefore, latest.escrowPin], pinAttempts).clean
+                    : isConflictRefusal(refresh && !refresh.enrolled ? refresh.error : undefined);
+            }
         }
         assertActive();
         return {
@@ -2144,7 +2218,8 @@ export function createSSSStrategy(config: SSSStrategyConfig): SSSKeyDerivationSt
             pinSignIn: {
                 mode: 'relinked',
                 pinRefreshed: false,
-                newPinRequired: pinHasRecordedWrongAttempts(status?.escrowPin),
+                newPinRequired: !pinSignInClean([status?.escrowPin], pending.pinKeep?.pinAttempts)
+                    .clean,
             },
         };
     };
@@ -3337,7 +3412,8 @@ export function createSSSStrategy(config: SSSStrategyConfig): SSSKeyDerivationSt
                             shareVersion: material.shareVersion,
                         },
                         input.pin,
-                        pinBefore
+                        pinBefore,
+                        input.pinAttempts
                     );
                 }
                 pendingIdentityRecovery = {
@@ -3349,7 +3425,14 @@ export function createSSSStrategy(config: SSSStrategyConfig): SSSKeyDerivationSt
                     fromEscrow: true,
                     // The PIN itself is not kept across the new-login step.
                     ...(input.method === 'escrow-pin'
-                        ? { pinKeep: { shareVersion: material.shareVersion } }
+                        ? {
+                              pinKeep: {
+                                  shareVersion: material.shareVersion,
+                                  ...(input.pinAttempts
+                                      ? { pinAttempts: { ...input.pinAttempts } }
+                                      : {}),
+                              },
+                          }
                         : {}),
                 };
                 // The OTP path uses exactly this pending state. Without a provider session

package/src/types.ts

@@ -125,6 +125,29 @@ export class EscrowPinUnavailableError extends Error {
     }
 }
 
+/**
+ * What this client saw during one PIN sign-in flow (own-typos rule, E). A flow starts
+ * with the first PIN status read before the first attempt and ends when the sign-in
+ * completes; a new modal or app start begins a new flow.
+ */
+export interface EscrowPinAttemptContext {
+    /**
+     * Verified wrong entries recorded against the PIN when the flow started, before
+     * any attempt here. Undefined when the server could not say (legacy record, failed
+     * read): treated as "wrong entries recorded".
+     */
+    priorWrongAttempts?: number;
+    /** Wrong entries this client itself submitted in this flow (mismatch responses). */
+    ownWrongAttempts: number;
+    /**
+     * Salt of the PIN generation the counts belong to (from the flow's first status).
+     * A status read during the release that shows another salt (a new PIN, or a
+     * same-PIN re-set elsewhere) means the counts describe a different PIN, so they
+     * are ignored and the stricter #1905 rule applies.
+     */
+    pinSalt?: string;
+}
+
 /** A failed PIN attempt consumes its hold; another attempt must start a fresh hold. */
 export class EscrowPinMismatchError extends Error {
     constructor(public readonly attemptsRemaining: number) {
@@ -199,6 +222,12 @@ export type RecoveryInput =
           expectedDid?: string;
           /** Verified recovery-email session; set only when no login is bound yet. */
           recoverySessionToken?: string;
+          /**
+           * Own-typos rule (E): wrong entries this client observed in the current PIN
+           * sign-in flow. Omitted by older callers, which keeps the stricter rule (any
+           * recorded wrong entry blocks the same-PIN re-set).
+           */
+          pinAttempts?: EscrowPinAttemptContext;
       }
     | {
           method: 'escrow';