@payez/next-mvp 4.7.10 → 4.8.1

package/dist/api-handlers/session/viability.js

@@ -6,6 +6,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.GET = GET;
+const revocation_fields_1 = require("../../auth/revocation-fields");
 const server_1 = require("next/server");
 const session_store_1 = require("../../lib/session-store");
 const auth_1 = require("../../server/auth");
@@ -45,7 +46,7 @@ async function GET(req) {
         const sessionState = await (0, auth_1.resolveSessionState)(req);
         if (sessionState.state === 'unknown') {
             console.warn('[VIABILITY] Session store unavailable - session state unknown');
-            return server_1.NextResponse.json({ authenticated: false, revocationStatus: 'unknown', error: 'Session store unavailable', code: 'STORE_UNAVAILABLE' }, { status: 500 });
+            return server_1.NextResponse.json({ authenticated: false, revocationStatus: 'unknown', unavailable: true, error: 'Session store unavailable', code: 'STORE_UNAVAILABLE' }, { status: 500 });
         }
         if (sessionState.state === 'missing') {
             console.warn('[VIABILITY] Stale cookie detected - verified cookie, session not in Redis');
@@ -174,8 +175,7 @@ async function GET(req) {
                     // 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',
+                    ...(0, revocation_fields_1.revocationFields)(revocationStatus), // PAY-2339: forceInvalid only for 'revoked'; unavailable:true for 'unknown'
                     // Cards 141688/141741 — the IDP's routing decision, relayed verbatim.
                     //
                     // THIS IS THE SECOND IMPLEMENTATION OF VIABILITY. The other is

package/dist/auth/auth-decision.d.ts

@@ -17,6 +17,8 @@ export interface AuthContext {
     sessionStatus: {
         exists: boolean | null;
         forceInvalid: boolean | null;
+        /** PAY-2339: the producer said the revocation backend could not answer. makeAuthDecision HOLDS (no sign-out). */
+        unavailable?: boolean;
         requires2FA: boolean;
         twoFactorComplete: boolean;
     };
@@ -34,6 +36,7 @@ export type AuthAction = {
 } | {
     type: 'service_error';
     reason: string;
+    check?: 'revocation' | 'viability';
 };
 /**
  * Main decision function - pure, testable, deterministic.

package/dist/auth/auth-decision.js

@@ -94,6 +94,15 @@ function decide(context) {
             reason: 'redis_unavailable'
         };
     }
+    // PAY-2339 (BAPert 74633): the revocation backend could not answer. Hold: not a verdict on the session, so no
+    // sign-out and no cookie is touched. A caller maps this to its own "temporarily unavailable" answer (the
+    // createMvpMiddleware twin sends /service-unavailable or a 503 with unavailable:true, check:'revocation').
+    if (sessionStatus.unavailable) {
+        if (isLoginPage) {
+            return { type: 'allow' };
+        }
+        return { type: 'service_error', reason: 'revocation_unknown', check: 'revocation' };
+    }
     // Session force invalidated - need fresh login
     if (sessionStatus.forceInvalid) {
         if (isLoginPage) {

package/dist/auth/revocation-fields.d.ts

@@ -0,0 +1,16 @@
+/**
+ * PAY-2339 (BAPert 74633 gap 1): the two revocation fields every viability producer emits, in ONE place so the
+ * producers (api-handlers/session/viability.ts and routes/auth/viability.ts, four return sites) cannot drift.
+ *
+ *   forceInvalid - true ONLY for 'revoked'. An 'unknown' answer is no longer a sign-out verdict.
+ *   unavailable  - true when the revocation backend could not answer: 'unknown' and ANY string that is not one of the
+ *                  three recognised states. A consumer that reads this JSON (useSessionCheck, makeAuthDecision) holds
+ *                  instead of signing the member out. `revocationStatus` itself is emitted unchanged.
+ *
+ * 'not_configured' is a configuration fault, not an outage: neither field is set for it (unchanged).
+ */
+export declare function revocationFields(status: unknown): {
+    forceInvalid: boolean;
+    unavailable: boolean;
+    revoked: boolean;
+};

package/dist/auth/revocation-fields.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.revocationFields = revocationFields;
+/**
+ * PAY-2339 (BAPert 74633 gap 1): the two revocation fields every viability producer emits, in ONE place so the
+ * producers (api-handlers/session/viability.ts and routes/auth/viability.ts, four return sites) cannot drift.
+ *
+ *   forceInvalid - true ONLY for 'revoked'. An 'unknown' answer is no longer a sign-out verdict.
+ *   unavailable  - true when the revocation backend could not answer: 'unknown' and ANY string that is not one of the
+ *                  three recognised states. A consumer that reads this JSON (useSessionCheck, makeAuthDecision) holds
+ *                  instead of signing the member out. `revocationStatus` itself is emitted unchanged.
+ *
+ * 'not_configured' is a configuration fault, not an outage: neither field is set for it (unchanged).
+ */
+function revocationFields(status) {
+    const revoked = status === 'revoked';
+    const unavailable = !(status === 'revoked' || status === 'active' || status === 'not_configured');
+    return { forceInvalid: revoked, unavailable, revoked };
+}

package/dist/middleware/create-middleware.d.ts

@@ -35,9 +35,13 @@ export interface SessionPointer {
     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;
     forceInvalid: boolean | null;
+    /** PAY-2339: the revocation backend could not answer and this app HOLDS (revocationFailMode 'hold'): no sign-out. */
+    unavailable?: boolean;
     requires2FA: boolean;
     twoFactorComplete: boolean;
 }
@@ -51,6 +55,7 @@ export type AuthAction = {
 } | {
     type: 'service_error';
     reason: string;
+    check?: UnavailableCheck;
 } | {
     type: 'refresh_needed';
 };
@@ -113,29 +118,41 @@ 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?: 'closed' | 'open';
+    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
@@ -173,8 +190,21 @@ export declare function createMvpMiddleware(options?: MvpMiddlewareOptions): (re
  * '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 declare function decideRevocationOutcome(data: {
+    revocationStatus?: unknown;
+    forceInvalid?: unknown;
+    revoked?: unknown;
+}, revocationFailMode: 'hold' | 'closed' | 'open', noRevocationSource?: boolean): RevocationOutcome;
 export declare function decideForceInvalid(data: {
     revocationStatus?: unknown;
     forceInvalid?: unknown;
     revoked?: unknown;
-}, revocationFailMode: 'closed' | 'open', noRevocationSource?: boolean): boolean;
+}, revocationFailMode: 'hold' | 'closed' | 'open', noRevocationSource?: boolean): boolean;

package/dist/middleware/create-middleware.js

@@ -21,6 +21,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.TWO_FACTOR_TIMEOUT_ERROR = void 0;
 exports.isPrefetchRequest = isPrefetchRequest;
 exports.createMvpMiddleware = createMvpMiddleware;
+exports.decideRevocationOutcome = decideRevocationOutcome;
 exports.decideForceInvalid = decideForceInvalid;
 const server_1 = require("next/server");
 const route_config_1 = require("../auth/route-config");
@@ -185,13 +186,32 @@ async function refreshFailureResponse(request, location, errorCode, clearCookies
  *               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) {
+function serviceUnavailableResponse(request, check = 'viability', unavailablePage) {
     const { pathname, search } = request.nextUrl;
     if (pathname.startsWith('/api/')) {
-        return server_1.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 server_1.NextResponse.json({ error: 'ServiceUnavailable', unavailable: true, check }, { status: 503 });
     }
-    const target = new URL('/service-unavailable', request.url);
     const callback = (0, safe_callback_1.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 server_1.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 server_1.NextResponse.redirect(target);
@@ -264,6 +284,14 @@ function makeAuthDecision(ctx) {
             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)
@@ -380,8 +408,9 @@ function createMvpMiddleware(options = {}) {
     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) {
@@ -499,42 +528,44 @@ function createMvpMiddleware(options = {}) {
             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.
+ * PAY-2339: the three-way form of the revocation decision. `decideForceInvalid` below is kept as its boolean view.
  *
- * 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).
+ *   '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
  */
-function decideForceInvalid(data, revocationFailMode, noRevocationSource = false) {
+function decideRevocationOutcome(data, revocationFailMode, noRevocationSource = false) {
     const status = data.revocationStatus;
     if (typeof status === 'string') {
         if (status === 'revoked')
-            return true;
+            return 'invalid';
         if (status === 'active')
-            return false;
+            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';
+            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';
+}
+function decideForceInvalid(data, revocationFailMode, noRevocationSource = false) {
+    return decideRevocationOutcome(data, revocationFailMode, noRevocationSource) === 'invalid';
 }
 /**
  * PAY-2147: does the request carry a session cookie? Used ONLY when the viability read itself FAILED.
@@ -620,7 +651,13 @@ async function checkViability(request, endpoint, log, revocationFailMode, noRevo
             // 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.
@@ -663,7 +700,7 @@ async function executeDecision(request, decision, pathname, sessionPointer, sess
                 ? clearingRedirect(request, decision.location, opts.reset)
                 : 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,
             // clear the session. Let it through; the real navigation refreshes.
@@ -730,7 +767,7 @@ async function handleRefresh(request, safeCallback, opts) {
         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);
+        return serviceUnavailableResponse(request, 'viability', opts.unavailablePage);
     }
     try {
         const baseUrl = (0, internal_api_url_1.getInternalApiUrl)(request);

package/dist/pages/service-unavailable/page.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 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 declare function safeReturnPath(raw: string | null | undefined): string;
+export default function ServiceUnavailablePage(): import("react/jsx-runtime").JSX.Element;

package/dist/pages/service-unavailable/page.js

@@ -0,0 +1,41 @@
+"use strict";
+'use client';
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.safeReturnPath = safeReturnPath;
+exports.default = ServiceUnavailablePage;
+const jsx_runtime_1 = require("react/jsx-runtime");
+const react_1 = require("react");
+const navigation_1 = require("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 "/".
+ */
+function safeReturnPath(raw) {
+    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 = (0, navigation_1.useSearchParams)();
+    const back = safeReturnPath(params?.get('callbackUrl'));
+    return ((0, jsx_runtime_1.jsx)("div", { className: "min-h-screen flex items-center justify-center p-4", children: (0, jsx_runtime_1.jsxs)("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)',
+            }, children: [(0, jsx_runtime_1.jsx)("h1", { className: "text-xl font-semibold mb-2", style: { color: 'var(--text-primary, #111827)' }, children: "Temporarily unavailable" }), (0, jsx_runtime_1.jsx)("p", { className: "mb-6", style: { color: 'var(--text-secondary, #6b7280)' }, children: "We could not check your session just now. You are still signed in. Please try again in a moment." }), (0, jsx_runtime_1.jsx)("a", { href: back, className: "inline-block rounded-lg px-4 py-2 font-medium", style: { background: 'var(--color-primary, #10b981)', color: 'white' }, children: "Try again" })] }) }));
+}
+function ServiceUnavailablePage() {
+    return ((0, jsx_runtime_1.jsx)(react_1.Suspense, { fallback: null, children: (0, jsx_runtime_1.jsx)(ServiceUnavailableContent, {}) }));
+}

package/dist/routes/auth/viability.d.ts

@@ -28,6 +28,7 @@ export declare function GET(req: NextRequest): Promise<NextResponse<{
     needsRefresh: boolean;
     authenticated: boolean;
     revocationStatus: RevocationStatus;
+    unavailable: boolean;
     error: string;
     code: string;
 }> | NextResponse<{
@@ -36,15 +37,6 @@ export declare function GET(req: NextRequest): Promise<NextResponse<{
     authenticated: boolean;
     reason: string;
 }> | NextResponse<{
-    viable: boolean;
-    needsRefresh: boolean;
-    expiresIn: number;
-    hasRefreshToken: boolean;
-    authenticated: boolean;
-    sessionTokenId: string | null;
-    revocationStatus: RevocationStatus;
-    forceInvalid: boolean;
-    revoked: boolean;
     tenantRequiresTwoFactor: boolean;
     userHasCompletedTenantTwoFactorRequirements: boolean;
     userStillNeedsTwoFactor: boolean;
@@ -56,4 +48,22 @@ export declare function GET(req: NextRequest): Promise<NextResponse<{
     expiresAt: string;
     roles: string[];
     clientId: string | null;
+    forceInvalid: boolean;
+    unavailable: boolean;
+    revoked: boolean;
+    viable: boolean;
+    needsRefresh: boolean;
+    expiresIn: number;
+    hasRefreshToken: boolean;
+    authenticated: boolean;
+    sessionTokenId: string | null;
+    revocationStatus: RevocationStatus;
+}> | NextResponse<{
+    viable: boolean;
+    needsRefresh: boolean;
+    authenticated: boolean;
+    revocationStatus: RevocationStatus;
+    error: string;
+    code: string;
+    correlationId: string;
 }>>;

package/dist/routes/auth/viability.js

@@ -16,6 +16,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.GET = GET;
+const revocation_fields_1 = require("../../auth/revocation-fields");
 const server_1 = require("next/server");
 const auth_1 = require("../../server/auth");
 const session_store_1 = require("../../lib/session-store");
@@ -150,6 +151,7 @@ async function GET(req) {
                 needsRefresh: false,
                 authenticated: false,
                 revocationStatus: 'unknown',
+                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 });
@@ -361,8 +363,7 @@ async function GET(req) {
                 // 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',
+                ...(0, revocation_fields_1.revocationFields)(revocationStatus), // PAY-2339: forceInvalid only for 'revoked'; unavailable:true for 'unknown'
                 // Clear names for middleware decision-making
                 tenantRequiresTwoFactor,
                 userHasCompletedTenantTwoFactorRequirements,
@@ -436,8 +437,7 @@ async function GET(req) {
                 reason: 'Token expired',
                 // Session revocation (PAY-1882 step 4) - same value on every return.
                 revocationStatus,
-                forceInvalid: revocationStatus === 'revoked' || revocationStatus === 'unknown',
-                revoked: revocationStatus === 'revoked',
+                ...(0, revocation_fields_1.revocationFields)(revocationStatus), // PAY-2339: forceInvalid only for 'revoked'; unavailable:true for 'unknown'
                 // RBAC fields
                 roles: session?.roles || [],
                 clientId: resolveClientId(session?.idpClientId),
@@ -452,8 +452,7 @@ async function GET(req) {
             sessionTokenId: sessionToken ? (0, token_log_id_1.tokenLogId)(sessionToken) : null,
             // Session revocation (PAY-1882 step 4) - same value on every return.
             revocationStatus,
-            forceInvalid: revocationStatus === 'revoked' || revocationStatus === 'unknown',
-            revoked: revocationStatus === 'revoked',
+            ...(0, revocation_fields_1.revocationFields)(revocationStatus), // PAY-2339: forceInvalid only for 'revoked'; unavailable:true for 'unknown'
             // Clear names
             tenantRequiresTwoFactor,
             userHasCompletedTenantTwoFactorRequirements,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@payez/next-mvp",
-  "version": "4.7.10",
+  "version": "4.8.1",
   "sideEffects": false,
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -910,6 +910,11 @@
       "require": "./dist/pages/client-admin/index.js",
       "default": "./dist/pages/client-admin/index.js"
     },
+    "./pages/service-unavailable": {
+      "types": "./dist/pages/service-unavailable/page.d.ts",
+      "require": "./dist/pages/service-unavailable/page.js",
+      "default": "./dist/pages/service-unavailable/page.js"
+    },
     "./pages/coming-soon": {
       "types": "./dist/pages/coming-soon/page.d.ts",
       "require": "./dist/pages/coming-soon/page.js",

package/src/api-handlers/session/viability.ts

@@ -4,6 +4,7 @@
  * This API route is called by the middleware to securely check if a session is valid.
  */
 
+import { revocationFields } from '../../auth/revocation-fields';
 import { NextRequest, NextResponse } from 'next/server';
 import { getSession as getRedisSession, getBetterAuthSession } from '../../lib/session-store';
 import { resolveSessionState } from '../../server/auth';
@@ -52,7 +53,7 @@ export async function GET(req: NextRequest) {
     if (sessionState.state === 'unknown') {
       console.warn('[VIABILITY] Session store unavailable - session state unknown');
       return NextResponse.json(
-        { authenticated: false, revocationStatus: 'unknown' as RevocationStatus, error: 'Session store unavailable', code: 'STORE_UNAVAILABLE' },
+        { authenticated: false, revocationStatus: 'unknown' as RevocationStatus, unavailable: true, error: 'Session store unavailable', code: 'STORE_UNAVAILABLE' },
         { status: 500 }
       );
     }
@@ -192,8 +193,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'
           // Cards 141688/141741 — the IDP's routing decision, relayed verbatim.
           //
           // THIS IS THE SECOND IMPLEMENTATION OF VIABILITY. The other is

package/src/auth/auth-decision.ts

@@ -22,6 +22,8 @@ export interface AuthContext {
   sessionStatus: {
     exists: boolean | null; // null = check failed/timeout
     forceInvalid: boolean | null; // null = check failed/timeout
+    /** PAY-2339: the producer said the revocation backend could not answer. makeAuthDecision HOLDS (no sign-out). */
+    unavailable?: boolean;
     requires2FA: boolean;
     twoFactorComplete: boolean;
   };
@@ -34,7 +36,7 @@ export interface AuthContext {
 export type AuthAction = 
   | { type: 'allow' }
   | { type: 'redirect'; location: string; reason: string; clearCookies?: boolean }
-  | { type: 'service_error'; reason: string };
+  | { type: 'service_error'; reason: string; check?: 'revocation' | 'viability' };
 
 /** PAY-2180: warn once per process, not per request. */
 let deprecationWarned = false;
@@ -139,6 +141,16 @@ function decide(context: AuthContext): AuthAction {
     };
   }
 
+  // PAY-2339 (BAPert 74633): the revocation backend could not answer. Hold: not a verdict on the session, so no
+  // sign-out and no cookie is touched. A caller maps this to its own "temporarily unavailable" answer (the
+  // createMvpMiddleware twin sends /service-unavailable or a 503 with unavailable:true, check:'revocation').
+  if (sessionStatus.unavailable) {
+    if (isLoginPage) {
+      return { type: 'allow' };
+    }
+    return { type: 'service_error', reason: 'revocation_unknown', check: 'revocation' };
+  }
+
   // Session force invalidated - need fresh login
   if (sessionStatus.forceInvalid) {
     if (isLoginPage) {

package/src/auth/revocation-fields.ts

@@ -0,0 +1,16 @@
+/**
+ * PAY-2339 (BAPert 74633 gap 1): the two revocation fields every viability producer emits, in ONE place so the
+ * producers (api-handlers/session/viability.ts and routes/auth/viability.ts, four return sites) cannot drift.
+ *
+ *   forceInvalid - true ONLY for 'revoked'. An 'unknown' answer is no longer a sign-out verdict.
+ *   unavailable  - true when the revocation backend could not answer: 'unknown' and ANY string that is not one of the
+ *                  three recognised states. A consumer that reads this JSON (useSessionCheck, makeAuthDecision) holds
+ *                  instead of signing the member out. `revocationStatus` itself is emitted unchanged.
+ *
+ * 'not_configured' is a configuration fault, not an outage: neither field is set for it (unchanged).
+ */
+export function revocationFields(status: unknown): { forceInvalid: boolean; unavailable: boolean; revoked: boolean } {
+  const revoked = status === 'revoked';
+  const unavailable = !(status === 'revoked' || status === 'active' || status === 'not_configured');
+  return { forceInvalid: revoked, unavailable, revoked };
+}

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,35 @@ 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).
+  // 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);
 }
@@ -438,6 +478,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 +605,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 +742,7 @@ export function createMvpMiddleware(options: MvpMiddlewareOptions = {}) {
       refreshEndpoint,
       rbacExemptPaths,
       reset: resolveReset(),
+      unavailablePage: options.unavailablePage,
       onRefreshSuccess: options.onRefreshSuccess,
       onRefreshFailure: options.onRefreshFailure,
     });
@@ -711,26 +761,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 +818,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 +897,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 +943,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 +970,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,
@@ -989,7 +1065,7 @@ async function handleRefresh(
     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);
+    return serviceUnavailableResponse(request, 'viability', opts.unavailablePage);
   }
 
   try {

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,