@payez/next-mvp 4.13.1 → 4.15.0

package/dist/pages/test-env/guarded.js

@@ -6,81 +6,45 @@ exports.RefreshTokenPage = RefreshTokenPage;
 exports.EmergencyLogoutPage = EmergencyLogoutPage;
 const jsx_runtime_1 = require("react/jsx-runtime");
 /**
- * SERVER-COMPONENT GUARDS for the test-env debug pages (card 249259, BAPert
- * ruling 35321). These are what `@payez/next-mvp/pages/test-env` exports. The
- * raw client components are NOT exported.
+ * The BARREL that `@payez/next-mvp/pages/test-env` exports: one server-component wrapper per test-env page.
  *
- * ── WHAT THIS IS, AND WHAT IT IS EMPHATICALLY NOT ───────────────────────────
- * MOUNTING IS STILL THE PRIMARY GATE. This wrapper is a backstop for a mount
- * that should not have happened. It is NOT a licence to mount these freely:
- * setting ENABLE_TEST_ROUTES=true in an environment where these pages are
- * mounted gives you exactly the exposure this package spent 248991 documenting
- * - a live session token and a copy button. If you are not actively debugging,
- * DO NOT MOUNT THESE AT ALL. The safest configuration remains their absence.
+ * PAY-3216 (Jon's order, 15 Nov): the ENABLE_TEST_ROUTES check and its notFound() are REMOVED. Each wrapper renders
+ * its page unconditionally, as the pages rendered before 1d40a8c. Ruling 35321 is withdrawn.
  *
- * ── WHY A SERVER COMPONENT, AND WHY THE PAGES THEMSELVES CANNOT DO THIS ─────
- * 248991 item 2 asked for a per-page env gate and it was correctly REFUSED:
- * the pages are `'use client'`, and non-`NEXT_PUBLIC_` variables are not
- * available in the browser (Next.js docs, environment-variables: "Non-
- * NEXT_PUBLIC_ environment variables are only available in the Node.js
- * environment"). A check written inside those files would read `undefined` on
- * the client and deny ALWAYS - killing the tool in dev too - while reading the
- * REAL value during SSR, producing a hydration mismatch. It would look like a
- * gate, satisfy a grep for one, and protect nothing.
+ * PAY-3220 (ruled Win 105653 s1): the ONE production switch, PAYEZ_TOKEN_PAGES_OFF (../../lib/token-pages-switch), sits
+ * here for the two token-showing pages ONLY. Unset, they render exactly as before. Set, they answer notFound(): a real
+ * 404, indistinguishable from a route that was never registered (a 403 would confirm the page exists).
+ * TestEnvPage (the index) and EmergencyLogoutPage are NOT covered, on purpose: Jon named the two token-showing pages.
  *
- * A SERVER component can read the variable for real. That is the whole reason
- * this file exists as a separate layer instead of a few lines in each page.
- *
- * ── FAIL CLOSED ─────────────────────────────────────────────────────────────
- * The test is `=== 'true'`, not truthiness. Unset, empty, "false", "0", "TRUE"
- * and every typo all deny. The UNSAFE state requires a deliberate, exact act;
- * the SAFE state is what you get by doing nothing, including by misconfiguring
- * it. A gate whose default is "open" is not a gate.
- *
- * `notFound()` is deliberate and is not a 403: a real 404 is indistinguishable
- * from a route that was never registered, whereas a 403 CONFIRMS the page
- * exists to anyone who probes for it. That is the same disclosure axis card
- * 245920 was raised about, so shipping the confirming variant here would
- * reintroduce next door the thing being fixed there.
- *
- * notFound() throws (NEXT_HTTP_ERROR_FALLBACK;404) and terminates rendering of
- * the segment, so nothing below it runs and the client component is never sent
- * to the browser. It does not need `return` - it is typed `never`.
+ * PER REQUEST: unstable_noStore() makes the segment dynamic, so a consumer's page is never prerendered with the build
+ * host's value. It is synchronous (the wrappers stay plain components, so PAY-3216's renderToString rows still hold) and
+ * a no-op outside a request. LIMIT: in Next 16 with cacheComponents (Dynamic I/O) it is a no-op too; the production
+ * roll's served check (both pages read back as 404 by request) is the row that would show it.
  */
 const navigation_1 = require("next/navigation");
