@payez/next-mvp 4.5.0 → 4.5.2

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

@@ -1,248 +1,277 @@
-/**
- * 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 },
-  );
-}
+/**
+ * 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> = {
+  // PAY-1608: NO NUMBER HERE. This is the sentence for a lock whose window the IDP did not send; lockedText()
+  // states the real window when Retry-After arrives. A hard-coded "15 minutes" was true only while every lock was 15.
+  LOCKED: 'Too many incorrect codes. Verification is locked for now - even a correct code is refused until the lock ends. 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';
+}
+
+/**
+ * PAY-1608: the window as words - "15 minutes", "1 minute", "45 seconds", "2 hours". Rounded UP, so the user is never
+ * told a shorter wait than the IDP enforces. Undefined in, undefined out.
+ */
+export function formatLockWindow(seconds: number | undefined): string | undefined {
+  if (typeof seconds !== 'number' || !Number.isFinite(seconds) || seconds <= 0) return undefined;
+  const plural = (n: number, unit: string) => `${n} ${unit}${n === 1 ? '' : 's'}`;
+  if (seconds < 60) return plural(Math.ceil(seconds), 'second');
+  const minutes = Math.ceil(seconds / 60);
+  if (minutes < 120) return plural(minutes, 'minute');
+  return plural(Math.ceil(minutes / 60), 'hour');
+}
+
+/** PAY-1608: the LOCKED sentence with the IDP's real window, or the number-free one when none was sent. */
+export function lockedText(retryAfterSeconds?: number): string {
+  const window = formatLockWindow(retryAfterSeconds);
+  return window
+    ? `Too many incorrect codes. Verification is locked for ${window} - wait before entering another code.`
+    : FIXED_TEXT.LOCKED;
+}
+
+export function twoFactorVerifyFailure(
+  result: { status: number; json: unknown; attemptedRefresh: boolean; retryAfterSeconds?: number },
+  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]
+    : code === 'LOCKED' ? lockedText(result.retryAfterSeconds)
+      : FIXED_TEXT[code as keyof typeof FIXED_TEXT];
+  // PAY-1608: a lock or a throttle relays the IDP's window, as a number (for a client that words it itself) and as the
+  // standard header. Never on other failures, and never invented: absent upstream means absent here.
+  const wait = (code === 'LOCKED' || code === 'RATE_LIMITED') && formatLockWindow(result.retryAfterSeconds)
+    ? Math.ceil(result.retryAfterSeconds as number) : undefined;
+  return NextResponse.json(
+    { success: false, error, code, ...(wait ? { retryAfterSeconds: wait } : {}), meta: { attemptedRefresh: result.attemptedRefresh } },
+    { status: result.status, ...(wait ? { headers: { 'Retry-After': String(wait) } } : {}) },
+  );
+}
+
+/**
+ * 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

@@ -197,8 +197,30 @@ function getSafeCallbackUrl(pathname: string, searchParams?: URLSearchParams): s
   return resolveCallbackDestination(pathname, searchParams);
 }
 
-/** Clear all session cookies on a response */
+/**
+ * PAY-2136 Rule A: a speculative request (router prefetch) must NEVER mutate cookies.
+ * A prefetch of /account/security was answered 307 + Set-Cookie (session cookies expired), the browser
+ * applied it, and the user's next real request (e.g. Approve) was signed out. Detected by any of:
+ * `Next-Router-Prefetch: 1|2` (Next sets it on EVERY Link prefetch; 2 = runtime prefetch) or `Sec-Purpose`/`Purpose`
+ * containing "prefetch".
+ * NOT `RSC: 1` + `_rsc`: a real client-side navigation carries both too (Nextpert-Scout 70976), so that shape
+ * would swallow in-app navigations and stop the middleware refreshing/clearing for them.
+ */
+export function isPrefetchRequest(request: NextRequest): boolean {
+  const h = request.headers;
+  const nrp = h.get('next-router-prefetch');
+  if (nrp === '1' || nrp === '2') return true;
+  if (/prefetch/i.test(h.get('sec-purpose') ?? '') || /prefetch/i.test(h.get('purpose') ?? '')) return true;
+  return false;
+}
+
+/**
+ * Clear all session cookies on a response. The ONE site that writes the expiry Set-Cookie for the middleware,
+ * so the prefetch guard lives here: on a prefetch the redirect is still returned (routing unchanged) but
+ * carries no Set-Cookie; the next real navigation reaches the same decision and clears then.
+ */
 function clearSessionCookies(response: NextResponse, request: NextRequest): void {
+  if (isPrefetchRequest(request)) return;
   const sessionCookie = getSessionCookieName();
   const secureCookie = getSecureSessionCookieName();
 
@@ -736,6 +758,9 @@ async function executeDecision(
       return NextResponse.redirect(new URL('/service-unavailable', request.url));
 
     case 'refresh_needed':
+      // PAY-2136: a speculative request must not spend (rotate) a single-use refresh token or, on a 401/403,
+      // clear the session. Let it through; the real navigation refreshes.
+      if (isPrefetchRequest(request)) return NextResponse.next();
       return handleRefresh(request, safeCallback, opts);
   }
 }