@payez/next-mvp 4.12.1 → 4.13.1

package/src/lib/qrcode.ts

@@ -0,0 +1,348 @@
+/**
+ * qrcode.ts — minimal QR Code generator (byte mode, ECC level M), a
+ * TypeScript port of Nayuki's qrcodegen (MIT) trimmed to what TOTP
+ * otpauth:// URIs need. Renders to an SVG path string (no library, no
+ * canvas) — D3 MFA page generates the QR client-side per contract
+ * (fe-be-contract §D3.1: "no BE QR image needed").
+ *
+ * Cross-checked bit-exact against python `qrcode` (see D3 day-end report).
+ * PAY-2631: copied verbatim from VibeID-Customer-Portal src/lib/qrcode.ts so the generated app draws the QR itself:
+ * the TOTP secret is never sent to a third-party QR service.
+ */
+
+// Galois field tables for Reed–Solomon
+const EXP = new Uint8Array(512);
+const LOG = new Uint8Array(256);
+(() => {
+  let x = 1;
+  for (let i = 0; i < 255; i++) {
+    EXP[i] = x;
+    LOG[x] = i;
+    x <<= 1;
+    if (x & 0x100) x ^= 0x11d;
+  }
+  for (let i = 255; i < 512; i++) EXP[i] = EXP[i - 255];
+})();
+
+function gfMul(a: number, b: number): number {
+  return a === 0 || b === 0 ? 0 : EXP[LOG[a] + LOG[b]];
+}
+
+// ECC codewords per block + block count, level M, versions 1–40
+// [eccPerBlock, numBlocks] indexed by version
+const M_TABLE: Array<[number, number]> = [
+  [0, 0],
+  [10, 1], [16, 1], [26, 1], [18, 2], [24, 2], [16, 4], [18, 4], [22, 4], [22, 5], [26, 5], // 1-10
+  [26, 6], [24, 6], [28, 8], [28, 7], [24, 10], [26, 10], [26, 11], [28, 12], [28, 11], [30, 12], // 11-20
+];
+
+function rawDataModules(version: number): number {
+  // Nayuki qrcodegen getNumRawDataModules — exact.
+  let result = (16 * version + 128) * version + 64;
+  if (version >= 2) {
+    const numAlign = Math.floor(version / 7) + 2;
+    result -= (25 * numAlign - 10) * numAlign - 55;
+    if (version >= 7) result -= 36;
+  }
+  return result;
+}
+
+function dataCodewords(version: number, eccPerBlock: number, numBlocks: number): number {
+  return Math.floor(rawDataModules(version) / 8) - eccPerBlock * numBlocks;
+}
+
+interface BitBuffer {
+  bits: number[];
+}
+
+function appendBits(buf: BitBuffer, val: number, len: number) {
+  for (let i = len - 1; i >= 0; i--) buf.bits.push((val >>> i) & 1);
+}
+
+function buildSegments(text: string, buf: BitBuffer) {
+  // byte mode: 0100, count(8 for v1-9 / 16 for v10+), data
+  const bytes = new TextEncoder().encode(text);
+  appendBits(buf, 0x4, 4);
+  return bytes;
+}
+
+function reedSolomon(data: Uint8Array, degree: number): Uint8Array {
+  // generator polynomial
+  const gen = new Uint8Array(degree);
+  gen[degree - 1] = 1;
+  let root = 1;
+  for (let i = 0; i < degree; i++) {
+    for (let j = 0; j < degree; j++) {
+      gen[j] = gfMul(gen[j], root);
+      if (j + 1 < degree) gen[j] ^= gen[j + 1];
+    }
+    root = gfMul(root, 0x02);
+  }
+  const res = new Uint8Array(degree);
+  for (const b of data) {
+    const factor = b ^ res[0];
+    res.copyWithin(0, 1);
+    res[degree - 1] = 0;
+    for (let i = 0; i < degree; i++) res[i] ^= gfMul(gen[i], factor);
+  }
+  return res;
+}
+
+const MASKS: Array<(r: number, c: number) => boolean> = [
+  (r, c) => (r + c) % 2 === 0,
+  (r) => r % 2 === 0,
+  (r, c) => c % 3 === 0,
+  (r, c) => (r + c) % 3 === 0,
+  (r, c) => (Math.floor(r / 2) + Math.floor(c / 3)) % 2 === 0,
+  (r, c) => ((r * c) % 2) + ((r * c) % 3) === 0,
+  (r, c) => (((r * c) % 2) + ((r * c) % 3)) % 2 === 0,
+  (r, c) => (((r + c) % 2) + ((r * c) % 3)) % 2 === 0,
+];
+
+const FORMAT_ECC_M = 0; // format bits use (ecc,mask); M=00
+const FORMAT_LOOKUP: number[] = (() => {
+  // Precomputed BCH(15,5) format strings for ecc=M(00), mask 0-7
+  const table: number[] = [];
+  for (let mask = 0; mask < 8; mask++) {
+    const data = (0 << 3) | mask;
+    let rem = data;
+    for (let i = 0; i < 10; i++) rem = (rem << 1) ^ ((rem >>> 9) * 0x537);
+    table.push(((data << 10) | rem) ^ 0x5412);
+  }
+  return table;
+})();
+
+export interface QrMatrix {
+  size: number;
+  modules: boolean[][]; // [row][col], true = dark
+}
+
+/** Full pre-matrix pipeline: version pick → bitstream → ECC → interleave.
+ *  Exported for the python cross-check harness (debugFinalBytes). */
+function buildFinalData(text: string): { version: number; finalData: number[] } {
+  const bytes = new TextEncoder().encode(text);
+  // pick smallest version (1-10 supported) that fits: capacity M byte mode
+  let version = 0;
+  let dataCw = 0;
+  let eccPerBlock = 0;
+  let numBlocks = 0;
+  for (let v = 1; v <= 10; v++) {
+    [eccPerBlock, numBlocks] = M_TABLE[v];
+    dataCw = dataCodewords(v, eccPerBlock, numBlocks);
+    const countBits = v <= 9 ? 8 : 16;
+    const needed = Math.ceil((4 + countBits + bytes.length * 8) / 8);
+    if (needed <= dataCw) {
+      version = v;
+      break;
+    }
+  }
+  if (version === 0) throw new Error('text too long for QR v10-M');
+
+  // bit stream: mode, count, data, terminator, pad
+  const buf: BitBuffer = { bits: [] };
+  buildSegments(text, buf);
+  const countBits = version <= 9 ? 8 : 16;
+  appendBits(buf, bytes.length, countBits);
+  for (const b of bytes) appendBits(buf, b, 8);
+  const capacity = dataCw * 8;
+  appendBits(buf, 0, Math.min(4, capacity - buf.bits.length));
+  while (buf.bits.length % 8 !== 0) buf.bits.push(0);
+  const data = new Uint8Array(dataCw);
+  for (let i = 0; i < buf.bits.length / 8; i++) {
+    let b = 0;
+    for (let j = 0; j < 8; j++) b = (b << 1) | buf.bits[i * 8 + j];
+    data[i] = b;
+  }
+  for (let i = buf.bits.length / 8, pad = 0xec; i < dataCw; i++, pad ^= 0xec ^ 0x11) data[i] = pad;
+
+  // ECC + interleave
+  const blockLen = Math.floor(dataCw / numBlocks);
+  const longBlocks = dataCw % numBlocks;
+  const blocks: Uint8Array[] = [];
+  const eccs: Uint8Array[] = [];
+  let off = 0;
+  for (let i = 0; i < numBlocks; i++) {
+    const len = blockLen + (i >= numBlocks - longBlocks ? 1 : 0);
+    const blk = data.slice(off, off + len);
+    off += len;
+    blocks.push(blk);
+    eccs.push(reedSolomon(blk, eccPerBlock));
+  }
+  const finalData: number[] = [];
+  const maxLen = blockLen + 1;
+  for (let i = 0; i < maxLen; i++) {
+    for (let b = 0; b < numBlocks; b++) {
+      if (i < blocks[b].length) finalData.push(blocks[b][i]);
+    }
+  }
+  for (let i = 0; i < eccPerBlock; i++) {
+    for (let b = 0; b < numBlocks; b++) finalData.push(eccs[b][i]);
+  }
+  return { version, finalData };
+}
+
+export function debugFinalBytes(text: string): { version: number; bytes: number[] } {
+  const { version, finalData } = buildFinalData(text);
+  return { version, bytes: finalData };
+}
+
+export function encodeQr(text: string, maskOverride?: number): QrMatrix {
+  const { version, finalData } = buildFinalData(text);
+  const size = 17 + version * 4;
+  const mod: boolean[][] = Array.from({ length: size }, () => new Array(size).fill(false));
+  const isFunc: boolean[][] = Array.from({ length: size }, () => new Array(size).fill(false));
+  const setF = (r: number, c: number, v: boolean) => {
+    mod[r][c] = v;
+    isFunc[r][c] = true;
+  };
+  const finder = (r: number, c: number) => {
+    for (let dr = -1; dr <= 7; dr++)
+      for (let dc = -1; dc <= 7; dc++) {
+        const rr = r + dr;
+        const cc = c + dc;
+        if (rr < 0 || cc < 0 || rr >= size || cc >= size) continue;
+        const inOuter = dr >= 0 && dr <= 6 && dc >= 0 && dc <= 6;
+        const v = inOuter && (dr === 0 || dr === 6 || dc === 0 || dc === 6 || (dr >= 2 && dr <= 4 && dc >= 2 && dc <= 4));
+        setF(rr, cc, v);
+      }
+  };
+  finder(0, 0);
+  finder(0, size - 7);
+  finder(size - 7, 0);
+  // alignment pattern centers per spec table
+  const aligns =
+    version === 1 ? [] :
+    version === 2 ? [6, 18] :
+    version === 3 ? [6, 22] :
+    version === 4 ? [6, 26] :
+    version === 5 ? [6, 30] :
+    version === 6 ? [6, 34] :
+    version === 7 ? [6, 22, 38] :
+    version === 8 ? [6, 24, 42] :
+    version === 9 ? [6, 26, 46] :
+                    [6, 28, 50]; // v10
+  for (const r of aligns)
+    for (const c of aligns) {
+      if ((r === 6 && c === 6) || (r === 6 && c === size - 7) || (r === size - 7 && c === 6)) continue;
+      for (let dr = -2; dr <= 2; dr++)
+        for (let dc = -2; dc <= 2; dc++) setF(r + dr, c + dc, Math.max(Math.abs(dr), Math.abs(dc)) !== 1);
+    }
+  // timing
+  for (let i = 8; i < size - 8; i++) {
+    if (!isFunc[6][i]) setF(6, i, i % 2 === 0);
+    if (!isFunc[i][6]) setF(i, 6, i % 2 === 0);
+  }
+  // dark module + format cells reserved (values written per mask).
+  // Canonical layout (verified against python-qrcode cell-for-cell):
+  //   copy 1: (8,0..5)=bits14..9, (8,7)=bit8, (8,8)=bit7, (7,8)=bit6,
+  //           (0..5,8)=bits0..5
+  //   copy 2: (n-1..n-7, 8)=bits14..8, (8, n-8..n-1)=bits7..0
+  //   dark module (n-8, 8) = 1
+  setF(size - 8, 8, true);
+  const formatCells: Array<[number, number]> = [];
+  for (let i = 0; i <= 5; i++) formatCells.push([8, i]);
+  formatCells.push([8, 7], [8, 8], [7, 8]);
+  for (let i = 0; i <= 5; i++) formatCells.push([i, 8]);
+  for (let i = 0; i <= 6; i++) formatCells.push([size - 1 - i, 8]);
+  for (let i = 0; i < 8; i++) formatCells.push([8, size - 8 + i]);
+  for (const [r, c] of formatCells) {
+    if (!(r === size - 8 && c === 8)) setF(r, c, false);
+  }
+
+  // data placement (zigzag) — finalData is BYTES; place their BITS MSB-first
+  const placeData = (mask: number) => {
+    const m = mod.map((row) => row.slice());
+    let bit = 0;
+    let upward = true;
+    for (let c = size - 1; c >= 1; c -= 2) {
+      if (c === 6) c = 5;
+      for (let i = 0; i < size; i++) {
+        const r = upward ? size - 1 - i : i;
+        for (const cc of [c, c - 1]) {
+          if (isFunc[r][cc]) continue;
+          const byte = finalData[bit >>> 3] ?? 0;
+          let v = bit < finalData.length * 8 ? ((byte >>> (7 - (bit & 7))) & 1) === 1 : false;
+          if (MASKS[mask](r, cc)) v = !v;
+          m[r][cc] = v;
+          bit++;
+        }
+      }
+      upward = !upward;
+    }
+    // format bits — canonical placement, both copies
+    const fmt = FORMAT_LOOKUP[(FORMAT_ECC_M << 3) | mask];
+    const fbit = (i: number) => ((fmt >>> i) & 1) === 1;
+    for (let i = 0; i <= 5; i++) m[8][i] = fbit(14 - i);
+    m[8][7] = fbit(8);
+    m[8][8] = fbit(7);
+    m[7][8] = fbit(6);
+    for (let i = 0; i <= 5; i++) m[i][8] = fbit(i);
+    for (let i = 0; i <= 6; i++) m[size - 1 - i][8] = fbit(14 - i);
+    for (let i = 0; i < 8; i++) m[8][size - 8 + i] = fbit(7 - i);
+    return m;
+  };
+
+  // mask selection by penalty
+  const penalty = (g: boolean[][]): number => {
+    let score = 0;
+    const s = g.length;
+    // N1 runs
+    for (let i = 0; i < s; i++) {
+      for (const dir of [0, 1]) {
+        let run = 1;
+        for (let j = 1; j <= s; j++) {
+          const same = j < s && (dir === 0 ? g[i][j] === g[i][j - 1] : g[j][i] === g[j - 1][i]);
+          if (same) run++;
+          else {
+            if (run >= 5) score += 3 + (run - 5);
+            run = 1;
+          }
+        }
+      }
+    }
+    // N2 blocks
+    for (let r = 0; r < s - 1; r++)
+      for (let c = 0; c < s - 1; c++)
+        if (g[r][c] === g[r + 1][c] && g[r][c] === g[r][c + 1] && g[r][c] === g[r + 1][c + 1]) score += 3;
+    // N3 finder-like
+    const pat = [true, false, true, true, true, false, true, false, false, false, false];
+    const patR = [...pat].reverse();
+    for (let i = 0; i < s; i++) {
+      for (let j = 0; j + 11 <= s; j++) {
+        const row = g[i].slice(j, j + 11);
+        const rowS = row.every((v, k) => v === pat[k]) || row.every((v, k) => v === patR[k]);
+        if (rowS) score += 40;
+        const col = Array.from({ length: 11 }, (_, k) => g[j + k][i]);
+        const colS = col.every((v, k) => v === pat[k]) || col.every((v, k) => v === patR[k]);
+        if (colS) score += 40;
+      }
+    }
+    // N4 balance
+    const dark = g.flat().filter(Boolean).length;
+    const pct = (dark * 100) / (s * s);
+    score += Math.floor(Math.abs(pct - 50) / 5) * 10;
+    return score;
+  };
+
+  if (maskOverride !== undefined) return { size, modules: placeData(maskOverride) };
+
+  let best: boolean[][] = [];
+  let bestScore = Infinity;
+  for (let mask = 0; mask < 8; mask++) {
+    const g = placeData(mask);
+    const sc = penalty(g);
+    if (sc < bestScore) {
+      bestScore = sc;
+      best = g;
+    }
+  }
+  return { size, modules: best };
+}
+
+/** Render to an SVG path (dark modules as 1x1 squares). */
+export function qrToSvgPath(qr: QrMatrix): string {
+  const parts: string[] = [];
+  for (let r = 0; r < qr.size; r++)
+    for (let c = 0; c < qr.size; c++) if (qr.modules[r][c]) parts.push(`M${c},${r}h1v1h-1z`);
+  return parts.join('');
+}

