@payez/next-mvp 4.7.9 → 4.8.0

package/src/middleware/create-middleware.ts

@@ -57,9 +57,14 @@ export interface SessionPointer {
   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;
 }
@@ -67,7 +72,7 @@ export interface SessionStatus {
 export type AuthAction =
   | { type: 'allow' }
   | { type: 'redirect'; location: string; reason: string; clearCookies?: boolean }
-  | { type: 'service_error'; reason: string }
+  | { type: 'service_error'; reason: string; check?: UnavailableCheck }
   | { type: 'refresh_needed' };
 
 // =============================================================================
@@ -135,29 +140,42 @@ export interface MvpMiddlewareOptions {
    */
   sessionResetRoute?: boolean | string;
   /**
-   * PAY-1882 step 4 - how this app treats a producer that reports the session's
+   * 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).
    *
-   *   'closed' (DEFAULT) - an unknown revocation status is NOT viable; the
-   *                        session is force-invalidated and the user re-auths.
-   *                        This is Jon's PAY-1880 ruling (option A, fail closed),
-   *                        2026-09-27, and BAPert 66316/66320 restates it for
-   *                        step 4. Consequence, accepted explicitly: a Vibe
-   *                        outage signs this app's users out. 'not_configured'
-   *                        also fails closed here - both live consumers ARE
-   *                        configured (BAPert 66356), so for them it means a
-   *                        misconfiguration, not "no revocation source".
-   *   'open'             - an unknown OR not-configured status stays viable
-   *                        (availability over fail-closed). Per-app opt-out for a
-   *                        deployment with no revocation source, or the two live
-   *                        consumers while Jon decides.
+   *   '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.
    *
-   * Neither mode changes `'revoked'` (always force-invalid) or an ABSENT
-   * `revocationStatus` (an older producer - unchanged behaviour, so no consumer
-   * is signed out for not implementing the check).
+   * `'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.
    */
-  revocationFailMode?: 'closed' | 'open';
+  unavailablePage?: string;
 
   /**
    * PAY-2302 cut 1c (BAPert 73585): this app has NO revocation source - for example a development environment
@@ -353,13 +371,34 @@ async function refreshFailureResponse(
  *               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): NextResponse {
+function serviceUnavailableResponse(request: NextRequest, check: UnavailableCheck = 'viability', unavailablePage?: string): NextResponse {
   const { pathname, search } = request.nextUrl;
   if (pathname.startsWith('/api/')) {
-    return NextResponse.json({ error: 'ServiceUnavailable' }, { status: 503 });
+    // 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 target = new URL('/service-unavailable', request.url);
   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).
+  // The named page applies to the revocation hold ONLY (BAPert 74648: the viability-failure arm is untouched). 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 = check === 'revocation' && unavailablePage && /^\/[A-Za-z0-9_\-\/]*$/.test(unavailablePage) && !unavailablePage.includes('//') ? unavailablePage : null;
+  if (check === 'revocation' && (!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>We could not check your session just now. You are still signed in.</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);
 }
@@ -438,6 +477,14 @@ function makeAuthDecision(ctx: AuthContext): AuthAction {
     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' };
@@ -557,8 +604,9 @@ export function createMvpMiddleware(options: MvpMiddlewareOptions = {}) {
   const refreshEndpoint = options.refreshEndpoint || '/api/auth/refresh';
   const bypassPaths = options.bypassPaths || [];
   const rbacExemptPaths = options.rbacExemptPaths || [];
-  // PAY-1882 step 4: default 'closed' (Jon's option A / BAPert 66316).
-  const revocationFailMode = options.revocationFailMode || 'closed';
+  // 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) {
@@ -693,6 +741,7 @@ export function createMvpMiddleware(options: MvpMiddlewareOptions = {}) {
       refreshEndpoint,
       rbacExemptPaths,
       reset: resolveReset(),
+      unavailablePage: options.unavailablePage,
       onRefreshSuccess: options.onRefreshSuccess,
       onRefreshFailure: options.onRefreshFailure,
     });
@@ -711,26 +760,44 @@ export function createMvpMiddleware(options: MvpMiddlewareOptions = {}) {
  * 'unknown'/'not_configured'. The booleans are read ONLY when revocationStatus is
  * absent (idealresume.online's older boolean-only route).
  */
-export function decideForceInvalid(
+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: 'closed' | 'open',
+  revocationFailMode: 'hold' | 'closed' | 'open',
   noRevocationSource: boolean = false,
-): boolean {
+): RevocationOutcome {
   const status = data.revocationStatus;
   if (typeof status === 'string') {
-    if (status === 'revoked') return true;
-    if (status === 'active') return false;
+    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 false;
-    // S1 (NightHawk 66409): ANY other string - 'unknown', 'not_configured', a
-    // typo like 'Revoked', 'error', or '' - is treated as 'unknown' (fail mode
-    // applies), NEVER as 'active'. Returning false here would let the first
-    // producer that emits an unexpected state silently switch revocation OFF -
-    // the exact PAY-1880 fail-open class. Only an explicit 'active' is viable.
-    return revocationFailMode === 'closed';
+    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 false.
-  return data.forceInvalid === true || data.revoked === true;
+  // 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';
 }
 
 /**
@@ -750,7 +817,7 @@ async function checkViability(
   request: NextRequest,
   endpoint: string,
   log: MiddlewareLogger,
-  revocationFailMode: 'closed' | 'open',
+  revocationFailMode: 'hold' | 'closed' | 'open',
   noRevocationSource: boolean = false
 ): Promise<{
   sessionStatus: SessionStatus;
@@ -829,7 +896,13 @@ async function checkViability(
       // 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).
-      sessionStatus.forceInvalid = decideForceInvalid(data, revocationFailMode, noRevocationSource);
+      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.
@@ -869,6 +942,8 @@ interface ExecuteOptions {
   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;
 }
@@ -894,7 +969,7 @@ async function executeDecision(
         : redirectTo(request, decision.location);
 
     case 'service_error':
-      return serviceUnavailableResponse(request);
+      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,

package/src/pages/service-unavailable/page.tsx

@@ -0,0 +1,63 @@
+'use client';
+
+import React, { Suspense } from 'react';
+import { useSearchParams } from 'next/navigation';
+
+/**
+ * PAY-2339 (option C): the default "temporarily unavailable" page the middleware sends a member to when the revocation
+ * check (or the viability read) could not answer. Mount it in one line in the consuming app:
+ *
+ *     // app/service-unavailable/page.tsx
+ *     export { default } from '@payez/next-mvp/pages/service-unavailable';
+ *
+ * It signs nobody out and clears nothing: "Try again" goes back to `callbackUrl`, and the member is still signed in. A
+ * consumer may replace the page (and the wording) with its own at the same route.
+ *
+ * `callbackUrl` is untrusted input. Only a same-origin PATH is followed ("/dashboard"); anything else (an absolute URL,
+ * a protocol-relative "//host", a "javascript:" value, a backslash trick, nothing at all) falls back to "/".
+ */
+export function safeReturnPath(raw: string | null | undefined): string {
+  if (!raw || typeof raw !== 'string') return '/';
+  if (!raw.startsWith('/') || raw.startsWith('//') || raw.includes('\\')) return '/';
+  if (/[\u0000-\u001f]/.test(raw)) return '/';
+  return raw;
+}
+
+function ServiceUnavailableContent() {
+  const params = useSearchParams();
+  const back = safeReturnPath(params?.get('callbackUrl'));
+  return (
+    <div className="min-h-screen flex items-center justify-center p-4">
+      <div
+        role="status"
+        className="max-w-md w-full text-center rounded-xl p-8 shadow-lg border"
+        style={{
+          backgroundColor: 'var(--bg-card, #ffffff)',
+          borderColor: 'var(--border-default, #e5e7eb)',
+        }}
+      >
+        <h1 className="text-xl font-semibold mb-2" style={{ color: 'var(--text-primary, #111827)' }}>
+          Temporarily unavailable
+        </h1>
+        <p className="mb-6" style={{ color: 'var(--text-secondary, #6b7280)' }}>
+          We could not check your session just now. You are still signed in. Please try again in a moment.
+        </p>
+        <a
+          href={back}
+          className="inline-block rounded-lg px-4 py-2 font-medium"
+          style={{ background: 'var(--color-primary, #10b981)', color: 'white' }}
+        >
+          Try again
+        </a>
+      </div>
+    </div>
+  );
+}
+
+export default function ServiceUnavailablePage() {
+  return (
+    <Suspense fallback={null}>
+      <ServiceUnavailableContent />
+    </Suspense>
+  );
+}

package/src/routes/auth/viability.ts

@@ -14,6 +14,7 @@
  * @since auth-ready-v2
  */
 
+import { revocationFields } from '../../auth/revocation-fields';
 import { NextRequest, NextResponse } from 'next/server';
 import { resolveSessionState } from '../../server/auth';
 import {
@@ -157,6 +158,7 @@ export async function GET(req: NextRequest) {
         needsRefresh: false,
         authenticated: false,
         revocationStatus: 'unknown' as RevocationStatus,
+        unavailable: true, // PAY-2339: a reader of this JSON gets the hold signal (the response is non-OK, so the middleware holds as service_error)
         error: 'Session store unavailable',
         code: 'STORE_UNAVAILABLE'
       }, { status: 500 });
@@ -383,8 +385,7 @@ export async function GET(req: NextRequest) {
         // Session revocation (PAY-1882 step 4): the four-state status, plus the
         // boolean the middleware's existing force-invalid branch already reads.
         revocationStatus,
-        forceInvalid: revocationStatus === 'revoked' || revocationStatus === 'unknown',
-        revoked: revocationStatus === 'revoked',
+        ...revocationFields(revocationStatus), // PAY-2339: forceInvalid only for 'revoked'; unavailable:true for 'unknown'
         // Clear names for middleware decision-making
         tenantRequiresTwoFactor,
         userHasCompletedTenantTwoFactorRequirements,
@@ -468,8 +469,7 @@ export async function GET(req: NextRequest) {
         reason: 'Token expired',
         // Session revocation (PAY-1882 step 4) - same value on every return.
         revocationStatus,
-        forceInvalid: revocationStatus === 'revoked' || revocationStatus === 'unknown',
-        revoked: revocationStatus === 'revoked',
+        ...revocationFields(revocationStatus), // PAY-2339: forceInvalid only for 'revoked'; unavailable:true for 'unknown'
         // RBAC fields
         roles: session?.roles || [],
         clientId: resolveClientId(session?.idpClientId),
@@ -485,8 +485,7 @@ export async function GET(req: NextRequest) {
       sessionTokenId: sessionToken ? tokenLogId(sessionToken) : null,
       // Session revocation (PAY-1882 step 4) - same value on every return.
       revocationStatus,
-      forceInvalid: revocationStatus === 'revoked' || revocationStatus === 'unknown',
-      revoked: revocationStatus === 'revoked',
+      ...revocationFields(revocationStatus), // PAY-2339: forceInvalid only for 'revoked'; unavailable:true for 'unknown'
       // Clear names
       tenantRequiresTwoFactor,
       userHasCompletedTenantTwoFactorRequirements,

package/src/types/auth.ts

@@ -25,6 +25,12 @@ export interface AuthConfig {
    * An OAuth-only client is a deliberate choice, never the default.
    */
   allowTraditionalLogin?: boolean;
+  /**
+   * PAY-2334: where /api/auth/settings stands. 'loading' = not answered yet, 'ready' = answered (or nothing to ask:
+   * useDynamicProviders off), 'failed' = non-2xx, thrown, or timed out. Absent means 'ready'. A page must not tell the user
+   * "sign-in is not available" while this is 'loading', and must say a failed read is a failed read, not an empty answer.
+   */
+  settingsStatus?: 'loading' | 'ready' | 'failed';
   providers: FederatedProvider[];
   enableRecovery: boolean;
   enableEmailSignup: boolean;