@payez/next-mvp 4.1.14 → 4.1.21

package/src/api-handlers/auth/passkey-signin.ts

@@ -0,0 +1,98 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { ENV_CONFIG } from '../../config/env';
+import { getIDPClientConfig } from '../../lib/idp-client-config';
+
+/**
+ * Passkey SIGN-IN ceremony (ANONYMOUS — no session exists yet):
+ *   optionsPOST -> POST /api/ExternalAuth/passwordless/passkey/options
+ *   verifyPOST  -> POST /api/ExternalAuth/passwordless/passkey/verify
+ *
+ * Anon idiom copied from auth/better-auth.ts (exchangeOAuthForIdpTokens):
+ * direct fetch to the IDP, client identified by client_id from the resolved
+ * IDP client config (slug preferred, numeric id fallback) — sent BOTH as the
+ * X-Client-Id header (the probe-verified routing key) and merged into the
+ * body when the caller did not supply one.
+ *
+ * The verify response is passed through WITHOUT unwrapping: this is a
+ * sign-in, its payload carries the grant the caller's session layer consumes.
+ */
+
+async function clientKey(): Promise<string> {
+  const config = await getIDPClientConfig();
+  return config.clientSlug || String(config.clientId);
+}
+
+async function anonCall(req: NextRequest, path: string) {
+  let parsed: Record<string, unknown> = {};
+  try {
+    const raw = await req.text();
+    if (raw && raw.trim().length > 0) parsed = JSON.parse(raw);
+  } catch {}
+
+  const key = await clientKey();
+  const res = await fetch(`${ENV_CONFIG.IDP_URL}${path}`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json', 'X-Client-Id': key },
+    body: JSON.stringify({ client_id: key, ...parsed }),
+    cache: 'no-store',
+  });
+  const json = await res.json().catch(() => null);
+  return { res, json };
+}
+
+export async function optionsPOST(req: NextRequest) {
+  const { res, json } = await anonCall(req, '/api/ExternalAuth/passwordless/passkey/options');
+  return NextResponse.json(json ?? { success: false, message: 'Empty upstream response' }, { status: res.status });
+}
+
+/**
+ * VERIFY DOES NOT USE anonCall — IT MUST RESHAPE, NOT SPREAD.
+ *
+ * The IDP contract is three fields (PasskeyModels.cs:36 PasskeyAuthVerifyRequest):
+ *     assertion_id : string
+ *     response     : the WHOLE AuthenticatorAssertionRawResponse from
+ *                    navigator.credentials.get()
+ *     client_id    : string
+ *
+ * anonCall SPREADS the caller's body (`{ client_id, ...parsed }`). For options
+ * that is harmless. For verify it is fatal: spreading an assertion hoists
+ * id/rawId/type to the top level and leaves `response` holding only the INNER
+ * {clientDataJSON, authenticatorData, signature, userHandle}. The IDP's guard
+ * then answers "response is required" in 4-12ms WITHOUT REACHING THE CRYPTO —
+ * a timing signature DotNetPert used to prove the caller was still spreading
+ * long after the graft-side plugin had been fixed.
+ *
+ * This route and the Better Auth plugin endpoint are TWO PATHS to the same IDP
+ * endpoint. Fixing only the plugin left this one live, spreading, and reachable
+ * on a URL one segment away from the correct one — which is what kept the
+ * sign-in leg red across several runs.
+ *
+ * Accepts the assertion either already nested (`{ assertion_id, response }`) or
+ * flat (`{ assertion_id, id, rawId, type, response }`) and normalises both, so a
+ * caller written against either shape works.
+ */
+export async function verifyPOST(req: NextRequest) {
+  let parsed: Record<string, unknown> = {};
+  try {
+    const raw = await req.text();
+    if (raw && raw.trim().length > 0) parsed = JSON.parse(raw);
+  } catch { /* empty body -> the IDP's own validation answers */ }
+
+  const { assertion_id: assertionId, response, ...rest } = parsed;
+
+  // Already-nested callers send `response` holding a full assertion (it has an
+  // `id`). Flat callers send the assertion's own fields alongside assertion_id,
+  // and their `response` is the inner attestation half — not a whole assertion.
+  const nested = response && typeof response === 'object' && 'id' in (response as object);
+  const assertion = nested ? response : { ...rest, response };
+
+  const key = await clientKey();
+  const res = await fetch(`${ENV_CONFIG.IDP_URL}/api/ExternalAuth/passwordless/passkey/verify`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json', 'X-Client-Id': key },
+    body: JSON.stringify({ client_id: key, assertion_id: assertionId, response: assertion }),
+    cache: 'no-store',
+  });
+  const json = await res.json().catch(() => null);
+  return NextResponse.json(json ?? { success: false, message: 'Empty upstream response' }, { status: res.status });
+}

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

