@payez/next-mvp 4.4.5 → 4.4.6

package/src/lib/session-store.ts

@@ -13,6 +13,7 @@ import { randomBytes } from 'crypto';
 import { SessionData } from '../models/SessionModel';
 import { getSessionPrefix, getRefreshLockPrefix, getAppSlug } from './app-slug';
 import { extractKidFromToken, decodeIdpAccessToken } from '../auth/utils/token-utils';
+import { tokenLogId } from './token-log-id';
 
 // Re-export SessionData for consumers
 export type { SessionData } from '../models/SessionModel';
@@ -293,11 +294,29 @@ export async function setSession(sessionToken: string, data: SessionData): Promi
     .exec();
 }
 
+/**
+ * Describe a credential-bearing value for a log line WITHOUT the value: its kind only.
+ * Deliberately no length or fingerprint either - both narrow the value down.
+ */
+function describeTokenValueForLog(v: unknown): string {
+  if (v === undefined) return 'undefined';
+  if (v === null) return 'null';
+  if (typeof v === 'string') return v.length === 0 ? 'empty string' : 'non-empty string (value withheld)';
+  return `${typeof v} (value withheld)`;
+}
+
 /**
  * Updates tokens within an existing session.
+ *
+ * CALLERS MUST CHECK THE RETURN VALUE (320072). A null return means the session
+ * row was absent and EVERY field in `updates` was discarded — it is a dropped
+ * write, not a no-op on unchanged data. Ignoring it is how a token refresh came
+ * to report success while persisting nothing.
+ *
  * @param sessionToken The session token to update.
  * @param updates Partial session data to update.
- * @returns The updated session data, or null if the session was not found.
+ * @returns The updated session data, or null if the session was not found — in
+ *          which case NOTHING WAS WRITTEN.
  */
 export async function updateSession(
   sessionToken: string,
@@ -309,6 +328,74 @@ export async function updateSession(
   // Get current session to merge with updates
   const currentSession = await getSession(sessionToken);
   if (!currentSession) {
+    /**
+     * 320072: THIS IS A DROPPED WRITE, AND IT USED TO LEAVE NO TRACE.
+     *
+     * Returning null here is correct — there is no row to merge into — but it
+     * was previously done in total silence: no throw, no log. Every caller that
+     * ignores the return value therefore believed it had persisted, and the
+     * most damaging caller did exactly that (ensure-fresh-access-token).
+     *
+     * The canonical row can legitimately be absent: better-auth.ts writes the
+     * `ba:` record and the canonical row in two steps, and the second is
+     * wrapped in a try/catch that only console.warn()s — a deliberate,
+     * documented degradation that leaves the BA session correct and this row
+     * missing. That decision is fine. What was NOT fine is that the READ side
+     * reported success anyway, so nothing ever surfaced it.
+     *
+     * Logged at error, not warn: the caller's data is gone. Callers that can
+     * tolerate a missing row should check the null return — which is now the
+     * documented contract — rather than rely on this being quiet.
+     */
+    /**
+     * DO NOT LOG `key` HERE. `getSessionKey()` (line 21) is
+     * `${getSessionPrefix()}${token}` — the prefix plus the WHOLE session
+     * token — so logging it writes a live, replayable credential into
+     * console.error, and logs travel further than the process that wrote them.
+     * The redacting idiom in this file is `substring(0, 8) + '...'`.
+     *
+     * NOTE ON WHAT THIS COMMENT NO LONGER CLAIMS. It used to say this was the
+     * single unredacted departure in the file, and gave a site count. Both were
+     * wrong: a RAW refresh token was being emitted at the
+     * REFRESH_TOKEN_BEING_CLEARED site below, and the count was stale. QAPert found that
+     * leak while reviewing PR 96 — he looked *because* this comment asserted
+     * there was nothing to find, which is the worst thing a comment can do.
+     * It is fixed in the same commit as this rewrite.
+     *
+     * So the counts are gone deliberately. A tally in prose decays silently on
+     * the next edit and then actively misleads; that decay is the defect being
+     * repaired here, and reproducing it in the fix would be absurd. If you need
+     * a number, measure it — do not trust this paragraph for one.
+     *
+     * What replaces the prose is enforcement. The invariant is
+     * NO RAW CREDENTIAL IS EVER EMITTED FROM THIS FUNCTION, and it is pinned by
+     * executable assertions, not by this text:
+     *   - Case 4 (session token, this log)
+     *   - Case 5 (refresh token, the REFRESH_TOKEN_BEING_CLEARED log below)
+     * in test/ensure-fresh-persist-failure.test.cjs. Both were proven to fail
+     * when their fix is mutated out. Delete a redaction and a test goes red;
+     * delete this comment and nothing does. Trust the tests.
+     *
+     * Caught by QAPert on 320072 and made binding by BAPert (R1043 s1).
+     *
+     * The prefix is logged SEPARATELY and deliberately, because it is the field
+     * that makes this line diagnostic rather than decorative: a "no canonical
+     * row" miss has two very different causes, and only the prefix tells them
+     * apart —
+     *   wrong keyspace  (slug/prefix disagreement — the 241875 / 213416 defect
+     *                    documented at line 111, where a writer and a reader
+     *                    resolved different slugs and every lookup silently
+     *                    missed), versus
+     *   absent row      (the documented better-auth.ts two-step degradation).
+     * The prefix is an app slug, not a secret. Redacting it too would leave a
+     * log that says only "something was missing".
+     */
+    console.error('[SESSION-STORE] UPDATE_DROPPED_NO_CANONICAL_ROW', {
+      keyPrefix: getSessionPrefix(),
+      sessionToken: tokenLogId(sessionToken),
+      updatedFields: Object.keys(updates),
+      note: 'updateSession found no session row; ALL updates were discarded and null was returned',
+    });
     return null;
   }
 
@@ -322,10 +409,15 @@ export async function updateSession(
 
   if (hadRefreshToken && !willHaveRefreshToken) {
     console.error('[SESSION-STORE] ⚠️ REFRESH_TOKEN_BEING_CLEARED', {
-      sessionToken: sessionToken.substring(0, 8) + '...',
+      sessionToken: tokenLogId(sessionToken),
       userId: currentSession.userId,
       updateKeys: Object.keys(updates),
-      refreshTokenInUpdate: (updates as any).idpRefreshToken || (updates as any).refreshToken,
+      // NEVER the value: a refresh token is a long-lived credential and this line ships to the
+      // log sink. The old `idpRefreshToken || refreshToken` printed a live legacy token raw when
+      // idpRefreshToken was null/"" (which clears) and refreshToken still held one.
+      // Test: test/session-store-refresh-token-not-logged.test.cjs
+      idpRefreshTokenInUpdate: describeTokenValueForLog((updates as any).idpRefreshToken),
+      legacyRefreshTokenInUpdate: describeTokenValueForLog((updates as any).refreshToken),
       refreshTokenClearedReason: (updates as any).refreshTokenClearedReason || 'UNKNOWN',
       stack: new Error().stack
     });
@@ -380,15 +472,66 @@ function mfaLifetimeFromAccessToken(accessToken?: string): Partial<SessionData>
 
   const fields: Partial<SessionData> = {};
 
+  /**
+   * *** TEST THE CONVERTED VALUE, NOT THE CLAIM'S PRESENCE. ***
+   *
+   * This guard previously branched on `claim !== undefined && claim !== null`
+   * and then wrote `Number(claim) * 1000`. Those are two different questions,
+   * and for a non-numeric claim they disagree: the claim IS present, so the
+   * branch is taken, and the value written is NaN. That single NaN defeats both
+   * guards in this system at once, in opposite directions:
+   *
+   *   - `mfaEvidencePresent = mfaLifetime.mfaExpiresAt !== undefined` is TRUE
+   *     for NaN, so R908(e) certifies a ceremony it never observed and GRANTS
+   *     mfaVerified.
+   *   - consumers read `mfaExpiresAt || 0`, and NaN is FALSY, so that collapses
+   *     to 0, `0 > 0` is false, and the session NEVER expires.
+   *
+   * Net: `mfaVerified: true` that nothing can ever expire — the exact
+   * pre-339563 fail-open described at the top of this function, restored
+   * through a malformed claim, and silent (neither warning below fires on NaN).
+   *
+   * So a claim that will not convert is treated as NO CLAIM: the key is OMITTED
+   * and R908(e) withholds the grant, identical to the absent-claim lane. Absent
+   * and unreadable are the same epistemic state — we do not know the expiry —
+   * and they must not produce opposite security outcomes.
+   *
+   * Omitted, never set-to-undefined: updateSession() merges with
+   * `{ ...current, ...updates }`, so a present-but-undefined key would CLOBBER
+   * a good stored value. Pinned by test/mfa-expiry-malformed-claim.test.cjs.
+   *
+   * *** `Number.isFinite` ALONE IS NOT ENOUGH — IT MUST ALSO BE POSITIVE. ***
+   * `Number([])` is 0, and 0 is perfectly finite. But the consumer guard reads
+   * `mfaExpiresAt || 0`, and 0 is FALSY, so a stored zero is indistinguishable
+   * from a missing value and fails open in precisely the same way NaN does —
+   * while still passing `!== undefined` and so still earning the R908(e) grant.
+   * The honest invariant is not "is it a number" but "can this value ever
+   * expire a session", and only a positive one can. A zero/negative
+   * `mfa_expires` is meaningless anyway (epoch 1970 or earlier).
+   *
+   * The `typeof` gate rejects objects and arrays outright rather than letting
+   * JS coercion invent a number for them: `[]` -> 0 and `[5]` -> 5 are accidents
+   * of coercion, not claims the IDP made.
+   */
+  const claimToNumber = (claim: unknown): number | undefined => {
+    if (typeof claim !== 'number' && typeof claim !== 'string') return undefined;
+    if (claim === '') return undefined;
+    const n = Number(claim);
+    return Number.isFinite(n) && n > 0 ? n : undefined;
+  };
+
   // Claims are Unix SECONDS; SessionData stores milliseconds.
-  if (decoded.mfa_expires !== undefined && decoded.mfa_expires !== null) {
-    fields.mfaExpiresAt = Number(decoded.mfa_expires) * 1000;
+  const mfaExpires = claimToNumber(decoded.mfa_expires);
+  if (mfaExpires !== undefined) {
+    fields.mfaExpiresAt = mfaExpires * 1000;
   }
-  if (decoded.mfa_time !== undefined && decoded.mfa_time !== null) {
-    fields.mfaCompletedAt = Number(decoded.mfa_time) * 1000;
+  const mfaTime = claimToNumber(decoded.mfa_time);
+  if (mfaTime !== undefined) {
+    fields.mfaCompletedAt = mfaTime * 1000;
   }
-  if (decoded.mfa_validity_hours !== undefined && decoded.mfa_validity_hours !== null) {
-    fields.mfaValidityHours = Number(decoded.mfa_validity_hours);
+  const mfaValidityHours = claimToNumber(decoded.mfa_validity_hours);
+  if (mfaValidityHours !== undefined) {
+    fields.mfaValidityHours = mfaValidityHours;
   }
 
   return fields;
@@ -419,7 +562,7 @@ export async function transitionTo2FASession(
   const newAccessToken = tokens.idpAccessToken || tokens.accessToken;
 
   console.log('[transitionTo2FASession] Called with:', {
-    sessionToken: sessionToken?.substring(0, 8) + '...',
+    sessionToken: tokenLogId(sessionToken),
     mfaMethod,
     hasAccessToken: !!newAccessToken,
     hasRefreshToken: !!(tokens.idpRefreshToken || tokens.refreshToken),
@@ -483,7 +626,7 @@ export async function transitionTo2FASession(
         'If this fires for a lane that DID complete a real ceremony, the defect is ' +
         'on the emit side (R908(b)) - do not "fix" it by minting the flag here.',
       {
-        sessionToken: sessionToken?.substring(0, 8) + '...',
+        sessionToken: tokenLogId(sessionToken),
         mfaMethod,
         hasAccessToken: !!newAccessToken,
       }
@@ -699,7 +842,7 @@ export async function acquireRefreshLock(
 
     if (result === 'OK') {
       console.debug('[SESSION-STORE] Refresh lock acquired', {
-        sessionToken: sessionToken.substring(0, 8) + '...',
+        sessionToken: tokenLogId(sessionToken),
         requestId,
         lockVersion
       });
@@ -709,7 +852,7 @@ export async function acquireRefreshLock(
       // Lock already exists, check if we should wait
       if (maxWaitMs > 0) {
         console.debug('[SESSION-STORE] Refresh lock already exists, waiting for release', {
-          sessionToken: sessionToken.substring(0, 8) + '...',
+          sessionToken: tokenLogId(sessionToken),
           requestId,
           maxWaitMs
         });
@@ -718,7 +861,7 @@ export async function acquireRefreshLock(
       }
 
       console.warn('[SESSION-STORE] Refresh lock already exists, not waiting', {
-        sessionToken: sessionToken.substring(0, 8) + '...',
+        sessionToken: tokenLogId(sessionToken),
         requestId
       });
 
@@ -726,7 +869,7 @@ export async function acquireRefreshLock(
     }
   } catch (error) {
     console.error('[SESSION-STORE] Failed to acquire refresh lock', {
-      sessionToken: sessionToken.substring(0, 8) + '...',
+      sessionToken: tokenLogId(sessionToken),
       requestId,
       error: error instanceof Error ? error.message : String(error)
     });
@@ -760,7 +903,7 @@ async function waitForRefreshLockRelease(
       await new Promise(resolve => setTimeout(resolve, pollInterval));
     } catch (error) {
       console.error('[SESSION-STORE] Error while waiting for refresh lock release', {
-        sessionToken: sessionToken.substring(0, 8) + '...',
+        sessionToken: tokenLogId(sessionToken),
         requestId,
         error: error instanceof Error ? error.message : String(error)
       });
@@ -769,7 +912,7 @@ async function waitForRefreshLockRelease(
   }
 
   console.warn('[SESSION-STORE] Timeout waiting for refresh lock release', {
-    sessionToken: sessionToken.substring(0, 8) + '...',
+    sessionToken: tokenLogId(sessionToken),
     requestId,
     waitedMs: Date.now() - startTime
   });
@@ -823,33 +966,33 @@ export async function releaseRefreshLock(
 
     if (result === 1) {
       console.debug('[SESSION-STORE] Refresh lock released successfully', {
-        sessionToken: sessionToken.substring(0, 8) + '...',
+        sessionToken: tokenLogId(sessionToken),
         requestId,
         lockVersion
       });
       return true;
     } else if (result === 0) {
       console.warn('[SESSION-STORE] Attempted to release non-existent refresh lock', {
-        sessionToken: sessionToken.substring(0, 8) + '...',
+        sessionToken: tokenLogId(sessionToken),
         requestId
       });
       return false;
     } else if (result === -1) {
       console.error('[SESSION-STORE] Attempted to release refresh lock owned by another request', {
-        sessionToken: sessionToken.substring(0, 8) + '...',
+        sessionToken: tokenLogId(sessionToken),
         requestId
       });
       return false;
     } else if (result === -2) {
       console.error('[SESSION-STORE] Lock version mismatch during release', {
-        sessionToken: sessionToken.substring(0, 8) + '...',
+        sessionToken: tokenLogId(sessionToken),
         requestId,
         lockVersion
       });
       return false;
     } else {
       console.error('[SESSION-STORE] Unexpected result from lock release script', {
-        sessionToken: sessionToken.substring(0, 8) + '...',
+        sessionToken: tokenLogId(sessionToken),
         requestId,
         result
       });
@@ -857,7 +1000,7 @@ export async function releaseRefreshLock(
     }
   } catch (error) {
     console.error('[SESSION-STORE] Failed to release refresh lock', {
-      sessionToken: sessionToken.substring(0, 8) + '...',
+      sessionToken: tokenLogId(sessionToken),
       requestId,
       error: error instanceof Error ? error.message : String(error)
     });
@@ -882,7 +1025,7 @@ export async function checkRefreshLock(sessionToken: string): Promise<RefreshLoc
     return JSON.parse(lockData) as RefreshLockInfo;
   } catch (error) {
     console.error('[SESSION-STORE] Failed to check refresh lock', {
-      sessionToken: sessionToken.substring(0, 8) + '...',
+      sessionToken: tokenLogId(sessionToken),
       error: error instanceof Error ? error.message : String(error)
     });
 

package/src/lib/startup-init.ts

@@ -12,6 +12,7 @@
 
 import 'server-only';
 import { getIDPClientConfig, clearConfigRedisCache, type IDPClientConfig } from './idp-client-config';
+import { slugStateReason } from './app-slug';
 
 let initializationStarted = false;
 let initializationComplete = false;
@@ -59,9 +60,21 @@ export async function ensureInitialized(): Promise<void> {
   // Mark as started
   initializationStarted = true;
 
-  // Start initialization
-  initializationPromise = performInitialization();
-  await initializationPromise;
+  // Start initialization.
+  //
+  // PAY-642: a FAILED attempt must not stay installed. This used to be
+  // `initializationPromise = performInitialization(); await initializationPromise;` with no reset, and the
+  // in-progress check above runs BEFORE the backoff check, so a pod that booted while the IdP was down replayed
+  // its first rejection to every caller forever: the 30 s backoff could never lead to a retry. Same latch, same
+  // fix, as createSingleFlight (lib/single-flight.ts): callers of the failing attempt still see the rejection
+  // (loud), then the attempt clears itself, identity-guarded so a slow failure never evicts a newer attempt.
+  // After a failure the backoff check above governs when the next attempt may start.
+  const attempt = performInitialization();
+  initializationPromise = attempt;
+  attempt.catch(() => {
+    if (initializationPromise === attempt) initializationPromise = null;
+  });
+  await attempt;
 }
 
 /**
@@ -168,8 +181,11 @@ async function performInitialization(): Promise<void> {
     // Step 3: Validate cookie name consistency
     // This catches bugs where getJwtCookieName() returns a different name than
     // what auth-options.ts configures, which causes sessions to fail in production
-    const { validateCookieNameConsistency, getSessionCookieName } = await import('./app-slug');
+    const { validateCookieNameConsistency, getSessionCookieName, assertAppSlugMatchesIdp, assertIdpSlugKnown } = await import('./app-slug');
     validateCookieNameConsistency();
+    // rigpert 60743: refuse to run with two cookie-name sources (IdP clientSlug vs APP_SLUG/CLIENT_ID).
+    assertIdpSlugKnown(cachedIDPConfig?.clientSlug);
+    assertAppSlugMatchesIdp(cachedIDPConfig?.clientSlug);
     console.log('[STARTUP] Cookie name consistency validated:', getSessionCookieName());
 
     // All done
@@ -225,6 +241,15 @@ ${connectionLine}║   Possible causes:
  * Get the cached IDP config after initialization.
  * Returns null if not yet initialized.
  */
+/**
+ * For health endpoints (rigpert 60765): a guard that does not stop the process is an empty red unless the mismatch is visible
+ * where operators and promote-fe look. Returns `SLUG_MISMATCH: cookie=<idp slug> gate=<app slug>` while the drift holds, else null;
+ * a health route should answer non-200 with this as the reason. Null until the IdP config has been fetched.
+ */
+export function getSlugMismatchReason(): string | null {
+  return slugStateReason(cachedIDPConfig?.clientSlug, initializationComplete || initializationFailed);
+}
+
 export function getStartupIDPConfig(): IDPClientConfig | null {
   return cachedIDPConfig;
 }

package/src/lib/token-lifecycle.ts

@@ -25,6 +25,7 @@ import { getSession as getRedisSession, SessionData } from './session-store';
 import { getSession as getBetterAuthSession } from '../server/auth';
 import { getRedis } from './redis';
 import { getAppSlug } from './app-slug';
+import { tokenLogId } from './token-log-id';
 
 // 5 minute threshold for "needs refresh" - matches refresh handler pattern
 const REFRESH_THRESHOLD_MS = 5 * 60 * 1000;
@@ -437,7 +438,7 @@ export async function ensureFreshToken(
     }
 
     console.log('[TOKEN_LIFECYCLE] ensureFreshToken check:', {
-      sessionToken: sessionToken.substring(0, 8) + '...',
+      sessionToken: tokenLogId(sessionToken),
       accessTokenExpires: tokenExpiresStr,
       now: new Date().toISOString(),
       needsRefresh: needsRefreshNow,

package/src/lib/token-log-id.ts

@@ -0,0 +1,69 @@
+/**
+ * tokenLogId - a log-safe correlation id for a session token (PR 154 follow-up, BAPert ruling on PAY-1427:
+ * "no token material in logs, not even partial").
+ *
+ * The package used to log `sessionToken.substring(0, 8) + '...'` so lines about one session could be
+ * correlated. Those 8 characters ARE token material. This returns `h:` + the first 12 hex characters of
+ * SHA-256(token) instead: the same correlation (one token -> one stable id, across every log line and
+ * process), with nothing of the token itself.
+ *
+ * Synchronous and dependency-free on purpose: the call sites include Edge middleware
+ * (create-middleware, auth-decision) and browser code (authStore, SessionSync), where node:crypto is
+ * unavailable and Web Crypto's digest is async. SHA-256 below follows FIPS 180-4 and is verified
+ * against node:crypto in test/session-token-log-id.test.cjs.
+ */
+
+const K = new Uint32Array([
+  0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5,
+  0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3, 0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174,
+  0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da,
+  0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7, 0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967,
+  0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13, 0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85,
+  0xa2bfe8a1, 0xa81a664b, 0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070,
+  0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f, 0x682e6ff3,
+  0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208, 0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2,
+]);
+
+const rotr = (x: number, n: number): number => (x >>> n) | (x << (32 - n));
+
+/** SHA-256 of the UTF-8 encoding of `input`, as lowercase hex. */
+export function sha256Hex(input: string): string {
+  const msg = new TextEncoder().encode(input);
+  const bitLen = msg.length * 8;
+  const padded = new Uint8Array(((msg.length + 9 + 63) >> 6) << 6);
+  padded.set(msg);
+  padded[msg.length] = 0x80;
+  const view = new DataView(padded.buffer);
+  view.setUint32(padded.length - 8, Math.floor(bitLen / 0x100000000));
+  view.setUint32(padded.length - 4, bitLen >>> 0);
+
+  const h = new Uint32Array([0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a, 0x510e527f, 0x9b05688c, 0x1f83d9ab, 0x5be0cd19]);
+  const w = new Uint32Array(64);
+  for (let off = 0; off < padded.length; off += 64) {
+    for (let i = 0; i < 16; i++) w[i] = view.getUint32(off + i * 4);
+    for (let i = 16; i < 64; i++) {
+      const s15 = w[i - 15];
+      const s2 = w[i - 2];
+      const sigma0 = rotr(s15, 7) ^ rotr(s15, 18) ^ (s15 >>> 3);
+      const sigma1 = rotr(s2, 17) ^ rotr(s2, 19) ^ (s2 >>> 10);
+      w[i] = (w[i - 16] + sigma0 + w[i - 7] + sigma1) | 0;
+    }
+    let a = h[0], b = h[1], c = h[2], d = h[3], e = h[4], f = h[5], g = h[6], hh = h[7];
+    for (let i = 0; i < 64; i++) {
+      const t1 = (hh + (rotr(e, 6) ^ rotr(e, 11) ^ rotr(e, 25)) + ((e & f) ^ (~e & g)) + K[i] + w[i]) | 0;
+      const t2 = ((rotr(a, 2) ^ rotr(a, 13) ^ rotr(a, 22)) + ((a & b) ^ (a & c) ^ (b & c))) | 0;
+      hh = g; g = f; f = e; e = (d + t1) | 0; d = c; c = b; b = a; a = (t1 + t2) | 0;
+    }
+    h[0] = (h[0] + a) | 0; h[1] = (h[1] + b) | 0; h[2] = (h[2] + c) | 0; h[3] = (h[3] + d) | 0;
+    h[4] = (h[4] + e) | 0; h[5] = (h[5] + f) | 0; h[6] = (h[6] + g) | 0; h[7] = (h[7] + hh) | 0;
+  }
+  let out = '';
+  for (let i = 0; i < 8; i++) out += (h[i] >>> 0).toString(16).padStart(8, '0');
+  return out;
+}
+
+/** `h:` + 12 hex of SHA-256(token); `none` when there is no token. Never any part of the token itself. */
+export function tokenLogId(token: string | null | undefined): string {
+  if (typeof token !== 'string' || token.length === 0) return 'none';
+  return 'h:' + sha256Hex(token).slice(0, 12);
+}

package/src/lib/two-factor-verify-failure.ts

@@ -0,0 +1,167 @@
+/**
+ * PAY-1443: the ONE way a 2FA verify handler answers an IDP rejection.
+ *
+ * Found live (portal.keelauth.com /account-auth/verify-code, 2026-09-17): a wrong
+ * authenticator code rendered as the banner text `{ message = Invalid authentication code }`.
+ * The handlers relayed `result.json?.message` verbatim, and the IDP's error text is not a
+ * user-facing string:
+ *   - deployed IDP: the >=400 envelope sets Message = value.ToString() on the controller's
+ *     `new { message = ... }`, producing C#'s anonymous-object ToString `{ message = X }`
+ *     (or a DTO's TYPE NAME for a typed body);
+ *   - IDP master (e03a0e449): no ToString, but the lookup is case-sensitive, so the envelope
+ *     message is "An error occurred" and the real text sits only in error.details.message.
+ *
+ * So the upstream text is used ONLY TO CLASSIFY, never rendered. The caller gets:
+ *   - the upstream HTTP status, unchanged (verify-code's 401 branch probes session liveness);
+ *   - a stable `code` the UI can switch on;
+ *   - one of the fixed sentences below.
+ */
+import { NextResponse } from 'next/server';
+
+export type TwoFactorVerifyMethod = 'totp' | 'sms' | 'email' | 'backup_code';
+
+export type TwoFactorVerifyFailureCode =
+  | 'INVALID_CODE'
+  | 'LOCKED'
+  | 'RATE_LIMITED'
+  | 'SESSION_REJECTED'
+  | 'VERIFY_UNAVAILABLE'
+  | 'VERIFY_FAILED';
+
+const INVALID_CODE_TEXT: Record<TwoFactorVerifyMethod, string> = {
+  totp: 'Invalid authentication code. Please try again.',
+  sms: 'Invalid verification code. Please try again.',
+  email: 'Invalid verification code. Please try again.',
+  backup_code: 'Invalid backup code. Please try again.',
+};
+
+const FIXED_TEXT: Record<Exclude<TwoFactorVerifyFailureCode, 'INVALID_CODE'>, string> = {
+  LOCKED: 'Too many incorrect codes. Verification is locked for 15 minutes - wait before entering another code.',
+  RATE_LIMITED: 'Too many attempts. Please wait a moment and try again.',
+  SESSION_REJECTED: 'We could not verify the code for this session. Please try again.',
+  VERIFY_UNAVAILABLE: 'We could not verify the code right now. Please try again.',
+  VERIFY_FAILED: 'We could not verify that code. Please try again.',
+};
+
+/**
+ * MfaTotpService ErrorCode "locked": the bare code, or `code = locked` inside a deployed
+ * ToString envelope.
+ *
+ * CAUGHT BEFORE SHIPPING (self-test, this file): an earlier draft wrote this with  word
+ * boundaries around `code` and `locked`. The literal that landed on disk was not the two
+ * characters backslash+b - it was a raw ASCII backspace byte (0x08), invisible in every editor
+ * and terminal that rendered this file, INCLUDING Read/cat/grep in this session. A regex with a
+ * literal backspace control character where a word-boundary assertion was intended matches
+ * nothing real, so `IDP_LOCKED.test(...)` was silently false on every fixture - caught only
+ * because the RED-first test stayed red after the earlier "fix" and a hex dump of the compiled
+ * line showed 08 where 5c62 (backslash, b) should have been. Word boundaries are not
+ * load-bearing for the shipped control cases (a bare code=locked substring is specific enough
+ * here - the IdP field name is literally code), so this drops them rather than re-risk the same
+ * invisible-byte trap.
+ */
+const IDP_LOCKED = /^locked$|code\s*=\s*locked/i;
+
+/**
+ * MfaTotpService ErrorCode "server_error" (PAY-1589: secret cannot be decrypted) or "service_unavailable" (330830): the replay store could not be read or written, so
+ * the verify FAILED CLOSED. It is a fault on our side, not a wrong code. Matched on the CODE only, never on
+ * the prose - "unavailable" appears in unrelated messages - in the same two forms as IDP_LOCKED.
+ */
+const IDP_UNAVAILABLE = /^(?:service_unavailable|server_error)$|code\s*=\s*(?:service_unavailable|server_error)\b/i;
+
+const WRONG_CODE = /\b(invalid|incorrect|wrong|expired)\b[^.]{0,40}\b(code|otp|totp|token)\b|\binvalid_code\b/i;
+
+/**
+ * Every string the IDP might have put anywhere in the error envelope, unwrapped from
+ * `{ message = X }` ToString form. Classification input only.
+ */
+export function upstreamErrorTexts(json: unknown): string[] {
+  const out: string[] = [];
+  const add = (v: unknown) => {
+    if (typeof v !== 'string' || !v) return;
+    out.push(v);
+    const m = v.match(/^\{\s*\w+\s*=\s*(.*?)\s*\}$/s);
+    if (m) out.push(m[1]);
+  };
+  const j = json as Record<string, any> | null | undefined;
+  if (!j || typeof j !== 'object') return out;
+  add(j.message);
+  add(j.code);
+  add(j.error);
+  if (j.error && typeof j.error === 'object') {
+    add(j.error.message);
+    add(j.error.code);
+    const d = j.error.details;
+    if (d && typeof d === 'object') { add(d.message); add(d.Message); add(d.code); add(d.errorCode); }
+  }
+  return out;
+}
+
+export function classifyTwoFactorVerifyFailure(status: number, json: unknown): TwoFactorVerifyFailureCode {
+  // PAY-902 (BAPert R484): the IdP's lockout CODE, not its prose. Door A is post-authentication, so stating
+  // the lockout discloses nothing; telling a locked-out user "try again" sends them to spend attempts.
+  //
+  // PAY-1574: THIS MUST COME BEFORE THE 429 TEST. PayEz-Core PR 366 answers a TOTP lockout as HTTP 429 carrying
+  // code "locked". With `status === 429` first, that status returned RATE_LIMITED and the lock code the IdP had
+  // just started sending was discarded unread - the tester saw a plain rate limit. A 429 with NO lock code is
+  // still RATE_LIMITED, below.
+  if (upstreamErrorTexts(json).some((t) => IDP_LOCKED.test(t))) return 'LOCKED';
+  if (status === 429) return 'RATE_LIMITED';
+  // PAY-1574: the verify failed closed on OUR side (replay store down). Not a wrong code, whatever the status.
+  if (upstreamErrorTexts(json).some((t) => IDP_UNAVAILABLE.test(t))) return 'VERIFY_UNAVAILABLE';
+  if (upstreamErrorTexts(json).some((t) => WRONG_CODE.test(t))) return 'INVALID_CODE';
+  if (status === 401 || status === 403) return 'SESSION_REJECTED';
+  if (status >= 500 || status === 0) return 'VERIFY_UNAVAILABLE';
+  return 'VERIFY_FAILED';
+}
+
+export function twoFactorVerifyFailure(
+  result: { status: number; json: unknown; attemptedRefresh: boolean },
+  method: TwoFactorVerifyMethod,
+): NextResponse {
+  const code = classifyTwoFactorVerifyFailure(result.status, result.json);
+  const error = code === 'INVALID_CODE' ? INVALID_CODE_TEXT[method] : FIXED_TEXT[code];
+  return NextResponse.json(
+    { success: false, error, code, meta: { attemptedRefresh: result.attemptedRefresh } },
+    { status: result.status },
+  );
+}
+
+/**
+ * PAY-1443 residual: account/send-code on the SAME verify-code screen. A send has no
+ * "wrong code" outcome, so it gets its own small classification, but the same rule applies:
+ * upstream text/code never reach the response. The portal renders `data.message || data.error`,
+ * so no `message` field is emitted on failure.
+ */
+export type TwoFactorSendMethod = 'sms' | 'email';
+
+export type TwoFactorSendFailureCode =
+  | 'RATE_LIMITED'
+  | 'SESSION_REJECTED'
+  | 'SEND_UNAVAILABLE'
+  | 'SEND_FAILED';
+
+const SEND_LABEL: Record<TwoFactorSendMethod, string> = { sms: 'text message', email: 'email' };
+
+export function classifyTwoFactorSendFailure(status: number): TwoFactorSendFailureCode {
+  if (status === 429) return 'RATE_LIMITED';
+  if (status === 401 || status === 403) return 'SESSION_REJECTED';
+  if (status >= 500 || status === 0) return 'SEND_UNAVAILABLE';
+  return 'SEND_FAILED';
+}
+
+export function twoFactorSendCodeFailure(
+  result: { status: number; attemptedRefresh: boolean },
+  method: TwoFactorSendMethod,
+): NextResponse {
+  const code = classifyTwoFactorSendFailure(result.status);
+  const label = SEND_LABEL[method];
+  const error =
+    code === 'RATE_LIMITED' ? FIXED_TEXT.RATE_LIMITED
+    : code === 'SESSION_REJECTED' ? `We could not send a ${label} code for this session. Please try again.`
+    : code === 'SEND_UNAVAILABLE' ? `We could not send a ${label} code right now. Please try again.`
+    : `We could not send a ${label} code. Please try again.`;
+  return NextResponse.json(
+    { success: false, error, code, meta: { attemptedRefresh: result.attemptedRefresh } },
+    { status: result.status },
+  );
+}