@payez/next-mvp 4.4.5 → 4.4.7

package/dist/lib/token-log-id.js

@@ -0,0 +1,84 @@
+"use strict";
+/**
+ * tokenLogId - a log-safe correlation id for a session token (PR 154 follow-up, BAPert ruling on PAY-1427:
+ * "no token material in logs, not even partial").
+ *
+ * The package used to log `sessionToken.substring(0, 8) + '...'` so lines about one session could be
+ * correlated. Those 8 characters ARE token material. This returns `h:` + the first 12 hex characters of
+ * SHA-256(token) instead: the same correlation (one token -> one stable id, across every log line and
+ * process), with nothing of the token itself.
+ *
+ * Synchronous and dependency-free on purpose: the call sites include Edge middleware
+ * (create-middleware, auth-decision) and browser code (authStore, SessionSync), where node:crypto is
+ * unavailable and Web Crypto's digest is async. SHA-256 below follows FIPS 180-4 and is verified
+ * against node:crypto in test/session-token-log-id.test.cjs.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sha256Hex = sha256Hex;
+exports.tokenLogId = tokenLogId;
+const K = new Uint32Array([
+    0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5,
+    0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3, 0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174,
+    0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da,
+    0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7, 0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967,
+    0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13, 0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85,
+    0xa2bfe8a1, 0xa81a664b, 0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070,
+    0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f, 0x682e6ff3,
+    0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208, 0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2,
+]);
+const rotr = (x, n) => (x >>> n) | (x << (32 - n));
+/** SHA-256 of the UTF-8 encoding of `input`, as lowercase hex. */
+function sha256Hex(input) {
+    const msg = new TextEncoder().encode(input);
+    const bitLen = msg.length * 8;
+    const padded = new Uint8Array(((msg.length + 9 + 63) >> 6) << 6);
+    padded.set(msg);
+    padded[msg.length] = 0x80;
+    const view = new DataView(padded.buffer);
+    view.setUint32(padded.length - 8, Math.floor(bitLen / 0x100000000));
+    view.setUint32(padded.length - 4, bitLen >>> 0);
+    const h = new Uint32Array([0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a, 0x510e527f, 0x9b05688c, 0x1f83d9ab, 0x5be0cd19]);
+    const w = new Uint32Array(64);
+    for (let off = 0; off < padded.length; off += 64) {
+        for (let i = 0; i < 16; i++)
+            w[i] = view.getUint32(off + i * 4);
+        for (let i = 16; i < 64; i++) {
+            const s15 = w[i - 15];
+            const s2 = w[i - 2];
+            const sigma0 = rotr(s15, 7) ^ rotr(s15, 18) ^ (s15 >>> 3);
+            const sigma1 = rotr(s2, 17) ^ rotr(s2, 19) ^ (s2 >>> 10);
+            w[i] = (w[i - 16] + sigma0 + w[i - 7] + sigma1) | 0;
+        }
+        let a = h[0], b = h[1], c = h[2], d = h[3], e = h[4], f = h[5], g = h[6], hh = h[7];
+        for (let i = 0; i < 64; i++) {
+            const t1 = (hh + (rotr(e, 6) ^ rotr(e, 11) ^ rotr(e, 25)) + ((e & f) ^ (~e & g)) + K[i] + w[i]) | 0;
+            const t2 = ((rotr(a, 2) ^ rotr(a, 13) ^ rotr(a, 22)) + ((a & b) ^ (a & c) ^ (b & c))) | 0;
+            hh = g;
+            g = f;
+            f = e;
+            e = (d + t1) | 0;
+            d = c;
+            c = b;
+            b = a;
+            a = (t1 + t2) | 0;
+        }
+        h[0] = (h[0] + a) | 0;
+        h[1] = (h[1] + b) | 0;
+        h[2] = (h[2] + c) | 0;
+        h[3] = (h[3] + d) | 0;
+        h[4] = (h[4] + e) | 0;
+        h[5] = (h[5] + f) | 0;
+        h[6] = (h[6] + g) | 0;
+        h[7] = (h[7] + hh) | 0;
+    }
+    let out = '';
+    for (let i = 0; i < 8; i++)
+        out += (h[i] >>> 0).toString(16).padStart(8, '0');
+    return out;
+}
+/** `h:` + 12 hex of SHA-256(token); `none` when there is no token. Never any part of the token itself. */
+function tokenLogId(token) {
+    if (typeof token !== 'string' || token.length === 0)
+        return 'none';
+    return 'h:' + sha256Hex(token).slice(0, 12);
+}

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