@@ -400,7 +400,7 @@ export function createRefreshHandler(config: RefreshConfig) {
           const errorMessage = idpError.message || 'Token refresh failed';
           // CRITICAL: 401 means token is definitively invalid - always discard
           // This prevents redirect loops where viability check keeps returning canRefresh:true
-          const discardToken = refreshResponse.status === 401 || idpError.discard_token === true;
+          let discardToken = refreshResponse.status === 401 || idpError.discard_token === true;
           const retryable = refreshResponse.status !== 401 && idpError.retryable === true;
           const resolution = idpError.resolution || null;
 
@@ -442,20 +442,43 @@ export function createRefreshHandler(config: RefreshConfig) {
 
           // If IDP signals to discard token, clear it from Redis
           if (discardToken) {
-            console.error('[AUTH_REFRESH] ⚠️ REFRESH_TOKEN_REMOVAL: IDP signaled discard_token', {
-              reason: 'IDP_DISCARD_TOKEN',
-              errorCode,
-              userId,
-              sessionToken: sessionToken.substring(0, 8) + '...',
-              hadRefreshToken: !!currentSession.idpRefreshToken,
-              stack: new Error().stack
-            });
-            await updateSession(sessionToken, {
-              idpRefreshToken: '',
-              idpRefreshTokenExpires: undefined,
-              refreshTokenClearedAt: Date.now(),
-              refreshTokenClearedReason: `IDP_DISCARD_TOKEN:${errorCode}`
-            });
+            // Race-safe discard (CAS): only clear if the refresh token we sent is STILL
+            // the current one. A concurrent refresh may have already rotated it — our 401
+            // is then stale, and wiping here would silently log out a healthy session
+            // (the rotation-race wipe, QA 6873 site 2). Skip the wipe + drop terminal if changed.
+            const postRefresh = await getSession(sessionToken);
+            const tokenUnchanged =
+              !!originalRefreshToken && postRefresh?.idpRefreshToken === originalRefreshToken;
+            if (tokenUnchanged) {
+              console.error('[AUTH_REFRESH] ⚠️ REFRESH_TOKEN_REMOVAL: IDP signaled discard_token', {
+                reason: 'IDP_DISCARD_TOKEN',
+                errorCode,
+                userId,
+                sessionToken: sessionToken.substring(0, 8) + '...',
+                hadRefreshToken: !!currentSession.idpRefreshToken,
+                stack: new Error().stack
+              });
+              await updateSession(sessionToken, {
+                idpRefreshToken: '',
+                idpRefreshTokenExpires: undefined,
+                refreshTokenClearedAt: Date.now(),
+                refreshTokenClearedReason: `IDP_DISCARD_TOKEN:${errorCode}`
+              });
+            } else {
+              // Concurrent refresh already rotated the token — our 401 is stale. Return the
+              // freshly-rotated token directly so the loser succeeds without a retry
+              // (race-fix follow-up #1).
+              discardToken = false;
+              console.warn('[AUTH_REFRESH] Discard suppressed: refresh token already rotated by a concurrent refresh — returning the fresh token (race-safe).');
+              if (postRefresh?.idpAccessToken && postRefresh.idpAccessTokenExpires) {
+                return NextResponse.json({
+                  refreshed: true,
+                  reason: 'completed_by_concurrent_request',
+                  accessTokenExpires: postRefresh.idpAccessTokenExpires,
+                  hasRefreshToken: !!postRefresh.idpRefreshToken,
+                });
+              }
+            }
           }
 
           return NextResponse.json({

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

@@ -0,0 +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 }
+    );
+  }
+}

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

