@payez/next-mvp 4.5.0 → 4.5.2

package/dist/auth/auth-decision.d.ts

@@ -21,6 +21,8 @@ export interface AuthContext {
         twoFactorComplete: boolean;
     };
     circuitBreakerOpen: boolean;
+    /** PAY-2136: the request is a router prefetch. A prefetch never clears cookies (see isPrefetchRequest). */
+    isPrefetch?: boolean;
 }
 export type AuthAction = {
     type: 'allow';
@@ -34,6 +36,13 @@ export type AuthAction = {
     reason: string;
 };
 /**
- * Main decision function - pure, testable, deterministic
+ * Main decision function - pure, testable, deterministic.
+ * PAY-2136: when `context.isPrefetch` is set, no redirect it returns asks for cookies to be cleared; the
+ * redirect itself is kept, and the next real navigation reaches the same decision and clears then.
+ *
+ * @deprecated PAY-2180: this exported engine is NOT the one the middleware runs. `createMvpMiddleware` decides with
+ * its own private engine (middleware/create-middleware.ts), so calling this answers a question nothing enforces.
+ * A sweep found no code consumer in the portal, idealvibe, idealresume or cryptaply. It will be REMOVED in the next
+ * major version, together with its re-exports from the package root and `/edge`. Use `createMvpMiddleware`.
  */
 export declare function makeAuthDecision(context: AuthContext): AuthAction;

package/dist/auth/auth-decision.js

@@ -9,10 +9,32 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.makeAuthDecision = makeAuthDecision;
 const safe_callback_1 = require("./safe-callback");
 const token_log_id_1 = require("../lib/token-log-id");
+/** PAY-2180: warn once per process, not per request. */
+let deprecationWarned = false;
 /**
- * Main decision function - pure, testable, deterministic
+ * Main decision function - pure, testable, deterministic.
+ * PAY-2136: when `context.isPrefetch` is set, no redirect it returns asks for cookies to be cleared; the
+ * redirect itself is kept, and the next real navigation reaches the same decision and clears then.
+ *
+ * @deprecated PAY-2180: this exported engine is NOT the one the middleware runs. `createMvpMiddleware` decides with
+ * its own private engine (middleware/create-middleware.ts), so calling this answers a question nothing enforces.
+ * A sweep found no code consumer in the portal, idealvibe, idealresume or cryptaply. It will be REMOVED in the next
+ * major version, together with its re-exports from the package root and `/edge`. Use `createMvpMiddleware`.
  */
 function makeAuthDecision(context) {
+    if (!deprecationWarned) {
+        deprecationWarned = true;
+        console.warn('[next-mvp] makeAuthDecision (auth/auth-decision) is deprecated (PAY-2180) and will be removed in the next major: ' +
+            'createMvpMiddleware does not use it. Use createMvpMiddleware.');
+    }
+    const action = decide(context);
+    if (context.isPrefetch && action.type === 'redirect' && action.clearCookies) {
+        const { clearCookies: _dropped, ...rest } = action;
+        return rest;
+    }
+    return action;
+}
+function decide(context) {
     const { pathname, isPublicRoute, isLoginPage, searchParams, sessionPointer, sessionStatus, circuitBreakerOpen } = context;
     // SAFEGUARD: Never use auth pages as callback URLs to prevent redirect loops.
     // 375656: `pathname` is our own request path rather than an attacker-supplied

package/dist/edge/middleware.d.ts

@@ -7,7 +7,7 @@
 export { makeAuthDecision } from '../auth/auth-decision';
 export { isUnauthenticatedRoute, configurePublicRoutes, getRouteConfig, configure2FABypassRoutes, should2FABypass, get2FABypassConfig } from '../auth/route-config';
 export type { UnauthenticatedRouteConfig, ProtectedRouteConfig } from '../auth/route-config';
-export { createMvpMiddleware } from '../middleware/create-middleware';
+export { createMvpMiddleware, isPrefetchRequest } from '../middleware/create-middleware';
 export type { MvpMiddlewareOptions, CircuitBreakerProvider, MiddlewareLogger, AuthContext, AuthAction, SessionPointer, SessionStatus } from '../middleware/create-middleware';
 export { TwoFactorPresets, AMRValues, ACRLevels, validateAMR, validateACR, checkTwoFactorRequirements } from '../middleware/twofa-presets';
 export type { TwoFactorRequirements, RouteConfig } from '../middleware/twofa-presets';

package/dist/edge/middleware.js

@@ -6,7 +6,7 @@
  * Client-side utilities that depend on browser APIs or server-only code are excluded.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getInternalApiUrl = exports.checkTwoFactorRequirements = exports.validateACR = exports.validateAMR = exports.ACRLevels = exports.AMRValues = exports.TwoFactorPresets = exports.createMvpMiddleware = exports.get2FABypassConfig = exports.should2FABypass = exports.configure2FABypassRoutes = exports.getRouteConfig = exports.configurePublicRoutes = exports.isUnauthenticatedRoute = exports.makeAuthDecision = void 0;
+exports.getInternalApiUrl = exports.checkTwoFactorRequirements = exports.validateACR = exports.validateAMR = exports.ACRLevels = exports.AMRValues = exports.TwoFactorPresets = exports.isPrefetchRequest = exports.createMvpMiddleware = exports.get2FABypassConfig = exports.should2FABypass = exports.configure2FABypassRoutes = exports.getRouteConfig = exports.configurePublicRoutes = exports.isUnauthenticatedRoute = exports.makeAuthDecision = void 0;
 // Authentication middleware and configuration (Edge Runtime compatible)
 var auth_decision_1 = require("../auth/auth-decision");
 Object.defineProperty(exports, "makeAuthDecision", { enumerable: true, get: function () { return auth_decision_1.makeAuthDecision; } });
@@ -19,6 +19,7 @@ Object.defineProperty(exports, "should2FABypass", { enumerable: true, get: funct
 Object.defineProperty(exports, "get2FABypassConfig", { enumerable: true, get: function () { return route_config_1.get2FABypassConfig; } });
 var create_middleware_1 = require("../middleware/create-middleware");
 Object.defineProperty(exports, "createMvpMiddleware", { enumerable: true, get: function () { return create_middleware_1.createMvpMiddleware; } });
+Object.defineProperty(exports, "isPrefetchRequest", { enumerable: true, get: function () { return create_middleware_1.isPrefetchRequest; } });
 // Two-Factor Authentication Presets (Edge Runtime compatible)
 var twofa_presets_1 = require("../middleware/twofa-presets");
 Object.defineProperty(exports, "TwoFactorPresets", { enumerable: true, get: function () { return twofa_presets_1.TwoFactorPresets; } });

package/dist/index.d.ts

@@ -6,7 +6,7 @@ export type { AuthConfig } from './types/auth';
 export { makeAuthDecision } from './auth/auth-decision';
 export { isUnauthenticatedRoute, configurePublicRoutes, getRouteConfig } from './auth/route-config';
 export { safeCallbackPath, isSafeCallbackPath, resolveCallbackDestination, DEFAULT_CALLBACK } from './auth/safe-callback';
-export { createMvpMiddleware } from './middleware/create-middleware';
+export { createMvpMiddleware, isPrefetchRequest } from './middleware/create-middleware';
 export { UserAvatarMenu, MobileNavDrawer } from './components/account';
 export type { UserAvatarMenuProps, MobileNavDrawerProps, NavItem, NavSection } from './components/account';
 export { ErrorMetricsCard, HealthMetricsCard, AuditLogViewer, AdminAnalyticsLayout, useErrorMetrics, useHealthMetrics, useAuditLog, useAdminAnalytics, getErrorMetrics, getHealthMetrics, writeAuditLog, queryAuditLog, } from './logging';

package/dist/index.js

@@ -8,7 +8,7 @@
 // - Better Auth: import { createBetterAuthInstance } from '@payez/next-mvp/auth/better-auth'
 // - Server auth: import { getSession } from '@payez/next-mvp/server/auth'
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.queryAuditLog = exports.writeAuditLog = exports.getHealthMetrics = exports.getErrorMetrics = exports.useAdminAnalytics = exports.useAuditLog = exports.useHealthMetrics = exports.useErrorMetrics = exports.AdminAnalyticsLayout = exports.AuditLogViewer = exports.HealthMetricsCard = exports.ErrorMetricsCard = exports.MobileNavDrawer = exports.UserAvatarMenu = exports.createMvpMiddleware = exports.DEFAULT_CALLBACK = exports.resolveCallbackDestination = exports.isSafeCallbackPath = exports.safeCallbackPath = exports.getRouteConfig = exports.configurePublicRoutes = exports.isUnauthenticatedRoute = exports.makeAuthDecision = exports.useTraditionalAuthEnabled = exports.useFederatedAuthEnabled = exports.useFederatedProviders = exports.useAuthMode = exports.useAuthConfig = exports.AuthProvider = exports.useAnonSession = exports.fetchWithAuth = void 0;
+exports.queryAuditLog = exports.writeAuditLog = exports.getHealthMetrics = exports.getErrorMetrics = exports.useAdminAnalytics = exports.useAuditLog = exports.useHealthMetrics = exports.useErrorMetrics = exports.AdminAnalyticsLayout = exports.AuditLogViewer = exports.HealthMetricsCard = exports.ErrorMetricsCard = exports.MobileNavDrawer = exports.UserAvatarMenu = exports.isPrefetchRequest = exports.createMvpMiddleware = exports.DEFAULT_CALLBACK = exports.resolveCallbackDestination = exports.isSafeCallbackPath = exports.safeCallbackPath = exports.getRouteConfig = exports.configurePublicRoutes = exports.isUnauthenticatedRoute = exports.makeAuthDecision = exports.useTraditionalAuthEnabled = exports.useFederatedAuthEnabled = exports.useFederatedProviders = exports.useAuthMode = exports.useAuthConfig = exports.AuthProvider = exports.useAnonSession = exports.fetchWithAuth = void 0;
 // Client-safe exports only
 // Client-side utilities
 var fetch_with_auth_1 = require("./client/fetch-with-auth");
@@ -40,6 +40,7 @@ Object.defineProperty(exports, "resolveCallbackDestination", { enumerable: true,
 Object.defineProperty(exports, "DEFAULT_CALLBACK", { enumerable: true, get: function () { return safe_callback_1.DEFAULT_CALLBACK; } });
 var create_middleware_1 = require("./middleware/create-middleware");
 Object.defineProperty(exports, "createMvpMiddleware", { enumerable: true, get: function () { return create_middleware_1.createMvpMiddleware; } });
+Object.defineProperty(exports, "isPrefetchRequest", { enumerable: true, get: function () { return create_middleware_1.isPrefetchRequest; } });
 // Account Components
 var account_1 = require("./components/account");
 Object.defineProperty(exports, "UserAvatarMenu", { enumerable: true, get: function () { return account_1.UserAvatarMenu; } });

package/dist/lib/idp-fetch.d.ts

@@ -1,6 +1,7 @@
 import { NextRequest } from 'next/server';
 import { assertAbsoluteIdpUrl } from './idp-url-guard';
-export { assertAbsoluteIdpUrl };
+import { parseRetryAfterSeconds } from './retry-after';
+export { assertAbsoluteIdpUrl, parseRetryAfterSeconds };
 /**
  * Centralized IDP fetch helper
  * - Injects Bearer from Redis session
@@ -12,5 +13,11 @@ export interface IdpFetchResult<T = any> {
     status: number;
     json: T | null;
     attemptedRefresh: boolean;
+    /**
+     * PAY-1608: the upstream Retry-After in whole seconds, when the IDP sent a usable one. Core sends it on every
+     * 2FA lock (MfaController.SecondFactorLocked: 429 + Retry-After 900; VerifyTotp: what is left of the lock).
+     * It used to be dropped here, so no BFF could state the real lock window. Absent otherwise.
+     */
+    retryAfterSeconds?: number;
 }
 export declare function idpFetchJSON<T = any>(req: NextRequest, targetUrl: string, init?: RequestInit): Promise<IdpFetchResult<T>>;

package/dist/lib/idp-fetch.js

@@ -33,13 +33,15 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.assertAbsoluteIdpUrl = void 0;
+exports.parseRetryAfterSeconds = exports.assertAbsoluteIdpUrl = void 0;
 exports.idpFetchJSON = idpFetchJSON;
 const test_aware_get_token_1 = require("./test-aware-get-token");
 const session_store_1 = require("./session-store");
 const internal_api_1 = require("./internal-api");
 const idp_url_guard_1 = require("./idp-url-guard");
 Object.defineProperty(exports, "assertAbsoluteIdpUrl", { enumerable: true, get: function () { return idp_url_guard_1.assertAbsoluteIdpUrl; } });
+const retry_after_1 = require("./retry-after");
+Object.defineProperty(exports, "parseRetryAfterSeconds", { enumerable: true, get: function () { return retry_after_1.parseRetryAfterSeconds; } });
 function buildHeaders(req, bearer, extra) {
     const headers = {
         Accept: 'application/json',
@@ -177,5 +179,6 @@ async function idpFetchJSON(req, targetUrl, init = {}) {
         }
         catch { }
     }
-    return { ok: res.ok, status: res.status, json: json, attemptedRefresh };
+    const retryAfterSeconds = (0, retry_after_1.parseRetryAfterSeconds)(res.headers?.get?.('Retry-After'));
+    return { ok: res.ok, status: res.status, json: json, attemptedRefresh, ...(retryAfterSeconds ? { retryAfterSeconds } : {}) };
 }

package/dist/lib/retry-after.d.ts

@@ -0,0 +1,10 @@
+/**
+ * PAY-1608: parse an HTTP Retry-After header to whole seconds.
+ *
+ * Accepts delta-seconds ("900") and an HTTP date in the future. Answers undefined for absent, zero, negative,
+ * fractional, past or malformed values - a caller that gets undefined states no window rather than a guessed one.
+ *
+ * A dependency-free leaf on purpose: idp-fetch re-exports it, but a test can load it without the session/redis
+ * graph idp-fetch pulls in.
+ */
+export declare function parseRetryAfterSeconds(value: string | null | undefined, nowMs?: number): number | undefined;

package/dist/lib/retry-after.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseRetryAfterSeconds = parseRetryAfterSeconds;
+/**
+ * PAY-1608: parse an HTTP Retry-After header to whole seconds.
+ *
+ * Accepts delta-seconds ("900") and an HTTP date in the future. Answers undefined for absent, zero, negative,
+ * fractional, past or malformed values - a caller that gets undefined states no window rather than a guessed one.
+ *
+ * A dependency-free leaf on purpose: idp-fetch re-exports it, but a test can load it without the session/redis
+ * graph idp-fetch pulls in.
+ */
+function parseRetryAfterSeconds(value, nowMs = Date.now()) {
+    if (typeof value !== 'string')
+        return undefined;
+    const v = value.trim();
+    if (/^\d+$/.test(v)) {
+        const n = parseInt(v, 10);
+        return n > 0 ? n : undefined;
+    }
+    // Only something that looks like an HTTP date (it has letters: "Sat, 10 Oct 2026 12:01:30 GMT") is parsed as
+    // one; "-5" and "1.5" must not reach Date.parse, which would read them as years.
+    if (!/[a-z]/i.test(v))
+        return undefined;
+    const at = Date.parse(v);
+    if (!Number.isFinite(at))
+        return undefined;
+    const secs = Math.ceil((at - nowMs) / 1000);
+    return secs > 0 ? secs : undefined;
+}

package/dist/lib/session-store.d.ts

@@ -218,3 +218,20 @@ export declare function isRefreshInProgress(sessionToken: string): Promise<boole
  * Force cleanup of expired or orphaned refresh locks
  */
 export declare function cleanupRefreshLocks(): Promise<number>;
+/**
+ * PAY-2136 DIAGNOSTIC (BAPert 70873): which of the session keys EXIST for a token, right now.
+ *
+ * Names/presence only - this returns booleans and the key PREFIX (an app slug, not a secret), never a value and
+ * never any part of the token. It exists so a NO_SESSION can be read for what it was: canonical row gone with the
+ * ba: record alive (the :330 asymmetry), both gone (expired/deleted), or the store could not be asked ('error').
+ *
+ * EXISTS, not GET: it cannot parse, cannot throw on a malformed blob, and cannot return a credential. Each key is
+ * asked separately so one timeout does not hide the other two. Never throws.
+ */
+export type KeyPresence = boolean | 'error';
+export declare function describeSessionKeyPresence(sessionToken: string): Promise<{
+    prefix: string;
+    canonical: KeyPresence;
+    ba: KeyPresence;
+    ver: KeyPresence;
+}>;

package/dist/lib/session-store.js

@@ -37,6 +37,7 @@ exports.releaseRefreshLock = releaseRefreshLock;
 exports.checkRefreshLock = checkRefreshLock;
 exports.isRefreshInProgress = isRefreshInProgress;
 exports.cleanupRefreshLocks = cleanupRefreshLocks;
+exports.describeSessionKeyPresence = describeSessionKeyPresence;
 const redis_1 = __importDefault(require("./redis"));
 const crypto_1 = require("crypto");
 const app_slug_1 = require("./app-slug");
@@ -927,3 +928,35 @@ async function cleanupRefreshLocks() {
     console.warn('[SESSION-STORE] cleanupRefreshLocks called - scanning for expired locks');
     return 0;
 }
+async function describeSessionKeyPresence(sessionToken) {
+    const ask = async (key) => {
+        try {
+            return (await redis_1.default.exists(key)) > 0;
+        }
+        catch {
+            return 'error';
+        }
+    };
+    let prefix = '';
+    try {
+        prefix = (0, app_slug_1.getSessionPrefix)();
+    }
+    catch {
+        prefix = '';
+    }
+    if (!sessionToken)
+        return { prefix, canonical: false, ba: false, ver: false };
+    let canonicalKey = '';
+    let baKey = '';
+    let verKey = '';
+    try {
+        canonicalKey = getSessionKey(sessionToken);
+        baKey = getBetterAuthSessionKey(sessionToken, (0, app_slug_1.getAppSlug)());
+        verKey = getSessionVersionKey(sessionToken);
+    }
+    catch {
+        return { prefix, canonical: 'error', ba: 'error', ver: 'error' };
+    }
+    const [canonical, ba, ver] = await Promise.all([ask(canonicalKey), ask(baKey), ask(verKey)]);
+    return { prefix, canonical, ba, ver };
+}

package/dist/lib/two-factor-verify-failure.d.ts

@@ -56,10 +56,18 @@ export declare function stepUpRefusal(status: number, json: unknown): StepUpRefu
  */
 export declare function upstreamErrorTexts(json: unknown): string[];
 export declare function classifyTwoFactorVerifyFailure(status: number, json: unknown): TwoFactorVerifyFailureCode;
+/**
+ * PAY-1608: the window as words - "15 minutes", "1 minute", "45 seconds", "2 hours". Rounded UP, so the user is never
+ * told a shorter wait than the IDP enforces. Undefined in, undefined out.
+ */
+export declare function formatLockWindow(seconds: number | undefined): string | undefined;
+/** PAY-1608: the LOCKED sentence with the IDP's real window, or the number-free one when none was sent. */
+export declare function lockedText(retryAfterSeconds?: number): string;
 export declare function twoFactorVerifyFailure(result: {
     status: number;
     json: unknown;
     attemptedRefresh: boolean;
+    retryAfterSeconds?: number;
 }, method: TwoFactorVerifyMethod): NextResponse;
 /**
  * PAY-1443 residual: account/send-code on the SAME verify-code screen. A send has no

package/dist/lib/two-factor-verify-failure.js

@@ -4,6 +4,8 @@ exports.STEP_UP_REFUSAL_CODE = void 0;
 exports.stepUpRefusal = stepUpRefusal;
 exports.upstreamErrorTexts = upstreamErrorTexts;
 exports.classifyTwoFactorVerifyFailure = classifyTwoFactorVerifyFailure;
+exports.formatLockWindow = formatLockWindow;
+exports.lockedText = lockedText;
 exports.twoFactorVerifyFailure = twoFactorVerifyFailure;
 exports.classifyTwoFactorSendFailure = classifyTwoFactorSendFailure;
 exports.twoFactorSendCodeFailure = twoFactorSendCodeFailure;
@@ -33,7 +35,9 @@ const INVALID_CODE_TEXT = {
     backup_code: 'Invalid backup code. Please try again.',
 };
 const FIXED_TEXT = {
-    LOCKED: 'Too many incorrect codes. Verification is locked for 15 minutes - wait before entering another code.',
+    // PAY-1608: NO NUMBER HERE. This is the sentence for a lock whose window the IDP did not send; lockedText()
+    // states the real window when Retry-After arrives. A hard-coded "15 minutes" was true only while every lock was 15.
+    LOCKED: 'Too many incorrect codes. Verification is locked for now - even a correct code is refused until the lock ends. Wait before entering another code.',
     RATE_LIMITED: 'Too many attempts. Please wait a moment and try again.',
     SESSION_REJECTED: 'We could not verify the code for this session. Please try again.',
     VERIFY_UNAVAILABLE: 'We could not verify the code right now. Please try again.',
@@ -186,13 +190,41 @@ function classifyTwoFactorVerifyFailure(status, json) {
         return 'VERIFY_UNAVAILABLE';
     return 'VERIFY_FAILED';
 }
+/**
+ * PAY-1608: the window as words - "15 minutes", "1 minute", "45 seconds", "2 hours". Rounded UP, so the user is never
+ * told a shorter wait than the IDP enforces. Undefined in, undefined out.
+ */
+function formatLockWindow(seconds) {
+    if (typeof seconds !== 'number' || !Number.isFinite(seconds) || seconds <= 0)
+        return undefined;
+    const plural = (n, unit) => `${n} ${unit}${n === 1 ? '' : 's'}`;
+    if (seconds < 60)
+        return plural(Math.ceil(seconds), 'second');
+    const minutes = Math.ceil(seconds / 60);
+    if (minutes < 120)
+        return plural(minutes, 'minute');
+    return plural(Math.ceil(minutes / 60), 'hour');
+}
+/** PAY-1608: the LOCKED sentence with the IDP's real window, or the number-free one when none was sent. */
+function lockedText(retryAfterSeconds) {
+    const window = formatLockWindow(retryAfterSeconds);
+    return window
+        ? `Too many incorrect codes. Verification is locked for ${window} - wait before entering another code.`
+        : FIXED_TEXT.LOCKED;
+}
 function twoFactorVerifyFailure(result, method) {
     const refusal = stepUpRefusal(result.status, result.json);
     if (refusal)
         return stepUpResponse(refusal, result.attemptedRefresh);
     const code = classifyTwoFactorVerifyFailure(result.status, result.json);
-    const error = code === 'INVALID_CODE' ? INVALID_CODE_TEXT[method] : FIXED_TEXT[code];
-    return server_1.NextResponse.json({ success: false, error, code, meta: { attemptedRefresh: result.attemptedRefresh } }, { status: result.status });
+    const error = code === 'INVALID_CODE' ? INVALID_CODE_TEXT[method]
+        : code === 'LOCKED' ? lockedText(result.retryAfterSeconds)
+            : FIXED_TEXT[code];
+    // PAY-1608: a lock or a throttle relays the IDP's window, as a number (for a client that words it itself) and as the
+    // standard header. Never on other failures, and never invented: absent upstream means absent here.
+    const wait = (code === 'LOCKED' || code === 'RATE_LIMITED') && formatLockWindow(result.retryAfterSeconds)
+        ? Math.ceil(result.retryAfterSeconds) : undefined;
+    return server_1.NextResponse.json({ success: false, error, code, ...(wait ? { retryAfterSeconds: wait } : {}), meta: { attemptedRefresh: result.attemptedRefresh } }, { status: result.status, ...(wait ? { headers: { 'Retry-After': String(wait) } } : {}) });
 }
 const SEND_LABEL = { sms: 'text message', email: 'email' };
 function classifyTwoFactorSendFailure(status, json) {

package/dist/middleware/create-middleware.d.ts

@@ -124,6 +124,16 @@ export interface MvpMiddlewareOptions {
      */
     revocationFailMode?: 'closed' | 'open';
 }
+/**
+ * PAY-2136 Rule A: a speculative request (router prefetch) must NEVER mutate cookies.
+ * A prefetch of /account/security was answered 307 + Set-Cookie (session cookies expired), the browser
+ * applied it, and the user's next real request (e.g. Approve) was signed out. Detected by any of:
+ * `Next-Router-Prefetch: 1|2` (Next sets it on EVERY Link prefetch; 2 = runtime prefetch) or `Sec-Purpose`/`Purpose`
+ * containing "prefetch".
+ * NOT `RSC: 1` + `_rsc`: a real client-side navigation carries both too (Nextpert-Scout 70976), so that shape
+ * would swallow in-app navigations and stop the middleware refreshing/clearing for them.
+ */
+export declare function isPrefetchRequest(request: NextRequest): boolean;
 /** Login error code for a pre-2FA session that expired before the code was verified (PAY-884). */
 export declare const TWO_FACTOR_TIMEOUT_ERROR = "TwoFactorTimeout";
 export declare function createMvpMiddleware(options?: MvpMiddlewareOptions): (request: NextRequest) => Promise<NextResponse>;

package/dist/middleware/create-middleware.js

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

package/dist/server/auth.js

@@ -48,6 +48,7 @@ exports.requireSession = requireSession;
 require("server-only");
 const better_auth_1 = require("../auth/better-auth");
 const session_store_1 = require("../lib/session-store");
+const token_log_id_1 = require("../lib/token-log-id");
 const verified_session_token_1 = require("./verified-session-token");
 function buildSessionDataFromAuthSession(session) {
     const user = session?.user;
@@ -138,6 +139,79 @@ function attachSessionData(session, sessionData, sessionToken) {
 async function getAuthInstance() {
     return (0, better_auth_1.getBetterAuthInstance)();
 }
+/* ----------------------------------------------------------------------------------------------------------------
+ * PAY-2136 DIAGNOSTICS (BAPert 70873, Nextpert-Scout 70872/70875) - LOG ONLY, NO BEHAVIOUR CHANGE.
+ *
+ * A getFreshIdpToken NO_SESSION used to carry no origin: three different returns produced the same
+ * `{error:'NO_SESSION'}`, and getSession() swallowed every Redis error into a bare `catch {}`. These helpers name
+ * the origin and make a swallowed read audible. Hard rules: every helper is wrapped so it can NEVER throw or change
+ * a return value; nothing here ever logs a token, a cookie VALUE or a Redis value - only a tokenLogId() fingerprint,
+ * cookie NAMES, booleans, and an error name/message with any long opaque run redacted.
+ * -------------------------------------------------------------------------------------------------------------- */
+/** An error name/message, first 80 chars, with any 24+ char opaque run (a token, a key) replaced. */
+function scrubForLog(v) {
+    const raw = v instanceof Error ? v.message : String(v ?? '');
+    return raw.replace(/[A-Za-z0-9_\-.+/=]{24,}/g, '[redacted]').slice(0, 80);
+}
+/** `catch {}` sites on the session read path: still swallowed, now audible. */
+function logSessionReadSwallowed(path, err) {
+    try {
+        const name = scrubForLog(err instanceof Error ? err.name : typeof err);
+        console.warn(`[server-auth] SESSION_READ_SWALLOWED path=${path} err=${name} msg=${scrubForLog(err)}`);
+    }
+    catch {
+        /* a diagnostic must never change the outcome */
+    }
+}
+/** Origin a: getSession(request) produced no token. Cookie NAMES only, never a value. */
+function logNoSessionOriginA(request) {
+    try {
+        const header = request?.headers?.get('cookie') ?? '';
+        // Only segments of the form name=value contribute a NAME. A segment with no '=' is not a cookie pair, and
+        // logging it whole could emit a bare token (Nextpert-Scout 70901 finding 1).
+        const cookieNames = header
+            .split(';')
+            // Structural, alphabet-independent (Nextpert-Scout 70945): base64 padding can only sit at the END of a bare
+            // value, so a bare padded token splits as name=<token>, value='' or '='. A real pair has a non-empty value that
+            // is not only '=' characters. (The old includes('=') let 74% of base64url tokens through as a "name".)
+            .filter((c) => {
+            const i = c.indexOf('=');
+            if (i < 0)
+                return false;
+            const v = c.slice(i + 1);
+            return v !== '' && !/^=+$/.test(v);
+        })
+            .map((c) => c.split('=')[0].trim())
+            .filter((n) => n !== '')
+            // A bare token that merely ENDS in base64 padding ('=') still passes the filter above and its "name" would be
+            // the token itself (Nextpert-Scout 70913). Real cookie names carry a separator ('.', '-', '_'); a long name with
+            // none is opaque, so it is logged as a placeholder, never as itself.
+            .map((n) => (n.length >= 24 && !/[._-]/.test(n) ? '[opaque-name]' : n))
+            .slice(0, 20);
+        console.warn('[server-auth] NO_SESSION origin=a', { hasCookieHeader: header !== '', cookieNames });
+    }
+    catch {
+        /* a diagnostic must never change the outcome */
+    }
+}
+/** Origins b and c: a token WAS resolved. Log which of its three keys exist (presence only), fire-and-forget. */
+function logNoSessionWithKeys(origin, sessionToken) {
+    try {
+        void (0, session_store_1.describeSessionKeyPresence)(sessionToken).then((keys) => {
+            try {
+                console.warn(`[server-auth] NO_SESSION origin=${origin}`, { token: (0, token_log_id_1.tokenLogId)(sessionToken), ...keys });
+            }
+            catch {
+                /* never throws */
+            }
+        }, () => {
+            /* never throws */
+        });
+    }
+    catch {
+        /* a diagnostic must never change the outcome */
+    }
+}
 /**
  * Get the current session from a request.
  *
@@ -167,7 +241,9 @@ async function getSession(request) {
     try {
         betterAuthSession = await auth.api.getSession({ headers: request.headers });
     }
-    catch { /* fall through to canonical Redis path */ }
+    catch (err) {
+        logSessionReadSwallowed('primary', err); // fall through to canonical Redis path
+    }
     if (betterAuthSession?.session?.token && betterAuthSession?.user) {
         const sessionToken = betterAuthSession.session.token;
         let sessionData = null;
@@ -176,7 +252,9 @@ async function getSession(request) {
             if (!sessionData)
                 sessionData = await (0, session_store_1.getBetterAuthSession)(sessionToken);
         }
-        catch { /* Redis unavailable */ }
+        catch (err) {
+            logSessionReadSwallowed('A', err); // Redis unavailable
+        }
         if (!sessionData)
             sessionData = buildSessionDataFromAuthSession(betterAuthSession);
         return attachSessionData(betterAuthSession, sessionData, sessionToken);
@@ -201,7 +279,9 @@ async function getSession(request) {
         if (!sessionData)
             sessionData = await (0, session_store_1.getBetterAuthSession)(sessionToken);
     }
-    catch { /* Redis unavailable */ }
+    catch (err) {
+        logSessionReadSwallowed('B', err); // Redis unavailable
+    }
     if (!sessionData)
         return null;
     // Synthesize a minimal session shape compatible with downstream callers.
@@ -282,6 +362,7 @@ async function getFreshIdpToken(request, config) {
     const session = await getSession(request);
     const sessionToken = session?.session?.token;
     if (!sessionToken) {
+        logNoSessionOriginA(request);
         return { success: false, error: 'NO_SESSION', status: 401, terminal: true };
     }
     const { ensureFreshAccessToken } = await Promise.resolve().then(() => __importStar(require('../lib/ensure-fresh-access-token')));
@@ -294,6 +375,8 @@ async function getFreshIdpToken(request, config) {
         requestId: request?.headers?.get('x-request-id') ?? undefined,
     });
     if (!result.ok) {
+        if (result.code === 'NO_SESSION')
+            logNoSessionWithKeys('b', sessionToken);
         return {
             success: false,
             error: result.code,
@@ -306,6 +389,7 @@ async function getFreshIdpToken(request, config) {
     }
     const sessionData = await (0, session_store_1.getSession)(sessionToken);
     if (!sessionData) {
+        logNoSessionWithKeys('c', sessionToken);
         return { success: false, error: 'NO_SESSION', status: 401, terminal: true };
     }
     return {

package/dist/vibe/sessions.d.ts

@@ -210,29 +210,14 @@ export declare function warnNonNumericUserId(sessionToken: string | undefined, r
 export declare function readSessionRevocationHmac(idpUserId: number): Promise<{
     ok: boolean;
     sessions: IVibeLoginSession[];
+    failure?: string;
 }>;
-/**
- * Determine whether a session is revoked, with an explicit UNKNOWN state
- * (PAY-1882 step 4 producer half).
- *
- * States:
- *   'not_configured' - this deployment has no revocation source (IDP_URL /
- *                      VIBE_CLIENT_ID / VIBE_HMAC_KEY absent). Viable; today's
- *                      behaviour. Logged once, not per request.
- *   'unknown'        - revocation IS configured but the read FAILED (non-OK,
- *                      timeout, throw). Enforcing middleware fails this CLOSED
- *                      by default (revocationFailMode 'closed'); a Vibe-less
- *                      consumer is 'not_configured', not 'unknown', so it is not
- *                      signed out.
- *   'revoked'        - the session's own token hash matches a revoked row, or
- *                      the user has no active session at all.
- *   'active'         - read OK and the session is not revoked.
- *
- * @param idpUserId - The user's IDP ID
- * @param sessionToken - The live session token; hashed to match the stored row.
- *                       When absent, the user-wide check applies (legacy path).
- */
-export declare function getRevocationStatus(idpUserId: number, sessionToken?: string): Promise<RevocationStatus>;
+/** True only for the exact code CONCURRENT_LIMIT (nested error.code, top-level code/errorCode); a non-JSON body falls back to the literal. */
+export declare function isConcurrentLimitBody(bodyText: string): boolean;
+/** Retry-After seconds when the proxy kept it (capped at 2 s: this runs in the request path), else 200-400 ms jitter. */
+export declare function revocationRetryDelayMs(response: Response): number;
+/** Which branch of the revocation decision produced the verdict (PAY-2136 reason log; never a value). */
+export type RevocationRule = 'own_row_revoked' | 'legacy_no_active' | 'legacy_recent_2h' | 'none';
 /**
  * Get session statistics for admin dashboard.
  *
@@ -246,3 +231,6 @@ export declare function getSessionStats(accessToken: string): Promise<{
     byDevice: Record<string, number>;
     recentLogins: number;
 }>;
+/** Test/ops hook: forget every cached verdict and in-flight read. */
+export declare function resetRevocationCache(): void;
+export declare function getRevocationStatus(idpUserId: number, sessionToken?: string): Promise<RevocationStatus>;