@learncard/sss-key-manager 0.2.6 → 0.3.0

package/src/sss-strategy.ts

@@ -29,6 +29,7 @@ import type {
     DidAuthVpSigner,
     EscrowAttestationPolicy,
     EscrowHoldStatus,
+    EscrowPinAttemptContext,
     EscrowRecoveryStart,
     EscrowEnrollmentState,
     RevokeOtherDevicesResult,
@@ -53,7 +54,12 @@ import {
     derivePinProof,
     ESCROW_PIN_MAX_ATTEMPTS,
 } from './escrow-pin';
-import { encryptEscrowBlob, generateEscrowKeyPair, openEscrowRelease } from './escrow-crypto';
+import {
+    canonicalEscrowEmailBrand,
+    encryptEscrowBlob,
+    generateEscrowKeyPair,
+    openEscrowRelease,
+} from './escrow-crypto';
 import { verifyEnclaveAttestation } from './escrow-attestation';
 import {
     createEscrowEnrollmentIntent,
@@ -68,7 +74,7 @@ import {
 } from './escrow-authority';
 import { getEscrowBlobIdentity } from './escrow-enrollment-intent';
 import type { VerifiedEnclaveIdentity, EscrowAuthorityState } from './escrow-authority.types';
-import { EscrowEvidenceError } from './escrow-authority.types';
+import { ESCROW_AUTHORITY_TENANT_PATTERN, EscrowEvidenceError } from './escrow-authority.types';
 import type { EscrowEnvelope } from './escrow-crypto';
 import type { EmailRelayBranding } from './email-relay-crypto';
 
@@ -133,7 +139,36 @@ export interface SSSStorageFunctions {
 
 export interface SSSStrategyConfig {
     /** Enable automatic enrollment under an explicit enclave trust policy. */
-    escrow?: { enabled: boolean; attestation: EscrowAttestationPolicy };
+    escrow?: {
+        enabled: boolean;
+        attestation: EscrowAttestationPolicy;
+        /**
+         * The escrow authority's tenant label: the enclave's measured
+         * `ESCROW_AUTHORITY_TENANT`, which it signs into every authority record and
+         * requires in every signed enrollment intent. Used for everything the
+         * enclave verifies (intent tenant, authority state, hold, code-delivery and
+         * persisted recovery expectations). Everything else (X-Tenant-Id, email
+         * branding, same-tenant guards) keeps using {@link SSSStrategyConfig.tenantId}.
+         *
+         * Defaults to `tenantId` (then `'learncard'`). Set it explicitly when this app
+         * shares another tenant's single-tenant enclave, e.g. VetPass on LearnCard's
+         * (`'learncard'`). Must match `/^[A-Za-z0-9_-]{1,128}$/`.
+         */
+        authorityTenant?: string;
+        /**
+         * Display name sealed into the escrow blob for enclave-sent emails
+         * (D21, `recoveryBrand`), e.g. `'VetPass'`. Sealed only when the
+         * recovery email and language are (nitro enroll/replace), never on a
+         * carry. Unset: the enclave brands emails from its measured tenant label.
+         *
+         * Set only after every live enclave host runs the brand-aware image: an
+         * older image drops the field whenever it re-encrypts the blob.
+         * Must pass {@link canonicalEscrowEmailBrand} (ASCII letters, digits,
+         * space, `-`, `'`, `&`; 1-32 characters); `createSSSStrategy` throws
+         * otherwise.
+         */
+        emailBrand?: string;
+    };
 
     /** Report enrollment failures without logging recovery material. */
     onEscrowError?: (err: unknown) => void;
@@ -246,6 +281,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() {
@@ -1032,6 +1071,23 @@ export function createSSSStrategy(config: SSSStrategyConfig): SSSKeyDerivationSt
         emailBranding,
         tenantId,
     } = config;
+    // Enclave-verified tenant (see SSSStrategyConfig.escrow.authorityTenant); never
+    // sent as X-Tenant-Id. Defaults keep LearnCard/Scouts behaviour unchanged.
+    const authorityTenant = config.escrow?.authorityTenant ?? tenantId ?? 'learncard';
+    if (config.escrow && !ESCROW_AUTHORITY_TENANT_PATTERN.test(authorityTenant))
+        throw new Error(
+            'Invalid escrow authority tenant: expected 1-128 letters, digits, "_" or "-".'
+        );
+    // D21: strict on write (the enclave and parsers are lenient on read), and
+    // canonicalized once here so every enrollment path seals the same value.
+    const emailBrand =
+        config.escrow?.emailBrand === undefined
+            ? undefined
+            : canonicalEscrowEmailBrand(config.escrow.emailBrand);
+    if (config.escrow?.emailBrand !== undefined && emailBrand === undefined)
+        throw new Error(
+            'Invalid escrow email brand: expected 1-32 ASCII letters, digits, spaces, "-", "\'" or "&", starting with a letter.'
+        );
     const storage = config.storage || defaultStorage;
     let storageGeneration = 0;
     const localWrites = new Set<Promise<void>>();
@@ -1117,7 +1173,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;
@@ -1284,7 +1340,7 @@ export function createSSSStrategy(config: SSSStrategyConfig): SSSKeyDerivationSt
         if (
             !expected ||
             expected.holdId !== holdId ||
-            expected.tenant !== (tenantId ?? 'learncard') ||
+            expected.tenant !== authorityTenant ||
             !expected.did ||
             !expected.clientEphemeralPublicKey ||
             !expected.blobHash ||
@@ -1352,7 +1408,7 @@ export function createSSSStrategy(config: SSSStrategyConfig): SSSKeyDerivationSt
         const result = await verifyEscrowAuthorityState(
             response,
             nonce,
-            tenantId ?? 'learncard',
+            authorityTenant,
             did,
             identity
         );
@@ -1422,8 +1478,15 @@ export function createSSSStrategy(config: SSSStrategyConfig): SSSKeyDerivationSt
                 did: primaryDid,
                 shareVersion,
                 ...(pinMaterial ? { pinVerifier: pinMaterial.pinVerifier } : {}),
+                // D21: the brand is sealed exactly when the contact is, so a
+                // carry (whose target the enclave refuses if it claims one)
+                // never sends it; the enclave inherits the source's brand.
                 ...(authority && recoveryEmail && bindsRecoveryContact
-                    ? { recoveryEmail, recoveryLanguage }
+                    ? {
+                          recoveryEmail,
+                          recoveryLanguage,
+                          ...(emailBrand ? { recoveryBrand: emailBrand } : {}),
+                      }
                     : {}),
             },
             publicKey,
@@ -1814,36 +1877,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 +2022,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 +2035,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 +2115,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 +2145,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 +2276,8 @@ export function createSSSStrategy(config: SSSStrategyConfig): SSSKeyDerivationSt
             pinSignIn: {
                 mode: 'relinked',
                 pinRefreshed: false,
-                newPinRequired: pinHasRecordedWrongAttempts(status?.escrowPin),
+                newPinRequired: !pinSignInClean([status?.escrowPin], pending.pinKeep?.pinAttempts)
+                    .clean,
             },
         };
     };
@@ -3079,7 +3212,7 @@ export function createSSSStrategy(config: SSSStrategyConfig): SSSKeyDerivationSt
                 const verified = await verifyEscrowHoldRecord(
                     result.holdRecord,
                     {
-                        tenant: tenantId ?? 'learncard',
+                        tenant: authorityTenant,
                         did: expectedDid,
                         holdId: result.holdId,
                         clientEphemeralPublicKey: pair.publicKey,
@@ -3088,7 +3221,7 @@ export function createSSSStrategy(config: SSSStrategyConfig): SSSKeyDerivationSt
                     identity
                 );
                 expectations = {
-                    tenant: tenantId ?? 'learncard',
+                    tenant: authorityTenant,
                     did: expectedDid,
                     holdId: result.holdId,
                     clientEphemeralPublicKey: pair.publicKey,
@@ -3337,7 +3470,8 @@ export function createSSSStrategy(config: SSSStrategyConfig): SSSKeyDerivationSt
                             shareVersion: material.shareVersion,
                         },
                         input.pin,
-                        pinBefore
+                        pinBefore,
+                        input.pinAttempts
                     );
                 }
                 pendingIdentityRecovery = {
@@ -3349,7 +3483,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';