@payez/next-mvp 4.5.5 → 4.5.7

package/dist/api-handlers/session/refresh-viability.d.ts

@@ -2,7 +2,8 @@ import { NextRequest, NextResponse } from 'next/server';
 export declare function GET(req: NextRequest): Promise<NextResponse<{
     canRefresh: boolean;
     reason: string;
-    sessionTokenId: null;
+    error: string;
+    code: string;
 }> | NextResponse<{
     canRefresh: boolean;
     reason: string;
@@ -10,7 +11,5 @@ export declare function GET(req: NextRequest): Promise<NextResponse<{
 }> | NextResponse<{
     canRefresh: boolean;
     reason: string;
-    error: string;
-    code: string;
-    correlationId: string;
+    sessionTokenId: null;
 }>>;

package/dist/api-handlers/session/refresh-viability.js

@@ -7,11 +7,29 @@ const refresh_token_validator_1 = require("../../lib/refresh-token-validator");
 const test_aware_get_token_1 = require("../../lib/test-aware-get-token");
 const logger_1 = require("../../config/logger");
 const token_log_id_1 = require("../../lib/token-log-id");
+const auth_1 = require("../../server/auth");
 async function GET(req) {
     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 (0, auth_1.resolveSessionState)(req);
+            if (sessionState.state === 'unknown') {
+                logger_1.logger.warn('[REFRESH-VIABILITY] Session store unavailable - session state unknown');
+                return server_1.NextResponse.json({ canRefresh: false, reason: 'store_unavailable', error: 'Session store unavailable', code: 'STORE_UNAVAILABLE' }, { status: 500 });
+            }
+            if (sessionState.state === 'missing') {
+                return server_1.NextResponse.json({ canRefresh: false, reason: 'session_not_found', sessionTokenId: (0, token_log_id_1.tokenLogId)(sessionState.sessionToken) }, { status: 200 });
+            }
+            if (sessionState.state === 'live') {
+                finalSessionToken = sessionState.session?.session?.token ?? null;
+            }
+        }
+        else if (!finalSessionToken) {
             const token = await (0, test_aware_get_token_1.getTokenTestAware)(req);
             // Support both field names: sessionToken (auth.ts JWT) and redisSessionId (legacy)
             finalSessionToken = (token?.sessionToken || token?.redisSessionId);

package/dist/api-handlers/session/viability.js

@@ -39,8 +39,22 @@ async function GET(req) {
                 code: 'AUTH_NOT_INITIALIZED'
             }, { status: 503 });
         }