@@ -0,0 +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 });
+}

package/src/api-handlers/mfa/methods.ts

@@ -0,0 +1,46 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { idpFetchJSON } from '../../lib/idp-fetch';
+import { ENV_CONFIG } from '../../config/env';
+
+/**
+ * MFA methods (GET list / DELETE one, /api/Account/mfa/methods[/{id}],
+ * user JWT). Drives the method picker: an EMPTY list must route the user to
+ * ENROLMENT, never to a verify screen for a factor they do not hold.
+ */
+
+function upstreamError(result: { status: number; json: unknown; attemptedRefresh: boolean }) {
+  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 },
+  );
+}
+
+function passthrough(json: unknown) {
+  const bodyJson: any = json;
+  if (bodyJson && typeof bodyJson === 'object' && 'success' in bodyJson && 'data' in bodyJson) {
+    if (bodyJson.success === true) return NextResponse.json(bodyJson.data ?? { success: true }, { status: 200 });
+    return NextResponse.json(bodyJson, { status: 200 });
+  }
+  return NextResponse.json(bodyJson ?? { success: true }, { status: 200 });
+}
+
+export async function GET(req: NextRequest) {
+  const result = await idpFetchJSON(req, `${ENV_CONFIG.IDP_URL}/api/Account/mfa/methods`, { method: 'GET' });
+  if (!result.ok) return upstreamError(result);
+  return passthrough(result.json);
+}
+
+export async function DELETE(req: NextRequest, id: string) {
+  const result = await idpFetchJSON(
+    req,
+    `${ENV_CONFIG.IDP_URL}/api/Account/mfa/methods/${encodeURIComponent(id)}`,
+    { method: 'DELETE' },
+  );
+  if (!result.ok) return upstreamError(result);
+  return passthrough(result.json);
+}

package/src/api-handlers/mfa/totp-confirm.ts

@@ -0,0 +1,42 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { idpFetchJSON } from '../../lib/idp-fetch';
+import { ENV_CONFIG } from '../../config/env';
+
+/**
+ * Confirm TOTP enrolment with the first authenticator code
+ * (POST /api/Account/mfa/totp/confirm, user JWT). Body forwarded verbatim —
+ * it carries the enrolment handle plus the code. Only after this succeeds is
+ * the method ACTIVE.
+ */
+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/totp/confirm`, {
+    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 });
+}

package/src/api-handlers/mfa/totp-enroll.ts

@@ -0,0 +1,42 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { idpFetchJSON } from '../../lib/idp-fetch';
+import { ENV_CONFIG } from '../../config/env';
+
+/**
+ * Begin TOTP enrolment (POST /api/Account/mfa/totp/enroll, user JWT).
+ * Returns the shared secret / otpauth URI for the QR. An enrolment left
+ * UNCONFIRMED is pending — it can only be RESTARTED, and must never render
+ * as "Active" (MFA honesty fixes, 2026-08-01).
+ */
+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/totp/enroll`, {
+    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 });
+}

package/src/api-handlers/mfa/totp-verify.ts

