@payez/next-mvp 4.13.0 → 4.14.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog — @payez/next-mvp
 
+## 4.14.0 (to be published under dist-tag `next` only, after 4.13.1; `latest` stays 4.8.9 until Jon says otherwise)
+
+A minor: additive exports, plus one behaviour change in the generated-app credential sign-in (listed first). Built from GitHub `keelsecurity/keelauth-next` main `33c188e0`; this release commit changes only this file and the version. Consumers keep their own pins.
+
+- **CHANGE (PAY-3083 / PAY-2938, AUTH-045): a first sign-in on an app with no authenticator now reaches enrolment instead of failing.** When the second-factor step answers with an access token and no refresh token, `api-handlers/auth/credential-login` no longer answers 502. It answers 200 in both cases below, never mints a session, and never echoes or logs the token. **(1) The IdP says `next_step: 'enroll_mfa'` (the enrolment-scoped answer after a verified email code, and the default when the IdP names no step):** the answer is `{ success: false, requiresTwoFactor: true, nextStep: 'enroll_mfa', enrolmentRequired: true }`, parks the token in an httpOnly cookie `payez_enrol` (SameSite=Strict, path `/`, 600 s) that only the two new routes below read; it expires the `adm2fa` and `adm2fa_lane` cookies. **(2) The IdP says `next_step: 'mfa_verify'`:** the answer passes that step through as `nextStep: 'mfa_verify'` with NO `enrolmentRequired` flag, NO `payez_enrol` cookie, and the `adm2fa` and `adm2fa_lane` cookies are left in place (the sign-in form continues at the code step). A refresh-only or empty success is still a 502. TOTP enrolment is per client (per app), by design.
+- **ADDITIVE: new exports** `./routes/mfa/first-enrol-enroll` and `./routes/mfa/first-enrol-confirm` (POST routes that read ONLY the `payez_enrol` cookie, accept JSON only, answer 401 `SIGN_IN_AGAIN` with no cookie, allow 5 attempts per cookie (the 6th is 429 and clears it), and on confirm return the recovery codes and clear the cookie; no session is minted), and `./dist/pages/first-enroll` (the page: QR, the key as selectable text under "Enter this code manually:", a sentence saying the authenticator is for this app only, the recovery codes, then "sign in again").
+- **ADDITIVE: `CredentialSignInForm` takes an optional `firstEnrolHref`**, and `credential-sign-in-client` has a new result kind `enrol_required` (returned only when the answer carries `enrolmentRequired: true` with `nextStep: 'enroll_mfa'`). With the prop set the form navigates there; **without it the form shows "This app has no authenticator setup page, so sign-in cannot continue. Tell the app owner." and does not loop.** A consumer that does not adopt it sees that sentence instead of the old silent loop. Generated apps from `@payez/cli` mount the routes and page and pass the prop (CLI release follows this one).
+- Tests: `test/credential-login.test.cjs`, `credential-sign-in-client.test.cjs`, `first-enrol-core.test.cjs`, `first-enrol-routes.test.cjs`, `first-enrol-panel.test.cjs` (with in-memory mutants, `test/lib/compile-mutant.cjs`).
+
+**Also in this release (additive, BAPert 88395/88454):**
+
+- **ADDITIVE (MINOR when released): SMS-first sign-up learns the `EMAIL_CONFIRMATION_REQUIRED` step (BAPert 88395 #2, 88454 #3; NextPert 88471).** The server (door 3b) now answers `verify-sms-code` with 200 success, `next_step = EMAIL_CONFIRMATION_REQUIRED` and NO reset token when the email is still unconfirmed. Before this, `accountApi.verifyOnboardingSmsCode` returned `{ success: true, resetToken: '' }` for that answer, which a consumer reads as "verified" and then calls set-password with an EMPTY token. Now: (a) the result type is the exported `SmsCodeVerification` and gains an OPTIONAL `nextStep` (`nextStep` ALONE is read from the nested shapes AND from a flat body; `reset_token`, `email` and `client_key` are still read from the nested shapes only, as before, so a consumer behind a proxy that forwards a flat body gets no token and the helper then says `more_steps`, the safe direction; absent / null / '' = no step; any other value, including `false`, `0` and a non-string, is kept as a non-empty UNRECOGNISED string, never dropped, so a server that means "no step" must send nothing or null); (b) new pure `interpretSmsVerification(result)` returns `verified` (only with a non-empty reset token and no step), `email_confirmation_required` (the package sentence "Your phone is verified. Confirm your email to finish signing up.", no error styling), `more_steps` ("One more step is needed to finish signing up." for ANY other step, and for success with an empty reset token) or `not_verified`; `success: false` WINS over any step (`not_verified`, so a failed answer never says "Your phone is verified"), and for every other answer it tests `nextStep` BEFORE the token; the sentences are the package's own, never the server's text. **The method itself still returns the server's `success` unchanged: a consumer MUST use `interpretSmsVerification` (or test `nextStep` first) and must not treat `success` alone as "verified", because `success: true` with an empty `resetToken` is what the server now sends for the unconfirmed-email case.** No breaking type change: a consumer that ignores `nextStep` compiles unchanged (test S6), and the email variant `verifyOnboardingCode` is untouched. **A consumer must adopt `interpretSmsVerification` (or branch on `nextStep` itself) to show the new screen; until it does, it behaves as before.** There is no SMS-first page in this package: the screen lives in the consuming sites, so the deploy of the server change (PR 85) waits on every live consumer taking this release. Tests: `test/sms-next-step.test.cjs` (32), `test/sms-next-step-mutants.test.cjs` (9 hand mutants, one per branch).
+
+## 4.13.1 (to be published under dist-tag `next` only, after 4.13.0; `latest` stays 4.8.9 until Jon says otherwise)
+
+A patch: ONE change, the PAY-2994 no-store fix for 8 GET routes (re-cut on GitHub from DevOps PR 1757, BAPert 92969; the DevOps repo is frozen).
+
+- **FIX (PAY-2994): eight GET routes now answer `Cache-Control: no-store` on every response.** The portal's BFF no-store ratchet found that these re-exported routes sent no Cache-Control, though their answers carry per-user data and some carry tokens, so a browser or an intermediate cache could keep them. New internal `lib/no-store` (`noStore(handler)`): it sets `no-store` on whatever the handler returns (errors and redirects too), REPLACES a looser existing value, rebuilds a Response whose headers are immutable (e.g. `Response.redirect`) with status, body and every `Set-Cookie` intact, passes the handler's arguments through, and hands a non-Response back untouched. Wrapped: `api-handlers/account/profile` GET, `api-handlers/anon/preferences` GET, `auth/better-auth` `createAuthGetHandler`, `routes/auth/session` GET, `routes/mfa/methods` GET, `routes/passkeys/list` GET, `routes/session/refresh-viability` GET, `routes/auth/viability` GET; and, as the same data under a second export path (NightHawk 92964 Low 1), `api-handlers/session/viability` GET and `api-handlers/session/refresh-viability` GET. No other behaviour changes. Package test `test/next-mvp-pay-2994-no-store.test.cjs` calls the REAL compiled GET of each and a mutant (wrapper removed) goes red.
+- **NOT covered (follow-up, so the next ratchet run is expected, NightHawk 92964 Low 2):** GET answers in `api-handlers/auth/status`, `api-handlers/auth/validate`, `routes/auth/session-reset`, `routes/auth/settings` and `api-handlers/oauth/resume` (a redirect that sets cookies) still send no `no-store`. They were not in the ratchet's finding.
+
 ## 4.13.0 (2026-11-05; published under dist-tag `next` only, after 4.12.1; `latest` stays 4.8.9 until Jon says otherwise)
 
 A minor. Numbered 4.13.0 because everything new is additive or opt-in and no export was removed (two exports were added: `./components/mfa/TotpEnrollPanel` and `./dist/pages/enroll`), but three changes alter behaviour for every consumer and are listed first so nobody is surprised. Built from GitHub `keelsecurity/keelauth-next` main (the code is e0ccb0b9; this release commit changes only this file and the version). Base: 4.12.1 (PR 1500 only). PR numbers are the GitHub-era numbers where the PR was opened after the cutover, else the ADO number. Consumers keep their own pins: nothing here bumps or pins any consumer, and the portal stays on 4.12.1 until its owner says otherwise.
@@ -42,6 +62,7 @@ Not covered: Safari/Firefox (Chromium only), non-browser clients and browsers th
 
 ## Earlier entries now rolled into 4.13.0 (previously "Unreleased: PAY-2568 / PAY-2279, draft PR; no release, no pin")
 
+
 - **CHANGE: a failed credential sign-in shows a fixed sentence chosen by a stable code, never the server text.** `lib/sign-in-failure` is one closed table: `invalid_credentials` ("Incorrect email or password.", wrong password, unknown account and any other refusal, identical), `not_a_member` (the IdP code `NotAMemberOfThisApp` at any HTTP status - the public door relays it as 400 - shown only to someone who proved the credentials), `too_many_attempts` (429, `AccountLocked`, `UserLockedOut`, one sentence for all). `/api/auth/admin-login` now answers `code` + the fixed sentence in `error`; the browser client takes the sentence from the table by code and ignores the body text (an unmapped refusal gets one generic sentence, `sign_in_failed`). Each rendered error carries `data-error-code` (form and login page). Allowlisted policy refusals (SsoRequired, InvalidRequest) still show their detail under code `policy_message`, as a plain text node, at most 200 characters (BAPert 85432); no other server text reaches the page. **What changes for a caller:** the 429 sentence and the `?error=CredentialsSignin` sentence changed; a custom UI that read `body.error` still gets a fixed sentence there. Rows: `test/signin-failure-copy.test.cjs` S1-S7 (RED on master, six mutants).
 - **FIX: the code step of a credential sign-in (wrong, unavailable, locked) shows its own sentence again (BAPert 85795).** The code-step branch of `api-handlers/auth/credential-login` sent no `code`, so after the change above every second-factor refusal fell to the generic "Could not sign in. Check your details and try again.", including the "problem on our side, not with your code" answer. The branch now sends `invalid_second_factor` ("That code is not correct. Check the code and try again."), `second_factor_unavailable` (the existing our-side sentence, with the Email-me-a-code offer kept) or `too_many_attempts`, chosen by the existing `classifyTwofaRejection` and never from IdP wording. The lockout sentence now states the window: `Too many sign-in attempts. Try again in N minutes, or reset your password.`, N = the server's `retryAfter` (seconds) rounded up to whole minutes and clamped to 1..60; with no usable number it stays the plain sentence (only a number is ever printed). The password-step 429 no longer invents a `retryAfter` of 60 when the IdP sent no Retry-After. A plain IdP 429 on the code step (a lane rate limit, not a `locked` lockout) has its own code `second_factor_rate_limited`: "Too many attempts. Try again in N minutes." (same N rule; plain fallback "Too many attempts. Wait a few minutes and try again."), so it no longer tells a user to reset their password; it makes no claim that the code is still valid (unproven here), and `twofa-rejection` no longer invents a 60 s `retryAfter`. Sentences lost by the 1719 regression in this lane: the wrong-code sentence, the our-side-fault sentence (with its Email-me-a-code offer text) and the lockout window. Test: `test/second-factor-copy.test.cjs` (T1-T15, mutants RED).
 

package/dist/api-handlers/account/profile.d.ts

@@ -1,41 +1,4 @@
 import { NextRequest, NextResponse } from 'next/server';
-/**
- * Account Profile API Handler
- *
- * GET /api/account/profile  - Get user profile
- * PUT /api/account/profile  - Update user profile
- *
- * WHY THIS WAS REWRITTEN (2026-08-02, QAPert defect #7)
- * Reported as "/api/account/profile 401s on the same cookie masked-info
- * accepts (200)". Two endpoints disagreeing about one cookie meant two auth
- * implementations, and they were:
- *
- *   masked-info.ts  idpFetchJSON(req, ...)           resolves the caller's token
- *                                                    from the server-side session
- *   profile.ts      req.headers.get('authorization') required an INBOUND bearer
- *
- * A browser sends a session COOKIE and no Authorization header, so the old
- * profile.ts 401'd EVERY browser request by construction. Nothing was revoked
- * and no token was stale — the handler demanded a credential the app does not
- * use.
- *
- * THE OLD AUTH CHECK WAS A VENEER. It tested that the header was PRESENT, never
- * that it was valid, then forwarded it upstream unexamined. Any string at all
- * got past it and the IDP did the real work. It looked like enforcement and
- * enforced nothing.
- *
- * WHAT THE WORKAROUND COST US: consumers could not call this with a cookie, so
- * the graft's useProfile hook fetched the raw IDP access token from
- * /api/session/idp-token INTO BROWSER JAVASCRIPT and re-sent it as a bearer.
- * That defeats the reason idpFetchJSON exists — it keeps the token server-side
- * precisely so client-side script can never hold it. The bearer-only handler
- * did not merely fail; it pushed its callers into exposing the token.
- *
- * Switching to idpFetchJSON makes the cookie work, so the hook's token round
- * trip can be deleted and /api/session/idp-token drops to a single deliberate
- * caller: the jwt-inspect debug page.
- *
- * @package @payez/next-mvp
- */
-export declare function GET(req: NextRequest): Promise<NextResponse<any>>;
+/** PAY-2994: the profile is one person's data; never cached (noStore). */
+export declare const GET: (req: NextRequest) => Promise<Response>;
 export declare function PUT(req: NextRequest): Promise<NextResponse<any>>;

package/dist/api-handlers/account/profile.js

@@ -1,10 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.GET = GET;
+exports.GET = void 0;
 exports.PUT = PUT;
 const server_1 = require("next/server");
 const idp_fetch_1 = require("../../lib/idp-fetch");
 const env_1 = require("../../config/env");
+const no_store_1 = require("../../lib/no-store");
 /**
  * Account Profile API Handler
  *
@@ -43,7 +44,7 @@ const env_1 = require("../../config/env");
  *
  * @package @payez/next-mvp
  */
-async function GET(req) {
+async function getProfile(req) {
     const result = await (0, idp_fetch_1.idpFetchJSON)(req, `${env_1.ENV_CONFIG.IDP_URL}/api/Account/profile`, {
         method: 'GET',
         headers: { 'Content-Type': 'application/json' },
@@ -61,6 +62,8 @@ async function GET(req) {
     }
     return server_1.NextResponse.json(result.json, { status: 200 });
 }
+/** PAY-2994: the profile is one person's data; never cached (noStore). */
+exports.GET = (0, no_store_1.noStore)(getProfile);
 async function PUT(req) {
     let body = '{}';
     try {

package/dist/api-handlers/anon/preferences.d.ts

@@ -8,23 +8,10 @@
  */
 import { NextRequest, NextResponse } from 'next/server';
 import { AnonSessionPreferences } from '../../lib/anon-session';
-/**
- * GET handler - retrieves anonymous session preferences
- */
-export declare function GET(request: NextRequest): Promise<NextResponse<{
-    success: boolean;
-    data: {
-        id: string;
-        preferences: AnonSessionPreferences;
-        metrics: import("../../lib/anon-session").AnonSessionMetrics;
-    };
-}> | NextResponse<{
-    success: boolean;
-    error: string;
-}>>;
 /**
  * POST handler - updates anonymous session preferences
  */
+export declare const GET: (request: NextRequest) => Promise<Response>;
 export declare function POST(request: NextRequest): Promise<NextResponse<{
     success: boolean;
     error: string;

package/dist/api-handlers/anon/preferences.js

@@ -8,17 +8,16 @@
  * Sets a cookie to track anonymous visitors and stores preferences in Redis.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.GET = GET;
+exports.GET = void 0;
 exports.POST = POST;
 const server_1 = require("next/server");
 const headers_1 = require("next/headers");
 const anon_session_1 = require("../../lib/anon-session");
 const log_safe_1 = require("../../lib/log-safe");
+const no_store_1 = require("../../lib/no-store");
 const COOKIE_MAX_AGE = 90 * 24 * 60 * 60; // 90 days in seconds
-/**
- * GET handler - retrieves anonymous session preferences
- */
-async function GET(request) {
+/** Retrieves anonymous session preferences. Exported as GET below, wrapped in noStore (PAY-2994). */
+async function getPreferences(request) {
     try {
         const cookieStore = await (0, headers_1.cookies)();
         let anonId = cookieStore.get(anon_session_1.ANON_COOKIE_NAME)?.value;
@@ -53,6 +52,7 @@ async function GET(request) {
 /**
  * POST handler - updates anonymous session preferences
  */
+exports.GET = (0, no_store_1.noStore)(getPreferences);
 async function POST(request) {
     try {
         const cookieStore = await (0, headers_1.cookies)();

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

@@ -52,6 +52,8 @@ const device_id_1 = require("../../lib/device-id");
 const twofa_rejection_1 = require("../../lib/twofa-rejection");
 const bearer_fetch_1 = require("../../lib/bearer-fetch");
 const log_safe_1 = require("../../lib/log-safe");
+// AUTH-045: the httpOnly cookie that carries the enrolment-scoped token from the code turn to the two enrolment routes (ONE name, defined in lib/first-enrol).
+const first_enrol_1 = require("../../lib/first-enrol");
 // `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.
@@ -325,6 +327,50 @@ async function POST(req) {
         const vresult = verifyData?.data?.result ?? verifyData?.data ?? verifyData;
         const vAccess = vresult?.access_token;
         const vRefresh = vresult?.refresh_token;
+        // PAY-3083 (AUTH-045): ACCESS WITHOUT REFRESH AT THE CODE TURN IS NOT A FAILURE - IT IS ENROLMENT.
+        //
+        // The IdP withholds the refresh token for a user who has no usable second factor on THIS client.
+        // TOTP enrolment is PER CLIENT (DotNetPert 99446 sec A, client 90717 / user 1175): the password turn
+        // answered Require2FA=true, IssueRefreshToken=false, step=enroll_mfa, and this verify turn then
+        // accepted the emailed code as CONTACT PROOF and issued an ENROLMENT-SCOPED access token, again with
+        // no refresh token. That is exactly what PAY-2798 requires of the IdP - the IdP is RIGHT.
+        //
+        // This branch used to read "access, no refresh" as an incomplete response and answer 502, so the
+        // developer who had just proved their contact was told the server was broken and could never reach
+        // the enrolment page: the 502 the field saw as
+        //   '[ADMIN-LOGIN] verify response missing token { hasAccess: true, hasRefresh: false }'.
+        //
+        // Send them to ENROLMENT instead, in the ONE contract the door and the form already share for it
+        // (PAY-2630): requiresTwoFactor + nextStep 'enroll_mfa'. No session is minted - an enrolment-scoped
+        // token is not a signed-in session - and the token value is NEVER logged nor echoed (BAPert 99521 #2).
+        //
+        // Guard kept: no access token AT ALL (a refresh-only or empty body) is still a broken success and
+        // still 502 below - this widening is only for a genuine access-with-no-refresh answer.
+        if (vAccess && !vRefresh) {
+            const step = vresult?.next_step === 'enroll_mfa' || vresult?.next_step === 'mfa_verify' ? vresult.next_step : 'enroll_mfa';
+            const enrolling = step === 'enroll_mfa';
+            const answer = server_1.NextResponse.json({
+                success: false,
+                requiresTwoFactor: true,
+                acceptedFactors: acceptedFactorsFor('email'),
+                sentVia: null,
+                codeRequested: false,
+                emailSent: false,
+                nextStep: step,
+                // AUTH-045 (walk 14 Nov 2026): requiresTwoFactor alone is also the password turn's "a code was sent", so the form re-drew the code box
+                // and looped. This flag is the ONLY signal that means "go enrol"; it is set on this answer and nowhere else.
+                ...(enrolling ? { enrolmentRequired: true } : {}),
+            }, { status: 200 });
+            if (enrolling) {
+                // No session exists for an enrolment-scoped token, and the enrolment page's actions need one, so the token rides in this httpOnly
+                // cookie to the enrolment routes (the portal's PAY-2798 part 2 pattern): never in a body, a URL or a log; strict; 600 s.
+                answer.cookies.set(first_enrol_1.ENROL_COOKIE, vAccess, { httpOnly: true, secure: process.env.NODE_ENV === 'production', sameSite: 'strict', path: '/', maxAge: first_enrol_1.ENROL_COOKIE_MAX_AGE });
+                // The provisional bearer is spent: the enrolment token replaces it.
+                answer.cookies.set('adm2fa', '', { path: '/', maxAge: 0 });
+                answer.cookies.set('adm2fa_lane', '', { path: '/', maxAge: 0 });
+            }
+            return answer;
+        }
         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 });

package/dist/api-handlers/health.d.ts

@@ -0,0 +1,5 @@
+export interface HealthRedis {
+    ping(): Promise<unknown>;
+}
+export type RedisState = 'up' | 'down' | 'unknown';
+export declare function createHealthHandler(getRedis: () => HealthRedis): () => Promise<Response>;

package/dist/api-handlers/health.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createHealthHandler = createHealthHandler;
+/**
+ * /api/health handler (PAY-2804, AUTH-045; BAPert ruling 88065).
+ *
+ * Sessions are Redis-only. The body reports state ONLY: `redis: 'up' | 'down' | 'unknown'` and
+ * `status: 'ok' | 'degraded'`. No REDIS_URL, host, port, error text or stack, to any caller (anonymous route).
+ *
+ * The HTTP status is 200 even when Redis is down: this route is the ALB target-group check, and a 503
+ * there would make the ALB pull every task for an outage that replacing tasks cannot fix.
+ * HEALTH_REDIS_FAILS_STATUS=1 turns Redis-down into 503 as a READINESS setting for a deployer's OWN probe;
+ * it is default off and must never be set on a load-balancer health check.
+ */
+const server_1 = require("next/server");
+const PING_BUDGET_MS = 2000;
+async function probe(redis) {
+    let timer;
+    try {
+        const timeout = new Promise((_, reject) => {
+            timer = setTimeout(() => reject(new Error('ping timeout')), PING_BUDGET_MS);
+        });
+        await Promise.race([redis.ping(), timeout]);
+        return 'up';
+    }
+    catch {
+        return 'down';
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+function createHealthHandler(getRedis) {
+    return async function GET() {
+        let redis;
+        let client;
+        try {
+            client = getRedis();
+        }
+        catch {
+            client = undefined;
+        }
+        redis = client ? await probe(client) : 'unknown';
+        const failsStatus = process.env.HEALTH_REDIS_FAILS_STATUS === '1';
+        return server_1.NextResponse.json({ status: redis === 'up' ? 'ok' : 'degraded', redis }, { status: redis !== 'up' && failsStatus ? 503 : 200, headers: { 'Cache-Control': 'no-store' } });
+    };
+}

package/dist/api-handlers/mfa/first-enrol.d.ts

@@ -0,0 +1,5 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { type EnrolStep } from '../../lib/first-enrol';
+export declare function enrolStepPOST(step: EnrolStep): (req: NextRequest) => Promise<NextResponse>;
+export declare const POST_ENROLL: (req: NextRequest) => Promise<NextResponse>;
+export declare const POST_CONFIRM: (req: NextRequest) => Promise<NextResponse>;

package/dist/api-handlers/mfa/first-enrol.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.POST_CONFIRM = exports.POST_ENROLL = void 0;
+exports.enrolStepPOST = enrolStepPOST;
+const node_crypto_1 = require("node:crypto");
+const server_1 = require("next/server");
+const idp_client_config_1 = require("../../lib/idp-client-config");
+const client_key_1 = require("../../lib/client-key");
+const mfa_json_guard_1 = require("../../lib/mfa-json-guard");
+const first_enrol_1 = require("../../lib/first-enrol");
+/**
+ * AUTH-045 first-enrolment carry (PAY-2938, BAPert 100969 rows 3-5): the TWO routes a user the IdP told to enrol uses, built on lib/first-enrol.
+ *
+ * WHO MAY CALL: the browser that holds the httpOnly enrolment cookie the credential door parked (ENROL_COOKIE). This is the ONLY module besides the
+ * door that reads that cookie, and it serves ONLY these two operations; every other package route stays session-gated and answers 401 to a caller
+ * holding nothing but this cookie (a gate row holds that). No cookie -> 401 SIGN_IN_AGAIN and no IdP call.
+ *
+ * What follows a confirm (BAPert 100969 row 5): the cookie is cleared and the answer carries the recovery codes; NO session is minted here and no new
+ * way to mint one is added. The person signs in again with their password and the authenticator, through the same credential door as before.
+ *
+ * The token never leaves the server: not in a body, a URL, a log or a Referer. The IdP's prose is never relayed.
+ */
+const digest = (s) => (0, node_crypto_1.createHash)('sha256').update(s).digest('hex');
+const cookieOpts = (maxAge) => ({ httpOnly: true, secure: process.env.NODE_ENV === 'production', sameSite: 'strict', path: '/', maxAge });
+function reply(status, body, clear) {
+    const res = server_1.NextResponse.json(body, { status, headers: mfa_json_guard_1.NO_STORE });
+    if (clear)
+        res.cookies.set(first_enrol_1.ENROL_COOKIE, '', cookieOpts(0));
+    return res;
+}
+function enrolStepPOST(step) {
+    return async function POST(req) {
+        const refused = (0, mfa_json_guard_1.refuseNonJson)(req);
+        if (refused)
+            return refused;
+        const token = req.cookies.get(first_enrol_1.ENROL_COOKIE)?.value;
+        if (!token)
+            return reply(401, { success: false, code: 'SIGN_IN_AGAIN' }, false);
+        if (!(0, first_enrol_1.attemptAllowed)(`${step}|ck|${digest(token)}`, first_enrol_1.LIMIT_PER_COOKIE))
+            return reply(429, { success: false, code: 'TOO_MANY', error: 'Too many attempts. Wait a few minutes and try again.' }, true);
+        const idp = process.env.IDP_URL;
+        let clientKey = '';
+        try {
+            const config = await (0, idp_client_config_1.getIDPClientConfig)();
+            clientKey = (0, client_key_1.resolveClientKey)(config, 'first-enrol').key ?? '';
+        }
+        catch {
+            return reply(503, { success: false, code: 'IDP_CONFIG_UNAVAILABLE' }, false);
+        }
+        if (!idp || !clientKey)
+            return reply(503, { success: false, code: 'IDP_CONFIG_UNAVAILABLE' }, false);
+        const body = await req.json().catch(() => null);
+        const r = await (0, first_enrol_1.runEnrolStep)({ fetchImpl: (u, i) => fetch(u, i), idp, clientKey }, { step, token, body });
+        return reply(r.status, r.body, r.cookie === 'clear');
+    };
+}
+exports.POST_ENROLL = enrolStepPOST('enroll');
+exports.POST_CONFIRM = enrolStepPOST('confirm');

package/dist/api-handlers/session/refresh-viability.d.ts

@@ -1,15 +1,3 @@
-import { NextRequest, NextResponse } from 'next/server';
-export declare function GET(req: NextRequest): Promise<NextResponse<{
-    canRefresh: boolean;
-    reason: string;
-    error: string;
-    code: string;
-}> | NextResponse<{
-    canRefresh: boolean;
-    reason: string;
-    sessionTokenId: string;
-}> | NextResponse<{
-    canRefresh: boolean;
-    reason: string;
-    sessionTokenId: null;
-}>>;
+import { NextRequest } from 'next/server';
+/** PAY-2994 (NightHawk 92964 Low 1): the api-handlers/session/* path is also in the exports map; wrap here too so a consumer importing it is covered. */
+export declare const GET: (req: NextRequest) => Promise<Response>;

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

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.GET = GET;
+exports.GET = void 0;
 const server_1 = require("next/server");
 const session_store_1 = require("../../lib/session-store");
 const refresh_token_validator_1 = require("../../lib/refresh-token-validator");
@@ -8,8 +8,9 @@ const test_aware_get_token_1 = require("../../lib/test-aware-get-token");
 const logger_1 = require("../../config/logger");
 const token_log_id_1 = require("../../lib/token-log-id");
 const log_safe_1 = require("../../lib/log-safe");
+const no_store_1 = require("../../lib/no-store");
 const auth_1 = require("../../server/auth");
-async function GET(req) {
+async function getRefreshViability(req) {
     try {
         const sessionToken = req.nextUrl.searchParams.get('token');
         let finalSessionToken = sessionToken;
@@ -59,3 +60,5 @@ async function GET(req) {
         return server_1.NextResponse.json({ canRefresh: false, reason: 'check_error', error: 'Failed to check refresh viability', code: 'INTERNAL_ERROR', correlationId }, { status: 500 });
     }
 }
+/** PAY-2994 (NightHawk 92964 Low 1): the api-handlers/session/* path is also in the exports map; wrap here too so a consumer importing it is covered. */
+exports.GET = (0, no_store_1.noStore)(getRefreshViability);

package/dist/api-handlers/session/viability.d.ts

@@ -3,11 +3,6 @@
  *
  * This API route is called by the middleware to securely check if a session is valid.
  */
-import { NextRequest, NextResponse } from 'next/server';
-export declare function GET(req: NextRequest): Promise<NextResponse<{
-    error: string;
-    message: string;
-    code: string;
-}> | NextResponse<{
-    authenticated: boolean;
-}>>;
+import { NextRequest } from 'next/server';
+/** PAY-2994 (NightHawk 92964 Low 1): the api-handlers/session/* path is also in the exports map; wrap here too so a consumer importing it is covered. */
+export declare const GET: (req: NextRequest) => Promise<Response>;

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

@@ -5,7 +5,7 @@
  * This API route is called by the middleware to securely check if a session is valid.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.GET = GET;
+exports.GET = void 0;
 const revocation_fields_1 = require("../../auth/revocation-fields");
 const server_1 = require("next/server");
 const session_store_1 = require("../../lib/session-store");
@@ -15,7 +15,8 @@ const idp_client_config_1 = require("../../lib/idp-client-config");
 const token_log_id_1 = require("../../lib/token-log-id");
 const sessions_1 = require("../../vibe/sessions");
 const log_safe_1 = require("../../lib/log-safe");
-async function GET(req) {
+const no_store_1 = require("../../lib/no-store");
+async function getViability(req) {
     try {
         // Ensure initialization is complete (auth signing secret resolved from IDP)
         if (!process.env.BETTER_AUTH_SECRET && !process.env.NEXTAUTH_SECRET) {
@@ -222,3 +223,5 @@ async function GET(req) {
         return server_1.NextResponse.json({ authenticated: false }, { status: 500 });
     }
 }
+/** PAY-2994 (NightHawk 92964 Low 1): the api-handlers/session/* path is also in the exports map; wrap here too so a consumer importing it is covered. */
+exports.GET = (0, no_store_1.noStore)(getViability);

package/dist/auth/better-auth-exposure.d.ts

@@ -0,0 +1,11 @@
+export declare const MAGIC_LINK_ADVISORY = "GHSA-965c-763c-88jm";
+export declare const MAGIC_LINK_FIX_VERSION = "1.7.7";
+/** The installed better-auth version, read from its own package.json (the package does not export './package.json'), or null when it cannot be found. */
+export declare function installedBetterAuthVersion(): string | null;
+/** True when `version` is strictly below `floor` (numeric major.minor.patch; a pre-release suffix is ignored). An unparseable version is NOT proven fixed, so it counts as below. */
+export declare function versionBelow(version: string | null, floor: string): boolean;
+/**
+ * Warn when the magic-link plugin is enabled on a better-auth below the fix. Returns whether it warned (so a test can assert it). `warn` and `version` are
+ * injectable for the same reason.
+ */
+export declare function warnIfMagicLinkBelowFix(magicLinkEnabled: boolean, warn?: (msg: string) => void, version?: string | null): boolean;

package/dist/auth/better-auth-exposure.js

@@ -0,0 +1,73 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAGIC_LINK_FIX_VERSION = exports.MAGIC_LINK_ADVISORY = void 0;
+exports.installedBetterAuthVersion = installedBetterAuthVersion;
+exports.versionBelow = versionBelow;
+exports.warnIfMagicLinkBelowFix = warnIfMagicLinkBelowFix;
+/**
+ * PAY-2592 slice 1: the exposure guard for better-auth GHSA-965c-763c-88jm (critical, CVSS 9.1; affected >=1.4.0-beta.18 <1.7.7).
+ *
+ * "OAuth state can be used as a Magic Link to sign in as another user." It needs ALL of: the Magic Link plugin enabled, an OAuth provider, and OAuth state
+ * stored with `account.storeStateStrategy: "database"` (better-auth's default when a database OR secondaryStorage exists). This package has secondaryStorage,
+ * so what keeps it unexposed is, today:
+ *   1. `account.storeStateStrategy: 'cookie'` is pinned in better-auth.ts (the advisory: cookie-backed state blocks the path), and
+ *   2. the magic-link plugin registers ONLY when a consumer passes `opts.magicLink`.
+ * Nothing in this package fixes the flaw; the fix is better-auth >= 1.7.7 (PAY-2592, spike pending). Until then a consumer that turns the plugin on is told, loudly,
+ * once per process.
+ *
+ * test/next-mvp-pay-2592-exposure-pins.test.cjs holds both conditions and this warning.
+ */
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+exports.MAGIC_LINK_ADVISORY = 'GHSA-965c-763c-88jm';
+exports.MAGIC_LINK_FIX_VERSION = '1.7.7';
+/** The installed better-auth version, read from its own package.json (the package does not export './package.json'), or null when it cannot be found. */
+function installedBetterAuthVersion() {
+    try {
+        let dir = (0, node_path_1.dirname)(require.resolve('better-auth'));
+        for (let i = 0; i < 8; i++) {
+            try {
+                const pkg = JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(dir, 'package.json'), 'utf8'));
+                if (pkg.name === 'better-auth' && typeof pkg.version === 'string')
+                    return pkg.version;
+            }
+            catch {
+                /* no package.json at this level */
+            }
+            const up = (0, node_path_1.dirname)(dir);
+            if (up === dir)
+                break;
+            dir = up;
+        }
+    }
+    catch {
+        /* unresolvable */
+    }
+    return null;
+}
+/** True when `version` is strictly below `floor` (numeric major.minor.patch; a pre-release suffix is ignored). An unparseable version is NOT proven fixed, so it counts as below. */
+function versionBelow(version, floor) {
+    const parse = (v) => /^(\d+)\.(\d+)\.(\d+)/.exec(v)?.slice(1, 4).map(Number) ?? null;
+    const a = version ? parse(version) : null;
+    const b = parse(floor);
+    if (!a || !b)
+        return true;
+    for (let i = 0; i < 3; i++) {
+        if (a[i] !== b[i])
+            return a[i] < b[i];
+    }
+    return false;
+}
+/**
+ * Warn when the magic-link plugin is enabled on a better-auth below the fix. Returns whether it warned (so a test can assert it). `warn` and `version` are
+ * injectable for the same reason.
+ */
+function warnIfMagicLinkBelowFix(magicLinkEnabled, warn = (m) => console.warn(m), version = installedBetterAuthVersion()) {
+    if (!magicLinkEnabled)
+        return false;
+    if (!versionBelow(version, exports.MAGIC_LINK_FIX_VERSION))
+        return false;
+    warn(`[BETTER_AUTH] WARNING ${exports.MAGIC_LINK_ADVISORY} (critical): the magic-link plugin is enabled on better-auth ${version ?? '(version unknown)'}, below the fix ${exports.MAGIC_LINK_FIX_VERSION}. ` +
+        `This package keeps account.storeStateStrategy='cookie', which blocks the attack; do NOT change that while magic link is on, and upgrade better-auth (PAY-2592).`);
+    return true;
+}

package/dist/auth/better-auth.js

@@ -78,6 +78,10 @@ const single_flight_1 = require("../lib/single-flight");
 const session_store_1 = require("../lib/session-store");
 const token_log_id_1 = require("../lib/token-log-id");
 const log_safe_1 = require("../lib/log-safe");
+const better_auth_exposure_1 = require("./better-auth-exposure");
+const no_store_1 = require("../lib/no-store");
+/** PAY-2592: the magic-link advisory warning fires once per process. */
+let magicLinkAdvisoryWarned = false;
 /**
  * 185121: short sha256 fingerprint for secrets/tokens in log lines — enough
  * to tell "same" from "divergent", never enough to reconstruct. 12 hex chars
@@ -489,6 +493,12 @@ function buildBetterAuthProviders(config) {
 function createBetterAuthInstance(idpConfig, opts = {}) {
     (0, app_slug_1.assertAppSlugMatchesIdp)(idpConfig.clientSlug);
     const appSlug = idpConfig.clientSlug || (0, app_slug_1.getAppSlug)();
+    // PAY-2592 (GHSA-965c-763c-88jm): a consumer that enables the magic-link plugin on a better-auth below 1.7.7 is told, once per process. What keeps the
+    // package unexposed is account.storeStateStrategy='cookie' below plus the plugin being opt-in; see better-auth-exposure.ts.
+    if (opts.magicLink && !magicLinkAdvisoryWarned) {
+        magicLinkAdvisoryWarned = true;
+        (0, better_auth_exposure_1.warnIfMagicLinkBelowFix)(true);
+    }
     // 185121 line 1: name the secret this instance PINNED, as a hash, never the
     // secret. 183047's surviving fork is HMAC-fail vs record-miss; an HMAC-fail
     // caused by a divergent secret is only diagnosable if every instance
@@ -1410,7 +1420,7 @@ function authErrorCodeFromLocation(location) {
  * ```
  */
 function createAuthGetHandler(loginPath = '/account-auth/login') {
-    return async function GET(request) {
+    const get = async function GET(request) {
         // Card 138635: establish the request-scoped carrier for the provider's raw
         // id_token. It must wrap BOTH ba.GET (which invokes getUserInfo, the only
         // hook that sees the token) and the exchange below (which forwards it).
@@ -1523,4 +1533,6 @@ function createAuthGetHandler(loginPath = '/account-auth/login') {
             return response;
         });
     };
+    // PAY-2994: every Better Auth GET answer (session, OAuth callbacks, redirects) is per-user and may set cookies; never cached.
+    return (0, no_store_1.noStore)(get);
 }

package/dist/auth/route-config.js

@@ -75,6 +75,15 @@ const defaultUnauthenticatedRoutes = [
         allowDuringCircuitBreakerOpen: true,
         requiresRateLimit: false
     },
+    {
+        // PAY-2804: the exact path. '/api/health/*' matches startsWith('/api/health/'), which the bare
+        // '/api/health' (the ALB check) does not, so without this entry it sat behind sign-in.
+        pattern: '/api/health',
+        description: 'Health check endpoint (ALB target; anonymous, state only)',
+        allowDuringCircuitBreakerOpen: true,
+        // An ALB check comes from few IPs: a rate limit here would answer 429 and get tasks pulled (NightHawk 89179).
+        requiresRateLimit: false
+    },
     {
         pattern: '/api/health/*',
         description: 'Health check endpoints',

package/dist/components/auth/CredentialSignInForm.d.ts

@@ -33,7 +33,12 @@ interface Props {
      * default would 404 a generated app's user right after a good sign-in).
      */
     enrollHref?: string;
+    /**
+     * AUTH-045: where a person is sent when the IdP says they must ENROL a factor and they have NO session (the door parked an httpOnly enrolment cookie).
+     * Distinct from enrollHref (which needs a session). NO DEFAULT: without it the form says so instead of redrawing the code box.
+     */
+    firstEnrolHref?: string;
 }
 export declare function resolveDestination(explicit?: string): string;
-export declare function CredentialSignInForm({ callbackUrl, fetchImpl, onSignedIn, showForgotPassword, enrollHref }: Props): import("react/jsx-runtime").JSX.Element;
+export declare function CredentialSignInForm({ callbackUrl, fetchImpl, onSignedIn, showForgotPassword, enrollHref, firstEnrolHref }: Props): import("react/jsx-runtime").JSX.Element;
 export default CredentialSignInForm;