@payez/next-mvp 4.4.5 → 4.4.7

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,248 @@
+/**
+ * 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'
+  | 'STEP_UP_FACTOR_NOT_ALLOWED'
+  | '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' | 'STEP_UP_FACTOR_NOT_ALLOWED'>, 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;
+
+/**
+ * PAY-1611: the IdP's 403 STEP_UP_FACTOR_NOT_ALLOWED refusal (Core ExternalAuthController.DeliveredCodeStepUpRefusal).
+ * A session signed in with an emailed/texted code only cannot re-prove itself with another emailed/texted code; the
+ * IdP says which factors it WILL take and what the user can do instead. The portal can only offer those options if
+ * this BFF relays them, so on that one refusal we emit the code plus ALLOWLISTED copies of the two lists.
+ *
+ * On the wire PayEzControllerBase.OnActionExecuted re-envelopes the action's object: the code is `error.code` and the
+ * object sits under `error.details`, so the lists are `error.details.allowed_methods` / `error.details.next_steps`.
+ * The unenveloped action shape (top-level `error` string, lists at top level) is accepted too.
+ *
+ * NEVER relayed (PAY-1443 stands): `error_description` or any other IdP prose, and any IdP `endpoint` - the consumer
+ * maps each action to its OWN route from a constant table. Unknown methods/actions are dropped, not passed through;
+ * missing or malformed lists give EMPTY lists, never invented ones.
+ */
+export const STEP_UP_REFUSAL_CODE = 'STEP_UP_FACTOR_NOT_ALLOWED';
+const STEP_UP_METHODS = ['totp', 'webauthn', 'backup_code'] as const;
+const STEP_UP_ACTIONS = ['use_authenticator', 'reset_password', 'enroll_authenticator'] as const;
+export type StepUpMethod = (typeof STEP_UP_METHODS)[number];
+export type StepUpAction = (typeof STEP_UP_ACTIONS)[number];
+export type StepUpNextStep = { action: 'use_authenticator'; methods: StepUpMethod[] } | { action: Exclude<StepUpAction, 'use_authenticator'> };
+export type StepUpRefusal = { allowed_methods: StepUpMethod[]; next_steps: StepUpNextStep[] };
+
+const STEP_UP_TEXT =
+  'This session was signed in with an emailed or texted code only, so another emailed or texted code cannot confirm it is you.';
+
+function allowedMethods(v: unknown): StepUpMethod[] {
+  if (!Array.isArray(v)) return [];
+  const out: StepUpMethod[] = [];
+  for (const m of v) {
+    if ((STEP_UP_METHODS as readonly unknown[]).includes(m) && !out.includes(m as StepUpMethod)) out.push(m as StepUpMethod);
+  }
+  return out;
+}
+
+/** The step-up refusal's allowlisted lists, or null when this is not that refusal (status 403 + the exact code only). */
+export function stepUpRefusal(status: number, json: unknown): StepUpRefusal | null {
+  if (status !== 403 || !json || typeof json !== 'object') return null;
+  const j = json as Record<string, unknown>;
+  const err = j.error;
+  let code: unknown;
+  let src: Record<string, unknown> = j;
+  if (err && typeof err === 'object') {
+    const e = err as Record<string, unknown>;
+    code = e.code;
+    src = e.details && typeof e.details === 'object' ? (e.details as Record<string, unknown>) : {};
+  } else {
+    code = err;
+  }
+  if (code !== STEP_UP_REFUSAL_CODE) return null;
+  const next_steps: StepUpNextStep[] = [];
+  const seen = new Set<string>();
+  for (const step of Array.isArray(src.next_steps) ? src.next_steps : []) {
+    if (!step || typeof step !== 'object') continue;
+    const action = (step as Record<string, unknown>).action;
+    if (typeof action !== 'string' || !(STEP_UP_ACTIONS as readonly string[]).includes(action) || seen.has(action)) continue;
+    seen.add(action);
+    next_steps.push(
+      action === 'use_authenticator'
+        ? { action, methods: allowedMethods((step as Record<string, unknown>).methods) }
+        : { action: action as Exclude<StepUpAction, 'use_authenticator'> },
+    );
+  }
+  return { allowed_methods: allowedMethods(src.allowed_methods), next_steps };
+}
+
+function stepUpResponse(refusal: StepUpRefusal, attemptedRefresh: boolean): NextResponse {
+  return NextResponse.json(
+    { success: false, error: STEP_UP_TEXT, code: STEP_UP_REFUSAL_CODE, ...refusal, meta: { attemptedRefresh } },
+    { status: 403 },
+  );
+}
+
+/**
+ * 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-1611: checked FIRST - an exact code on a 403, so no prose rule below can claim it first.
+  if (stepUpRefusal(status, json)) return 'STEP_UP_FACTOR_NOT_ALLOWED';
+  // 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 refusal = stepUpRefusal(result.status, result.json);
+  if (refusal) return stepUpResponse(refusal, result.attemptedRefresh);
+  const code = classifyTwoFactorVerifyFailure(result.status, result.json);
+  const error = code === 'INVALID_CODE' ? INVALID_CODE_TEXT[method] : FIXED_TEXT[code as keyof typeof FIXED_TEXT];
+  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'
+  | 'STEP_UP_FACTOR_NOT_ALLOWED'
+  | 'SEND_UNAVAILABLE'
+  | 'SEND_FAILED';
+
+const SEND_LABEL: Record<TwoFactorSendMethod, string> = { sms: 'text message', email: 'email' };
+
+export function classifyTwoFactorSendFailure(status: number, json?: unknown): TwoFactorSendFailureCode {
+  if (stepUpRefusal(status, json)) return 'STEP_UP_FACTOR_NOT_ALLOWED'; // PAY-1611, before the 401/403 branch
+  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; json?: unknown },
+  method: TwoFactorSendMethod,
+): NextResponse {
+  const refusal = stepUpRefusal(result.status, result.json);
+  if (refusal) return stepUpResponse(refusal, result.attemptedRefresh);
+  const code = classifyTwoFactorSendFailure(result.status, result.json);
+  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 },
+  );
+}

package/src/middleware/create-middleware.ts

@@ -23,6 +23,7 @@ import { resolveCallbackDestination } from '../auth/safe-callback';
 import { getInternalApiUrl } from '../edge/internal-api-url';
 import { getSessionCookieName, getSecureSessionCookieName } from '../lib/app-slug';
 import { checkPagePermission, isRBACEnabled } from './rbac-check';
+import { tokenLogId } from '../lib/token-log-id';
 
 // =============================================================================
 // TYPES
@@ -40,7 +41,8 @@ export interface AuthContext {
 
 export interface SessionPointer {
   exists: boolean;
-  sessionToken?: string;
+  /** PAY-1481: tokenLogId of the session token (presence + log correlation), never the token itself. */
+  sessionTokenId?: string | null;
   expired?: boolean;
   hasRefreshToken?: boolean;
   roles: string[];