@@ -0,0 +1,156 @@
+/**
+ * Verify TOTP 2FA Challenge Handler
+ *
+ * Verifies an authenticator-app code AT LOGIN and completes the 2FA flow,
+ * transitioning the session to MFA-verified.
+ *
+ * WHY THIS EXISTS (2026-08-02)
+ * The package shipped TOTP ENROLMENT (totp-enroll, totp-confirm, against
+ * /api/Account/mfa/totp/*) but no TOTP CHALLENGE. SMS and email both had one
+ * (verify-sms, verify-email, against /api/ExternalAuth/twofa/*), so TOTP could
+ * be enrolled and then never used to satisfy a login challenge — mfaVerified
+ * stayed false forever for authenticator-app users, even though the IDP
+ * advertises totp in allowed2FAMethods and exposes the endpoint.
+ *
+ * DO NOT "FIX" THIS BY MAKING totp-confirm TRANSITION THE SESSION. Three people
+ * proposed exactly that on the grounds that its SMS/email "siblings" do it. They
+ * are not siblings: totp-confirm is ENROLMENT. Flipping mfaVerified there would
+ * mean enrolling a factor counts as passing a challenge, letting a
+ * password-only session self-promote to MFA-verified by adding an
+ * authenticator. Enrolment must never set mfaVerified.
+ *
+ * FIELD NAME: the IDP expects { "code": ... } here
+ * (MfaTotpVerifyRequest, [JsonPropertyName("code")]), NOT the
+ * { "verification_code": ... } that the SMS endpoint takes. Copying verify-sms
+ * and changing only the URL produces a handler that reaches the IDP and is
+ * rejected, which reads as "wrong code" rather than "wrong shape".
+ *
+ * @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();
+    // Accept the same aliases the client might send; the IDP field is `code`.
+    const code = body.code || body.totpCode || body.verificationCode || body.verification_code;
+
+    if (!code) {
+      return NextResponse.json(
+        {
+          success: false,
+          error: 'Authenticator code is required',
+          code: 'INVALID_REQUEST',
+        },
+        { status: 400 }
+      );
+    }
+
+    // idpFetchJSON injects the caller's Bearer from the session store.
+    const result = await idpFetchJSON(
+      req,
+      `${ENV_CONFIG.IDP_URL}/api/ExternalAuth/twofa/totp/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 }
+      );
+    }
+
+    // Unwrap IDP envelope { success, data }
+    const unwrappedData = result.json?.data || result.json;
+
+    // Only a successful challenge that returns fresh tokens may transition the
+    // session. No tokens => no transition: we must not mark 2FA complete on the
+    // strength of a 200 alone.
+    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_TOTP] 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' // 2FA method, used by the refresh-token flow
+        );
+
+        sessionTransitioned = true;
+        console.log('[VERIFY_TOTP] Session transitioned to 2FA-verified');
+      } else {
+        console.warn('[VERIFY_TOTP] IDP verified the code but no session token was resolvable — session NOT transitioned');
+      }
+    } else {
+      console.warn('[VERIFY_TOTP] IDP returned 2xx without tokens — session NOT transitioned');
+    }
+
+    // Do not expose tokens to the client.
+    //
+    // twoFactorSessionVerified REPORTS WHAT ACTUALLY HAPPENED. It is NOT a copy
+    // of `success`. The code can verify at the IDP while the session is not
+    // transitioned — no tokens returned, or no resolvable session token — and a
+    // client that trusted a hardcoded `true` would show the user as MFA-verified
+    // while the session still says otherwise. That divergence between the guard
+    // and the report is the defect this field exists to avoid.
+    // (verify-sms.ts hardcodes it true and has the same flaw — reported upstream.)
+    return NextResponse.json(
+      {
+        success: true,
+        verificationSuccessful: true,
+        twoFactorSessionVerified: sessionTransitioned,
+        message: unwrappedData.message || 'Authenticator code verified successfully',
+      },
+      { status: 200 }
+    );
+  } catch (error) {
+    console.error('[VERIFY_TOTP] Error:', error);
+    return NextResponse.json(
+      {
+        success: false,
+        error: 'Failed to verify code',
+        code: 'INTERNAL_ERROR',
+      },
+      { status: 500 }
+    );
+  }
+}