@@ -0,0 +1,78 @@
+/**
+ * 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';
+/**
+ * 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 declare const STEP_UP_REFUSAL_CODE = "STEP_UP_FACTOR_NOT_ALLOWED";
+declare const STEP_UP_METHODS: readonly ["totp", "webauthn", "backup_code"];
+declare const STEP_UP_ACTIONS: readonly ["use_authenticator", "reset_password", "enroll_authenticator"];
+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[];
+};
+/** The step-up refusal's allowlisted lists, or null when this is not that refusal (status 403 + the exact code only). */
+export declare function stepUpRefusal(status: number, json: unknown): StepUpRefusal | null;
+/**
+ * Every string the IDP might have put anywhere in the error envelope, unwrapped from
+ * `{ message = X }` ToString form. Classification input only.
+ */
+export declare function upstreamErrorTexts(json: unknown): string[];
+export declare function classifyTwoFactorVerifyFailure(status: number, json: unknown): TwoFactorVerifyFailureCode;
+export declare function twoFactorVerifyFailure(result: {
+    status: number;
+    json: unknown;
+    attemptedRefresh: boolean;
+}, method: TwoFactorVerifyMethod): NextResponse;
+/**
+ * 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';
+export declare function classifyTwoFactorSendFailure(status: number, json?: unknown): TwoFactorSendFailureCode;
+export declare function twoFactorSendCodeFailure(result: {
+    status: number;
+    attemptedRefresh: boolean;
+    json?: unknown;
+}, method: TwoFactorSendMethod): NextResponse;
+export {};

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

@@ -0,0 +1,220 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.STEP_UP_REFUSAL_CODE = void 0;
+exports.stepUpRefusal = stepUpRefusal;
+exports.upstreamErrorTexts = upstreamErrorTexts;
+exports.classifyTwoFactorVerifyFailure = classifyTwoFactorVerifyFailure;
+exports.twoFactorVerifyFailure = twoFactorVerifyFailure;
+exports.classifyTwoFactorSendFailure = classifyTwoFactorSendFailure;
+exports.twoFactorSendCodeFailure = twoFactorSendCodeFailure;
+/**
+ * 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.
+ */
+const server_1 = require("next/server");
+const INVALID_CODE_TEXT = {
+    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 = {
+    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.
+ */
+exports.STEP_UP_REFUSAL_CODE = 'STEP_UP_FACTOR_NOT_ALLOWED';
+const STEP_UP_METHODS = ['totp', 'webauthn', 'backup_code'];
+const STEP_UP_ACTIONS = ['use_authenticator', 'reset_password', 'enroll_authenticator'];
+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) {
+    if (!Array.isArray(v))
+        return [];
+    const out = [];
+    for (const m of v) {
+        if (STEP_UP_METHODS.includes(m) && !out.includes(m))
+            out.push(m);
+    }
+    return out;
+}
+/** The step-up refusal's allowlisted lists, or null when this is not that refusal (status 403 + the exact code only). */
+function stepUpRefusal(status, json) {
+    if (status !== 403 || !json || typeof json !== 'object')
+        return null;
+    const j = json;
+    const err = j.error;
+    let code;
+    let src = j;
+    if (err && typeof err === 'object') {
+        const e = err;
+        code = e.code;
+        src = e.details && typeof e.details === 'object' ? e.details : {};
+    }
+    else {
+        code = err;
+    }
+    if (code !== exports.STEP_UP_REFUSAL_CODE)
+        return null;
+    const next_steps = [];
+    const seen = new Set();
+    for (const step of Array.isArray(src.next_steps) ? src.next_steps : []) {
+        if (!step || typeof step !== 'object')
+            continue;
+        const action = step.action;
+        if (typeof action !== 'string' || !STEP_UP_ACTIONS.includes(action) || seen.has(action))
+            continue;
+        seen.add(action);
+        next_steps.push(action === 'use_authenticator'
+            ? { action, methods: allowedMethods(step.methods) }
+            : { action: action });
+    }
+    return { allowed_methods: allowedMethods(src.allowed_methods), next_steps };
+}
+function stepUpResponse(refusal, attemptedRefresh) {
+    return server_1.NextResponse.json({ success: false, error: STEP_UP_TEXT, code: exports.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.
+ */
+function upstreamErrorTexts(json) {
+    const out = [];
+    const add = (v) => {
+        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;
+    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;
+}
+function classifyTwoFactorVerifyFailure(status, json) {
+    // 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';
+}
+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 SEND_LABEL = { sms: 'text message', email: 'email' };
+function classifyTwoFactorSendFailure(status, json) {
+    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';
+}
+function twoFactorSendCodeFailure(result, method) {
+    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 server_1.NextResponse.json({ success: false, error, code, meta: { attemptedRefresh: result.attemptedRefresh } }, { status: result.status });
+}

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

@@ -28,7 +28,8 @@ export interface AuthContext {
 }
 export interface SessionPointer {
     exists: boolean;
-    sessionToken?: string;
+    /** PAY-1481: tokenLogId of the session token (presence + log correlation), never the token itself. */
+    sessionTokenId?: string | null;
     expired?: boolean;
     hasRefreshToken?: boolean;
     roles: string[];
@@ -99,4 +100,6 @@ export interface MvpMiddlewareOptions {
     /** Paths exempt from RBAC checks (auth still enforced, just no page-permission check) */
     rbacExemptPaths?: string[];
 }
+/** Login error code for a pre-2FA session that expired before the code was verified (PAY-884). */
+export declare const TWO_FACTOR_TIMEOUT_ERROR = "TwoFactorTimeout";
 export declare function createMvpMiddleware(options?: MvpMiddlewareOptions): (request: NextRequest) => Promise<NextResponse>;

package/dist/middleware/create-middleware.js

@@ -18,6 +18,7 @@
  *   });
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.TWO_FACTOR_TIMEOUT_ERROR = void 0;
 exports.createMvpMiddleware = createMvpMiddleware;
 const server_1 = require("next/server");
 const route_config_1 = require("../auth/route-config");
@@ -105,6 +106,34 @@ function redirectTo(request, location, clearCookies = false) {
     }
     return response;
 }
+/**
+ * Terminal response for a FAILED token refresh.
+ *
+ * For `/api/` requests a redirect is the wrong terminator: fetch() follows the 307,
+ * receives 200 + an HTML login page, and the caller parses garbage instead of
+ * branching on an error. Those callers get a 401 JSON body they can branch on;
+ * document requests keep the existing redirect exactly as before.
+ *
+ * Cookie-clearing is preserved on BOTH arms. That is load-bearing, not incidental:
+ * on a permanent failure (401/403) stale cookies must be cleared or the next request
+ * refreshes again and loops (see the CRITICAL note in handleRefresh). A JSON arm that
+ * skipped clearing would convert a redirect loop into a silent refresh loop.
+ *
+ * Scoped deliberately to handleRefresh's failure exits. It is NOT folded into
+ * redirectTo(), and NOT hoisted above the refresh decision: an `/api/` hatch placed
+ * higher would intercept 'refresh_needed' and disable middleware token refresh across
+ * the whole API surface (card 340024 C1).
+ */
+function refreshFailureResponse(request, location, errorCode, clearCookies = false) {
+    if (request.nextUrl.pathname.startsWith('/api/')) {
+        const response = server_1.NextResponse.json({ error: errorCode }, { status: 401 });
+        if (clearCookies) {
+            clearSessionCookies(response, request);
+        }
+        return response;
+    }
+    return redirectTo(request, location, clearCookies);
+}
 // =============================================================================
 // AUTH DECISION ENGINE
 // =============================================================================
@@ -115,6 +144,26 @@ function redirectTo(request, location, clearCookies = false) {
 function makeAuthDecision(ctx) {
     const { pathname, isPublicRoute, isLoginPage: onLoginPage, searchParams, sessionPointer, sessionStatus, circuitBreakerOpen } = ctx;
     const safeCallback = getSafeCallbackUrl(pathname);
+    // --- PAY-884: a provisional (pre-2FA) session whose token has expired can never finish 2FA ---
+    // The IdP issues no refresh token until 2FA completes, and it validates token lifetime, so
+    // once the provisional access token expires neither refresh nor code verification can
+    // succeed. Sending the user to the verify-code page (or to error=SessionExpired, which the
+    // login page deliberately shows as NO message) strands them mid-2FA with no explanation.
+    // Say what happened instead, and clear the dead session so the next sign-in starts clean.
+    // Scoped to the verify-code page and protected pages: /api/ keeps its 401-JSON carve-out
+    // (307290), the login page stays reachable, and public pages are left to the existing arms.
+    if (isExpiredProvisionalSession(sessionPointer, sessionStatus) &&
+        !pathname.startsWith('/api/') &&
+        !onLoginPage &&
+        (pathname === VERIFY_CODE_PAGE || !isPublicRoute)) {
+        const callback = pathname === VERIFY_CODE_PAGE ? getSafeCallbackUrl(pathname, searchParams) : safeCallback;
+        return {
+            type: 'redirect',
+            location: `${LOGIN_PAGE}?callbackUrl=${encodeURIComponent(callback)}&error=${exports.TWO_FACTOR_TIMEOUT_ERROR}`,
+            reason: 'pre_2fa_token_expired',
+            clearCookies: true,
+        };
+    }
     // --- Public routes: Allow, but enforce 2FA for authenticated users ---
     if (isPublicRoute && !onLoginPage) {
         if (needsTwoFactorRedirect(pathname, sessionPointer, sessionStatus)) {
@@ -221,6 +270,21 @@ function makeAuthDecision(ctx) {
     // --- All checks passed ---
     return { type: 'allow' };
 }
+/** Login error code for a pre-2FA session that expired before the code was verified (PAY-884). */
+exports.TWO_FACTOR_TIMEOUT_ERROR = 'TwoFactorTimeout';
+/**
+ * PAY-884: 2FA outstanding, access token expired, and no refresh token to renew it.
+ * Only a viability answer that positively says the session exists qualifies (null = check failed).
+ */
+function isExpiredProvisionalSession(session, status) {
+    return (session.exists &&
+        status.exists === true &&
+        status.forceInvalid === false &&
+        status.requires2FA &&
+        !status.twoFactorComplete &&
+        session.expired === true &&
+        !session.hasRefreshToken);
+}
 /** Check if user needs 2FA redirect */
 function needsTwoFactorRedirect(pathname, session, status) {
     if (!session.exists || !status.exists)
@@ -311,9 +375,16 @@ function createMvpMiddleware(options = {}) {
         // The warning is deliberately KEPT: it is the only operational signal that
         // stale sessions are occurring, and it costs nothing to log before
         // delegating. Do not re-introduce a `return` in this block.
-        if (!isPublic && sessionStatus.exists === false && sessionPointer.sessionToken) {
+        if (!isPublic && sessionStatus.exists === false && sessionPointer.sessionTokenId) {
+            // PAY-1505: the KEY is `sessionTokenId`, not `sessionToken`. The value has
+            // always been a tokenLogId fingerprint (viability.ts builds it as
+            // `tokenLogId(sessionToken)`), but labelling it `sessionToken` told any
+            // operator reading this log that the line carried the token itself. The
+            // credential-in-logs source guard reads the key for exactly that reason:
+            // a field named `sessionToken` must hold a safe value, and proving that
+            // across an API boundary is not possible from the name alone.
             log.warn('Stale session detected (delegating to decision engine)', {
-                sessionToken: sessionPointer.sessionToken?.substring(0, 8) + '...',
+                sessionTokenId: sessionPointer.sessionTokenId,
                 pathname
             });
         }
@@ -348,7 +419,7 @@ async function checkViability(request, endpoint, log) {
     };
     const sessionPointer = {
         exists: false,
-        sessionToken: undefined,
+        sessionTokenId: undefined,
         expired: false,
         hasRefreshToken: false,
         roles: [],
@@ -369,11 +440,11 @@ async function checkViability(request, endpoint, log) {
         if (response.ok) {
             const data = await response.json();
             // Support both response formats (viability and refresh-viability)
-            sessionStatus.exists = data.authenticated ?? (data.sessionToken && data.reason !== 'session_not_found');
+            sessionStatus.exists = data.authenticated ?? (!!data.sessionTokenId && data.reason !== 'session_not_found');
             sessionStatus.requires2FA = data.requires2FA || false;
             sessionStatus.twoFactorComplete = data.twoFactorComplete || false;
             sessionPointer.exists = sessionStatus.exists ?? false;
-            sessionPointer.sessionToken = data.sessionToken;
+            sessionPointer.sessionTokenId = data.sessionTokenId ?? null;
             sessionPointer.expired = data.accessTokenExpired || false;
             sessionPointer.hasRefreshToken = data.hasRefreshToken ?? data.canRefresh ?? false;
             sessionPointer.roles = data.roles || [];
@@ -457,7 +528,7 @@ async function handleRefresh(request, safeCallback, opts) {
     // Check if circuit breaker allows refresh attempt
     if (!cb.canAttemptRefresh()) {
         log.warn('Circuit breaker preventing refresh attempt');
-        return redirectTo(request, `${LOGIN_PAGE}?callbackUrl=${encodeURIComponent(safeCallback)}&error=ServiceUnavailable`, true);
+        return refreshFailureResponse(request, `${LOGIN_PAGE}?callbackUrl=${encodeURIComponent(safeCallback)}&error=ServiceUnavailable`, 'ServiceUnavailable', true);
     }
     try {
         const baseUrl = (0, internal_api_url_1.getInternalApiUrl)(request);
@@ -494,7 +565,7 @@ async function handleRefresh(request, safeCallback, opts) {
             clearingCookies: isPermanentFailure
         });
         onRefreshFailure?.(response.status, false);
-        return redirectTo(request, `${LOGIN_PAGE}?callbackUrl=${encodeURIComponent(safeCallback)}&error=${errorParam}`, isPermanentFailure);
+        return refreshFailureResponse(request, `${LOGIN_PAGE}?callbackUrl=${encodeURIComponent(safeCallback)}&error=${errorParam}`, errorParam, isPermanentFailure);
     }
     catch (error) {
         const isNetwork = cb.isNetworkError(error);
@@ -508,6 +579,6 @@ async function handleRefresh(request, safeCallback, opts) {
         }
         onRefreshFailure?.(0, isNetwork);
         // Network error - don't clear cookies, might be transient
-        return redirectTo(request, `${LOGIN_PAGE}?callbackUrl=${encodeURIComponent(safeCallback)}&error=RefreshError`, false);
+        return refreshFailureResponse(request, `${LOGIN_PAGE}?callbackUrl=${encodeURIComponent(safeCallback)}&error=RefreshError`, 'RefreshError', false);
     }
 }

package/dist/pages/login/page.js

@@ -131,6 +131,11 @@ function LoginForm({ altAuthSlot }) {
                 console.log('[LOGIN] SessionExpired detected - normal behavior');
                 friendlyError = null;
             }
+            else if (urlError === 'TwoFactorTimeout') {
+                // PAY-884: the sign-in expired while the verification code was outstanding. Unlike
+                // SessionExpired this is NOT silent - the user was mid-2FA and must know why they are here.
+                friendlyError = 'Your verification step timed out before the code was confirmed. Please sign in again.';
+            }
             else if (urlError === 'ServiceUnavailable') {
                 friendlyError = 'Authentication service is temporarily unavailable. Please try again in a few minutes.';
             }

package/dist/pages/recovery/page.js

@@ -11,6 +11,7 @@ const SelectMethodStep_1 = require("../../components/recovery/SelectMethodStep")
 const VerifyCodeStep_1 = require("../../components/recovery/VerifyCodeStep");
 const SetPasswordStep_1 = require("../../components/recovery/SetPasswordStep");
 const CompleteStep_1 = require("../../components/recovery/CompleteStep");
+const RequestedStep_1 = require("../../components/recovery/RequestedStep");
 const useTheme_1 = require("../../theme/useTheme");
 function RecoveryContent() {
     const router = (0, navigation_1.useRouter)();
@@ -24,13 +25,18 @@ function RecoveryContent() {
     const [verificationCode, setVerificationCode] = (0, react_1.useState)('');
     const [passwordResetToken, setPasswordResetToken] = (0, react_1.useState)(null);
     const [error, setError] = (0, react_1.useState)(null);
+    // PAY-1591: true when the reset failed because the recovery itself is dead; the error box then offers a way back.
+    const [recoveryExpired, setRecoveryExpired] = (0, react_1.useState)(false);
     const [loading, setLoading] = (0, react_1.useState)(false);
+    // PAY-1588: true only after the IdP accepted the new password. The 'complete' step is ALSO reached from initiate()
+    // when no recovery session comes back, and that path must not tell the user a password was set.
+    const [resetSucceeded, setResetSucceeded] = (0, react_1.useState)(false);
     const handleInitiateRecovery = async () => {
         setLoading(true);
         setError(null);
         try {
             const response = await api_1.accountApi.initiateRecovery(email);
-            if (response.success && response.data.recovery_session_token) {
+            if (response.success && response.data?.recovery_session_token) {
                 setRecoverySession({
                     recoveryToken: response.data.recovery_session_token,
                     email: email,
@@ -43,7 +49,8 @@ function RecoveryContent() {
                 setCurrentStep('select-method');
             }
             else {
-                setCurrentStep('complete');
+                // No recovery session (unknown / locked / throttled): the ONE neutral step, never CompleteStep (rigpert 60711).
+                setCurrentStep('requested');
             }
         }
         catch (err) {
@@ -105,9 +112,11 @@ function RecoveryContent() {
             return;
         setLoading(true);
         setError(null);
+        setRecoveryExpired(false);
         try {
             const response = await api_1.accountApi.resetPasswordWithToken(recoverySession.email, passwordResetToken.token, password, confirmPassword);
             if (response.success) {
+                setResetSucceeded(true);
                 setCurrentStep('complete');
             }
             else {
@@ -116,6 +125,7 @@ function RecoveryContent() {
         }
         catch (err) {
             setError(err instanceof Error ? err.message : 'Failed to reset password.');
+            setRecoveryExpired(!!err && err.code === 'RECOVERY_EXPIRED');
         }
         finally {
             setLoading(false);
@@ -129,9 +139,9 @@ function RecoveryContent() {
         else if (currentStep === 'set-password')
             setCurrentStep('verify-code');
     };
-    return ((0, jsx_runtime_1.jsx)("div", { className: "w-full flex items-center justify-center p-6", style: { background: 'var(--bg-default)' }, children: (0, jsx_runtime_1.jsxs)("div", { className: "max-w-md w-full", children: [error && ((0, jsx_runtime_1.jsx)("div", { className: "mb-4 bg-red-50 border border-red-200 rounded-2xl p-3", children: (0, jsx_runtime_1.jsx)("p", { className: "text-red-700 text-sm", children: error }) })), loading && ((0, jsx_runtime_1.jsx)("div", { className: "mb-4 rounded-2xl p-3", style: { background: 'var(--bg-card)', borderColor: 'var(--border-default)' }, children: (0, jsx_runtime_1.jsx)("p", { className: "text-sm", style: { color: 'var(--text-secondary)' }, children: "Processing..." }) })), currentStep === 'initiate' && ((0, jsx_runtime_1.jsx)(InitiateRecoveryStep_1.InitiateRecoveryStep, { email: email, setEmail: setEmail, onSubmit: handleInitiateRecovery, loading: loading })), currentStep === 'select-method' && recoverySession && ((0, jsx_runtime_1.jsx)(SelectMethodStep_1.SelectMethodStep, { session: recoverySession, onSelectMethod: handleSendCode, loading: loading })), currentStep === 'verify-code' && ((0, jsx_runtime_1.jsx)(VerifyCodeStep_1.VerifyCodeStep, { code: verificationCode, setCode: setVerificationCode, onSubmit: handleVerifyCode, onResend: () => selectedMethod && handleSendCode(selectedMethod), loading: loading, maskedDestination: selectedMethod === 'sms'
+    return ((0, jsx_runtime_1.jsx)("div", { className: "w-full flex items-center justify-center p-6", style: { background: 'var(--bg-default)' }, children: (0, jsx_runtime_1.jsxs)("div", { className: "max-w-md w-full", children: [error && ((0, jsx_runtime_1.jsxs)("div", { className: "mb-4 bg-red-50 border border-red-200 rounded-2xl p-3", children: [(0, jsx_runtime_1.jsx)("p", { className: "text-red-700 text-sm", children: error }), recoveryExpired && ((0, jsx_runtime_1.jsx)("a", { href: "/account-auth/recovery", className: "text-sm font-medium underline", children: "Start password recovery again" }))] })), loading && ((0, jsx_runtime_1.jsx)("div", { className: "mb-4 rounded-2xl p-3", style: { background: 'var(--bg-card)', borderColor: 'var(--border-default)' }, children: (0, jsx_runtime_1.jsx)("p", { className: "text-sm", style: { color: 'var(--text-secondary)' }, children: "Processing..." }) })), currentStep === 'initiate' && ((0, jsx_runtime_1.jsx)(InitiateRecoveryStep_1.InitiateRecoveryStep, { email: email, setEmail: setEmail, onSubmit: handleInitiateRecovery, loading: loading })), currentStep === 'select-method' && recoverySession && ((0, jsx_runtime_1.jsx)(SelectMethodStep_1.SelectMethodStep, { session: recoverySession, onSelectMethod: handleSendCode, loading: loading })), currentStep === 'verify-code' && ((0, jsx_runtime_1.jsx)(VerifyCodeStep_1.VerifyCodeStep, { code: verificationCode, setCode: setVerificationCode, onSubmit: handleVerifyCode, onResend: () => selectedMethod && handleSendCode(selectedMethod), loading: loading, maskedDestination: selectedMethod === 'sms'
                         ? recoverySession?.maskedPhone
-                        : recoverySession?.maskedEmail })), currentStep === 'set-password' && ((0, jsx_runtime_1.jsx)(SetPasswordStep_1.SetPasswordStep, { onSubmit: handleResetPassword, loading: loading })), currentStep === 'complete' && ((0, jsx_runtime_1.jsx)(CompleteStep_1.CompleteStep, { onGoToLogin: () => router.push('/account-auth/login') })), currentStep !== 'complete' && currentStep !== 'initiate' && !loading && ((0, jsx_runtime_1.jsx)("div", { className: "mt-6 text-center", children: (0, jsx_runtime_1.jsx)("button", { type: "button", onClick: handleGoBack, className: "text-sm hover:underline font-medium", style: { color: 'var(--text-primary)' }, children: "\u2190 Go Back" }) }))] }) }));
+                        : recoverySession?.maskedEmail })), currentStep === 'set-password' && ((0, jsx_runtime_1.jsx)(SetPasswordStep_1.SetPasswordStep, { onSubmit: handleResetPassword, loading: loading })), currentStep === 'requested' && (0, jsx_runtime_1.jsx)(RequestedStep_1.RequestedStep, { onGoToLogin: () => router.push('/account-auth/login') }), currentStep === 'complete' && ((0, jsx_runtime_1.jsx)(CompleteStep_1.CompleteStep, { onGoToLogin: () => router.push(resetSucceeded ? '/account-auth/login?notice=password-set' : '/account-auth/login') })), currentStep !== 'complete' && currentStep !== 'requested' && currentStep !== 'initiate' && !loading && ((0, jsx_runtime_1.jsx)("div", { className: "mt-6 text-center", children: (0, jsx_runtime_1.jsx)("button", { type: "button", onClick: handleGoBack, className: "text-sm hover:underline font-medium", style: { color: 'var(--text-primary)' }, children: "\u2190 Go Back" }) }))] }) }));
 }
 function LoadingFallback() {
     const colors = (0, useTheme_1.useColors)();