@@ -208,6 +210,40 @@ function redirectTo(
   return response;
 }
 
+/**
+ * Terminal response for a FAILED token refresh.
+ *
+ * For `/api/` requests a redirect is the wrong terminator: fetch() follows the 307,
+ * receives 200 + an HTML login page, and the caller parses garbage instead of
+ * branching on an error. Those callers get a 401 JSON body they can branch on;
+ * document requests keep the existing redirect exactly as before.
+ *
+ * Cookie-clearing is preserved on BOTH arms. That is load-bearing, not incidental:
+ * on a permanent failure (401/403) stale cookies must be cleared or the next request
+ * refreshes again and loops (see the CRITICAL note in handleRefresh). A JSON arm that
+ * skipped clearing would convert a redirect loop into a silent refresh loop.
+ *
+ * Scoped deliberately to handleRefresh's failure exits. It is NOT folded into
+ * redirectTo(), and NOT hoisted above the refresh decision: an `/api/` hatch placed
+ * higher would intercept 'refresh_needed' and disable middleware token refresh across
+ * the whole API surface (card 340024 C1).
+ */
+function refreshFailureResponse(
+  request: NextRequest,
+  location: string,
+  errorCode: string,
+  clearCookies = false
+): NextResponse {
+  if (request.nextUrl.pathname.startsWith('/api/')) {
+    const response = NextResponse.json({ error: errorCode }, { status: 401 });
+    if (clearCookies) {
+      clearSessionCookies(response, request);
+    }
+    return response;
+  }
+  return redirectTo(request, location, clearCookies);
+}
+
 // =============================================================================
 // AUTH DECISION ENGINE
 // =============================================================================
