@payez/next-mvp 4.8.1 → 4.8.2

package/src/middleware/create-middleware.ts

@@ -1,1141 +1,1141 @@
-/**
- * MVP Middleware - Authentication & Route Protection
- *
- * Creates a Next.js middleware handler that protects routes based on:
- * - Authentication status (session cookie → Redis viability check)
- * - 2FA completion status
- * - RBAC permissions (if enabled)
- *
- * Usage: Export the result from your app's middleware.ts:
- *   export default createMvpMiddleware();
- *
- * With custom options:
- *   export default createMvpMiddleware({
- *     circuitBreaker: myCircuitBreaker,
- *     logger: myLogger,
- *     viabilityEndpoint: '/api/session/refresh-viability',
- *   });
- */
-
-import { NextRequest, NextResponse } from 'next/server';
-import { isUnauthenticatedRoute, should2FABypass } from '../auth/route-config';
-import { resolveCallbackDestination, safeCallbackPath } from '../auth/safe-callback';
-import { getInternalApiUrl } from '../edge/internal-api-url';
-import { getSessionCookieName, getSecureSessionCookieName } from '../lib/app-slug';
-import { checkPagePermission, isRBACEnabled } from './rbac-check';
-import { tokenLogId } from '../lib/token-log-id';
-import { expireSessionCookies } from '../auth/session-cookie-clear';
-import {
-  DEFAULT_SESSION_RESET_ROUTE,
-  boundSessionCookie,
-  normaliseResetParams,
-  resetSecret,
-  signedResetHref,
-} from '../auth/session-reset-link';
-
-// =============================================================================
-// TYPES
-// =============================================================================
-
-export interface AuthContext {
-  pathname: string;
-  isPublicRoute: boolean;
-  isLoginPage: boolean;
-  searchParams: URLSearchParams;
-  sessionPointer: SessionPointer;
-  sessionStatus: SessionStatus;
-  circuitBreakerOpen: boolean;
-}
-
-export interface SessionPointer {
-  exists: boolean;
-  /** PAY-1481: tokenLogId of the session token (presence + log correlation), never the token itself. */
-  sessionTokenId?: string | null;
-  expired?: boolean;
-  hasRefreshToken?: boolean;
-  roles: string[];
-  clientId: string;
-}
-
-/** PAY-2339: which check could not answer. A fixed, machine-readable value: consumers never parse message text. */
-export type UnavailableCheck = 'revocation' | 'viability';
-
-export interface SessionStatus {
-  exists: boolean | null;       // null = check failed/timeout
-  forceInvalid: boolean | null; // null = check failed/timeout
-  /** PAY-2339: the revocation backend could not answer and this app HOLDS (revocationFailMode 'hold'): no sign-out. */
-  unavailable?: boolean;
-  requires2FA: boolean;
-  twoFactorComplete: boolean;
-}
-
-export type AuthAction =
-  | { type: 'allow' }
-  | { type: 'redirect'; location: string; reason: string; clearCookies?: boolean }
-  | { type: 'service_error'; reason: string; check?: UnavailableCheck }
-  | { type: 'refresh_needed' };
-
-// =============================================================================
-// CIRCUIT BREAKER INTERFACE
-// =============================================================================
-
-/**
- * Circuit breaker interface for middleware integration.
- * Implement this to provide custom circuit breaker behavior.
- */
-export interface CircuitBreakerProvider {
-  /** Check if circuit breaker is currently open */
-  isOpen(): boolean;
-  /** Check if a refresh attempt is allowed (for HALF_OPEN state) */
-  canAttemptRefresh(): boolean;
-  /** Record a successful operation (closes the breaker) */
-  recordSuccess(): void;
-  /** Record a failed operation (may open the breaker) */
-  recordFailure(error?: Error): void;
-  /** Check if an error is a network error (vs HTTP error) */
-  isNetworkError(error: any): boolean;
-}
-
-/**
- * Logger interface for middleware.
- * Implement this to provide custom logging.
- */
-export interface MiddlewareLogger {
-  info(message: string, data?: Record<string, any>): void;
-  warn(message: string, data?: Record<string, any>): void;
-  error(message: string, data?: Record<string, any>): void;
-}
-
-/**
- * Configuration options for createMvpMiddleware
- */
-export interface MvpMiddlewareOptions {
-  /** Custom circuit breaker implementation */
-  circuitBreaker?: CircuitBreakerProvider;
-  /** Custom logger implementation */
-  logger?: MiddlewareLogger;
-  /** Custom viability check endpoint (default: /api/session/viability) */
-  viabilityEndpoint?: string;
-  /** Custom refresh endpoint (default: /api/auth/refresh) */
-  refreshEndpoint?: string;
-  /** Hook called on successful refresh */
-  onRefreshSuccess?: () => void;
-  /** Hook called on refresh failure */
-  onRefreshFailure?: (status: number, isNetworkError: boolean) => void;
-  /** Additional paths to bypass middleware (beyond /api/auth/ and /api/session/) */
-  bypassPaths?: string[];
-  /** Paths exempt from RBAC checks (auth still enforced, just no page-permission check) */
-  rbacExemptPaths?: string[];
-  /**
-   * PAY-2218 - send a page's session-ending redirect through the session-reset ROUTE instead of clearing the
-   * cookies in the middleware response. Next strips the router's prefetch headers before middleware runs
-   * (15.5.x and 16.x; 16.2.x restores them only with `skipProxyUrlNormalize: true`), so a middleware clear also
-   * fires on a router PREFETCH and signs the user out of a page they never opened. The route sees those headers.
-   *
-   * Requires the app to mount the route:  app/api/auth/session-reset/route.ts
-   *     export { GET } from '@payez/next-mvp/routes/auth/session-reset';
-   * `true` uses that default path; a string names another mount point under /api/auth/ (middleware bypasses it).
-   * Needs BETTER_AUTH_SECRET (or NEXTAUTH_SECRET) to sign the hand-off; without one the direct clear is kept and
-   * an error is logged once. Default: off (the direct clear), because an unmounted route would 404 every sign-out.
-   */
-  sessionResetRoute?: boolean | string;
-  /**
-   * PAY-1882 step 4 / PAY-2339 - how this app treats a producer that reports the session's
-   * revocation status as `'unknown'` (a Vibe read that FAILED: non-OK, timeout,
-   * throw - the status could not be determined).
-   *
-   *   'hold' (DEFAULT since PAY-2339, Jon 2026-10-13, option C) - the member is NOT signed out. The request is
-   *                        answered "temporarily unavailable": a page goes to /service-unavailable?callbackUrl=
-   *                        (the session cookie is NOT touched, so "Try again" returns the member still signed in);
-   *                        an /api request gets a 503 carrying `unavailable: true` and `check: 'revocation'`, a
-   *                        fixed machine-readable value. Nothing protected is served while the answer is unknown.
-   *                        Each held request logs one countable `revocation_unavailable` line.
-   *                        THIS REPLACES THE OLD DEFAULT: the PAY-1880 ruling (Jon, 2026-09-27, option A) made
-   *                        'closed' the default and accepted that a Vibe outage signs an app's users out. That
-   *                        sentence no longer applies to 'unknown' by default: a Vibe outage no longer signs members
-   *                        out unless the app asks for 'closed'. 'revoked' is unchanged.
-   *   'closed'           - an unknown revocation status is NOT viable; the session is force-invalidated and the
-   *                        user re-auths (TODAY'S sign-out, now opt-in by name). Consequence, accepted explicitly:
-   *                        a Vibe outage signs this app's users out.
-   *   'open'             - an unknown status stays viable (availability over fail-closed). Per-app opt-out for a
-   *                        deployment with no revocation source.
-   *
-   * `'not_configured'` is UNCHANGED under the default: it is a configuration fault, not an outage, so it still
-   * force-invalidates exactly as before (a "try again" page would be false); `noRevocationSource` is the only way
-   * to make it viable. Neither mode changes `'revoked'` (always force-invalid, unchanged) or an ABSENT
-   * `revocationStatus` (an older producer - unchanged behaviour, so no consumer is signed out for not
-   * implementing the check). A consumer that wrote 'closed' or 'open' by name keeps exactly what it asked for.
-   */
-  revocationFailMode?: 'hold' | 'closed' | 'open';
-
-  /**
-   * PAY-2339 (BAPert 74640): where a page request goes while a revocation answer is held. DEFAULT (absent): the
-   * middleware answers inline with a minimal 503 HTML page ("Temporarily unavailable", a "Try again" link to the safe
-   * callback, no Set-Cookie), so a consumer that never added a page cannot get a 404. Name a same-site path (e.g.
-   * '/service-unavailable') to redirect there instead with `?callbackUrl=`; the consumer then mounts
-   * `export { default } from '@payez/next-mvp/pages/service-unavailable'` (or its own page) at that route.
-   */
-  unavailablePage?: string;
-
-  /**
-   * PAY-2302 cut 1c (BAPert 73585): this app has NO revocation source - for example a development environment
-   * provisioned without a vibe client id / HMAC key - and says so EXPLICITLY. Under it a viability answer of
-   * `revocationStatus: 'not_configured'` is viable, and a loud warning is logged once at startup.
-   *
-   * It relaxes ONLY 'not_configured'. 'unknown' (a revocation read that FAILED) and 'revoked' stay closed whatever
-   * `revocationFailMode` says, and the default (option absent) is unchanged: 'not_configured' fails closed, because
-   * for an app that HAS a vibe client it means a misconfiguration (BAPert 66356). Do not use this to paper over a
-   * misconfigured production app; remove it when the environment has a vibe client + HMAC key.
-   */
-  noRevocationSource?: boolean;
-}
-
-// =============================================================================
-// DEFAULT IMPLEMENTATIONS
-// =============================================================================
-
-/** Default no-op circuit breaker (always closed) */
-const defaultCircuitBreaker: CircuitBreakerProvider = {
-  isOpen: () => false,
-  canAttemptRefresh: () => true,
-  recordSuccess: () => {},
-  recordFailure: () => {},
-  isNetworkError: (error: any) => {
-    return error?.cause?.code === 'ECONNREFUSED' ||
-           error?.code === 'ECONNREFUSED' ||
-           error?.message?.includes('ECONNREFUSED') ||
-           error?.message?.includes('fetch failed') ||
-           error?.message?.includes('ENOTFOUND') ||
-           error?.message?.includes('ETIMEDOUT') ||
-           error?.message?.includes('ECONNRESET');
-  }
-};
-
-/** Default console logger */
-const defaultLogger: MiddlewareLogger = {
-  info: (msg, data) => console.log(`[MIDDLEWARE] ${msg}`, data || ''),
-  warn: (msg, data) => console.warn(`[MIDDLEWARE] ${msg}`, data || ''),
-  error: (msg, data) => console.error(`[MIDDLEWARE] ${msg}`, data || ''),
-};
-
-// =============================================================================
-// HELPERS
-// =============================================================================
-
-const LOGIN_PAGE = '/account-auth/login';
-const VERIFY_CODE_PAGE = '/account-auth/verify-code';
-
-// PAY-2315 (4.7.1): /login is a public alias of the login page. It used to take the 'public: allow' arm and never reached the
-// 'already_authenticated' redirect, so a signed-in user was shown the sign-in form. It is the login page for every arm now.
-// (safe-callback refuses /login as a destination, so this cannot redirect to itself.)
-const LOGIN_ALIAS = '/login';
-
-function isLoginPage(pathname: string): boolean {
-  return pathname === LOGIN_PAGE || pathname === LOGIN_ALIAS;
-}
-
-/**
- * Ensures callback URLs never point to auth pages (prevents redirect loops) AND
- * never point off-origin (prevents open redirect).
- *
- * 375656: the previous body tested `pathname` FIRST and returned '/' early, so
- * the two call sites that pass an attacker-controlled `searchParams` are both
- * inside `if (onLoginPage)` branches - and `isLoginPage` is exact equality against
- * `LOGIN_PAGE`, which starts with `/account-auth/`. The early return therefore
- * fired before the parameter was ever read. That made this function SAFE, but
- * safe because of which argument the caller happened to pass, not because the
- * attacker-controlled value was ever checked: `existing` was returned raw on the
- * strength of a `startsWith` test that `https://evil.example.com` passes.
- * Nothing named that dependency, and reordering the arguments would have opened
- * it silently. Both inputs are now validated by the same parser-based guard.
- */
-function getSafeCallbackUrl(pathname: string, searchParams?: URLSearchParams): string {
-  return resolveCallbackDestination(pathname, searchParams);
-}
-
-/**
- * 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;
-  expireSessionCookies(response, Array.from(request.cookies, ([name]) => name));
-}
-
-/** Create redirect response, optionally clearing cookies */
-function redirectTo(
-  request: NextRequest,
-  location: string,
-  clearCookies = false
-): NextResponse {
-  const response = NextResponse.redirect(new URL(location, request.url));
-  if (clearCookies) {
-    clearSessionCookies(response, request);
-  }
-  return response;
-}
-
-/** PAY-2218: where a page's clearing redirect goes when the app has mounted the session-reset route. */
-interface ResetConfig {
-  route: string;
-  secret: string;
-}
-
-/**
- * A redirect that must also END the session. With the reset route configured, a page request is sent through it
- * WITHOUT any Set-Cookie here: the route sees the flight headers this middleware cannot (Next strips them before
- * middleware), answers a prefetch 204 + no-store, and clears on the real navigation. `/api/` requests and apps
- * without the route keep the direct clear exactly as before.
- */
-async function clearingRedirect(request: NextRequest, location: string, reset?: ResetConfig): Promise<NextResponse> {
-  if (!reset || request.nextUrl.pathname.startsWith('/api/')) {
-    return redirectTo(request, location, true);
-  }
-  const target = new URL(location, request.url);
-  const params = normaliseResetParams({
-    callbackUrl: target.searchParams.get('callbackUrl'),
-    reason: target.searchParams.get('reason'),
-    error: target.searchParams.get('error'),
-  });
-  // Bound to THIS request's session cookie: the route clears only when its own request carries the same one.
-  const bound = boundSessionCookie((n) => request.cookies.get(n)?.value, getSessionCookieName(), getSecureSessionCookieName());
-  const response = NextResponse.redirect(new URL(await signedResetHref(reset.route, params, reset.secret, bound), request.url));
-  response.headers.set('cache-control', 'no-store');
-  return response;
-}
-
-/**
- * Terminal response for a FAILED token refresh.
- *
- * For `/api/` requests a redirect is the wrong terminator: fetch() follows the 307,
- * receives 200 + an HTML login page, and the caller parses garbage instead of
- * branching on an error. Those callers get a 401 JSON body they can branch on;
- * document requests keep the existing redirect exactly as before.
- *
- * Cookie-clearing is preserved on BOTH arms. That is load-bearing, not incidental:
- * on a permanent failure (401/403) stale cookies must be cleared or the next request
- * refreshes again and loops (see the CRITICAL note in handleRefresh). A JSON arm that
- * skipped clearing would convert a redirect loop into a silent refresh loop.
- *
- * Scoped deliberately to handleRefresh's failure exits. It is NOT folded into
- * redirectTo(), and NOT hoisted above the refresh decision: an `/api/` hatch placed
- * higher would intercept 'refresh_needed' and disable middleware token refresh across
- * the whole API surface (card 340024 C1).
- */
-async function refreshFailureResponse(
-  request: NextRequest,
-  location: string,
-  errorCode: string,
-  clearCookies = false,
-  reset?: ResetConfig
-): Promise<NextResponse> {
-  if (request.nextUrl.pathname.startsWith('/api/')) {
-    const response = NextResponse.json({ error: errorCode }, { status: 401 });
-    if (clearCookies) {
-      clearSessionCookies(response, request);
-    }
-    return response;
-  }
-  return clearCookies ? clearingRedirect(request, location, reset) : redirectTo(request, location);
-}
-
-/**
- * PAY-2147: the terminal answer when the middleware CANNOT TELL whether the session is good
- * (circuit breaker open, a half-open breaker refusing a refresh attempt, or the viability read failed).
- *
- * "I could not check" is not a verdict on the session, so this NEVER touches a cookie: a transient blip
- * in the IdP / viability path used to wipe the session of every user who made any request while the
- * breaker was open. Cookies are cleared only on a POSITIVE signal (force_invalidated, stale_session,
- * pre_2fa_token_expired, refresh 401/403, explicit sign-out) - never from here.
- *
- *  - /api/*  -> 503 JSON a caller can branch on (a redirect would be followed by fetch() into a 200 HTML page).
- *  - pages   -> /service-unavailable (public + allowDuringCircuitBreakerOpen, so it cannot loop), carrying the
- *               requested path as `callbackUrl` so "Try again" returns the user to it still signed in. The path goes
- *               through safeCallbackPath (URL-parser origin check): an off-origin or auth-surface value is dropped.
- */
-function serviceUnavailableResponse(request: NextRequest, check: UnavailableCheck = 'viability', unavailablePage?: string): NextResponse {
-  const { pathname, search } = request.nextUrl;
-  if (pathname.startsWith('/api/')) {
-    // PAY-2339 P1/P12: one fixed machine-readable shape for every "could not check" answer. No protected data.
-    return NextResponse.json({ error: 'ServiceUnavailable', unavailable: true, check }, { status: 503 });
-  }
-  const callback = safeCallbackPath(pathname + search);
-  // PAY-2339 (BAPert 74640, P13): a HELD revocation answer needs no page in the consumer. Unless the app names its own
-  // page (`unavailablePage`), the middleware answers inline: a minimal 503 HTML, a "try again" link to the safe
-  // callback, and no Set-Cookie (nothing here touches the session). No redirect, so no 404 is possible.
-  // `unavailablePage` is accepted only as a PLAIN path ([A-Za-z0-9_-/]; no query, fragment, %-encoding, dot segment or
-  // scheme), so the self-check below compares like with like and a mis-set value falls back to the inline page (Scout 74668).
-  // PAY-2345: the viability-FAILURE arm (500 / timeout / breaker) takes the same path, so an app with no page of its own
-  // gets the inline 503 instead of a 404 during an outage. The two arms differ only in `check` (JSON body for /api/*). If the
-  // request is already FOR the named page (an app that did not register it as public), answer inline: redirecting to
-  // it again would loop with a longer callbackUrl each time (QAPert 74651).
-  const named = unavailablePage && /^\/[A-Za-z0-9_\-\/]*$/.test(unavailablePage) && !unavailablePage.includes('//') ? unavailablePage : null;
-  if (!named || pathname.replace(/\/+$/, '') === named.replace(/\/+$/, '')) {
-    const href = callback.replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;');
-    return new NextResponse(
-      '<!doctype html><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>Temporarily unavailable</title>' +
-        '<main role="status" style="font-family:system-ui,sans-serif;max-width:28rem;margin:20vh auto;padding:0 1rem;text-align:center">' +
-        '<h1 style="font-size:1.25rem">Temporarily unavailable</h1>' +
-        '<p>' + (check === 'revocation' ? 'We could not check your session just now. You are still signed in.' : 'We could not reach the sign-in service just now. Please try again.') + '</p>' +
-        '<p><a href="' + href + '">Try again</a></p></main>',
-      { status: 503, headers: { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store', 'retry-after': '30' } },
-    );
-  }
-  const target = new URL(named || '/service-unavailable', request.url);
-  if (callback !== '/') target.searchParams.set('callbackUrl', callback);
-  return NextResponse.redirect(target);
-}
-
-// =============================================================================
-// AUTH DECISION ENGINE
-// =============================================================================
-
-/**
- * Pure function that determines what action to take based on auth state.
- * No side effects - just examines context and returns a decision.
- */
-function makeAuthDecision(ctx: AuthContext): AuthAction {
-  const { pathname, isPublicRoute, isLoginPage: onLoginPage, searchParams, sessionPointer, sessionStatus, circuitBreakerOpen } = ctx;
-  const safeCallback = getSafeCallbackUrl(pathname);
-
-  // --- PAY-884: a provisional (pre-2FA) session whose token has expired can never finish 2FA ---
-  // The IdP issues no refresh token until 2FA completes, and it validates token lifetime, so
-  // once the provisional access token expires neither refresh nor code verification can
-  // succeed. Sending the user to the verify-code page (or to error=SessionExpired, which the
-  // login page deliberately shows as NO message) strands them mid-2FA with no explanation.
-  // Say what happened instead, and clear the dead session so the next sign-in starts clean.
-  // Scoped to the verify-code page and protected pages: /api/ keeps its 401-JSON carve-out
-  // (307290), the login page stays reachable, and public pages are left to the existing arms.
-  if (
-    isExpiredProvisionalSession(sessionPointer, sessionStatus) &&
-    !pathname.startsWith('/api/') &&
-    !onLoginPage &&
-    (pathname === VERIFY_CODE_PAGE || !isPublicRoute)
-  ) {
-    const callback = pathname === VERIFY_CODE_PAGE ? getSafeCallbackUrl(pathname, searchParams) : safeCallback;
-    return {
-      type: 'redirect',
-      location: `${LOGIN_PAGE}?callbackUrl=${encodeURIComponent(callback)}&error=${TWO_FACTOR_TIMEOUT_ERROR}`,
-      reason: 'pre_2fa_token_expired',
-      clearCookies: true,
-    };
-  }
-
-  // --- Public routes: Allow, but enforce 2FA for authenticated users ---
-  if (isPublicRoute && !onLoginPage) {
-    if (needsTwoFactorRedirect(pathname, sessionPointer, sessionStatus)) {
-      return redirect2FA(safeCallback);
-    }
-    return { type: 'allow' };
-  }
-
-  // --- Circuit breaker open: Service degraded ---
-  // PAY-2147: the breaker opening says the IdP/viability path is unreachable, NOT that the session is bad.
-  // Answer "service unavailable" (503 for /api, /service-unavailable for pages) and leave every cookie alone.
-  if (circuitBreakerOpen) {
-    if (onLoginPage) return { type: 'allow' };
-    return { type: 'service_error', reason: 'circuit_breaker_open' };
-  }
-
-  // --- No session cookie: Need to login ---
-  if (!sessionPointer.exists) {
-    if (onLoginPage) return { type: 'allow' };
-    if (pathname === '/') {
-      const unauthUrl = process.env.UNAUTHENTICATED_REDIRECT_URL || '/account-auth/login';
-      return { type: 'redirect', location: unauthUrl, reason: 'unauthenticated_root' };
-    }
-    if (pathname.startsWith('/api/')) {
-      return { type: 'allow' }; // Let API return proper 401 JSON
-    }
-    return {
-      type: 'redirect',
-      location: `${LOGIN_PAGE}?callbackUrl=${encodeURIComponent(safeCallback)}`,
-      reason: 'no_session'
-    };
-  }
-
-  // --- Service error: Can't verify session ---
-  if (sessionStatus.exists === null || sessionStatus.forceInvalid === null) {
-    if (onLoginPage) return { type: 'allow' }; // the login page must stay reachable while the check is down
-    return { type: 'service_error', reason: 'viability_check_failed' };
-  }
-
-  // --- PAY-2339: the revocation backend could not answer and this app HOLDS (the default) ---
-  // Not a verdict on the session: no cookie is touched, nothing protected is served, and the answer says why in a
-  // fixed machine-readable form. The login page stays reachable.
-  if (sessionStatus.unavailable) {
-    if (onLoginPage) return { type: 'allow' };
-    return { type: 'service_error', reason: 'revocation_unknown', check: 'revocation' };
-  }
-
-  // --- Session force-invalidated (admin action, password change, etc.) ---
-  if (sessionStatus.forceInvalid) {
-    if (onLoginPage) return { type: 'allow' };
-    if (pathname.startsWith('/api/')) return { type: 'allow' };
-    return {
-      type: 'redirect',
-      location: `${LOGIN_PAGE}?callbackUrl=${encodeURIComponent(safeCallback)}&reason=invalidated`,
-      reason: 'force_invalidated',
-      clearCookies: true
-    };
-  }
-
-  // --- Stale session (cookie exists but Redis entry gone) ---
-  if (!sessionStatus.exists) {
-    if (onLoginPage) return { type: 'allow' };
-    if (pathname.startsWith('/api/')) return { type: 'allow' };
-    return {
-      type: 'redirect',
-      location: `${LOGIN_PAGE}?callbackUrl=${encodeURIComponent(safeCallback)}&reason=stale`,
-      reason: 'stale_session',
-      clearCookies: true
-    };
-  }
-
-  // --- 2FA required but not completed ---
-  if (needsTwoFactorRedirect(pathname, sessionPointer, sessionStatus)) {
-    if (onLoginPage) {
-      const cb = getSafeCallbackUrl(pathname, searchParams);
-      return { type: 'redirect', location: `${VERIFY_CODE_PAGE}?callbackUrl=${encodeURIComponent(cb)}`, reason: '2fa_from_login' };
-    }
-    return redirect2FA(safeCallback);
-  }
-
-  // --- Token expired: Try refresh ---
-  if (sessionPointer.expired) {
-    if (onLoginPage) return { type: 'allow' };
-    if (sessionPointer.hasRefreshToken) {
-      return { type: 'refresh_needed' };
-    }
-    // 307290: this is the TERMINAL arm of the expired branch - refresh is not
-    // possible here, so the only outcomes are "redirect" or "allow". Every other
-    // terminal branch in this function (:242 no_session, :259 force_invalidated,
-    // :271 stale_session, :318 2FA-incomplete) already exempts /api/ so the route
-    // can answer with a real 401 JSON; this one did not, and redirecting an API
-    // request to an HTML login page makes the failure INVISIBLE - fetch() follows
-    // the 307, gets 200 HTML, resolves successfully and parses garbage.
-    // MUST stay BELOW the hasRefreshToken check above: placed any higher it would
-    // intercept 'refresh_needed' and disable middleware token refresh for the
-    // entire API surface.
-    if (pathname.startsWith('/api/')) return { type: 'allow' }; // Let API return proper 401 JSON
-    return {
-      type: 'redirect',
-      location: `${LOGIN_PAGE}?callbackUrl=${encodeURIComponent(safeCallback)}&error=SessionExpired`,
-      reason: 'token_expired_no_refresh'
-    };
-  }
-
-  // --- Authenticated user on login page: Send to their destination ---
-  if (onLoginPage) {
-    const dest = getSafeCallbackUrl(pathname, searchParams);
-    return { type: 'redirect', location: dest, reason: 'already_authenticated' };
-  }
-
-  // --- All checks passed ---
-  return { type: 'allow' };
-}
-
-/** Login error code for a pre-2FA session that expired before the code was verified (PAY-884). */
-export const TWO_FACTOR_TIMEOUT_ERROR = 'TwoFactorTimeout';
-
-/**
- * PAY-884: 2FA outstanding, access token expired, and no refresh token to renew it.
- * Only a viability answer that positively says the session exists qualifies (null = check failed).
- */
-function isExpiredProvisionalSession(session: SessionPointer, status: SessionStatus): boolean {
-  return (
-    session.exists &&
-    status.exists === true &&
-    status.forceInvalid === false &&
-    status.requires2FA &&
-    !status.twoFactorComplete &&
-    session.expired === true &&
-    !session.hasRefreshToken
-  );
-}
-
-/** Check if user needs 2FA redirect */
-function needsTwoFactorRedirect(pathname: string, session: SessionPointer, status: SessionStatus): boolean {
-  if (!session.exists || !status.exists) return false;
-  if (!status.requires2FA || status.twoFactorComplete) return false;
-  if (pathname === VERIFY_CODE_PAGE) return false;
-  if (should2FABypass(pathname)) return false;
-  if (pathname.startsWith('/api/')) return false; // APIs return JSON errors
-  return true;
-}
-
-function redirect2FA(callbackUrl: string): AuthAction {
-  return {
-    type: 'redirect',
-    location: `${VERIFY_CODE_PAGE}?callbackUrl=${encodeURIComponent(callbackUrl)}`,
-    reason: '2fa_required'
-  };
-}
-
-// =============================================================================
-// MIDDLEWARE FACTORY
-// =============================================================================
-
-/** PAY-2218: the stripped-flight-headers warning is logged once per process, not once per request. */
-let flightHeadersStrippedWarned = false;
-
-export function createMvpMiddleware(options: MvpMiddlewareOptions = {}) {
-  // Resolve options with defaults
-  const cb = options.circuitBreaker || defaultCircuitBreaker;
-  const log = options.logger || defaultLogger;
-  const viabilityEndpoint = options.viabilityEndpoint || '/api/session/viability';
-  const refreshEndpoint = options.refreshEndpoint || '/api/auth/refresh';
-  const bypassPaths = options.bypassPaths || [];
-  const rbacExemptPaths = options.rbacExemptPaths || [];
-  // PAY-2339: the default is 'hold' (Jon 2026-10-13, option C): an unknown revocation answer does not sign the member
-  // out. PAY-1882 step 4 had 'closed' (Jon's PAY-1880 option A, BAPert 66316); it is now opt-in by name.
-  const revocationFailMode = options.revocationFailMode || 'hold';
-  // PAY-2302 cut 1c: strictly `=== true`, so a truthy string in a config file cannot switch revocation off.
-  const noRevocationSource = options.noRevocationSource === true;
-  if (noRevocationSource) {
-    log.warn(
-      '[next-mvp] noRevocationSource is ON: sessions of this app CANNOT be revoked server-side (no vibe client / HMAC key). ' +
-      "revocationStatus 'not_configured' is treated as viable; 'unknown' and 'revoked' still sign the user out. " +
-      'Remove this option once the environment has a vibe client id and HMAC key.'
-    );
-  }
-  const sessionResetRoute =
-    options.sessionResetRoute === true ? DEFAULT_SESSION_RESET_ROUTE
-    : typeof options.sessionResetRoute === 'string' && options.sessionResetRoute ? options.sessionResetRoute
-    : undefined;
-  let resetSecretMissingLogged = false;
-  const resolveReset = (): ResetConfig | undefined => {
-    if (!sessionResetRoute) return undefined;
-    const secret = resetSecret();
-    if (secret) return { route: sessionResetRoute, secret };
-    if (!resetSecretMissingLogged) {
-      resetSecretMissingLogged = true;
-      log.error('sessionResetRoute is set but no BETTER_AUTH_SECRET/NEXTAUTH_SECRET is available to sign the hand-off; clearing in middleware instead', { sessionResetRoute });
-    }
-    return undefined;
-  };
-
-  return async function middleware(request: NextRequest): Promise<NextResponse> {
-    const { pathname, searchParams } = request.nextUrl;
-
-    // =========================================================================
-    // CRITICAL: Auth routes MUST bypass middleware
-    // =========================================================================
-    // These routes are called internally by middleware itself (viability check,
-    // token refresh). Without this bypass, we get infinite loops or 403s.
-    // This has caused production outages. DO NOT REMOVE.
-    // =========================================================================
-    if (pathname.startsWith('/api/auth/') || pathname.startsWith('/api/session/')) {
-      return NextResponse.next();
-    }
-
-    // Check custom bypass paths
-    for (const bypassPath of bypassPaths) {
-      if (pathname.startsWith(bypassPath)) {
-        return NextResponse.next();
-      }
-    }
-
-    // PAY-2218: a router request (it carries `next-url`) that arrives WITHOUT `rsc` had its flight headers stripped
-    // by Next before middleware ran, so isPrefetchRequest() cannot see a router prefetch on this app. Say so once.
-    if (!sessionResetRoute && !flightHeadersStrippedWarned && request.headers.has('next-url') && !request.headers.has('rsc')) {
-      flightHeadersStrippedWarned = true;
-      log.warn('Next strips router prefetch headers before middleware on this app, so a session-ending redirect can fire on a prefetch. Mount @payez/next-mvp/routes/auth/session-reset and set sessionResetRoute (PAY-2218).', { pathname });
-    }
-
-    const isPublic = isUnauthenticatedRoute(pathname);
-    const isLogin = isLoginPage(pathname);
-
-    // --- Optimization: Skip viability check for unauthenticated public browsing ---
-    if (isPublic && !isLogin) {
-      const hasCookie = request.cookies.get(getSessionCookieName())?.value ||
-                        request.cookies.get(getSecureSessionCookieName())?.value;
-      if (!hasCookie) {
-        return NextResponse.next();
-      }
-      // Has cookie - continue to viability check for 2FA enforcement
-    }
-
-    // --- Fetch session viability from internal API ---
-    const { sessionStatus, sessionPointer } = await checkViability(
-      request,
-      viabilityEndpoint,
-      log,
-      revocationFailMode,
-      noRevocationSource
-    );
-
-    // --- Stale session (cookie exists but session doesn't): OBSERVE ONLY, DO NOT DECIDE ---
-    //
-    // *** CARD 349607. THIS BLOCK USED TO `return` HERE, AND THAT RETURN WAS A BYPASS. ***
-    //
-    // makeAuthDecision() below already handles this exact condition at its
-    // `if (!sessionStatus.exists)` branch, and it handles it with TWO guard
-    // clauses that this early return did not have:
-    //
-    //     if (onLoginPage)                 return { type: 'allow' };   // no redirect loop
-    //     if (pathname.startsWith('/api/'))return { type: 'allow' };   // no HTML 307 at fetch()
-    //
-    // Returning here skipped BOTH. The `/api/` case is the reported harm: a
-    // stale-session XHR was answered with a 307 to an HTML login page, so the
-    // failure is invisible to `fetch()` - the caller sees an opaque redirect
-    // instead of an auth error, which is the same "correct logic preempted by
-    // an earlier return" shape recorded on 307290.
-    //
-    // This was NOT a missing feature one level down - the decision engine's
-    // branch is a strict superset of the behaviour this block implemented.
-    // The early return was a DUPLICATE that had drifted from the original.
-    // Adding a single `/api/` exemption here would have re-created the
-    // duplication (and left the onLoginPage divergence in place), so the
-    // duplicate is removed instead and the engine is left as the ONE decider.
-    //
-    // The warning is deliberately KEPT: it is the only operational signal that
-    // stale sessions are occurring, and it costs nothing to log before
-    // delegating. Do not re-introduce a `return` in this block.
-    if (!isPublic && sessionStatus.exists === false && sessionPointer.sessionTokenId) {
-      // PAY-1505: the KEY is `sessionTokenId`, not `sessionToken`. The value has
-      // always been a tokenLogId fingerprint (viability.ts builds it as
-      // `tokenLogId(sessionToken)`), but labelling it `sessionToken` told any
-      // operator reading this log that the line carried the token itself. The
-      // credential-in-logs source guard reads the key for exactly that reason:
-      // a field named `sessionToken` must hold a safe value, and proving that
-      // across an API boundary is not possible from the name alone.
-      log.warn('Stale session detected (delegating to decision engine)', {
-        sessionTokenId: sessionPointer.sessionTokenId,
-        pathname
-      });
-    }
-
-    // --- Run decision engine ---
-    const decision = makeAuthDecision({
-      pathname,
-      isPublicRoute: isPublic,
-      isLoginPage: isLogin,
-      searchParams,
-      sessionPointer,
-      sessionStatus,
-      circuitBreakerOpen: cb.isOpen(),
-    });
-
-    // --- Execute decision ---
-    return executeDecision(request, decision, pathname, sessionPointer, sessionStatus, {
-      circuitBreaker: cb,
-      logger: log,
-      refreshEndpoint,
-      rbacExemptPaths,
-      reset: resolveReset(),
-      unavailablePage: options.unavailablePage,
-      onRefreshSuccess: options.onRefreshSuccess,
-      onRefreshFailure: options.onRefreshFailure,
-    });
-  };
-}
-
-/**
- * The revocation decision, as a pure function (PAY-1882 step 4, NightHawk 66392).
- *
- * Separate + exported so the B1 defect is testable with a REAL mutant: the bug was
- * that `data.forceInvalid === true` was read BEFORE revocationFailMode, so a
- * producer that folds 'unknown' into forceInvalid made the 'open' lever dead.
- *
- * RULE: when the producer supplies `revocationStatus`, it is AUTHORITATIVE - the
- * decision is made from it plus failMode, and the folded booleans are ignored for
- * 'unknown'/'not_configured'. The booleans are read ONLY when revocationStatus is
- * absent (idealresume.online's older boolean-only route).
- */
-export type RevocationOutcome = 'viable' | 'invalid' | 'hold';
-
-/**
- * PAY-2339: the three-way form of the revocation decision. `decideForceInvalid` below is kept as its boolean view.
- *
- *   'invalid' - sign the member out (cookies cleared, login page)
- *   'hold'    - the backend could not answer and this app holds: no sign-out, answer "temporarily unavailable"
- *   'viable'  - carry on
- */
-export function decideRevocationOutcome(
-  data: { revocationStatus?: unknown; forceInvalid?: unknown; revoked?: unknown },
-  revocationFailMode: 'hold' | 'closed' | 'open',
-  noRevocationSource: boolean = false,
-): RevocationOutcome {
-  const status = data.revocationStatus;
-  if (typeof status === 'string') {
-    if (status === 'revoked') return 'invalid';
-    if (status === 'active') return 'viable';
-    // PAY-2302 cut 1c: an app that declared it has no revocation source. ONLY the exact 'not_configured' string.
-    if (status === 'not_configured' && noRevocationSource === true) return 'viable';
-    // PAY-2339: 'not_configured' is a configuration fault, not an outage. Under the default it stays signed out
-    // exactly as before; only 'open' relaxes it (a Vibe-less app).
-    if (status === 'not_configured') return revocationFailMode === 'open' ? 'viable' : 'invalid';
-    // S1 (NightHawk 66409): ANY other string - 'unknown', a typo like 'Revoked', 'error', or '' - is treated as
-    // 'unknown' (the fail mode applies), NEVER as 'active'. Only an explicit 'active' is viable.
-    if (revocationFailMode === 'open') return 'viable';
-    return revocationFailMode === 'closed' ? 'invalid' : 'hold';
-  }
-  // No revocationStatus: an older boolean producer. Absence of both stays viable.
-  return data.forceInvalid === true || data.revoked === true ? 'invalid' : 'viable';
-}
-
-export function decideForceInvalid(
-  data: { revocationStatus?: unknown; forceInvalid?: unknown; revoked?: unknown },
-  revocationFailMode: 'hold' | 'closed' | 'open',
-  noRevocationSource: boolean = false,
-): boolean {
-  return decideRevocationOutcome(data, revocationFailMode, noRevocationSource) === 'invalid';
-}
-
-/**
- * PAY-2147: does the request carry a session cookie? Used ONLY when the viability read itself FAILED.
- * Before this, a failed read left sessionPointer.exists=false, so the decision engine took its `no_session` arm
- * (pages -> the LOGIN page, /api -> straight through) and its `exists === null` -> service_error arm below it was
- * unreachable dead code: a user holding a perfectly good session was told to sign in during an outage. With a
- * cookie present and the check down we do not know the session is bad, so the engine must say "service
- * unavailable", not "sign in". No cookie -> unchanged (no_session).
- */
-function hasSessionCookie(request: NextRequest): boolean {
-  return !!(request.cookies.get(getSessionCookieName())?.value || request.cookies.get(getSecureSessionCookieName())?.value);
-}
-
-/** Check session viability via internal API */
-async function checkViability(
-  request: NextRequest,
-  endpoint: string,
-  log: MiddlewareLogger,
-  revocationFailMode: 'hold' | 'closed' | 'open',
-  noRevocationSource: boolean = false
-): Promise<{
-  sessionStatus: SessionStatus;
-  sessionPointer: SessionPointer;
-}> {
-  const sessionStatus: SessionStatus = {
-    exists: false,
-    forceInvalid: false,
-    requires2FA: false,
-    twoFactorComplete: false,
-  };
-  const sessionPointer: SessionPointer = {
-    exists: false,
-    sessionTokenId: undefined,
-    expired: false,
-    hasRefreshToken: false,
-    roles: [],
-    clientId: '',
-  };
-
-  try {
-    const baseUrl = getInternalApiUrl(request);
-    const response = await fetch(new URL(endpoint, baseUrl), {
-      method: 'GET',
-      headers: {
-        'Accept': 'application/json',
-        'Cache-Control': 'no-store',
-        'Cookie': request.headers.get('cookie') || ''
-      },
-      credentials: 'include',
-      signal: AbortSignal.timeout(5000),
-    });
-
-    if (response.ok) {
-      const data = await response.json();
-      // Support both response formats (viability and refresh-viability)
-      sessionStatus.exists = data.authenticated ?? (!!data.sessionTokenId && data.reason !== 'session_not_found');
-      sessionStatus.requires2FA = data.requires2FA || false;
-      sessionStatus.twoFactorComplete = data.twoFactorComplete || false;
-      // --- Session revocation (PAY-1882 Step 4) ---
-      // Two producer spellings are honoured, because both exist on the wire:
-      //   - boolean `forceInvalid` / `revoked` (idealresume.online's route today)
-      //   - the three-state `revocationStatus` the package's own viability
-      //     handlers now emit (PAY-1882 step 4).
-      //
-      // RULING (Jon, via BAPert 66316): 'revoked' ALWAYS fails closed. 'unknown'
-      // (a FAILED Vibe read) fails closed by default and is the ONLY state that
-      // the per-app `revocationFailMode` option can relax to viable.
-      //
-      // Four producer states (BAPert 66320), with the fail-closed ruling for
-      // 'not_configured' added by BAPert 66356:
-      //   'active'         - Vibe read OK, not revoked  -> viable
-      //   'revoked'        - Vibe says revoked          -> force-invalid, ALWAYS
-      //   'unknown'        - read FAILED                -> force-invalid if 'closed'
-      //   'not_configured' - no revocation source       -> force-invalid if 'closed'
-      //
-      // WHY 'not_configured' FAILS CLOSED WHEN 'closed': both live consumers of
-      // this middleware (portal.keelauth.com / keelauth-portal, idealvibe.online)
-      // DO set IDP_URL + VIBE_CLIENT_ID + VIBE_HMAC_KEY (BAPert 66356, measured in
-      // their committed manifests + the graft pipeline's own secret check), so for
-      // them 'not_configured' can only mean a MISCONFIGURATION - revocation
-      // silently switched off is exactly the PAY-1880 fail-open bug. An app with
-      // no revocation source that genuinely wants availability sets
-      // revocationFailMode 'open'.
-      //
-      // A MISSING revocationStatus (an older producer) keeps today's behaviour,
-      // i.e. NOT force-invalid: absence must never sign out a population that
-      // never opted into the check.
-      //
-      // *** revocationStatus IS AUTHORITATIVE WHEN PRESENT (NightHawk 66392). ***
-      // The package's own producers emit `forceInvalid: revocationStatus ===
-      // 'revoked' || revocationStatus === 'unknown'`. If the boolean were read
-      // FIRST, `forceInvalid: true` would short-circuit before revocationFailMode
-      // was consulted, so `'open'` could never keep an 'unknown' session viable -
-      // the opt-out lever would be DEAD. So: when a producer supplies a
-      // revocations status, decide from it + failMode and ignore the folded
-      // booleans for unknown/not_configured. The booleans are read ONLY when
-      // revocationStatus is ABSENT (idealresume.online's older boolean route).
-      const outcome = decideRevocationOutcome(data, revocationFailMode, noRevocationSource);
-      sessionStatus.forceInvalid = outcome === 'invalid';
-      if (outcome === 'hold') {
-        sessionStatus.unavailable = true;
-        // PAY-2339 P11: one countable line per held request, naming the check. No session value, no address.
-        log.warn('revocation_unavailable', { check: 'revocation' });
-      }
-      // PAY-2216: a STALE session - the cookie resolved to a token, but no store holds the session - used to set
-      // pointer.exists=false, so makeAuthDecision took no_session (login, cookie NOT cleared) and its stale_session
-      // arm (clearCookies) was unreachable: a dead cookie lingered and re-ran viability on every request.
-      // Stale is a POSITIVE signal and needs ALL of: this 2xx read, exists === false, a sessionTokenId (every
-      // producer sets it only when a cookie resolved to a token: routes/auth/viability.ts, api-handlers/session/
-      // viability.ts, refresh-viability.ts 'session_not_found'), and a session cookie on THIS request (plain or
-      // __Secure-). A FAILED read never gets here (exists=null -> service_error, PAY-2147); a store error throws
-      // inside every producer and answers 5xx or 'unknown' WITHOUT a sessionTokenId; no cookie -> no_session.
-      const stale = sessionStatus.exists === false && !!data.sessionTokenId && hasSessionCookie(request);
-      sessionPointer.exists = stale ? true : (sessionStatus.exists ?? false);
-      sessionPointer.sessionTokenId = data.sessionTokenId ?? null;
-      sessionPointer.expired = data.accessTokenExpired || false;
-      sessionPointer.hasRefreshToken = data.hasRefreshToken ?? data.canRefresh ?? false;
-      sessionPointer.roles = data.roles || [];
-      sessionPointer.clientId = data.clientId || '';
-    } else {
-      log.error('Viability check failed', { status: response.status });
-      sessionStatus.exists = null;
-      sessionStatus.forceInvalid = null;
-      sessionPointer.exists = hasSessionCookie(request); // PAY-2147: see hasSessionCookie
-    }
-  } catch (error) {
-    log.error('Viability check error', { error: error instanceof Error ? error.message : String(error) });
-    sessionStatus.exists = null;
-    sessionStatus.forceInvalid = null;
-    sessionPointer.exists = hasSessionCookie(request); // PAY-2147: see hasSessionCookie
-  }
-
-  return { sessionStatus, sessionPointer };
-}
-
-/** Options passed to executeDecision */
-interface ExecuteOptions {
-  circuitBreaker: CircuitBreakerProvider;
-  logger: MiddlewareLogger;
-  refreshEndpoint: string;
-  rbacExemptPaths: string[];
-  /** PAY-2218: set when the app mounted the session-reset route AND a signing secret exists. */
-  reset?: ResetConfig;
-  /** PAY-2339: the app's named hold page; absent = the inline 503 HTML. */
-  unavailablePage?: string;
-  onRefreshSuccess?: () => void;
-  onRefreshFailure?: (status: number, isNetworkError: boolean) => void;
-}
-
-/** Execute the auth decision */
-async function executeDecision(
-  request: NextRequest,
-  decision: AuthAction,
-  pathname: string,
-  sessionPointer: SessionPointer,
-  sessionStatus: SessionStatus,
-  opts: ExecuteOptions
-): Promise<NextResponse> {
-  const safeCallback = getSafeCallbackUrl(pathname);
-
-  switch (decision.type) {
-    case 'allow':
-      return handleAllow(request, pathname, sessionPointer, sessionStatus, opts.rbacExemptPaths);
-
-    case 'redirect':
-      return decision.clearCookies
-        ? clearingRedirect(request, decision.location, opts.reset)
-        : redirectTo(request, decision.location);
-
-    case 'service_error':
-      return serviceUnavailableResponse(request, decision.check ?? 'viability', opts.unavailablePage);
-
-    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);
-  }
-}
-
-/** Paths that must never be RBAC-checked (they are RBAC redirect targets) */
-const RBAC_EXEMPT_PATHS = ['/error', '/unauthorized', '/service-unavailable'];
-
-/** Handle 'allow' decision - run RBAC if enabled */
-async function handleAllow(
-  request: NextRequest,
-  pathname: string,
-  sessionPointer: SessionPointer,
-  sessionStatus: SessionStatus,
-  rbacExemptPaths: string[] = []
-): Promise<NextResponse> {
-  const isPublic = isUnauthenticatedRoute(pathname);
-
-  // PAY-2216: RBAC needs a session that viability CONFIRMED. A stale /api request (pointer.exists only says the
-  // cookie is present, status.exists is false) is allowed through so the route handler answers its own 401 - not an
-  // RBAC 401 here. TRUTHY, not `=== true` (NightHawk 71960): status.exists carries the producer's JSON value as-is,
-  // and a consumer route may answer authenticated: 1 / "true"; `=== true` skipped RBAC for those healthy sessions
-  // (fail-OPEN). Truthy keeps 4.5.3's RBAC coverage exactly and still excludes stale (false) and a failed read (null).
-  if (isRBACEnabled() && !isPublic && sessionPointer.exists && sessionStatus.exists) {
-    // Skip RBAC for error/fallback pages (prevent redirect loops) and app-configured exempt paths
-    if (RBAC_EXEMPT_PATHS.some(p => pathname.startsWith(p)) ||
-        rbacExemptPaths.some(p => pathname.startsWith(p))) {
-      return NextResponse.next();
-    }
-
-    if (!sessionPointer.clientId) {
-      console.error('[MIDDLEWARE] RBAC: No clientId — returning 401');
-      if (pathname.startsWith('/api/')) {
-        return NextResponse.json(
-          { error: 'Unauthorized — missing clientId for RBAC' },
-          { status: 401 }
-        );
-      }
-      return NextResponse.redirect(new URL('/unauthorized', request.url));
-    }
-
-    try {
-      const result = await checkPagePermission(pathname, sessionPointer.roles, sessionPointer.clientId);
-
-      if (!result.allowed) {
-        console.log('[MIDDLEWARE] RBAC denied:', { pathname, reason: result.reason });
-
-        // In development, fail open - RBAC API may not be fully configured
-        if (process.env.NODE_ENV !== 'production') {
-          console.warn('[MIDDLEWARE] RBAC: Allowing in development despite denial:', result.reason);
-          return NextResponse.next();
-        }
-
-        return NextResponse.redirect(new URL(result.redirect || '/unauthorized', request.url));
-      }
-
-      if (result.requires_2fa && !sessionStatus.twoFactorComplete) {
-        return NextResponse.redirect(
-          new URL(`${VERIFY_CODE_PAGE}?callbackUrl=${encodeURIComponent(pathname)}`, request.url)
-        );
-      }
-    } catch (error) {
-      console.error('[MIDDLEWARE] RBAC error:', error);
-
-      // In development, fail open
-      if (process.env.NODE_ENV !== 'production') {
-        console.warn('[MIDDLEWARE] RBAC: Allowing in development despite error');
-        return NextResponse.next();
-      }
-
-      return NextResponse.redirect(new URL('/error?code=rbac_error', request.url));
-    }
-  }
-
-  return NextResponse.next();
-}
-
-/** Handle token refresh */
-async function handleRefresh(
-  request: NextRequest,
-  safeCallback: string,
-  opts: ExecuteOptions
-): Promise<NextResponse> {
-  const { circuitBreaker: cb, logger: log, refreshEndpoint, onRefreshSuccess, onRefreshFailure } = opts;
-
-  // Check if circuit breaker allows refresh attempt
-  if (!cb.canAttemptRefresh()) {
-    log.warn('Circuit breaker preventing refresh attempt');
-    // PAY-2147: a breaker that merely declines to TRY a refresh has learned nothing about the session; wiping the
-    // cookies here logged out every user on the first request after a blip (HALF_OPEN refuses all but one probe).
-    return serviceUnavailableResponse(request, 'viability', opts.unavailablePage);
-  }
-
-  try {
-    const baseUrl = getInternalApiUrl(request);
-    const response = await fetch(new URL(refreshEndpoint, baseUrl), {
-      method: 'POST',
-      headers: {
-        'Accept': 'application/json',
-        'Content-Type': 'application/json',
-        'Cookie': request.headers.get('cookie') || '',
-        'x-session-token': request.cookies.get(getSessionCookieName())?.value ||
-                           request.cookies.get(getSecureSessionCookieName())?.value || ''
-      },
-      credentials: 'include',
-      signal: AbortSignal.timeout(5000),
-    });
-
-    if (response.ok) {
-      const data = await response.json();
-      if (data.refreshed || data.reason === 'already_fresh') {
-        cb.recordSuccess();
-        onRefreshSuccess?.();
-        log.info('Token refresh successful');
-        return NextResponse.next();
-      }
-    }
-
-    // Refresh failed - check for permanent failures (401/403) vs transient (5xx)
-    // CRITICAL: Always clear cookies on 401/403 to prevent redirect loops
-    // CRITICAL: Only record circuit breaker failures for network errors, not HTTP errors
-    // HTTP 500 means the server responded - it's reachable. Only network failures should trip the breaker.
-    const isPermanentFailure = response.status === 401 || response.status === 403;
-    const errorParam = isPermanentFailure ? 'SessionExpired' : 'RefreshError';
-
-    log.warn('Refresh failed', {
-      status: response.status,
-      isPermanentFailure,
-      clearingCookies: isPermanentFailure
-    });
-
-    onRefreshFailure?.(response.status, false);
-
-    return refreshFailureResponse(
-      request,
-      `${LOGIN_PAGE}?callbackUrl=${encodeURIComponent(safeCallback)}&error=${errorParam}`,
-      errorParam,
-      isPermanentFailure,
-      opts.reset
-    );
-  } catch (error: any) {
-    const isNetwork = cb.isNetworkError(error);
-    log.error('Refresh error', {
-      error: error instanceof Error ? error.message : String(error),
-      isNetworkError: isNetwork
-    });
-
-    // Only record circuit breaker failure for actual network errors
-    if (isNetwork) {
-      cb.recordFailure(error);
-    }
-
-    onRefreshFailure?.(0, isNetwork);
-
-    // Network error - don't clear cookies, might be transient
-    return refreshFailureResponse(
-      request,
-      `${LOGIN_PAGE}?callbackUrl=${encodeURIComponent(safeCallback)}&error=RefreshError`,
-      'RefreshError',
-      false
-    );
-  }
-}
-
+/**
+ * MVP Middleware - Authentication & Route Protection
+ *
+ * Creates a Next.js middleware handler that protects routes based on:
+ * - Authentication status (session cookie → Redis viability check)
+ * - 2FA completion status
+ * - RBAC permissions (if enabled)
+ *
+ * Usage: Export the result from your app's middleware.ts:
+ *   export default createMvpMiddleware();
+ *
+ * With custom options:
+ *   export default createMvpMiddleware({
+ *     circuitBreaker: myCircuitBreaker,
+ *     logger: myLogger,
+ *     viabilityEndpoint: '/api/session/refresh-viability',
+ *   });
+ */
+
+import { NextRequest, NextResponse } from 'next/server';
+import { isUnauthenticatedRoute, should2FABypass } from '../auth/route-config';
+import { resolveCallbackDestination, safeCallbackPath } from '../auth/safe-callback';
+import { getInternalApiUrl } from '../edge/internal-api-url';
+import { getSessionCookieName, getSecureSessionCookieName } from '../lib/app-slug';
+import { checkPagePermission, isRBACEnabled } from './rbac-check';
+import { tokenLogId } from '../lib/token-log-id';
+import { expireSessionCookies } from '../auth/session-cookie-clear';
+import {
+  DEFAULT_SESSION_RESET_ROUTE,
+  boundSessionCookie,
+  normaliseResetParams,
+  resetSecret,
+  signedResetHref,
+} from '../auth/session-reset-link';
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+export interface AuthContext {
+  pathname: string;
+  isPublicRoute: boolean;
+  isLoginPage: boolean;
+  searchParams: URLSearchParams;
+  sessionPointer: SessionPointer;
+  sessionStatus: SessionStatus;
+  circuitBreakerOpen: boolean;
+}
+
+export interface SessionPointer {
+  exists: boolean;
+  /** PAY-1481: tokenLogId of the session token (presence + log correlation), never the token itself. */
+  sessionTokenId?: string | null;
+  expired?: boolean;
+  hasRefreshToken?: boolean;
+  roles: string[];
+  clientId: string;
+}
+
+/** PAY-2339: which check could not answer. A fixed, machine-readable value: consumers never parse message text. */
+export type UnavailableCheck = 'revocation' | 'viability';
+
+export interface SessionStatus {
+  exists: boolean | null;       // null = check failed/timeout
+  forceInvalid: boolean | null; // null = check failed/timeout
+  /** PAY-2339: the revocation backend could not answer and this app HOLDS (revocationFailMode 'hold'): no sign-out. */
+  unavailable?: boolean;
+  requires2FA: boolean;
+  twoFactorComplete: boolean;
+}
+
+export type AuthAction =
+  | { type: 'allow' }
+  | { type: 'redirect'; location: string; reason: string; clearCookies?: boolean }
+  | { type: 'service_error'; reason: string; check?: UnavailableCheck }
+  | { type: 'refresh_needed' };
+
+// =============================================================================
+// CIRCUIT BREAKER INTERFACE
+// =============================================================================
+
+/**
+ * Circuit breaker interface for middleware integration.
+ * Implement this to provide custom circuit breaker behavior.
+ */
+export interface CircuitBreakerProvider {
+  /** Check if circuit breaker is currently open */
+  isOpen(): boolean;
+  /** Check if a refresh attempt is allowed (for HALF_OPEN state) */
+  canAttemptRefresh(): boolean;
+  /** Record a successful operation (closes the breaker) */
+  recordSuccess(): void;
+  /** Record a failed operation (may open the breaker) */
+  recordFailure(error?: Error): void;
+  /** Check if an error is a network error (vs HTTP error) */
+  isNetworkError(error: any): boolean;
+}
+
+/**
+ * Logger interface for middleware.
+ * Implement this to provide custom logging.
+ */
+export interface MiddlewareLogger {
+  info(message: string, data?: Record<string, any>): void;
+  warn(message: string, data?: Record<string, any>): void;
+  error(message: string, data?: Record<string, any>): void;
+}
+
+/**
+ * Configuration options for createMvpMiddleware
+ */
+export interface MvpMiddlewareOptions {
+  /** Custom circuit breaker implementation */
+  circuitBreaker?: CircuitBreakerProvider;
+  /** Custom logger implementation */
+  logger?: MiddlewareLogger;
+  /** Custom viability check endpoint (default: /api/session/viability) */
+  viabilityEndpoint?: string;
+  /** Custom refresh endpoint (default: /api/auth/refresh) */
+  refreshEndpoint?: string;
+  /** Hook called on successful refresh */
+  onRefreshSuccess?: () => void;
+  /** Hook called on refresh failure */
+  onRefreshFailure?: (status: number, isNetworkError: boolean) => void;
+  /** Additional paths to bypass middleware (beyond /api/auth/ and /api/session/) */
+  bypassPaths?: string[];
+  /** Paths exempt from RBAC checks (auth still enforced, just no page-permission check) */
+  rbacExemptPaths?: string[];
+  /**
+   * PAY-2218 - send a page's session-ending redirect through the session-reset ROUTE instead of clearing the
+   * cookies in the middleware response. Next strips the router's prefetch headers before middleware runs
+   * (15.5.x and 16.x; 16.2.x restores them only with `skipProxyUrlNormalize: true`), so a middleware clear also
+   * fires on a router PREFETCH and signs the user out of a page they never opened. The route sees those headers.
+   *
+   * Requires the app to mount the route:  app/api/auth/session-reset/route.ts
+   *     export { GET } from '@payez/next-mvp/routes/auth/session-reset';
+   * `true` uses that default path; a string names another mount point under /api/auth/ (middleware bypasses it).
+   * Needs BETTER_AUTH_SECRET (or NEXTAUTH_SECRET) to sign the hand-off; without one the direct clear is kept and
+   * an error is logged once. Default: off (the direct clear), because an unmounted route would 404 every sign-out.
+   */
+  sessionResetRoute?: boolean | string;
+  /**
+   * PAY-1882 step 4 / PAY-2339 - how this app treats a producer that reports the session's
+   * revocation status as `'unknown'` (a Vibe read that FAILED: non-OK, timeout,
+   * throw - the status could not be determined).
+   *
+   *   'hold' (DEFAULT since PAY-2339, Jon 2026-10-13, option C) - the member is NOT signed out. The request is
+   *                        answered "temporarily unavailable": a page goes to /service-unavailable?callbackUrl=
+   *                        (the session cookie is NOT touched, so "Try again" returns the member still signed in);
+   *                        an /api request gets a 503 carrying `unavailable: true` and `check: 'revocation'`, a
+   *                        fixed machine-readable value. Nothing protected is served while the answer is unknown.
+   *                        Each held request logs one countable `revocation_unavailable` line.
+   *                        THIS REPLACES THE OLD DEFAULT: the PAY-1880 ruling (Jon, 2026-09-27, option A) made
+   *                        'closed' the default and accepted that a Vibe outage signs an app's users out. That
+   *                        sentence no longer applies to 'unknown' by default: a Vibe outage no longer signs members
+   *                        out unless the app asks for 'closed'. 'revoked' is unchanged.
+   *   'closed'           - an unknown revocation status is NOT viable; the session is force-invalidated and the
+   *                        user re-auths (TODAY'S sign-out, now opt-in by name). Consequence, accepted explicitly:
+   *                        a Vibe outage signs this app's users out.
+   *   'open'             - an unknown status stays viable (availability over fail-closed). Per-app opt-out for a
+   *                        deployment with no revocation source.
+   *
+   * `'not_configured'` is UNCHANGED under the default: it is a configuration fault, not an outage, so it still
+   * force-invalidates exactly as before (a "try again" page would be false); `noRevocationSource` is the only way
+   * to make it viable. Neither mode changes `'revoked'` (always force-invalid, unchanged) or an ABSENT
+   * `revocationStatus` (an older producer - unchanged behaviour, so no consumer is signed out for not
+   * implementing the check). A consumer that wrote 'closed' or 'open' by name keeps exactly what it asked for.
+   */
+  revocationFailMode?: 'hold' | 'closed' | 'open';
+
+  /**
+   * PAY-2339 (BAPert 74640): where a page request goes while a revocation answer is held. DEFAULT (absent): the
+   * middleware answers inline with a minimal 503 HTML page ("Temporarily unavailable", a "Try again" link to the safe
+   * callback, no Set-Cookie), so a consumer that never added a page cannot get a 404. Name a same-site path (e.g.
+   * '/service-unavailable') to redirect there instead with `?callbackUrl=`; the consumer then mounts
+   * `export { default } from '@payez/next-mvp/pages/service-unavailable'` (or its own page) at that route.
+   */
+  unavailablePage?: string;
+
+  /**
+   * PAY-2302 cut 1c (BAPert 73585): this app has NO revocation source - for example a development environment
+   * provisioned without a vibe client id / HMAC key - and says so EXPLICITLY. Under it a viability answer of
+   * `revocationStatus: 'not_configured'` is viable, and a loud warning is logged once at startup.
+   *
+   * It relaxes ONLY 'not_configured'. 'unknown' (a revocation read that FAILED) and 'revoked' stay closed whatever
+   * `revocationFailMode` says, and the default (option absent) is unchanged: 'not_configured' fails closed, because
+   * for an app that HAS a vibe client it means a misconfiguration (BAPert 66356). Do not use this to paper over a
+   * misconfigured production app; remove it when the environment has a vibe client + HMAC key.
+   */
+  noRevocationSource?: boolean;
+}
+
+// =============================================================================
+// DEFAULT IMPLEMENTATIONS
+// =============================================================================
+
+/** Default no-op circuit breaker (always closed) */
+const defaultCircuitBreaker: CircuitBreakerProvider = {
+  isOpen: () => false,
+  canAttemptRefresh: () => true,
+  recordSuccess: () => {},
+  recordFailure: () => {},
+  isNetworkError: (error: any) => {
+    return error?.cause?.code === 'ECONNREFUSED' ||
+           error?.code === 'ECONNREFUSED' ||
+           error?.message?.includes('ECONNREFUSED') ||
+           error?.message?.includes('fetch failed') ||
+           error?.message?.includes('ENOTFOUND') ||
+           error?.message?.includes('ETIMEDOUT') ||
+           error?.message?.includes('ECONNRESET');
+  }
+};
+
+/** Default console logger */
+const defaultLogger: MiddlewareLogger = {
+  info: (msg, data) => console.log(`[MIDDLEWARE] ${msg}`, data || ''),
+  warn: (msg, data) => console.warn(`[MIDDLEWARE] ${msg}`, data || ''),
+  error: (msg, data) => console.error(`[MIDDLEWARE] ${msg}`, data || ''),
+};
+
+// =============================================================================
+// HELPERS
+// =============================================================================
+
+const LOGIN_PAGE = '/account-auth/login';
+const VERIFY_CODE_PAGE = '/account-auth/verify-code';
+
+// PAY-2315 (4.7.1): /login is a public alias of the login page. It used to take the 'public: allow' arm and never reached the
+// 'already_authenticated' redirect, so a signed-in user was shown the sign-in form. It is the login page for every arm now.
+// (safe-callback refuses /login as a destination, so this cannot redirect to itself.)
+const LOGIN_ALIAS = '/login';
+
+function isLoginPage(pathname: string): boolean {
+  return pathname === LOGIN_PAGE || pathname === LOGIN_ALIAS;
+}
+
+/**
+ * Ensures callback URLs never point to auth pages (prevents redirect loops) AND
+ * never point off-origin (prevents open redirect).
+ *
+ * 375656: the previous body tested `pathname` FIRST and returned '/' early, so
+ * the two call sites that pass an attacker-controlled `searchParams` are both
+ * inside `if (onLoginPage)` branches - and `isLoginPage` is exact equality against
+ * `LOGIN_PAGE`, which starts with `/account-auth/`. The early return therefore
+ * fired before the parameter was ever read. That made this function SAFE, but
+ * safe because of which argument the caller happened to pass, not because the
+ * attacker-controlled value was ever checked: `existing` was returned raw on the
+ * strength of a `startsWith` test that `https://evil.example.com` passes.
+ * Nothing named that dependency, and reordering the arguments would have opened
+ * it silently. Both inputs are now validated by the same parser-based guard.
+ */
+function getSafeCallbackUrl(pathname: string, searchParams?: URLSearchParams): string {
+  return resolveCallbackDestination(pathname, searchParams);
+}
+
+/**
+ * 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;
+  expireSessionCookies(response, Array.from(request.cookies, ([name]) => name));
+}
+
+/** Create redirect response, optionally clearing cookies */
+function redirectTo(
+  request: NextRequest,
+  location: string,
+  clearCookies = false
+): NextResponse {
+  const response = NextResponse.redirect(new URL(location, request.url));
+  if (clearCookies) {
+    clearSessionCookies(response, request);
+  }
+  return response;
+}
+
+/** PAY-2218: where a page's clearing redirect goes when the app has mounted the session-reset route. */
+interface ResetConfig {
+  route: string;
+  secret: string;
+}
+
+/**
+ * A redirect that must also END the session. With the reset route configured, a page request is sent through it
+ * WITHOUT any Set-Cookie here: the route sees the flight headers this middleware cannot (Next strips them before
+ * middleware), answers a prefetch 204 + no-store, and clears on the real navigation. `/api/` requests and apps
+ * without the route keep the direct clear exactly as before.
+ */
+async function clearingRedirect(request: NextRequest, location: string, reset?: ResetConfig): Promise<NextResponse> {
+  if (!reset || request.nextUrl.pathname.startsWith('/api/')) {
+    return redirectTo(request, location, true);
+  }
+  const target = new URL(location, request.url);
+  const params = normaliseResetParams({
+    callbackUrl: target.searchParams.get('callbackUrl'),
+    reason: target.searchParams.get('reason'),
+    error: target.searchParams.get('error'),
+  });
+  // Bound to THIS request's session cookie: the route clears only when its own request carries the same one.
+  const bound = boundSessionCookie((n) => request.cookies.get(n)?.value, getSessionCookieName(), getSecureSessionCookieName());
+  const response = NextResponse.redirect(new URL(await signedResetHref(reset.route, params, reset.secret, bound), request.url));
+  response.headers.set('cache-control', 'no-store');
+  return response;
+}
+
+/**
+ * Terminal response for a FAILED token refresh.
+ *
+ * For `/api/` requests a redirect is the wrong terminator: fetch() follows the 307,
+ * receives 200 + an HTML login page, and the caller parses garbage instead of
+ * branching on an error. Those callers get a 401 JSON body they can branch on;
+ * document requests keep the existing redirect exactly as before.
+ *
+ * Cookie-clearing is preserved on BOTH arms. That is load-bearing, not incidental:
+ * on a permanent failure (401/403) stale cookies must be cleared or the next request
+ * refreshes again and loops (see the CRITICAL note in handleRefresh). A JSON arm that
+ * skipped clearing would convert a redirect loop into a silent refresh loop.
+ *
+ * Scoped deliberately to handleRefresh's failure exits. It is NOT folded into
+ * redirectTo(), and NOT hoisted above the refresh decision: an `/api/` hatch placed
+ * higher would intercept 'refresh_needed' and disable middleware token refresh across
+ * the whole API surface (card 340024 C1).
+ */
+async function refreshFailureResponse(
+  request: NextRequest,
+  location: string,
+  errorCode: string,
+  clearCookies = false,
+  reset?: ResetConfig
+): Promise<NextResponse> {
+  if (request.nextUrl.pathname.startsWith('/api/')) {
+    const response = NextResponse.json({ error: errorCode }, { status: 401 });
+    if (clearCookies) {
+      clearSessionCookies(response, request);
+    }
+    return response;
+  }
+  return clearCookies ? clearingRedirect(request, location, reset) : redirectTo(request, location);
+}
+
+/**
+ * PAY-2147: the terminal answer when the middleware CANNOT TELL whether the session is good
+ * (circuit breaker open, a half-open breaker refusing a refresh attempt, or the viability read failed).
+ *
+ * "I could not check" is not a verdict on the session, so this NEVER touches a cookie: a transient blip
+ * in the IdP / viability path used to wipe the session of every user who made any request while the
+ * breaker was open. Cookies are cleared only on a POSITIVE signal (force_invalidated, stale_session,
+ * pre_2fa_token_expired, refresh 401/403, explicit sign-out) - never from here.
+ *
+ *  - /api/*  -> 503 JSON a caller can branch on (a redirect would be followed by fetch() into a 200 HTML page).
+ *  - pages   -> /service-unavailable (public + allowDuringCircuitBreakerOpen, so it cannot loop), carrying the
+ *               requested path as `callbackUrl` so "Try again" returns the user to it still signed in. The path goes
+ *               through safeCallbackPath (URL-parser origin check): an off-origin or auth-surface value is dropped.
+ */
+function serviceUnavailableResponse(request: NextRequest, check: UnavailableCheck = 'viability', unavailablePage?: string): NextResponse {
+  const { pathname, search } = request.nextUrl;
+  if (pathname.startsWith('/api/')) {
+    // PAY-2339 P1/P12: one fixed machine-readable shape for every "could not check" answer. No protected data.
+    return NextResponse.json({ error: 'ServiceUnavailable', unavailable: true, check }, { status: 503 });
+  }
+  const callback = safeCallbackPath(pathname + search);
+  // PAY-2339 (BAPert 74640, P13): a HELD revocation answer needs no page in the consumer. Unless the app names its own
+  // page (`unavailablePage`), the middleware answers inline: a minimal 503 HTML, a "try again" link to the safe
+  // callback, and no Set-Cookie (nothing here touches the session). No redirect, so no 404 is possible.
+  // `unavailablePage` is accepted only as a PLAIN path ([A-Za-z0-9_-/]; no query, fragment, %-encoding, dot segment or
+  // scheme), so the self-check below compares like with like and a mis-set value falls back to the inline page (Scout 74668).
+  // PAY-2345: the viability-FAILURE arm (500 / timeout / breaker) takes the same path, so an app with no page of its own
+  // gets the inline 503 instead of a 404 during an outage. The two arms differ only in `check` (JSON body for /api/*). If the
+  // request is already FOR the named page (an app that did not register it as public), answer inline: redirecting to
+  // it again would loop with a longer callbackUrl each time (QAPert 74651).
+  const named = unavailablePage && /^\/[A-Za-z0-9_\-\/]*$/.test(unavailablePage) && !unavailablePage.includes('//') ? unavailablePage : null;
+  if (!named || pathname.replace(/\/+$/, '') === named.replace(/\/+$/, '')) {
+    const href = callback.replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;');
+    return new NextResponse(
+      '<!doctype html><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>Temporarily unavailable</title>' +
+        '<main role="status" style="font-family:system-ui,sans-serif;max-width:28rem;margin:20vh auto;padding:0 1rem;text-align:center">' +
+        '<h1 style="font-size:1.25rem">Temporarily unavailable</h1>' +
+        '<p>' + (check === 'revocation' ? 'We could not check your session just now. You are still signed in.' : 'We could not reach the sign-in service just now. Please try again.') + '</p>' +
+        '<p><a href="' + href + '">Try again</a></p></main>',
+      { status: 503, headers: { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store', 'retry-after': '30' } },
+    );
+  }
+  const target = new URL(named || '/service-unavailable', request.url);
+  if (callback !== '/') target.searchParams.set('callbackUrl', callback);
+  return NextResponse.redirect(target);
+}
+
+// =============================================================================
+// AUTH DECISION ENGINE
+// =============================================================================
+
+/**
+ * Pure function that determines what action to take based on auth state.
+ * No side effects - just examines context and returns a decision.
+ */
+function makeAuthDecision(ctx: AuthContext): AuthAction {
+  const { pathname, isPublicRoute, isLoginPage: onLoginPage, searchParams, sessionPointer, sessionStatus, circuitBreakerOpen } = ctx;
+  const safeCallback = getSafeCallbackUrl(pathname);
+
+  // --- PAY-884: a provisional (pre-2FA) session whose token has expired can never finish 2FA ---
+  // The IdP issues no refresh token until 2FA completes, and it validates token lifetime, so
+  // once the provisional access token expires neither refresh nor code verification can
+  // succeed. Sending the user to the verify-code page (or to error=SessionExpired, which the
+  // login page deliberately shows as NO message) strands them mid-2FA with no explanation.
+  // Say what happened instead, and clear the dead session so the next sign-in starts clean.
+  // Scoped to the verify-code page and protected pages: /api/ keeps its 401-JSON carve-out
+  // (307290), the login page stays reachable, and public pages are left to the existing arms.
+  if (
+    isExpiredProvisionalSession(sessionPointer, sessionStatus) &&
+    !pathname.startsWith('/api/') &&
+    !onLoginPage &&
+    (pathname === VERIFY_CODE_PAGE || !isPublicRoute)
+  ) {
+    const callback = pathname === VERIFY_CODE_PAGE ? getSafeCallbackUrl(pathname, searchParams) : safeCallback;
+    return {
+      type: 'redirect',
+      location: `${LOGIN_PAGE}?callbackUrl=${encodeURIComponent(callback)}&error=${TWO_FACTOR_TIMEOUT_ERROR}`,
+      reason: 'pre_2fa_token_expired',
+      clearCookies: true,
+    };
+  }
+
+  // --- Public routes: Allow, but enforce 2FA for authenticated users ---
+  if (isPublicRoute && !onLoginPage) {
+    if (needsTwoFactorRedirect(pathname, sessionPointer, sessionStatus)) {
+      return redirect2FA(safeCallback);
+    }
+    return { type: 'allow' };
+  }
+
+  // --- Circuit breaker open: Service degraded ---
+  // PAY-2147: the breaker opening says the IdP/viability path is unreachable, NOT that the session is bad.
+  // Answer "service unavailable" (503 for /api, /service-unavailable for pages) and leave every cookie alone.
+  if (circuitBreakerOpen) {
+    if (onLoginPage) return { type: 'allow' };
+    return { type: 'service_error', reason: 'circuit_breaker_open' };
+  }
+
+  // --- No session cookie: Need to login ---
+  if (!sessionPointer.exists) {
+    if (onLoginPage) return { type: 'allow' };
+    if (pathname === '/') {
+      const unauthUrl = process.env.UNAUTHENTICATED_REDIRECT_URL || '/account-auth/login';
+      return { type: 'redirect', location: unauthUrl, reason: 'unauthenticated_root' };
+    }
+    if (pathname.startsWith('/api/')) {
+      return { type: 'allow' }; // Let API return proper 401 JSON
+    }
+    return {
+      type: 'redirect',
+      location: `${LOGIN_PAGE}?callbackUrl=${encodeURIComponent(safeCallback)}`,
+      reason: 'no_session'
+    };
+  }
+
+  // --- Service error: Can't verify session ---
+  if (sessionStatus.exists === null || sessionStatus.forceInvalid === null) {
+    if (onLoginPage) return { type: 'allow' }; // the login page must stay reachable while the check is down
+    return { type: 'service_error', reason: 'viability_check_failed' };
+  }
+
+  // --- PAY-2339: the revocation backend could not answer and this app HOLDS (the default) ---
+  // Not a verdict on the session: no cookie is touched, nothing protected is served, and the answer says why in a
+  // fixed machine-readable form. The login page stays reachable.
+  if (sessionStatus.unavailable) {
+    if (onLoginPage) return { type: 'allow' };
+    return { type: 'service_error', reason: 'revocation_unknown', check: 'revocation' };
+  }
+
+  // --- Session force-invalidated (admin action, password change, etc.) ---
+  if (sessionStatus.forceInvalid) {
+    if (onLoginPage) return { type: 'allow' };
+    if (pathname.startsWith('/api/')) return { type: 'allow' };
+    return {
+      type: 'redirect',
+      location: `${LOGIN_PAGE}?callbackUrl=${encodeURIComponent(safeCallback)}&reason=invalidated`,
+      reason: 'force_invalidated',
+      clearCookies: true
+    };
+  }
+
+  // --- Stale session (cookie exists but Redis entry gone) ---
+  if (!sessionStatus.exists) {
+    if (onLoginPage) return { type: 'allow' };
+    if (pathname.startsWith('/api/')) return { type: 'allow' };
+    return {
+      type: 'redirect',
+      location: `${LOGIN_PAGE}?callbackUrl=${encodeURIComponent(safeCallback)}&reason=stale`,
+      reason: 'stale_session',
+      clearCookies: true
+    };
+  }
+
+  // --- 2FA required but not completed ---
+  if (needsTwoFactorRedirect(pathname, sessionPointer, sessionStatus)) {
+    if (onLoginPage) {
+      const cb = getSafeCallbackUrl(pathname, searchParams);
+      return { type: 'redirect', location: `${VERIFY_CODE_PAGE}?callbackUrl=${encodeURIComponent(cb)}`, reason: '2fa_from_login' };
+    }
+    return redirect2FA(safeCallback);
+  }
+
+  // --- Token expired: Try refresh ---
+  if (sessionPointer.expired) {
+    if (onLoginPage) return { type: 'allow' };
+    if (sessionPointer.hasRefreshToken) {
+      return { type: 'refresh_needed' };
+    }
+    // 307290: this is the TERMINAL arm of the expired branch - refresh is not
+    // possible here, so the only outcomes are "redirect" or "allow". Every other
+    // terminal branch in this function (:242 no_session, :259 force_invalidated,
+    // :271 stale_session, :318 2FA-incomplete) already exempts /api/ so the route
+    // can answer with a real 401 JSON; this one did not, and redirecting an API
+    // request to an HTML login page makes the failure INVISIBLE - fetch() follows
+    // the 307, gets 200 HTML, resolves successfully and parses garbage.
+    // MUST stay BELOW the hasRefreshToken check above: placed any higher it would
+    // intercept 'refresh_needed' and disable middleware token refresh for the
+    // entire API surface.
+    if (pathname.startsWith('/api/')) return { type: 'allow' }; // Let API return proper 401 JSON
+    return {
+      type: 'redirect',
+      location: `${LOGIN_PAGE}?callbackUrl=${encodeURIComponent(safeCallback)}&error=SessionExpired`,
+      reason: 'token_expired_no_refresh'
+    };
+  }
+
+  // --- Authenticated user on login page: Send to their destination ---
+  if (onLoginPage) {
+    const dest = getSafeCallbackUrl(pathname, searchParams);
+    return { type: 'redirect', location: dest, reason: 'already_authenticated' };
+  }
+
+  // --- All checks passed ---
+  return { type: 'allow' };
+}
+
+/** Login error code for a pre-2FA session that expired before the code was verified (PAY-884). */
+export const TWO_FACTOR_TIMEOUT_ERROR = 'TwoFactorTimeout';
+
+/**
+ * PAY-884: 2FA outstanding, access token expired, and no refresh token to renew it.
+ * Only a viability answer that positively says the session exists qualifies (null = check failed).
+ */
+function isExpiredProvisionalSession(session: SessionPointer, status: SessionStatus): boolean {
+  return (
+    session.exists &&
+    status.exists === true &&
+    status.forceInvalid === false &&
+    status.requires2FA &&
+    !status.twoFactorComplete &&
+    session.expired === true &&
+    !session.hasRefreshToken
+  );
+}
+
+/** Check if user needs 2FA redirect */
+function needsTwoFactorRedirect(pathname: string, session: SessionPointer, status: SessionStatus): boolean {
+  if (!session.exists || !status.exists) return false;
+  if (!status.requires2FA || status.twoFactorComplete) return false;
+  if (pathname === VERIFY_CODE_PAGE) return false;
+  if (should2FABypass(pathname)) return false;
+  if (pathname.startsWith('/api/')) return false; // APIs return JSON errors
+  return true;
+}
+
+function redirect2FA(callbackUrl: string): AuthAction {
+  return {
+    type: 'redirect',
+    location: `${VERIFY_CODE_PAGE}?callbackUrl=${encodeURIComponent(callbackUrl)}`,
+    reason: '2fa_required'
+  };
+}
+
+// =============================================================================
+// MIDDLEWARE FACTORY
+// =============================================================================
+
+/** PAY-2218: the stripped-flight-headers warning is logged once per process, not once per request. */
+let flightHeadersStrippedWarned = false;
+
+export function createMvpMiddleware(options: MvpMiddlewareOptions = {}) {
+  // Resolve options with defaults
+  const cb = options.circuitBreaker || defaultCircuitBreaker;
+  const log = options.logger || defaultLogger;
+  const viabilityEndpoint = options.viabilityEndpoint || '/api/session/viability';
+  const refreshEndpoint = options.refreshEndpoint || '/api/auth/refresh';
+  const bypassPaths = options.bypassPaths || [];
+  const rbacExemptPaths = options.rbacExemptPaths || [];
+  // PAY-2339: the default is 'hold' (Jon 2026-10-13, option C): an unknown revocation answer does not sign the member
+  // out. PAY-1882 step 4 had 'closed' (Jon's PAY-1880 option A, BAPert 66316); it is now opt-in by name.
+  const revocationFailMode = options.revocationFailMode || 'hold';
+  // PAY-2302 cut 1c: strictly `=== true`, so a truthy string in a config file cannot switch revocation off.
+  const noRevocationSource = options.noRevocationSource === true;
+  if (noRevocationSource) {
+    log.warn(
+      '[next-mvp] noRevocationSource is ON: sessions of this app CANNOT be revoked server-side (no vibe client / HMAC key). ' +
+      "revocationStatus 'not_configured' is treated as viable; 'unknown' and 'revoked' still sign the user out. " +
+      'Remove this option once the environment has a vibe client id and HMAC key.'
+    );
+  }
+  const sessionResetRoute =
+    options.sessionResetRoute === true ? DEFAULT_SESSION_RESET_ROUTE
+    : typeof options.sessionResetRoute === 'string' && options.sessionResetRoute ? options.sessionResetRoute
+    : undefined;
+  let resetSecretMissingLogged = false;
+  const resolveReset = (): ResetConfig | undefined => {
+    if (!sessionResetRoute) return undefined;
+    const secret = resetSecret();
+    if (secret) return { route: sessionResetRoute, secret };
+    if (!resetSecretMissingLogged) {
+      resetSecretMissingLogged = true;
+      log.error('sessionResetRoute is set but no BETTER_AUTH_SECRET/NEXTAUTH_SECRET is available to sign the hand-off; clearing in middleware instead', { sessionResetRoute });
+    }
+    return undefined;
+  };
+
+  return async function middleware(request: NextRequest): Promise<NextResponse> {
+    const { pathname, searchParams } = request.nextUrl;
+
+    // =========================================================================
+    // CRITICAL: Auth routes MUST bypass middleware
+    // =========================================================================
+    // These routes are called internally by middleware itself (viability check,
+    // token refresh). Without this bypass, we get infinite loops or 403s.
+    // This has caused production outages. DO NOT REMOVE.
+    // =========================================================================
+    if (pathname.startsWith('/api/auth/') || pathname.startsWith('/api/session/')) {
+      return NextResponse.next();
+    }
+
+    // Check custom bypass paths
+    for (const bypassPath of bypassPaths) {
+      if (pathname.startsWith(bypassPath)) {
+        return NextResponse.next();
+      }
+    }
+
+    // PAY-2218: a router request (it carries `next-url`) that arrives WITHOUT `rsc` had its flight headers stripped
+    // by Next before middleware ran, so isPrefetchRequest() cannot see a router prefetch on this app. Say so once.
+    if (!sessionResetRoute && !flightHeadersStrippedWarned && request.headers.has('next-url') && !request.headers.has('rsc')) {
+      flightHeadersStrippedWarned = true;
+      log.warn('Next strips router prefetch headers before middleware on this app, so a session-ending redirect can fire on a prefetch. Mount @payez/next-mvp/routes/auth/session-reset and set sessionResetRoute (PAY-2218).', { pathname });
+    }
+
+    const isPublic = isUnauthenticatedRoute(pathname);
+    const isLogin = isLoginPage(pathname);
+
+    // --- Optimization: Skip viability check for unauthenticated public browsing ---
+    if (isPublic && !isLogin) {
+      const hasCookie = request.cookies.get(getSessionCookieName())?.value ||
+                        request.cookies.get(getSecureSessionCookieName())?.value;
+      if (!hasCookie) {
+        return NextResponse.next();
+      }
+      // Has cookie - continue to viability check for 2FA enforcement
+    }
+
+    // --- Fetch session viability from internal API ---
+    const { sessionStatus, sessionPointer } = await checkViability(
+      request,
+      viabilityEndpoint,
+      log,
+      revocationFailMode,
+      noRevocationSource
+    );
+
+    // --- Stale session (cookie exists but session doesn't): OBSERVE ONLY, DO NOT DECIDE ---
+    //
+    // *** CARD 349607. THIS BLOCK USED TO `return` HERE, AND THAT RETURN WAS A BYPASS. ***
+    //
+    // makeAuthDecision() below already handles this exact condition at its
+    // `if (!sessionStatus.exists)` branch, and it handles it with TWO guard
+    // clauses that this early return did not have:
+    //
+    //     if (onLoginPage)                 return { type: 'allow' };   // no redirect loop
+    //     if (pathname.startsWith('/api/'))return { type: 'allow' };   // no HTML 307 at fetch()
+    //
+    // Returning here skipped BOTH. The `/api/` case is the reported harm: a
+    // stale-session XHR was answered with a 307 to an HTML login page, so the
+    // failure is invisible to `fetch()` - the caller sees an opaque redirect
+    // instead of an auth error, which is the same "correct logic preempted by
+    // an earlier return" shape recorded on 307290.
+    //
+    // This was NOT a missing feature one level down - the decision engine's
+    // branch is a strict superset of the behaviour this block implemented.
+    // The early return was a DUPLICATE that had drifted from the original.
+    // Adding a single `/api/` exemption here would have re-created the
+    // duplication (and left the onLoginPage divergence in place), so the
+    // duplicate is removed instead and the engine is left as the ONE decider.
+    //
+    // The warning is deliberately KEPT: it is the only operational signal that
+    // stale sessions are occurring, and it costs nothing to log before
+    // delegating. Do not re-introduce a `return` in this block.
+    if (!isPublic && sessionStatus.exists === false && sessionPointer.sessionTokenId) {
+      // PAY-1505: the KEY is `sessionTokenId`, not `sessionToken`. The value has
+      // always been a tokenLogId fingerprint (viability.ts builds it as
+      // `tokenLogId(sessionToken)`), but labelling it `sessionToken` told any
+      // operator reading this log that the line carried the token itself. The
+      // credential-in-logs source guard reads the key for exactly that reason:
+      // a field named `sessionToken` must hold a safe value, and proving that
+      // across an API boundary is not possible from the name alone.
+      log.warn('Stale session detected (delegating to decision engine)', {
+        sessionTokenId: sessionPointer.sessionTokenId,
+        pathname
+      });
+    }
+
+    // --- Run decision engine ---
+    const decision = makeAuthDecision({
+      pathname,
+      isPublicRoute: isPublic,
+      isLoginPage: isLogin,
+      searchParams,
+      sessionPointer,
+      sessionStatus,
+      circuitBreakerOpen: cb.isOpen(),
+    });
+
+    // --- Execute decision ---
+    return executeDecision(request, decision, pathname, sessionPointer, sessionStatus, {
+      circuitBreaker: cb,
+      logger: log,
+      refreshEndpoint,
+      rbacExemptPaths,
+      reset: resolveReset(),
+      unavailablePage: options.unavailablePage,
+      onRefreshSuccess: options.onRefreshSuccess,
+      onRefreshFailure: options.onRefreshFailure,
+    });
+  };
+}
+
+/**
+ * The revocation decision, as a pure function (PAY-1882 step 4, NightHawk 66392).
+ *
+ * Separate + exported so the B1 defect is testable with a REAL mutant: the bug was
+ * that `data.forceInvalid === true` was read BEFORE revocationFailMode, so a
+ * producer that folds 'unknown' into forceInvalid made the 'open' lever dead.
+ *
+ * RULE: when the producer supplies `revocationStatus`, it is AUTHORITATIVE - the
+ * decision is made from it plus failMode, and the folded booleans are ignored for
+ * 'unknown'/'not_configured'. The booleans are read ONLY when revocationStatus is
+ * absent (idealresume.online's older boolean-only route).
+ */
+export type RevocationOutcome = 'viable' | 'invalid' | 'hold';
+
+/**
+ * PAY-2339: the three-way form of the revocation decision. `decideForceInvalid` below is kept as its boolean view.
+ *
+ *   'invalid' - sign the member out (cookies cleared, login page)
+ *   'hold'    - the backend could not answer and this app holds: no sign-out, answer "temporarily unavailable"
+ *   'viable'  - carry on
+ */
+export function decideRevocationOutcome(
+  data: { revocationStatus?: unknown; forceInvalid?: unknown; revoked?: unknown },
+  revocationFailMode: 'hold' | 'closed' | 'open',
+  noRevocationSource: boolean = false,
+): RevocationOutcome {
+  const status = data.revocationStatus;
+  if (typeof status === 'string') {
+    if (status === 'revoked') return 'invalid';
+    if (status === 'active') return 'viable';
+    // PAY-2302 cut 1c: an app that declared it has no revocation source. ONLY the exact 'not_configured' string.
+    if (status === 'not_configured' && noRevocationSource === true) return 'viable';
+    // PAY-2339: 'not_configured' is a configuration fault, not an outage. Under the default it stays signed out
+    // exactly as before; only 'open' relaxes it (a Vibe-less app).
+    if (status === 'not_configured') return revocationFailMode === 'open' ? 'viable' : 'invalid';
+    // S1 (NightHawk 66409): ANY other string - 'unknown', a typo like 'Revoked', 'error', or '' - is treated as
+    // 'unknown' (the fail mode applies), NEVER as 'active'. Only an explicit 'active' is viable.
+    if (revocationFailMode === 'open') return 'viable';
+    return revocationFailMode === 'closed' ? 'invalid' : 'hold';
+  }
+  // No revocationStatus: an older boolean producer. Absence of both stays viable.
+  return data.forceInvalid === true || data.revoked === true ? 'invalid' : 'viable';
+}
+
+export function decideForceInvalid(
+  data: { revocationStatus?: unknown; forceInvalid?: unknown; revoked?: unknown },
+  revocationFailMode: 'hold' | 'closed' | 'open',
+  noRevocationSource: boolean = false,
+): boolean {
+  return decideRevocationOutcome(data, revocationFailMode, noRevocationSource) === 'invalid';
+}
+
+/**
+ * PAY-2147: does the request carry a session cookie? Used ONLY when the viability read itself FAILED.
+ * Before this, a failed read left sessionPointer.exists=false, so the decision engine took its `no_session` arm
+ * (pages -> the LOGIN page, /api -> straight through) and its `exists === null` -> service_error arm below it was
+ * unreachable dead code: a user holding a perfectly good session was told to sign in during an outage. With a
+ * cookie present and the check down we do not know the session is bad, so the engine must say "service
+ * unavailable", not "sign in". No cookie -> unchanged (no_session).
+ */
+function hasSessionCookie(request: NextRequest): boolean {
+  return !!(request.cookies.get(getSessionCookieName())?.value || request.cookies.get(getSecureSessionCookieName())?.value);
+}
+
+/** Check session viability via internal API */
+async function checkViability(
+  request: NextRequest,
+  endpoint: string,
+  log: MiddlewareLogger,
+  revocationFailMode: 'hold' | 'closed' | 'open',
+  noRevocationSource: boolean = false
+): Promise<{
+  sessionStatus: SessionStatus;
+  sessionPointer: SessionPointer;
+}> {
+  const sessionStatus: SessionStatus = {
+    exists: false,
+    forceInvalid: false,
+    requires2FA: false,
+    twoFactorComplete: false,
+  };
+  const sessionPointer: SessionPointer = {
+    exists: false,
+    sessionTokenId: undefined,
+    expired: false,
+    hasRefreshToken: false,
+    roles: [],
+    clientId: '',
+  };
+
+  try {
+    const baseUrl = getInternalApiUrl(request);
+    const response = await fetch(new URL(endpoint, baseUrl), {
+      method: 'GET',
+      headers: {
+        'Accept': 'application/json',
+        'Cache-Control': 'no-store',
+        'Cookie': request.headers.get('cookie') || ''
+      },
+      credentials: 'include',
+      signal: AbortSignal.timeout(5000),
+    });
+
+    if (response.ok) {
+      const data = await response.json();
+      // Support both response formats (viability and refresh-viability)
+      sessionStatus.exists = data.authenticated ?? (!!data.sessionTokenId && data.reason !== 'session_not_found');
+      sessionStatus.requires2FA = data.requires2FA || false;
+      sessionStatus.twoFactorComplete = data.twoFactorComplete || false;
+      // --- Session revocation (PAY-1882 Step 4) ---
+      // Two producer spellings are honoured, because both exist on the wire:
+      //   - boolean `forceInvalid` / `revoked` (idealresume.online's route today)
+      //   - the three-state `revocationStatus` the package's own viability
+      //     handlers now emit (PAY-1882 step 4).
+      //
+      // RULING (Jon, via BAPert 66316): 'revoked' ALWAYS fails closed. 'unknown'
+      // (a FAILED Vibe read) fails closed by default and is the ONLY state that
+      // the per-app `revocationFailMode` option can relax to viable.
+      //
+      // Four producer states (BAPert 66320), with the fail-closed ruling for
+      // 'not_configured' added by BAPert 66356:
+      //   'active'         - Vibe read OK, not revoked  -> viable
+      //   'revoked'        - Vibe says revoked          -> force-invalid, ALWAYS
+      //   'unknown'        - read FAILED                -> force-invalid if 'closed'
+      //   'not_configured' - no revocation source       -> force-invalid if 'closed'
+      //
+      // WHY 'not_configured' FAILS CLOSED WHEN 'closed': both live consumers of
+      // this middleware (portal.keelauth.com / keelauth-portal, idealvibe.online)
+      // DO set IDP_URL + VIBE_CLIENT_ID + VIBE_HMAC_KEY (BAPert 66356, measured in
+      // their committed manifests + the graft pipeline's own secret check), so for
+      // them 'not_configured' can only mean a MISCONFIGURATION - revocation
+      // silently switched off is exactly the PAY-1880 fail-open bug. An app with
+      // no revocation source that genuinely wants availability sets
+      // revocationFailMode 'open'.
+      //
+      // A MISSING revocationStatus (an older producer) keeps today's behaviour,
+      // i.e. NOT force-invalid: absence must never sign out a population that
+      // never opted into the check.
+      //
+      // *** revocationStatus IS AUTHORITATIVE WHEN PRESENT (NightHawk 66392). ***
+      // The package's own producers emit `forceInvalid: revocationStatus ===
+      // 'revoked' || revocationStatus === 'unknown'`. If the boolean were read
+      // FIRST, `forceInvalid: true` would short-circuit before revocationFailMode
+      // was consulted, so `'open'` could never keep an 'unknown' session viable -
+      // the opt-out lever would be DEAD. So: when a producer supplies a
+      // revocations status, decide from it + failMode and ignore the folded
+      // booleans for unknown/not_configured. The booleans are read ONLY when
+      // revocationStatus is ABSENT (idealresume.online's older boolean route).
+      const outcome = decideRevocationOutcome(data, revocationFailMode, noRevocationSource);
+      sessionStatus.forceInvalid = outcome === 'invalid';
+      if (outcome === 'hold') {
+        sessionStatus.unavailable = true;
+        // PAY-2339 P11: one countable line per held request, naming the check. No session value, no address.
+        log.warn('revocation_unavailable', { check: 'revocation' });
+      }
+      // PAY-2216: a STALE session - the cookie resolved to a token, but no store holds the session - used to set
+      // pointer.exists=false, so makeAuthDecision took no_session (login, cookie NOT cleared) and its stale_session
+      // arm (clearCookies) was unreachable: a dead cookie lingered and re-ran viability on every request.
+      // Stale is a POSITIVE signal and needs ALL of: this 2xx read, exists === false, a sessionTokenId (every
+      // producer sets it only when a cookie resolved to a token: routes/auth/viability.ts, api-handlers/session/
+      // viability.ts, refresh-viability.ts 'session_not_found'), and a session cookie on THIS request (plain or
+      // __Secure-). A FAILED read never gets here (exists=null -> service_error, PAY-2147); a store error throws
+      // inside every producer and answers 5xx or 'unknown' WITHOUT a sessionTokenId; no cookie -> no_session.
+      const stale = sessionStatus.exists === false && !!data.sessionTokenId && hasSessionCookie(request);
+      sessionPointer.exists = stale ? true : (sessionStatus.exists ?? false);
+      sessionPointer.sessionTokenId = data.sessionTokenId ?? null;
+      sessionPointer.expired = data.accessTokenExpired || false;
+      sessionPointer.hasRefreshToken = data.hasRefreshToken ?? data.canRefresh ?? false;
+      sessionPointer.roles = data.roles || [];
+      sessionPointer.clientId = data.clientId || '';
+    } else {
+      log.error('Viability check failed', { status: response.status });
+      sessionStatus.exists = null;
+      sessionStatus.forceInvalid = null;
+      sessionPointer.exists = hasSessionCookie(request); // PAY-2147: see hasSessionCookie
+    }
+  } catch (error) {
+    log.error('Viability check error', { error: error instanceof Error ? error.message : String(error) });
+    sessionStatus.exists = null;
+    sessionStatus.forceInvalid = null;
+    sessionPointer.exists = hasSessionCookie(request); // PAY-2147: see hasSessionCookie
+  }
+
+  return { sessionStatus, sessionPointer };
+}
+
+/** Options passed to executeDecision */
+interface ExecuteOptions {
+  circuitBreaker: CircuitBreakerProvider;
+  logger: MiddlewareLogger;
+  refreshEndpoint: string;
+  rbacExemptPaths: string[];
+  /** PAY-2218: set when the app mounted the session-reset route AND a signing secret exists. */
+  reset?: ResetConfig;
+  /** PAY-2339: the app's named hold page; absent = the inline 503 HTML. */
+  unavailablePage?: string;
+  onRefreshSuccess?: () => void;
+  onRefreshFailure?: (status: number, isNetworkError: boolean) => void;
+}
+
+/** Execute the auth decision */
+async function executeDecision(
+  request: NextRequest,
+  decision: AuthAction,
+  pathname: string,
+  sessionPointer: SessionPointer,
+  sessionStatus: SessionStatus,
+  opts: ExecuteOptions
+): Promise<NextResponse> {
+  const safeCallback = getSafeCallbackUrl(pathname);
+
+  switch (decision.type) {
+    case 'allow':
+      return handleAllow(request, pathname, sessionPointer, sessionStatus, opts.rbacExemptPaths);
+
+    case 'redirect':
+      return decision.clearCookies
+        ? clearingRedirect(request, decision.location, opts.reset)
+        : redirectTo(request, decision.location);
+
+    case 'service_error':
+      return serviceUnavailableResponse(request, decision.check ?? 'viability', opts.unavailablePage);
+
+    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);
+  }
+}
+
+/** Paths that must never be RBAC-checked (they are RBAC redirect targets) */
+const RBAC_EXEMPT_PATHS = ['/error', '/unauthorized', '/service-unavailable'];
+
+/** Handle 'allow' decision - run RBAC if enabled */
+async function handleAllow(
+  request: NextRequest,
+  pathname: string,
+  sessionPointer: SessionPointer,
+  sessionStatus: SessionStatus,
+  rbacExemptPaths: string[] = []
+): Promise<NextResponse> {
+  const isPublic = isUnauthenticatedRoute(pathname);
+
+  // PAY-2216: RBAC needs a session that viability CONFIRMED. A stale /api request (pointer.exists only says the
+  // cookie is present, status.exists is false) is allowed through so the route handler answers its own 401 - not an
+  // RBAC 401 here. TRUTHY, not `=== true` (NightHawk 71960): status.exists carries the producer's JSON value as-is,
+  // and a consumer route may answer authenticated: 1 / "true"; `=== true` skipped RBAC for those healthy sessions
+  // (fail-OPEN). Truthy keeps 4.5.3's RBAC coverage exactly and still excludes stale (false) and a failed read (null).
+  if (isRBACEnabled() && !isPublic && sessionPointer.exists && sessionStatus.exists) {
+    // Skip RBAC for error/fallback pages (prevent redirect loops) and app-configured exempt paths
+    if (RBAC_EXEMPT_PATHS.some(p => pathname.startsWith(p)) ||
+        rbacExemptPaths.some(p => pathname.startsWith(p))) {
+      return NextResponse.next();
+    }
+
+    if (!sessionPointer.clientId) {
+      console.error('[MIDDLEWARE] RBAC: No clientId — returning 401');
+      if (pathname.startsWith('/api/')) {
+        return NextResponse.json(
+          { error: 'Unauthorized — missing clientId for RBAC' },
+          { status: 401 }
+        );
+      }
+      return NextResponse.redirect(new URL('/unauthorized', request.url));
+    }
+
+    try {
+      const result = await checkPagePermission(pathname, sessionPointer.roles, sessionPointer.clientId);
+
+      if (!result.allowed) {
+        console.log('[MIDDLEWARE] RBAC denied:', { pathname, reason: result.reason });
+
+        // In development, fail open - RBAC API may not be fully configured
+        if (process.env.NODE_ENV !== 'production') {
+          console.warn('[MIDDLEWARE] RBAC: Allowing in development despite denial:', result.reason);
+          return NextResponse.next();
+        }
+
+        return NextResponse.redirect(new URL(result.redirect || '/unauthorized', request.url));
+      }
+
+      if (result.requires_2fa && !sessionStatus.twoFactorComplete) {
+        return NextResponse.redirect(
+          new URL(`${VERIFY_CODE_PAGE}?callbackUrl=${encodeURIComponent(pathname)}`, request.url)
+        );
+      }
+    } catch (error) {
+      console.error('[MIDDLEWARE] RBAC error:', error);
+
+      // In development, fail open
+      if (process.env.NODE_ENV !== 'production') {
+        console.warn('[MIDDLEWARE] RBAC: Allowing in development despite error');
+        return NextResponse.next();
+      }
+
+      return NextResponse.redirect(new URL('/error?code=rbac_error', request.url));
+    }
+  }
+
+  return NextResponse.next();
+}
+
+/** Handle token refresh */
+async function handleRefresh(
+  request: NextRequest,
+  safeCallback: string,
+  opts: ExecuteOptions
+): Promise<NextResponse> {
+  const { circuitBreaker: cb, logger: log, refreshEndpoint, onRefreshSuccess, onRefreshFailure } = opts;
+
+  // Check if circuit breaker allows refresh attempt
+  if (!cb.canAttemptRefresh()) {
+    log.warn('Circuit breaker preventing refresh attempt');
+    // PAY-2147: a breaker that merely declines to TRY a refresh has learned nothing about the session; wiping the
+    // cookies here logged out every user on the first request after a blip (HALF_OPEN refuses all but one probe).
+    return serviceUnavailableResponse(request, 'viability', opts.unavailablePage);
+  }
+
+  try {
+    const baseUrl = getInternalApiUrl(request);
+    const response = await fetch(new URL(refreshEndpoint, baseUrl), {
+      method: 'POST',
+      headers: {
+        'Accept': 'application/json',
+        'Content-Type': 'application/json',
+        'Cookie': request.headers.get('cookie') || '',
+        'x-session-token': request.cookies.get(getSessionCookieName())?.value ||
+                           request.cookies.get(getSecureSessionCookieName())?.value || ''
+      },
+      credentials: 'include',
+      signal: AbortSignal.timeout(5000),
+    });
+
+    if (response.ok) {
+      const data = await response.json();
+      if (data.refreshed || data.reason === 'already_fresh') {
+        cb.recordSuccess();
+        onRefreshSuccess?.();
+        log.info('Token refresh successful');
+        return NextResponse.next();
+      }
+    }
+
+    // Refresh failed - check for permanent failures (401/403) vs transient (5xx)
+    // CRITICAL: Always clear cookies on 401/403 to prevent redirect loops
+    // CRITICAL: Only record circuit breaker failures for network errors, not HTTP errors
+    // HTTP 500 means the server responded - it's reachable. Only network failures should trip the breaker.
+    const isPermanentFailure = response.status === 401 || response.status === 403;
+    const errorParam = isPermanentFailure ? 'SessionExpired' : 'RefreshError';
+
+    log.warn('Refresh failed', {
+      status: response.status,
+      isPermanentFailure,
+      clearingCookies: isPermanentFailure
+    });
+
+    onRefreshFailure?.(response.status, false);
+
+    return refreshFailureResponse(
+      request,
+      `${LOGIN_PAGE}?callbackUrl=${encodeURIComponent(safeCallback)}&error=${errorParam}`,
+      errorParam,
+      isPermanentFailure,
+      opts.reset
+    );
+  } catch (error: any) {
+    const isNetwork = cb.isNetworkError(error);
+    log.error('Refresh error', {
+      error: error instanceof Error ? error.message : String(error),
+      isNetworkError: isNetwork
+    });
+
+    // Only record circuit breaker failure for actual network errors
+    if (isNetwork) {
+      cb.recordFailure(error);
+    }
+
+    onRefreshFailure?.(0, isNetwork);
+
+    // Network error - don't clear cookies, might be transient
+    return refreshFailureResponse(
+      request,
+      `${LOGIN_PAGE}?callbackUrl=${encodeURIComponent(safeCallback)}&error=RefreshError`,
+      'RefreshError',
+      false
+    );
+  }
+}
+