@payez/next-mvp 4.5.4 → 4.5.6

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/better-auth.js

@@ -64,6 +64,7 @@ const jose_1 = require("jose"); // better-auth's own JWT dependency
 const better_auth_1 = require("better-auth");
 const next_js_1 = require("better-auth/next-js");
 const next_js_2 = require("better-auth/next-js");
+const session_response_sanitizer_1 = require("./session-response-sanitizer");
 const magic_link_1 = require("better-auth/plugins/magic-link");
 const client_key_1 = require("../lib/client-key");
 const generic_oauth_1 = require("better-auth/plugins/generic-oauth");
@@ -887,7 +888,10 @@ async function getBetterAuthHandler() {
     if (!isBetterAuthEnabled())
         return null;
     const auth = await getBetterAuthInstance();
-    return (0, next_js_2.toNextJsHandler)(auth);
+    // PAY-2217: Better Auth's native endpoints (get-session, list-sessions, sign-in/*, sign-up/*) put the session
+    // token in the body. Strip it at the HTTP boundary here, so every consumer that mounts this handler gets it;
+    // auth.api (server-side) is untouched and still sees the token. See session-response-sanitizer.ts.
+    return (0, session_response_sanitizer_1.wrapBetterAuthHandler)(auth, (0, next_js_2.toNextJsHandler)(auth));
 }
 /**
  * Exchange OAuth identity for IDP tokens and store in the BA Redis session.

package/dist/auth/session-response-sanitizer.d.ts

@@ -0,0 +1,70 @@
+/**
+ * PAY-2217: no session token reaches browser JS from Better Auth's own HTTP endpoints.
+ *
+ * WHAT WAS WRONG. PAY-1481 removed token material from the package's own GET /api/auth/session. Better Auth's native
+ * endpoints are a separate surface served by the catch-all mount, and their default bodies carry the session
+ * credential identifier:
+ *   GET  /get-session    -> { session: { id, token, userId, ... }, user }
+ *   GET  /list-sessions  -> [ { id, token, ... } ]        (EVERY session of the user, not just this one)
+ *   POST /sign-in/*      -> { token, user, ... }
+ *   POST /sign-up/*      -> { token, user }
+ *   GET  /magic-link/verify (no callbackURL) -> { token, user }   (NightHawk G4 on PR 1190, measured on a real instance)
+ * and any plugin endpoint (passkey verify, two-factor verify, genericOAuth) answers a session object the same way.
+ * `token` is the Redis key of the session. The cookie is token.HMAC and Path B verifies the signature, so a bare
+ * token is not a replayable cookie (gate rows B1-B4 measure that), but it is a credential identifier readable by any
+ * script on the page, for this session and for every other session the user has. It breaks the PAY-1481 rule.
+ *
+ * EVERY 2xx JSON BODY IS STRIPPED, not a named list of paths. A list protects the endpoints someone remembered and
+ * silently misses the next plugin; the strip is a function of the response, so a new endpoint is covered the day it is
+ * mounted. A 2xx JSON body that legitimately needs one of these names to reach the browser would have to be
+ * allowlisted here on purpose (none is known: no client in this package reads one).
+ *
+ * WHERE THE FIX LIVES, AND WHY NOT customSession. Server-side code in this package reads session.session.token from
+ * auth.api.getSession() (viability, refresh, status, the OAuth exchange). A customSession plugin or an after-hook
+ * runs for those calls too and would strip the token from them. So the strip is applied at the HTTP BOUNDARY only:
+ * getBetterAuthHandler() returns handlers wrapped by wrapBetterAuthHandler(), and auth.api stays untouched.
+ *
+ * WHAT THE BROWSER GETS INSTEAD.
+ *   - list-sessions rows carry `isCurrent` (computed here against the caller's cookie-resolved session) and `id`.
+ *   - POST /revoke-session-by-id { id }: revokes ONE of the CALLER's sessions by its id. An id that is not one of the
+ *     caller's own sessions answers 404 (never 403: do not confirm that another user's session id exists).
+ *   - Better Auth's native POST /revoke-session { token } still exists and still requires a cookie-resolved session
+ *     that owns the token, but no browser ever holds a token to send it.
+ */
+/** Deep copy of `value` with every credential-named key removed, at any depth, in objects and arrays. */
+export declare function stripSessionCredentials(value: unknown): unknown;
+/** "/api/auth/get-session" -> "/get-session". Anything not under an /auth/ segment is returned as-is. */
+export declare function authSubPath(pathname: string): string;
+interface AuthApi {
+    getSession: (opts: {
+        headers: Headers;
+    }) => Promise<any>;
+    listSessions: (opts: {
+        headers: Headers;
+    }) => Promise<any>;
+    revokeSession: (opts: {
+        headers: Headers;
+        body: {
+            token: string;
+        };
+        asResponse?: boolean;
+    }) => Promise<any>;
+}
+/** Sanitise one already-produced Better Auth response. Pure function of (request, response, current token). */
+export declare function sanitizeBetterAuthResponse(req: Request, res: Response, currentToken: () => Promise<string | undefined>): Promise<Response>;
+type Handler = (req: Request) => Promise<Response>;
+/**
+ * Wrap Better Auth's Next.js handlers so no response carries a session credential to the browser.
+ * `auth` is the Better Auth instance; its `api` is used server-side only (to find the caller's current session and to
+ * revoke by id) and is not modified.
+ */
+export declare function wrapBetterAuthHandler(auth: {
+    api: AuthApi;
+}, handlers: {
+    GET: Handler;
+    POST: Handler;
+}): {
+    GET: Handler;
+    POST: Handler;
+};
+export {};