@@ -220,6 +256,29 @@ function makeAuthDecision(ctx: AuthContext): AuthAction {
   const { pathname, isPublicRoute, isLoginPage: onLoginPage, searchParams, sessionPointer, sessionStatus, circuitBreakerOpen } = ctx;
   const safeCallback = getSafeCallbackUrl(pathname);
 
+  // --- PAY-884: a provisional (pre-2FA) session whose token has expired can never finish 2FA ---
+  // The IdP issues no refresh token until 2FA completes, and it validates token lifetime, so
+  // once the provisional access token expires neither refresh nor code verification can
+  // succeed. Sending the user to the verify-code page (or to error=SessionExpired, which the
+  // login page deliberately shows as NO message) strands them mid-2FA with no explanation.
+  // Say what happened instead, and clear the dead session so the next sign-in starts clean.
+  // Scoped to the verify-code page and protected pages: /api/ keeps its 401-JSON carve-out
+  // (307290), the login page stays reachable, and public pages are left to the existing arms.
+  if (
+    isExpiredProvisionalSession(sessionPointer, sessionStatus) &&
+    !pathname.startsWith('/api/') &&
+    !onLoginPage &&
+    (pathname === VERIFY_CODE_PAGE || !isPublicRoute)
+  ) {
+    const callback = pathname === VERIFY_CODE_PAGE ? getSafeCallbackUrl(pathname, searchParams) : safeCallback;
+    return {
+      type: 'redirect',
+      location: `${LOGIN_PAGE}?callbackUrl=${encodeURIComponent(callback)}&error=${TWO_FACTOR_TIMEOUT_ERROR}`,
+      reason: 'pre_2fa_token_expired',
+      clearCookies: true,
+    };
+  }
+
   // --- Public routes: Allow, but enforce 2FA for authenticated users ---
   if (isPublicRoute && !onLoginPage) {
     if (needsTwoFactorRedirect(pathname, sessionPointer, sessionStatus)) {
@@ -328,6 +387,25 @@ function makeAuthDecision(ctx: AuthContext): AuthAction {
   return { type: 'allow' };
 }
 
+/** Login error code for a pre-2FA session that expired before the code was verified (PAY-884). */
+export const TWO_FACTOR_TIMEOUT_ERROR = 'TwoFactorTimeout';
+
+/**
+ * PAY-884: 2FA outstanding, access token expired, and no refresh token to renew it.
+ * Only a viability answer that positively says the session exists qualifies (null = check failed).
+ */
+function isExpiredProvisionalSession(session: SessionPointer, status: SessionStatus): boolean {
+  return (
+    session.exists &&
+    status.exists === true &&
+    status.forceInvalid === false &&
+    status.requires2FA &&
+    !status.twoFactorComplete &&
+    session.expired === true &&
+    !session.hasRefreshToken
+  );
+}
+
 /** Check if user needs 2FA redirect */
 function needsTwoFactorRedirect(pathname: string, session: SessionPointer, status: SessionStatus): boolean {
   if (!session.exists || !status.exists) return false;
@@ -423,9 +501,16 @@ export function createMvpMiddleware(options: MvpMiddlewareOptions = {}) {
     // The warning is deliberately KEPT: it is the only operational signal that
     // stale sessions are occurring, and it costs nothing to log before
     // delegating. Do not re-introduce a `return` in this block.
-    if (!isPublic && sessionStatus.exists === false && sessionPointer.sessionToken) {
+    if (!isPublic && sessionStatus.exists === false && sessionPointer.sessionTokenId) {
+      // PAY-1505: the KEY is `sessionTokenId`, not `sessionToken`. The value has
+      // always been a tokenLogId fingerprint (viability.ts builds it as
+      // `tokenLogId(sessionToken)`), but labelling it `sessionToken` told any
+      // operator reading this log that the line carried the token itself. The
+      // credential-in-logs source guard reads the key for exactly that reason:
+      // a field named `sessionToken` must hold a safe value, and proving that
+      // across an API boundary is not possible from the name alone.
       log.warn('Stale session detected (delegating to decision engine)', {
-        sessionToken: sessionPointer.sessionToken?.substring(0, 8) + '...',
+        sessionTokenId: sessionPointer.sessionTokenId,
         pathname
       });
     }
@@ -470,7 +555,7 @@ async function checkViability(
   };
   const sessionPointer: SessionPointer = {
     exists: false,
-    sessionToken: undefined,
+    sessionTokenId: undefined,
     expired: false,
     hasRefreshToken: false,
     roles: [],
@@ -493,11 +578,11 @@ async function checkViability(
     if (response.ok) {
       const data = await response.json();
       // Support both response formats (viability and refresh-viability)
-      sessionStatus.exists = data.authenticated ?? (data.sessionToken && data.reason !== 'session_not_found');
+      sessionStatus.exists = data.authenticated ?? (!!data.sessionTokenId && data.reason !== 'session_not_found');
       sessionStatus.requires2FA = data.requires2FA || false;
       sessionStatus.twoFactorComplete = data.twoFactorComplete || false;
       sessionPointer.exists = sessionStatus.exists ?? false;
-      sessionPointer.sessionToken = data.sessionToken;
+      sessionPointer.sessionTokenId = data.sessionTokenId ?? null;
       sessionPointer.expired = data.accessTokenExpired || false;
       sessionPointer.hasRefreshToken = data.hasRefreshToken ?? data.canRefresh ?? false;
       sessionPointer.roles = data.roles || [];
@@ -630,9 +715,10 @@ async function handleRefresh(
   // Check if circuit breaker allows refresh attempt
   if (!cb.canAttemptRefresh()) {
     log.warn('Circuit breaker preventing refresh attempt');
-    return redirectTo(
+    return refreshFailureResponse(
       request,
       `${LOGIN_PAGE}?callbackUrl=${encodeURIComponent(safeCallback)}&error=ServiceUnavailable`,
+      'ServiceUnavailable',
       true
     );
   }
@@ -677,9 +763,10 @@ async function handleRefresh(
 
     onRefreshFailure?.(response.status, false);
 
-    return redirectTo(
+    return refreshFailureResponse(
       request,
       `${LOGIN_PAGE}?callbackUrl=${encodeURIComponent(safeCallback)}&error=${errorParam}`,
+      errorParam,
       isPermanentFailure
     );
   } catch (error: any) {
@@ -697,9 +784,10 @@ async function handleRefresh(
     onRefreshFailure?.(0, isNetwork);
 
     // Network error - don't clear cookies, might be transient
-    return redirectTo(
+    return refreshFailureResponse(
       request,
       `${LOGIN_PAGE}?callbackUrl=${encodeURIComponent(safeCallback)}&error=RefreshError`,
+      'RefreshError',
       false
     );
   }

package/src/pages/login/page.tsx

@@ -141,6 +141,10 @@ function LoginForm({ altAuthSlot }: { altAuthSlot?: React.ReactNode }) {
         // Session expiration is normal - don't show as error
         console.log('[LOGIN] SessionExpired detected - normal behavior');
         friendlyError = null;
+      } else if (urlError === 'TwoFactorTimeout') {
+        // PAY-884: the sign-in expired while the verification code was outstanding. Unlike
+        // SessionExpired this is NOT silent - the user was mid-2FA and must know why they are here.
+        friendlyError = 'Your verification step timed out before the code was confirmed. Please sign in again.';
       } else if (urlError === 'ServiceUnavailable') {
         friendlyError = 'Authentication service is temporarily unavailable. Please try again in a few minutes.';
       } else if (urlError.startsWith("Unexpected token")) {

package/src/pages/recovery/page.tsx

@@ -9,6 +9,7 @@ import { SelectMethodStep } from '../../components/recovery/SelectMethodStep';
 import { VerifyCodeStep } from '../../components/recovery/VerifyCodeStep';
 import { SetPasswordStep } from '../../components/recovery/SetPasswordStep';
 import { CompleteStep } from '../../components/recovery/CompleteStep';
+import { RequestedStep } from '../../components/recovery/RequestedStep';
 import { useColors } from '../../theme/useTheme';
 
 function RecoveryContent() {
@@ -24,7 +25,12 @@ function RecoveryContent() {
   const [verificationCode, setVerificationCode] = useState('');
   const [passwordResetToken, setPasswordResetToken] = useState<PasswordResetToken | null>(null);
   const [error, setError] = useState<string | null>(null);
+  // PAY-1591: true when the reset failed because the recovery itself is dead; the error box then offers a way back.
+  const [recoveryExpired, setRecoveryExpired] = useState(false);
   const [loading, setLoading] = useState(false);
+  // PAY-1588: true only after the IdP accepted the new password. The 'complete' step is ALSO reached from initiate()
+  // when no recovery session comes back, and that path must not tell the user a password was set.
+  const [resetSucceeded, setResetSucceeded] = useState(false);
 
   const handleInitiateRecovery = async () => {
     setLoading(true);
@@ -33,7 +39,7 @@ function RecoveryContent() {
     try {
       const response = await accountApi.initiateRecovery(email);
 
-      if (response.success && response.data.recovery_session_token) {
+      if (response.success && response.data?.recovery_session_token) {
         setRecoverySession({
           recoveryToken: response.data.recovery_session_token,
           email: email,
@@ -45,7 +51,8 @@ function RecoveryContent() {
         });
         setCurrentStep('select-method');
       } else {
-        setCurrentStep('complete');
+        // No recovery session (unknown / locked / throttled): the ONE neutral step, never CompleteStep (rigpert 60711).
+        setCurrentStep('requested');
       }
     } catch (err) {
       setError(err instanceof Error ? err.message : 'Failed to initiate recovery. Please try again.');
@@ -110,6 +117,7 @@ function RecoveryContent() {
 
     setLoading(true);
     setError(null);
+    setRecoveryExpired(false);
 
     try {
       const response = await accountApi.resetPasswordWithToken(
@@ -120,12 +128,14 @@ function RecoveryContent() {
       );
 
       if (response.success) {
+        setResetSucceeded(true);
         setCurrentStep('complete');
       } else {
         setError('Failed to reset password. Please try again.');
       }
     } catch (err) {
       setError(err instanceof Error ? err.message : 'Failed to reset password.');
+      setRecoveryExpired(!!err && (err as { code?: string }).code === 'RECOVERY_EXPIRED');
     } finally {
       setLoading(false);
     }
@@ -143,6 +153,11 @@ function RecoveryContent() {
         {error && (
           <div className="mb-4 bg-red-50 border border-red-200 rounded-2xl p-3">
             <p className="text-red-700 text-sm">{error}</p>
+            {recoveryExpired && (
+              <a href="/account-auth/recovery" className="text-sm font-medium underline">
+                Start password recovery again
+              </a>
+            )}
           </div>
         )}
 
@@ -191,13 +206,15 @@ function RecoveryContent() {
           />
         )}
 
+        {currentStep === 'requested' && <RequestedStep onGoToLogin={() => router.push('/account-auth/login')} />}
+
         {currentStep === 'complete' && (
           <CompleteStep
-            onGoToLogin={() => router.push('/account-auth/login')}
+            onGoToLogin={() => router.push(resetSucceeded ? '/account-auth/login?notice=password-set' : '/account-auth/login')}
           />
         )}
 
-        {currentStep !== 'complete' && currentStep !== 'initiate' && !loading && (
+        {currentStep !== 'complete' && currentStep !== 'requested' && currentStep !== 'initiate' && !loading && (
           <div className="mt-6 text-center">
             <button
               type="button"