@payez/next-mvp 4.8.1 → 4.8.2

package/src/server/auth.ts

@@ -1,486 +1,486 @@
-/**
- * Server-side auth utilities for Better Auth.
- *
- * All server-side auth flows go through the Better Auth instance returned by
- * getAuthInstance(); use getSession(req) for the request-scoped session.
- */
-
-import 'server-only';
-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 =
-  | { success: true; accessToken: string; sessionData: SessionData }
-  | { success: false; error: 'NO_SESSION'; terminal: true }
-  // Card 187871: a Better Auth session can exist with NO idpAccessToken yet
-  // because 2FA is required and not yet completed - the IDP never issued the
-  // full token. That is a RECOVERABLE state (route to 2FA), not a dead
-  // session. Only collapse it to NO_TOKEN/terminal when the session itself
-  // already claims 2FA is done (sessionData.mfaVerified === true) and there is
-  // still no token - that combination is genuinely broken.
-  | { success: false; error: 'NO_TOKEN'; terminal: true }
-  | { success: false; error: 'NO_TOKEN_PENDING_2FA'; terminal: false; sessionData: SessionData };
-
-function buildSessionDataFromAuthSession(session: any): SessionData | null {
-  const user = session?.user;
-  if (!user?.id && !user?.email) {
-    return null;
-  }
-
-  const expiresAt = session?.session?.expiresAt
-    ? new Date(session.session.expiresAt).getTime()
-    : Date.now() + 24 * 60 * 60 * 1000;
-
-  return {
-    userId: user.userId || user.id || '',
-    email: user.email || '',
-    name: user.name || undefined,
-    image: user.image || undefined,
-    roles: Array.isArray(user.roles) ? user.roles : [],
-    idpAccessToken: user.idpAccessToken,
-    idpRefreshToken: user.idpRefreshToken,
-    idpAccessTokenExpires: user.idpAccessTokenExpires || expiresAt,
-    mfaVerified: user.mfaVerified ?? user.twoFactorSessionVerified ?? false,
-    oauthProvider: user.oauthProvider,
-    idpClientId: user.idpClientId,
-    merchantId: user.merchantId,
-  };
-}
-
-function attachSessionData(session: any, sessionData: SessionData | null, sessionToken?: string) {
-  if (!sessionData) {
-    return session;
-  }
-
-  const enrichedSessionData = {
-    ...sessionData,
-    ...(sessionToken ? { sessionToken } : {}),
-  };
-
-  (session as any).sessionData = enrichedSessionData;
-
-  if (session?.user) {
-    const user = session.user as any;
-    user.userId = enrichedSessionData.userId || user.userId;
-    user.email = enrichedSessionData.email || user.email;
-    user.name = enrichedSessionData.name || user.name;
-    user.image = enrichedSessionData.image || user.image;
-    user.roles = enrichedSessionData.roles || user.roles || [];
-    user.idpAccessToken = enrichedSessionData.idpAccessToken;
-    user.idpRefreshToken = enrichedSessionData.idpRefreshToken;
-    user.idpAccessTokenExpires = enrichedSessionData.idpAccessTokenExpires;
-    user.mfaVerified = enrichedSessionData.mfaVerified;
-    user.twoFactorSessionVerified =
-      enrichedSessionData.mfaVerified ?? user.twoFactorSessionVerified;
-    user.oauthProvider = enrichedSessionData.oauthProvider || user.oauthProvider;
-    user.idpClientId = enrichedSessionData.idpClientId || user.idpClientId;
-    user.merchantId = enrichedSessionData.merchantId || user.merchantId;
-  }
-
-  return session;
-}
-
-/**
- * Get the initialized Better Auth instance (singleton).
- *
- * 244549: the single-flight memoisation lives in lib/single-flight.ts rather
- * than inline here, and that placement is deliberate rather than tidiness.
- * The bug being fixed -- a REJECTED init promise cached for the life of the
- * process, so recovery was restart-only -- went unnoticed precisely because
- * this module cannot be loaded in a unit test: importing it pulls in
- * better-auth and the whole IDP config stack. Extracted into a zero-import
- * module, the retry semantics are covered by
- * test/single-flight-retry.test.cjs, which imports dist/ and therefore
- * exercises the artefact that actually ships.
- *
- * PAY-1623 (package half, BAPert 62449): THIS FUNNEL NO LONGER BUILDS ITS OWN
- * INSTANCE. It used to call `createBetterAuthInstance(config)` with no opts, so
- * it carried NONE of the app-supplied plugins registered by the host app at
- * startup (`configureBetterAuth()` -> `state.configuredOpts`). `samlAcs()` and
- * `passkeySignIn()` arrive only that way, so `getAuthInstance()` returned an
- * instance on which `auth.api.samlAcs` was `undefined` — the exact package twin
- * of the portal ACS crash `t.api.samlAcs is not a function` (Jon's walk,
- * 2026-09-21; Portal PR 517 fixed the portal by importing the CONFIGURED
- * instance, `getBetterAuthInstance`, which is why this file must now resolve the
- * same one). It also silently created a SECOND, divergent instance beside the
- * one every /api/auth/* route uses — two instances, two secrets, one process.
- *
- * It now DELEGATES to that configured funnel, which is the single source of
- * truth for the process's Better Auth instance:
- *   - it carries `state.configuredOpts` (better-auth.ts:930), so the app
- *     plugins are present;
- *   - its init is already single-flighted with the retry semantics described in
- *     lib/single-flight.ts (see getBetterAuthInstance, card 244549/338215), so
- *     this function keeps the same no-latch recovery contract;
- *   - there is now ONE instance, so the double-init / divergent-secret hazard
- *     this path used to create is gone by construction.
- */
-export async function getAuthInstance() {
-  return getBetterAuthInstance();
-}
-
-
-/* ----------------------------------------------------------------------------------------------------------------
- * PAY-2136 DIAGNOSTICS (BAPert 70873, Nextpert-Scout 70872/70875) - LOG ONLY, NO BEHAVIOUR CHANGE.
- *
- * A getFreshIdpToken NO_SESSION used to carry no origin: three different returns produced the same
- * `{error:'NO_SESSION'}`, and getSession() swallowed every Redis error into a bare `catch {}`. These helpers name
- * the origin and make a swallowed read audible. Hard rules: every helper is wrapped so it can NEVER throw or change
- * a return value; nothing here ever logs a token, a cookie VALUE or a Redis value - only a tokenLogId() fingerprint,
- * cookie NAMES, booleans, and an error name/message with any long opaque run redacted.
- * -------------------------------------------------------------------------------------------------------------- */
-
-/** An error name/message, first 80 chars, with any 24+ char opaque run (a token, a key) replaced. */
-function scrubForLog(v: 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.
- *
- * Source-of-truth contract: **Redis is canonical for liveness.** Better Auth's
- * cookie+cache layer is treated as a SESSION POINTER (it owns the signed-cookie
- * secret and the canonical cookie parse) but does NOT decide whether a session
- * is alive. If Better Auth's primary path returns null or a partial session
- * (cookie cache miss, secondary storage eviction, token rotation), we fall
- * back to manually extracting the session-token claim from the cookie and
- * querying the canonical Redis store directly.
- *
- * This closes the asymmetric early-exit that caused contradictory answers
- * within milliseconds in production traces:
- *   GET /api/session/viability    → 200 (Redis: alive)
- *   GET /api/session/idp-token    → 200 (Redis: alive)
- *   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 { 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
-  }
-
-  if (betterAuthSession?.session?.token && betterAuthSession?.user) {
-    const sessionToken = betterAuthSession.session.token as string;
-    let sessionData: SessionData | null = null;
-    try {
-      sessionData = await getRedisSession(sessionToken);
-      if (!sessionData) sessionData = await getBetterAuthRedisSession(sessionToken);
-    } catch (err) {
-      logSessionReadSwallowed('A', err); // Redis unavailable
-    }
-    if (!sessionData) sessionData = buildSessionDataFromAuthSession(betterAuthSession);
-    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
-  // canonical app session at `{slug}:{token}` is still alive but Better
-  // Auth's `ba:{slug}:{token}` secondary record was evicted or the
-  // in-memory cookie cache returned stale-null.
-  //
-  // PAY-1476: this path used to take the token with NO signature check, on the
-  // theory that "Redis lookup is the validation". It is not: a leaked token has
-  // a live record, so the token string alone authenticated, with any garbage in
-  // 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);
-  // 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 { 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
-  // populated here even though Better Auth didn't give us a full session.
-  const synthetic = {
-    session: { token: sessionToken },
-    user: {
-      id: sessionData.userId,
-      email: sessionData.email,
-      roles: sessionData.roles,
-    },
-  };
-  return { state: 'live', session: attachSessionData(synthetic, sessionData, sessionToken) };
-}
-
-/**
- * Get normalized session data for the current request.
- *
- * This prefers the app's Redis session because it carries the canonical
- * IDP token, roles, and tenant-specific user identity used by app routes.
- */
-export async function getSessionData(request?: Request): Promise<SessionData | null> {
-  const session = await getSession(request);
-  const sessionData =
-    ((session as any)?.sessionData as SessionData | undefined) ||
-    buildSessionDataFromAuthSession(session);
-
-  if (!sessionData) {
-    return null;
-  }
-
-  const sessionToken = session?.session?.token as string | undefined;
-  return sessionToken
-    ? { ...sessionData, sessionToken }
-    : sessionData;
-}
-
-/**
- * Get the current request's IDP access token without triggering a refresh.
- *
- * Use this for routes that only need the currently-issued bearer token and
- * should fail closed instead of performing token lifecycle work. For backend
- * proxy routes that forward the token to a downstream API, prefer
- * `getFreshIdpToken` — it preflights expiry and refreshes single-flight, so
- * the proxy never sends a credential it already knows is invalid.
- */
-export async function getIdpToken(request?: Request): Promise<IdpTokenResult> {
-  const sessionData = await getSessionData(request);
-  if (!sessionData) {
-    return { success: false, error: 'NO_SESSION', terminal: true };
-  }
-
-  const accessToken = sessionData.idpAccessToken || (sessionData as any).accessToken;
-  if (!accessToken) {
-    // Card 187871: a live Better Auth session with no idpAccessToken and
-    // mfaVerified !== true is a user mid-2FA, not a dead session - the IDP
-    // withholds the full token until 2FA completes (idp-fetch.ts:81/113).
-    // Only treat this as terminal once the session itself claims 2FA is
-    // already done; a token missing AFTER that is genuinely broken.
-    if (sessionData.mfaVerified !== true) {
-      return { success: false, error: 'NO_TOKEN_PENDING_2FA', terminal: false, sessionData };
-    }
-    return { success: false, error: 'NO_TOKEN', terminal: true };
-  }
-
-  return {
-    success: true,
-    accessToken,
-    sessionData,
-  };
-}
-
-export type FreshIdpTokenResult =
-  | { success: true; accessToken: string; sessionData: SessionData; refreshed: boolean }
-  | {
-      success: false;
-      error: string;
-      status: number;
-      terminal?: boolean;
-      discardToken?: boolean;
-      retryable?: boolean;
-      resolution?: string;
-    };
-
-export interface FreshIdpTokenConfig {
-  idpBaseUrl: string;
-  clientId: string;
-  refreshEndpoint?: string;
-  /** Refresh if the access token is within this many ms of expiry. Default 60_000. */
-  safetyWindowMs?: number;
-}
-
-/**
- * Get the current request's IDP access token, preflight-refreshing if it is
- * expired or within the safety window. Single-flight via Redis lock, so
- * concurrent calls on the same session share one IDP round-trip and one
- * single-use refresh-token consumption.
- *
- * Use this in proxy routes. The returned `accessToken` is safe to forward to
- * a downstream API without expecting a 401. If `success` is false, surface a
- * 401/redirect — there is no recoverable token for this session.
- */
-export async function getFreshIdpToken(
-  request: Request | undefined,
-  config: FreshIdpTokenConfig
-): Promise<FreshIdpTokenResult> {
-  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 };
-  }
-
-  const { ensureFreshAccessToken } = await import('../lib/ensure-fresh-access-token');
-  const result = await ensureFreshAccessToken(
-    sessionToken,
-    {
-      idpBaseUrl: config.idpBaseUrl,
-      clientId: config.clientId,
-      refreshEndpoint: config.refreshEndpoint,
-    },
-    {
-      safetyWindowMs: config.safetyWindowMs,
-      requestId: request?.headers?.get('x-request-id') ?? undefined,
-    }
-  );
-
-  if (!result.ok) {
-    if (result.code === 'NO_SESSION') logNoSessionWithKeys('b', sessionToken);
-    return {
-      success: false,
-      error: result.code,
-      status: result.status,
-      terminal: result.terminal,
-      discardToken: result.discardToken,
-      retryable: result.retryable,
-      resolution: result.resolution,
-    };
-  }
-
-  const sessionData = await getRedisSession(sessionToken);
-  if (!sessionData) {
-    logNoSessionWithKeys('c', sessionToken);
-    return { success: false, error: 'NO_SESSION', status: 401, terminal: true };
-  }
-
-  return {
-    success: true,
-    accessToken: result.accessToken,
-    sessionData,
-    refreshed: result.refreshed,
-  };
-}
-
-/**
- * Get the current session, throwing if not authenticated.
- * Use in API handlers that require auth.
- */
-export async function requireSession(request: Request) {
-  const session = await getSession(request);
-  if (!session) {
-    throw new Error('Unauthorized');
-  }
-  return session;
-}
+/**
+ * Server-side auth utilities for Better Auth.
+ *
+ * All server-side auth flows go through the Better Auth instance returned by
+ * getAuthInstance(); use getSession(req) for the request-scoped session.
+ */
+
+import 'server-only';
+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 =
+  | { success: true; accessToken: string; sessionData: SessionData }
+  | { success: false; error: 'NO_SESSION'; terminal: true }
+  // Card 187871: a Better Auth session can exist with NO idpAccessToken yet
+  // because 2FA is required and not yet completed - the IDP never issued the
+  // full token. That is a RECOVERABLE state (route to 2FA), not a dead
+  // session. Only collapse it to NO_TOKEN/terminal when the session itself
+  // already claims 2FA is done (sessionData.mfaVerified === true) and there is
+  // still no token - that combination is genuinely broken.
+  | { success: false; error: 'NO_TOKEN'; terminal: true }
+  | { success: false; error: 'NO_TOKEN_PENDING_2FA'; terminal: false; sessionData: SessionData };
+
+function buildSessionDataFromAuthSession(session: any): SessionData | null {
+  const user = session?.user;
+  if (!user?.id && !user?.email) {
+    return null;
+  }
+
+  const expiresAt = session?.session?.expiresAt
+    ? new Date(session.session.expiresAt).getTime()
+    : Date.now() + 24 * 60 * 60 * 1000;
+
+  return {
+    userId: user.userId || user.id || '',
+    email: user.email || '',
+    name: user.name || undefined,
+    image: user.image || undefined,
+    roles: Array.isArray(user.roles) ? user.roles : [],
+    idpAccessToken: user.idpAccessToken,
+    idpRefreshToken: user.idpRefreshToken,
+    idpAccessTokenExpires: user.idpAccessTokenExpires || expiresAt,
+    mfaVerified: user.mfaVerified ?? user.twoFactorSessionVerified ?? false,
+    oauthProvider: user.oauthProvider,
+    idpClientId: user.idpClientId,
+    merchantId: user.merchantId,
+  };
+}
+
+function attachSessionData(session: any, sessionData: SessionData | null, sessionToken?: string) {
+  if (!sessionData) {
+    return session;
+  }
+
+  const enrichedSessionData = {
+    ...sessionData,
+    ...(sessionToken ? { sessionToken } : {}),
+  };
+
+  (session as any).sessionData = enrichedSessionData;
+
+  if (session?.user) {
+    const user = session.user as any;
+    user.userId = enrichedSessionData.userId || user.userId;
+    user.email = enrichedSessionData.email || user.email;
+    user.name = enrichedSessionData.name || user.name;
+    user.image = enrichedSessionData.image || user.image;
+    user.roles = enrichedSessionData.roles || user.roles || [];
+    user.idpAccessToken = enrichedSessionData.idpAccessToken;
+    user.idpRefreshToken = enrichedSessionData.idpRefreshToken;
+    user.idpAccessTokenExpires = enrichedSessionData.idpAccessTokenExpires;
+    user.mfaVerified = enrichedSessionData.mfaVerified;
+    user.twoFactorSessionVerified =
+      enrichedSessionData.mfaVerified ?? user.twoFactorSessionVerified;
+    user.oauthProvider = enrichedSessionData.oauthProvider || user.oauthProvider;
+    user.idpClientId = enrichedSessionData.idpClientId || user.idpClientId;
+    user.merchantId = enrichedSessionData.merchantId || user.merchantId;
+  }
+
+  return session;
+}
+
+/**
+ * Get the initialized Better Auth instance (singleton).
+ *
+ * 244549: the single-flight memoisation lives in lib/single-flight.ts rather
+ * than inline here, and that placement is deliberate rather than tidiness.
+ * The bug being fixed -- a REJECTED init promise cached for the life of the
+ * process, so recovery was restart-only -- went unnoticed precisely because
+ * this module cannot be loaded in a unit test: importing it pulls in
+ * better-auth and the whole IDP config stack. Extracted into a zero-import
+ * module, the retry semantics are covered by
+ * test/single-flight-retry.test.cjs, which imports dist/ and therefore
+ * exercises the artefact that actually ships.
+ *
+ * PAY-1623 (package half, BAPert 62449): THIS FUNNEL NO LONGER BUILDS ITS OWN
+ * INSTANCE. It used to call `createBetterAuthInstance(config)` with no opts, so
+ * it carried NONE of the app-supplied plugins registered by the host app at
+ * startup (`configureBetterAuth()` -> `state.configuredOpts`). `samlAcs()` and
+ * `passkeySignIn()` arrive only that way, so `getAuthInstance()` returned an
+ * instance on which `auth.api.samlAcs` was `undefined` — the exact package twin
+ * of the portal ACS crash `t.api.samlAcs is not a function` (Jon's walk,
+ * 2026-09-21; Portal PR 517 fixed the portal by importing the CONFIGURED
+ * instance, `getBetterAuthInstance`, which is why this file must now resolve the
+ * same one). It also silently created a SECOND, divergent instance beside the
+ * one every /api/auth/* route uses — two instances, two secrets, one process.
+ *
+ * It now DELEGATES to that configured funnel, which is the single source of
+ * truth for the process's Better Auth instance:
+ *   - it carries `state.configuredOpts` (better-auth.ts:930), so the app
+ *     plugins are present;
+ *   - its init is already single-flighted with the retry semantics described in
+ *     lib/single-flight.ts (see getBetterAuthInstance, card 244549/338215), so
+ *     this function keeps the same no-latch recovery contract;
+ *   - there is now ONE instance, so the double-init / divergent-secret hazard
+ *     this path used to create is gone by construction.
+ */
+export async function getAuthInstance() {
+  return getBetterAuthInstance();
+}
+
+
+/* ----------------------------------------------------------------------------------------------------------------
+ * PAY-2136 DIAGNOSTICS (BAPert 70873, Nextpert-Scout 70872/70875) - LOG ONLY, NO BEHAVIOUR CHANGE.
+ *
+ * A getFreshIdpToken NO_SESSION used to carry no origin: three different returns produced the same
+ * `{error:'NO_SESSION'}`, and getSession() swallowed every Redis error into a bare `catch {}`. These helpers name
+ * the origin and make a swallowed read audible. Hard rules: every helper is wrapped so it can NEVER throw or change
+ * a return value; nothing here ever logs a token, a cookie VALUE or a Redis value - only a tokenLogId() fingerprint,
+ * cookie NAMES, booleans, and an error name/message with any long opaque run redacted.
+ * -------------------------------------------------------------------------------------------------------------- */
+
+/** An error name/message, first 80 chars, with any 24+ char opaque run (a token, a key) replaced. */
+function scrubForLog(v: 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.
+ *
+ * Source-of-truth contract: **Redis is canonical for liveness.** Better Auth's
+ * cookie+cache layer is treated as a SESSION POINTER (it owns the signed-cookie
+ * secret and the canonical cookie parse) but does NOT decide whether a session
+ * is alive. If Better Auth's primary path returns null or a partial session
+ * (cookie cache miss, secondary storage eviction, token rotation), we fall
+ * back to manually extracting the session-token claim from the cookie and
+ * querying the canonical Redis store directly.
+ *
+ * This closes the asymmetric early-exit that caused contradictory answers
+ * within milliseconds in production traces:
+ *   GET /api/session/viability    → 200 (Redis: alive)
+ *   GET /api/session/idp-token    → 200 (Redis: alive)
+ *   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 { 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
+  }
+
+  if (betterAuthSession?.session?.token && betterAuthSession?.user) {
+    const sessionToken = betterAuthSession.session.token as string;
+    let sessionData: SessionData | null = null;
+    try {
+      sessionData = await getRedisSession(sessionToken);
+      if (!sessionData) sessionData = await getBetterAuthRedisSession(sessionToken);
+    } catch (err) {
+      logSessionReadSwallowed('A', err); // Redis unavailable
+    }
+    if (!sessionData) sessionData = buildSessionDataFromAuthSession(betterAuthSession);
+    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
+  // canonical app session at `{slug}:{token}` is still alive but Better
+  // Auth's `ba:{slug}:{token}` secondary record was evicted or the
+  // in-memory cookie cache returned stale-null.
+  //
+  // PAY-1476: this path used to take the token with NO signature check, on the
+  // theory that "Redis lookup is the validation". It is not: a leaked token has
+  // a live record, so the token string alone authenticated, with any garbage in
+  // 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);
+  // 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 { 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
+  // populated here even though Better Auth didn't give us a full session.
+  const synthetic = {
+    session: { token: sessionToken },
+    user: {
+      id: sessionData.userId,
+      email: sessionData.email,
+      roles: sessionData.roles,
+    },
+  };
+  return { state: 'live', session: attachSessionData(synthetic, sessionData, sessionToken) };
+}
+
+/**
+ * Get normalized session data for the current request.
+ *
+ * This prefers the app's Redis session because it carries the canonical
+ * IDP token, roles, and tenant-specific user identity used by app routes.
+ */
+export async function getSessionData(request?: Request): Promise<SessionData | null> {
+  const session = await getSession(request);
+  const sessionData =
+    ((session as any)?.sessionData as SessionData | undefined) ||
+    buildSessionDataFromAuthSession(session);
+
+  if (!sessionData) {
+    return null;
+  }
+
+  const sessionToken = session?.session?.token as string | undefined;
+  return sessionToken
+    ? { ...sessionData, sessionToken }
+    : sessionData;
+}
+
+/**
+ * Get the current request's IDP access token without triggering a refresh.
+ *
+ * Use this for routes that only need the currently-issued bearer token and
+ * should fail closed instead of performing token lifecycle work. For backend
+ * proxy routes that forward the token to a downstream API, prefer
+ * `getFreshIdpToken` — it preflights expiry and refreshes single-flight, so
+ * the proxy never sends a credential it already knows is invalid.
+ */
+export async function getIdpToken(request?: Request): Promise<IdpTokenResult> {
+  const sessionData = await getSessionData(request);
+  if (!sessionData) {
+    return { success: false, error: 'NO_SESSION', terminal: true };
+  }
+
+  const accessToken = sessionData.idpAccessToken || (sessionData as any).accessToken;
+  if (!accessToken) {
+    // Card 187871: a live Better Auth session with no idpAccessToken and
+    // mfaVerified !== true is a user mid-2FA, not a dead session - the IDP
+    // withholds the full token until 2FA completes (idp-fetch.ts:81/113).
+    // Only treat this as terminal once the session itself claims 2FA is
+    // already done; a token missing AFTER that is genuinely broken.
+    if (sessionData.mfaVerified !== true) {
+      return { success: false, error: 'NO_TOKEN_PENDING_2FA', terminal: false, sessionData };
+    }
+    return { success: false, error: 'NO_TOKEN', terminal: true };
+  }
+
+  return {
+    success: true,
+    accessToken,
+    sessionData,
+  };
+}
+
+export type FreshIdpTokenResult =
+  | { success: true; accessToken: string; sessionData: SessionData; refreshed: boolean }
+  | {
+      success: false;
+      error: string;
+      status: number;
+      terminal?: boolean;
+      discardToken?: boolean;
+      retryable?: boolean;
+      resolution?: string;
+    };
+
+export interface FreshIdpTokenConfig {
+  idpBaseUrl: string;
+  clientId: string;
+  refreshEndpoint?: string;
+  /** Refresh if the access token is within this many ms of expiry. Default 60_000. */
+  safetyWindowMs?: number;
+}
+
+/**
+ * Get the current request's IDP access token, preflight-refreshing if it is
+ * expired or within the safety window. Single-flight via Redis lock, so
+ * concurrent calls on the same session share one IDP round-trip and one
+ * single-use refresh-token consumption.
+ *
+ * Use this in proxy routes. The returned `accessToken` is safe to forward to
+ * a downstream API without expecting a 401. If `success` is false, surface a
+ * 401/redirect — there is no recoverable token for this session.
+ */
+export async function getFreshIdpToken(
+  request: Request | undefined,
+  config: FreshIdpTokenConfig
+): Promise<FreshIdpTokenResult> {
+  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 };
+  }
+
+  const { ensureFreshAccessToken } = await import('../lib/ensure-fresh-access-token');
+  const result = await ensureFreshAccessToken(
+    sessionToken,
+    {
+      idpBaseUrl: config.idpBaseUrl,
+      clientId: config.clientId,
+      refreshEndpoint: config.refreshEndpoint,
+    },
+    {
+      safetyWindowMs: config.safetyWindowMs,
+      requestId: request?.headers?.get('x-request-id') ?? undefined,
+    }
+  );
+
+  if (!result.ok) {
+    if (result.code === 'NO_SESSION') logNoSessionWithKeys('b', sessionToken);
+    return {
+      success: false,
+      error: result.code,
+      status: result.status,
+      terminal: result.terminal,
+      discardToken: result.discardToken,
+      retryable: result.retryable,
+      resolution: result.resolution,
+    };
+  }
+
+  const sessionData = await getRedisSession(sessionToken);
+  if (!sessionData) {
+    logNoSessionWithKeys('c', sessionToken);
+    return { success: false, error: 'NO_SESSION', status: 401, terminal: true };
+  }
+
+  return {
+    success: true,
+    accessToken: result.accessToken,
+    sessionData,
+    refreshed: result.refreshed,
+  };
+}
+
+/**
+ * Get the current session, throwing if not authenticated.
+ * Use in API handlers that require auth.
+ */
+export async function requireSession(request: Request) {
+  const session = await getSession(request);
+  if (!session) {
+    throw new Error('Unauthorized');
+  }
+  return session;
+}