package/dist/auth/session-response-sanitizer.js

@@ -0,0 +1,136 @@
+"use strict";
+/**
+ * PAY-2217: no session token reaches browser JS from Better Auth's own HTTP endpoints.
+ *
+ * WHAT WAS WRONG. PAY-1481 removed token material from the package's own GET /api/auth/session. Better Auth's native
+ * endpoints are a separate surface served by the catch-all mount, and their default bodies carry the session
+ * credential identifier:
+ *   GET  /get-session    -> { session: { id, token, userId, ... }, user }
+ *   GET  /list-sessions  -> [ { id, token, ... } ]        (EVERY session of the user, not just this one)
+ *   POST /sign-in/*      -> { token, user, ... }
+ *   POST /sign-up/*      -> { token, user }
+ *   GET  /magic-link/verify (no callbackURL) -> { token, user }   (NightHawk G4 on PR 1190, measured on a real instance)
+ * and any plugin endpoint (passkey verify, two-factor verify, genericOAuth) answers a session object the same way.
+ * `token` is the Redis key of the session. The cookie is token.HMAC and Path B verifies the signature, so a bare
+ * token is not a replayable cookie (gate rows B1-B4 measure that), but it is a credential identifier readable by any
+ * script on the page, for this session and for every other session the user has. It breaks the PAY-1481 rule.
+ *
+ * EVERY 2xx JSON BODY IS STRIPPED, not a named list of paths. A list protects the endpoints someone remembered and
+ * silently misses the next plugin; the strip is a function of the response, so a new endpoint is covered the day it is
+ * mounted. A 2xx JSON body that legitimately needs one of these names to reach the browser would have to be
+ * allowlisted here on purpose (none is known: no client in this package reads one).
+ *
+ * WHERE THE FIX LIVES, AND WHY NOT customSession. Server-side code in this package reads session.session.token from
+ * auth.api.getSession() (viability, refresh, status, the OAuth exchange). A customSession plugin or an after-hook
+ * runs for those calls too and would strip the token from them. So the strip is applied at the HTTP BOUNDARY only:
+ * getBetterAuthHandler() returns handlers wrapped by wrapBetterAuthHandler(), and auth.api stays untouched.
+ *
+ * WHAT THE BROWSER GETS INSTEAD.
+ *   - list-sessions rows carry `isCurrent` (computed here against the caller's cookie-resolved session) and `id`.
+ *   - POST /revoke-session-by-id { id }: revokes ONE of the CALLER's sessions by its id. An id that is not one of the
+ *     caller's own sessions answers 404 (never 403: do not confirm that another user's session id exists).
+ *   - Better Auth's native POST /revoke-session { token } still exists and still requires a cookie-resolved session
+ *     that owns the token, but no browser ever holds a token to send it.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stripSessionCredentials = stripSessionCredentials;
+exports.authSubPath = authSubPath;
+exports.sanitizeBetterAuthResponse = sanitizeBetterAuthResponse;
+exports.wrapBetterAuthHandler = wrapBetterAuthHandler;
+/** Credential-bearing key names, compared case- and separator-insensitively. */
+const STRIP_KEYS = new Set(['token', 'sessiontoken', 'accesstoken', 'refreshtoken', 'idtoken']);
+const norm = (k) => k.toLowerCase().replace(/[_\-\s]/g, '');
+/** Deep copy of `value` with every credential-named key removed, at any depth, in objects and arrays. */
+function stripSessionCredentials(value) {
+    if (Array.isArray(value))
+        return value.map(stripSessionCredentials);
+    if (value !== null && typeof value === 'object') {
+        const out = {};
+        for (const [k, v] of Object.entries(value)) {
+            if (STRIP_KEYS.has(norm(k)))
+                continue;
+            out[k] = stripSessionCredentials(v);
+        }
+        return out;
+    }
+    return value;
+}
+/** "/api/auth/get-session" -> "/get-session". Anything not under an /auth/ segment is returned as-is. */
+function authSubPath(pathname) {
+    const i = pathname.indexOf('/api/auth/');
+    if (i >= 0)
+        return pathname.slice(i + '/api/auth'.length).replace(/\/+$/, '') || '/';
+    return pathname.replace(/\/+$/, '') || '/';
+}
+function isJson(res) {
+    return (res.headers.get('content-type') || '').toLowerCase().includes('application/json');
+}
+/** A Response with a new JSON body and the original status and headers (content-length recomputed by the runtime). */
+function withJsonBody(res, body) {
+    const headers = new Headers(res.headers);
+    headers.delete('content-length');
+    return new Response(JSON.stringify(body), { status: res.status, statusText: res.statusText, headers });
+}
+/** Sanitise one already-produced Better Auth response. Pure function of (request, response, current token). */
+async function sanitizeBetterAuthResponse(req, res, currentToken) {
+    const sub = authSubPath(new URL(req.url).pathname);
+    if (!res.ok || !isJson(res))
+        return res;
+    let body;
+    try {
+        body = await res.clone().json();
+    }
+    catch {
+        return res; // unreadable body: nothing to strip, and do not turn it into a different failure
+    }
+    if (sub === '/list-sessions' && Array.isArray(body)) {
+        const cur = await currentToken().catch(() => undefined);
+        body = body.map((row) => row && typeof row === 'object' ? { ...row, isCurrent: !!cur && row.token === cur } : row);
+    }
+    return withJsonBody(res, stripSessionCredentials(body));
+}
+const json = (status, body) => new Response(JSON.stringify(body), { status, headers: { 'content-type': 'application/json' } });
+/** POST /revoke-session-by-id { id }: revoke one of the caller's own sessions by id. */
+async function revokeById(req, api) {
+    let id;
+    try {
+        id = (await req.json())?.id;
+    }
+    catch {
+        return json(400, { code: 'INVALID_REQUEST', message: 'Body must be JSON { id }' });
+    }
+    if (typeof id !== 'string' || id.length === 0) {
+        return json(400, { code: 'INVALID_REQUEST', message: 'id is required' });
+    }
+    const headers = new Headers(req.headers);
+    const rows = await api.listSessions({ headers }).catch(() => null);
+    if (rows === null)
+        return json(401, { code: 'UNAUTHORIZED', message: 'No session' });
+    // listSessions returns ONLY the caller's own sessions, so a foreign id cannot match: 404, not 403.
+    const row = Array.isArray(rows) ? rows.find((r) => r && r.id === id && typeof r.token === 'string') : undefined;
+    if (!row)
+        return json(404, { code: 'SESSION_NOT_FOUND', message: 'No such session' });
+    const res = await api.revokeSession({ headers, body: { token: row.token }, asResponse: true });
+    // Pass Better Auth's own answer (and its Set-Cookie when the current session was the one revoked) through.
+    return res instanceof Response ? res : json(200, { status: true });
+}
+/**
+ * Wrap Better Auth's Next.js handlers so no response carries a session credential to the browser.
+ * `auth` is the Better Auth instance; its `api` is used server-side only (to find the caller's current session and to
+ * revoke by id) and is not modified.
+ */
+function wrapBetterAuthHandler(auth, handlers) {
+    const currentTokenFor = (req) => async () => {
+        const s = await auth.api.getSession({ headers: new Headers(req.headers) });
+        return s?.session?.token;
+    };
+    return {
+        GET: async (req) => sanitizeBetterAuthResponse(req, await handlers.GET(req), currentTokenFor(req)),
+        POST: async (req) => {
+            const sub = authSubPath(new URL(req.url).pathname);
+            if (sub === '/revoke-session-by-id')
+                return revokeById(req, auth.api);
+            return sanitizeBetterAuthResponse(req, await handlers.POST(req), currentTokenFor(req));
+        },
+    };
+}

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

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/dist/stores/authStore.js

