@payez/next-mvp 4.5.4 → 4.5.6

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

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

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

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

package/src/auth/better-auth.ts

@@ -16,6 +16,7 @@ import { decodeJwt } from 'jose';   // better-auth's own JWT dependency
 import { betterAuth } from 'better-auth';
 import { nextCookies } from 'better-auth/next-js';
 import { toNextJsHandler } from 'better-auth/next-js';
+import { wrapBetterAuthHandler } from './session-response-sanitizer';
 import { magicLink, type MagicLinkOptions } from 'better-auth/plugins/magic-link';
 import { resolveClientKey } from '../lib/client-key';
 import { genericOAuth } from 'better-auth/plugins/generic-oauth';
@@ -996,7 +997,10 @@ export async function getBetterAuthHandler(): Promise<{ GET: (req: Request) => P
   if (!isBetterAuthEnabled()) return null;
 
   const auth = await getBetterAuthInstance();
-  return 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 wrapBetterAuthHandler(auth as any, toNextJsHandler(auth));
 }
 
 /**

package/src/auth/session-response-sanitizer.ts

@@ -0,0 +1,151 @@
+/**
+ * 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.
+ */
+
+/** Credential-bearing key names, compared case- and separator-insensitively. */
+const STRIP_KEYS = new Set(['token', 'sessiontoken', 'accesstoken', 'refreshtoken', 'idtoken']);
+
+const norm = (k: string): string => k.toLowerCase().replace(/[_\-\s]/g, '');
+
+/** Deep copy of `value` with every credential-named key removed, at any depth, in objects and arrays. */
+export function stripSessionCredentials(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(stripSessionCredentials);
+  if (value !== null && typeof value === 'object') {
+    const out: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+      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. */
+export function authSubPath(pathname: string): string {
+  const i = pathname.indexOf('/api/auth/');
+  if (i >= 0) return pathname.slice(i + '/api/auth'.length).replace(/\/+$/, '') || '/';
+  return pathname.replace(/\/+$/, '') || '/';
+}
+
+function isJson(res: Response): boolean {
+  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: Response, body: unknown): Response {
+  const headers = new Headers(res.headers);
+  headers.delete('content-length');
+  return new Response(JSON.stringify(body), { status: res.status, statusText: res.statusText, headers });
+}
+
+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 async function sanitizeBetterAuthResponse(
+  req: Request,
+  res: Response,
+  currentToken: () => Promise<string | undefined>,
+): Promise<Response> {
+  const sub = authSubPath(new URL(req.url).pathname);
+  if (!res.ok || !isJson(res)) return res;
+
+  let body: unknown;
+  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: any) =>
+      row && typeof row === 'object' ? { ...row, isCurrent: !!cur && row.token === cur } : row,
+    );
+  }
+  return withJsonBody(res, stripSessionCredentials(body));
+}
+
+const json = (status: number, body: unknown): Response =>
+  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: Request, api: AuthApi): Promise<Response> {
+  let id: unknown;
+  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: any) => 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 });
+}
+
+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 function wrapBetterAuthHandler(
+  auth: { api: AuthApi },
+  handlers: { GET: Handler; POST: Handler },
+): { GET: Handler; POST: Handler } {
+  const currentTokenFor = (req: Request) => async (): Promise<string | undefined> => {
+    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/src/routes/auth/viability.ts

@@ -15,7 +15,7 @@
  */
 
 import { NextRequest, NextResponse } from 'next/server';
-import { getSession as getBetterAuthSession } from '../../server/auth';
+import { resolveSessionState } from '../../server/auth';
 import {
   getSession as getRedisSession,
   getBetterAuthSession as getBetterAuthRedisSession,
@@ -142,9 +142,40 @@ function resolveClientId(sessionClientId: string | undefined): string | null {
  */
 export async function GET(req: NextRequest) {
   try {
-    const baSession = await getBetterAuthSession(req);
+    // 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 resolveSessionState(req);
 
-    if (!baSession) {
+    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 NextResponse.json({
+        viable: false,
+        needsRefresh: false,
+        authenticated: false,
+        revocationStatus: 'unknown' as RevocationStatus,
+        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 NextResponse.json({
+        viable: false,
+        needsRefresh: false,
+        authenticated: false,
+        sessionTokenId: 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 NextResponse.json({
         viable: false,
         needsRefresh: false,
@@ -153,6 +184,8 @@ export async function GET(req: NextRequest) {
       });
     }
 
+    const baSession = sessionState.session;
+
     const token = baSession as any;
     const sessionToken = baSession.session?.token;
 

package/src/server/auth.ts

@@ -221,17 +221,60 @@ function logNoSessionWithKeys(origin: 'b' | 'c', sessionToken: string): void {
  *   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 async function getSession(request?: Request): Promise<any> {
+  const state = await resolveSessionState(request);
+  return state.state === 'live' ? state.session : null;
+}
+
+/**
+ * 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 async function resolveSessionState(request?: Request): Promise<SessionState> {
   const auth = await getAuthInstance();
-  if (!request) return null;
+  if (!request) 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: any = 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
   }
 
@@ -245,7 +288,7 @@ export async function getSession(request?: Request): Promise<any> {
       logSessionReadSwallowed('A', err); // Redis unavailable
     }
     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
@@ -260,16 +303,21 @@ export async function getSession(request?: Request): Promise<any> {
   // 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 resolveVerifiedSessionTokenFromRequest(request);
-  if (!sessionToken) return null;
+  // 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 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: SessionData | null = null;
   try {
     sessionData = await getRedisSession(sessionToken);
     if (!sessionData) sessionData = await getBetterAuthRedisSession(sessionToken);
   } catch (err) {
     logSessionReadSwallowed('B', err); // Redis unavailable
+    return { state: 'unknown' };
   }
-  if (!sessionData) return null;
+  if (!sessionData) return { state: 'missing', sessionToken };
 
   // Synthesize a minimal session shape compatible with downstream callers.
   // The `session.token` field is what `getFreshIdpToken` and other callers
@@ -283,7 +331,7 @@ export async function getSession(request?: Request): Promise<any> {
       roles: sessionData.roles,
     },
   };
-  return attachSessionData(synthetic, sessionData, sessionToken);
+  return { state: 'live', session: attachSessionData(synthetic, sessionData, sessionToken) };
 }
 
 /**

package/src/stores/authStore.ts

@@ -637,23 +637,13 @@ export const useAuthStore = create<AuthStore>()(
           // 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 (): Promise<string | undefined> => {
-            let token = get().session?.sessionToken as string | undefined;
-            if (token) return token;
-            try {
-              for (let attempt = 1; attempt <= 3 && !token; attempt++) {
-                const { data: s } = await authClient.getSession();
-                token = (s as any)?.sessionToken;
-                if (!token) {
-                  await new Promise(r => setTimeout(r, 150));
-                }
-              }
-            } catch {
-              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 (): Promise<string | undefined> =>
+            get().session?.sessionToken as string | undefined;
 
           const sessionTokenHeader = await resolveSessionTokenForHeader();