@payez/next-mvp 4.5.5 → 4.5.7

package/dist/server/auth.d.ts

@@ -78,8 +78,46 @@ export declare function getAuthInstance(): Promise<any>;
  *   getFreshIdpToken              → NO_SESSION (Better Auth cache miss)
  *
  * Returns the session object or null if not authenticated per Redis.
+ *
+ * PAY-2216: this is now a thin wrapper over {@link resolveSessionState} and returns the session ONLY for `live`.
+ * Its signature and every answer it gives are unchanged; callers that must tell a dead session from an
+ * unreachable store call resolveSessionState directly.
  */
 export declare function getSession(request?: Request): Promise<any>;
+/**
+ * PAY-2216: what the session store said about this request's cookie. `getSession()` collapses all three
+ * non-live answers to `null`, and that collapse is the defect this type exists to undo.
+ *
+ * MEASURED (PAY-2216, NextPert 2026-10-11, portal fe547fa4 / next-mvp 4.5.4 / ioredis 5.3.2, real server):
+ * a Redis OUTAGE and a really DELETED key both came out of getSession() as `null`, so viability answered the
+ * identical `200 No session found` for both. Clearing on that shape would log every live user out on an
+ * outage (the PAY-2147 class), so nothing cleared at all and a dead cookie lingered.
+ *
+ *   live    - the session resolved. `session` is exactly what getSession() returns.
+ *   missing - a cookie whose signature VERIFIED (HMAC or JWS, resolveVerifiedSessionTokenFromRequest) and BOTH
+ *             store reads (canonical `{slug}:sess:{t}` and Better Auth's `ba:{slug}:{t}`) COMPLETED and found
+ *             nothing. The store answered; the session is gone. Clearing the cookie is correct. This includes
+ *             a Redis that restarted EMPTY: those sessions really are gone (BAPert 72093, gate row 6).
+ *   unknown - a store read THREW (connection refused, commandTimeout, max retries). The store did not answer,
+ *             so nothing is known about the session. NEVER clear on this. Callers answer 5xx.
+ *   none    - no session cookie, or a cookie whose signature does not verify, with the store not failing.
+ *             Nothing to clear on our authority: a forged cookie never yields `missing`.
+ *
+ * The rule the whole type exists for: `missing` REQUIRES a verified cookie AND reads that completed. Weaken
+ * either and an outage or a forged cookie becomes a clear.
+ */
+export type SessionState = {
+    state: 'live';
+    session: any;
+} | {
+    state: 'missing';
+    sessionToken: string;
+} | {
+    state: 'unknown';
+} | {
+    state: 'none';
+};
+export declare function resolveSessionState(request?: Request): Promise<SessionState>;
 /**
  * Get normalized session data for the current request.
  *

package/dist/server/auth.js

@@ -41,6 +41,7 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getAuthInstance = getAuthInstance;
 exports.getSession = getSession;
+exports.resolveSessionState = resolveSessionState;
 exports.getSessionData = getSessionData;
 exports.getIdpToken = getIdpToken;
 exports.getFreshIdpToken = getFreshIdpToken;
@@ -230,18 +231,32 @@ function logNoSessionWithKeys(origin, sessionToken) {
  *   getFreshIdpToken              → NO_SESSION (Better Auth cache miss)
  *
  * Returns the session object or null if not authenticated per Redis.
+ *
+ * PAY-2216: this is now a thin wrapper over {@link resolveSessionState} and returns the session ONLY for `live`.
+ * Its signature and every answer it gives are unchanged; callers that must tell a dead session from an
+ * unreachable store call resolveSessionState directly.
  */
 async function getSession(request) {
+    const state = await resolveSessionState(request);
+    return state.state === 'live' ? state.session : null;
+}
+async function resolveSessionState(request) {
     const auth = await getAuthInstance();
     if (!request)
-        return null;
+        return { state: 'none' };
     // Path A — Better Auth primary path (cookie cache → secondary storage).
     // Fast happy-path when both Better Auth and Redis agree.
+    //
+    // PAY-2216: secondaryStorage.get RETHROWS a Redis failure on purpose (170033), so a throw here means "the store
+    // could not be asked". It is remembered: if Path B then has no verified token to read with, the honest answer is
+    // `unknown`, not `none`.
     let betterAuthSession = null;
+    let primaryThrew = false;
     try {
         betterAuthSession = await auth.api.getSession({ headers: request.headers });
     }
     catch (err) {
+        primaryThrew = true;
         logSessionReadSwallowed('primary', err); // fall through to canonical Redis path
     }
     if (betterAuthSession?.session?.token && betterAuthSession?.user) {
@@ -257,7 +272,7 @@ async function getSession(request) {
         }
         if (!sessionData)
             sessionData = buildSessionDataFromAuthSession(betterAuthSession);
-        return attachSessionData(betterAuthSession, sessionData, sessionToken);
+        return { state: 'live', session: attachSessionData(betterAuthSession, sessionData, sessionToken) };
     }
     // Path B — Better Auth said null/incomplete. Fall back to a VERIFIED cookie
     // decode + Redis-canonical liveness check. This catches cases where the
@@ -271,8 +286,12 @@ async function getSession(request) {
     // the signature position, and a forged JWS too. The token now comes only from
     // the shared verified resolver (HMAC or JWS signature checked first).
     const sessionToken = await (0, verified_session_token_1.resolveVerifiedSessionTokenFromRequest)(request);
+    // No verified token. If Better Auth's read THREW, the store was failing, so we cannot say the cookie is
+    // unverifiable rather than unreadable: `unknown`. Otherwise there is nothing to act on: `none`.
     if (!sessionToken)
-        return null;
+        return primaryThrew ? { state: 'unknown' } : { state: 'none' };
+    // PAY-2216: both reads must COMPLETE for a miss to mean anything. Either one throwing is `unknown`, which
+    // nobody may clear on. These two functions do a bare redis.get and do not swallow (verified at 4.5.4).
     let sessionData = null;
     try {
         sessionData = await (0, session_store_1.getSession)(sessionToken);
@@ -281,9 +300,10 @@ async function getSession(request) {
     }
     catch (err) {
         logSessionReadSwallowed('B', err); // Redis unavailable
+        return { state: 'unknown' };
     }
     if (!sessionData)
-        return null;
+        return { state: 'missing', sessionToken };
     // Synthesize a minimal session shape compatible with downstream callers.
     // The `session.token` field is what `getFreshIdpToken` and other callers
     // read to drive `ensureFreshAccessToken` + Redis lookups, so it MUST be
@@ -296,7 +316,7 @@ async function getSession(request) {
             roles: sessionData.roles,
         },
     };
-    return attachSessionData(synthetic, sessionData, sessionToken);
+    return { state: 'live', session: attachSessionData(synthetic, sessionData, sessionToken) };
 }
 /**
  * Get normalized session data for the current request.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@payez/next-mvp",
-  "version": "4.5.5",
+  "version": "4.5.7",
   "sideEffects": false,
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -700,6 +700,11 @@
       "require": "./dist/routes/auth/logout.js",
       "default": "./dist/routes/auth/logout.js"
     },
+    "./routes/auth/session-reset": {
+      "types": "./dist/routes/auth/session-reset.d.ts",
+      "require": "./dist/routes/auth/session-reset.js",
+      "default": "./dist/routes/auth/session-reset.js"
+    },
     "./routes/auth/viability": {
       "types": "./dist/routes/auth/viability.d.ts",
       "require": "./dist/routes/auth/viability.js",

package/src/api-handlers/session/refresh-viability.ts

@@ -4,12 +4,29 @@ import { checkRefreshViability } from '../../lib/refresh-token-validator';
 import { getTokenTestAware } from '../../lib/test-aware-get-token';
 import { logger } from '../../config/logger';
 import { tokenLogId } from '../../lib/token-log-id';
+import { resolveSessionState } from '../../server/auth';
 
 export async function GET(req: NextRequest) {
   try {
     const sessionToken = req.nextUrl.searchParams.get('token');
     let finalSessionToken = sessionToken;
-    if (!finalSessionToken) {
+    if (!finalSessionToken && process.env.TEST_MODE !== 'true') {
+      // PAY-2216: outside TEST_MODE getTokenTestAware is getSession(), which answered null for a store outage AND
+      // for a deleted session, so this route said not_logged_in to both and its own session_not_found arm (below)
+      // was unreachable from a cookie. Ask for the state instead. Same rules as routes/auth/viability.ts:
+      // 'unknown' never reads as logged out or stale; 'missing' requires a verified cookie.
+      const sessionState = await resolveSessionState(req);
+      if (sessionState.state === 'unknown') {
+        logger.warn('[REFRESH-VIABILITY] Session store unavailable - session state unknown');
+        return NextResponse.json({ canRefresh: false, reason: 'store_unavailable', error: 'Session store unavailable', code: 'STORE_UNAVAILABLE' }, { status: 500 });
+      }
+      if (sessionState.state === 'missing') {
+        return NextResponse.json({ canRefresh: false, reason: 'session_not_found', sessionTokenId: tokenLogId(sessionState.sessionToken) }, { status: 200 });
+      }
+      if (sessionState.state === 'live') {
+        finalSessionToken = sessionState.session?.session?.token ?? null;
+      }
+    } else if (!finalSessionToken) {
       const token = await getTokenTestAware(req);
       // Support both field names: sessionToken (auth.ts JWT) and redisSessionId (legacy)
       finalSessionToken = (token?.sessionToken || token?.redisSessionId) as string;

package/src/api-handlers/session/viability.ts

@@ -6,7 +6,7 @@
 
 import { NextRequest, NextResponse } from 'next/server';
 import { getSession as getRedisSession, getBetterAuthSession } from '../../lib/session-store';
-import { getSession } from '../../server/auth';
+import { resolveSessionState } from '../../server/auth';
 import { isInitializationFailed, ensureInitialized } from '../../lib/startup-init';
 import { getIDPClientConfig } from '../../lib/idp-client-config';
 import { tokenLogId } from '../../lib/token-log-id';
@@ -45,8 +45,25 @@ export async function GET(req: NextRequest) {
       );
     }
 
-    // Get session from Better Auth
-    const betterAuthSession = await getSession(req);
+    // PAY-2216: the TWIN of routes/auth/viability.ts - same tri-state, same answers, or an app mounting this export
+    // keeps the defect. 'unknown' (store did not answer) is a 5xx and never stale; 'missing' (verified cookie, store
+    // answered "not here") is the stale shape with a token id; 'none' stays { authenticated: false }.
+    const sessionState = await resolveSessionState(req);
+    if (sessionState.state === 'unknown') {
+      console.warn('[VIABILITY] Session store unavailable - session state unknown');
+      return NextResponse.json(
+        { authenticated: false, revocationStatus: 'unknown' as RevocationStatus, error: 'Session store unavailable', code: 'STORE_UNAVAILABLE' },
+        { status: 500 }
+      );
+    }
+    if (sessionState.state === 'missing') {
+      console.warn('[VIABILITY] Stale cookie detected - verified cookie, session not in Redis');
+      return NextResponse.json({
+        authenticated: false,
+        sessionTokenId: tokenLogId(sessionState.sessionToken) // PAY-1481: correlation id, never the token
+      });
+    }
+    const betterAuthSession = sessionState.state === 'live' ? sessionState.session : null;
 
     // Debug logging
     if (!betterAuthSession) {

package/src/auth/safe-callback.ts

@@ -95,6 +95,11 @@ export function safeCallbackPath(raw: unknown, fallback: string = DEFAULT_CALLBA
   // Loopbacks into the auth surface cause redirect cycles.
   if (url.pathname.startsWith(AUTH_PREFIX)) return fallback;
 
+  // PAY-2218: `_rsc` is Next's flight cache-buster. Once skipProxyUrlNormalize lets it reach middleware it leaks
+  // into return targets (`callbackUrl=/overview?_rsc=abc12`, NightHawk 72013); it is never a meaningful part of a
+  // destination. Only touched when present, so every other query keeps its exact spelling.
+  if (url.searchParams.has('_rsc')) url.searchParams.delete('_rsc');
+
   // The parser's normalised output - control characters already stripped.
   const candidate = url.pathname + url.search + url.hash;
 

package/src/auth/session-cookie-clear.ts

@@ -0,0 +1,30 @@
+/**
+ * The ONE body that writes the session-cookie expiry Set-Cookie headers. Shared by the middleware
+ * (create-middleware.ts clearSessionCookies, behind its prefetch guard) and the PAY-2218 session-reset route, so
+ * the two clearing sites cannot drift apart on which cookies they expire or with which attributes.
+ */
+import type { NextResponse } from 'next/server';
+import { getSessionCookieName, getSecureSessionCookieName } from '../lib/app-slug';
+
+export function expireSessionCookies(response: NextResponse, requestCookieNames: Iterable<string>): void {
+  const sessionCookie = getSessionCookieName();
+  const secureCookie = getSecureSessionCookieName();
+
+  // Clear main cookies
+  response.cookies.set(sessionCookie, '', { path: '/', expires: new Date(0), httpOnly: true, sameSite: 'lax' });
+  response.cookies.set(secureCookie, '', { path: '/', expires: new Date(0), httpOnly: true, sameSite: 'lax', secure: true });
+
+  // Clear any chunked cookies (NextAuth chunks large cookies)
+  for (const name of requestCookieNames) {
+    if (name.startsWith(`${sessionCookie}.`) || name.startsWith(`${secureCookie}.`)) {
+      const isSecure = name.startsWith('__Secure-');
+      response.cookies.set(name, '', {
+        path: '/',
+        expires: new Date(0),
+        httpOnly: true,
+        sameSite: 'lax',
+        ...(isSecure && { secure: true })
+      });
+    }
+  }
+}

package/src/auth/session-reset-link.ts

@@ -0,0 +1,159 @@
+/**
+ * PAY-2218 PR 2: the hand-off between the middleware and the session-reset route.
+ *
+ * WHY A ROUTE AT ALL. Next 15.5.x and 16.x (16.2.x without `skipProxyUrlNormalize`) strip every router flight
+ * header (`rsc`, `next-router-prefetch`, `next-router-segment-prefetch`, `next-router-state-tree`) from the request
+ * handed to middleware, so middleware cannot tell a router prefetch from a real navigation and its prefetch guard is
+ * dead. A ROUTE HANDLER does see them, on 15.5.9, 16.1.5 and 16.2.12 (measured with a real Chromium against real
+ * `next start` servers, PAY-2218 comments 2026-10-11). So the middleware no longer writes the clearing Set-Cookie
+ * itself: it redirects to the reset route, and the route decides.
+ *
+ * WHY THE ROUTE ANSWERS A PREFETCH WITH 204, NOT A REDIRECT. On 15.5.9 the router CACHES a prefetched redirect chain
+ * and the later click reuses it without calling middleware or the route again - so "decline on the prefetch, clear
+ * on the real navigation" never clears there. A 204 + no-store gives the router nothing to cache, so the real click
+ * reaches the route and clears (measured 2/2 on 15.5.9 and 16.2.12; the 307 mutant never clears on 15.5.9).
+ *
+ * WHY SIGNED. The route clears cookies on a GET. Unsigned, any page could link a signed-in user to it and log them
+ * out. The middleware signs (callbackUrl, reason, error, exp, session binding); the route clears only on a valid,
+ * unexpired signature and otherwise just sends the user to the login page with the cookies untouched.
+ *
+ * KEY SEPARATION (BAPert 72219). The signing key is DERIVED - HMAC(authSecret, 'next-mvp/session-reset/v1') - never
+ * the raw auth secret, so no value the app signs with that secret for any other purpose can pass as a reset token.
+ *
+ * SESSION BINDING (BAPert 72219). The signature covers SHA-256 of the session cookie the redirect was issued FOR. The
+ * route recomputes it from ITS OWN request's cookie and clears only on a match, so a token captured from one user
+ * clears nothing when sent to another (logout-CSRF), and a second use is a no-op (the first use cleared the cookie it
+ * was bound to). The hash never travels in the URL; it is only an input to the signature.
+ *
+ * WHY THE ROUTE REBUILDS THE LOGIN URL. The route never redirects to a URL it was handed. It takes `callbackUrl`
+ * (through safeCallbackPath), `reason` and `error` (allowlisted) and builds `${LOGIN_PAGE}?...` itself, so it cannot
+ * become an open redirect whatever the query says.
+ *
+ * Edge-safe: Web Crypto only (middleware runs on the edge runtime on 15.5.x).
+ */
+import { safeCallbackPath } from './safe-callback';
+
+export const LOGIN_PAGE = '/account-auth/login';
+
+/** The mount point consumers use: `app/api/auth/session-reset/route.ts` (under /api/auth/, which middleware bypasses). */
+export const DEFAULT_SESSION_RESET_ROUTE = '/api/auth/session-reset';
+
+/** How long a signed reset link stays valid. A real navigation follows the 307 at once; this only bounds replay. */
+export const RESET_LINK_TTL_SECONDS = 300;
+
+/** The purpose label for the derived signing key. Changing it invalidates every outstanding reset link. */
+export const RESET_KEY_PURPOSE = 'next-mvp/session-reset/v1';
+
+/** The only `reason` / `error` values the middleware emits on a clearing redirect. Anything else is dropped. */
+export const RESET_REASONS: readonly string[] = ['stale', 'invalidated'];
+export const RESET_ERRORS: readonly string[] = ['SessionExpired', 'TwoFactorTimeout'];
+
+export interface ResetParams {
+  callbackUrl: string;
+  reason?: string;
+  error?: string;
+}
+
+const encoder = new TextEncoder();
+const FIELD_SEPARATOR = String.fromCharCode(10);
+
+function b64url(bytes: Uint8Array): string {
+  return btoa(String.fromCharCode(...bytes)).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+
+async function hmacBytes(key: Uint8Array, message: string): Promise<Uint8Array> {
+  const k = await crypto.subtle.importKey('raw', key as BufferSource, { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
+  return new Uint8Array(await crypto.subtle.sign('HMAC', k, encoder.encode(message)));
+}
+
+/** Sign with the DERIVED key: HMAC(HMAC(authSecret, purpose), message). Never with the raw auth secret. */
+async function sign(secret: string, message: string): Promise<string> {
+  const derived = await hmacBytes(encoder.encode(secret), RESET_KEY_PURPOSE);
+  return b64url(await hmacBytes(derived, message));
+}
+
+/** SHA-256 of the session cookie value, b64url. No session cookie binds to the empty string. */
+async function sessionBinding(sessionCookieValue: string | undefined): Promise<string> {
+  if (!sessionCookieValue) return '';
+  return b64url(new Uint8Array(await crypto.subtle.digest('SHA-256', encoder.encode(sessionCookieValue))));
+}
+
+/** Constant-time over equal lengths, and unequal lengths never match. */
+function sameString(a: string, b: string): boolean {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  return diff === 0;
+}
+
+/** The secret the app already signs its session cookie with. Undefined means "cannot sign": callers fall back. */
+export function resetSecret(): string | undefined {
+  return process.env.BETTER_AUTH_SECRET || process.env.NEXTAUTH_SECRET || undefined;
+}
+
+/** The session cookie a reset is bound to: the __Secure- one when present, else the plain one. */
+export function boundSessionCookie(get: (name: string) => string | undefined, plainName: string, secureName: string): string | undefined {
+  return get(secureName) || get(plainName) || undefined;
+}
+
+/** Normalise to exactly what the route will honour, so what is signed is what is verified. */
+export function normaliseResetParams(raw: { callbackUrl?: string | null; reason?: string | null; error?: string | null }): ResetParams {
+  const out: ResetParams = { callbackUrl: safeCallbackPath(raw.callbackUrl ?? '') };
+  if (raw.reason && RESET_REASONS.includes(raw.reason)) out.reason = raw.reason;
+  if (raw.error && RESET_ERRORS.includes(raw.error)) out.error = raw.error;
+  return out;
+}
+
+/** What the signature covers. Exported for the key-separation row, which signs it with the RAW secret. */
+export function resetPayload(p: ResetParams, exp: number, binding: string): string {
+  return ['v2', p.callbackUrl, p.reason ?? '', p.error ?? '', String(exp), binding].join(FIELD_SEPARATOR);
+}
+
+/** The login URL for these params, in the exact shape the middleware has always emitted. */
+export function loginLocation(p: ResetParams): string {
+  let loc = `${LOGIN_PAGE}?callbackUrl=${encodeURIComponent(p.callbackUrl)}`;
+  if (p.reason) loc += `&reason=${p.reason}`;
+  if (p.error) loc += `&error=${p.error}`;
+  return loc;
+}
+
+/**
+ * Path + query for the reset route, bound to `sessionCookieValue` (the session cookie on the request being ended).
+ * `nowMs` is injectable for tests.
+ */
+export async function signedResetHref(
+  route: string,
+  p: ResetParams,
+  secret: string,
+  sessionCookieValue: string | undefined,
+  nowMs: number = Date.now()
+): Promise<string> {
+  const exp = Math.floor(nowMs / 1000) + RESET_LINK_TTL_SECONDS;
+  const q = new URLSearchParams({ callbackUrl: p.callbackUrl });
+  if (p.reason) q.set('reason', p.reason);
+  if (p.error) q.set('error', p.error);
+  q.set('exp', String(exp));
+  q.set('sig', await sign(secret, resetPayload(p, exp, await sessionBinding(sessionCookieValue))));
+  return `${route}?${q.toString()}`;
+}
+
+/**
+ * Read a reset request's query. `signed` is true only for a valid, unexpired signature over the normalised params AND
+ * this request's own session cookie (`sessionCookieValue`). With no session cookie there is nothing to clear: false.
+ * The params are returned either way: an unsigned request still gets a sensible login redirect, just no clearing.
+ */
+export async function readResetRequest(
+  search: URLSearchParams,
+  secret: string | undefined,
+  sessionCookieValue: string | undefined,
+  nowMs: number = Date.now()
+): Promise<{ params: ResetParams; signed: boolean }> {
+  const params = normaliseResetParams({ callbackUrl: search.get('callbackUrl'), reason: search.get('reason'), error: search.get('error') });
+  const sig = search.get('sig');
+  const exp = Number(search.get('exp'));
+  if (!secret || !sig || !sessionCookieValue || !Number.isInteger(exp) || exp < Math.floor(nowMs / 1000)) return { params, signed: false };
+  // The signature covers the NORMALISED params and THIS request's session, so a tampered value, or the token arriving
+  // with a different session cookie (another user, or the same user after signing in again), fails here.
+  const want = await sign(secret, resetPayload(params, exp, await sessionBinding(sessionCookieValue)));
+  return { params, signed: sameString(sig, want) };
+}

package/src/middleware/create-middleware.ts

@@ -24,6 +24,14 @@ 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';
+import { expireSessionCookies } from '../auth/session-cookie-clear';
+import {
+  DEFAULT_SESSION_RESET_ROUTE,
+  boundSessionCookie,
+  normaliseResetParams,
+  resetSecret,
+  signedResetHref,
+} from '../auth/session-reset-link';
 
 // =============================================================================
 // TYPES
@@ -113,6 +121,19 @@ export interface MvpMiddlewareOptions {
   bypassPaths?: string[];
   /** Paths exempt from RBAC checks (auth still enforced, just no page-permission check) */
   rbacExemptPaths?: string[];
+  /**
+   * PAY-2218 - send a page's session-ending redirect through the session-reset ROUTE instead of clearing the
+   * cookies in the middleware response. Next strips the router's prefetch headers before middleware runs
+   * (15.5.x and 16.x; 16.2.x restores them only with `skipProxyUrlNormalize: true`), so a middleware clear also
+   * fires on a router PREFETCH and signs the user out of a page they never opened. The route sees those headers.
+   *
+   * Requires the app to mount the route:  app/api/auth/session-reset/route.ts
+   *     export { GET } from '@payez/next-mvp/routes/auth/session-reset';
+   * `true` uses that default path; a string names another mount point under /api/auth/ (middleware bypasses it).
+   * Needs BETTER_AUTH_SECRET (or NEXTAUTH_SECRET) to sign the hand-off; without one the direct clear is kept and
+   * an error is logged once. Default: off (the direct clear), because an unmounted route would 404 every sign-out.
+   */
+  sessionResetRoute?: boolean | string;
   /**
    * PAY-1882 step 4 - how this app treats a producer that reports the session's
    * revocation status as `'unknown'` (a Vibe read that FAILED: non-OK, timeout,
@@ -221,26 +242,7 @@ export function isPrefetchRequest(request: NextRequest): boolean {
  */
 function clearSessionCookies(response: NextResponse, request: NextRequest): void {
   if (isPrefetchRequest(request)) return;
-  const sessionCookie = getSessionCookieName();
-  const secureCookie = getSecureSessionCookieName();
-
-  // Clear main cookies
-  response.cookies.set(sessionCookie, '', { path: '/', expires: new Date(0), httpOnly: true, sameSite: 'lax' });
-  response.cookies.set(secureCookie, '', { path: '/', expires: new Date(0), httpOnly: true, sameSite: 'lax', secure: true });
-
-  // Clear any chunked cookies (NextAuth chunks large cookies)
-  for (const [name] of request.cookies) {
-    if (name.startsWith(`${sessionCookie}.`) || name.startsWith(`${secureCookie}.`)) {
-      const isSecure = name.startsWith('__Secure-');
-      response.cookies.set(name, '', {
-        path: '/',
-        expires: new Date(0),
-        httpOnly: true,
-        sameSite: 'lax',
-        ...(isSecure && { secure: true })
-      });
-    }
-  }
+  expireSessionCookies(response, Array.from(request.cookies, ([name]) => name));
 }
 
 /** Create redirect response, optionally clearing cookies */
@@ -256,6 +258,35 @@ function redirectTo(
   return response;
 }
 
+/** PAY-2218: where a page's clearing redirect goes when the app has mounted the session-reset route. */
+interface ResetConfig {
+  route: string;
+  secret: string;
+}
+
+/**
+ * A redirect that must also END the session. With the reset route configured, a page request is sent through it
+ * WITHOUT any Set-Cookie here: the route sees the flight headers this middleware cannot (Next strips them before
+ * middleware), answers a prefetch 204 + no-store, and clears on the real navigation. `/api/` requests and apps
+ * without the route keep the direct clear exactly as before.
+ */
+async function clearingRedirect(request: NextRequest, location: string, reset?: ResetConfig): Promise<NextResponse> {
+  if (!reset || request.nextUrl.pathname.startsWith('/api/')) {
+    return redirectTo(request, location, true);
+  }
+  const target = new URL(location, request.url);
+  const params = normaliseResetParams({
+    callbackUrl: target.searchParams.get('callbackUrl'),
+    reason: target.searchParams.get('reason'),
+    error: target.searchParams.get('error'),
+  });
+  // 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));
+  response.headers.set('cache-control', 'no-store');
+  return response;
+}
+
 /**
  * Terminal response for a FAILED token refresh.
  *
@@ -274,12 +305,13 @@ function redirectTo(
  * higher would intercept 'refresh_needed' and disable middleware token refresh across
  * the whole API surface (card 340024 C1).
  */
-function refreshFailureResponse(
+async function refreshFailureResponse(
   request: NextRequest,
   location: string,
   errorCode: string,
-  clearCookies = false
-): NextResponse {
+  clearCookies = false,
+  reset?: ResetConfig
+): Promise<NextResponse> {
   if (request.nextUrl.pathname.startsWith('/api/')) {
     const response = NextResponse.json({ error: errorCode }, { status: 401 });
     if (clearCookies) {
@@ -287,7 +319,7 @@ function refreshFailureResponse(
     }
     return response;
   }
-  return redirectTo(request, location, clearCookies);
+  return clearCookies ? clearingRedirect(request, location, reset) : redirectTo(request, location);
 }
 
 /**
@@ -497,6 +529,9 @@ function redirect2FA(callbackUrl: string): AuthAction {
 // MIDDLEWARE FACTORY
 // =============================================================================
 
+/** PAY-2218: the stripped-flight-headers warning is logged once per process, not once per request. */
+let flightHeadersStrippedWarned = false;
+
 export function createMvpMiddleware(options: MvpMiddlewareOptions = {}) {
   // Resolve options with defaults
   const cb = options.circuitBreaker || defaultCircuitBreaker;
@@ -507,6 +542,21 @@ export function createMvpMiddleware(options: MvpMiddlewareOptions = {}) {
   const rbacExemptPaths = options.rbacExemptPaths || [];
   // PAY-1882 step 4: default 'closed' (Jon's option A / BAPert 66316).
   const revocationFailMode = options.revocationFailMode || 'closed';
+  const sessionResetRoute =
+    options.sessionResetRoute === true ? DEFAULT_SESSION_RESET_ROUTE
+    : typeof options.sessionResetRoute === 'string' && options.sessionResetRoute ? options.sessionResetRoute
+    : undefined;
+  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 async function middleware(request: NextRequest): Promise<NextResponse> {
     const { pathname, searchParams } = request.nextUrl;
@@ -529,6 +579,13 @@ export function createMvpMiddleware(options: MvpMiddlewareOptions = {}) {
       }
     }
 
+    // PAY-2218: a router request (it carries `next-url`) that arrives WITHOUT `rsc` had its flight headers stripped
+    // by Next before middleware ran, so isPrefetchRequest() cannot see a router prefetch on this app. Say so once.
+    if (!sessionResetRoute && !flightHeadersStrippedWarned && request.headers.has('next-url') && !request.headers.has('rsc')) {
+      flightHeadersStrippedWarned = true;
+      log.warn('Next strips router prefetch headers before middleware on this app, so a session-ending redirect can fire on a prefetch. Mount @payez/next-mvp/routes/auth/session-reset and set sessionResetRoute (PAY-2218).', { pathname });
+    }
+
     const isPublic = isUnauthenticatedRoute(pathname);
     const isLogin = isLoginPage(pathname);
 
@@ -608,6 +665,7 @@ export function createMvpMiddleware(options: MvpMiddlewareOptions = {}) {
       logger: log,
       refreshEndpoint,
       rbacExemptPaths,
+      reset: resolveReset(),
       onRefreshSuccess: options.onRefreshSuccess,
       onRefreshFailure: options.onRefreshFailure,
     });
@@ -778,6 +836,8 @@ interface ExecuteOptions {
   logger: MiddlewareLogger;
   refreshEndpoint: string;
   rbacExemptPaths: string[];
+  /** PAY-2218: set when the app mounted the session-reset route AND a signing secret exists. */
+  reset?: ResetConfig;
   onRefreshSuccess?: () => void;
   onRefreshFailure?: (status: number, isNetworkError: boolean) => void;
 }
@@ -798,7 +858,9 @@ async function executeDecision(
       return handleAllow(request, pathname, sessionPointer, sessionStatus, opts.rbacExemptPaths);
 
     case 'redirect':
-      return redirectTo(request, decision.location, decision.clearCookies);
+      return decision.clearCookies
+        ? clearingRedirect(request, decision.location, opts.reset)
+        : redirectTo(request, decision.location);
 
     case 'service_error':
       return serviceUnavailableResponse(request);
@@ -943,7 +1005,8 @@ async function handleRefresh(
       request,
       `${LOGIN_PAGE}?callbackUrl=${encodeURIComponent(safeCallback)}&error=${errorParam}`,
       errorParam,
-      isPermanentFailure
+      isPermanentFailure,
+      opts.reset
     );
   } catch (error: any) {
     const isNetwork = cb.isNetworkError(error);