@@ -425,25 +425,12 @@ exports.useAuthStore = (0, zustand_1.create)()((0, middleware_1.devtools)((set,
         try {
             // COORDINATED REFRESH: The server now handles distributed locking
             // We just need to make the refresh call and let the server coordinate
-            // Resolve session token for header
-            const resolveSessionTokenForHeader = async () => {
-                let token = get().session?.sessionToken;
-                if (token)
-                    return token;
-                try {
-                    for (let attempt = 1; attempt <= 3 && !token; attempt++) {
-                        const { data: s } = await better_auth_client_1.authClient.getSession();
-                        token = s?.sessionToken;
-                        if (!token) {
-                            await new Promise(r => setTimeout(r, 150));
-                        }
-                    }
-                }
-                catch {
-                    logger_1.authLogger.warn('[AuthStore] Failed to resolve session token from Better Auth during refresh');
-                }
-                return token;
-            };
+            // PAY-2217: the session token is NOT read from Better Auth's getSession() any more. The HTTP body no
+            // longer carries it (wrapBetterAuthHandler), and this read was already dead: getSession() returns
+            // { session: { token } }, never a top-level `sessionToken`, so the 3 x 150 ms retry loop that used to sit
+            // here always ran to exhaustion. The server resolves the session from the cookie and REJECTS an
+            // x-session-token header when it cannot (refresh.ts, 246007), so the header is advisory at best.
+            const resolveSessionTokenForHeader = async () => get().session?.sessionToken;
             const sessionTokenHeader = await resolveSessionTokenForHeader();
             const refreshResponse = await fetch('/api/auth/refresh', {
                 method: 'POST',