+const cache_1 = require("next/cache");
+const token_pages_switch_1 = require("../../lib/token-pages-switch");
 const TestEnvPage_1 = require("./TestEnvPage");
 const JwtInspectPage_1 = require("./JwtInspectPage");
 const RefreshTokenPage_1 = require("./RefreshTokenPage");
 const EmergencyLogoutPage_1 = require("./EmergencyLogoutPage");
-/**
- * The single gate. Exact-match on purpose - see FAIL CLOSED above.
- *
- * Read at REQUEST time inside each page rather than once at module scope: a
- * module-scope constant would be captured at build time, so a consumer who
- * changed the variable would keep whatever value was baked into the bundle and
- * would have no way to tell. Reading per render costs an object property
- * lookup and removes an entire class of "I turned it off and it stayed on".
- */
-function testRoutesEnabled() {
-    return process.env.ENABLE_TEST_ROUTES === 'true';
-}
 function TestEnvPage() {
-    if (!testRoutesEnabled())
-        (0, navigation_1.notFound)();
     return (0, jsx_runtime_1.jsx)(TestEnvPage_1.TestEnvPage, {});
 }
-function JwtInspectPage() {
-    if (!testRoutesEnabled())
+/** PAY-3220: per request, then the switch. notFound() throws, so nothing below it renders and no client code is sent. */
+function refuseWhenTokenPagesOff() {
+    (0, cache_1.unstable_noStore)();
+    if ((0, token_pages_switch_1.tokenPagesOff)())
         (0, navigation_1.notFound)();
+}
+function JwtInspectPage() {
+    refuseWhenTokenPagesOff();
     return (0, jsx_runtime_1.jsx)(JwtInspectPage_1.JwtInspectPage, {});
 }
 function RefreshTokenPage() {
-    if (!testRoutesEnabled())
-        (0, navigation_1.notFound)();
+    refuseWhenTokenPagesOff();
     return (0, jsx_runtime_1.jsx)(RefreshTokenPage_1.RefreshTokenPage, {});
 }
 function EmergencyLogoutPage() {
-    if (!testRoutesEnabled())
-        (0, navigation_1.notFound)();
     return (0, jsx_runtime_1.jsx)(EmergencyLogoutPage_1.EmergencyLogoutPage, {});
 }

package/dist/pages/test-env/index.d.ts

@@ -7,8 +7,8 @@
  * and the block below is a four-line copy-paste that mounts every debug page
  * this package has. It previously carried no warning at all.
  *
- * NONE of these pages has an env gate of its own. Unlike the force-expire
- * handler (ENABLE_TEST_ROUTES) or the idp-token route
+ * NONE of these pages has an env gate of its own. Like the force-expire
+ * handler (no flag since PAY-3216) and unlike the idp-token route
  * (ENABLE_TOKEN_INSPECTOR), a mounted page is reachable exactly as far as your
  * middleware allows. MOUNTING IS THE GATE — so gate the WHOLE /test-env
  * segment, per environment, not page by page.
@@ -22,28 +22,19 @@
  *   RefreshTokenPage     Drives the destructive /api/test/force-expire.
  *   EmergencyLogoutPage  Mildest. Self-inflicted, recoverable.
  *
- * ── THESE PAGES ARE NOW ENV-GATED, FAIL-CLOSED (249259, BAPert ruling 35321) ──
- * SUPERSEDES the previous note here, which said a gate was impossible and that
- * mounting was the only control. That was correct about the PAGES and wrong as
- * a conclusion: it CANNOT be done inside these `'use client'` files, but it CAN
- * be done in a server component wrapping them. That wrapper now ships, and it
- * is what the four names below resolve to — see ./guarded.tsx.
- *
- *     ENABLE_TEST_ROUTES === 'true'   ->  the page renders
- *     anything else, including unset  ->  notFound()
- *
- * It is the DEFAULT, not an opt-in sibling: BAPert's ruling was explicit that
- * "an opt-in safety gate is one nobody opts into". The raw ungated components
- * are NOT exported. Same import path, same component names, same signatures —
- * consumers add one env var to their dev environments and change no code.
- *
- * ── MOUNTING IS STILL THE PRIMARY GATE ──────────────────────────────────────
- * Do not read the env var as making mounting safe. The wrapper is a backstop
- * for a mount that should not have happened. With ENABLE_TEST_ROUTES=true in an
- * environment where these are mounted you have exactly the exposure 248991
- * documented: a live session token, one click from the clipboard. If you are
- * not actively debugging, DO NOT MOUNT THESE AT ALL — the safest configuration
- * is still their absence, and the env var does not change that.
+ * ── NO ENV GATE (PAY-3216, Jon's order, 15 Nov) ─────────────────────────────
+ * The ENABLE_TEST_ROUTES gate that 1d40a8c (4.2.0, ruling 35321) put on these
+ * four pages is REMOVED: they render with no flag set, as before that commit.
+ * The ruling is withdrawn. MOUNTING IS THE GATE: a mounted page is reachable
+ * exactly as far as your middleware allows. Which of them a production site
+ * mounts is the site owner's choice.
+ *
+ * ── ONE PRODUCTION SWITCH (PAY-3220) ────────────────────────────────────────
+ * PAYEZ_TOKEN_PAGES_OFF, UNSET by default (every page works as above). Set on
+ * a production host, on Jon's word only, it makes JwtInspectPage,
+ * RefreshTokenPage and /api/test/force-expire answer 404. TestEnvPage and
+ * EmergencyLogoutPage are not covered. Read server-side per request; see
+ * lib/token-pages-switch for the values it accepts.
  *
  * Each page's own docstring carries the detail. If you are not actively
  * debugging, DO NOT MOUNT THESE AT ALL — the safest configuration is their

package/dist/pages/test-env/index.js

@@ -8,8 +8,8 @@
  * and the block below is a four-line copy-paste that mounts every debug page
  * this package has. It previously carried no warning at all.
  *
- * NONE of these pages has an env gate of its own. Unlike the force-expire
- * handler (ENABLE_TEST_ROUTES) or the idp-token route
+ * NONE of these pages has an env gate of its own. Like the force-expire
+ * handler (no flag since PAY-3216) and unlike the idp-token route
  * (ENABLE_TOKEN_INSPECTOR), a mounted page is reachable exactly as far as your
  * middleware allows. MOUNTING IS THE GATE — so gate the WHOLE /test-env
  * segment, per environment, not page by page.
@@ -23,28 +23,19 @@
  *   RefreshTokenPage     Drives the destructive /api/test/force-expire.
  *   EmergencyLogoutPage  Mildest. Self-inflicted, recoverable.
  *
- * ── THESE PAGES ARE NOW ENV-GATED, FAIL-CLOSED (249259, BAPert ruling 35321) ──
- * SUPERSEDES the previous note here, which said a gate was impossible and that
- * mounting was the only control. That was correct about the PAGES and wrong as
- * a conclusion: it CANNOT be done inside these `'use client'` files, but it CAN
- * be done in a server component wrapping them. That wrapper now ships, and it
- * is what the four names below resolve to — see ./guarded.tsx.
+ * ── NO ENV GATE (PAY-3216, Jon's order, 15 Nov) ─────────────────────────────
+ * The ENABLE_TEST_ROUTES gate that 1d40a8c (4.2.0, ruling 35321) put on these
+ * four pages is REMOVED: they render with no flag set, as before that commit.
+ * The ruling is withdrawn. MOUNTING IS THE GATE: a mounted page is reachable
+ * exactly as far as your middleware allows. Which of them a production site
+ * mounts is the site owner's choice.
  *
- *     ENABLE_TEST_ROUTES === 'true'   ->  the page renders
- *     anything else, including unset  ->  notFound()
- *
- * It is the DEFAULT, not an opt-in sibling: BAPert's ruling was explicit that
- * "an opt-in safety gate is one nobody opts into". The raw ungated components
- * are NOT exported. Same import path, same component names, same signatures —
- * consumers add one env var to their dev environments and change no code.
- *
- * ── MOUNTING IS STILL THE PRIMARY GATE ──────────────────────────────────────
- * Do not read the env var as making mounting safe. The wrapper is a backstop
- * for a mount that should not have happened. With ENABLE_TEST_ROUTES=true in an
- * environment where these are mounted you have exactly the exposure 248991
- * documented: a live session token, one click from the clipboard. If you are
- * not actively debugging, DO NOT MOUNT THESE AT ALL — the safest configuration
- * is still their absence, and the env var does not change that.
+ * ── ONE PRODUCTION SWITCH (PAY-3220) ────────────────────────────────────────
+ * PAYEZ_TOKEN_PAGES_OFF, UNSET by default (every page works as above). Set on
+ * a production host, on Jon's word only, it makes JwtInspectPage,
+ * RefreshTokenPage and /api/test/force-expire answer 404. TestEnvPage and
+ * EmergencyLogoutPage are not covered. Read server-side per request; see
+ * lib/token-pages-switch for the values it accepts.
  *
  * Each page's own docstring carries the detail. If you are not actively
  * debugging, DO NOT MOUNT THESE AT ALL — the safest configuration is their
@@ -67,9 +58,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.EmergencyLogoutPage = exports.RefreshTokenPage = exports.JwtInspectPage = exports.default = exports.TestEnvPage = void 0;
-// GUARDED wrappers only. Exporting the raw components from './TestEnvPage'
-// etc. would reintroduce an ungated path to the same pages under a different
-// import, which is the "opt-in gate nobody opts into" the ruling rejected.
+// Through the barrel (./guarded), as on main: it is PAY-3220's seam. Since PAY-3216 it renders each page with no flag.
 var guarded_1 = require("./guarded");
 Object.defineProperty(exports, "TestEnvPage", { enumerable: true, get: function () { return guarded_1.TestEnvPage; } });
 Object.defineProperty(exports, "default", { enumerable: true, get: function () { return guarded_1.TestEnvPage; } });

package/dist/routes/mfa/first-enrol-confirm.d.ts

@@ -0,0 +1,10 @@
+/**
+ * AUTH-045 first-enrolment: confirm the first authenticator code, clear the enrolment cookie, return the recovery codes. Mints no session.
+ *
+ * @example
+ * ```typescript
+ * // app/api/auth/first-enrol/confirm/route.ts
+ * export { POST } from '@payez/next-mvp/routes/mfa/first-enrol-confirm';
+ * ```
+ */
+export { POST_CONFIRM as POST } from '../../api-handlers/mfa/first-enrol';

package/dist/routes/mfa/first-enrol-confirm.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.POST = void 0;
+/**
+ * AUTH-045 first-enrolment: confirm the first authenticator code, clear the enrolment cookie, return the recovery codes. Mints no session.
+ *
+ * @example
+ * ```typescript
+ * // app/api/auth/first-enrol/confirm/route.ts
+ * export { POST } from '@payez/next-mvp/routes/mfa/first-enrol-confirm';
+ * ```
+ */
+var first_enrol_1 = require("../../api-handlers/mfa/first-enrol");
+Object.defineProperty(exports, "POST", { enumerable: true, get: function () { return first_enrol_1.POST_CONFIRM; } });

package/dist/routes/mfa/first-enrol-enroll.d.ts

@@ -0,0 +1,10 @@
+/**
+ * AUTH-045 first-enrolment: begin TOTP enrolment for a user the IdP told to enrol (uses ONLY the httpOnly enrolment cookie the credential door parked).
+ *
+ * @example
+ * ```typescript
+ * // app/api/auth/first-enrol/enroll/route.ts
+ * export { POST } from '@payez/next-mvp/routes/mfa/first-enrol-enroll';
+ * ```
+ */
+export { POST_ENROLL as POST } from '../../api-handlers/mfa/first-enrol';

package/dist/routes/mfa/first-enrol-enroll.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.POST = void 0;
+/**
+ * AUTH-045 first-enrolment: begin TOTP enrolment for a user the IdP told to enrol (uses ONLY the httpOnly enrolment cookie the credential door parked).
+ *
+ * @example
+ * ```typescript
+ * // app/api/auth/first-enrol/enroll/route.ts
+ * export { POST } from '@payez/next-mvp/routes/mfa/first-enrol-enroll';
+ * ```
+ */
+var first_enrol_1 = require("../../api-handlers/mfa/first-enrol");
+Object.defineProperty(exports, "POST", { enumerable: true, get: function () { return first_enrol_1.POST_ENROLL; } });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@payez/next-mvp",
-  "version": "4.13.1",
+  "version": "4.15.0",
   "sideEffects": false,
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -130,6 +130,11 @@
       "require": "./dist/lib/session-store.js",
       "default": "./dist/lib/session-store.js"
     },
+    "./lib/idp-logout": {
+      "types": "./dist/lib/idp-logout.d.ts",
+      "require": "./dist/lib/idp-logout.js",
+      "default": "./dist/lib/idp-logout.js"
+    },
     "./lib/nextauth-secret": {
       "types": "./dist/lib/nextauth-secret.d.ts",
       "require": "./dist/lib/nextauth-secret.js",
@@ -155,6 +160,11 @@
       "require": "./dist/lib/app-slug.js",
       "default": "./dist/lib/app-slug.js"
     },
+    "./lib/first-enrol": {
+      "types": "./dist/lib/first-enrol.d.ts",
+      "require": "./dist/lib/first-enrol.js",
+      "default": "./dist/lib/first-enrol.js"
+    },
     "./api-handlers/anon/preferences": {
       "types": "./dist/api-handlers/anon/preferences.d.ts",
       "require": "./dist/api-handlers/anon/preferences.js",
@@ -990,6 +1000,16 @@
       "require": "./dist/routes/mfa/totp-confirm.js",
       "default": "./dist/routes/mfa/totp-confirm.js"
     },
+    "./routes/mfa/first-enrol-enroll": {
+      "types": "./dist/routes/mfa/first-enrol-enroll.d.ts",
+      "require": "./dist/routes/mfa/first-enrol-enroll.js",
+      "default": "./dist/routes/mfa/first-enrol-enroll.js"
+    },
+    "./routes/mfa/first-enrol-confirm": {
+      "types": "./dist/routes/mfa/first-enrol-confirm.d.ts",
+      "require": "./dist/routes/mfa/first-enrol-confirm.js",
+      "default": "./dist/routes/mfa/first-enrol-confirm.js"
+    },
     "./routes/mfa/totp-verify": {
       "types": "./dist/routes/mfa/totp-verify.d.ts",
       "require": "./dist/routes/mfa/totp-verify.js",
@@ -1100,6 +1120,11 @@
       "require": "./dist/components/mfa/TotpEnrollPanel.js",
       "default": "./dist/components/mfa/TotpEnrollPanel.js"
     },
+    "./dist/pages/first-enroll": {
+      "types": "./dist/pages/first-enroll/page.d.ts",
+      "require": "./dist/pages/first-enroll/page.js",
+      "default": "./dist/pages/first-enroll/page.js"
+    },
     "./dist/pages/enroll": {
       "types": "./dist/pages/enroll/page.d.ts",
       "require": "./dist/pages/enroll/page.js",

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

@@ -49,6 +49,8 @@ import { DEVICE_ID_HEADER, isValidDeviceId } from '../../lib/device-id';
 import { classifyTwofaRejection, type TwofaLaneResult } from '../../lib/twofa-rejection';
 import { bearerFetch } from '../../lib/bearer-fetch';
 import { errForLog } from '../../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).
+import { ENROL_COOKIE, ENROL_COOKIE_MAX_AGE } from '../../lib/first-enrol';
 
 // `export const runtime = 'nodejs'` must be written LITERALLY in the app's route file (Next ignores a re-exported segment config).
 
@@ -348,6 +350,53 @@ export async function POST(req: NextRequest) {
     const vresult = verifyData?.data?.result ?? verifyData?.data ?? verifyData;
     const vAccess: string | undefined = vresult?.access_token;
     const vRefresh: string | undefined = 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 = 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(ENROL_COOKIE, vAccess, { httpOnly: true, secure: process.env.NODE_ENV === 'production', sameSite: 'strict', path: '/', maxAge: 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 NextResponse.json({ success: false, error: 'Authentication service returned an incomplete response' }, { status: 502 });

package/src/api-handlers/mfa/first-enrol.ts

@@ -0,0 +1,55 @@
+import { createHash } from 'node:crypto';
+import { NextRequest, NextResponse } from 'next/server';
+import { getIDPClientConfig } from '../../lib/idp-client-config';
+import { resolveClientKey } from '../../lib/client-key';
+import { NO_STORE, refuseNonJson } from '../../lib/mfa-json-guard';
+import { ENROL_COOKIE, LIMIT_PER_COOKIE, attemptAllowed, runEnrolStep, type EnrolStep } from '../../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: string) => createHash('sha256').update(s).digest('hex');
+
+const cookieOpts = (maxAge: number) => ({ httpOnly: true, secure: process.env.NODE_ENV === 'production', sameSite: 'strict' as const, path: '/', maxAge });
+
+function reply(status: number, body: Record<string, unknown>, clear: boolean): NextResponse {
+  const res = NextResponse.json(body, { status, headers: NO_STORE });
+  if (clear) res.cookies.set(ENROL_COOKIE, '', cookieOpts(0));
+  return res;
+}
+
+export function enrolStepPOST(step: EnrolStep) {
+  return async function POST(req: NextRequest): Promise<NextResponse> {
+    const refused = refuseNonJson(req);
+    if (refused) return refused;
+    const token = req.cookies.get(ENROL_COOKIE)?.value;
+    if (!token) return reply(401, { success: false, code: 'SIGN_IN_AGAIN' }, false);
+    if (!attemptAllowed(`${step}|ck|${digest(token)}`, 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 getIDPClientConfig();
+      clientKey = 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 runEnrolStep({ fetchImpl: (u, i) => fetch(u, i), idp, clientKey }, { step, token, body });
+    return reply(r.status, r.body, r.cookie === 'clear');
+  };
+}
+
+export const POST_ENROLL = enrolStepPOST('enroll');
+export const POST_CONFIRM = enrolStepPOST('confirm');

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

@@ -37,10 +37,18 @@ export async function POST(req: NextRequest) {
     );
   }
 
+  // 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: any = result.json;
-  if (bodyJson && typeof bodyJson === 'object' && 'success' in bodyJson && 'data' in bodyJson) {
-    if (bodyJson.success === true) return NextResponse.json(bodyJson.data, { status: 200, headers: NO_STORE });
-    return NextResponse.json(bodyJson, { status: 200, headers: NO_STORE });
-  }
-  return NextResponse.json(bodyJson ?? {}, { status: 200, headers: NO_STORE });
+  const enveloped = bodyJson && typeof bodyJson === 'object' && 'success' in bodyJson && 'data' in bodyJson;
+  const data: any = (enveloped ? (bodyJson.success === true ? bodyJson.data : null) : bodyJson) ?? {};
+  return NextResponse.json(
+    { confirmed: data.confirmed === true, stepped_up: data.stepped_up === true },
+    { status: 200, headers: NO_STORE },
+  );
 }

package/src/api-handlers/test/force-expire.ts

@@ -3,6 +3,7 @@ import { getSession as getBetterAuthSession } from '../../server/auth';
 import { getSession, updateSession } from '../../lib/session-store';
 import { logExceptionWithCorrelation } from '../../lib/safe-error-response';
 import { tokenLogId } from '../../lib/token-log-id';
+import { tokenPagesOff } from '../../lib/token-pages-switch';
 
 /**
  * ⚠️ DESTRUCTIVE TEST-ONLY HANDLER — DO NOT MOUNT IN PRODUCTION. ⚠️
@@ -20,19 +21,18 @@ import { tokenLogId } from '../../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';
  * ```
  *
@@ -40,67 +40,12 @@ import { tokenLogId } from '../../lib/token-log-id';
  * The safest configuration is the absence of the route.
  */
 export const POST = async (req: NextRequest) => {
-  // 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).',
-    );
+  // 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.
 
-    if (process.env.NODE_ENV === 'production') {
-      return new NextResponse(null, { status: 404 });
-    }
-
-    return 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-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 (tokenPagesOff()) return new NextResponse(null, { status: 404 });
 
   try {
     const betterAuthSession = await getBetterAuthSession(req);
@@ -120,11 +65,9 @@ export const POST = async (req: NextRequest) => {
     // 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