@payez/next-mvp 4.13.1 → 4.15.0

package/CHANGELOG.md

@@ -1,6 +1,38 @@
 # Changelog — @payez/next-mvp
 
-## Unreleased
+## 4.15.0 (to be published under dist-tag `next` only, after 4.14.0; `latest` stays 4.8.9 until Jon says otherwise)
+
+What main holds since 4.14.0, plus two new exports. Built from GitHub `keelsecurity/keelauth-next` main `1e65be6c9305`; this release commit changes only this file and the version. 4.14.0 was built from `33c188e0` (no tag, no `gitHead`); this one should be tagged `v4.15.0` at the sha it is published from. Consumers keep their own pins. The number is Jon's: two of the changes below are additive exports, which semver would call a minor.
+
+**Behaviour changes (read first)**
+
+- **CHANGE (PAY-3216, PR #25, Jon's order): the four test-env pages and the force-expire handler work with NO flag again, as before 4.2.0.** 4.14.0 still carried the `ENABLE_TEST_ROUTES` gate (`1d40a8c`: the pages rendered `notFound()` unless the flag was `true`; `072d20e`: force-expire answered 404 by default). Both gates are removed: `pages/test-env` renders each page unconditionally (the `guarded` barrel stays as the one seam; its only condition is PAY-3220's `PAYEZ_TOKEN_PAGES_OFF` for the two token pages, below, unset by default), and `api-handlers/test/force-expire` reaches its own session check (401 without a session) in development AND production. Its caller-supplied-token removal and the page redaction stay. **A consumer that mounts these pages or the force-expire route and relied on the flag to hide them in production must now gate them itself, or set `PAYEZ_TOKEN_PAGES_OFF` (next item) for the two token pages and force-expire.** Test: `test/pay-3216-test-env-no-flag.test.cjs`.
+- **NEW SWITCH (PAY-3220, PR #33): `PAYEZ_TOKEN_PAGES_OFF`, UNSET = as today.** Read on the server per request (never at module scope, never `NEXT_PUBLIC_`, never from request input). `true`/`1`/`yes`/`on` (any case) makes `JwtInspectPage` and `RefreshTokenPage` answer `notFound()` (a real 404) and `POST /api/test/force-expire` answer an empty 404 before any session is read; `false`/`0`/`no`/`off` or unset/blank leaves them on; ANY OTHER value is OFF with one warning naming the variable. `TestEnvPage` and `EmergencyLogoutPage` are not covered. **Set it only on a production host, on Jon's word, together with the PAY-3220 production-roll note** (also unmount or gate the consumer's own `/api/internal/session-data`, which the jwt-inspect page reads, and leave `ENABLE_TOKEN_INSPECTOR` unset). Test: `test/pay-3220-token-pages-switch.test.cjs`.
+- **FIX (PAY-3214, PR #26): `routes/mfa/totp-confirm` answers only `{ confirmed, stepped_up }`.** In 4.14.0 the re-minted access/refresh pair the IdP returns on a confirm reached the browser in the response body. It is now dropped: nothing is stored, the session's MFA state is untouched, and every 200 is that one projected body with `no-store`. A consumer that read tokens from this body (none should) gets none. Test: `test/pay-3214-totp-confirm-no-tokens.test.cjs`.
+- **FIX (PAY-3139, PRs #17, #19): an enabled sign-in provider whose required credentials are missing is left out** (empty client id for any provider; empty client secret for google), with one `PROVIDER_CREDENTIALS_MISSING` console.error naming the provider and the missing FIELD, never a value. Its sign-in then answers better-auth's typed `PROVIDER_NOT_FOUND` instead of a zero-byte 500. The provider name in that line, and at the two other IdP-config log sites, passes through one shared `logSafeName` (`lib/log-safe`), so a name from the IdP's row cannot forge a second log line. Tests: `test/provider-credentials-missing.test.cjs` (8 rows, mutants red).
+
+**New exports (additive)**
+
+- **`./lib/idp-logout` (PAY-3245, PR #30):** `revokeSessionAtIdp(req)` and `IdpLogoutUnconfirmedError`, so a consumer with its own sign-out route calls the package's one IdP revoke instead of copying it. Test: `test/next-mvp-pay-3245-idp-logout-export.test.cjs`.
+- **`./lib/first-enrol` (PAY-3270, PR #31):** `ENROL_COOKIE` (`'payez_enrol'`) and `ENROL_COOKIE_MAX_AGE` (`600`), so a consumer that parks the enrolment-scoped token for the first-enrol routes uses the package's cookie name instead of copying it. Test: `test/next-mvp-pay-3270-first-enrol-export.test.cjs`.
+
+**Docs and tests only (no runtime change)**
+
+- PAY-3228 B3 (PR #28): the five places that show `auth/login` say it is SERVER-ONLY and point a browser sign-in at `credential-login`.
+- Tests: AUTH-045 provisioning half, `test/credential-login.test.cjs`: the first-sign-in journey is captured and a second enrolment is proven not to happen, with F1 as the red-first control and F2/F3 as positive controls (PR #12); AUTH-045 F1 asserts `enrolmentRequired` on the code turn (PR #23); C1 compares TypeScript diagnostic paths after `path.resolve` and has a positive control (PR #18); PAY-3214 M1's stub matchers accept either path separator; AUTH-045 R7b skips transient `__*mutant*` files.
+
+**Not in this package:** `@payez/cli` 0.1.3 (pin on 4.14.0, PR #21) ships with `@payez/cli`.
+
+## 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).
 

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/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/mfa/totp-confirm.d.ts

@@ -5,4 +5,4 @@ import { NextRequest, NextResponse } from 'next/server';
  * it carries the enrolment handle plus the code. Only after this succeeds is
  * the method ACTIVE.
  */
-export declare function POST(req: NextRequest): Promise<NextResponse<any>>;
+export declare function POST(req: NextRequest): Promise<NextResponse<unknown>>;

package/dist/api-handlers/mfa/totp-confirm.js

@@ -36,11 +36,15 @@ async function POST(req) {
             meta: { attemptedRefresh: result.attemptedRefresh },
         }, { status: result.status, headers: mfa_json_guard_1.NO_STORE });
     }
+    // PAY-3214: the browser gets ONLY `confirmed` and `stepped_up`. When the IdP steps the session up it
+    // re-mints and answers { confirmed, stepped_up: true, access_token, refresh_token, token_type }; relaying
+    // `data` whole put the person's bearer and refresh token in a browser-readable body. The pair is DROPPED
+    // here, not stored: storing it would change the session's MFA state from an ENROLMENT, which
+    // totp-verify.ts's header forbids, and that is a ruling not yet given (BAPert-MB 105226 s3-s4). With the
+    // pair dropped the session keeps its own token, as on the IdP's own `stepped_up: false` path.
+    // `stepped_up` is passed back as the IdP said it (its meaning, with the pair dropped, is s3 Q2 of that ruling).
     const bodyJson = result.json;
-    if (bodyJson && typeof bodyJson === 'object' && 'success' in bodyJson && 'data' in bodyJson) {
-        if (bodyJson.success === true)
-            return server_1.NextResponse.json(bodyJson.data, { status: 200, headers: mfa_json_guard_1.NO_STORE });
-        return server_1.NextResponse.json(bodyJson, { status: 200, headers: mfa_json_guard_1.NO_STORE });
-    }
-    return server_1.NextResponse.json(bodyJson ?? {}, { status: 200, headers: mfa_json_guard_1.NO_STORE });
+    const enveloped = bodyJson && typeof bodyJson === 'object' && 'success' in bodyJson && 'data' in bodyJson;
+    const data = (enveloped ? (bodyJson.success === true ? bodyJson.data : null) : bodyJson) ?? {};
+    return server_1.NextResponse.json({ confirmed: data.confirmed === true, stepped_up: data.stepped_up === true }, { status: 200, headers: mfa_json_guard_1.NO_STORE });
 }

package/dist/api-handlers/test/force-expire.d.ts

@@ -15,19 +15,18 @@ import { NextRequest, NextResponse } from 'next/server';
  * mounts a destructive endpoint. Every one of the three surfaces this route
  * ended up on followed exactly these instructions.
  *
- * The handler itself was fixed (244877: default-deny behind ENABLE_TEST_ROUTES,
- * plus the caller-supplied-token IDOR removed). But a fixed handler shipped
+ * The handler itself was fixed (244877: the caller-supplied-token IDOR removed;
+ * its ENABLE_TEST_ROUTES gate was later removed again by PAY-3216). But a fixed handler shipped
  * with unqualified mounting instructions still spreads: the guidance was never
  * corrected alongside the code, and a package that documents a dangerous route
  * as a plain convenience is instructing the weaker configuration.
  *
  * ── IF YOU MOUNT IT, MOUNT IT LIKE THIS ───────────────────────────────────
- * Required: set ENABLE_TEST_ROUTES=true IN THAT ENVIRONMENT ONLY. Absent, empty
- * or any other value default-DENIES (404). Never set it in production.
+ * There is no env flag (PAY-3216): a mounted handler answers. Mount it only
+ * where you mean it to answer.
  *
  * ```typescript
  * // app/api/test/force-expire/route.ts   — TEST/DEV ENVIRONMENTS ONLY
- * // Requires ENABLE_TEST_ROUTES=true in that environment; 404s otherwise.
  * export { POST } from '@payez/next-mvp/api-handlers/test/force-expire';
  * ```
  *

package/dist/api-handlers/test/force-expire.js

@@ -6,6 +6,7 @@ const auth_1 = require("../../server/auth");
 const session_store_1 = require("../../lib/session-store");
 const safe_error_response_1 = require("../../lib/safe-error-response");
 const token_log_id_1 = require("../../lib/token-log-id");
+const token_pages_switch_1 = require("../../lib/token-pages-switch");
 /**
  * ⚠️ DESTRUCTIVE TEST-ONLY HANDLER — DO NOT MOUNT IN PRODUCTION. ⚠️
  *
@@ -22,19 +23,18 @@ const token_log_id_1 = require("../../lib/token-log-id");
  * mounts a destructive endpoint. Every one of the three surfaces this route
  * ended up on followed exactly these instructions.
  *
- * The handler itself was fixed (244877: default-deny behind ENABLE_TEST_ROUTES,
- * plus the caller-supplied-token IDOR removed). But a fixed handler shipped
+ * The handler itself was fixed (244877: the caller-supplied-token IDOR removed;
+ * its ENABLE_TEST_ROUTES gate was later removed again by PAY-3216). But a fixed handler shipped
  * with unqualified mounting instructions still spreads: the guidance was never
  * corrected alongside the code, and a package that documents a dangerous route
  * as a plain convenience is instructing the weaker configuration.
  *
  * ── IF YOU MOUNT IT, MOUNT IT LIKE THIS ───────────────────────────────────
- * Required: set ENABLE_TEST_ROUTES=true IN THAT ENVIRONMENT ONLY. Absent, empty
- * or any other value default-DENIES (404). Never set it in production.
+ * There is no env flag (PAY-3216): a mounted handler answers. Mount it only
+ * where you mean it to answer.
  *
  * ```typescript
  * // app/api/test/force-expire/route.ts   — TEST/DEV ENVIRONMENTS ONLY
- * // Requires ENABLE_TEST_ROUTES=true in that environment; 404s otherwise.
  * export { POST } from '@payez/next-mvp/api-handlers/test/force-expire';
  * ```
  *
@@ -42,59 +42,12 @@ const token_log_id_1 = require("../../lib/token-log-id");
  * The safest configuration is the absence of the route.
  */
 const POST = async (req) => {
-    // 244877 (package-level): DEFAULT DENY behind ENABLE_TEST_ROUTES.
-    //
-    // This handler MUTATES session state — it rewrites idpAccessTokenExpires two
-    // minutes into the past — and was gated on nothing but "any signed-in
-    // session": no role check, no env kill-switch. Because consuming apps mount
-    // it with a one-line re-export, EVERY consumer inherited that, including
-    // deployments on production hosts.
-    //
-    // The card was raised against one app's local copy. Sweeping the pattern
-    // rather than the instance found the same route in three places — a local
-    // copy in the graft, a local copy in idealvibe.online, and idealresume.online
-    // re-exporting THIS handler — so the fix belongs here, at the source all
-    // three ultimately derive from, not only in whichever copy was noticed first.
-    //
-    // The gate is the FIRST statement, before any session decode, so a disabled
-    // build does not reveal that the route is live. Absent, empty, or any value
-    // other than 'true' disables it. Distinguishable body on purpose: a bare 404
-    // reads as "route missing / build broken" and sends someone debugging
-    // deployment instead of reading a flag.
-    //
-    // A consumer that genuinely needs this in a test environment sets
-    // ENABLE_TEST_ROUTES=true there, which is the same posture the token
-    // inspector already uses for a strictly LESS dangerous, read-only route.
-    if (process.env.ENABLE_TEST_ROUTES !== 'true') {
-        // DISCLOSURE IS CONDITIONAL ON ENVIRONMENT (QAPert-NightHawk 34539, after
-        // QAPert caught that my first version shipped the very leak we had just
-        // criticised elsewhere).
-        //
-        // My original body named the flag: "Set ENABLE_TEST_ROUTES=true...". That
-        // is the same class of disclosure as TOKEN_INSPECTOR_DISABLED — it confirms
-        // the route exists, names the capability, and hands a prober the exact
-        // switch that turns it on. Having argued against that pattern one directory
-        // over, shipping it here would have been incoherent.
-        //
-        // Deleting the message outright is also wrong: it is what stops a developer
-        // losing an hour deciding whether their build is broken. The tension
-        // resolves by AUDIENCE, not by picking a side:
-        //   production      -> 404, EMPTY body. Nothing about the capability, the
-        //                      flag, or even that a handler is here.
-        //   non-production  -> 404 + the helpful message naming the flag.
-        //
-        // The operator affordance survives in production too, via the log line
-        // below: logs are visible to operators and not to probers, which is exactly
-        // the split the response body cannot make.
-        console.warn('[FORCE-EXPIRE] blocked: ENABLE_TEST_ROUTES is not "true" (test routes default-deny).');
-        if (process.env.NODE_ENV === 'production') {
-            return new server_1.NextResponse(null, { status: 404 });
-        }
-        return server_1.NextResponse.json({
-            error: 'TEST_ROUTES_DISABLED',
-            message: 'Test routes are disabled in this build. Set ENABLE_TEST_ROUTES=true to enable them (development only).',
-        }, { status: 404 });
-    }
+    // PAY-3216 (Jon's order, 15 Nov): the ENABLE_TEST_ROUTES default-deny gate that 072d20e (244877) put here is
+    // REMOVED. The handler works with no flag set, as before that commit. Mounting is the gate.
+    // PAY-3220 (ruled Win 105653 s1): the production switch for the token pages covers this route too, since the refresh
+    // page is its one caller. Unset, nothing changes. Set, an empty 404 before any session is read.
+    if ((0, token_pages_switch_1.tokenPagesOff)())
+        return new server_1.NextResponse(null, { status: 404 });
     try {
         const betterAuthSession = await (0, auth_1.getSession)(req);
         // ACCESS CONTROL (QAPert 34553). This handler previously fell back to a
@@ -112,11 +65,9 @@ const POST = async (req) => {
         // now ALWAYS the caller's own, which is also what the graft's local copy
         // has always done.
         //
-        // This is defence in depth, not the only control: the ENABLE_TEST_ROUTES
-        // gate above already 404s this handler by default. But the gate is
-        // switched ON in test environments, and "unauthenticated users can expire
-        // each other's sessions" is not acceptable there either — a control that
-        // only holds while a feature is switched off is not an access control.
+        // A control that only held while a feature was switched off would not be
+        // an access control: "unauthenticated users can expire each other's
+        // sessions" is not acceptable in any environment that mounts this.
         //
         // Corrects NextPert's own scope claim on card 244877 ("a caller could only
         // ever expire their OWN session"): that was read off the graft's LOCAL

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

@@ -80,6 +80,22 @@ export interface IdpOAuthProviderConfig {
     getUserInfo: ReturnType<typeof createIdpOAuthHooks>['getUserInfo'];
 }
 export declare function buildIdpOAuthProviderConfig(appBaseUrl?: string): IdpOAuthProviderConfig | null;
+/**
+ * PAY-3139: the credentials better-auth ITSELF requires before it can build a provider's authorize URL.
+ *
+ * Read from @better-auth/core 1.5.6 (social-providers/*.mjs, createAuthorizationURL): google throws
+ * `BetterAuthError("CLIENT_ID_AND_SECRET_REQUIRED")` when clientId OR clientSecret is empty. That is a plain
+ * throw, not an APIError, so the sign-in door answered a 500 with an EMPTY body (dev-93, 14 Nov: the IdP served
+ * the public, secret-redacted client config, so google's secret arrived empty). apple, facebook and github have
+ * no such guard (facebook signs in by id_token; apple's secret is the IdP's), so only the id is required there:
+ * an empty client id cannot produce a working authorize URL for any provider.
+ *
+ * Returns the missing FIELD NAMES, never a value.
+ */
+export declare function missingProviderCredentials(name: string, oauth: {
+    clientId?: string | null;
+    clientSecret?: string | null;
+}): Array<'clientId' | 'clientSecret'>;
 export declare function buildBetterAuthProviders(config: IDPClientConfig): Record<string, BetterAuthSocialProvider>;
 /**
  * Optional configuration for `createBetterAuthInstance`.

package/dist/auth/better-auth.js

@@ -46,6 +46,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.IDP_ERROR_CODES_TO_FORWARD = exports.OAUTH_SIGN_IN_FAILED_ERROR = void 0;
 exports.secretFingerprint = secretFingerprint;
 exports.buildIdpOAuthProviderConfig = buildIdpOAuthProviderConfig;
+exports.missingProviderCredentials = missingProviderCredentials;
 exports.buildBetterAuthProviders = buildBetterAuthProviders;
 exports.createBetterAuthInstance = createBetterAuthInstance;
 exports.isBetterAuthEnabled = isBetterAuthEnabled;
@@ -241,12 +242,45 @@ function buildIdpOAuthProviderConfig(appBaseUrl) {
          */
     };
 }
+/**
+ * PAY-3139: the credentials better-auth ITSELF requires before it can build a provider's authorize URL.
+ *
+ * Read from @better-auth/core 1.5.6 (social-providers/*.mjs, createAuthorizationURL): google throws
+ * `BetterAuthError("CLIENT_ID_AND_SECRET_REQUIRED")` when clientId OR clientSecret is empty. That is a plain
+ * throw, not an APIError, so the sign-in door answered a 500 with an EMPTY body (dev-93, 14 Nov: the IdP served
+ * the public, secret-redacted client config, so google's secret arrived empty). apple, facebook and github have
+ * no such guard (facebook signs in by id_token; apple's secret is the IdP's), so only the id is required there:
+ * an empty client id cannot produce a working authorize URL for any provider.
+ *
+ * Returns the missing FIELD NAMES, never a value.
+ */
+function missingProviderCredentials(name, oauth) {
+    const required = name === 'google' ? ['clientId', 'clientSecret'] : ['clientId'];
+    return required.filter((field) => String(oauth[field] ?? '').trim() === '');
+}
 function buildBetterAuthProviders(config) {
     const providers = {};
     for (const oauth of config.oauthProviders || []) {
         if (!oauth.enabled)
             continue;
         const name = oauth.provider.toLowerCase();
+        /**
+         * PAY-3139: an ENABLED row that lacks a credential better-auth requires is LEFT OUT, loudly. Left in, its
+         * sign-in throws inside better-auth and the door answers an empty 500 that names nothing. Left out, the
+         * same door answers better-auth's typed 404 PROVIDER_NOT_FOUND, and this line names the provider and the
+         * missing field (never a value), once per instance build.
+         */
+        const missing = missingProviderCredentials(name, oauth);
+        if (missing.length > 0) {
+            const secretHint = missing.includes('clientSecret')
+                ? ` (the secret is read env-first from ${(0, idp_client_config_1.providerSecretEnvVar)(oauth.provider)}, else from the IdP's ` +
+                    `secret-bearing client config, which a client that sends no valid client_secret does not receive)`
+                : '';
+            console.error(`[BETTER_AUTH] PROVIDER_CREDENTIALS_MISSING provider=${(0, log_safe_1.logSafeName)(name)} missing=${missing.join(',')}: ` +
+                `left out of the sign-in providers, so its sign-in answers PROVIDER_NOT_FOUND until the ` +
+                `${missing.join(' and ')} reach this app${secretHint}`);
+            continue;
+        }
         const additionalParams = oauth.additionalParams ?? {};
         const rawPrompt = additionalParams.prompt;
         const rawAccessType = additionalParams.accessType ?? additionalParams.access_type;

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;

package/dist/components/auth/CredentialSignInForm.js

@@ -31,7 +31,7 @@ function resolveDestination(explicit) {
     }
     return (0, safe_callback_1.safeCallbackPath)((0, authorize_resume_1.authorizeResumeHref)(returnUrl), (0, safe_callback_1.safeCallbackPath)(raw, '/dashboard'));
 }
-function CredentialSignInForm({ callbackUrl, fetchImpl, onSignedIn, showForgotPassword = false, enrollHref }) {
+function CredentialSignInForm({ callbackUrl, fetchImpl, onSignedIn, showForgotPassword = false, enrollHref, firstEnrolHref }) {
     const [step, setStep] = (0, react_1.useState)('credentials');
     const [email, setEmail] = (0, react_1.useState)('');
     const [password, setPassword] = (0, react_1.useState)('');
@@ -62,6 +62,20 @@ function CredentialSignInForm({ callbackUrl, fetchImpl, onSignedIn, showForgotPa
                     window.location.href = destination;
                 return;
             }
+            if (r.kind === 'enrol_required') {
+                // AUTH-045: the code was accepted as contact proof; the door parked the enrolment-scoped token in an httpOnly cookie. Go and enrol: never redraw
+                // the code box (the 14 Nov walk looped there). A host that gave no enrolment page gets a sentence, not a silent loop.
+                if (firstEnrolHref) {
+                    if (onSignedIn)
+                        onSignedIn(firstEnrolHref);
+                    else
+                        window.location.href = firstEnrolHref;
+                    return;
+                }
+                setError('This app has no authenticator setup page, so sign-in cannot continue. Tell the app owner.');
+                setErrorCode('sign_in_failed');
+                return;
+            }
             if (r.kind === 'two_factor') {
                 setCodeRequest(r.codeRequest);
                 setDevCode(r.devCode);

package/dist/components/mfa/FirstEnrolPanel.d.ts

@@ -0,0 +1,21 @@
+/**
+ * AUTH-045 first-enrolment carry (PAY-2938, BAPert 100969): the panel for a person the IdP told to ENROL a factor on THIS app, who has NO session.
+ * Ported from the portal's EnrolRequired (PAY-2798 part 2). It talks ONLY to the two routes that read the httpOnly enrolment cookie:
+ *   POST /api/auth/first-enrol/enroll   (started on mount: the person already asked for this by signing in)
+ *   POST /api/auth/first-enrol/confirm  (the 6-digit code from the app) -> the recovery codes, then "sign in again"
+ *
+ * Rules: the secret and otpauth_uri live in component state only (never a URL, storage, console or a third-party QR service); a 401 is never a
+ * message box (the person is sent back to sign-in); a fixed sentence per refusal code, never the server's text; no session is minted here.
+ */
+export declare const FIRST_ENROL_ENROLL_URL = "/api/auth/first-enrol/enroll";
+export declare const FIRST_ENROL_CONFIRM_URL = "/api/auth/first-enrol/confirm";
+/** BAPert 100969 row 6: one sentence that this app has its own authenticator entry (per-client factor, by design). */
+export declare const PER_APP_SENTENCE = "This app has its own authenticator entry: an authenticator you set up for another app or site does not carry over, so you add one here once.";
+export declare const DONE_SENTENCE = "Your authenticator is set. Sign in with your password and the code from your app.";
+export declare const SIGN_IN_AGAIN_SENTENCE = "This setup timed out or the sign-in expired. Sign in again to continue.";
+export declare function FirstEnrolPanel({ fetchImpl, signInHref, onSignInAgain, }?: {
+    fetchImpl?: typeof fetch;
+    signInHref?: string;
+    onSignInAgain?: (href: string) => void;
+}): import("react/jsx-runtime").JSX.Element;
+export default FirstEnrolPanel;

package/dist/components/mfa/FirstEnrolPanel.js

@@ -0,0 +1,115 @@
+"use strict";
+'use client';
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SIGN_IN_AGAIN_SENTENCE = exports.DONE_SENTENCE = exports.PER_APP_SENTENCE = exports.FIRST_ENROL_CONFIRM_URL = exports.FIRST_ENROL_ENROLL_URL = void 0;
+exports.FirstEnrolPanel = FirstEnrolPanel;
+const jsx_runtime_1 = require("react/jsx-runtime");
+const react_1 = require("react");
+const QrCode_1 = require("./QrCode");
+/**
+ * AUTH-045 first-enrolment carry (PAY-2938, BAPert 100969): the panel for a person the IdP told to ENROL a factor on THIS app, who has NO session.
+ * Ported from the portal's EnrolRequired (PAY-2798 part 2). It talks ONLY to the two routes that read the httpOnly enrolment cookie:
+ *   POST /api/auth/first-enrol/enroll   (started on mount: the person already asked for this by signing in)
+ *   POST /api/auth/first-enrol/confirm  (the 6-digit code from the app) -> the recovery codes, then "sign in again"
+ *
+ * Rules: the secret and otpauth_uri live in component state only (never a URL, storage, console or a third-party QR service); a 401 is never a
+ * message box (the person is sent back to sign-in); a fixed sentence per refusal code, never the server's text; no session is minted here.
+ */
+exports.FIRST_ENROL_ENROLL_URL = '/api/auth/first-enrol/enroll';
+exports.FIRST_ENROL_CONFIRM_URL = '/api/auth/first-enrol/confirm';
+/** BAPert 100969 row 6: one sentence that this app has its own authenticator entry (per-client factor, by design). */
+exports.PER_APP_SENTENCE = 'This app has its own authenticator entry: an authenticator you set up for another app or site does not carry over, so you add one here once.';
+exports.DONE_SENTENCE = 'Your authenticator is set. Sign in with your password and the code from your app.';
+exports.SIGN_IN_AGAIN_SENTENCE = 'This setup timed out or the sign-in expired. Sign in again to continue.';
+const REFUSAL_COPY = {
+    CODE_INVALID: 'That code did not work. Check the 6 digits in your authenticator app and try again.',
+    TOO_MANY: 'Too many attempts. Wait a few minutes and sign in again.',
+    ENROLMENT_RESTART: 'This setup timed out. Reload the page to get a new code to scan.',
+    UNAVAILABLE: 'We could not reach the sign-in service. Nothing was changed. Try again in a moment.',
+};
+const FALLBACK_COPY = 'Setup was not completed. Try again.';
+const readJson = async (res) => res.json().catch(() => null);
+function FirstEnrolPanel({ fetchImpl, signInHref = '/account-auth/login', onSignInAgain, } = {}) {
+    const doFetch = fetchImpl ?? ((...a) => fetch(...a));
+    const [stage, setStage] = (0, react_1.useState)('starting');
+    const [enroll, setEnroll] = (0, react_1.useState)(null);
+    const [code, setCode] = (0, react_1.useState)('');
+    const [error, setError] = (0, react_1.useState)(null);
+    const [codes, setCodes] = (0, react_1.useState)(null);
+    const [busy, setBusy] = (0, react_1.useState)(false);
+    const started = (0, react_1.useRef)(false);
+    const toSignIn = () => {
+        if (onSignInAgain)
+            onSignInAgain(signInHref);
+        else
+            window.location.href = signInHref;
+    };
+    async function begin() {
+        setBusy(true);
+        setError(null);
+        try {
+            const res = await doFetch(exports.FIRST_ENROL_ENROLL_URL, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ friendly_name: 'This device' }) });
+            if (res.status === 401)
+                return toSignIn(); // a 401 is never a message box
+            const body = await readJson(res);
+            if (res.ok && body?.data?.secret && body?.data?.otpauth_uri && Number.isInteger(body?.data?.enrollment_id)) {
+                setEnroll({ secret: body.data.secret, otpauth_uri: body.data.otpauth_uri, enrollment_id: body.data.enrollment_id });
+                setStage('enrolling');
+                return;
+            }
+            setError(REFUSAL_COPY[body?.code] ?? FALLBACK_COPY);
+            setStage('failed');
+        }
+        catch {
+            setError(REFUSAL_COPY.UNAVAILABLE);
+            setStage('failed');
+        }
+        finally {
+            setBusy(false);
+        }
+    }
+    (0, react_1.useEffect)(() => {
+        if (started.current)
+            return;
+        started.current = true;
+        void begin();
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, []);
+    async function confirm() {
+        if (!enroll || !/^\d{6}$/.test(code)) {
+            setError('Enter the 6-digit code from your app.');
+            return;
+        }
+        setBusy(true);
+        setError(null);
+        try {
+            const res = await doFetch(exports.FIRST_ENROL_CONFIRM_URL, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ enrollment_id: enroll.enrollment_id, code }) });
+            if (res.status === 401)
+                return toSignIn();
+            const body = await readJson(res);
+            if (res.ok && body?.confirmed === true) {
+                setEnroll(null);
+                setCode('');
+                setCodes(Array.isArray(body.codes) ? body.codes.filter((c) => typeof c === 'string') : null);
+                setStage('done');
+                return;
+            }
+            setCode('');
+            setError(REFUSAL_COPY[body?.code] ?? FALLBACK_COPY);
+        }
+        catch {
+            setError(REFUSAL_COPY.UNAVAILABLE);
+        }
+        finally {
+            setBusy(false);
+        }
+    }
+    if (stage === 'done') {
+        return ((0, jsx_runtime_1.jsxs)("div", { "data-testid": "first-enrol-done", role: "status", children: [(0, jsx_runtime_1.jsx)("p", { children: exports.DONE_SENTENCE }), codes && codes.length > 0 ? ((0, jsx_runtime_1.jsxs)(jsx_runtime_1.Fragment, { children: [(0, jsx_runtime_1.jsx)("p", { children: "Save these recovery codes somewhere safe. Each one works once, and they are not shown again." }), (0, jsx_runtime_1.jsx)("ul", { "data-testid": "first-enrol-codes", children: codes.map((c) => ((0, jsx_runtime_1.jsx)("li", { children: (0, jsx_runtime_1.jsx)("code", { children: c }) }, c))) })] })) : ((0, jsx_runtime_1.jsx)("p", { "data-testid": "first-enrol-no-codes", children: "We could not show your recovery codes. You can create new ones after you sign in." })), (0, jsx_runtime_1.jsx)("p", { children: (0, jsx_runtime_1.jsx)("a", { href: signInHref, children: "Sign in" }) })] }));
+    }
+    return ((0, jsx_runtime_1.jsxs)("div", { "data-testid": "first-enrol-panel", style: { display: 'flex', flexDirection: 'column', gap: 12, alignItems: 'flex-start' }, children: [(0, jsx_runtime_1.jsx)("p", { "data-testid": "first-enrol-per-app", children: exports.PER_APP_SENTENCE }), stage === 'starting' ? (0, jsx_runtime_1.jsx)("p", { "data-testid": "first-enrol-starting", children: "Setting up\u2026" }) : null, stage === 'enrolling' && enroll ? ((0, jsx_runtime_1.jsxs)(jsx_runtime_1.Fragment, { children: [(0, jsx_runtime_1.jsx)("p", { children: "Open your authenticator app and scan this code. A phone camera works too." }), (0, jsx_runtime_1.jsx)(QrCode_1.QrCode, { value: enroll.otpauth_uri }), (0, jsx_runtime_1.jsxs)("div", { children: [(0, jsx_runtime_1.jsx)("div", { children: "Can't scan? Enter this code manually:" }), (0, jsx_runtime_1.jsx)("code", { "data-testid": "first-enrol-secret", style: { wordBreak: 'break-all' }, children: enroll.secret })] }), (0, jsx_runtime_1.jsxs)("form", { onSubmit: (e) => {
+                            e.preventDefault();
+                            void confirm();
+                        }, children: [(0, jsx_runtime_1.jsx)("label", { htmlFor: "first-enrol-code", children: "Enter the 6-digit code from your app:" }), (0, jsx_runtime_1.jsx)("br", {}), (0, jsx_runtime_1.jsx)("input", { id: "first-enrol-code", "data-testid": "first-enrol-code", inputMode: "numeric", autoComplete: "one-time-code", maxLength: 6, value: code, disabled: busy, onChange: (e) => setCode(e.target.value.replace(/\D/g, '').slice(0, 6)) }), ' ', (0, jsx_runtime_1.jsx)("button", { type: "submit", "data-testid": "first-enrol-confirm", disabled: busy || code.length !== 6, children: "Confirm" })] })] })) : null, error ? ((0, jsx_runtime_1.jsx)("p", { role: "alert", "data-testid": "first-enrol-error", children: error })) : null, stage === 'failed' ? ((0, jsx_runtime_1.jsx)("p", { children: (0, jsx_runtime_1.jsx)("a", { href: signInHref, children: "Sign in again" }) })) : null] }));
+}
+exports.default = FirstEnrolPanel;