@payez/next-mvp 4.5.5 → 4.5.7

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

@@ -0,0 +1,37 @@
+/**
+ * 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';
+import { isPrefetchRequest } from '../../middleware/create-middleware';
+import { expireSessionCookies } from '../../auth/session-cookie-clear';
+import { getSessionCookieName, getSecureSessionCookieName } from '../../lib/app-slug';
+import { boundSessionCookie, loginLocation, readResetRequest, resetSecret } from '../../auth/session-reset-link';
+
+export const dynamic = 'force-dynamic';
+
+export async function GET(request: NextRequest): Promise<NextResponse> {
+  if (isPrefetchRequest(request)) {
+    return new NextResponse(null, { status: 204, headers: { 'cache-control': 'no-store' } });
+  }
+  const bound = boundSessionCookie((n) => request.cookies.get(n)?.value, getSessionCookieName(), getSecureSessionCookieName());
+  const { params, signed } = await readResetRequest(request.nextUrl.searchParams, resetSecret(), bound);
+  const response = NextResponse.redirect(new URL(loginLocation(params), request.url), 307);
+  response.headers.set('cache-control', 'no-store');
+  if (signed) expireSessionCookies(response, Array.from(request.cookies, ([name]) => name));
+  return response;
+}

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) };
 }
 
 /**