@payez/next-mvp 4.5.7 → 4.7.9

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

@@ -0,0 +1,858 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.POST = POST;
+/**
+ * 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").
+ */
+const server_1 = require("next/server");
+const jose_1 = require("jose");
+const idp_client_config_1 = require("../../lib/idp-client-config");
+const client_key_1 = require("../../lib/client-key");
+const session_store_1 = require("../../lib/session-store");
+const app_slug_1 = require("../../lib/app-slug");
+const crypto_1 = require("crypto");
+const device_id_1 = require("../../lib/device-id");
+const twofa_rejection_1 = require("../../lib/twofa-rejection");
+const bearer_fetch_1 = require("../../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) {
+    const supplied = req.headers.get(device_id_1.DEVICE_ID_HEADER);
+    if ((0, device_id_1.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 = (0, crypto_1.createHash)('sha256').update(`${ip}|${ua}`).digest('hex').slice(0, 32);
+    return `payez-PayEz-${digest}`;
+}
+function decodeJwtPayload(jwt) {
+    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) {
+    const decoded = decodeJwtPayload(jwt);
+    return typeof decoded?.exp === 'number' ? decoded.exp * 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) {
+    const { key } = (0, client_key_1.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) {
+    return sendLane === null ? ['totp'] : sendLane === 'sms' ? ['sms'] : ['email'];
+}
+async function POST(req) {
+    let body;
+    try {
+        body = await req.json();
+    }
+    catch {
+        return server_1.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 server_1.NextResponse.json({ success: false, error: 'Email is required' }, { status: 400 });
+    }
+    if (!password) {
+        return server_1.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;
+    try {
+        config = await (0, idp_client_config_1.getIDPClientConfig)();
+    }
+    catch (err) {
+        console.error('[ADMIN_LOGIN] IDP client config unavailable — returning 503:', err);
+        return server_1.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;
+    if (code) {
+        const provisional = req.cookies.get('adm2fa')?.value;
+        if (!provisional) {
+            return server_1.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 } },
+            sms: { path: 'twofa/sms/verify', body: { verification_code: code } },
+            email: { path: 'twofa/email/verify', body: { verification_code: code } },
+        };
+        const order = sentLane === 'sms' ? ['sms', 'totp'] : ['totp', 'email'];
+        const laneStatuses = [];
+        // PAY-903: each refused lane's body, so a TOTP `locked` answer is not lost behind a later lane.
+        const laneResults = [];
+        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 (0, bearer_fetch_1.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 server_1.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 = (0, twofa_rejection_1.classifyTwofaRejection)(laneResults, idpResponse.headers.get('retry-after'));
+            return server_1.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 = vresult?.access_token;
+        const vRefresh = vresult?.refresh_token;
+        if (!vAccess || !vRefresh) {
+            console.error('[ADMIN-LOGIN] verify response missing tokens', { hasAccess: !!vAccess, hasRefresh: !!vRefresh });
+            return server_1.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 = {
+        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_1.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 server_1.NextResponse.json({ success: false, error: 'Unable to reach the authentication service' }, { status: 503 });
+    }
+    const rawText = await idpResponse.text();
+    let data;
+    try {
+        data = JSON.parse(rawText);
+    }
+    catch {
+        console.error('[ADMIN-LOGIN] IDP returned non-JSON response', { status: idpResponse.status, body: rawText });
+        return server_1.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 server_1.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 server_1.NextResponse.json({ success: false, error: publicRefusalMessage(f) }, { status: idpResponse.status });
+    }
+    if (data?.success === false) {
+        const f = logIdpAuthRefusal('envelope-success-false', idpResponse.status, data);
+        return server_1.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 = result?.access_token;
+    const refreshToken = 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 = [];
+        if (accessToken) {
+            try {
+                const mResp = await (0, bearer_fetch_1.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.isArray(mJson)
+                        ? mJson
+                        : Array.isArray(mJson?.data)
+                            ? (mJson.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 = 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;
+        if (accessToken && sendLane) {
+            try {
+                const sendResp = await (0, bearer_fetch_1.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 = 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 = server_1.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 server_1.NextResponse.json({ success: false, error: 'Authentication service returned an incomplete response' }, { status: 502 });
+    }
+    return mintSession(accessToken, refreshToken, email, result, config);
+}
+/**
+ * 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) {
+    const d = (data ?? {});
+    const candidates = [
+        ['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, b) => 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) {
+    if (f.code && SAFE_TO_SHOW.has(f.code) && f.detail)
+        return f.detail;
+    return UNIFORM_REFUSAL;
+}
+function logIdpAuthRefusal(branch, httpStatus, data) {
+    const f = extractIdpFailure(data);
+    const d = (data ?? {});
+    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, refreshToken, email, result, config) {
+    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 : null;
+    const userRoles = Array.isArray(result?.user?.roles) && result.user.roles.length > 0
+        ? result.user.roles
+        : 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 (0, session_store_1.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 jose_1.SignJWT({ sessionToken })
+        .setProtectedHeader({ alg: 'HS256' })
+        .setIssuedAt()
+        .setExpirationTime(Math.floor(Date.now() / 1000) + session_store_1.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 = server_1.NextResponse.json({ success: true });
+    const cookieOpts = {
+        httpOnly: true,
+        secure: isProd,
+        sameSite: 'lax',
+        path: '/',
+        maxAge: session_store_1.SESSION_TTL,
+    };
+    response.cookies.set((0, app_slug_1.getSessionCookieName)(), jwt, cookieOpts);
+    if (isProd) {
+        response.cookies.set((0, app_slug_1.getSecureSessionCookieName)(), jwt, cookieOpts);
+    }
+    return response;
+}