package/src/lib/sign-in-failure.ts

@@ -0,0 +1,88 @@
+/**
+ * PAY-2568 / PAY-2279 (BAPert 85415, 85419): what a failed credential sign-in SAYS, and the stable machine code it carries.
+ *
+ * ONE closed table. The sentence the page shows comes from here, keyed on a code; it never comes from a server message string
+ * (the IdP's wire text, a stack, an upstream detail). The code is derived from the response STATUS plus the IdP's error CODE
+ * (never its message text):
+ *
+ *   invalid_credentials  wrong password OR unknown account OR any other refusal. Identical on purpose: the sentence and the body
+ *                        must not separate "no such account" from "wrong password" (user enumeration).
+ *   not_a_member         the IdP error code NotAMemberOfThisApp, whatever the HTTP status. Decided by the IdP AFTER the password is
+ *                        proven (PayEz-Core InternalTokenController.IssueCorporateToken: password validation 401s first, membership
+ *                        comes after), so this sentence is shown only to someone who proved the credentials. The STATUS is not part
+ *                        of the key: the internal mint door answers 403, but the PUBLIC door relays the same refusal as HTTP 400
+ *                        (measured on dev-93, PR 1719 walk, Scout 85449). Keying on 403 made rule 2 unreachable.
+ *   too_many_attempts    429 (any code), or an AccountLocked / UserLockedOut refusal. One sentence for both: the user is not told
+ *                        which. A lockout exists only for a real account, which is an accepted, argued signal (BAPert 85419).
+ */
+
+export type SignInFailureCode =
+  | 'invalid_credentials'
+  | 'not_a_member'
+  | 'too_many_attempts'
+  | 'invalid_second_factor'
+  | 'second_factor_unavailable'
+  | 'second_factor_rate_limited';
+
+export const SIGN_IN_FAILURE_COPY: Record<SignInFailureCode, string> = {
+  invalid_credentials: 'Incorrect email or password.',
+  not_a_member: "Your account does not have access to this app. Ask the app's administrator to invite you.",
+  too_many_attempts: 'Too many sign-in attempts. Wait a few minutes and try again, or reset your password.',
+  // The code step (after the password was proven). BAPert 85795 item 2 wrote the first sentence; the second is the sentence this lane
+  // already showed for an IdP-side fault (twofa-rejection.ts), now chosen by code like the rest. Neither depends on IdP wording: the
+  // IdP answers a wrong TOTP code with the generic code INVALID_REQUEST + 'Invalid code', so the branch (status + lockout/fault codes),
+  // not the IdP code, decides.
+  invalid_second_factor: 'That code is not correct. Check the code and try again.',
+  // A plain IdP 429 on the code step (NOT a lockout, which stays too_many_attempts). BAPert 85813: 'your code is still valid' is dropped because
+  // nothing in this package proves a rate-limited attempt leaves the code unconsumed; add it back only on the IdP owner's confirmation.
+  second_factor_rate_limited: 'Too many attempts. Wait a few minutes and try again.',
+  second_factor_unavailable: 'We could not check your code just now - this is a problem on our side, not with your code. Try again shortly.',
+};
+
+/**
+ * BAPert 85807: the lockout sentence states the window when the server sent one. N = retryAfter (seconds) rounded UP to whole minutes,
+ * clamped to an integer 1..60. Absent, unparseable or non-finite -> the plain table sentence. Only a NUMBER from the server is printed,
+ * never text. (1 is "1 minute", not "1 minutes".)
+ */
+export function tooManyAttemptsMessage(retryAfterSeconds: unknown, code: 'too_many_attempts' | 'second_factor_rate_limited' = 'too_many_attempts'): string {
+  const n = typeof retryAfterSeconds === 'number' ? retryAfterSeconds : typeof retryAfterSeconds === 'string' && /^\s*\d+(\.\d+)?\s*$/.test(retryAfterSeconds) ? Number(retryAfterSeconds) : NaN;
+  if (!Number.isFinite(n) || n <= 0) return SIGN_IN_FAILURE_COPY[code];
+  const minutes = Math.min(60, Math.max(1, Math.ceil(n / 60)));
+  const unit = minutes === 1 ? 'minute' : 'minutes';
+  return code === 'second_factor_rate_limited'
+    ? `Too many attempts. Try again in ${minutes} ${unit}.`
+    : `Too many sign-in attempts. Try again in ${minutes} ${unit}, or reset your password.`;
+}
+
+/** True only for a code this table defines. A hostile or new string from the wire is not one. */
+export function isSignInFailureCode(v: unknown): v is SignInFailureCode {
+  return typeof v === 'string' && Object.prototype.hasOwnProperty.call(SIGN_IN_FAILURE_COPY, v);
+}
+
+/** The sentence for a code, or null when the code is not in the table. */
+export function signInFailureMessage(code: unknown): string | null {
+  return isSignInFailureCode(code) ? SIGN_IN_FAILURE_COPY[code] : null;
+}
+
+/** BAPert 85432: an allowlisted policy refusal (SsoRequired / InvalidRequest) is the only server text a page may show: plain text only, at most this long. */
+export const POLICY_DETAIL_MAX = 200;
+
+/** The policy detail as shown: a string, trimmed, at most POLICY_DETAIL_MAX characters. Rendered as a React text node, never as HTML. */
+export function capPolicyDetail(v: unknown): string | null {
+  if (typeof v !== "string") return null;
+  const t = v.trim();
+  return t ? t.slice(0, POLICY_DETAIL_MAX) : null;
+}
+
+const norm = (c: unknown) => (typeof c === 'string' ? c.replace(/[^A-Za-z0-9]/g, '').toUpperCase() : '');
+const NOT_A_MEMBER = 'NOTAMEMBEROFTHISAPP';
+const LOCKED = new Set(['ACCOUNTLOCKED', 'USERLOCKEDOUT']);
+
+/** Server side: the code for a refusal, from the HTTP status (429 only) and the IdP's error code. Called only for refusals. */
+export function classifySignInFailure(status: number, idpCode: string | null | undefined): SignInFailureCode {
+  if (status === 429) return 'too_many_attempts';
+  const c = norm(idpCode);
+  if (LOCKED.has(c)) return 'too_many_attempts';
+  if (c === NOT_A_MEMBER) return 'not_a_member';
+  return 'invalid_credentials';
+}