-        // Get session from Better Auth
-        const betterAuthSession = await (0, auth_1.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 (0, auth_1.resolveSessionState)(req);
+        if (sessionState.state === 'unknown') {
+            console.warn('[VIABILITY] Session store unavailable - session state unknown');
+            return server_1.NextResponse.json({ authenticated: false, revocationStatus: 'unknown', 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 server_1.NextResponse.json({
+                authenticated: false,
+                sessionTokenId: (0, token_log_id_1.tokenLogId)(sessionState.sessionToken) // PAY-1481: correlation id, never the token
+            });
+        }
+        const betterAuthSession = sessionState.state === 'live' ? sessionState.session : null;
         // Debug logging
         if (!betterAuthSession) {
             console.warn('[VIABILITY] getSession returned null');

package/dist/auth/safe-callback.js

@@ -97,6 +97,11 @@ function safeCallbackPath(raw, fallback = exports.DEFAULT_CALLBACK) {
     // 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;
     // *** SECOND RESOLUTION. DO NOT DELETE THIS AS REDUNDANT - IT IS NOT. ***

package/dist/auth/session-cookie-clear.d.ts

@@ -0,0 +1,7 @@
+/**
+ * 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';
+export declare function expireSessionCookies(response: NextResponse, requestCookieNames: Iterable<string>): void;

package/dist/auth/session-cookie-clear.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.expireSessionCookies = expireSessionCookies;
+const app_slug_1 = require("../lib/app-slug");
+function expireSessionCookies(response, requestCookieNames) {
+    const sessionCookie = (0, app_slug_1.getSessionCookieName)();
+    const secureCookie = (0, app_slug_1.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/dist/auth/session-reset-link.d.ts

@@ -0,0 +1,43 @@
+export declare 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 declare 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 declare const RESET_LINK_TTL_SECONDS = 300;
+/** The purpose label for the derived signing key. Changing it invalidates every outstanding reset link. */
+export declare 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 declare const RESET_REASONS: readonly string[];
+export declare const RESET_ERRORS: readonly string[];
+export interface ResetParams {
+    callbackUrl: string;
+    reason?: string;
+    error?: string;
+}
+/** The secret the app already signs its session cookie with. Undefined means "cannot sign": callers fall back. */
+export declare function resetSecret(): string | undefined;
+/** The session cookie a reset is bound to: the __Secure- one when present, else the plain one. */
+export declare function boundSessionCookie(get: (name: string) => string | undefined, plainName: string, secureName: string): string | undefined;
+/** Normalise to exactly what the route will honour, so what is signed is what is verified. */
+export declare function normaliseResetParams(raw: {
+    callbackUrl?: string | null;
+    reason?: string | null;
+    error?: string | null;
+}): ResetParams;
+/** What the signature covers. Exported for the key-separation row, which signs it with the RAW secret. */
+export declare function resetPayload(p: ResetParams, exp: number, binding: string): string;
+/** The login URL for these params, in the exact shape the middleware has always emitted. */
+export declare function loginLocation(p: ResetParams): string;
+/**
+ * Path + query for the reset route, bound to `sessionCookieValue` (the session cookie on the request being ended).
+ * `nowMs` is injectable for tests.
+ */
+export declare function signedResetHref(route: string, p: ResetParams, secret: string, sessionCookieValue: string | undefined, nowMs?: number): Promise<string>;
+/**
+ * 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 declare function readResetRequest(search: URLSearchParams, secret: string | undefined, sessionCookieValue: string | undefined, nowMs?: number): Promise<{
+    params: ResetParams;
+    signed: boolean;
+}>;

package/dist/auth/session-reset-link.js

@@ -0,0 +1,144 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RESET_ERRORS = exports.RESET_REASONS = exports.RESET_KEY_PURPOSE = exports.RESET_LINK_TTL_SECONDS = exports.DEFAULT_SESSION_RESET_ROUTE = exports.LOGIN_PAGE = void 0;
+exports.resetSecret = resetSecret;
+exports.boundSessionCookie = boundSessionCookie;
+exports.normaliseResetParams = normaliseResetParams;
+exports.resetPayload = resetPayload;
+exports.loginLocation = loginLocation;
+exports.signedResetHref = signedResetHref;
+exports.readResetRequest = readResetRequest;
+/**
+ * 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).
+ */
+const safe_callback_1 = require("./safe-callback");
+exports.LOGIN_PAGE = '/account-auth/login';
+/** The mount point consumers use: `app/api/auth/session-reset/route.ts` (under /api/auth/, which middleware bypasses). */
+exports.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. */
+exports.RESET_LINK_TTL_SECONDS = 300;
+/** The purpose label for the derived signing key. Changing it invalidates every outstanding reset link. */
+exports.RESET_KEY_PURPOSE = 'next-mvp/session-reset/v1';
+/** The only `reason` / `error` values the middleware emits on a clearing redirect. Anything else is dropped. */
+exports.RESET_REASONS = ['stale', 'invalidated'];
+exports.RESET_ERRORS = ['SessionExpired', 'TwoFactorTimeout'];
+const encoder = new TextEncoder();
+const FIELD_SEPARATOR = String.fromCharCode(10);
+function b64url(bytes) {
+    return btoa(String.fromCharCode(...bytes)).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+async function hmacBytes(key, message) {
+    const k = await crypto.subtle.importKey('raw', key, { 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, message) {
+    const derived = await hmacBytes(encoder.encode(secret), exports.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) {
+    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, b) {
+    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. */
+function resetSecret() {
+    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. */
+function boundSessionCookie(get, plainName, secureName) {
+    return get(secureName) || get(plainName) || undefined;
+}
+/** Normalise to exactly what the route will honour, so what is signed is what is verified. */
+function normaliseResetParams(raw) {
+    const out = { callbackUrl: (0, safe_callback_1.safeCallbackPath)(raw.callbackUrl ?? '') };
+    if (raw.reason && exports.RESET_REASONS.includes(raw.reason))
+        out.reason = raw.reason;
+    if (raw.error && exports.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. */
+function resetPayload(p, exp, binding) {
+    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. */
+function loginLocation(p) {
+    let loc = `${exports.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.
+ */
+async function signedResetHref(route, p, secret, sessionCookieValue, nowMs = Date.now()) {
+    const exp = Math.floor(nowMs / 1000) + exports.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.
+ */
+async function readResetRequest(search, secret, sessionCookieValue, nowMs = Date.now()) {
+    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/dist/middleware/create-middleware.d.ts

@@ -99,6 +99,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,

package/dist/middleware/create-middleware.js

@@ -28,6 +28,8 @@ const safe_callback_1 = require("../auth/safe-callback");
 const internal_api_url_1 = require("../edge/internal-api-url");
 const app_slug_1 = require("../lib/app-slug");
 const rbac_check_1 = require("./rbac-check");
+const session_cookie_clear_1 = require("../auth/session-cookie-clear");
+const session_reset_link_1 = require("../auth/session-reset-link");
 // =============================================================================
 // DEFAULT IMPLEMENTATIONS
 // =============================================================================
@@ -105,24 +107,7 @@ function isPrefetchRequest(request) {
 function clearSessionCookies(response, request) {
     if (isPrefetchRequest(request))
         return;
-    const sessionCookie = (0, app_slug_1.getSessionCookieName)();
-    const secureCookie = (0, app_slug_1.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 })
-            });
-        }
-    }
+    (0, session_cookie_clear_1.expireSessionCookies)(response, Array.from(request.cookies, ([name]) => name));
 }
 /** Create redirect response, optionally clearing cookies */
 function redirectTo(request, location, clearCookies = false) {
@@ -132,6 +117,28 @@ function redirectTo(request, location, clearCookies = false) {
     }
     return response;
 }
+/**
+ * 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, location, reset) {
+    if (!reset || request.nextUrl.pathname.startsWith('/api/')) {
+        return redirectTo(request, location, true);
+    }
+    const target = new URL(location, request.url);
+    const params = (0, session_reset_link_1.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 = (0, session_reset_link_1.boundSessionCookie)((n) => request.cookies.get(n)?.value, (0, app_slug_1.getSessionCookieName)(), (0, app_slug_1.getSecureSessionCookieName)());
+    const response = server_1.NextResponse.redirect(new URL(await (0, session_reset_link_1.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.
  *
@@ -150,7 +157,7 @@ function redirectTo(request, location, clearCookies = false) {
  * higher would intercept 'refresh_needed' and disable middleware token refresh across
  * the whole API surface (card 340024 C1).
  */
-function refreshFailureResponse(request, location, errorCode, clearCookies = false) {
+async function refreshFailureResponse(request, location, errorCode, clearCookies = false, reset) {
     if (request.nextUrl.pathname.startsWith('/api/')) {
         const response = server_1.NextResponse.json({ error: errorCode }, { status: 401 });
         if (clearCookies) {
@@ -158,7 +165,7 @@ function refreshFailureResponse(request, location, errorCode, clearCookies = fal
         }
         return response;
     }
-    return redirectTo(request, location, clearCookies);
+    return clearCookies ? clearingRedirect(request, location, reset) : redirectTo(request, location);
 }
 /**
  * PAY-2147: the terminal answer when the middleware CANNOT TELL whether the session is good
@@ -359,6 +366,8 @@ function redirect2FA(callbackUrl) {
 // =============================================================================
 // MIDDLEWARE FACTORY
 // =============================================================================
+/** PAY-2218: the stripped-flight-headers warning is logged once per process, not once per request. */
+let flightHeadersStrippedWarned = false;
 function createMvpMiddleware(options = {}) {
     // Resolve options with defaults
     const cb = options.circuitBreaker || defaultCircuitBreaker;
@@ -369,6 +378,22 @@ function createMvpMiddleware(options = {}) {
     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 ? session_reset_link_1.DEFAULT_SESSION_RESET_ROUTE
+        : typeof options.sessionResetRoute === 'string' && options.sessionResetRoute ? options.sessionResetRoute
+            : undefined;
+    let resetSecretMissingLogged = false;
+    const resolveReset = () => {
+        if (!sessionResetRoute)
+            return undefined;
+        const secret = (0, session_reset_link_1.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) {
         const { pathname, searchParams } = request.nextUrl;
         // =========================================================================
@@ -387,6 +412,12 @@ function createMvpMiddleware(options = {}) {
                 return server_1.NextResponse.next();
             }
         }
+        // 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 = (0, route_config_1.isUnauthenticatedRoute)(pathname);
         const isLogin = isLoginPage(pathname);
         // --- Optimization: Skip viability check for unauthenticated public browsing ---
@@ -456,6 +487,7 @@ function createMvpMiddleware(options = {}) {
             logger: log,
             refreshEndpoint,
             rbacExemptPaths,
+            reset: resolveReset(),
             onRefreshSuccess: options.onRefreshSuccess,
             onRefreshFailure: options.onRefreshFailure,
         });
@@ -613,7 +645,9 @@ async function executeDecision(request, decision, pathname, sessionPointer, sess
         case 'allow':
             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);
         case 'refresh_needed':
@@ -719,7 +753,7 @@ async function handleRefresh(request, safeCallback, opts) {
             clearingCookies: isPermanentFailure
         });
         onRefreshFailure?.(response.status, false);
-        return refreshFailureResponse(request, `${LOGIN_PAGE}?callbackUrl=${encodeURIComponent(safeCallback)}&error=${errorParam}`, errorParam, isPermanentFailure);
+        return refreshFailureResponse(request, `${LOGIN_PAGE}?callbackUrl=${encodeURIComponent(safeCallback)}&error=${errorParam}`, errorParam, isPermanentFailure, opts.reset);
     }
     catch (error) {
         const isNetwork = cb.isNetworkError(error);

package/dist/routes/auth/session-reset.d.ts

@@ -0,0 +1,21 @@
+/**
+ * PAY-2218 PR 2: the session-reset route. Mount it at app/api/auth/session-reset/route.ts:
+ *
+ *     export { GET } from '@payez/next-mvp/routes/auth/session-reset';
+ *
+ * and turn it on with createMvpMiddleware({ sessionResetRoute: true }). The middleware then sends a page's
+ * session-ending redirect (stale session, force-invalidated, pre-2FA timeout, refresh 401/403) here instead of
+ * clearing the cookies itself. See src/auth/session-reset-link.ts for the measurements behind each rule.
+ *
+ *  - Router PREFETCH (the route sees `next-router-prefetch`, which Next strips before middleware): 204 + no-store,
+ *    no redirect, no Set-Cookie. A redirect here would be cached by the 15.5.x router and reused by the click, so
+ *    the real navigation would never come back to clear.
+ *  - Real navigation with a valid signed hand-off: expire the session cookies and 307 to the login page.
+ *  - Anything unsigned, tampered, expired, or bound to a DIFFERENT session than this request's cookie: 307 to the
+ *    login page and touch NO cookie (nobody can link a signed-in user here to log them out; a second use is a no-op).
+ *
+ * The login URL is always rebuilt from allowlisted parts; the route never redirects to a URL it was given.
+ */
+import { NextRequest, NextResponse } from 'next/server';
+export declare const dynamic = "force-dynamic";
+export declare function GET(request: NextRequest): Promise<NextResponse>;

package/dist/routes/auth/session-reset.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dynamic = void 0;
+exports.GET = GET;
+/**
+ * PAY-2218 PR 2: the session-reset route. Mount it at app/api/auth/session-reset/route.ts:
+ *
+ *     export { GET } from '@payez/next-mvp/routes/auth/session-reset';
+ *
+ * and turn it on with createMvpMiddleware({ sessionResetRoute: true }). The middleware then sends a page's
+ * session-ending redirect (stale session, force-invalidated, pre-2FA timeout, refresh 401/403) here instead of
+ * clearing the cookies itself. See src/auth/session-reset-link.ts for the measurements behind each rule.
+ *
+ *  - Router PREFETCH (the route sees `next-router-prefetch`, which Next strips before middleware): 204 + no-store,
+ *    no redirect, no Set-Cookie. A redirect here would be cached by the 15.5.x router and reused by the click, so
+ *    the real navigation would never come back to clear.
+ *  - Real navigation with a valid signed hand-off: expire the session cookies and 307 to the login page.
+ *  - Anything unsigned, tampered, expired, or bound to a DIFFERENT session than this request's cookie: 307 to the
+ *    login page and touch NO cookie (nobody can link a signed-in user here to log them out; a second use is a no-op).
+ *
+ * The login URL is always rebuilt from allowlisted parts; the route never redirects to a URL it was given.
+ */
+const server_1 = require("next/server");
+const create_middleware_1 = require("../../middleware/create-middleware");
+const session_cookie_clear_1 = require("../../auth/session-cookie-clear");
+const app_slug_1 = require("../../lib/app-slug");
+const session_reset_link_1 = require("../../auth/session-reset-link");
+exports.dynamic = 'force-dynamic';
+async function GET(request) {
+    if ((0, create_middleware_1.isPrefetchRequest)(request)) {
+        return new server_1.NextResponse(null, { status: 204, headers: { 'cache-control': 'no-store' } });
+    }
+    const bound = (0, session_reset_link_1.boundSessionCookie)((n) => request.cookies.get(n)?.value, (0, app_slug_1.getSessionCookieName)(), (0, app_slug_1.getSecureSessionCookieName)());
+    const { params, signed } = await (0, session_reset_link_1.readResetRequest)(request.nextUrl.searchParams, (0, session_reset_link_1.resetSecret)(), bound);
+    const response = server_1.NextResponse.redirect(new URL((0, session_reset_link_1.loginLocation)(params), request.url), 307);
+    response.headers.set('cache-control', 'no-store');
+    if (signed)
+        (0, session_cookie_clear_1.expireSessionCookies)(response, Array.from(request.cookies, ([name]) => name));
+    return response;
+}

package/dist/routes/auth/viability.d.ts

@@ -24,6 +24,13 @@ import { type RevocationStatus } from '../../vibe/sessions';
  * - expiresIn: number - Seconds until token expires
  */
 export declare function GET(req: NextRequest): Promise<NextResponse<{
+    viable: boolean;
+    needsRefresh: boolean;
+    authenticated: boolean;
+    revocationStatus: RevocationStatus;
+    error: string;
+    code: string;
+}> | NextResponse<{
     viable: boolean;
     needsRefresh: boolean;
     authenticated: boolean;
@@ -49,12 +56,4 @@ export declare function GET(req: NextRequest): Promise<NextResponse<{
     expiresAt: string;
     roles: string[];
     clientId: string | null;
-}> | NextResponse<{
-    viable: boolean;
-    needsRefresh: boolean;
-    authenticated: boolean;
-    revocationStatus: RevocationStatus;
-    error: string;
-    code: string;
-    correlationId: string;
 }>>;

package/dist/routes/auth/viability.js

@@ -136,8 +136,37 @@ function resolveClientId(sessionClientId) {
  */
 async function GET(req) {
     try {
-        const baSession = await (0, auth_1.getSession)(req);
-        if (!baSession) {
+        // PAY-2216: ask for the session's STATE, not a session-or-null. A null used to cover a store outage, a deleted
+        // session and no cookie alike, so this route answered 'No session found' to all three and the middleware could
+        // never clear a dead cookie (it must not clear on an outage). See SessionState in server/auth.
+        const sessionState = await (0, auth_1.resolveSessionState)(req);
+        if (sessionState.state === 'unknown') {
+            // The store did not answer. NOT a statement about the session: never stale, never 'No session found'.
+            // Same shape as this route's catch (PAY-1882 step 4): 'unknown' revocation -> the middleware's fail-closed
+            // path, a non-OK answer -> service_error, which never clears cookies.
+            console.warn('[VIABILITY] Session store unavailable - session state unknown');
+            return server_1.NextResponse.json({
+                viable: false,
+                needsRefresh: false,
+                authenticated: false,
+                revocationStatus: 'unknown',
+                error: 'Session store unavailable',
+                code: 'STORE_UNAVAILABLE'
+            }, { status: 500 });
+        }
+        if (sessionState.state === 'missing') {
+            // A VERIFIED cookie and a store that answered "not here". The existing stale shape, so the middleware's
+            // stale_session arm (PAY-2216 / 4.5.4) clears it.
+            console.warn('[VIABILITY] Stale cookie detected - verified cookie, session not in Redis');
+            return server_1.NextResponse.json({
+                viable: false,
+                needsRefresh: false,
+                authenticated: false,
+                sessionTokenId: (0, token_log_id_1.tokenLogId)(sessionState.sessionToken), // PAY-1481: a correlation id, never the token
+                reason: 'Stale session - cookie exists but session not found in Redis'
+            });
+        }
+        if (sessionState.state === 'none') {
             return server_1.NextResponse.json({
                 viable: false,
                 needsRefresh: false,
@@ -145,6 +174,7 @@ async function GET(req) {
                 reason: 'No session found'
             });
         }
+        const baSession = sessionState.session;
         const token = baSession;
         const sessionToken = baSession.session?.token;
         // Try the canonical session-store first; fall back to the Better-Auth-keyed