@payez/next-mvp 4.1.21 → 4.4.0

package/src/api-handlers/auth/refresh.ts

@@ -4,17 +4,38 @@
  * 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';
+import { randomUUID } from 'crypto';
 import { getSession as getBetterAuthSession } from '../../server/auth';
 import { getSession, updateSession, acquireRefreshLock, releaseRefreshLock, checkRefreshLock } from '../../lib/session-store';
 import { computeTokenExpiries } from '../../lib/token-expiry';
@@ -56,12 +77,55 @@ export function createRefreshHandler(config: RefreshConfig) {
       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 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 NextResponse.json(
+            {
+              error: 'Session ownership could not be established',
+              code: 'UNAUTHORIZED',
+            },
+            { status: 401 },
+          );
         }
       }
 
@@ -114,20 +178,43 @@ export function createRefreshHandler(config: RefreshConfig) {
       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_${randomUUID()}`;
       const lockAcquired = await acquireRefreshLock(sessionToken, requestId, 5000);
 
       let weAcquiredLock = false;
       let releaseLockVersion: number | undefined;
 
       if (!lockAcquired.acquired) {
-        const existingLock = await 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;
@@ -643,7 +730,17 @@ export function createRefreshHandler(config: RefreshConfig) {
           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/src/api-handlers/auth/signout.ts

@@ -11,7 +11,7 @@
 
 import { NextRequest, NextResponse } from 'next/server';
 import { cookies } from 'next/headers';
-import { deleteSession } from '../../lib/session-store';
+import { deleteSessionEverywhere } from '../../lib/session-store';
 import { getSession } from '../../server/auth';
 import {
   getSessionCookieName,
@@ -146,10 +146,11 @@ export function createSignoutHandler() {
       }
     }
 
-    // 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 deleteSession(redisSessionToken);
+        await deleteSessionEverywhere(redisSessionToken);
         console.info('[SIGNOUT] Redis session cleanup successful', {
           sessionToken: redisSessionToken.substring(0, 8) + '...'
         });

package/src/api-handlers/auth/verify-code.ts

@@ -81,8 +81,11 @@ export function createVerifyCodeHandler() {
         refreshTokenExpires
       );
 
-      // Mark 2FA as complete
-      await 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 mark2FAComplete(sessionToken, accessToken);
 
       console.info('[VERIFY-CODE] 2FA completion successful', {
         sessionToken: sessionToken.substring(0, 8) + '...',

package/src/api-handlers/mfa/backup-code-verify.ts

@@ -1,175 +1,175 @@
-/**
- * Verify Backup Code 2FA Challenge Handler
- *
- * Verifies a single-use recovery code AT LOGIN and completes the 2FA flow,
- * transitioning the session to MFA-verified.
- *
- * WHY THIS EXISTS (2026-08-02)
- * The package shipped backup-code GENERATION (backup-codes.ts, POST
- * /api/Account/mfa/backup-codes) and no way to SPEND one. Codes could be
- * generated, displayed once, written down — and then never used to satisfy a
- * login challenge. Exactly the gap TOTP had before totp-verify: the enrolment
- * half without the challenge half.
- *
- * THIS IS THE FACTOR OF LAST RESORT. A user reaches for a backup code when they
- * have lost the authenticator, so it is the one path that must work when
- * everything else has already failed. A recovery mechanism that cannot be
- * redeemed is worse than none: it invites people to rely on it.
- *
- * FIELD NAME: the IDP expects { "code": ... }
- * (MfaBackupCodeVerifyRequest, [JsonPropertyName("code")]). The dash in
- * 'xxxx-xxxx' is optional per the IDP contract, so the code is forwarded as
- * typed and normalisation is left to the IDP rather than guessed here.
- *
- * SINGLE USE, CONSUMED ATOMICALLY. The IDP hash-compares against unused codes
- * and stamps used_at + used_by_ip in the same operation (MfaController 5g).
- * NEVER retry this call on a network error or an ambiguous response — a retry
- * can burn a second code, and the user has ten.
- *
- * DO NOT MAKE GENERATION TRANSITION THE SESSION, the same trap totp-confirm
- * carries: generating recovery codes is not proof of possessing one.
- *
- * THE STORED 2FA METHOD IS 'totp', NOT 'backup_code'. READ THIS BEFORE
- * "CORRECTING" IT — it looks wrong and is not.
- *
- *   1. IT MATCHES THE IDP. MfaController 5g sets
- *      `TwoFactorMethod = TwoFactorMethodType.Totp` for this exact path,
- *      commented "Backup code = recovery proof of the TOTP factor", and the
- *      reissued token's amr carries mfa+totp. A backup code is not a separate
- *      factor; it is recovery proof of the authenticator factor.
- *
- *   2. INVENTING A NEW VALUE SILENTLY BREAKS TOKEN REFRESH. refresh.ts:279
- *      resolves the method with ['sms','totp','email'].includes(m). Anything
- *      outside that set is dropped, so `two_factor_method` never reaches the
- *      IDP on refresh, and a session established with a recovery code refreshes
- *      differently from one established with the authenticator — for the same
- *      underlying factor. It fails quietly, days later, as "sessions
- *      occasionally drop", with nothing pointing back to this string.
- *
- * The type union (email|sms|totp) is not the reason for the choice, it is a
- * coincidence that caught it. Widening the union would have compiled and
- * shipped the refresh bug.
- *
- * @package @payez/next-mvp
- */
-
-import { NextRequest, NextResponse } from 'next/server';
-import { idpFetchJSON } from '../../lib/idp-fetch';
-import { ENV_CONFIG } from '../../config/env';
-import { getTokenTestAware } from '../../lib/test-aware-get-token';
-import { transitionTo2FASession } from '../../lib/session-store';
-import { jwtDecode } from '../../lib/jwt-decode';
-
-export async function POST(req: NextRequest) {
-  try {
-    const body = await req.json();
-    const code = body.code || body.backupCode || body.verificationCode || body.verification_code;
-
-    if (!code) {
-      return NextResponse.json(
-        {
-          success: false,
-          error: 'Backup code is required',
-          code: 'INVALID_REQUEST',
-        },
-        { status: 400 }
-      );
-    }
-
-    const result = await idpFetchJSON(
-      req,
-      `${ENV_CONFIG.IDP_URL}/api/ExternalAuth/twofa/backup-code/verify`,
-      {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ code }),
-      }
-    );
-
-    if (!result.ok) {
-      return NextResponse.json(
-        {
-          success: false,
-          error: result.json?.message || 'Verification failed',
-          code: result.json?.code || 'IDP_ERROR',
-          meta: { attemptedRefresh: result.attemptedRefresh },
-        },
-        { status: result.status }
-      );
-    }
-
-    const unwrappedData = result.json?.data || result.json;
-
-    // Only a challenge that returns fresh tokens may transition the session.
-    let sessionTransitioned = false;
-
-    if (unwrappedData.access_token && unwrappedData.refresh_token) {
-      const token = await getTokenTestAware(req);
-      const sessionToken = (token?.sessionToken || token?.redisSessionId) as string | undefined;
-
-      if (sessionToken) {
-        let accessTokenExpires = Date.now() + 15 * 60 * 1000;
-        try {
-          const decoded = jwtDecode<{ exp?: number }>(unwrappedData.access_token);
-          if (decoded?.exp) accessTokenExpires = decoded.exp * 1000;
-        } catch {
-          console.warn('[VERIFY_BACKUP_CODE] Could not decode access token, using default expiration');
-        }
-
-        let refreshTokenExpires = Date.now() + 3 * 24 * 60 * 60 * 1000;
-        try {
-          const decoded = jwtDecode<{ exp?: number }>(unwrappedData.refresh_token);
-          if (decoded?.exp) refreshTokenExpires = decoded.exp * 1000;
-        } catch {
-          // Refresh token may carry no exp claim; default stands.
-        }
-
-        await transitionTo2FASession(
-          sessionToken,
-          {
-            accessToken: unwrappedData.access_token,
-            refreshToken: unwrappedData.refresh_token,
-            accessTokenExpires,
-            refreshTokenExpires,
-          },
-          // 'totp' is deliberate and load-bearing. See "THE STORED 2FA METHOD"
-          // in the file header before changing it.
-          'totp'
-        );
-
-        sessionTransitioned = true;
-        console.log('[VERIFY_BACKUP_CODE] Session transitioned to 2FA-verified');
-      } else {
-        console.warn('[VERIFY_BACKUP_CODE] IDP accepted the code but no session token was resolvable — session NOT transitioned. THE CODE IS ALREADY SPENT.');
-      }
-    } else {
-      console.warn('[VERIFY_BACKUP_CODE] IDP returned 2xx without tokens — session NOT transitioned. THE CODE IS ALREADY SPENT.');
-    }
-
-    // twoFactorSessionVerified reports WHAT ACTUALLY HAPPENED, never a copy of
-    // `success`. It matters more here than anywhere else: the code is consumed
-    // the moment the IDP accepts it, so a client that trusted a hardcoded true
-    // would show the user as verified, leave the session unverified, and have
-    // burned one of their ten recovery codes to do it.
-    return NextResponse.json(
-      {
-        success: true,
-        verificationSuccessful: true,
-        twoFactorSessionVerified: sessionTransitioned,
-        codeConsumed: true,
-        message: unwrappedData.message || 'Backup code verified successfully',
-      },
-      { status: 200 }
-    );
-  } catch (error) {
-    console.error('[VERIFY_BACKUP_CODE] Error:', error);
-    return NextResponse.json(
-      {
-        success: false,
-        error: 'Failed to verify backup code',
-        code: 'INTERNAL_ERROR',
-      },
-      { status: 500 }
-    );
-  }
-}
+/**
+ * Verify Backup Code 2FA Challenge Handler
+ *
+ * Verifies a single-use recovery code AT LOGIN and completes the 2FA flow,
+ * transitioning the session to MFA-verified.
+ *
+ * WHY THIS EXISTS (2026-08-02)
+ * The package shipped backup-code GENERATION (backup-codes.ts, POST
+ * /api/Account/mfa/backup-codes) and no way to SPEND one. Codes could be
+ * generated, displayed once, written down — and then never used to satisfy a
+ * login challenge. Exactly the gap TOTP had before totp-verify: the enrolment
+ * half without the challenge half.
+ *
+ * THIS IS THE FACTOR OF LAST RESORT. A user reaches for a backup code when they
+ * have lost the authenticator, so it is the one path that must work when
+ * everything else has already failed. A recovery mechanism that cannot be
+ * redeemed is worse than none: it invites people to rely on it.
+ *
+ * FIELD NAME: the IDP expects { "code": ... }
+ * (MfaBackupCodeVerifyRequest, [JsonPropertyName("code")]). The dash in
+ * 'xxxx-xxxx' is optional per the IDP contract, so the code is forwarded as
+ * typed and normalisation is left to the IDP rather than guessed here.
+ *
+ * SINGLE USE, CONSUMED ATOMICALLY. The IDP hash-compares against unused codes
+ * and stamps used_at + used_by_ip in the same operation (MfaController 5g).
+ * NEVER retry this call on a network error or an ambiguous response — a retry
+ * can burn a second code, and the user has ten.
+ *
+ * DO NOT MAKE GENERATION TRANSITION THE SESSION, the same trap totp-confirm
+ * carries: generating recovery codes is not proof of possessing one.
+ *
+ * THE STORED 2FA METHOD IS 'totp', NOT 'backup_code'. READ THIS BEFORE
+ * "CORRECTING" IT — it looks wrong and is not.
+ *
+ *   1. IT MATCHES THE IDP. MfaController 5g sets
+ *      `TwoFactorMethod = TwoFactorMethodType.Totp` for this exact path,
+ *      commented "Backup code = recovery proof of the TOTP factor", and the
+ *      reissued token's amr carries mfa+totp. A backup code is not a separate
+ *      factor; it is recovery proof of the authenticator factor.
+ *
+ *   2. INVENTING A NEW VALUE SILENTLY BREAKS TOKEN REFRESH. refresh.ts:279
+ *      resolves the method with ['sms','totp','email'].includes(m). Anything
+ *      outside that set is dropped, so `two_factor_method` never reaches the
+ *      IDP on refresh, and a session established with a recovery code refreshes
+ *      differently from one established with the authenticator — for the same
+ *      underlying factor. It fails quietly, days later, as "sessions
+ *      occasionally drop", with nothing pointing back to this string.
+ *
+ * The type union (email|sms|totp) is not the reason for the choice, it is a
+ * coincidence that caught it. Widening the union would have compiled and
+ * shipped the refresh bug.
+ *
+ * @package @payez/next-mvp
+ */
+
+import { NextRequest, NextResponse } from 'next/server';
+import { idpFetchJSON } from '../../lib/idp-fetch';
+import { ENV_CONFIG } from '../../config/env';
+import { getTokenTestAware } from '../../lib/test-aware-get-token';
+import { transitionTo2FASession } from '../../lib/session-store';
+import { jwtDecode } from '../../lib/jwt-decode';
+
+export async function POST(req: NextRequest) {
+  try {
+    const body = await req.json();
+    const code = body.code || body.backupCode || body.verificationCode || body.verification_code;
+
+    if (!code) {
+      return NextResponse.json(
+        {
+          success: false,
+          error: 'Backup code is required',
+          code: 'INVALID_REQUEST',
+        },
+        { status: 400 }
+      );
+    }
+
+    const result = await idpFetchJSON(
+      req,
+      `${ENV_CONFIG.IDP_URL}/api/ExternalAuth/twofa/backup-code/verify`,
+      {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ code }),
+      }
+    );
+
+    if (!result.ok) {
+      return NextResponse.json(
+        {
+          success: false,
+          error: result.json?.message || 'Verification failed',
+          code: result.json?.code || 'IDP_ERROR',
+          meta: { attemptedRefresh: result.attemptedRefresh },
+        },
+        { status: result.status }
+      );
+    }
+
+    const unwrappedData = result.json?.data || result.json;
+
+    // Only a challenge that returns fresh tokens may transition the session.
+    let sessionTransitioned = false;
+
+    if (unwrappedData.access_token && unwrappedData.refresh_token) {
+      const token = await getTokenTestAware(req);
+      const sessionToken = (token?.sessionToken || token?.redisSessionId) as string | undefined;
+
+      if (sessionToken) {
+        let accessTokenExpires = Date.now() + 15 * 60 * 1000;
+        try {
+          const decoded = jwtDecode<{ exp?: number }>(unwrappedData.access_token);
+          if (decoded?.exp) accessTokenExpires = decoded.exp * 1000;
+        } catch {
+          console.warn('[VERIFY_BACKUP_CODE] Could not decode access token, using default expiration');
+        }
+
+        let refreshTokenExpires = Date.now() + 3 * 24 * 60 * 60 * 1000;
+        try {
+          const decoded = jwtDecode<{ exp?: number }>(unwrappedData.refresh_token);
+          if (decoded?.exp) refreshTokenExpires = decoded.exp * 1000;
+        } catch {
+          // Refresh token may carry no exp claim; default stands.
+        }
+
+        await transitionTo2FASession(
+          sessionToken,
+          {
+            accessToken: unwrappedData.access_token,
+            refreshToken: unwrappedData.refresh_token,
+            accessTokenExpires,
+            refreshTokenExpires,
+          },
+          // 'totp' is deliberate and load-bearing. See "THE STORED 2FA METHOD"
+          // in the file header before changing it.
+          'totp'
+        );
+
+        sessionTransitioned = true;
+        console.log('[VERIFY_BACKUP_CODE] Session transitioned to 2FA-verified');
+      } else {
+        console.warn('[VERIFY_BACKUP_CODE] IDP accepted the code but no session token was resolvable — session NOT transitioned. THE CODE IS ALREADY SPENT.');
+      }
+    } else {
+      console.warn('[VERIFY_BACKUP_CODE] IDP returned 2xx without tokens — session NOT transitioned. THE CODE IS ALREADY SPENT.');
+    }
+
+    // twoFactorSessionVerified reports WHAT ACTUALLY HAPPENED, never a copy of
+    // `success`. It matters more here than anywhere else: the code is consumed
+    // the moment the IDP accepts it, so a client that trusted a hardcoded true
+    // would show the user as verified, leave the session unverified, and have
+    // burned one of their ten recovery codes to do it.
+    return NextResponse.json(
+      {
+        success: true,
+        verificationSuccessful: true,
+        twoFactorSessionVerified: sessionTransitioned,
+        codeConsumed: true,
+        message: unwrappedData.message || 'Backup code verified successfully',
+      },
+      { status: 200 }
+    );
+  } catch (error) {
+    console.error('[VERIFY_BACKUP_CODE] Error:', error);
+    return NextResponse.json(
+      {
+        success: false,
+        error: 'Failed to verify backup code',
+        code: 'INTERNAL_ERROR',
+      },
+      { status: 500 }
+    );
+  }
+}

package/src/api-handlers/mfa/backup-codes.ts

@@ -1,41 +1,41 @@
-import { NextRequest, NextResponse } from 'next/server';
-import { idpFetchJSON } from '../../lib/idp-fetch';
-import { ENV_CONFIG } from '../../config/env';
-
-/**
- * Generate MFA backup codes (POST /api/Account/mfa/backup-codes, user JWT).
- * Regeneration REPLACES the prior set — the response carries the new codes
- * once; they are shown once and never retrievable again.
- */
-export async function POST(req: NextRequest) {
-  let body = '{}';
-  try {
-    const raw = await req.text();
-    if (raw && raw.trim().length > 0) body = raw;
-  } catch {}
-
-  const result = await idpFetchJSON(req, `${ENV_CONFIG.IDP_URL}/api/Account/mfa/backup-codes`, {
-    method: 'POST',
-    headers: { 'Content-Type': 'application/json' },
-    body,
-  });
-
-  if (!result.ok) {
-    return NextResponse.json(
-      {
-        success: false,
-        message: 'Upstream error',
-        error: { code: 'UPSTREAM_SERVICE_ERROR', status: result.status, details: result.json },
-        meta: { attemptedRefresh: result.attemptedRefresh },
-      },
-      { status: result.status },
-    );
-  }
-
-  const bodyJson: any = result.json;
-  if (bodyJson && typeof bodyJson === 'object' && 'success' in bodyJson && 'data' in bodyJson) {
-    if (bodyJson.success === true) return NextResponse.json(bodyJson.data, { status: 200 });
-    return NextResponse.json(bodyJson, { status: 200 });
-  }
-  return NextResponse.json(bodyJson ?? {}, { status: 200 });
-}
+import { NextRequest, NextResponse } from 'next/server';
+import { idpFetchJSON } from '../../lib/idp-fetch';
+import { ENV_CONFIG } from '../../config/env';
+
+/**
+ * Generate MFA backup codes (POST /api/Account/mfa/backup-codes, user JWT).
+ * Regeneration REPLACES the prior set — the response carries the new codes
+ * once; they are shown once and never retrievable again.
+ */
+export async function POST(req: NextRequest) {
+  let body = '{}';
+  try {
+    const raw = await req.text();
+    if (raw && raw.trim().length > 0) body = raw;
+  } catch {}
+
+  const result = await idpFetchJSON(req, `${ENV_CONFIG.IDP_URL}/api/Account/mfa/backup-codes`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body,
+  });
+
+  if (!result.ok) {
+    return NextResponse.json(
+      {
+        success: false,
+        message: 'Upstream error',
+        error: { code: 'UPSTREAM_SERVICE_ERROR', status: result.status, details: result.json },
+        meta: { attemptedRefresh: result.attemptedRefresh },
+      },
+      { status: result.status },
+    );
+  }
+
+  const bodyJson: any = result.json;
+  if (bodyJson && typeof bodyJson === 'object' && 'success' in bodyJson && 'data' in bodyJson) {
+    if (bodyJson.success === true) return NextResponse.json(bodyJson.data, { status: 200 });
+    return NextResponse.json(bodyJson, { status: 200 });
+  }
+  return NextResponse.json(bodyJson ?? {}, { status: 200 });
+}