package/src/lib/twofa-rejection.ts

@@ -31,6 +31,8 @@ export interface TwofaRejection {
   status: 400 | 429 | 502;
   error: string;
   retryAfter?: number;
+  /** True only for the plain IdP 429 (a lane rate limit), not for a `locked` lockout: the page words them differently. */
+  rateLimited?: true;
   /**
    * PAY-2284: true when the authenticator (or text) lane failed on OUR side and the emailed-code lane has not faulted. The sign-in
    * card then shows a real "Email me a code instead" action. Before this, the copy said "use another sign-in method" and the screen
@@ -62,8 +64,11 @@ export function classifyTwofaRejection(lanes: TwofaLaneResult[], retryAfterHeade
     const parsed = retryAfterHeader ? parseInt(retryAfterHeader, 10) : NaN;
     return {
       status: 429,
-      error: 'Too many attempts. Your code is still valid - wait before trying again.',
-      retryAfter: Number.isFinite(parsed) && parsed > 0 ? parsed : 60,
+      // Not shown to users (the handler sends the table sentence for the code); no claim about the code's validity, which is unproven.
+      error: 'Too many attempts. Wait a few minutes and try again.',
+      // BAPert 85813: no invented number. The page prints retryAfter as minutes, so it is sent only when the IdP sent a usable Retry-After.
+      ...(Number.isFinite(parsed) && parsed > 0 ? { retryAfter: parsed } : {}),
+      rateLimited: true,
     };
   }
   // PAY-1589: an IdP-side fault that arrives as 400 + code (TOTP secret cannot be decrypted -> server_error;

package/src/middleware/create-middleware.ts

@@ -17,6 +17,7 @@
  *   });
  */
 
+import { warnPrefetchGuardDeadOnce } from './prefetch-guard-status';
 import { NextRequest, NextResponse } from 'next/server';
 import { isUnauthenticatedRoute, should2FABypass } from '../auth/route-config';
 import { resolveCallbackDestination, safeCallbackPath } from '../auth/safe-callback';
@@ -31,6 +32,7 @@ import {
   normaliseResetParams,
   resetSecret,
   signedResetHref,
+  resetSigningSecret,
 } from '../auth/session-reset-link';
 import { errForLog } from '../lib/log-safe';
 
@@ -140,6 +142,14 @@ export interface MvpMiddlewareOptions {
    * an error is logged once. Default: off (the direct clear), because an unmounted route would 404 every sign-out.
    */
   sessionResetRoute?: boolean | string;
+  /**
+   * PAY-2218 (BAPert 83102, Scout option 1): OFF by default. When the EDGE middleware cannot see BETTER_AUTH_SECRET / NEXTAUTH_SECRET (the IdP-supplied secret is
+   * published into process.env only in the Node process), the hand-off cannot be signed and the direct clear is kept. Turn this ON to sign it with a key derived from the
+   * session cookie instead (the env secret still wins where it IS visible). It must be turned on in BOTH places or the route refuses the link: here, and on the route
+   * with `createSessionResetHandler({ cookieKey: true })`. Accepted residual risk of ON: an attacker who controls a sibling subdomain can plant a cookie value they
+   * know and sign a link that clears THAT value (a forced logout of that value only). Every app that can see the env secret should leave this OFF.
+   */
+  sessionResetCookieKey?: boolean;
   /**
    * PAY-1882 step 4 / PAY-2339 - how this app treats a producer that reports the session's
    * revocation status as `'unknown'` (a Vibe read that FAILED: non-OK, timeout,
@@ -271,6 +281,34 @@ export function isPrefetchRequest(request: NextRequest): boolean {
   return false;
 }
 
+/**
+ * PAY-2218 P2 (BAPert 86134, after NightHawk 86133 measured the sign-out on a real Next 15.5.9 server and a real Chromium).
+ * Next 15.x and 16.0-16.1 (and 16.2 without skipProxyUrlNormalize) strip the router-prefetch headers before middleware runs, so
+ * isPrefetchRequest() cannot see a router prefetch there. The browser's own fetch metadata is NOT stripped: a router prefetch is a
+ * fetch() (`Sec-Fetch-Mode: cors`, `Sec-Fetch-Dest: empty`), a real top-level navigation is `navigate` + `document`.
+ *
+ * THE TABLE (clearSessionCookies expires the cookies only when this returns false):
+ *   Sec-Fetch-Mode present and not 'navigate'  OR  Sec-Fetch-Dest present and not 'document'   -> true  (do NOT clear)
+ *   Sec-Fetch-Mode 'navigate' and/or Dest 'document', none different                           -> false (clear, as before)
+ *   NO Sec-Fetch-* at all, and rsc / next-router-prefetch / next-router-state-tree / sec-purpose|purpose: prefetch present -> true (never clear)
+ *   NO Sec-Fetch-* at all, none of those (curl, old clients, server-to-server)                  -> false (clear, as before)
+ * The redirect is still returned; the stale cookie is then cleared by the real navigation that follows.
+ * Fetch metadata is a forbidden header (page script cannot set it) and clearing is the safe direction, so a forged value can only delay a
+ * clear that the next navigation performs.
+ */
+export function isKnownNonNavigationRequest(request: NextRequest): boolean {
+  const h = request.headers;
+  const mode = h.get('sec-fetch-mode');
+  const dest = h.get('sec-fetch-dest');
+  if (mode !== null || dest !== null) {
+    if (mode !== null && mode.trim().toLowerCase() !== 'navigate') return true;
+    if (dest !== null && dest.trim().toLowerCase() !== 'document') return true;
+    return false;
+  }
+  if (isPrefetchRequest(request)) return true;
+  return h.has('rsc') || h.has('next-router-prefetch') || h.has('next-router-state-tree');
+}
+
 /**
  * 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
@@ -278,6 +316,7 @@ export function isPrefetchRequest(request: NextRequest): boolean {
  */
 function clearSessionCookies(response: NextResponse, request: NextRequest): void {
   if (isPrefetchRequest(request)) return;
+  if (isKnownNonNavigationRequest(request)) return;
   expireSessionCookies(response, Array.from(request.cookies, ([name]) => name));
 }
 
@@ -297,7 +336,12 @@ function redirectTo(
 /** PAY-2218: where a page's clearing redirect goes when the app has mounted the session-reset route. */
 interface ResetConfig {
   route: string;
-  secret: string;
+  /** The env secret when the edge can see it. */
+  envSecret?: string;
+  /** PAY-2218 opt-in: when true and there is no env secret, a key derived from the session cookie signs the hand-off (resetSigningSecret). */
+  cookieKey?: boolean;
+  /** Called once per request that could not be signed at all (no usable secret; with cookieKey also no session cookie). */
+  onCannotSign?: () => void;
 }
 
 /**
@@ -318,7 +362,12 @@ async function clearingRedirect(request: NextRequest, location: string, reset?:
   });
   // Bound to THIS request's session cookie: the route clears only when its own request carries the same one.
   const bound = boundSessionCookie((n) => request.cookies.get(n)?.value, getSessionCookieName(), getSecureSessionCookieName());
-  const response = NextResponse.redirect(new URL(await signedResetHref(reset.route, params, reset.secret, bound), request.url));
+  const secret = reset.cookieKey ? await resetSigningSecret(reset.envSecret, bound) : reset.envSecret;
+  if (!secret) {
+    reset.onCannotSign?.();
+    return redirectTo(request, location, true);
+  }
+  const response = NextResponse.redirect(new URL(await signedResetHref(reset.route, params, secret, bound), request.url));
   response.headers.set('cache-control', 'no-store');
   return response;
 }
@@ -611,6 +660,8 @@ export function createMvpMiddleware(options: MvpMiddlewareOptions = {}) {
   const revocationFailMode = options.revocationFailMode || 'hold';
   // PAY-2302 cut 1c: strictly `=== true`, so a truthy string in a config file cannot switch revocation off.
   const noRevocationSource = options.noRevocationSource === true;
+  // PAY-2218 P1: log once if this Next version cannot show middleware a router prefetch. Log-only.
+  warnPrefetchGuardDeadOnce((m) => log.warn(m));
   if (noRevocationSource) {
     log.warn(
       '[next-mvp] noRevocationSource is ON: sessions of this app CANNOT be revoked server-side (no vibe client / HMAC key). ' +
@@ -625,13 +676,22 @@ export function createMvpMiddleware(options: MvpMiddlewareOptions = {}) {
   let resetSecretMissingLogged = false;
   const resolveReset = (): ResetConfig | undefined => {
     if (!sessionResetRoute) return undefined;
-    const secret = resetSecret();
-    if (secret) return { route: sessionResetRoute, secret };
-    if (!resetSecretMissingLogged) {
-      resetSecretMissingLogged = true;
-      log.error('sessionResetRoute is set but no BETTER_AUTH_SECRET/NEXTAUTH_SECRET is available to sign the hand-off; clearing in middleware instead', { sessionResetRoute });
-    }
-    return undefined;
+    return {
+      route: sessionResetRoute,
+      envSecret: resetSecret(),
+      cookieKey: options.sessionResetCookieKey === true,
+      onCannotSign: () => {
+        if (resetSecretMissingLogged) return;
+        resetSecretMissingLogged = true;
+        // No values here: only the route name.
+        log.error(
+          options.sessionResetCookieKey === true
+            ? 'sessionResetRoute is set but there is neither a BETTER_AUTH_SECRET/NEXTAUTH_SECRET visible to the middleware nor a session cookie to derive a signing key from; clearing in middleware instead'
+            : 'sessionResetRoute is set but no BETTER_AUTH_SECRET/NEXTAUTH_SECRET is available to sign the hand-off; clearing in middleware instead (set sessionResetCookieKey, and createSessionResetHandler({ cookieKey: true }) on the route, if the edge cannot see the env secret)',
+          { sessionResetRoute }
+        );
+      },
+    };
   };
 
   return async function middleware(request: NextRequest): Promise<NextResponse> {

package/src/middleware/prefetch-guard-status.ts

@@ -0,0 +1,56 @@
+/**
+ * PAY-2218 P1 (BAPert 86123, reworded 86209): say, once, at middleware creation, that the HEADER-based router-prefetch guard cannot see router prefetches
+ * on this Next version. After P2 the session-cookie clear no longer depends on it (it keys on Sec-Fetch-Mode/Dest), so this is information, not a call to
+ * migrate. No behaviour change: this only logs.
+ *
+ * MEASURED (adapter.js read in each version's own node_modules): Next 15.5.9 and 16.1.5 delete the flight headers (rsc, next-router-prefetch, ...)
+ * from the request middleware sees UNCONDITIONALLY, and 15.5.9 also strips `_rsc` from the URL, so isPrefetchRequest() is false for every router
+ * prefetch and no config can change that. Next 16.2.x skips the strip when `skipProxyUrlNormalize: true`.
+ *
+ * NOT warned, on purpose: Next >= 16.2 (the flag is a build-time define that user middleware code cannot reliably read back, so a warning there
+ * would be a guess) and Next 14 (not measured). Unparseable or missing version: silent.
+ */
+export type PrefetchGuardStatus = { dead: boolean; reason: string };
+
+export function prefetchGuardStatus(nextVersion: string | undefined | null): PrefetchGuardStatus {
+  const m = /^(\d+)\.(\d+)\./.exec(String(nextVersion ?? '').trim());
+  if (!m) return { dead: false, reason: 'unknown version' };
+  const major = Number(m[1]);
+  const minor = Number(m[2]);
+  if (major === 15 || (major === 16 && minor < 2)) {
+    return { dead: true, reason: 'strips the router-prefetch headers (rsc, next-router-prefetch) before middleware runs and has no opt-out' };
+  }
+  return { dead: false, reason: 'not measured as dead' };
+}
+
+function detectNextVersion(): string | undefined {
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    return (require('next/package.json') as { version?: string }).version;
+  } catch {
+    return undefined;
+  }
+}
+
+let warned = false;
+
+/** Logs PAYEZ_PREFETCH_GUARD_DEAD once per process when the guard is dead on this Next version. Returns true when it logged. */
+export function warnPrefetchGuardDeadOnce(
+  warn: (message: string, data?: unknown) => void,
+  nextVersion: string | undefined | null = detectNextVersion(),
+): boolean {
+  if (warned) return false;
+  const s = prefetchGuardStatus(nextVersion);
+  if (!s.dead) return false;
+  warned = true;
+  warn(
+    `PAYEZ_PREFETCH_GUARD_DEAD next=${nextVersion}: this Next version ${s.reason}, so isPrefetchRequest() cannot see a router prefetch. ` +
+      "The session-cookie clear relies on the browser's Sec-Fetch-Mode/Dest instead (PAY-2218 P2); non-browser clients and browsers that send no Sec-Fetch headers are not covered.",
+  );
+  return true;
+}
+
+/** Test seam: forget that the warning was logged. */
+export function resetPrefetchGuardWarningForTests(): void {
+  warned = false;
+}