@payez/next-mvp 4.5.0 → 4.5.1

package/dist/vibe/sessions.js

@@ -46,10 +46,14 @@ exports.hashSessionToken = hashSessionToken;
 exports.resolveNumericIdpUserId = resolveNumericIdpUserId;
 exports.warnNonNumericUserId = warnNonNumericUserId;
 exports.readSessionRevocationHmac = readSessionRevocationHmac;
-exports.getRevocationStatus = getRevocationStatus;
+exports.isConcurrentLimitBody = isConcurrentLimitBody;
+exports.revocationRetryDelayMs = revocationRetryDelayMs;
 exports.getSessionStats = getSessionStats;
+exports.resetRevocationCache = resetRevocationCache;
+exports.getRevocationStatus = getRevocationStatus;
 const crypto_1 = __importDefault(require("crypto"));
 const token_utils_1 = require("../auth/utils/token-utils");
+const token_log_id_1 = require("../lib/token-log-id");
 // -----------------------------------------------------------------------------
 // CONFIGURATION
 // -----------------------------------------------------------------------------
@@ -457,21 +461,22 @@ async function readSessionRevocationHmac(idpUserId) {
     const signingKey = getEnv('VIBE_HMAC_KEY');
     if (!idpUrl || !clientId || !signingKey) {
         // Caller distinguishes this from a read failure; report ok:false, not [].
-        return { ok: false, sessions: [] };
+        return { ok: false, sessions: [], failure: 'misconfigured' };
     }
     const endpoint = `/v1/collections/${COLLECTION}/tables/${TABLE}/query`;
     const proxyUrl = `${idpUrl}/api/vibe/proxy`;
-    const timestamp = Math.floor(Date.now() / 1000);
-    const signature = generateHmacSignature(signingKey, timestamp, 'POST', endpoint);
-    // NOTE the absence of Authorization. This is the twin's credential.
-    const headers = {
-        'Content-Type': 'application/json',
-        'X-Vibe-Client-Id': clientId,
-        'X-Vibe-Timestamp': String(timestamp),
-        'X-Vibe-Signature': signature,
-    };
-    try {
-        const response = await fetch(proxyUrl, {
+    // Signed per ATTEMPT: the retry below must not reuse a timestamp that has aged.
+    const send = () => {
+        const timestamp = Math.floor(Date.now() / 1000);
+        const signature = generateHmacSignature(signingKey, timestamp, 'POST', endpoint);
+        // NOTE the absence of Authorization. This is the twin's credential.
+        const headers = {
+            'Content-Type': 'application/json',
+            'X-Vibe-Client-Id': clientId,
+            'X-Vibe-Timestamp': String(timestamp),
+            'X-Vibe-Signature': signature,
+        };
+        return fetch(proxyUrl, {
             method: 'POST',
             headers,
             body: JSON.stringify({
@@ -485,10 +490,21 @@ async function readSessionRevocationHmac(idpUserId) {
                 },
             }),
         });
+    };
+    try {
+        let response = await send();
+        // PAY-2136: ONE retry, and only for the transient class. The portal's own prefetch burst exceeds the free
+        // tier's concurrency (CONCURRENT_LIMIT, HTTP 429). Keyed on the BODY code, never on Retry-After: the IdP proxy
+        // relays body and status but drops that header (PAY-2143). AUTH_BLOCKED / other 429s and every 5xx are NOT
+        // retried (a block is not transient; a retry only adds a counted failure).
+        if (response.status === 429 && isConcurrentLimitBody(await safeBodyText(response))) {
+            await new Promise((resolve) => setTimeout(resolve, revocationRetryDelayMs(response)));
+            response = await send();
+        }
         if (!response.ok) {
             // PAY-1427: never the raw proxy body - an error page can echo the request.
             console.error(`[vibe-sessions] Revocation read proxy error ${response.status}`);
-            return { ok: false, sessions: [] };
+            return { ok: false, sessions: [], failure: String(response.status) }; // PAY-2136: status only, for the reason log
         }
         const data = await response.json();
         const unwrapped = (data?.data ?? data);
@@ -496,8 +512,38 @@ async function readSessionRevocationHmac(idpUserId) {
     }
     catch (error) {
         console.error('[vibe-sessions] Revocation read failed:', error);
-        return { ok: false, sessions: [] };
+        return { ok: false, sessions: [], failure: 'exception' };
+    }
+}
+/** Body text of a response WITHOUT consuming the caller's copy; '' on any failure. */
+async function safeBodyText(response) {
+    try {
+        return await response.clone().text();
+    }
+    catch {
+        return '';
+    }
+}
+/** True only for the exact code CONCURRENT_LIMIT (nested error.code, top-level code/errorCode); a non-JSON body falls back to the literal. */
+function isConcurrentLimitBody(bodyText) {
+    try {
+        const b = JSON.parse(bodyText);
+        const nested = b?.error?.code;
+        const code = [nested, b?.code, b?.errorCode].find((c) => typeof c === 'string');
+        if (typeof code === 'string')
+            return code === 'CONCURRENT_LIMIT';
+        return false;
     }
+    catch {
+        return /CONCURRENT_LIMIT/.test(bodyText);
+    }
+}
+/** Retry-After seconds when the proxy kept it (capped at 2 s: this runs in the request path), else 200-400 ms jitter. */
+function revocationRetryDelayMs(response) {
+    const ra = Number(response.headers?.get?.('retry-after'));
+    if (Number.isFinite(ra) && ra > 0)
+        return Math.min(ra * 1000, 2000);
+    return 200 + Math.floor(Math.random() * 200);
 }
 /**
  * THE one revocation decision (PAY-2037 step 1, BAPert 69150): hash-first, per session.
@@ -509,12 +555,15 @@ async function readSessionRevocationHmac(idpUserId) {
  * rule apply: no active row -> the most recently revoked (none revoked: not revoked); else any revoked inside 2h.
  */
 function findRevokingSession(sessions, sessionTokenHash) {
+    return findRevokingSessionWithRule(sessions, sessionTokenHash).row;
+}
+function findRevokingSessionWithRule(sessions, sessionTokenHash) {
     if (sessions.length === 0)
-        return null;
+        return { row: null, rule: 'none' };
     if (sessionTokenHash) {
         const matching = sessions.find(s => s.session_token_hash === sessionTokenHash);
         if (matching)
-            return matching.status === 'revoked' ? matching : null;
+            return matching.status === 'revoked' ? { row: matching, rule: 'own_row_revoked' } : { row: null, rule: 'none' };
     }
     // Hash not found (a legacy row minted before hashing) or no hash given: idealresume's user-wide
     // rules, lib/vibe-sessions.ts:594-651 (BAPert 69189).
@@ -525,11 +574,30 @@ function findRevokingSession(sessions, sessionTokenHash) {
     if (!sessions.some(s => s.status === 'active')) {
         const revoked = sessions.filter(s => s.status === 'revoked' && s.revoked_at).sort(newestFirst);
         if (revoked.length > 0)
-            return revoked[0];
+            return { row: revoked[0], rule: 'legacy_no_active' };
     }
     // Check 2: any row revoked in the last TWO hours (idealresume's window; 5-minute polling needs the time).
     const twoHoursAgo = Date.now() - 2 * 60 * 60 * 1000;
-    return (sessions.filter(s => s.status === 'revoked' && revokedAt(s) > twoHoursAgo).sort(newestFirst)[0] ?? null);
+    const recent = sessions.filter(s => s.status === 'revoked' && revokedAt(s) > twoHoursAgo).sort(newestFirst)[0] ?? null;
+    return recent ? { row: recent, rule: 'legacy_recent_2h' } : { row: null, rule: 'none' };
+}
+/**
+ * PAY-2136: one shape-only line per NON-viable revocation verdict, naming WHICH rule fired. Never a token, userId,
+ * hash, or row content: the rule label, a read-failure status code, a row COUNT and the session's tokenLogId.
+ * Must never throw into the viability path.
+ */
+function logRevocationReason(verdict, reason, sessionToken, extra = {}) {
+    try {
+        console.warn('[REVOCATION] verdict', {
+            verdict,
+            reason,
+            sessionTokenId: sessionToken ? (0, token_log_id_1.tokenLogId)(sessionToken) : null,
+            ...extra,
+        });
+    }
+    catch {
+        /* diagnostic only */
+    }
 }
 /**
  * Determine whether a session is revoked, with an explicit UNKNOWN state
@@ -552,7 +620,7 @@ function findRevokingSession(sessions, sessionTokenHash) {
  * @param sessionToken - The live session token; hashed to match the stored row.
  *                       When absent, the user-wide check applies (legacy path).
  */
-async function getRevocationStatus(idpUserId, sessionToken) {
+async function readRevocationStatus(idpUserId, sessionToken) {
     const idpUrl = getEnv('IDP_URL');
     const clientId = getEnv('VIBE_CLIENT_ID');
     const signingKey = getEnv('VIBE_HMAC_KEY');
@@ -573,16 +641,21 @@ async function getRevocationStatus(idpUserId, sessionToken) {
     // do NOT report "no sessions". 'unknown' is the fail-closed state.
     if (!idpUrl || !signingKey) {
         console.warn('[vibe-sessions] Revocation check MISCONFIGURED (VIBE_CLIENT_ID set but IDP_URL/VIBE_HMAC_KEY missing) - reporting unknown (fail closed)');
+        logRevocationReason('unknown', 'misconfigured', sessionToken);
         return 'unknown';
     }
-    const { ok, sessions } = await readSessionRevocationHmac(idpUserId);
+    const { ok, sessions, failure } = await readSessionRevocationHmac(idpUserId);
     if (!ok) {
         console.warn('[vibe-sessions] Revocation read failed - reporting unknown');
+        logRevocationReason('unknown', `read_failed:${failure ?? 'unknown'}`, sessionToken);
         return 'unknown';
     }
-    return findRevokingSession(sessions, sessionToken ? hashSessionToken(sessionToken) : undefined)
-        ? 'revoked'
-        : 'active';
+    const { row, rule } = findRevokingSessionWithRule(sessions, sessionToken ? hashSessionToken(sessionToken) : undefined);
+    if (row) {
+        logRevocationReason('revoked', rule, sessionToken, { rows: sessions.length });
+        return 'revoked';
+    }
+    return 'active';
 }
 // -----------------------------------------------------------------------------
 // STATISTICS
@@ -631,3 +704,65 @@ async function getSessionStats(accessToken) {
         recentLogins: stats.recentLogins,
     };
 }
+// -----------------------------------------------------------------------------
+// PAY-2136: SINGLE-FLIGHT + SHORT RESULT CACHE for the revocation read
+// -----------------------------------------------------------------------------
+// Every middleware viability check does one revocation read through the IdP proxy for the SAME Vibe client. A page
+// whose chrome prefetches ~4 links makes ~8 checks inside a second; the free tier allows 2 concurrent queries, so
+// the 3rd+ read was a 429 CONCURRENT_LIMIT and (before this change) signed the user out. Now concurrent callers for
+// ONE session share ONE in-flight read, and a CONFIRMED verdict is reused for a few seconds.
+//   - keyed by userId + the token HASH: never shared across sessions or users;
+//   - only 'active' / 'revoked' are cached: a failure ('unknown') is shared while in flight but never remembered, so
+//     the next request reads again; a revoked session is honoured at most REVOCATION_CACHE_MS late;
+//   - REVOCATION_CACHE_MS=0 disables the cache (single-flight still applies).
+const DEFAULT_REVOCATION_CACHE_MS = 5000;
+const MAX_REVOCATION_CACHE_ENTRIES = 2000;
+const revocationInflight = new Map();
+const revocationVerdicts = new Map();
+function revocationCacheMs() {
+    const raw = process.env.REVOCATION_CACHE_MS;
+    if (raw === undefined || raw === '')
+        return DEFAULT_REVOCATION_CACHE_MS;
+    const n = Number(raw);
+    return Number.isFinite(n) && n >= 0 ? Math.min(n, 30_000) : DEFAULT_REVOCATION_CACHE_MS;
+}
+/** Test/ops hook: forget every cached verdict and in-flight read. */
+function resetRevocationCache() {
+    revocationInflight.clear();
+    revocationVerdicts.clear();
+}
+async function getRevocationStatus(idpUserId, sessionToken) {
+    // No token = the user-wide legacy path: nothing session-specific to key on, so no sharing.
+    if (!sessionToken)
+        return readRevocationStatus(idpUserId, sessionToken);
+    const key = `${idpUserId}:${hashSessionToken(sessionToken)}`;
+    const ttl = revocationCacheMs();
+    const now = Date.now();
+    const hit = revocationVerdicts.get(key);
+    if (hit && ttl > 0 && now - hit.at < ttl)
+        return hit.status;
+    if (hit)
+        revocationVerdicts.delete(key);
+    const existing = revocationInflight.get(key);
+    if (existing)
+        return existing;
+    const read = readRevocationStatus(idpUserId, sessionToken)
+        .then((status) => {
+        if (ttl > 0 && (status === 'active' || status === 'revoked')) {
+            if (revocationVerdicts.size >= MAX_REVOCATION_CACHE_ENTRIES) {
+                for (const [k, v] of revocationVerdicts)
+                    if (now - v.at >= ttl)
+                        revocationVerdicts.delete(k);
+                if (revocationVerdicts.size >= MAX_REVOCATION_CACHE_ENTRIES)
+                    revocationVerdicts.clear();
+            }
+            revocationVerdicts.set(key, { status, at: Date.now() });
+        }
+        return status;
+    })
+        .finally(() => {
+        revocationInflight.delete(key);
+    });
+    revocationInflight.set(key, read);
+    return read;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@payez/next-mvp",
-  "version": "4.5.0",
+  "version": "4.5.1",
   "sideEffects": false,
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/auth/auth-decision.ts

@@ -26,6 +26,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;
 }
 
 // Output types for the decision engine
@@ -35,9 +37,20 @@ export type AuthAction =
   | { type: 'service_error'; 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.
  */
 export function makeAuthDecision(context: AuthContext): AuthAction {
+  const action = decide(context);
+  if (context.isPrefetch && action.type === 'redirect' && action.clearCookies) {
+    const { clearCookies: _dropped, ...rest } = action;
+    return rest;
+  }
+  return action;
+}
+
+function decide(context: AuthContext): AuthAction {
   const {
     pathname,
     isPublicRoute,

package/src/edge/middleware.ts

@@ -16,7 +16,7 @@ export {
   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,

package/src/index.ts

@@ -27,7 +27,7 @@ export { isUnauthenticatedRoute, configurePublicRoutes, getRouteConfig } from '.
 // The ONE callback-target guard (N7 / PAY-1989): apps import this instead of
 // copying it. Exposed from the main index AND as the subpath ./auth/safe-callback.
 export { safeCallbackPath, isSafeCallbackPath, resolveCallbackDestination, DEFAULT_CALLBACK } from './auth/safe-callback';
-export { createMvpMiddleware } from './middleware/create-middleware';
+export { createMvpMiddleware, isPrefetchRequest } from './middleware/create-middleware';
 
 // Account Components
 export { UserAvatarMenu, MobileNavDrawer } from './components/account';

package/src/lib/session-store.ts

@@ -1048,3 +1048,45 @@ export async function cleanupRefreshLocks(): Promise<number> {
   console.warn('[SESSION-STORE] cleanupRefreshLocks called - scanning for expired locks');
   return 0;
 }
+
+/**
+ * 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 async function describeSessionKeyPresence(
+  sessionToken: string
+): Promise<{ prefix: string; canonical: KeyPresence; ba: KeyPresence; ver: KeyPresence }> {
+  const ask = async (key: string): Promise<KeyPresence> => {
+    try {
+      return (await redis.exists(key)) > 0;
+    } catch {
+      return 'error';
+    }
+  };
+  let prefix = '';
+  try {
+    prefix = 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, 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/src/middleware/create-middleware.ts

@@ -197,8 +197,30 @@ function getSafeCallbackUrl(pathname: string, searchParams?: URLSearchParams): s
   return 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.
+ */
+export function isPrefetchRequest(request: NextRequest): boolean {
+  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: NextResponse, request: NextRequest): void {
+  if (isPrefetchRequest(request)) return;
   const sessionCookie = getSessionCookieName();
   const secureCookie = getSecureSessionCookieName();
 
@@ -736,6 +758,9 @@ async function executeDecision(
       return 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 NextResponse.next();
       return handleRefresh(request, safeCallback, opts);
   }
 }

package/src/server/auth.ts

@@ -10,8 +10,10 @@ import { getBetterAuthInstance } from '../auth/better-auth';
 import {
   getSession as getRedisSession,
   getBetterAuthSession as getBetterAuthRedisSession,
+  describeSessionKeyPresence,
   type SessionData,
 } from '../lib/session-store';
+import { tokenLogId } from '../lib/token-log-id';
 import { resolveVerifiedSessionTokenFromRequest } from './verified-session-token';
 
 export type IdpTokenResult =
@@ -125,6 +127,82 @@ export async function getAuthInstance() {
 }
 
 
+/* ----------------------------------------------------------------------------------------------------------------
+ * 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: unknown): string {
+  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: 'primary' | 'A' | 'B', err: unknown): void {
+  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: Request | undefined): void {
+  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: 'b' | 'c', sessionToken: string): void {
+  try {
+    void describeSessionKeyPresence(sessionToken).then(
+      (keys) => {
+        try {
+          console.warn(`[server-auth] NO_SESSION origin=${origin}`, { token: tokenLogId(sessionToken), ...keys });
+        } catch {
+          /* never throws */
+        }
+      },
+      () => {
+        /* never throws */
+      }
+    );
+  } catch {
+    /* a diagnostic must never change the outcome */
+  }
+}
+
 /**
  * Get the current session from a request.
  *
@@ -153,7 +231,9 @@ export async function getSession(request?: Request): Promise<any> {
   let betterAuthSession: any = null;
   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 as string;
@@ -161,7 +241,9 @@ export async function getSession(request?: Request): Promise<any> {
     try {
       sessionData = await getRedisSession(sessionToken);
       if (!sessionData) sessionData = await getBetterAuthRedisSession(sessionToken);
-    } catch { /* Redis unavailable */ }
+    } catch (err) {
+      logSessionReadSwallowed('A', err); // Redis unavailable
+    }
     if (!sessionData) sessionData = buildSessionDataFromAuthSession(betterAuthSession);
     return attachSessionData(betterAuthSession, sessionData, sessionToken);
   }
@@ -184,7 +266,9 @@ export async function getSession(request?: Request): Promise<any> {
   try {
     sessionData = await getRedisSession(sessionToken);
     if (!sessionData) sessionData = await getBetterAuthRedisSession(sessionToken);
-  } catch { /* Redis unavailable */ }
+  } catch (err) {
+    logSessionReadSwallowed('B', err); // Redis unavailable
+  }
   if (!sessionData) return null;
 
   // Synthesize a minimal session shape compatible with downstream callers.
@@ -296,6 +380,7 @@ export async function getFreshIdpToken(
   const session = await getSession(request);
   const sessionToken = session?.session?.token as string | undefined;
   if (!sessionToken) {
+    logNoSessionOriginA(request);
     return { success: false, error: 'NO_SESSION', status: 401, terminal: true };
   }
 
@@ -314,6 +399,7 @@ export async function getFreshIdpToken(
   );
 
   if (!result.ok) {
+    if (result.code === 'NO_SESSION') logNoSessionWithKeys('b', sessionToken);
     return {
       success: false,
       error: result.code,
@@ -327,6 +413,7 @@ export async function getFreshIdpToken(
 
   const sessionData = await getRedisSession(sessionToken);
   if (!sessionData) {
+    logNoSessionWithKeys('c', sessionToken);
     return { success: false, error: 'NO_SESSION', status: 401, terminal: true };
   }