@payez/next-mvp 4.5.1 → 4.5.3

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

@@ -39,5 +39,10 @@ export type AuthAction = {
  * Main decision function - pure, testable, deterministic.
  * PAY-2136: when `context.isPrefetch` is set, no redirect it returns asks for cookies to be cleared; the
  * redirect itself is kept, and the next real navigation reaches the same decision and clears then.
+ *
+ * @deprecated PAY-2180: this exported engine is NOT the one the middleware runs. `createMvpMiddleware` decides with
+ * its own private engine (middleware/create-middleware.ts), so calling this answers a question nothing enforces.
+ * A sweep found no code consumer in the portal, idealvibe, idealresume or cryptaply. It will be REMOVED in the next
+ * major version, together with its re-exports from the package root and `/edge`. Use `createMvpMiddleware`.
  */
 export declare function makeAuthDecision(context: AuthContext): AuthAction;

package/dist/auth/auth-decision.js

@@ -9,12 +9,24 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.makeAuthDecision = makeAuthDecision;
 const safe_callback_1 = require("./safe-callback");
 const token_log_id_1 = require("../lib/token-log-id");
+/** PAY-2180: warn once per process, not per request. */
+let deprecationWarned = false;
 /**
  * Main decision function - pure, testable, deterministic.
  * PAY-2136: when `context.isPrefetch` is set, no redirect it returns asks for cookies to be cleared; the
  * redirect itself is kept, and the next real navigation reaches the same decision and clears then.
+ *
+ * @deprecated PAY-2180: this exported engine is NOT the one the middleware runs. `createMvpMiddleware` decides with
+ * its own private engine (middleware/create-middleware.ts), so calling this answers a question nothing enforces.
+ * A sweep found no code consumer in the portal, idealvibe, idealresume or cryptaply. It will be REMOVED in the next
+ * major version, together with its re-exports from the package root and `/edge`. Use `createMvpMiddleware`.
  */
 function makeAuthDecision(context) {
+    if (!deprecationWarned) {
+        deprecationWarned = true;
+        console.warn('[next-mvp] makeAuthDecision (auth/auth-decision) is deprecated (PAY-2180) and will be removed in the next major: ' +
+            'createMvpMiddleware does not use it. Use createMvpMiddleware.');
+    }
     const action = decide(context);
     if (context.isPrefetch && action.type === 'redirect' && action.clearCookies) {
         const { clearCookies: _dropped, ...rest } = action;
@@ -49,8 +61,10 @@ function decide(context) {
         return {
             type: 'redirect',
             location: '/account-auth/login?error=ServiceUnavailable&reason=CircuitBreakerOpen',
-            reason: 'CircuitBreakerOpen',
-            clearCookies: true
+            reason: 'CircuitBreakerOpen'
+            // PAY-2147: NO clearCookies. The breaker opening is not a verdict on the session; clearing here logged out every
+            // user who made a request during a blip. (Deprecated twin: it cannot express a 503 or the /service-unavailable
+            // page - createMvpMiddleware does, see serviceUnavailableResponse.)
         };
     }
     // No session pointer (JWT cookie) - need to login

package/dist/lib/idp-fetch.d.ts

@@ -1,6 +1,7 @@
 import { NextRequest } from 'next/server';
 import { assertAbsoluteIdpUrl } from './idp-url-guard';
-export { assertAbsoluteIdpUrl };
+import { parseRetryAfterSeconds } from './retry-after';
+export { assertAbsoluteIdpUrl, parseRetryAfterSeconds };
 /**
  * Centralized IDP fetch helper
  * - Injects Bearer from Redis session
@@ -12,5 +13,11 @@ export interface IdpFetchResult<T = any> {
     status: number;
     json: T | null;
     attemptedRefresh: boolean;
+    /**
+     * PAY-1608: the upstream Retry-After in whole seconds, when the IDP sent a usable one. Core sends it on every
+     * 2FA lock (MfaController.SecondFactorLocked: 429 + Retry-After 900; VerifyTotp: what is left of the lock).
+     * It used to be dropped here, so no BFF could state the real lock window. Absent otherwise.
+     */
+    retryAfterSeconds?: number;
 }
 export declare function idpFetchJSON<T = any>(req: NextRequest, targetUrl: string, init?: RequestInit): Promise<IdpFetchResult<T>>;

package/dist/lib/idp-fetch.js

@@ -33,13 +33,15 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.assertAbsoluteIdpUrl = void 0;
+exports.parseRetryAfterSeconds = exports.assertAbsoluteIdpUrl = void 0;
 exports.idpFetchJSON = idpFetchJSON;
 const test_aware_get_token_1 = require("./test-aware-get-token");
 const session_store_1 = require("./session-store");
 const internal_api_1 = require("./internal-api");
 const idp_url_guard_1 = require("./idp-url-guard");
 Object.defineProperty(exports, "assertAbsoluteIdpUrl", { enumerable: true, get: function () { return idp_url_guard_1.assertAbsoluteIdpUrl; } });
+const retry_after_1 = require("./retry-after");
+Object.defineProperty(exports, "parseRetryAfterSeconds", { enumerable: true, get: function () { return retry_after_1.parseRetryAfterSeconds; } });
 function buildHeaders(req, bearer, extra) {
     const headers = {
         Accept: 'application/json',
@@ -177,5 +179,6 @@ async function idpFetchJSON(req, targetUrl, init = {}) {
         }
         catch { }
     }
-    return { ok: res.ok, status: res.status, json: json, attemptedRefresh };
+    const retryAfterSeconds = (0, retry_after_1.parseRetryAfterSeconds)(res.headers?.get?.('Retry-After'));
+    return { ok: res.ok, status: res.status, json: json, attemptedRefresh, ...(retryAfterSeconds ? { retryAfterSeconds } : {}) };
 }

package/dist/lib/retry-after.d.ts

@@ -0,0 +1,10 @@
+/**
+ * PAY-1608: parse an HTTP Retry-After header to whole seconds.
+ *
+ * Accepts delta-seconds ("900") and an HTTP date in the future. Answers undefined for absent, zero, negative,
+ * fractional, past or malformed values - a caller that gets undefined states no window rather than a guessed one.
+ *
+ * A dependency-free leaf on purpose: idp-fetch re-exports it, but a test can load it without the session/redis
+ * graph idp-fetch pulls in.
+ */
+export declare function parseRetryAfterSeconds(value: string | null | undefined, nowMs?: number): number | undefined;

package/dist/lib/retry-after.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseRetryAfterSeconds = parseRetryAfterSeconds;
+/**
+ * PAY-1608: parse an HTTP Retry-After header to whole seconds.
+ *
+ * Accepts delta-seconds ("900") and an HTTP date in the future. Answers undefined for absent, zero, negative,
+ * fractional, past or malformed values - a caller that gets undefined states no window rather than a guessed one.
+ *
+ * A dependency-free leaf on purpose: idp-fetch re-exports it, but a test can load it without the session/redis
+ * graph idp-fetch pulls in.
+ */
+function parseRetryAfterSeconds(value, nowMs = Date.now()) {
+    if (typeof value !== 'string')
+        return undefined;
+    const v = value.trim();
+    if (/^\d+$/.test(v)) {
+        const n = parseInt(v, 10);
+        return n > 0 ? n : undefined;
+    }
+    // Only something that looks like an HTTP date (it has letters: "Sat, 10 Oct 2026 12:01:30 GMT") is parsed as
+    // one; "-5" and "1.5" must not reach Date.parse, which would read them as years.
+    if (!/[a-z]/i.test(v))
+        return undefined;
+    const at = Date.parse(v);
+    if (!Number.isFinite(at))
+        return undefined;
+    const secs = Math.ceil((at - nowMs) / 1000);
+    return secs > 0 ? secs : undefined;
+}

package/dist/lib/two-factor-verify-failure.d.ts

@@ -56,10 +56,18 @@ export declare function stepUpRefusal(status: number, json: unknown): StepUpRefu
  */
 export declare function upstreamErrorTexts(json: unknown): string[];
 export declare function classifyTwoFactorVerifyFailure(status: number, json: unknown): TwoFactorVerifyFailureCode;
+/**
+ * PAY-1608: the window as words - "15 minutes", "1 minute", "45 seconds", "2 hours". Rounded UP, so the user is never
+ * told a shorter wait than the IDP enforces. Undefined in, undefined out.
+ */
+export declare function formatLockWindow(seconds: number | undefined): string | undefined;
+/** PAY-1608: the LOCKED sentence with the IDP's real window, or the number-free one when none was sent. */
+export declare function lockedText(retryAfterSeconds?: number): string;
 export declare function twoFactorVerifyFailure(result: {
     status: number;
     json: unknown;
     attemptedRefresh: boolean;
+    retryAfterSeconds?: number;
 }, method: TwoFactorVerifyMethod): NextResponse;
 /**
  * PAY-1443 residual: account/send-code on the SAME verify-code screen. A send has no

package/dist/lib/two-factor-verify-failure.js

@@ -4,6 +4,8 @@ exports.STEP_UP_REFUSAL_CODE = void 0;
 exports.stepUpRefusal = stepUpRefusal;
 exports.upstreamErrorTexts = upstreamErrorTexts;
 exports.classifyTwoFactorVerifyFailure = classifyTwoFactorVerifyFailure;
+exports.formatLockWindow = formatLockWindow;
+exports.lockedText = lockedText;
 exports.twoFactorVerifyFailure = twoFactorVerifyFailure;
 exports.classifyTwoFactorSendFailure = classifyTwoFactorSendFailure;
 exports.twoFactorSendCodeFailure = twoFactorSendCodeFailure;
@@ -33,7 +35,9 @@ const INVALID_CODE_TEXT = {
     backup_code: 'Invalid backup code. Please try again.',
 };
 const FIXED_TEXT = {
-    LOCKED: 'Too many incorrect codes. Verification is locked for 15 minutes - wait before entering another code.',
+    // PAY-1608: NO NUMBER HERE. This is the sentence for a lock whose window the IDP did not send; lockedText()
+    // states the real window when Retry-After arrives. A hard-coded "15 minutes" was true only while every lock was 15.
+    LOCKED: 'Too many incorrect codes. Verification is locked for now - even a correct code is refused until the lock ends. Wait before entering another code.',
     RATE_LIMITED: 'Too many attempts. Please wait a moment and try again.',
     SESSION_REJECTED: 'We could not verify the code for this session. Please try again.',
     VERIFY_UNAVAILABLE: 'We could not verify the code right now. Please try again.',
@@ -186,13 +190,41 @@ function classifyTwoFactorVerifyFailure(status, json) {
         return 'VERIFY_UNAVAILABLE';
     return 'VERIFY_FAILED';
 }
+/**
+ * PAY-1608: the window as words - "15 minutes", "1 minute", "45 seconds", "2 hours". Rounded UP, so the user is never
+ * told a shorter wait than the IDP enforces. Undefined in, undefined out.
+ */
+function formatLockWindow(seconds) {
+    if (typeof seconds !== 'number' || !Number.isFinite(seconds) || seconds <= 0)
+        return undefined;
+    const plural = (n, unit) => `${n} ${unit}${n === 1 ? '' : 's'}`;
+    if (seconds < 60)
+        return plural(Math.ceil(seconds), 'second');
+    const minutes = Math.ceil(seconds / 60);
+    if (minutes < 120)
+        return plural(minutes, 'minute');
+    return plural(Math.ceil(minutes / 60), 'hour');
+}
+/** PAY-1608: the LOCKED sentence with the IDP's real window, or the number-free one when none was sent. */
+function lockedText(retryAfterSeconds) {
+    const window = formatLockWindow(retryAfterSeconds);
+    return window
+        ? `Too many incorrect codes. Verification is locked for ${window} - wait before entering another code.`
+        : FIXED_TEXT.LOCKED;
+}
 function twoFactorVerifyFailure(result, method) {
     const refusal = stepUpRefusal(result.status, result.json);
     if (refusal)
         return stepUpResponse(refusal, result.attemptedRefresh);
     const code = classifyTwoFactorVerifyFailure(result.status, result.json);
-    const error = code === 'INVALID_CODE' ? INVALID_CODE_TEXT[method] : FIXED_TEXT[code];
-    return server_1.NextResponse.json({ success: false, error, code, meta: { attemptedRefresh: result.attemptedRefresh } }, { status: result.status });
+    const error = code === 'INVALID_CODE' ? INVALID_CODE_TEXT[method]
+        : code === 'LOCKED' ? lockedText(result.retryAfterSeconds)
+            : FIXED_TEXT[code];
+    // PAY-1608: a lock or a throttle relays the IDP's window, as a number (for a client that words it itself) and as the
+    // standard header. Never on other failures, and never invented: absent upstream means absent here.
+    const wait = (code === 'LOCKED' || code === 'RATE_LIMITED') && formatLockWindow(result.retryAfterSeconds)
+        ? Math.ceil(result.retryAfterSeconds) : undefined;
+    return server_1.NextResponse.json({ success: false, error, code, ...(wait ? { retryAfterSeconds: wait } : {}), meta: { attemptedRefresh: result.attemptedRefresh } }, { status: result.status, ...(wait ? { headers: { 'Retry-After': String(wait) } } : {}) });
 }
 const SEND_LABEL = { sms: 'text message', email: 'email' };
 function classifyTwoFactorSendFailure(status, json) {

package/dist/middleware/create-middleware.js

@@ -160,6 +160,31 @@ function refreshFailureResponse(request, location, errorCode, clearCookies = fal
     }
     return redirectTo(request, location, clearCookies);
 }
+/**
+ * PAY-2147: the terminal answer when the middleware CANNOT TELL whether the session is good
+ * (circuit breaker open, a half-open breaker refusing a refresh attempt, or the viability read failed).
+ *
+ * "I could not check" is not a verdict on the session, so this NEVER touches a cookie: a transient blip
+ * in the IdP / viability path used to wipe the session of every user who made any request while the
+ * breaker was open. Cookies are cleared only on a POSITIVE signal (force_invalidated, stale_session,
+ * pre_2fa_token_expired, refresh 401/403, explicit sign-out) - never from here.
+ *
+ *  - /api/*  -> 503 JSON a caller can branch on (a redirect would be followed by fetch() into a 200 HTML page).
+ *  - pages   -> /service-unavailable (public + allowDuringCircuitBreakerOpen, so it cannot loop), carrying the
+ *               requested path as `callbackUrl` so "Try again" returns the user to it still signed in. The path goes
+ *               through safeCallbackPath (URL-parser origin check): an off-origin or auth-surface value is dropped.
+ */
+function serviceUnavailableResponse(request) {
+    const { pathname, search } = request.nextUrl;
+    if (pathname.startsWith('/api/')) {
+        return server_1.NextResponse.json({ error: 'ServiceUnavailable' }, { status: 503 });
+    }
+    const target = new URL('/service-unavailable', request.url);
+    const callback = (0, safe_callback_1.safeCallbackPath)(pathname + search);
+    if (callback !== '/')
+        target.searchParams.set('callbackUrl', callback);
+    return server_1.NextResponse.redirect(target);
+}
 // =============================================================================
 // AUTH DECISION ENGINE
 // =============================================================================
@@ -198,15 +223,12 @@ function makeAuthDecision(ctx) {
         return { type: 'allow' };
     }
     // --- Circuit breaker open: Service degraded ---
+    // PAY-2147: the breaker opening says the IdP/viability path is unreachable, NOT that the session is bad.
+    // Answer "service unavailable" (503 for /api, /service-unavailable for pages) and leave every cookie alone.
     if (circuitBreakerOpen) {
         if (onLoginPage)
             return { type: 'allow' };
-        return {
-            type: 'redirect',
-            location: `${LOGIN_PAGE}?error=ServiceUnavailable`,
-            reason: 'circuit_breaker_open',
-            clearCookies: true
-        };
+        return { type: 'service_error', reason: 'circuit_breaker_open' };
     }
     // --- No session cookie: Need to login ---
     if (!sessionPointer.exists) {
@@ -227,6 +249,8 @@ function makeAuthDecision(ctx) {
     }
     // --- Service error: Can't verify session ---
     if (sessionStatus.exists === null || sessionStatus.forceInvalid === null) {
+        if (onLoginPage)
+            return { type: 'allow' }; // the login page must stay reachable while the check is down
         return { type: 'service_error', reason: 'viability_check_failed' };
     }
     // --- Session force-invalidated (admin action, password change, etc.) ---
@@ -466,6 +490,17 @@ function decideForceInvalid(data, revocationFailMode) {
     // No revocationStatus: an older boolean producer. Absence of both stays false.
     return data.forceInvalid === true || data.revoked === true;
 }
+/**
+ * PAY-2147: does the request carry a session cookie? Used ONLY when the viability read itself FAILED.
+ * Before this, a failed read left sessionPointer.exists=false, so the decision engine took its `no_session` arm
+ * (pages -> the LOGIN page, /api -> straight through) and its `exists === null` -> service_error arm below it was
+ * unreachable dead code: a user holding a perfectly good session was told to sign in during an outage. With a
+ * cookie present and the check down we do not know the session is bad, so the engine must say "service
+ * unavailable", not "sign in". No cookie -> unchanged (no_session).
+ */
+function hasSessionCookie(request) {
+    return !!(request.cookies.get((0, app_slug_1.getSessionCookieName)())?.value || request.cookies.get((0, app_slug_1.getSecureSessionCookieName)())?.value);
+}
 /** Check session viability via internal API */
 async function checkViability(request, endpoint, log, revocationFailMode) {
     const sessionStatus = {
@@ -551,12 +586,14 @@ async function checkViability(request, endpoint, log, revocationFailMode) {
             log.error('Viability check failed', { status: response.status });
             sessionStatus.exists = null;
             sessionStatus.forceInvalid = null;
+            sessionPointer.exists = hasSessionCookie(request); // PAY-2147: see hasSessionCookie
         }
     }
     catch (error) {
         log.error('Viability check error', { error: error instanceof Error ? error.message : String(error) });
         sessionStatus.exists = null;
         sessionStatus.forceInvalid = null;
+        sessionPointer.exists = hasSessionCookie(request); // PAY-2147: see hasSessionCookie
     }
     return { sessionStatus, sessionPointer };
 }
@@ -569,7 +606,7 @@ async function executeDecision(request, decision, pathname, sessionPointer, sess
         case 'redirect':
             return redirectTo(request, decision.location, decision.clearCookies);
         case 'service_error':
-            return server_1.NextResponse.redirect(new URL('/service-unavailable', request.url));
+            return serviceUnavailableResponse(request);
         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.
@@ -629,7 +666,9 @@ async function handleRefresh(request, safeCallback, opts) {
     // Check if circuit breaker allows refresh attempt
     if (!cb.canAttemptRefresh()) {
         log.warn('Circuit breaker preventing refresh attempt');
-        return refreshFailureResponse(request, `${LOGIN_PAGE}?callbackUrl=${encodeURIComponent(safeCallback)}&error=ServiceUnavailable`, 'ServiceUnavailable', true);
+        // 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);
     }
     try {
         const baseUrl = (0, internal_api_url_1.getInternalApiUrl)(request);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@payez/next-mvp",
-  "version": "4.5.1",
+  "version": "4.5.3",
   "sideEffects": false,
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/scripts/check-publish-health.mjs

@@ -31,6 +31,7 @@ import { execFileSync } from 'node:child_process';
 import { readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { dirname, join } from 'node:path';
+import { resolvePublishTag } from './publish-health-tag.mjs';
 
 const here = dirname(fileURLToPath(import.meta.url));
 const pkgPath = join(here, '..', 'package.json');
@@ -69,6 +70,14 @@ try {
 const name = local.name;
 const localVersion = local.version;
 
+// PAY-2136: compare against the dist-tag being published (`npm publish --tag next` -> `next`), not always `latest`.
+const tag = resolvePublishTag(process.argv.slice(2), process.env);
+if (tag === null) {
+  console.error('[publish-health] INCONCLUSIVE: the requested dist-tag is not a plain tag name.');
+  process.exit(2);
+}
+const registrySpec = tag === 'latest' ? name : `${name}@${tag}`;
+
 // Auth is reported separately: a dead credential is the ROOT of 171900, and folding
 // it into "lagging" would hide which of the two things is actually broken.
 let authUser = null;
@@ -105,11 +114,11 @@ const REGISTRY_RETRY_MS = 2000;
 let registryVersion = null;
 for (let attempt = 1; attempt <= REGISTRY_ATTEMPTS; attempt++) {
   try {
-    registryVersion = run(['view', name, 'version', '--prefer-online']);
+    registryVersion = run(['view', registrySpec, 'version', '--prefer-online']);
   } catch (err) {
     const msg = String(err.stderr || err.message || '');
     if (/E404|404 Not Found/.test(msg)) {
-      console.error(`[publish-health] FAIL: ${name} has NEVER been published to the registry.`);
+      console.error(`[publish-health] FAIL: ${registrySpec} has NEVER been published to the registry.`);
       console.error(`[publish-health] local=${localVersion} registry=<absent>`);
       process.exit(1);
     }
@@ -135,7 +144,7 @@ const delta = compareVersions(localVersion, registryVersion);
 
 console.log(`[publish-health] package  : ${name}`);
 console.log(`[publish-health] local    : ${localVersion}`);
-console.log(`[publish-health] registry : ${registryVersion}`);
+console.log(`[publish-health] registry : ${registryVersion} (dist-tag ${tag})`);
 console.log(`[publish-health] npm auth : ${authUser ? `logged in as ${authUser}` : 'NOT AUTHENTICATED (npm whoami failed)'}`);
 
 if (delta > 0) {

package/scripts/publish-health-tag.mjs

@@ -0,0 +1,27 @@
+/**
+ * Which dist-tag should the publish-health check compare the local version against?
+ *
+ * PAY-2136 (BAPert 71043): `npm publish --tag next` runs this check as `postpublish`, and it compared local against
+ * the `latest` tag, so a CORRECT next-tag publish printed "registry LAGS local" and exited 1 - noise nobody should
+ * learn to ignore. Resolution order: `--tag <x>` / `--tag=<x>` argument, then npm_config_tag (npm sets it inside
+ * lifecycle scripts from `--tag`), then `latest`. A tag that is not a plain word is rejected (null), never guessed.
+ */
+const TAG = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+
+export function resolvePublishTag(argv = [], env = {}) {
+  let raw;
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--tag') {
+      raw = argv[i + 1];
+      break;
+    }
+    if (a.startsWith('--tag=')) {
+      raw = a.slice('--tag='.length);
+      break;
+    }
+  }
+  if (raw === undefined) raw = env.npm_config_tag;
+  if (raw === undefined || raw === '') return 'latest';
+  return TAG.test(raw) ? raw : null;
+}

package/src/auth/auth-decision.ts

@@ -36,12 +36,27 @@ export type AuthAction =
   | { type: 'redirect'; location: string; reason: string; clearCookies?: boolean }
   | { type: 'service_error'; reason: string };
 
+/** PAY-2180: warn once per process, not per request. */
+let deprecationWarned = false;
+
 /**
  * Main decision function - pure, testable, deterministic.
  * PAY-2136: when `context.isPrefetch` is set, no redirect it returns asks for cookies to be cleared; the
  * redirect itself is kept, and the next real navigation reaches the same decision and clears then.
+ *
+ * @deprecated PAY-2180: this exported engine is NOT the one the middleware runs. `createMvpMiddleware` decides with
+ * its own private engine (middleware/create-middleware.ts), so calling this answers a question nothing enforces.
+ * A sweep found no code consumer in the portal, idealvibe, idealresume or cryptaply. It will be REMOVED in the next
+ * major version, together with its re-exports from the package root and `/edge`. Use `createMvpMiddleware`.
  */
 export function makeAuthDecision(context: AuthContext): AuthAction {
+  if (!deprecationWarned) {
+    deprecationWarned = true;
+    console.warn(
+      '[next-mvp] makeAuthDecision (auth/auth-decision) is deprecated (PAY-2180) and will be removed in the next major: ' +
+        'createMvpMiddleware does not use it. Use createMvpMiddleware.'
+    );
+  }
   const action = decide(context);
   if (context.isPrefetch && action.type === 'redirect' && action.clearCookies) {
     const { clearCookies: _dropped, ...rest } = action;
@@ -88,8 +103,10 @@ function decide(context: AuthContext): AuthAction {
     return {
       type: 'redirect',
       location: '/account-auth/login?error=ServiceUnavailable&reason=CircuitBreakerOpen',
-      reason: 'CircuitBreakerOpen',
-      clearCookies: true
+      reason: 'CircuitBreakerOpen'
+      // PAY-2147: NO clearCookies. The breaker opening is not a verdict on the session; clearing here logged out every
+      // user who made a request during a blip. (Deprecated twin: it cannot express a 503 or the /service-unavailable
+      // page - createMvpMiddleware does, see serviceUnavailableResponse.)
     };
   }
 

package/src/lib/idp-fetch.ts

@@ -3,12 +3,13 @@ import { getTokenTestAware } from './test-aware-get-token';
 import { getSession } from './session-store';
 import { internalRefresh } from './internal-api';
 import { assertAbsoluteIdpUrl } from './idp-url-guard';
+import { parseRetryAfterSeconds } from './retry-after';
 
 // Re-exported so `idp-fetch` remains the single obvious import for IDP calling
 // concerns; the implementation lives in a dependency-free leaf so the three
 // direct-fetch callers (auth/jwks.ts, auth/passkey-signin.ts x2) do not have to
 // pull this module's server-only chain in for one regex.
-export { assertAbsoluteIdpUrl };
+export { assertAbsoluteIdpUrl, parseRetryAfterSeconds };
 
 /**
  * Centralized IDP fetch helper
@@ -21,6 +22,12 @@ export interface IdpFetchResult<T = any> {
   status: number;
   json: T | null;
   attemptedRefresh: boolean;
+  /**
+   * PAY-1608: the upstream Retry-After in whole seconds, when the IDP sent a usable one. Core sends it on every
+   * 2FA lock (MfaController.SecondFactorLocked: 429 + Retry-After 900; VerifyTotp: what is left of the lock).
+   * It used to be dropped here, so no BFF could state the real lock window. Absent otherwise.
+   */
+  retryAfterSeconds?: number;
 }
 
 function buildHeaders(req: NextRequest, bearer?: string, extra?: Record<string, string>) {
@@ -158,5 +165,6 @@ export async function idpFetchJSON<T = any>(
     } catch {}
   }
 
-  return { ok: res.ok, status: res.status, json: json as T | null, attemptedRefresh };
+  const retryAfterSeconds = parseRetryAfterSeconds(res.headers?.get?.('Retry-After'));
+  return { ok: res.ok, status: res.status, json: json as T | null, attemptedRefresh, ...(retryAfterSeconds ? { retryAfterSeconds } : {}) };
 }

package/src/lib/retry-after.ts

@@ -0,0 +1,24 @@
+/**
+ * PAY-1608: parse an HTTP Retry-After header to whole seconds.
+ *
+ * Accepts delta-seconds ("900") and an HTTP date in the future. Answers undefined for absent, zero, negative,
+ * fractional, past or malformed values - a caller that gets undefined states no window rather than a guessed one.
+ *
+ * A dependency-free leaf on purpose: idp-fetch re-exports it, but a test can load it without the session/redis
+ * graph idp-fetch pulls in.
+ */
+export function parseRetryAfterSeconds(value: string | null | undefined, nowMs: number = Date.now()): number | undefined {
+  if (typeof value !== 'string') return undefined;
+  const v = value.trim();
+  if (/^\d+$/.test(v)) {
+    const n = parseInt(v, 10);
+    return n > 0 ? n : undefined;
+  }
+  // Only something that looks like an HTTP date (it has letters: "Sat, 10 Oct 2026 12:01:30 GMT") is parsed as
+  // one; "-5" and "1.5" must not reach Date.parse, which would read them as years.
+  if (!/[a-z]/i.test(v)) return undefined;
+  const at = Date.parse(v);
+  if (!Number.isFinite(at)) return undefined;
+  const secs = Math.ceil((at - nowMs) / 1000);
+  return secs > 0 ? secs : undefined;
+}

package/src/lib/two-factor-verify-failure.ts

@@ -1,248 +1,277 @@
-/**
- * PAY-1443: the ONE way a 2FA verify handler answers an IDP rejection.
- *
- * Found live (portal.keelauth.com /account-auth/verify-code, 2026-09-17): a wrong
- * authenticator code rendered as the banner text `{ message = Invalid authentication code }`.
- * The handlers relayed `result.json?.message` verbatim, and the IDP's error text is not a
- * user-facing string:
- *   - deployed IDP: the >=400 envelope sets Message = value.ToString() on the controller's
- *     `new { message = ... }`, producing C#'s anonymous-object ToString `{ message = X }`
- *     (or a DTO's TYPE NAME for a typed body);
- *   - IDP master (e03a0e449): no ToString, but the lookup is case-sensitive, so the envelope
- *     message is "An error occurred" and the real text sits only in error.details.message.
- *
- * So the upstream text is used ONLY TO CLASSIFY, never rendered. The caller gets:
- *   - the upstream HTTP status, unchanged (verify-code's 401 branch probes session liveness);
- *   - a stable `code` the UI can switch on;
- *   - one of the fixed sentences below.
- */
-import { NextResponse } from 'next/server';
-
-export type TwoFactorVerifyMethod = 'totp' | 'sms' | 'email' | 'backup_code';
-
-export type TwoFactorVerifyFailureCode =
-  | 'INVALID_CODE'
-  | 'LOCKED'
-  | 'RATE_LIMITED'
-  | 'SESSION_REJECTED'
-  | 'STEP_UP_FACTOR_NOT_ALLOWED'
-  | 'VERIFY_UNAVAILABLE'
-  | 'VERIFY_FAILED';
-
-const INVALID_CODE_TEXT: Record<TwoFactorVerifyMethod, string> = {
-  totp: 'Invalid authentication code. Please try again.',
-  sms: 'Invalid verification code. Please try again.',
-  email: 'Invalid verification code. Please try again.',
-  backup_code: 'Invalid backup code. Please try again.',
-};
-
-const FIXED_TEXT: Record<Exclude<TwoFactorVerifyFailureCode, 'INVALID_CODE' | 'STEP_UP_FACTOR_NOT_ALLOWED'>, string> = {
-  LOCKED: 'Too many incorrect codes. Verification is locked for 15 minutes - wait before entering another code.',
-  RATE_LIMITED: 'Too many attempts. Please wait a moment and try again.',
-  SESSION_REJECTED: 'We could not verify the code for this session. Please try again.',
-  VERIFY_UNAVAILABLE: 'We could not verify the code right now. Please try again.',
-  VERIFY_FAILED: 'We could not verify that code. Please try again.',
-};
-
-/**
- * MfaTotpService ErrorCode "locked": the bare code, or `code = locked` inside a deployed
- * ToString envelope.
- *
- * CAUGHT BEFORE SHIPPING (self-test, this file): an earlier draft wrote this with  word
- * boundaries around `code` and `locked`. The literal that landed on disk was not the two
- * characters backslash+b - it was a raw ASCII backspace byte (0x08), invisible in every editor
- * and terminal that rendered this file, INCLUDING Read/cat/grep in this session. A regex with a
- * literal backspace control character where a word-boundary assertion was intended matches
- * nothing real, so `IDP_LOCKED.test(...)` was silently false on every fixture - caught only
- * because the RED-first test stayed red after the earlier "fix" and a hex dump of the compiled
- * line showed 08 where 5c62 (backslash, b) should have been. Word boundaries are not
- * load-bearing for the shipped control cases (a bare code=locked substring is specific enough
- * here - the IdP field name is literally code), so this drops them rather than re-risk the same
- * invisible-byte trap.
- */
-const IDP_LOCKED = /^locked$|code\s*=\s*locked/i;
-
-/**
- * MfaTotpService ErrorCode "server_error" (PAY-1589: secret cannot be decrypted) or "service_unavailable" (330830): the replay store could not be read or written, so
- * the verify FAILED CLOSED. It is a fault on our side, not a wrong code. Matched on the CODE only, never on
- * the prose - "unavailable" appears in unrelated messages - in the same two forms as IDP_LOCKED.
- */
-const IDP_UNAVAILABLE = /^(?:service_unavailable|server_error)$|code\s*=\s*(?:service_unavailable|server_error)\b/i;
-
-const WRONG_CODE = /\b(invalid|incorrect|wrong|expired)\b[^.]{0,40}\b(code|otp|totp|token)\b|\binvalid_code\b/i;
-
-/**
- * PAY-1611: the IdP's 403 STEP_UP_FACTOR_NOT_ALLOWED refusal (Core ExternalAuthController.DeliveredCodeStepUpRefusal).
- * A session signed in with an emailed/texted code only cannot re-prove itself with another emailed/texted code; the
- * IdP says which factors it WILL take and what the user can do instead. The portal can only offer those options if
- * this BFF relays them, so on that one refusal we emit the code plus ALLOWLISTED copies of the two lists.
- *
- * On the wire PayEzControllerBase.OnActionExecuted re-envelopes the action's object: the code is `error.code` and the
- * object sits under `error.details`, so the lists are `error.details.allowed_methods` / `error.details.next_steps`.
- * The unenveloped action shape (top-level `error` string, lists at top level) is accepted too.
- *
- * NEVER relayed (PAY-1443 stands): `error_description` or any other IdP prose, and any IdP `endpoint` - the consumer
- * maps each action to its OWN route from a constant table. Unknown methods/actions are dropped, not passed through;
- * missing or malformed lists give EMPTY lists, never invented ones.
- */
-export const STEP_UP_REFUSAL_CODE = 'STEP_UP_FACTOR_NOT_ALLOWED';
-const STEP_UP_METHODS = ['totp', 'webauthn', 'backup_code'] as const;
-const STEP_UP_ACTIONS = ['use_authenticator', 'reset_password', 'enroll_authenticator'] as const;
-export type StepUpMethod = (typeof STEP_UP_METHODS)[number];
-export type StepUpAction = (typeof STEP_UP_ACTIONS)[number];
-export type StepUpNextStep = { action: 'use_authenticator'; methods: StepUpMethod[] } | { action: Exclude<StepUpAction, 'use_authenticator'> };
-export type StepUpRefusal = { allowed_methods: StepUpMethod[]; next_steps: StepUpNextStep[] };
-
-const STEP_UP_TEXT =
-  'This session was signed in with an emailed or texted code only, so another emailed or texted code cannot confirm it is you.';
-
-function allowedMethods(v: unknown): StepUpMethod[] {
-  if (!Array.isArray(v)) return [];
-  const out: StepUpMethod[] = [];
-  for (const m of v) {
-    if ((STEP_UP_METHODS as readonly unknown[]).includes(m) && !out.includes(m as StepUpMethod)) out.push(m as StepUpMethod);
-  }
-  return out;
-}
-
-/** The step-up refusal's allowlisted lists, or null when this is not that refusal (status 403 + the exact code only). */
-export function stepUpRefusal(status: number, json: unknown): StepUpRefusal | null {
-  if (status !== 403 || !json || typeof json !== 'object') return null;
-  const j = json as Record<string, unknown>;
-  const err = j.error;
-  let code: unknown;
-  let src: Record<string, unknown> = j;
-  if (err && typeof err === 'object') {
-    const e = err as Record<string, unknown>;
-    code = e.code;
-    src = e.details && typeof e.details === 'object' ? (e.details as Record<string, unknown>) : {};
-  } else {
-    code = err;
-  }
-  if (code !== STEP_UP_REFUSAL_CODE) return null;
-  const next_steps: StepUpNextStep[] = [];
-  const seen = new Set<string>();
-  for (const step of Array.isArray(src.next_steps) ? src.next_steps : []) {
-    if (!step || typeof step !== 'object') continue;
-    const action = (step as Record<string, unknown>).action;
-    if (typeof action !== 'string' || !(STEP_UP_ACTIONS as readonly string[]).includes(action) || seen.has(action)) continue;
-    seen.add(action);
-    next_steps.push(
-      action === 'use_authenticator'
-        ? { action, methods: allowedMethods((step as Record<string, unknown>).methods) }
-        : { action: action as Exclude<StepUpAction, 'use_authenticator'> },
-    );
-  }
-  return { allowed_methods: allowedMethods(src.allowed_methods), next_steps };
-}
-
-function stepUpResponse(refusal: StepUpRefusal, attemptedRefresh: boolean): NextResponse {
-  return NextResponse.json(
-    { success: false, error: STEP_UP_TEXT, code: STEP_UP_REFUSAL_CODE, ...refusal, meta: { attemptedRefresh } },
-    { status: 403 },
-  );
-}
-
-/**
- * Every string the IDP might have put anywhere in the error envelope, unwrapped from
- * `{ message = X }` ToString form. Classification input only.
- */
-export function upstreamErrorTexts(json: unknown): string[] {
-  const out: string[] = [];
-  const add = (v: unknown) => {
-    if (typeof v !== 'string' || !v) return;
-    out.push(v);
-    const m = v.match(/^\{\s*\w+\s*=\s*(.*?)\s*\}$/s);
-    if (m) out.push(m[1]);
-  };
-  const j = json as Record<string, any> | null | undefined;
-  if (!j || typeof j !== 'object') return out;
-  add(j.message);
-  add(j.code);
-  add(j.error);
-  if (j.error && typeof j.error === 'object') {
-    add(j.error.message);
-    add(j.error.code);
-    const d = j.error.details;
-    if (d && typeof d === 'object') { add(d.message); add(d.Message); add(d.code); add(d.errorCode); }
-  }
-  return out;
-}
-
-export function classifyTwoFactorVerifyFailure(status: number, json: unknown): TwoFactorVerifyFailureCode {
-  // PAY-1611: checked FIRST - an exact code on a 403, so no prose rule below can claim it first.
-  if (stepUpRefusal(status, json)) return 'STEP_UP_FACTOR_NOT_ALLOWED';
-  // PAY-902 (BAPert R484): the IdP's lockout CODE, not its prose. Door A is post-authentication, so stating
-  // the lockout discloses nothing; telling a locked-out user "try again" sends them to spend attempts.
-  //
-  // PAY-1574: THIS MUST COME BEFORE THE 429 TEST. PayEz-Core PR 366 answers a TOTP lockout as HTTP 429 carrying
-  // code "locked". With `status === 429` first, that status returned RATE_LIMITED and the lock code the IdP had
-  // just started sending was discarded unread - the tester saw a plain rate limit. A 429 with NO lock code is
-  // still RATE_LIMITED, below.
-  if (upstreamErrorTexts(json).some((t) => IDP_LOCKED.test(t))) return 'LOCKED';
-  if (status === 429) return 'RATE_LIMITED';
-  // PAY-1574: the verify failed closed on OUR side (replay store down). Not a wrong code, whatever the status.
-  if (upstreamErrorTexts(json).some((t) => IDP_UNAVAILABLE.test(t))) return 'VERIFY_UNAVAILABLE';
-  if (upstreamErrorTexts(json).some((t) => WRONG_CODE.test(t))) return 'INVALID_CODE';
-  if (status === 401 || status === 403) return 'SESSION_REJECTED';
-  if (status >= 500 || status === 0) return 'VERIFY_UNAVAILABLE';
-  return 'VERIFY_FAILED';
-}
-
-export function twoFactorVerifyFailure(
-  result: { status: number; json: unknown; attemptedRefresh: boolean },
-  method: TwoFactorVerifyMethod,
-): NextResponse {
-  const refusal = stepUpRefusal(result.status, result.json);
-  if (refusal) return stepUpResponse(refusal, result.attemptedRefresh);
-  const code = classifyTwoFactorVerifyFailure(result.status, result.json);
-  const error = code === 'INVALID_CODE' ? INVALID_CODE_TEXT[method] : FIXED_TEXT[code as keyof typeof FIXED_TEXT];
-  return NextResponse.json(
-    { success: false, error, code, meta: { attemptedRefresh: result.attemptedRefresh } },
-    { status: result.status },
-  );
-}
-
-/**
- * PAY-1443 residual: account/send-code on the SAME verify-code screen. A send has no
- * "wrong code" outcome, so it gets its own small classification, but the same rule applies:
- * upstream text/code never reach the response. The portal renders `data.message || data.error`,
- * so no `message` field is emitted on failure.
- */
-export type TwoFactorSendMethod = 'sms' | 'email';
-
-export type TwoFactorSendFailureCode =
-  | 'RATE_LIMITED'
-  | 'SESSION_REJECTED'
-  | 'STEP_UP_FACTOR_NOT_ALLOWED'
-  | 'SEND_UNAVAILABLE'
-  | 'SEND_FAILED';
-
-const SEND_LABEL: Record<TwoFactorSendMethod, string> = { sms: 'text message', email: 'email' };
-
-export function classifyTwoFactorSendFailure(status: number, json?: unknown): TwoFactorSendFailureCode {
-  if (stepUpRefusal(status, json)) return 'STEP_UP_FACTOR_NOT_ALLOWED'; // PAY-1611, before the 401/403 branch
-  if (status === 429) return 'RATE_LIMITED';
-  if (status === 401 || status === 403) return 'SESSION_REJECTED';
-  if (status >= 500 || status === 0) return 'SEND_UNAVAILABLE';
-  return 'SEND_FAILED';
-}
-
-export function twoFactorSendCodeFailure(
-  result: { status: number; attemptedRefresh: boolean; json?: unknown },
-  method: TwoFactorSendMethod,
-): NextResponse {
-  const refusal = stepUpRefusal(result.status, result.json);
-  if (refusal) return stepUpResponse(refusal, result.attemptedRefresh);
-  const code = classifyTwoFactorSendFailure(result.status, result.json);
-  const label = SEND_LABEL[method];
-  const error =
-    code === 'RATE_LIMITED' ? FIXED_TEXT.RATE_LIMITED
-    : code === 'SESSION_REJECTED' ? `We could not send a ${label} code for this session. Please try again.`
-    : code === 'SEND_UNAVAILABLE' ? `We could not send a ${label} code right now. Please try again.`
-    : `We could not send a ${label} code. Please try again.`;
-  return NextResponse.json(
-    { success: false, error, code, meta: { attemptedRefresh: result.attemptedRefresh } },
-    { status: result.status },
-  );
-}
+/**
+ * PAY-1443: the ONE way a 2FA verify handler answers an IDP rejection.
+ *
+ * Found live (portal.keelauth.com /account-auth/verify-code, 2026-09-17): a wrong
+ * authenticator code rendered as the banner text `{ message = Invalid authentication code }`.
+ * The handlers relayed `result.json?.message` verbatim, and the IDP's error text is not a
+ * user-facing string:
+ *   - deployed IDP: the >=400 envelope sets Message = value.ToString() on the controller's
+ *     `new { message = ... }`, producing C#'s anonymous-object ToString `{ message = X }`
+ *     (or a DTO's TYPE NAME for a typed body);
+ *   - IDP master (e03a0e449): no ToString, but the lookup is case-sensitive, so the envelope
+ *     message is "An error occurred" and the real text sits only in error.details.message.
+ *
+ * So the upstream text is used ONLY TO CLASSIFY, never rendered. The caller gets:
+ *   - the upstream HTTP status, unchanged (verify-code's 401 branch probes session liveness);
+ *   - a stable `code` the UI can switch on;
+ *   - one of the fixed sentences below.
+ */
+import { NextResponse } from 'next/server';
+
+export type TwoFactorVerifyMethod = 'totp' | 'sms' | 'email' | 'backup_code';
+
+export type TwoFactorVerifyFailureCode =
+  | 'INVALID_CODE'
+  | 'LOCKED'
+  | 'RATE_LIMITED'
+  | 'SESSION_REJECTED'
+  | 'STEP_UP_FACTOR_NOT_ALLOWED'
+  | 'VERIFY_UNAVAILABLE'
+  | 'VERIFY_FAILED';
+
+const INVALID_CODE_TEXT: Record<TwoFactorVerifyMethod, string> = {
+  totp: 'Invalid authentication code. Please try again.',
+  sms: 'Invalid verification code. Please try again.',
+  email: 'Invalid verification code. Please try again.',
+  backup_code: 'Invalid backup code. Please try again.',
+};
+
+const FIXED_TEXT: Record<Exclude<TwoFactorVerifyFailureCode, 'INVALID_CODE' | 'STEP_UP_FACTOR_NOT_ALLOWED'>, string> = {
+  // PAY-1608: NO NUMBER HERE. This is the sentence for a lock whose window the IDP did not send; lockedText()
+  // states the real window when Retry-After arrives. A hard-coded "15 minutes" was true only while every lock was 15.
+  LOCKED: 'Too many incorrect codes. Verification is locked for now - even a correct code is refused until the lock ends. Wait before entering another code.',
+  RATE_LIMITED: 'Too many attempts. Please wait a moment and try again.',
+  SESSION_REJECTED: 'We could not verify the code for this session. Please try again.',
+  VERIFY_UNAVAILABLE: 'We could not verify the code right now. Please try again.',
+  VERIFY_FAILED: 'We could not verify that code. Please try again.',
+};
+
+/**
+ * MfaTotpService ErrorCode "locked": the bare code, or `code = locked` inside a deployed
+ * ToString envelope.
+ *
+ * CAUGHT BEFORE SHIPPING (self-test, this file): an earlier draft wrote this with  word
+ * boundaries around `code` and `locked`. The literal that landed on disk was not the two
+ * characters backslash+b - it was a raw ASCII backspace byte (0x08), invisible in every editor
+ * and terminal that rendered this file, INCLUDING Read/cat/grep in this session. A regex with a
+ * literal backspace control character where a word-boundary assertion was intended matches
+ * nothing real, so `IDP_LOCKED.test(...)` was silently false on every fixture - caught only
+ * because the RED-first test stayed red after the earlier "fix" and a hex dump of the compiled
+ * line showed 08 where 5c62 (backslash, b) should have been. Word boundaries are not
+ * load-bearing for the shipped control cases (a bare code=locked substring is specific enough
+ * here - the IdP field name is literally code), so this drops them rather than re-risk the same
+ * invisible-byte trap.
+ */
+const IDP_LOCKED = /^locked$|code\s*=\s*locked/i;
+
+/**
+ * MfaTotpService ErrorCode "server_error" (PAY-1589: secret cannot be decrypted) or "service_unavailable" (330830): the replay store could not be read or written, so
+ * the verify FAILED CLOSED. It is a fault on our side, not a wrong code. Matched on the CODE only, never on
+ * the prose - "unavailable" appears in unrelated messages - in the same two forms as IDP_LOCKED.
+ */
+const IDP_UNAVAILABLE = /^(?:service_unavailable|server_error)$|code\s*=\s*(?:service_unavailable|server_error)\b/i;
+
+const WRONG_CODE = /\b(invalid|incorrect|wrong|expired)\b[^.]{0,40}\b(code|otp|totp|token)\b|\binvalid_code\b/i;
+
+/**
+ * PAY-1611: the IdP's 403 STEP_UP_FACTOR_NOT_ALLOWED refusal (Core ExternalAuthController.DeliveredCodeStepUpRefusal).
+ * A session signed in with an emailed/texted code only cannot re-prove itself with another emailed/texted code; the
+ * IdP says which factors it WILL take and what the user can do instead. The portal can only offer those options if
+ * this BFF relays them, so on that one refusal we emit the code plus ALLOWLISTED copies of the two lists.
+ *
+ * On the wire PayEzControllerBase.OnActionExecuted re-envelopes the action's object: the code is `error.code` and the
+ * object sits under `error.details`, so the lists are `error.details.allowed_methods` / `error.details.next_steps`.
+ * The unenveloped action shape (top-level `error` string, lists at top level) is accepted too.
+ *
+ * NEVER relayed (PAY-1443 stands): `error_description` or any other IdP prose, and any IdP `endpoint` - the consumer
+ * maps each action to its OWN route from a constant table. Unknown methods/actions are dropped, not passed through;
+ * missing or malformed lists give EMPTY lists, never invented ones.
+ */
+export const STEP_UP_REFUSAL_CODE = 'STEP_UP_FACTOR_NOT_ALLOWED';
+const STEP_UP_METHODS = ['totp', 'webauthn', 'backup_code'] as const;
+const STEP_UP_ACTIONS = ['use_authenticator', 'reset_password', 'enroll_authenticator'] as const;
+export type StepUpMethod = (typeof STEP_UP_METHODS)[number];
+export type StepUpAction = (typeof STEP_UP_ACTIONS)[number];
+export type StepUpNextStep = { action: 'use_authenticator'; methods: StepUpMethod[] } | { action: Exclude<StepUpAction, 'use_authenticator'> };
+export type StepUpRefusal = { allowed_methods: StepUpMethod[]; next_steps: StepUpNextStep[] };
+
+const STEP_UP_TEXT =
+  'This session was signed in with an emailed or texted code only, so another emailed or texted code cannot confirm it is you.';
+
+function allowedMethods(v: unknown): StepUpMethod[] {
+  if (!Array.isArray(v)) return [];
+  const out: StepUpMethod[] = [];
+  for (const m of v) {
+    if ((STEP_UP_METHODS as readonly unknown[]).includes(m) && !out.includes(m as StepUpMethod)) out.push(m as StepUpMethod);
+  }
+  return out;
+}
+
+/** The step-up refusal's allowlisted lists, or null when this is not that refusal (status 403 + the exact code only). */
+export function stepUpRefusal(status: number, json: unknown): StepUpRefusal | null {
+  if (status !== 403 || !json || typeof json !== 'object') return null;
+  const j = json as Record<string, unknown>;
+  const err = j.error;
+  let code: unknown;
+  let src: Record<string, unknown> = j;
+  if (err && typeof err === 'object') {
+    const e = err as Record<string, unknown>;
+    code = e.code;
+    src = e.details && typeof e.details === 'object' ? (e.details as Record<string, unknown>) : {};
+  } else {
+    code = err;
+  }
+  if (code !== STEP_UP_REFUSAL_CODE) return null;
+  const next_steps: StepUpNextStep[] = [];
+  const seen = new Set<string>();
+  for (const step of Array.isArray(src.next_steps) ? src.next_steps : []) {
+    if (!step || typeof step !== 'object') continue;
+    const action = (step as Record<string, unknown>).action;
+    if (typeof action !== 'string' || !(STEP_UP_ACTIONS as readonly string[]).includes(action) || seen.has(action)) continue;
+    seen.add(action);
+    next_steps.push(
+      action === 'use_authenticator'
+        ? { action, methods: allowedMethods((step as Record<string, unknown>).methods) }
+        : { action: action as Exclude<StepUpAction, 'use_authenticator'> },
+    );
+  }
+  return { allowed_methods: allowedMethods(src.allowed_methods), next_steps };
+}
+
+function stepUpResponse(refusal: StepUpRefusal, attemptedRefresh: boolean): NextResponse {
+  return NextResponse.json(
+    { success: false, error: STEP_UP_TEXT, code: STEP_UP_REFUSAL_CODE, ...refusal, meta: { attemptedRefresh } },
+    { status: 403 },
+  );
+}
+
+/**
+ * Every string the IDP might have put anywhere in the error envelope, unwrapped from
+ * `{ message = X }` ToString form. Classification input only.
+ */
+export function upstreamErrorTexts(json: unknown): string[] {
+  const out: string[] = [];
+  const add = (v: unknown) => {
+    if (typeof v !== 'string' || !v) return;
+    out.push(v);
+    const m = v.match(/^\{\s*\w+\s*=\s*(.*?)\s*\}$/s);
+    if (m) out.push(m[1]);
+  };
+  const j = json as Record<string, any> | null | undefined;
+  if (!j || typeof j !== 'object') return out;
+  add(j.message);
+  add(j.code);
+  add(j.error);
+  if (j.error && typeof j.error === 'object') {
+    add(j.error.message);
+    add(j.error.code);
+    const d = j.error.details;
+    if (d && typeof d === 'object') { add(d.message); add(d.Message); add(d.code); add(d.errorCode); }
+  }
+  return out;
+}
+
+export function classifyTwoFactorVerifyFailure(status: number, json: unknown): TwoFactorVerifyFailureCode {
+  // PAY-1611: checked FIRST - an exact code on a 403, so no prose rule below can claim it first.
+  if (stepUpRefusal(status, json)) return 'STEP_UP_FACTOR_NOT_ALLOWED';
+  // PAY-902 (BAPert R484): the IdP's lockout CODE, not its prose. Door A is post-authentication, so stating
+  // the lockout discloses nothing; telling a locked-out user "try again" sends them to spend attempts.
+  //
+  // PAY-1574: THIS MUST COME BEFORE THE 429 TEST. PayEz-Core PR 366 answers a TOTP lockout as HTTP 429 carrying
+  // code "locked". With `status === 429` first, that status returned RATE_LIMITED and the lock code the IdP had
+  // just started sending was discarded unread - the tester saw a plain rate limit. A 429 with NO lock code is
+  // still RATE_LIMITED, below.
+  if (upstreamErrorTexts(json).some((t) => IDP_LOCKED.test(t))) return 'LOCKED';
+  if (status === 429) return 'RATE_LIMITED';
+  // PAY-1574: the verify failed closed on OUR side (replay store down). Not a wrong code, whatever the status.
+  if (upstreamErrorTexts(json).some((t) => IDP_UNAVAILABLE.test(t))) return 'VERIFY_UNAVAILABLE';
+  if (upstreamErrorTexts(json).some((t) => WRONG_CODE.test(t))) return 'INVALID_CODE';
+  if (status === 401 || status === 403) return 'SESSION_REJECTED';
+  if (status >= 500 || status === 0) return 'VERIFY_UNAVAILABLE';
+  return 'VERIFY_FAILED';
+}
+
+/**
+ * PAY-1608: the window as words - "15 minutes", "1 minute", "45 seconds", "2 hours". Rounded UP, so the user is never
+ * told a shorter wait than the IDP enforces. Undefined in, undefined out.
+ */
+export function formatLockWindow(seconds: number | undefined): string | undefined {
+  if (typeof seconds !== 'number' || !Number.isFinite(seconds) || seconds <= 0) return undefined;
+  const plural = (n: number, unit: string) => `${n} ${unit}${n === 1 ? '' : 's'}`;
+  if (seconds < 60) return plural(Math.ceil(seconds), 'second');
+  const minutes = Math.ceil(seconds / 60);
+  if (minutes < 120) return plural(minutes, 'minute');
+  return plural(Math.ceil(minutes / 60), 'hour');
+}
+
+/** PAY-1608: the LOCKED sentence with the IDP's real window, or the number-free one when none was sent. */
+export function lockedText(retryAfterSeconds?: number): string {
+  const window = formatLockWindow(retryAfterSeconds);
+  return window
+    ? `Too many incorrect codes. Verification is locked for ${window} - wait before entering another code.`
+    : FIXED_TEXT.LOCKED;
+}
+
+export function twoFactorVerifyFailure(
+  result: { status: number; json: unknown; attemptedRefresh: boolean; retryAfterSeconds?: number },
+  method: TwoFactorVerifyMethod,
+): NextResponse {
+  const refusal = stepUpRefusal(result.status, result.json);
+  if (refusal) return stepUpResponse(refusal, result.attemptedRefresh);
+  const code = classifyTwoFactorVerifyFailure(result.status, result.json);
+  const error = code === 'INVALID_CODE' ? INVALID_CODE_TEXT[method]
+    : code === 'LOCKED' ? lockedText(result.retryAfterSeconds)
+      : FIXED_TEXT[code as keyof typeof FIXED_TEXT];
+  // PAY-1608: a lock or a throttle relays the IDP's window, as a number (for a client that words it itself) and as the
+  // standard header. Never on other failures, and never invented: absent upstream means absent here.
+  const wait = (code === 'LOCKED' || code === 'RATE_LIMITED') && formatLockWindow(result.retryAfterSeconds)
+    ? Math.ceil(result.retryAfterSeconds as number) : undefined;
+  return NextResponse.json(
+    { success: false, error, code, ...(wait ? { retryAfterSeconds: wait } : {}), meta: { attemptedRefresh: result.attemptedRefresh } },
+    { status: result.status, ...(wait ? { headers: { 'Retry-After': String(wait) } } : {}) },
+  );
+}
+
+/**
+ * PAY-1443 residual: account/send-code on the SAME verify-code screen. A send has no
+ * "wrong code" outcome, so it gets its own small classification, but the same rule applies:
+ * upstream text/code never reach the response. The portal renders `data.message || data.error`,
+ * so no `message` field is emitted on failure.
+ */
+export type TwoFactorSendMethod = 'sms' | 'email';
+
+export type TwoFactorSendFailureCode =
+  | 'RATE_LIMITED'
+  | 'SESSION_REJECTED'
+  | 'STEP_UP_FACTOR_NOT_ALLOWED'
+  | 'SEND_UNAVAILABLE'
+  | 'SEND_FAILED';
+
+const SEND_LABEL: Record<TwoFactorSendMethod, string> = { sms: 'text message', email: 'email' };
+
+export function classifyTwoFactorSendFailure(status: number, json?: unknown): TwoFactorSendFailureCode {
+  if (stepUpRefusal(status, json)) return 'STEP_UP_FACTOR_NOT_ALLOWED'; // PAY-1611, before the 401/403 branch
+  if (status === 429) return 'RATE_LIMITED';
+  if (status === 401 || status === 403) return 'SESSION_REJECTED';
+  if (status >= 500 || status === 0) return 'SEND_UNAVAILABLE';
+  return 'SEND_FAILED';
+}
+
+export function twoFactorSendCodeFailure(
+  result: { status: number; attemptedRefresh: boolean; json?: unknown },
+  method: TwoFactorSendMethod,
+): NextResponse {
+  const refusal = stepUpRefusal(result.status, result.json);
+  if (refusal) return stepUpResponse(refusal, result.attemptedRefresh);
+  const code = classifyTwoFactorSendFailure(result.status, result.json);
+  const label = SEND_LABEL[method];
+  const error =
+    code === 'RATE_LIMITED' ? FIXED_TEXT.RATE_LIMITED
+    : code === 'SESSION_REJECTED' ? `We could not send a ${label} code for this session. Please try again.`
+    : code === 'SEND_UNAVAILABLE' ? `We could not send a ${label} code right now. Please try again.`
+    : `We could not send a ${label} code. Please try again.`;
+  return NextResponse.json(
+    { success: false, error, code, meta: { attemptedRefresh: result.attemptedRefresh } },
+    { status: result.status },
+  );
+}

package/src/middleware/create-middleware.ts

@@ -19,7 +19,7 @@
 
 import { NextRequest, NextResponse } from 'next/server';
 import { isUnauthenticatedRoute, should2FABypass } from '../auth/route-config';
-import { resolveCallbackDestination } from '../auth/safe-callback';
+import { resolveCallbackDestination, safeCallbackPath } from '../auth/safe-callback';
 import { getInternalApiUrl } from '../edge/internal-api-url';
 import { getSessionCookieName, getSecureSessionCookieName } from '../lib/app-slug';
 import { checkPagePermission, isRBACEnabled } from './rbac-check';
@@ -290,6 +290,31 @@ function refreshFailureResponse(
   return redirectTo(request, location, clearCookies);
 }
 
+/**
+ * PAY-2147: the terminal answer when the middleware CANNOT TELL whether the session is good
+ * (circuit breaker open, a half-open breaker refusing a refresh attempt, or the viability read failed).
+ *
+ * "I could not check" is not a verdict on the session, so this NEVER touches a cookie: a transient blip
+ * in the IdP / viability path used to wipe the session of every user who made any request while the
+ * breaker was open. Cookies are cleared only on a POSITIVE signal (force_invalidated, stale_session,
+ * pre_2fa_token_expired, refresh 401/403, explicit sign-out) - never from here.
+ *
+ *  - /api/*  -> 503 JSON a caller can branch on (a redirect would be followed by fetch() into a 200 HTML page).
+ *  - pages   -> /service-unavailable (public + allowDuringCircuitBreakerOpen, so it cannot loop), carrying the
+ *               requested path as `callbackUrl` so "Try again" returns the user to it still signed in. The path goes
+ *               through safeCallbackPath (URL-parser origin check): an off-origin or auth-surface value is dropped.
+ */
+function serviceUnavailableResponse(request: NextRequest): NextResponse {
+  const { pathname, search } = request.nextUrl;
+  if (pathname.startsWith('/api/')) {
+    return NextResponse.json({ error: 'ServiceUnavailable' }, { status: 503 });
+  }
+  const target = new URL('/service-unavailable', request.url);
+  const callback = safeCallbackPath(pathname + search);
+  if (callback !== '/') target.searchParams.set('callbackUrl', callback);
+  return NextResponse.redirect(target);
+}
+
 // =============================================================================
 // AUTH DECISION ENGINE
 // =============================================================================
@@ -334,14 +359,11 @@ function makeAuthDecision(ctx: AuthContext): AuthAction {
   }
 
   // --- Circuit breaker open: Service degraded ---
+  // PAY-2147: the breaker opening says the IdP/viability path is unreachable, NOT that the session is bad.
+  // Answer "service unavailable" (503 for /api, /service-unavailable for pages) and leave every cookie alone.
   if (circuitBreakerOpen) {
     if (onLoginPage) return { type: 'allow' };
-    return {
-      type: 'redirect',
-      location: `${LOGIN_PAGE}?error=ServiceUnavailable`,
-      reason: 'circuit_breaker_open',
-      clearCookies: true
-    };
+    return { type: 'service_error', reason: 'circuit_breaker_open' };
   }
 
   // --- No session cookie: Need to login ---
@@ -363,6 +385,7 @@ function makeAuthDecision(ctx: AuthContext): AuthAction {
 
   // --- Service error: Can't verify session ---
   if (sessionStatus.exists === null || sessionStatus.forceInvalid === null) {
+    if (onLoginPage) return { type: 'allow' }; // the login page must stay reachable while the check is down
     return { type: 'service_error', reason: 'viability_check_failed' };
   }
 
@@ -622,6 +645,18 @@ export function decideForceInvalid(
   return data.forceInvalid === true || data.revoked === true;
 }
 
+/**
+ * PAY-2147: does the request carry a session cookie? Used ONLY when the viability read itself FAILED.
+ * Before this, a failed read left sessionPointer.exists=false, so the decision engine took its `no_session` arm
+ * (pages -> the LOGIN page, /api -> straight through) and its `exists === null` -> service_error arm below it was
+ * unreachable dead code: a user holding a perfectly good session was told to sign in during an outage. With a
+ * cookie present and the check down we do not know the session is bad, so the engine must say "service
+ * unavailable", not "sign in". No cookie -> unchanged (no_session).
+ */
+function hasSessionCookie(request: NextRequest): boolean {
+  return !!(request.cookies.get(getSessionCookieName())?.value || request.cookies.get(getSecureSessionCookieName())?.value);
+}
+
 /** Check session viability via internal API */
 async function checkViability(
   request: NextRequest,
@@ -716,11 +751,13 @@ async function checkViability(
       log.error('Viability check failed', { status: response.status });
       sessionStatus.exists = null;
       sessionStatus.forceInvalid = null;
+      sessionPointer.exists = hasSessionCookie(request); // PAY-2147: see hasSessionCookie
     }
   } catch (error) {
     log.error('Viability check error', { error: error instanceof Error ? error.message : String(error) });
     sessionStatus.exists = null;
     sessionStatus.forceInvalid = null;
+    sessionPointer.exists = hasSessionCookie(request); // PAY-2147: see hasSessionCookie
   }
 
   return { sessionStatus, sessionPointer };
@@ -755,7 +792,7 @@ async function executeDecision(
       return redirectTo(request, decision.location, decision.clearCookies);
 
     case 'service_error':
-      return NextResponse.redirect(new URL('/service-unavailable', request.url));
+      return serviceUnavailableResponse(request);
 
     case 'refresh_needed':
       // PAY-2136: a speculative request must not spend (rotate) a single-use refresh token or, on a 401/403,
@@ -843,12 +880,9 @@ async function handleRefresh(
   // Check if circuit breaker allows refresh attempt
   if (!cb.canAttemptRefresh()) {
     log.warn('Circuit breaker preventing refresh attempt');
-    return refreshFailureResponse(
-      request,
-      `${LOGIN_PAGE}?callbackUrl=${encodeURIComponent(safeCallback)}&error=ServiceUnavailable`,
-      'ServiceUnavailable',
-      true
-    );
+    // 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);
   }
 
   try {