@payez/next-mvp 4.5.6 → 4.7.9

package/src/api-handlers/auth/credential-login.ts

@@ -0,0 +1,948 @@
+/**
+ * PAY-2302 (cut 1): THIS HANDLER NOW LIVES IN @payez/next-mvp. It was written as an app-local route in
+ * VibeID-Customer-Portal (src/app/api/auth/admin-login/route.ts, card 238225) because the package had no credential sign-in:
+ * its Better Auth instance configures socialProviders only (no emailAndPassword) and createLoginHandler (api-handlers/auth/login.ts)
+ * proxies the IdP without writing a session. It moved here so a generated app (create-next-app) can sign a user in; the portal
+ * re-exports it. Where the history below says "the package", "app-local" or "the graft", read it as written BEFORE the move.
+ *
+ * Admin password sign-in — card 238225 stage-2.
+ *
+ * Deliberately NOT a better-auth flow: better-auth's own auth/better-auth.js
+ * only configures socialProviders (Google) - zero emailAndPassword - and
+ * BAPert's ruling (32776, re 32769) was explicit: keep the shared package
+ * untouched, land this as an app-local custom route instead. It talks to the
+ * IDP the same way @payez/next-mvp's createLoginHandler does
+ * (api-handlers/auth/login.js: POST {IDP_URL}/api/ExternalAuth/login), which
+ * is the exact endpoint QAPert's TOTP fixture already proved works (mail
+ * 32622). createLoginHandler itself was not reused here - its own doc
+ * comment says it normalizes "for NextAuth authorize()", a caller this
+ * better-auth-only package no longer has.
+ *
+ * Two-step, same shape testing/qa/H1-AUTH-MECHANISM-2026-07-31.md documents
+ * for the IDP: an access token with NO refresh token means 2FA is
+ * outstanding (refresh is deliberately withheld until the second factor
+ * clears). Step 1 (email+password) either finishes in one shot or comes back
+ * asking for a code; step 2 resubmits email+password+code together - the IDP
+ * endpoint accepts two_factor_code directly on the same login call, so this
+ * never needs the already-authenticated totp-verify/verify-code endpoints
+ * (those add a *second* factor to an existing session; this establishes the
+ * first one).
+ *
+ * Session write: this is the "legacy JWT + Redis" path decode-session.js
+ * still actively maintains as a fallback (see its 183047 rework, and
+ * session-cookie-shape.js's JWS branch) - not dead NextAuth-era code, just
+ * unused by anything else in the package because better-auth mints its own
+ * ba-hmac cookies for every OTHER sign-in path. Nothing else in the package
+ * currently WRITES this shape; this route is the one place that now does,
+ * by design (BAPert 32776: "custom route ... writes session via
+ * lib/session-store.js").
+ */
+import { NextRequest, NextResponse } from 'next/server';
+import { SignJWT } from 'jose';
+import { getIDPClientConfig } from '../../lib/idp-client-config';
+import { resolveClientKey } from '../../lib/client-key';
+import { createSession, SESSION_TTL } from '../../lib/session-store';
+import { getSessionCookieName, getSecureSessionCookieName } from '../../lib/app-slug';
+import { createHash } from 'crypto';
+import { DEVICE_ID_HEADER, isValidDeviceId } from '../../lib/device-id';
+import { classifyTwofaRejection, type TwofaLaneResult } from '../../lib/twofa-rejection';
+import { bearerFetch } from '../../lib/bearer-fetch';
+
+// `export const runtime = 'nodejs'` must be written LITERALLY in the app's route file (Next ignores a re-exported segment config).
+
+/**
+ * The device id to forward to the IDP for THIS caller — card 240566.
+ *
+ * Previously a single hardcoded constant was sent for everybody, so to the
+ * IDP's rate limiter the entire portal was one device: any attacker's failed
+ * attempts drained the throttle budget for every real user (shared-fate
+ * lockout), and per-device risk signals meant nothing.
+ *
+ * Order of preference:
+ *  1. The browser's own persisted id (src/lib/device-id.ts), sent as the
+ *     X-Device-Id header. Validated against the exact shape before it is
+ *     forwarded -- this value crosses the network from an untrusted client
+ *     and is interpolated into a Cookie header, so an unvalidated value
+ *     would let a caller inject arbitrary cookie content. The regex admits
+ *     only `payez-PayEz-<32 lowercase hex>`, which contains no delimiter
+ *     that could break out of the cookie.
+ *  2. A stable id DERIVED from the caller (IP + user-agent, hashed). This is
+ *     the no-JS / non-browser / storage-blocked path. It still separates
+ *     callers from each other, so shared-fate is closed even when the client
+ *     never presents an id -- which is the whole point of the card. It is
+ *     deliberately NOT the old global constant: falling back to that would
+ *     have quietly preserved the very bug this fixes for every such caller.
+ *
+ * This id is a throttling/telemetry key and NEVER a credential. It is
+ * client-influenced by design and grants nothing on its own; the IDP's
+ * identifier- and IP-scoped limits remain the real control.
+ */
+function resolveDeviceId(req: NextRequest): string {
+  const supplied = req.headers.get(DEVICE_ID_HEADER);
+  if (isValidDeviceId(supplied)) return supplied;
+
+  const ip =
+    req.headers.get('x-forwarded-for')?.split(',')[0]?.trim() ||
+    req.headers.get('x-real-ip') ||
+    'unknown-ip';
+  const ua = req.headers.get('user-agent') || 'unknown-ua';
+  const digest = createHash('sha256').update(`${ip}|${ua}`).digest('hex').slice(0, 32);
+  return `payez-PayEz-${digest}`;
+}
+
+interface AdminLoginBody {
+  email?: unknown;
+  password?: unknown;
+  code?: unknown;
+}
+
+function decodeJwtPayload(jwt: string): Record<string, unknown> | null {
+  try {
+    const payloadSegment = jwt.split('.')[1];
+    if (!payloadSegment) return null;
+    return JSON.parse(Buffer.from(payloadSegment, 'base64').toString('utf-8'));
+  } catch {
+    return null;
+  }
+}
+
+function decodeJwtExpiryMs(jwt: string): number | null {
+  const decoded = decodeJwtPayload(jwt);
+  return typeof decoded?.exp === 'number' ? (decoded.exp as number) * 1000 : null;
+}
+
+
+/**
+ * 268410: the routing key this door sends to the IDP.
+ *
+ * Was `String(config.clientId)` at five sites - NUMERIC-ONLY, no slug preference
+ * anywhere in the expression - on the AUTHENTICATION DOOR, which is the worst
+ * place in the codebase for the arm the IDP accepts with no existence check.
+ * Falls back to the numeric exactly as before, so no working deployment changes
+ * behaviour; the fallback is now logged and attributable.
+ *
+ * NOTE: the `idpClientId` field written into the session record below is NOT a
+ * routing key - it is a record of which client the session was minted against,
+ * it is read nowhere, and it is deliberately left as the numeric id.
+ */
+function clientKey(config: { clientSlug?: string | null; clientId?: string | number | null }): string {
+  const { key } = resolveClientKey(config, 'graft/admin-login');
+  return key ?? '';
+}
+
+/**
+ * PAY-2314: the factors the code step should tell the user about, by the lane the send turn chose.
+ *   null  (a TOTP holder: nothing was sent) -> ['totp']
+ *   'sms'                                 -> ['sms']
+ *   'email' (also: mfa/methods unreadable)  -> ['email']
+ * The VERIFY chain is unchanged (it still tries totp as the stateless companion lane); this is only what we ADVERTISE.
+ */
+function acceptedFactorsFor(sendLane: 'sms' | 'email' | null): readonly string[] {
+  return sendLane === null ? ['totp'] : sendLane === 'sms' ? ['sms'] : ['email'];
+}
+
+export async function POST(req: NextRequest) {
+  let body: AdminLoginBody;
+  try {
+    body = await req.json();
+  } catch {
+    return NextResponse.json({ success: false, error: 'Invalid JSON format' }, { status: 400 });
+  }
+
+  const email = typeof body.email === 'string' ? body.email.trim() : '';
+  const password = typeof body.password === 'string' ? body.password : '';
+  const code = typeof body.code === 'string' && body.code.trim() ? body.code.trim() : undefined;
+
+  if (!email) {
+    return NextResponse.json({ success: false, error: 'Email is required' }, { status: 400 });
+  }
+  if (!password) {
+    return NextResponse.json({ success: false, error: 'Password is required' }, { status: 400 });
+  }
+
+  // 244276: this call was OUTSIDE any try/catch. getIDPClientConfig() throws on a
+  // config-resolution failure - an empty authSecret, or the circuit breaker open with
+  // no cached config - and an unhandled throw in a route handler becomes an EMPTY 500.
+  // The sign-in card reads any non-2xx without a structured body as a failed attempt
+  // and shows "Could not sign in. Check your details".
+  //
+  // So an INFRASTRUCTURE OUTAGE was reported to the user as THEIR MISTAKE. That is the
+  // worst direction for this error to point: the one person who cannot fix it is told
+  // it is their fault, and the people who can fix it never hear about it, because a
+  // user who believes they mistyped a password retries instead of reporting.
+  //
+  // BAPert 2026-08-24 15:39:03Z: Jon hit an unhandled backend exception on this path.
+  // This card was filed "severity LOW - papered over once the graft re-seeds client 76".
+  // It was not papered over. It reached the person the product exists for.
+  //
+  // 503 + a structured body, deliberately: 503 is the honest status for "our dependency
+  // is down, this is not about your request", it is not cached, and the structured body
+  // is what lets the card tell an outage from a rejection at all.
+  let config: Awaited<ReturnType<typeof getIDPClientConfig>>;
+  try {
+    config = await getIDPClientConfig();
+  } catch (err) {
+    console.error('[ADMIN_LOGIN] IDP client config unavailable — returning 503:', err);
+    return NextResponse.json(
+      {
+        success: false,
+        error: 'Sign-in is temporarily unavailable. This is a problem on our side, not with your details. Please try again shortly.',
+        code: 'IDP_CONFIG_UNAVAILABLE',
+        retryable: true,
+      },
+      { status: 503 },
+    );
+  }
+
+  const idpUrl = `${process.env.IDP_URL}/api/ExternalAuth/login`;
+
+  // CODE STEP (240379 follow-through): verify the emailed code against the
+  // provisional bearer parked at the requiresTwoFactor turn. twofa/email/verify
+  // returns the FULL token pair (IssueRefreshToken=true after 2FA completion)
+  // - that response then rides the same session-mint tail as a direct login.
+  let idpResponse: Response;
+  if (code) {
+    const provisional = req.cookies.get('adm2fa')?.value;
+    if (!provisional) {
+      return NextResponse.json(
+        { success: false, error: 'Your verification window expired. Sign in again.' },
+        { status: 200 },
+      );
+    }
+    // DUAL-LANE VERIFY (both allowed_2fa_methods on client 12): a 6-digit
+    // code could be either lane, so try TOTP first (MfaController
+    // /api/ExternalAuth/twofa/totp/verify, body {code} - the endpoint
+    // DotNetPert proved end-to-end in 33513; local HMAC check, cheap), then
+    // fall back to the emailed code (twofa/email/verify,
+    // body {verification_code}). Both return the same flat
+    // Success({access_token, refresh_token}) envelope on step-up.
+    const verifyHeaders = {
+      'Content-Type': 'application/json',
+      Accept: 'application/json',
+      Authorization: `Bearer ${provisional}`,
+      'X-Client-Id': clientKey(config),
+    };
+    /**
+     * 267479 (verify half): the send half learned to fire twofa/sms/send for an
+     * SMS holder, but THIS chain still only tried totp then email - so the code
+     * we had just texted Jon was never offered to the verifier that could accept
+     * it, and he was told "That code is not right or has expired." The code was
+     * right. It was minted into the SMS store and nothing ever asked that store.
+     *
+     * twofa/sms/verify takes the SAME DTO as the email lane
+     * (ExternalAuthController.cs:3390 -> IdentityTwoFactorAuthRequest.VerificationCode,
+     * exactly like :3544) and is on the provisional allowlist beside sms/send
+     * (JwtMiddleware.cs:195). Backend was ready; only this call was missing.
+     *
+     * THE LANE SET IS RESTRICTED, NOT MERELY REORDERED - 268164, QAPert-NightHawk.
+     * My first cut of this appended sms to the end of the chain and broke only on
+     * SUCCESS, so every FAILED verify still fell through to twofa/sms/verify even
+     * for a user who holds no SMS factor. That is not free, because the SMS
+     * attempt counter is keyed on the PHONE NUMBER ALONE:
+     *
+     *   AcsSmsService.cs:227  GetCodeKey(phone) => $"sms_code_{phone}"   // no user, no client
+     *                :43     MaxAttempts = 5
+     *                :171-174 at the limit: TryRemove - a STILL-VALID code is DESTROYED
+     *
+     * So a wrong code from anyone sharing a phone number could burn down another
+     * user's good code and tell THEM "Too many incorrect attempts." Before this
+     * commit the door never called sms/verify at all, so appending it was a
+     * regression I introduced, not a pre-existing risk.
+     *
+     * Rule: NEVER probe a lane we did not send to. sms/verify fires only when the
+     * send turn actually texted this user (adm2fa_lane === 'sms'). TOTP is always
+     * safe to try - it is a stateless local HMAC with no stored entry and nothing
+     * to destroy - so it stays as the companion lane. Anything else, including a
+     * missing cookie from an older client, gets exactly the historic totp -> email
+     * chain, so this can never be worse than the behaviour it replaced.
+     */
+    const sentLane = req.cookies.get('adm2fa_lane')?.value;
+    const laneSpec = {
+      totp: { path: 'twofa/totp/verify', body: { code } as Record<string, string> },
+      sms: { path: 'twofa/sms/verify', body: { verification_code: code } as Record<string, string> },
+      email: { path: 'twofa/email/verify', body: { verification_code: code } as Record<string, string> },
+    } as const;
+    type VerifyLane = keyof typeof laneSpec;
+    const order: VerifyLane[] = sentLane === 'sms' ? ['sms', 'totp'] : ['totp', 'email'];
+    const laneStatuses: number[] = [];
+    // PAY-903: each refused lane's body, so a TOTP `locked` answer is not lost behind a later lane.
+    const laneResults: TwofaLaneResult[] = [];
+    try {
+      // Seeded so TS sees a definite assignment; the loop always runs at least once.
+      idpResponse = new Response(null, { status: 500 });
+      for (const lane of order) {
+        const spec = laneSpec[lane];
+        idpResponse = await bearerFetch(`${process.env.IDP_URL}/api/ExternalAuth/${spec.path}`, {
+          method: 'POST',
+          headers: verifyHeaders,
+          body: JSON.stringify(spec.body),
+        });
+        laneStatuses.push(idpResponse.status);
+        if (idpResponse.ok) break;
+        // PAY-1608: each lane keeps its own Retry-After, so a lockout states the LOCKED lane's window.
+        laneResults.push({ lane, status: idpResponse.status, body: await idpResponse.clone().text().catch(() => ''), retryAfter: idpResponse.headers.get('retry-after') });
+      }
+    } catch (error) {
+      console.error('[ADMIN-LOGIN] twofa verify fetch failed:', error instanceof Error ? error.message : String(error));
+      return NextResponse.json({ success: false, error: 'Unable to reach the authentication service' }, { status: 503 });
+    }
+    if (!idpResponse.ok) {
+      const txt = await idpResponse.text().catch(() => '');
+      console.warn('[ADMIN-LOGIN] twofa verify rejected', { statuses: laneStatuses, body: txt.slice(0, 200) });
+
+      /**
+       * 268121 FE-CONTRACT RULING (NextPert). DotNetPert's abc5ce27f asked for this
+       * ruling BEFORE merge and landed first, so this is the FE half arriving after
+       * the backend half - stated plainly rather than quietly.
+       *
+       * THIS BRANCH USED TO COLLAPSE EVERY NON-OK STATUS INTO "That code is not
+       * right or has expired." That was survivable while the backend answered 200
+       * for everything. It is NOT survivable now: 268121 makes a delivery/serverfault
+       * answer 502/500, so an INFRASTRUCTURE failure was being reported to the user
+       * as THEIR TYPING MISTAKE.
+       *
+       * That is the exact inversion DotNetPert refused to ship on his side - he
+       * declined to 502 the login family because it would turn "wrong code" into
+       * "server broken". This is the same error running the other way: "server
+       * broken" presented as "wrong code". Blaming a user for a server fault also
+       * costs them real attempts, because they will retype a code that was never
+       * the problem - and on this door attempts are a scarce, shared resource
+       * (268164: the SMS counter is keyed on PHONE NUMBER).
+       *
+       * AND 429 WAS THE WORST CASE. A rate-limit refusal read as "your code is
+       * wrong", so a locked-out user was told to try again - which, below
+       * threshold, SETS A FRESH 1-HOUR WINDOW (RateLimitingMiddleware: the tripped
+       * gate returns before the increment, but a sub-threshold failure re-arms).
+       * The FE was actively coaching users into extending their own lockout. That
+       * ambiguity cost this floor the morning of 2026-08-26.
+       *
+       * Classification is by the MOST BLOCKING status seen across lanes, not the
+       * last one: with order=[sms,totp] a 429 on lane 1 and a 400 on lane 2 must
+       * report the 429, or the loop hides the thing the user most needs to know.
+       */
+      // PAY-903: the same ordering, now in src/lib/auth/twofa-rejection.ts, plus the IdP `locked` code
+      // (MfaController.VerifyTotp answers a 15-minute lockout as 400 {code:"locked"}), which status-only
+      // classification told to "try again".
+      const rejection = classifyTwofaRejection(laneResults, idpResponse.headers.get('retry-after'));
+      return NextResponse.json(
+        {
+          success: false,
+          error: rejection.error,
+          ...(rejection.retryAfter !== undefined ? { retryAfter: rejection.retryAfter } : {}),
+          // PAY-2284: the card shows a real "email me a code" action only when this is true.
+          ...(rejection.offerEmailCode ? { offerEmailCode: true } : {}),
+        },
+        { status: rejection.status },
+      );
+    }
+    const verifyData = await idpResponse.json().catch(() => null);
+    // Success helper wraps flat: {success, data:{access_token, refresh_token, ...}}
+    // (no `.result` nesting on this endpoint - measured shape).
+    const vresult = verifyData?.data?.result ?? verifyData?.data ?? verifyData;
+    const vAccess: string | undefined = vresult?.access_token;
+    const vRefresh: string | undefined = vresult?.refresh_token;
+    if (!vAccess || !vRefresh) {
+      console.error('[ADMIN-LOGIN] verify response missing tokens', { hasAccess: !!vAccess, hasRefresh: !!vRefresh });
+      return NextResponse.json({ success: false, error: 'Authentication service returned an incomplete response' }, { status: 502 });
+    }
+    const out = await mintSession(vAccess, vRefresh, email, vresult, config);
+    out.cookies.set('adm2fa', '', { path: '/', maxAge: 0 });
+    out.cookies.set('adm2fa_lane', '', { path: '/', maxAge: 0 });
+    return out;
+  }
+
+  const idpPayload: Record<string, unknown> = {
+    username_or_email: email,
+    password,
+    client_id: clientKey(config),
+    client_type: 'partner',
+  };
+  try {
+    idpResponse = await fetch(idpUrl, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        Accept: 'application/json',
+        // 240566: per-CALLER device id, not the one hardcoded constant every
+        // portal user used to share. Same cookie name and shape
+        // createLoginHandler forwards, so the IDP contract is unchanged --
+        // only the value is now distinct per browser. See resolveDeviceId.
+        Cookie: `${DEVICE_ID_HEADER}=${resolveDeviceId(req)}`,
+      },
+      body: JSON.stringify(idpPayload),
+    });
+  } catch (error) {
+    console.error('[ADMIN-LOGIN] IDP fetch failed:', error instanceof Error ? error.message : String(error));
+    return NextResponse.json({ success: false, error: 'Unable to reach the authentication service' }, { status: 503 });
+  }
+
+  const rawText = await idpResponse.text();
+  let data: any;
+  try {
+    data = JSON.parse(rawText);
+  } catch {
+    console.error('[ADMIN-LOGIN] IDP returned non-JSON response', { status: idpResponse.status, body: rawText });
+    return NextResponse.json({ success: false, error: 'Invalid response from the authentication service' }, { status: 502 });
+  }
+
+  if (idpResponse.status === 429) {
+    const retryAfter = idpResponse.headers.get('retry-after');
+    return NextResponse.json(
+      { success: false, error: 'Too many attempts. Please try again later.', retryAfter: retryAfter ? parseInt(retryAfter, 10) : 60 },
+      { status: 429 }
+    );
+  }
+
+  if (!idpResponse.ok) {
+    const f = logIdpAuthRefusal('non-ok', idpResponse.status, data);
+    return NextResponse.json({ success: false, error: publicRefusalMessage(f) }, { status: idpResponse.status });
+  }
+
+  if (data?.success === false) {
+    const f = logIdpAuthRefusal('envelope-success-false', idpResponse.status, data);
+    return NextResponse.json({ success: false, error: publicRefusalMessage(f) }, { status: 200 });
+  }
+
+  // Unwrap the IDP's canonical envelope, same shape login.js normalizes.
+  const result = data?.data?.result ?? data?.result ?? data;
+  const accessToken: string | undefined = result?.access_token;
+  const refreshToken: string | undefined = result?.refresh_token;
+
+  // 2FA outstanding: access issued, refresh deliberately withheld. The
+  // H1-AUTH doc's "two_factor_code accepted on the same login call" shape
+  // DOES NOT EXIST on this IDP build - measured 2026-08-23 (240379/:4702):
+  // TwoFactorCode appears nowhere in External.Id.Api's login path. The real
+  // step-up contract is: login -> PROVISIONAL bearer (access, no refresh) ->
+  // POST twofa/email/send (Bearer provisional) -> emailed code ->
+  // POST twofa/email/verify {code} (Bearer provisional) -> FULL token pair.
+  // So: fire the email send NOW, park the provisional token in a short-lived
+  // httpOnly cookie, and let the code step verify against it (branch above).
+  const requiresTwoFactor = result?.two_factor_required === true || (!!accessToken && !refreshToken);
+  if (requiresTwoFactor) {
+    let emailSent = false;
+    /**
+     * 267479: WHICH FACTOR DOES THIS USER ACTUALLY HOLD?
+     *
+     * This door used to fire twofa/email/send at EVERYONE. That is wrong in two
+     * separate ways and Jon hit both:
+     *   - he holds sms(confirmed) and NO usable TOTP (measured on the live 93 DB,
+     *     DotNetPert mail 37564), and the deployed build CAN send it - AcsSmsService
+     *     + twofa/sms/send are live at d873cea44 - but this file has never had an
+     *     SMS branch at all, so his own factor was unreachable from the sign-in door;
+     *   - a TOTP holder gets a mail they never needed, because TOTP has nothing to
+     *     send (there is no twofa/totp/send BY DESIGN - DotNetPert).
+     *
+     * /api/Account/mfa/methods IS on the IDP's provisional allowlist
+     * (JwtMiddleware._mfaPendingAllowedPaths), as are twofa/sms/send and
+     * twofa/email/send - so the provisional bearer we already hold is enough to ask
+     * the question and then act on the answer.
+     *
+     * FAIL-SAFE: any failure, timeout or unreadable body leaves `usable` empty and
+     * we fall through to EMAIL, which is exactly the old behaviour. This can only
+     * add a correct SMS/TOTP branch; it cannot take away the lane that worked.
+     *
+     * KNOWN LIMIT, stated so nobody reads more into this than it does: mfa/methods
+     * reads user_mfa_methods ONLY. A TOTP factor living in the legacy
+     * user_client_security_settings.authenticator_key store is invisible here (266652)
+     * and such a user falls to email - again, the old behaviour, so no regression.
+     * There are currently ZERO legacy keys on 93, so that class is empty today.
+     */
+    let usableFactors: string[] = [];
+    if (accessToken) {
+      try {
+        const mResp = await bearerFetch(`${process.env.IDP_URL}/api/Account/mfa/methods`, {
+          method: 'GET',
+          headers: {
+            Accept: 'application/json',
+            Authorization: `Bearer ${accessToken}`,
+            'X-Client-Id': clientKey(config),
+          },
+        });
+        if (mResp.ok) {
+          const mJson = await mResp.json().catch(() => null);
+          const rows: Array<Record<string, unknown>> = Array.isArray(mJson)
+            ? mJson
+            : Array.isArray((mJson as { data?: unknown })?.data)
+              ? ((mJson as { data: Array<Record<string, unknown>> }).data)
+              : [];
+          usableFactors = rows
+            // confirmed_at REQUIRED - the endpoint returns PENDING enrolments too, and a
+            // started-but-never-finished QR scan is not a factor you can challenge against.
+            .filter((r) => !!r.confirmed_at && !r.revoked_at)
+            .map((r) => String(r.method ?? '').toLowerCase());
+        } else {
+          console.warn('[ADMIN-LOGIN] mfa/methods unreadable, defaulting to email lane', mResp.status);
+        }
+      } catch (err) {
+        console.warn('[ADMIN-LOGIN] mfa/methods fetch failed, defaulting to email lane:', err instanceof Error ? err.message : String(err));
+      }
+    }
+    // PAY-2314: advertise what this user can actually use, derived from the SAME usableFactors that chose the lane
+    // (a fixed ['totp','email'] told a user with no authenticator to use one). An unreadable mfa/methods leaves
+    // usableFactors empty, which already chose the email lane -> ['email'].
+    // TOTP wins when present: there is nothing to send, so sending anything is noise.
+    // Otherwise send the code for the factor they actually hold.
+    const sendLane: 'sms' | 'email' | null = usableFactors.includes('totp')
+      ? null
+      : usableFactors.includes('sms')
+        ? 'sms'
+        : 'email';
+    /**
+     * 262392 on the SIGN-IN DOOR: the dev code echo exists, Jon asked for it by
+     * name ("i need the code to come back from the send request for dev
+     * testing"), and it is wired into /account-auth/verify-code - but NOT here,
+     * on the door he actually signs in through. This route threw the send body
+     * away entirely, reading only `sendResp.ok`.
+     *
+     * WHY THAT MATTERS MORE THAN A CONVENIENCE: ExternalAuthController.cs:3341
+     * attaches the echo REGARDLESS of response.Success, and says why - "the ACS
+     * send fails while the toll-free number is unverified, so gating the echo on
+     * a successful send would mean it never fires". Meanwhile ACS answers 202 =
+     * ACCEPTED, not delivered, and there are ZERO EventGrid subscriptions, so
+     * NOTHING in this system can observe whether the text actually arrived
+     * (DotNetPert-Scout, 268492).
+     *
+     * So on a dev rig the echo is not a nicety - it is the ONLY path to the code
+     * when delivery silently fails, and this door was dropping it.
+     *
+     * NO FRONTEND GATE, DELIBERATELY. The backend emits the field ONLY under
+     * IsDevelopment() && Sms:DevCodeEcho, and the DTO is
+     * [JsonIgnore(WhenWritingNull)] so a CLOSED GATE EMITS NO FIELD AT ALL.
+     * Absence IS the contract. A second FE-side flag could drift out of step with
+     * the server and show a UI that believes itself disabled while the server
+     * echoes - the exact two-gates defect class this codebase spent today
+     * chasing. We forward strictly what the server chose to send.
+     */
+    let devCode: string | undefined;
+    if (accessToken && sendLane) {
+      try {
+        const sendResp = await bearerFetch(`${process.env.IDP_URL}/api/ExternalAuth/twofa/${sendLane}/send`, {
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+            Accept: 'application/json',
+            Authorization: `Bearer ${accessToken}`,
+            'X-Client-Id': clientKey(config),
+          },
+          body: JSON.stringify({ client_id: clientKey(config) }),
+        });
+        emailSent = sendResp.ok;
+        // The body can only be consumed ONCE, and we now need it on BOTH paths -
+        // the failure log and the echo - so read it here rather than in a branch.
+        const sendBody = await sendResp.text().catch(() => '');
+        if (!sendResp.ok) {
+          console.error(`[ADMIN-LOGIN] twofa/${sendLane}/send failed`, sendResp.status, sendBody.slice(0, 200));
+        }
+        // Shape-tolerant on purpose: the standardized envelope nests as {data:{result}}
+        // on some routes and {data} on others. Betting on one shape would render
+        // nothing on the others, and a silent nothing is indistinguishable from
+        // "echo is off" - precisely the ambiguity this display exists to remove.
+        try {
+          const j: any = JSON.parse(sendBody);
+          const echoed =
+            j?.dev_verification_code ??
+            j?.data?.dev_verification_code ??
+            j?.data?.result?.dev_verification_code ??
+            j?.result?.dev_verification_code;
+          if (typeof echoed === 'string' && echoed) devCode = echoed;
+        } catch {
+          // not JSON - nothing to echo, and never a reason to fail the sign-in
+        }
+      } catch (err) {
+        console.error(`[ADMIN-LOGIN] twofa/${sendLane}/send fetch failed:`, err instanceof Error ? err.message : String(err));
+      }
+    }
+    // 267479: `method:'email'` WAS A HARDCODED LITERAL HERE, and it was a lie for
+    // every user whose factor was not email. It also threw away the backend's own
+    // answer: the IDP computes the right factor (256768 / MfaFactorPolicy) and
+    // returns `next_step`, which this file read ZERO times.
+    //
+    // Report what actually happened instead of asserting a method:
+    //   sentVia         which lane we ACTUALLY fired, or null for a TOTP holder
+    //                   (nothing to send). Drives the copy on the card.
+    //   codeRequested   the send's own ok. NOT a delivery receipt - per 267561
+    //                   twofa/email/send returns 200 even when the SMTP send threw,
+    //                   so this means "we asked for a code", never "one arrived".
+    //                   Any copy built on it must survive that. `emailSent` is kept
+    //                   as an alias purely so an older client does not break.
+    //   acceptedFactors what the VERIFY lane will actually TRY for this user, and
+    //                   it is now lane-dependent rather than fixed: an SMS holder
+    //                   gets sms+totp, everyone else gets the historic totp+email.
+    //                   It is deliberately NOT the union - probing a lane we did
+    //                   not send to spends someone's attempt counter (268164).
+    const resp = NextResponse.json(
+      {
+        success: false,
+        requiresTwoFactor: true,
+        acceptedFactors: acceptedFactorsFor(sendLane),
+        sentVia: sendLane,
+        codeRequested: emailSent,
+        emailSent,
+        // Present ONLY when the server chose to echo (dev rigs). Absence is the
+        // contract - see the block above; do not add a second gate for it.
+        ...(devCode ? { devVerificationCode: devCode } : {}),
+        nextStep: result?.next_step ?? null,
+      },
+      { status: 200 },
+    );
+    if (accessToken) {
+      resp.cookies.set('adm2fa', accessToken, {
+        httpOnly: true,
+        secure: process.env.NODE_ENV === 'production',
+        sameSite: 'lax',
+        path: '/',
+        maxAge: 600, // matches the emailed code's usefulness window
+      });
+      // 267479: remember WHICH lane we fired. The verify turn is a separate
+      // request that would otherwise have to guess, and every wrong guess spends
+      // one of the user's remaining attempts. A TOTP holder has no send, so the
+      // lane is recorded as 'totp' and that is what gets tried first.
+      resp.cookies.set('adm2fa_lane', sendLane ?? 'totp', {
+        httpOnly: true,
+        secure: process.env.NODE_ENV === 'production',
+        sameSite: 'lax',
+        path: '/',
+        maxAge: 600,
+      });
+    }
+    return resp;
+  }
+
+  if (!accessToken || !refreshToken) {
+    console.error('[ADMIN-LOGIN] IDP success response missing tokens', { hasAccess: !!accessToken, hasRefresh: !!refreshToken });
+    return NextResponse.json({ success: false, error: 'Authentication service returned an incomplete response' }, { status: 502 });
+  }
+
+  return mintSession(accessToken, refreshToken, email, result, config);
+}
+
+/**
+ * WHY THIS EXISTS: the IDP TELLS US why it refused, and we were throwing it away.
+ *
+ * ExternalAuthController's login failure envelope is TWO-LAYER, and the two layers carry
+ * very different amounts of information:
+ *
+ *   top level   Message = "Authentication failed"        <- generic, identical for every cause
+ *   errors[0]   Code / Message / Resolution / FieldName  <- THE ACTUAL REASON
+ *
+ * Both relay branches below read only `data?.message`, i.e. the generic layer, and dropped
+ * `errors[0]` on the floor. So a refusal for SsoRequired, InvalidRequest, AccountLocked,
+ * EmailNotConfirmed, PasswordChangeRequired or a genuinely wrong password all presented to
+ * an operator as the SAME six words, with nothing written anywhere to tell them apart.
+ *
+ * That is the 268410 defect in a different costume: two materially different causes made
+ * INDISTINGUISHABLE at the boundary. It cost the floor a morning on 2026-08-26 - a shut door
+ * at :4793 that could not be attributed to a credential, a config, or a policy, because the
+ * one artifact that knew the answer was discarded in this function.
+ *
+ * *** THE REASON IS LOGGED, NOT RETURNED, AND THAT ASYMMETRY IS DELIBERATE. ***
+ *
+ * AuthErrorCode has UserNotFound AND InvalidCredentials as SEPARATE values
+ * (PayEz.DTOs/Models/Token/Internal/AuthErrorCode.cs). Returning the code to the browser
+ * would let an unauthenticated caller tell "no such account" from "wrong password" - a user
+ * ENUMERATION oracle on the sign-in door. AccountLocked and EmailNotConfirmed leak existence
+ * the same way. The generic top-level message is doing real security work, so the client
+ * response below is UNCHANGED and must stay that way.
+ *
+ * The server log is the correct place: operators can read it, the browser cannot. If a future
+ * change wants a code in the response, it needs a per-code allowlist argued on enumeration
+ * grounds - not a blanket passthrough.
+ */
+type IdpFailure = {
+  code: string | null;
+  detail: string | null;
+  resolution: string | null;
+  fieldName: string | null;
+  shape: string;
+};
+
+/**
+ * 270725 (QAPert): THE REASON IS NOT WHERE I ASSUMED, AND MY FIRST FIX READ THE WRONG FIELD.
+ *
+ * 0019b66 read `data.errors[0]`, which is the shape ExternalTokenResponse serializes on the
+ * Ok() path. QAPert MEASURED the live 400 and it arrives as
+ * `error.details.errors[0].message`. Different path, different wrapper - so my diagnostic
+ * would have logged nulls forever and looked like "the IDP said nothing", which is EXACTLY
+ * the quietly-failing diagnostic my own comment warned about one commit earlier.
+ *
+ * So this probes BOTH shapes and RECORDS WHICH ONE MATCHED. If the envelope moves again the
+ * log says `shape: none` instead of silently reporting no reason - the failure is visible.
+ */
+function extractIdpFailure(data: unknown): IdpFailure {
+  const d = (data ?? {}) as Record<string, any>;
+  const candidates: Array<[string, any]> = [
+    ['error.details.errors[0]', d?.error?.details?.errors?.[0]],
+    ['errors[0]', Array.isArray(d?.errors) ? d.errors[0] : undefined],
+    ['error.details', d?.error?.details],
+    ['error', typeof d?.error === 'object' ? d.error : undefined],
+  ];
+  for (const [shape, cand] of candidates) {
+    if (cand && typeof cand === 'object') {
+      const pick = (a: string, b: string) => cand[a] ?? cand[b] ?? null;
+      const code = pick('code', 'Code');
+      const detail = pick('message', 'Message');
+      if (code || detail) {
+        return {
+          code: code == null ? null : String(code),
+          detail: detail == null ? null : String(detail),
+          resolution: pick('resolution', 'Resolution'),
+          fieldName: pick('fieldName', 'FieldName'),
+          shape,
+        };
+      }
+    }
+  }
+  return { code: null, detail: null, resolution: null, fieldName: null, shape: 'none' };
+}
+
+/**
+ * WHICH CODES MAY BE SHOWN TO AN UNAUTHENTICATED CALLER. ALLOWLIST, DEFAULT-DENY.
+ *
+ * 270725 asks to surface `error.code` so the card can tell a lockout from a rejection.
+ * I am NOT doing that, and the card's OWN NULL CONTROL is the reason: it measured a
+ * nonexistent user returning `error.code = UserNotFound`. Surfacing the code therefore
+ * separates "no such account" from "wrong password" from "this account is locked" - a user
+ * ENUMERATION ORACLE on the sign-in door, reachable with no credential. AccountLocked leaks
+ * existence just as hard: a lockout only EXISTS for a real account.
+ *
+ * These codes leak nothing about whether an account exists, so they may be shown:
+ *   SsoRequired / SsoRequiredBreakGlass - a property of the EMAIL DOMAIN's connection, not of
+ *     any account, and the user cannot proceed without being told.
+ *   InvalidRequest - a property of the request the caller just made.
+ */
+const SAFE_TO_SHOW = new Set(['SsoRequired', 'SsoRequiredBreakGlass', 'InvalidRequest']);
+
+/**
+ * THE UNIFORM REFUSAL. One string for typo, unknown account, and lockout alike.
+ *
+ * 270725's real harm is NOT that the user is under-informed - it is that the copy INVITES A
+ * RETRY. THE NUMBERS IN THIS PARAGRAPH WERE WRONG UNTIL 2026-09-03 AND THE CORRECTION IS
+ * WORTH MORE THAN THE ORIGINAL CLAIM, so it is recorded rather than quietly edited:
+ *
+ *   IT SAID: "a sub-threshold retry SETS A FRESH ONE-HOUR WINDOW".
+ *   MEASURED (PayEz.External.Id.Api/Helper/ServiceCollectionExtension.cs:66-68):
+ *       MaxFailedAccessAttempts = 5
+ *       DefaultLockoutTimeSpan  = TimeSpan.FromMinutes(15)      <- FIFTEEN MINUTES, NOT SIXTY
+ *   AND a sub-threshold failure sets NO window at all: UserValidationService.cs:209 calls
+ *   AccessFailedAsync(), which INCREMENTS a counter; the window is armed only when the count
+ *   reaches 5. So the original sentence was wrong on the duration (4x) and on the mechanism.
+ *
+ * WHAT IS STILL TRUE, AND WHY THE COPY BELOW DOES NOT CHANGE: repeated wrong passwords DO
+ * block sign-in, and "wait a few minutes" is ACCURATE for 15 minutes - it would have been
+ * actively misleading for 60. The copy was right while its own justification was not.
+ *
+ * ALSO MEASURED, and it bounds the harm further: AccessFailedAsync fires ONLY on
+ * !passwordValid (UserValidationService.cs:205-209), so a user retrying with the CORRECT
+ * password does not increment anything. The counter only moves on genuinely wrong passwords.
+ *
+ * NOT DRIVEN, DO NOT CITE AS FACT (BAPert R480): whether five FURTHER wrong passwords during
+ * an ALREADY-ACTIVE lockout move LockoutEnd. The password path increments before it checks
+ * the lock (unlike the TOTP path, MfaTotpService.cs:193-199, which returns BEFORE the
+ * increment and is therefore inert on retry), so it is a strong prediction from ordering plus
+ * stock Identity semantics - not a measurement. The check is five deliberate failures, then
+ * five more during the lockout, watching whether LockoutEnd moves.
+ *
+ * That harm can be fixed WITHOUT an oracle: warn about the cost of retrying in the copy shown
+ * for EVERY failure. A message that is identical across all three causes cannot discriminate
+ * between them, so it tells an attacker nothing - while telling a real
+ * user the one thing that actually protects them.
+ */
+const UNIFORM_REFUSAL =
+  'We could not sign you in. Check your email and password. ' +
+  'If you have already tried a few times, wait a few minutes before trying again - ' +
+  'repeated attempts temporarily block sign-in, even with the right password.';
+
+/**
+ * Pick what the BROWSER is allowed to see. The full reason always goes to the log.
+ */
+function publicRefusalMessage(f: IdpFailure): string {
+  if (f.code && SAFE_TO_SHOW.has(f.code) && f.detail) return f.detail;
+  return UNIFORM_REFUSAL;
+}
+
+function logIdpAuthRefusal(branch: string, httpStatus: number, data: unknown): IdpFailure {
+  const f = extractIdpFailure(data);
+  const d = (data ?? {}) as Record<string, unknown>;
+  console.error('[ADMIN-LOGIN] IDP REFUSED SIGN-IN - specific reason follows (not sent to the browser: enumeration)', {
+    branch,
+    httpStatus,
+    envelopeMessage: d.message ?? (typeof d.error === 'string' ? d.error : null) ?? null,
+    code: f.code,
+    detail: f.detail,
+    resolution: f.resolution,
+    fieldName: f.fieldName,
+    shape: f.shape,
+    shownToUser: publicRefusalMessage(f) === UNIFORM_REFUSAL ? 'UNIFORM (cause withheld)' : 'code-specific (allowlisted)',
+  });
+  return f;
+}
+
+/**
+ * Session-mint tail, shared by the direct-login success path and the
+ * twofa/email/verify step-up path (240379 email-2FA lane): claims-seeded
+ * roles/userId, createSession, JWS cookie under both names in prod.
+ */
+async function mintSession(
+  accessToken: string,
+  refreshToken: string,
+  email: string,
+  result: any,
+  config: { clientId: string | number; authSecret: string },
+): Promise<NextResponse> {
+  const accessTokenExpires = decodeJwtExpiryMs(accessToken) ?? Date.now() + 15 * 60 * 1000;
+
+  // 240379 tier-2 fix — the IDP login envelope carries NO top-level `roles`
+  // or `user_id` (measured live against idp.payez.net, 2026-08-23): identity
+  // lives in the ACCESS TOKEN's claims (roles, user_id) and partially under
+  // `result.user` (user_name, roles). The old `result?.roles ?? []` mapping
+  // therefore seeded EVERY session with roles:[] and userId=email — so
+  // check-admin-role's hasAdminRole([]) denied even payez_admin holders and
+  // the admin console 307'd to /sign-in?error=SessionInvalid with the
+  // session freshly minted (measured: persona 903 with payez_admin in its
+  // JWT, session record roles:[] in redis-keelauth).
+  //
+  // The JWT came to us DIRECTLY from the IDP over TLS in this same response
+  // — decoding its claims here trusts exactly what storing its tokens
+  // already trusts; no client-supplied value is involved.
+  const claims = decodeJwtPayload(accessToken);
+  const claimRoles = Array.isArray(claims?.roles) ? (claims!.roles as string[]) : null;
+  const userRoles = Array.isArray(result?.user?.roles) && result.user.roles.length > 0
+    ? (result.user.roles as string[])
+    : null;
+
+  // 388680: the MFA expiry that BOUNDS mfaVerified/twoFactorComplete below.
+  // Normalised here rather than inline so the conversion is done exactly once
+  // and every rejected shape is visible in one place.
+  //
+  //   Number(...)     the claim arrives as a JSON STRING ("1789345863") on all
+  //                   38 live records; SessionData.mfaExpiresAt is typed number.
+  //   * 1000          every read site compares against Date.now() in MILLISECONDS
+  //                   (routes/auth/viability.ts, api-handlers/session/viability.ts,
+  //                   server/auth-guard.ts, all `n > 0 && n < Date.now()`).
+  //                   Writing raw SECONDS is the one shape that is actively
+  //                   dangerous in the other direction: a positive number far in
+  //                   the past reads as EXPIRED and fails closed on every login.
+  //   > 0 && finite   rejects the degenerate shapes so the field is OMITTED
+  //                   rather than written as a meaningless number:
+  //                   undefined/"abc" -> NaN, null/"" -> 0.
+  //                   Be precise about why, because it is NOT that these fail
+  //                   closed - MEASURED at all four read sites, `n > 0` is false
+  //                   for both NaN and 0, so either one reads as NEVER-EXPIRES,
+  //                   exactly like an absent field. They fail OPEN. Omitting is
+  //                   therefore behaviourally identical to writing them, and is
+  //                   preferred because it does not put a meaningless value in a
+  //                   security field, and because a stored NaN passes the
+  //                   `!== undefined` style check that 393082 is about.
+  //
+  // *** DO NOT "TIDY" THIS BACK TO MATCH THE OTHER WRITER. THE DEVIATION IS THE POINT. ***
+// (Written when this handler lived in the portal and "upstream" meant the package's session-store; the portal's copy is now
+// this file, and the weaker guard named below is the one still in lib/session-store.ts.)
+  // The upstream writer in @payez/next-mvp (dist/lib/session-store.js:358) guards
+  // this same field with `!== undefined && !== null`. That is WEAKER and it is
+  // weaker in the exact way this guard exists to prevent: it admits PRESENT-BUT-
+  // MALFORMED claims - mfa_expires:"abc", "", "1789345863x" - which pass the null
+  // check, hit Number(...) and store NaN in a security field. Matching upstream
+  // here would propagate that hole for the sake of symmetry. Ruled deliberate by
+  // BAPert 2026-09-12 (mail 53814): the stated purpose of the `!= null` shape was
+  // to never write NaN, and it does not achieve that; `Number.isFinite` does.
+  // The same hole on the package's own paths is filed as a finding on 393082 and
+  // is NOT fixed here.
+  const mfaExpiresSec = Number(claims?.mfa_expires);
+  const mfaExpiresAtMs =
+    Number.isFinite(mfaExpiresSec) && mfaExpiresSec > 0 ? mfaExpiresSec * 1000 : null;
+
+  const sessionToken = await createSession({
+    userId: String(claims?.user_id ?? result?.user_id ?? result?.userId ?? email),
+    email,
+    name: result?.user?.user_name ?? result?.name ?? result?.full_name,
+    idpAccessToken: accessToken,
+    idpRefreshToken: refreshToken,
+    idpAccessTokenExpires: accessTokenExpires,
+    // Reached only once the IDP has handed back a refresh token, i.e. no 2FA
+    // outstanding for this login - same "no tokens => no transition" posture
+    // totp-verify.js uses for the second-factor case.
+    //
+    // 388680: these two were written WITHOUT the expiry that bounds them. The
+    // constraint is present in the token - claims.mfa_expires, decoded above -
+    // and was being discarded, so a session stayed fully trusted for its whole
+    // TTL (~71h) after its MFA had expired. Measured live 2026-09-12: 20 of 38
+    // records had mfa_expires in the past while still carrying mfaVerified:true,
+    // each with ~35h of TTL left. Never drop a constraint the token carries.
+    mfaVerified: true,
+    twoFactorComplete: true,
+    ...(mfaExpiresAtMs !== null ? { mfaExpiresAt: mfaExpiresAtMs } : {}),
+    roles: claimRoles ?? userRoles ?? result?.roles ?? [],
+    idpClientId: String(config.clientId),
+  });
+
+  const secret = new TextEncoder().encode(config.authSecret);
+  const jwt = await new SignJWT({ sessionToken })
+    .setProtectedHeader({ alg: 'HS256' })
+    .setIssuedAt()
+    .setExpirationTime(Math.floor(Date.now() / 1000) + SESSION_TTL)
+    .sign(secret);
+
+  const isProd = process.env.NODE_ENV === 'production';
+
+  // 240379 PROD FIX — write the session under BOTH cookie names in production.
+  //
+  // The package's own read contract (app-slug.ts getJwtCookieName) says prod
+  // readers use the __Secure- name — but server/auth.ts's
+  // extractSessionTokenFromCookie (the Path-B fallback that resolves THIS
+  // route's legacy JWS sessions, and the only reader the viability route
+  // reaches for them) calls getSessionCookieName() and NEVER checks the
+  // __Secure- variant. Measured live on portal.keelauth.com: sign-in 200,
+  // record present in Redis (idp_admin_ui_graft:sess:{token}), and
+  // /api/session/viability still answered "No session found" — the minted
+  // session was invisible to every gate, so pages bounced back to /sign-in.
+  // On 93-dev NODE_ENV made writer and reader agree, which is why 238225's
+  // walk passed there and prod died.
+  //
+  // The reader-side fix is one line in the package (use getJwtCookieName());
+  // that is an MVP release (channel-drift 208574 caution).
+  //
+  // Set BOTH names. Every reader combination is covered (Path B reads the base
+  // name; SessionSync/signout/middleware handle the secure one; the graft
+  // middleware checks both), and both carry the same JWS so there is no
+  // divergence to reconcile. Signout/deny paths already clear both names.
+  //
+  // *** DO NOT RETIRE THIS DUAL-WRITE WHEN THE READER FIX SHIPS. ***
+  //
+  // An earlier version of this comment said "until then", which reads as a
+  // licence to drop one name as soon as the package reader is fixed. It is
+  // not, and that inference is the whole hazard — so it is corrected here.
+  // Shipping the reader is NOT the precondition; REDEPLOYING EVERY CONSUMER
+  // is. The reader fix is strictly additive (it looks at MORE names), so it
+  // can land alone, in either order, with no change to this file.
+  //
+  // The four cells (card 245246, governing analysis):
+  //   old reader (base only) + BOTH written    -> finds base       WORKS (today)
+  //   fixed reader (both)    + BOTH written    -> finds __Secure-  WORKS
+  //   fixed reader (both)    + base only       -> falls to base    WORKS
+  //   old reader (base only) + __Secure- ONLY  -> finds NOTHING    BREAKS
+  //
+  // Exactly one cell breaks, and retiring this dual-write is the ONLY path
+  // into it. Retirement requires all three, verified not assumed (card
+  // 245283): (1) the fixed reader PUBLISHED, not merely committed; (2) EVERY
+  // consumer repinned AND redeployed, checked against the artifact that runs
+  // (dist/ in the image, not src/); (3) a sign-in walked on a prod-shaped
+  // surface confirming the __Secure- name resolves.
+  //
+  // Enforced by qa/dual-write-retirement-gate.sh (wired into `npm run
+  // qa:static`), so deleting either write below fails CI loudly instead of
+  // failing silently in production at sign-in. Retire the gate in the same
+  // change as the dual-write, never before it.
+  const response = NextResponse.json({ success: true });
+  const cookieOpts = {
+    httpOnly: true,
+    secure: isProd,
+    sameSite: 'lax' as const,
+    path: '/',
+    maxAge: SESSION_TTL,
+  };
+  response.cookies.set(getSessionCookieName(), jwt, cookieOpts);
+  if (isProd) {
+    response.cookies.set(getSecureSessionCookieName(), jwt, cookieOpts);
+  }
+  return response;
+}