@payez/next-mvp 4.4.5 → 4.4.6

package/dist/lib/startup-init.js

@@ -46,12 +46,14 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ensureInitialized = ensureInitialized;
 exports.logStartupStatus = logStartupStatus;
+exports.getSlugMismatchReason = getSlugMismatchReason;
 exports.getStartupIDPConfig = getStartupIDPConfig;
 exports.isInitializationFailed = isInitializationFailed;
 exports.getInitializationError = getInitializationError;
 exports.isAppReady = isAppReady;
 require("server-only");
 const idp_client_config_1 = require("./idp-client-config");
+const app_slug_1 = require("./app-slug");
 let initializationStarted = false;
 let initializationComplete = false;
 let initializationFailed = false;
@@ -90,9 +92,22 @@ async function ensureInitialized() {
     lastStartupAttemptTime = now;
     // Mark as started
     initializationStarted = true;
-    // Start initialization
-    initializationPromise = performInitialization();
-    await initializationPromise;
+    // Start initialization.
+    //
+    // PAY-642: a FAILED attempt must not stay installed. This used to be
+    // `initializationPromise = performInitialization(); await initializationPromise;` with no reset, and the
+    // in-progress check above runs BEFORE the backoff check, so a pod that booted while the IdP was down replayed
+    // its first rejection to every caller forever: the 30 s backoff could never lead to a retry. Same latch, same
+    // fix, as createSingleFlight (lib/single-flight.ts): callers of the failing attempt still see the rejection
+    // (loud), then the attempt clears itself, identity-guarded so a slow failure never evicts a newer attempt.
+    // After a failure the backoff check above governs when the next attempt may start.
+    const attempt = performInitialization();
+    initializationPromise = attempt;
+    attempt.catch(() => {
+        if (initializationPromise === attempt)
+            initializationPromise = null;
+    });
+    await attempt;
 }
 /**
  * Synchronously log startup status
@@ -190,8 +205,11 @@ async function performInitialization() {
         // Step 3: Validate cookie name consistency
         // This catches bugs where getJwtCookieName() returns a different name than
         // what auth-options.ts configures, which causes sessions to fail in production
-        const { validateCookieNameConsistency, getSessionCookieName } = await Promise.resolve().then(() => __importStar(require('./app-slug')));
+        const { validateCookieNameConsistency, getSessionCookieName, assertAppSlugMatchesIdp, assertIdpSlugKnown } = await Promise.resolve().then(() => __importStar(require('./app-slug')));
         validateCookieNameConsistency();
+        // rigpert 60743: refuse to run with two cookie-name sources (IdP clientSlug vs APP_SLUG/CLIENT_ID).
+        assertIdpSlugKnown(cachedIDPConfig?.clientSlug);
+        assertAppSlugMatchesIdp(cachedIDPConfig?.clientSlug);
         console.log('[STARTUP] Cookie name consistency validated:', getSessionCookieName());
         // All done
         console.log('');
@@ -241,6 +259,14 @@ ${connectionLine}║   Possible causes:
  * Get the cached IDP config after initialization.
  * Returns null if not yet initialized.
  */
+/**
+ * For health endpoints (rigpert 60765): a guard that does not stop the process is an empty red unless the mismatch is visible
+ * where operators and promote-fe look. Returns `SLUG_MISMATCH: cookie=<idp slug> gate=<app slug>` while the drift holds, else null;
+ * a health route should answer non-200 with this as the reason. Null until the IdP config has been fetched.
+ */
+function getSlugMismatchReason() {
+    return (0, app_slug_1.slugStateReason)(cachedIDPConfig?.clientSlug, initializationComplete || initializationFailed);
+}
 function getStartupIDPConfig() {
     return cachedIDPConfig;
 }

package/dist/lib/token-lifecycle.js

@@ -27,6 +27,7 @@ const session_store_1 = require("./session-store");
 const auth_1 = require("../server/auth");
 const redis_1 = require("./redis");
 const app_slug_1 = require("./app-slug");
+const token_log_id_1 = require("./token-log-id");
 // 5 minute threshold for "needs refresh" - matches refresh handler pattern
 const REFRESH_THRESHOLD_MS = 5 * 60 * 1000;
 // Concurrent refresh handling configuration
@@ -360,7 +361,7 @@ async function ensureFreshToken(request) {
             }
         }
         console.log('[TOKEN_LIFECYCLE] ensureFreshToken check:', {
-            sessionToken: sessionToken.substring(0, 8) + '...',
+            sessionToken: (0, token_log_id_1.tokenLogId)(sessionToken),
             accessTokenExpires: tokenExpiresStr,
             now: new Date().toISOString(),
             needsRefresh: needsRefreshNow,

package/dist/lib/token-log-id.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 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.
+ */
+/** SHA-256 of the UTF-8 encoding of `input`, as lowercase hex. */
+export declare function sha256Hex(input: string): string;
+/** `h:` + 12 hex of SHA-256(token); `none` when there is no token. Never any part of the token itself. */
+export declare function tokenLogId(token: string | null | undefined): string;

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,45 @@
+/**
+ * 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' | 'VERIFY_UNAVAILABLE' | 'VERIFY_FAILED';
+/**
+ * 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' | 'SEND_UNAVAILABLE' | 'SEND_FAILED';
+export declare function classifyTwoFactorSendFailure(status: number): TwoFactorSendFailureCode;
+export declare function twoFactorSendCodeFailure(result: {
+    status: number;
+    attemptedRefresh: boolean;
+}, method: TwoFactorSendMethod): NextResponse;

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

@@ -0,0 +1,143 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+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;
+/**
+ * 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-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 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) {
+    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 code = classifyTwoFactorSendFailure(result.status);
+    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[];

package/dist/middleware/create-middleware.js

@@ -105,6 +105,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
 // =============================================================================
@@ -311,9 +339,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 +383,7 @@ async function checkViability(request, endpoint, log) {
     };
     const sessionPointer = {
         exists: false,
-        sessionToken: undefined,
+        sessionTokenId: undefined,
         expired: false,
         hasRefreshToken: false,
         roles: [],
@@ -369,11 +404,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 +492,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 +529,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 +543,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/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)();