@payez/next-mvp 4.7.9 → 4.8.0

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/client/AuthContext.d.ts

@@ -9,6 +9,8 @@ interface AuthProviderProps {
      */
     useDynamicProviders?: boolean;
 }
+/** PAY-2334: how long /api/auth/settings may take before the sign-in card stops waiting and says it could not load. */
+export declare const SETTINGS_FETCH_TIMEOUT_MS = 10000;
 export declare function AuthProvider({ children, config, useDynamicProviders }: AuthProviderProps): import("react/jsx-runtime").JSX.Element;
 export declare function useAuthConfig(): AuthConfig;
 export declare function useAuthMode(): AuthMode;

package/dist/client/AuthContext.js

@@ -1,6 +1,7 @@
 "use strict";
 'use client';
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.SETTINGS_FETCH_TIMEOUT_MS = void 0;
 exports.AuthProvider = AuthProvider;
 exports.useAuthConfig = useAuthConfig;
 exports.useAuthMode = useAuthMode;
@@ -29,9 +30,14 @@ const PROVIDER_MAP = {
 };
 // OAuth providers we support in UI (excludes credentials)
 const OAUTH_PROVIDER_IDS = ['google', 'apple', 'facebook', 'github', 'azure-ad', 'microsoft-entra-id'];
+/** PAY-2334: how long /api/auth/settings may take before the sign-in card stops waiting and says it could not load. */
+exports.SETTINGS_FETCH_TIMEOUT_MS = 10000;
 function AuthProvider({ children, config, useDynamicProviders = true }) {
     const [dynamicProviders, setDynamicProviders] = (0, react_1.useState)([]);
     const [providersLoaded, setProvidersLoaded] = (0, react_1.useState)(!useDynamicProviders);
+    // PAY-2334: providersLoaded is true on failure too (it only means "stop waiting"), so it cannot tell an empty answer from
+    // no answer. This can: loading -> ready (answered) | failed (non-2xx, thrown, timed out).
+    const [settingsStatus, setSettingsStatus] = (0, react_1.useState)(useDynamicProviders ? 'loading' : 'ready');
     // What the IDP says this client offers. null until /api/auth/settings answers.
     const [serverSettings, setServerSettings] = (0, react_1.useState)(null);
     // Create QueryClient instance for React Query - used internally by MVP hooks
@@ -50,6 +56,9 @@ function AuthProvider({ children, config, useDynamicProviders = true }) {
             return;
         let mounted = true;
         async function fetchDynamicProviders() {
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(), exports.SETTINGS_FETCH_TIMEOUT_MS);
+            let status = 'failed';
             try {
                 // READ THE IDP. This used to be a hardcoded literal:
                 //     const result = { google: { id: 'google', name: 'Google' } };
@@ -59,7 +68,7 @@ function AuthProvider({ children, config, useDynamicProviders = true }) {
                 //
                 // /api/auth/settings already serves the real answer (enabledProviders,
                 // allowFederatedLogin, enablePasswordReset) and nothing consumed it.
-                const response = await fetch('/api/auth/settings');
+                const response = await fetch('/api/auth/settings', { signal: controller.signal });
                 if (!response.ok) {
                     // No silent substitution. Absent settings means we do not know what this
                     // client offers, and inventing a provider list is how a tenant ends up with a
@@ -79,6 +88,7 @@ function AuthProvider({ children, config, useDynamicProviders = true }) {
                     .filter(id => OAUTH_PROVIDER_IDS.includes(id))
                     .map(id => PROVIDER_MAP[id])
                     .filter((p) => p !== undefined);
+                status = 'ready';
                 setDynamicProviders(oauthProviders);
                 setServerSettings({
                     allowFederatedLogin: settings?.allowFederatedLogin !== false,
@@ -92,7 +102,9 @@ function AuthProvider({ children, config, useDynamicProviders = true }) {
                 console.error('[AuthProvider] could not read /api/auth/settings:', err);
             }
             finally {
+                clearTimeout(timer);
                 if (mounted) {
+                    setSettingsStatus(status);
                     setProvidersLoaded(true);
                 }
             }
@@ -110,6 +122,7 @@ function AuthProvider({ children, config, useDynamicProviders = true }) {
         ...defaultConfig,
         ...config,
         providers, // from the IDP when useDynamicProviders is on
+        settingsStatus: useDynamicProviders ? settingsStatus : 'ready',
         // THE SERVER DECIDES, THE SITE MAY OVERRIDE. A site that passes an explicit value
         // still wins; absent that, what the tenant's IDP reports is what renders. A client
         // hardcoding its own auth mode is how a sign-in screen and its IDP disagree.

package/dist/components/auth/ModeAwareLoginPage.js

@@ -37,7 +37,10 @@ function ModeAwareLoginPage({ onFederatedSignIn, onTraditionalSignIn, onForgotPa
     return ((0, jsx_runtime_1.jsxs)(jsx_runtime_1.Fragment, { children: [error && ((0, jsx_runtime_1.jsx)("div", { className: "mb-6 px-4 py-3 rounded-lg", style: {
                     background: 'var(--color-error, #ef4444)',
                     color: 'white',
-                }, children: error })), isFederated && ((0, jsx_runtime_1.jsx)(FederatedAuthSection_1.FederatedAuthSection, { providers: config.providers, onProviderClick: handleFederatedClick, isLoading: totalLoading })), isFederated && isTraditional && ((0, jsx_runtime_1.jsxs)("div", { className: "flex items-center gap-3 my-6", "aria-hidden": "true", children: [(0, jsx_runtime_1.jsx)("span", { className: "h-px flex-1", style: { background: 'var(--border-default, #e5e7eb)' } }), (0, jsx_runtime_1.jsx)("span", { className: "text-xs uppercase tracking-wide", style: { color: 'var(--text-muted, #6b7280)' }, children: "or" }), (0, jsx_runtime_1.jsx)("span", { className: "h-px flex-1", style: { background: 'var(--border-default, #e5e7eb)' } })] })), isTraditional && ((0, jsx_runtime_1.jsx)(TraditionalAuthSection_1.TraditionalAuthSection, { email: email, password: password, onEmailChange: setEmail, onPasswordChange: setPassword, onSubmit: handleTraditionalSubmit, isLoading: totalLoading, buttonText: "Sign In", showForgotPassword: config.enableRecovery, onForgotPassword: onForgotPassword })), !isFederated && !isTraditional && ((0, jsx_runtime_1.jsxs)("div", { role: "alert", className: "px-4 py-3 rounded-lg text-sm text-left", style: {
+                }, children: error })), isFederated && ((0, jsx_runtime_1.jsx)(FederatedAuthSection_1.FederatedAuthSection, { providers: config.providers, onProviderClick: handleFederatedClick, isLoading: totalLoading })), isFederated && isTraditional && ((0, jsx_runtime_1.jsxs)("div", { className: "flex items-center gap-3 my-6", "aria-hidden": "true", children: [(0, jsx_runtime_1.jsx)("span", { className: "h-px flex-1", style: { background: 'var(--border-default, #e5e7eb)' } }), (0, jsx_runtime_1.jsx)("span", { className: "text-xs uppercase tracking-wide", style: { color: 'var(--text-muted, #6b7280)' }, children: "or" }), (0, jsx_runtime_1.jsx)("span", { className: "h-px flex-1", style: { background: 'var(--border-default, #e5e7eb)' } })] })), isTraditional && ((0, jsx_runtime_1.jsx)(TraditionalAuthSection_1.TraditionalAuthSection, { email: email, password: password, onEmailChange: setEmail, onPasswordChange: setPassword, onSubmit: handleTraditionalSubmit, isLoading: totalLoading, buttonText: "Sign In", showForgotPassword: config.enableRecovery, onForgotPassword: onForgotPassword })), !isFederated && !isTraditional && config.settingsStatus === 'loading' && ((0, jsx_runtime_1.jsx)("div", { role: "status", className: "px-4 py-3 rounded-lg text-sm text-left", style: { color: 'var(--text-secondary, #6b7280)' }, children: (0, jsx_runtime_1.jsx)("p", { children: "Loading sign-in options\u2026" }) })), !isFederated && !isTraditional && config.settingsStatus === 'failed' && ((0, jsx_runtime_1.jsxs)("div", { role: "alert", className: "px-4 py-3 rounded-lg text-sm text-left", style: {
+                    border: '1px solid var(--border-default, #e5e7eb)',
+                    color: 'var(--text-primary, #111827)',
+                }, children: [(0, jsx_runtime_1.jsx)("p", { className: "font-semibold", children: "Could not load sign-in options." }), (0, jsx_runtime_1.jsx)("p", { className: "mt-1", children: "Please reload the page. If it keeps happening, contact an administrator." })] })), !isFederated && !isTraditional && (config.settingsStatus ?? 'ready') === 'ready' && ((0, jsx_runtime_1.jsxs)("div", { role: "alert", className: "px-4 py-3 rounded-lg text-sm text-left", style: {
                     border: '1px solid var(--border-default, #e5e7eb)',
                     color: 'var(--text-primary, #111827)',
                 }, children: [(0, jsx_runtime_1.jsx)("p", { className: "font-semibold", children: "Sign-in is not available for this application." }), (0, jsx_runtime_1.jsx)("p", { className: "mt-1", children: "No sign-in method is enabled for this client. An administrator needs to enable a federated provider or username and password sign-in." })] }))] }));

package/dist/components/auth/ModeAwareSignupPage.js

@@ -56,26 +56,11 @@ function ModeAwareSignupPage({ onFederatedSignUp, onTraditionalSignUp, isLoading
                             border: '1px solid var(--border-default)',
                             color: 'white',
                             background: 'var(--color-primary, #10b981)',
-                        }, children: totalLoading ? 'Creating Account...' : 'Create Account' })] })), isFederated === false && isTraditional === false && ((0, jsx_runtime_1.jsxs)(jsx_runtime_1.Fragment, { children: [(0, jsx_runtime_1.jsx)(FederatedAuthSection_1.FederatedAuthSection, { providers: config.providers, onProviderClick: handleFederatedClick, isLoading: totalLoading }), config.providers.length > 0 && config.enableEmailSignup && ((0, jsx_runtime_1.jsxs)("div", { className: "relative my-6", children: [(0, jsx_runtime_1.jsx)("div", { className: "absolute inset-0 flex items-center", children: (0, jsx_runtime_1.jsx)("div", { className: "w-full", style: {
-                                        borderTop: '1px solid var(--border-default)',
-                                    } }) }), (0, jsx_runtime_1.jsx)("div", { className: "relative flex justify-center text-sm", children: (0, jsx_runtime_1.jsx)("span", { className: "px-2", style: {
-                                        background: 'var(--bg-card)',
-                                        color: 'var(--text-secondary)',
-                                    }, children: "Or sign up with email" }) })] })), config.enableEmailSignup && ((0, jsx_runtime_1.jsxs)("form", { onSubmit: handleTraditionalSubmit, className: "space-y-4", children: [(0, jsx_runtime_1.jsxs)("div", { children: [(0, jsx_runtime_1.jsx)("label", { className: "block text-sm font-medium mb-2", style: { color: 'var(--text-primary)' }, children: "Email Address" }), (0, jsx_runtime_1.jsx)("input", { type: "email", value: email, onChange: (e) => setEmail(e.target.value), placeholder: "you@example.com", disabled: totalLoading, required: true, className: "w-full px-4 py-3 rounded-lg border transition-colors focus:outline-none focus:ring-2 disabled:opacity-50", style: {
-                                            border: '1px solid var(--border-default)',
-                                            color: 'var(--text-primary)',
-                                            background: 'var(--bg-default)',
-                                        } })] }), (0, jsx_runtime_1.jsxs)("div", { children: [(0, jsx_runtime_1.jsx)("label", { className: "block text-sm font-medium mb-2", style: { color: 'var(--text-primary)' }, children: "Password" }), (0, jsx_runtime_1.jsx)("input", { type: "password", value: password, onChange: (e) => setPassword(e.target.value), placeholder: "\u2022\u2022\u2022\u2022\u2022\u2022\u2022\u2022", disabled: totalLoading, required: true, className: "w-full px-4 py-3 rounded-lg border transition-colors focus:outline-none focus:ring-2 disabled:opacity-50", style: {
-                                            border: '1px solid var(--border-default)',
-                                            color: 'var(--text-primary)',
-                                            background: 'var(--bg-default)',
-                                        } })] }), (0, jsx_runtime_1.jsxs)("div", { children: [(0, jsx_runtime_1.jsx)("label", { className: "block text-sm font-medium mb-2", style: { color: 'var(--text-primary)' }, children: "Confirm Password" }), (0, jsx_runtime_1.jsx)("input", { type: "password", value: confirmPassword, onChange: (e) => setConfirmPassword(e.target.value), placeholder: "\u2022\u2022\u2022\u2022\u2022\u2022\u2022\u2022", disabled: totalLoading, required: true, className: "w-full px-4 py-3 rounded-lg border transition-colors focus:outline-none focus:ring-2 disabled:opacity-50", style: {
-                                            border: '1px solid var(--border-default)',
-                                            color: 'var(--text-primary)',
-                                            background: 'var(--bg-default)',
-                                        } })] }), (0, jsx_runtime_1.jsx)("button", { type: "submit", disabled: totalLoading, className: "w-full py-3 px-4 rounded-lg font-semibold focus:outline-none focus:ring-2 disabled:opacity-50 disabled:cursor-not-allowed transition-colors mt-6", style: {
-                                    border: '1px solid var(--border-default)',
-                                    color: 'white',
-                                    background: 'var(--color-primary, #10b981)',
-                                }, children: totalLoading ? 'Creating Account...' : 'Create Account' })] }))] }))] }));
+                        }, children: totalLoading ? 'Creating Account...' : 'Create Account' })] })), !isFederated && !isTraditional && config.settingsStatus === 'loading' && ((0, jsx_runtime_1.jsx)("div", { role: "status", className: "px-4 py-3 rounded-lg text-sm text-left", style: { color: 'var(--text-secondary, #6b7280)' }, children: (0, jsx_runtime_1.jsx)("p", { children: "Loading sign-up options\u2026" }) })), !isFederated && !isTraditional && config.settingsStatus === 'failed' && ((0, jsx_runtime_1.jsxs)("div", { role: "alert", className: "px-4 py-3 rounded-lg text-sm text-left", style: {
+                    border: '1px solid var(--border-default, #e5e7eb)',
+                    color: 'var(--text-primary, #111827)',
+                }, children: [(0, jsx_runtime_1.jsx)("p", { className: "font-semibold", children: "Could not load sign-up options." }), (0, jsx_runtime_1.jsx)("p", { className: "mt-1", children: "Please reload the page. If it keeps happening, contact an administrator." })] })), !isFederated && !isTraditional && (config.settingsStatus ?? 'ready') === 'ready' && ((0, jsx_runtime_1.jsxs)("div", { role: "alert", className: "px-4 py-3 rounded-lg text-sm text-left", style: {
+                    border: '1px solid var(--border-default, #e5e7eb)',
+                    color: 'var(--text-primary, #111827)',
+                }, children: [(0, jsx_runtime_1.jsx)("p", { className: "font-semibold", children: "Sign-up is not available for this application." }), (0, jsx_runtime_1.jsx)("p", { className: "mt-1", children: "No sign-up method is enabled for this client. An administrator needs to enable a federated provider or username and password sign-in." })] }))] }));
 }

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,31 @@ 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).
+    // 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 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>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 server_1.NextResponse.redirect(target);
@@ -264,6 +283,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 +407,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 +527,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 +650,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 +699,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.

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;
 }>>;