@payez/next-mvp 4.1.21 → 4.4.0

package/dist/api-handlers/account/reset-password.js

@@ -2,20 +2,53 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.POST = POST;
 const server_1 = require("next/server");
+const idp_client_config_1 = require("../../lib/idp-client-config");
+const client_key_1 = require("../../lib/client-key");
 function getIdpUrl() {
     const url = process.env.IDP_URL;
     if (!url)
         throw new Error('[IDP_URL] FATAL: IDP_URL environment variable is REQUIRED.');
     return url;
 }
+/**
+ * RECOVERY CLIENT KEY — cards 268012 (S12) and 268410.
+ *
+ * These four proxies populated NONE of PayEzClientIdResolver's six slots, so
+ * RequirePayEzUnAuthorized 404'd the request BEFORE the action ran and no
+ * recovery token was ever minted. That is why S12 failed at step 1.
+ *
+ * NOT `ENV_CONFIG.CLIENT_ID`, which is what card 268012 originally prescribed.
+ * That variable is the ENVIRONMENT-SPECIFIC NUMERIC id, and the IDP accepts a
+ * numeric with NO existence check (RequirePayEzUnAuthorizedAttribute.cs:31-33)
+ * while it VALIDATES a slug (:41-47). Hardcoding the numeric here would have
+ * added four more sites to the 268410 family and made a stale id answer for
+ * the WRONG TENANT on a password-reset path, silently. Slug-preferring, with
+ * the numeric fallback logged, is the same resolver the other nine sites use.
+ *
+ * SERVER VALUE WINS: client_id is applied AFTER the caller's payload spread.
+ * These are unauthenticated recovery endpoints, so a browser-supplied
+ * client_id would be a tenant-targeting lever. The caller does not get to
+ * choose which tenant their password reset is addressed to.
+ */
+async function recoveryClientKey() {
+    try {
+        const config = await (0, idp_client_config_1.getIDPClientConfig)();
+        return (0, client_key_1.resolveClientKey)(config, 'account/reset-password').key;
+    }
+    catch (e) {
+        console.error('[account/reset-password] could not resolve IDP client config for client_id:', e);
+        return null;
+    }
+}
 async function POST(req) {
     const IDP_URL = getIdpUrl();
     try {
         const payload = await req.json();
+        const clientKey = await recoveryClientKey();
         const upstream = await fetch(`${IDP_URL}/api/Account/reset-password`, {
             method: 'POST',
-            headers: { 'Content-Type': 'application/json' },
-            body: JSON.stringify(payload),
+            headers: { 'Content-Type': 'application/json', ...(clientKey ? { 'X-Client-Id': clientKey } : {}) },
+            body: JSON.stringify({ ...payload, ...(clientKey ? { client_id: clientKey } : {}) }),
         });
         const data = await upstream.json().catch(() => ({}));
         return server_1.NextResponse.json(data, { status: upstream.status });

package/dist/api-handlers/account/validate-password.js

@@ -20,7 +20,7 @@ async function POST(req) {
         }
         // Get IDP base URL and client ID from environment
         const idpBaseUrl = process.env.IDP_URL;
-        const clientId = process.env.CLIENT_ID || process.env.NEXT_PUBLIC_CLIENT_ID;
+        const clientId = process.env.CLIENT_ID;
         if (!idpBaseUrl) {
             console.error('[VALIDATE_PASSWORD] IDP_URL not configured');
             return server_1.NextResponse.json({
@@ -61,8 +61,26 @@ async function POST(req) {
                 headers: { 'Cache-Control': 'no-store' },
             });
         }
-        // Return the IDP response with proper structure
-        return server_1.NextResponse.json(responseData, {
+        /**
+         * 283211 - UNWRAP THE IDP ENVELOPE. Approved by BAPert 2026-08-30.
+         *
+         * The IDP answers this endpoint with an ENVELOPE - { success, data: { is_valid, score,
+         * failed_requirements, policy } } - and this line used to hand that straight back. The
+         * `as ValidatePasswordResponse` is a COMPILE-TIME ASSERTION AND PERFORMS NO RUNTIME
+         * TRANSFORMATION, so nothing ever reshaped it and the type told us it was fine.
+         *
+         * The consumer is usePasswordValidation, which reads `data.is_valid` at the top level and
+         * calls setIsValid with it. Against an envelope that is `undefined`, so isValid never
+         * became true; and EVERY error path in this file returns a FLAT { is_valid: false }. So the
+         * success shape was unreadable and the failure shape was readable-and-false: setIsValid(true)
+         * was UNREACHABLE, and the Change Password button's `canSubmit` could never enable.
+         *
+         * `responseData?.data ?? responseData` is defensive in both directions BY DESIGN: it unwraps
+         * the envelope we get today and passes a flat body through unchanged, so it does not break
+         * if the IDP is later made consistent with this file's own declared response type.
+         */
+        const unwrapped = responseData?.data ?? responseData;
+        return server_1.NextResponse.json(unwrapped, {
             status: 200,
             headers: { 'Cache-Control': 'no-store' },
         });

package/dist/api-handlers/admin/analytics.js

@@ -46,6 +46,7 @@ exports.createAnalyticsHandler = createAnalyticsHandler;
 const server_1 = require("next/server");
 const auth_1 = require("../../server/auth");
 const startup_init_1 = require("../../lib/startup-init");
+const client_key_1 = require("../../lib/client-key");
 const roles_1 = require("../../lib/roles");
 async function checkAdminRole(request) {
     const session = await (0, auth_1.getSession)(request);
@@ -82,7 +83,7 @@ async function vibeServiceRequest(endpoint, options) {
     const proxyUrl = `${idpUrl}/api/vibe/proxy`;
     // Get the client slug from startup config for multi-client admin support
     const idpConfig = (0, startup_init_1.getStartupIDPConfig)();
-    const idpClientId = idpConfig?.clientSlug || idpConfig?.clientId;
+    const idpClientId = (0, client_key_1.resolveClientKey)(idpConfig, 'admin/analytics').key;
     try {
         const res = await fetch(proxyUrl, {
             method: 'POST',

package/dist/api-handlers/admin/audit.js

@@ -45,6 +45,7 @@ exports.createAuditHandler = createAuditHandler;
 const server_1 = require("next/server");
 const auth_1 = require("../../server/auth");
 const startup_init_1 = require("../../lib/startup-init");
+const client_key_1 = require("../../lib/client-key");
 const roles_1 = require("../../lib/roles");
 async function checkAdminRole(request) {
     const session = await (0, auth_1.getSession)(request);
@@ -81,7 +82,7 @@ async function vibeServiceRequest(endpoint, options) {
     const proxyUrl = `${idpUrl}/api/vibe/proxy`;
     // Get the client slug from startup config for multi-client admin support
     const idpConfig = (0, startup_init_1.getStartupIDPConfig)();
-    const idpClientId = idpConfig?.clientSlug || idpConfig?.clientId;
+    const idpClientId = (0, client_key_1.resolveClientKey)(idpConfig, 'admin/audit').key;
     try {
         const res = await fetch(proxyUrl, {
             method: 'POST',

package/dist/api-handlers/admin/sessions.js

@@ -46,6 +46,7 @@ exports.createSessionsHandler = createSessionsHandler;
 const server_1 = require("next/server");
 const auth_1 = require("../../server/auth");
 const startup_init_1 = require("../../lib/startup-init");
+const client_key_1 = require("../../lib/client-key");
 const roles_1 = require("../../lib/roles");
 /**
  * Check if the current user has admin role
@@ -88,7 +89,7 @@ async function vibeServiceRequest(endpoint, options) {
     const proxyUrl = `${idpUrl}/api/vibe/proxy`;
     // Get the client slug from startup config for multi-client admin support
     const idpConfig = (0, startup_init_1.getStartupIDPConfig)();
-    const idpClientId = idpConfig?.clientSlug || idpConfig?.clientId;
+    const idpClientId = (0, client_key_1.resolveClientKey)(idpConfig, 'admin/sessions').key;
     try {
         const res = await fetch(proxyUrl, {
             method: 'POST',

package/dist/api-handlers/admin/stats.js

@@ -46,6 +46,7 @@ exports.createStatsHandler = createStatsHandler;
 const server_1 = require("next/server");
 const auth_1 = require("../../server/auth");
 const startup_init_1 = require("../../lib/startup-init");
+const client_key_1 = require("../../lib/client-key");
 const redis_1 = require("../../lib/redis");
 const roles_1 = require("../../lib/roles");
 async function checkAdminRole(request) {
@@ -82,7 +83,7 @@ async function vibeServiceRequest(endpoint, options) {
         .digest('base64');
     const proxyUrl = `${idpUrl}/api/vibe/proxy`;
     const idpConfig = (0, startup_init_1.getStartupIDPConfig)();
-    const idpClientId = idpConfig?.clientSlug || idpConfig?.clientId;
+    const idpClientId = (0, client_key_1.resolveClientKey)(idpConfig, 'admin/stats').key;
     try {
         const res = await fetch(proxyUrl, {
             method: 'POST',

package/dist/api-handlers/admin/users.js

@@ -45,6 +45,7 @@ exports.createUsersHandler = createUsersHandler;
 const server_1 = require("next/server");
 const auth_1 = require("../../server/auth");
 const startup_init_1 = require("../../lib/startup-init");
+const client_key_1 = require("../../lib/client-key");
 const roles_1 = require("../../lib/roles");
 async function checkAdminRole(request) {
     const session = await (0, auth_1.getSession)(request);
@@ -81,7 +82,7 @@ async function vibeServiceRequest(endpoint, options) {
     const proxyUrl = `${idpUrl}/api/vibe/proxy`;
     // Get the client slug from startup config for multi-client admin support
     const idpConfig = (0, startup_init_1.getStartupIDPConfig)();
-    const idpClientId = idpConfig?.clientSlug || idpConfig?.clientId;
+    const idpClientId = (0, client_key_1.resolveClientKey)(idpConfig, 'admin/users').key;
     try {
         const res = await fetch(proxyUrl, {
             method: 'POST',

package/dist/api-handlers/admin/vibe-data.js

@@ -52,6 +52,7 @@ exports.createQueryHandler = createQueryHandler;
 const server_1 = require("next/server");
 const auth_1 = require("../../server/auth");
 const startup_init_1 = require("../../lib/startup-init");
+const client_key_1 = require("../../lib/client-key");
 const roles_1 = require("../../lib/roles");
 /**
  * Check if the current user has admin role
@@ -96,7 +97,7 @@ async function vibeServiceRequest(endpoint, options) {
     const proxyUrl = `${idpUrl}/api/vibe/proxy`;
     // Get the client slug from startup config for multi-client admin support
     const idpConfig = (0, startup_init_1.getStartupIDPConfig)();
-    const idpClientId = idpConfig?.clientSlug || idpConfig?.clientId;
+    const idpClientId = (0, client_key_1.resolveClientKey)(idpConfig, 'admin/vibe-data').key;
     try {
         const res = await fetch(proxyUrl, {
             method: 'POST',

package/dist/api-handlers/auth/jwks.js

@@ -4,9 +4,12 @@ exports.GET = GET;
 const server_1 = require("next/server");
 const env_1 = require("../../config/env");
 const logger_1 = require("../../config/logger");
+const idp_url_guard_1 = require("../../lib/idp-url-guard");
 async function GET(_req) {
     try {
         const url = `${env_1.ENV_CONFIG.IDP_URL}${env_1.API_ENDPOINTS.externalAuth.jwks}`;
+        // Direct fetch - the idpFetchJSON guard is not on this path.
+        (0, idp_url_guard_1.assertAbsoluteIdpUrl)(url);
         const res = await fetch(url, { headers: { 'Accept': 'application/json' } });
         const bodyText = await res.text();
         try {
@@ -19,6 +22,13 @@ async function GET(_req) {
         }
     }
     catch (error) {
+        // This catch DISCARDED `error` entirely and answered a bare 502, so a config
+        // fault and a dead upstream were indistinguishable - and the guard's named
+        // message above would have been swallowed with them. The 502 body is left
+        // unchanged (it is a public response shape); the cause now reaches the log.
+        logger_1.logger.error('[AUTH_JWKS] Failed to fetch JWKS', {
+            message: error instanceof Error ? error.message : String(error),
+        });
         return server_1.NextResponse.json({ error: 'Failed to fetch JWKS' }, { status: 502 });
     }
 }

package/dist/api-handlers/auth/login.js

@@ -87,10 +87,13 @@ function createLoginHandler(config) {
         }
         // Extract client headers for forwarding to IDP
         const clientHeaders = {};
-        // Forward client IP if available
+        // Forward client IP if available.
+        // 269334 / R21: forward the FULL chain, do NOT collapse to [0] - see the same
+        // change in lib/idp-fetch.ts. [0] is the forgeable client-supplied entry and
+        // collapsing to it destroys the chain the IDP's trusted-hop logic reads.
         const clientIp = req.headers.get('x-forwarded-for') || req.headers.get('x-real-ip');
         if (clientIp) {
-            clientHeaders['X-Forwarded-For'] = clientIp.split(',')[0].trim();
+            clientHeaders['X-Forwarded-For'] = clientIp;
         }
         // Forward user agent if available
         const userAgent = req.headers.get('user-agent');

package/dist/api-handlers/auth/passkey-signin.js

@@ -5,6 +5,8 @@ exports.verifyPOST = verifyPOST;
 const server_1 = require("next/server");
 const env_1 = require("../../config/env");
 const idp_client_config_1 = require("../../lib/idp-client-config");
+const client_key_1 = require("../../lib/client-key");
+const idp_url_guard_1 = require("../../lib/idp-url-guard");
 /**
  * Passkey SIGN-IN ceremony (ANONYMOUS — no session exists yet):
  *   optionsPOST -> POST /api/ExternalAuth/passwordless/passkey/options
@@ -21,7 +23,14 @@ const idp_client_config_1 = require("../../lib/idp-client-config");
  */
 async function clientKey() {
     const config = await (0, idp_client_config_1.getIDPClientConfig)();
-    return config.clientSlug || String(config.clientId);
+    const { key } = (0, client_key_1.resolveClientKey)(config, 'auth/passkey-signin');
+    // Refuse rather than send an empty client_id. Card 268410: the graft's own
+    // copy of this path learned this the hard way — `|| ''` made an unset config
+    // look like a valid value and the IDP answered "client_id is required" in
+    // 7-9ms, which read as a request-shape bug for hours.
+    if (!key)
+        throw new Error('[passkey-signin] no IDP client slug or id resolved - refusing to send an empty client_id');
+    return key;
 }
 async function anonCall(req, path) {
     let parsed = {};
@@ -32,6 +41,10 @@ async function anonCall(req, path) {
     }
     catch { }
     const key = await clientKey();
+    // This route calls fetch directly, so it does NOT reach the guard inside
+    // idpFetchJSON. Same reasoning as the clientKey() throw above: name the missing
+    // config rather than sending a request built from it.
+    (0, idp_url_guard_1.assertAbsoluteIdpUrl)(`${env_1.ENV_CONFIG.IDP_URL}${path}`);
     const res = await fetch(`${env_1.ENV_CONFIG.IDP_URL}${path}`, {
         method: 'POST',
         headers: { 'Content-Type': 'application/json', 'X-Client-Id': key },
@@ -86,6 +99,8 @@ async function verifyPOST(req) {
     const nested = response && typeof response === 'object' && 'id' in response;
     const assertion = nested ? response : { ...rest, response };
     const key = await clientKey();
+    // Direct fetch - see the note in anonCall; the idpFetchJSON guard is not on this path.
+    (0, idp_url_guard_1.assertAbsoluteIdpUrl)(`${env_1.ENV_CONFIG.IDP_URL}/api/ExternalAuth/passwordless/passkey/verify`);
     const res = await fetch(`${env_1.ENV_CONFIG.IDP_URL}/api/ExternalAuth/passwordless/passkey/verify`, {
         method: 'POST',
         headers: { 'Content-Type': 'application/json', 'X-Client-Id': key },

package/dist/api-handlers/auth/refresh.d.ts

@@ -4,14 +4,34 @@
  * ASK BEFORE EDITING - TESTED AND WORKING SYSTEM
  *
  * This handler manages the server-side refresh token cycle with:
- * - Better Auth session extraction
- * - Session token fallback for internal calls
+ * - Better Auth session extraction (the ONLY way a session is established here)
  * - PayEz IDP refresh token exchange
  * - Session state updates with new tokens
  * - Proper error handling and logging
  * - Single-use semantics enforcement
  *
- * @version 2.0
+ * ── 246007: THE `x-session-token` FALLBACK IS GONE. IT NOW HARD-DENIES. ────
+ * This list previously advertised an x-session-token fallback for internal
+ * callers as a current capability. That behaviour has been REMOVED: a request presenting `x-session-token` with
+ * no cookie-resolved session of its own is rejected 401 UNAUTHORIZED, because
+ * there is no session to establish ownership of the token it names. Accepting
+ * it let a caller refresh a session they did not own.
+ *
+ * The line is corrected here rather than merely deleted, and it is called out
+ * rather than quietly dropped, because THIS DOCSTRING SHIPS. It is compiled
+ * into dist and into the .d.ts, so it reaches every consumer's editor as hover
+ * text. QAPert-NightHawk caught that the fixed build was still describing the
+ * removed capability as a current feature (34973) — her verifier tests code
+ * properties and reads no comments, so a correct build could have published
+ * documentation asserting the opposite of what the code does.
+ *
+ * That matters twice over: an internal caller relying on the fallback gets a
+ * silent behavioural break while the docs promise it still works, and a
+ * published package that misdescribes its own auth behaviour is the same
+ * amplifier that put other defects onto three surfaces — shipped code carrying
+ * instructions for using it wrongly.
+ *
+ * @version 2.1
  */
 import { NextRequest, NextResponse } from 'next/server';
 interface RefreshConfig {

package/dist/api-handlers/auth/refresh.js

@@ -5,19 +5,40 @@
  * ASK BEFORE EDITING - TESTED AND WORKING SYSTEM
  *
  * This handler manages the server-side refresh token cycle with:
- * - Better Auth session extraction
- * - Session token fallback for internal calls
+ * - Better Auth session extraction (the ONLY way a session is established here)
  * - PayEz IDP refresh token exchange
  * - Session state updates with new tokens
  * - Proper error handling and logging
  * - Single-use semantics enforcement
  *
- * @version 2.0
+ * ── 246007: THE `x-session-token` FALLBACK IS GONE. IT NOW HARD-DENIES. ────
+ * This list previously advertised an x-session-token fallback for internal
+ * callers as a current capability. That behaviour has been REMOVED: a request presenting `x-session-token` with
+ * no cookie-resolved session of its own is rejected 401 UNAUTHORIZED, because
+ * there is no session to establish ownership of the token it names. Accepting
+ * it let a caller refresh a session they did not own.
+ *
+ * The line is corrected here rather than merely deleted, and it is called out
+ * rather than quietly dropped, because THIS DOCSTRING SHIPS. It is compiled
+ * into dist and into the .d.ts, so it reaches every consumer's editor as hover
+ * text. QAPert-NightHawk caught that the fixed build was still describing the
+ * removed capability as a current feature (34973) — her verifier tests code
+ * properties and reads no comments, so a correct build could have published
+ * documentation asserting the opposite of what the code does.
+ *
+ * That matters twice over: an internal caller relying on the fallback gets a
+ * silent behavioural break while the docs promise it still works, and a
+ * published package that misdescribes its own auth behaviour is the same
+ * amplifier that put other defects onto three surfaces — shipped code carrying
+ * instructions for using it wrongly.
+ *
+ * @version 2.1
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.POST = void 0;
 exports.createRefreshHandler = createRefreshHandler;
 const server_1 = require("next/server");
+const crypto_1 = require("crypto");
 const auth_1 = require("../../server/auth");
 const session_store_1 = require("../../lib/session-store");
 const token_expiry_1 = require("../../lib/token-expiry");
@@ -49,12 +70,50 @@ function createRefreshHandler(config) {
             let sessionToken = (betterAuthSession?.session?.token);
             let userId = betterAuthSession?.user?.id;
             if (!sessionToken) {
-                // Fallback: check for session token in header (for internal server-to-server calls)
+                // OWNERSHIP CHECK on the x-session-token fallback (246007). BAPert ruled
+                // 34708: ship it, accept the one-time re-login cost, do not gate on 240654.
+                //
+                // WHAT THIS CLOSED: the fallback took a session token from a CALLER-SUPPLIED
+                // header and acted on that session with no check that it belonged to the
+                // caller. /api/auth/* is in publicRoutes on the consuming surfaces, so an
+                // UNAUTHENTICATED caller who knew any session token could cause that session
+                // to be refreshed -- an identity assumption, and the precondition for the
+                // forced-logout chain via IDP reuse detection.
+                //
+                // WHY THE CHECK IS A HARD DENY RATHER THAN A COMPARISON, which is the part
+                // worth understanding before anyone "improves" it: this branch is reached
+                // ONLY when getBetterAuthSession() failed to resolve a session from the
+                // request's own cookie. The natural ownership check -- "the header may only
+                // name the session the caller's cookie already resolves to" -- therefore has
+                // nothing to compare against by construction. Any correct ownership test at
+                // this point evaluates to reject. So the check and outright removal coincide
+                // here; a more permissive version is not possible without moving the check
+                // somewhere it can actually see an authenticated identity.
+                //
+                // WHO THIS AFFECTS, and it is a deliberate accepted cost, not an oversight:
+                // internal callers (lib/internal-api internalRefresh, from api-handler and
+                // idp-fetch) forward the end user's cookie. Where that cookie resolves they
+                // never enter this branch and are unaffected. Where it does not -- sessions
+                // minted before the graft dual-write (8a5ac21) whose cookie carries only the
+                // __Secure- name, which the pre-240654 resolver could not read -- the refresh
+                // now fails and the user re-authenticates ONCE. Their next login writes both
+                // cookie names and they are permanently fine. That population cannot grow, does
+                // not age out (session TTL slides on every write), and does not self-heal on
+                // use (this handler sets no cookie) -- so the only ways out were to accept the
+                // re-login or leave the defect live. BAPert chose to accept it.
+                //
+                // If server-to-server refresh must work WITHOUT an end-user cookie, that needs
+                // real service authentication -- a shared secret, mTLS, or a network policy --
+                // never a header any client can set.
                 const headerSessionToken = req.headers.get('x-session-token');
                 if (headerSessionToken) {
-                    sessionToken = headerSessionToken;
-                    const currentSession = await (0, session_store_1.getSession)(sessionToken);
-                    userId = currentSession?.userId || currentSession?.email;
+                    console.warn('[AUTH_REFRESH] REJECTED x-session-token: no cookie-resolved session to own it. ' +
+                        'A header-named session is not proof of ownership; the caller must present a ' +
+                        'session cookie this server can resolve.');
+                    return server_1.NextResponse.json({
+                        error: 'Session ownership could not be established',
+                        code: 'UNAUTHORIZED',
+                    }, { status: 401 });
                 }
             }
             if (!sessionToken || !userId) {
@@ -102,19 +161,41 @@ function createRefreshHandler(config) {
             console.log(`║ 2FA Complete:             ${String(!!currentSession.mfaVerified).padEnd(10)}                                   ║`);
             console.log(`║ Auth Level (ACR):         ${String(currentSession.authenticationLevel || '1').padEnd(10)}                                   ║`);
             console.log('╚══════════════════════════════════════════════════════════════════════════════╝');
-            // Try to acquire refresh lock to prevent concurrent refresh attempts
-            const requestId = req.headers.get('x-request-id') ?? `refresh_${Date.now()}`;
+            // LOCK IDENTITY IS MINTED SERVER-SIDE. It must never come from a header.
+            //
+            // This was `req.headers.get('x-request-id') ?? \`refresh_${Date.now()}\``, and the
+            // value was used as the lock's `acquiredBy`. Below it, a branch let a caller
+            // PROCEED WITHOUT THE LOCK when the existing lock's acquiredBy equalled the id
+            // they had supplied. Since the caller chose that id, the branch was a lock
+            // bypass requiring no guesswork: send N concurrent requests all carrying the
+            // same x-request-id, and every one after the first skips the wait.
+            //
+            // That completed an attacker-controlled forced logout, because the serialisation
+            // is what prevents refresh-token REUSE, and the IDP treats reuse as compromise:
+            // IdentityRefreshTokenService:166 -> RevokeDescendantTokens ->
+            // IdentityRefreshTokenRepository:142 revokes every ACTIVE token for that USER
+            // issued after the reused one -- across all devices and all client apps. So a
+            // caller who knew one session token could log a user out everywhere by sending
+            // a few requests with a header value of their own choosing.
+            //
+            // Minting server-side removes the bypass by construction: no caller can produce
+            // a value that matches an in-flight lock, so the equality branch can never be
+            // true and is deleted rather than left inert -- an unreachable branch that
+            // trusts a header is a trap for whoever edits this next.
+            //
+            // The anti-deadlock intent that branch served is preserved by the wait path
+            // below, which is the correct handling anyway: a genuine duplicate waits for the
+            // in-flight refresh and returns its result instead of starting a second one.
+            // The header is still read, for TRACING ONLY, and never influences control flow.
+            const traceId = req.headers.get('x-request-id') ?? undefined;
+            const requestId = `refresh_${(0, crypto_1.randomUUID)()}`;
             const lockAcquired = await (0, session_store_1.acquireRefreshLock)(sessionToken, requestId, 5000);
             let weAcquiredLock = false;
             let releaseLockVersion;
             if (!lockAcquired.acquired) {
-                const existingLock = await (0, session_store_1.checkRefreshLock)(sessionToken);
-                if (existingLock && existingLock.acquiredBy === requestId) {
-                    console.info('[AUTH_REFRESH] Proceeding under existing caller-held lock', { requestId });
-                }
-                else {
+                {
                     // Wait for the lock to release, then check if token is now fresh
-                    console.info('[AUTH_REFRESH] Refresh in progress by another request, waiting for completion...', { requestId });
+                    console.info('[AUTH_REFRESH] Refresh in progress by another request, waiting for completion...', { requestId, traceId });
                     const maxWaitMs = 5000;
                     const checkIntervalMs = 200;
                     const startWait = Date.now();
@@ -595,7 +676,17 @@ function createRefreshHandler(config) {
                     bearerKeyId: newBearerKeyId || currentSession.bearerKeyId,
                     authenticationMethods: amrClaims,
                     authenticationLevel: acrLevel,
-                    mfaVerified: amrClaims.includes('mfa') || currentSession.mfaVerified,
+                    // 170007 rule 2 (BAPert ruling on 121350): '||' is the wrong operator
+                    // for a fact with an expiry. mfaVerified is derived from amrClaims,
+                    // which is FRESH every exchange (decoded from the token just
+                    // returned, falling back to the prior session's amr only on a
+                    // genuine decode failure a few lines up — not on "this token
+                    // doesn't currently carry mfa"). ORing in currentSession.mfaVerified
+                    // made the flag MONOTONIC against a claim that DECAYS (mfa_time,
+                    // 10 minutes): once true, it stayed true forever regardless of
+                    // what the current token actually says, silently re-opening the
+                    // 2FA bypass with no bug in the bridge. Re-derive only.
+                    mfaVerified: amrClaims.includes('mfa'),
                     mfaCompletedAt: mfaTime,
                     mfaExpiresAt: mfaExpires,
                     mfaValidityHours: mfaValidityHours

package/dist/api-handlers/auth/signout.js

@@ -129,10 +129,11 @@ function createSignoutHandler() {
                 console.warn('[SIGNOUT] Manual JWT decode failed to extract session token');
             }
         }
-        // Delete Redis session if UUID was extracted
+        // Delete the session from EVERY store (181922): canonical + BA secondary.
+        // Canonical-only deletion let the ba: record resurrect the session.
         if (redisSessionToken) {
             try {
-                await (0, session_store_1.deleteSession)(redisSessionToken);
+                await (0, session_store_1.deleteSessionEverywhere)(redisSessionToken);
                 console.info('[SIGNOUT] Redis session cleanup successful', {
                     sessionToken: redisSessionToken.substring(0, 8) + '...'
                 });

package/dist/api-handlers/auth/verify-code.js

@@ -57,8 +57,11 @@ function createVerifyCodeHandler() {
             });
             // Update tokens in Redis
             await (0, session_store_1.updateTokens)(sessionToken, accessToken, refreshToken, accessTokenExpires, refreshTokenExpires);
-            // Mark 2FA as complete
-            await (0, session_store_1.mark2FAComplete)(sessionToken);
+            // Mark 2FA as complete.
+            // 339563: pass the stepped-up access token so the session gets an
+            // mfaExpiresAt alongside mfaVerified. Without it the gate's `> 0` guard
+            // treats the missing expiry as "never expires".
+            await (0, session_store_1.mark2FAComplete)(sessionToken, accessToken);
             console.info('[VERIFY-CODE] 2FA completion successful', {
                 sessionToken: sessionToken.substring(0, 8) + '...',
                 userId: betterAuthSession?.user?.id

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

@@ -71,7 +71,33 @@ async function GET(req) {
                 // CRITICAL: OAuth sessions without refresh token always need 2FA completion
                 // to obtain a refresh token from the IDP. The OAuth callback sets mfaVerified=false
                 // when no refresh_token is present. This must override the client config.
-                if (sessionData.mfaVerified === false && !sessionData.idpRefreshToken) {
+                //
+                // *** R807 (BAPert, card 362550) — SECOND OF THE TWO SITES THE SIGNAL IS FOR. ***
+                // The `=== false` below reads as strict but had stopped behaving strictly: every
+                // construction site collapses an ABSENT mfaVerified to `false` (`?? false`), so by
+                // the time it is read here "the callback said false" and "we never knew" are the
+                // same value. This override therefore fired on EVERY session, not on OAuth sessions
+                // that genuinely lack a refresh token.
+                //
+                // The comment at line ~122 of this file already warned that fixing only ONE of the
+                // two viability implementations leaves an app mounting the other one blind. That
+                // applies here verbatim: routes/auth/viability.ts carries the same guard, and both
+                // are publicly exported entry points, so both must gate on the signal or the defect
+                // survives one export over.
+                //
+                // mfaSignalPresent === true -> the producer really emitted a value, so the `false`
+                //                              is a MEASUREMENT. Override.
+                // absent / false            -> LEGACY session (minted before the signal existed) or
+                //                              a path with no IDP tokens. NOT a signal. Do not
+                //                              force a re-challenge.
+                //
+                // *** CONFINED, BY RULING. *** This signal is permissive by construction — it can
+                // only ever SUPPRESS this override, never grant access. Anything that GRANTS must
+                // keep gating on `mfaVerified`, which stays fail-closed at all five sites. R807 is
+                // void if this signal reaches an auth decision.
+                if (sessionData.mfaSignalPresent === true &&
+                    sessionData.mfaVerified === false &&
+                    !sessionData.idpRefreshToken) {
                     requires2FA = true;
                 }
                 // CRITICAL: Check if MFA has expired (2FA TTL enforcement)

package/dist/api-handlers/test/force-expire.d.ts

@@ -1,23 +1,37 @@
 import { NextRequest, NextResponse } from 'next/server';
 /**
- * Force-expire access token for testing refresh flow.
+ * ⚠️ DESTRUCTIVE TEST-ONLY HANDLER — DO NOT MOUNT IN PRODUCTION. ⚠️
  *
- * Sets the access token expiry to 2 minutes in the past,
- * which will trigger a refresh on the next API call.
+ * Force-expire access token for testing refresh flow. Sets the access token
+ * expiry to 2 minutes in the past, which will trigger a refresh on the next
+ * API call.
+ *
+ * THIS MUTATES SESSION STATE. It is a test affordance, not a product feature.
+ *
+ * ── WHY THIS WARNING EXISTS (QAPert 34983) ────────────────────────────────
+ * The usage block below is not decoration: THIS DOCSTRING IS THE SPREAD
+ * MECHANISM. It ships compiled into dist and into the .d.ts, so it reaches
+ * every consumer's editor as hover text, and it is a one-line copy-paste that
+ * mounts a destructive endpoint. Every one of the three surfaces this route
+ * ended up on followed exactly these instructions.
+ *
+ * The handler itself was fixed (244877: default-deny behind ENABLE_TEST_ROUTES,
+ * plus the caller-supplied-token IDOR removed). But a fixed handler shipped
+ * with unqualified mounting instructions still spreads: the guidance was never
+ * corrected alongside the code, and a package that documents a dangerous route
+ * as a plain convenience is instructing the weaker configuration.
+ *
+ * ── IF YOU MOUNT IT, MOUNT IT LIKE THIS ───────────────────────────────────
+ * Required: set ENABLE_TEST_ROUTES=true IN THAT ENVIRONMENT ONLY. Absent, empty
+ * or any other value default-DENIES (404). Never set it in production.
  *
- * Usage in consuming app:
  * ```typescript
- * // app/api/test/force-expire/route.ts
+ * // app/api/test/force-expire/route.ts   — TEST/DEV ENVIRONMENTS ONLY
+ * // Requires ENABLE_TEST_ROUTES=true in that environment; 404s otherwise.
  * export { POST } from '@payez/next-mvp/api-handlers/test/force-expire';
  * ```
+ *
+ * If you do not need to exercise the refresh flow, DO NOT MOUNT THIS AT ALL.
+ * The safest configuration is the absence of the route.
  */
-export declare const POST: (req: NextRequest) => Promise<NextResponse<{
-    success: boolean;
-    error: string;
-}> | NextResponse<{
-    success: boolean;
-    previous: number | null;
-    previousIso: string | null;
-    newExpiry: number;
-    newExpiryIso: string;
-}>>;
+export declare const POST: (req: NextRequest) => Promise<NextResponse<unknown>>;