@payez/next-mvp 4.13.1 → 4.15.0

package/src/pages/test-env/JwtInspectPage.tsx

@@ -35,23 +35,25 @@ function decodeJwtPayload(token: string): any {
  * IN PRODUCTION. ⚠️
  *
  * Session Inspector Page. Debug page for inspecting session data from Redis:
- * shows user info, roles, 2FA status, and TOKENS. It offers
- * COPY-TO-CLIPBOARD buttons for the live SESSION TOKEN and ACCESS TOKEN, and
- * reads them from the consuming app's `/api/internal/session-data` route.
+ * shows user info, roles, 2FA status, and the DECODED CLAIMS of the IDP access
+ * token, which it reads from the consuming app's `/api/internal/session-data`
+ * route. Credentials themselves are shown as tokenLogId + length ONLY: the
+ * Copy-to-clipboard and Reveal controls this docstring used to describe were
+ * removed by PAY-1470 (BAPert 59022, 59040), and test-env-no-token-material
+ * holds the page to that. (PAY-3220: this sentence was stale until now.)
  *
  * ────────────────────────── WHY THIS WARNING EXISTS (QAPert 35000 / 248991) ──────────────────────────
- * THIS PAGE HAS NO ENV GATE OF ITS OWN. Unlike the force-expire handler
- * (default-denied behind ENABLE_TEST_ROUTES) or the idp-token route (behind
- * ENABLE_TOKEN_INSPECTOR), a mounted page is reachable exactly as far as the
- * consuming app's own middleware allows. MOUNTING IT IS THE GATE. There is no
- * second line of defence behind it.
+ * Like the force-expire handler (no flag since PAY-3216) and unlike the
+ * idp-token route (behind ENABLE_TOKEN_INSPECTOR), a mounted page is reachable
+ * exactly as far as the consuming app's own middleware allows. MOUNTING IT IS
+ * THE GATE. The one switch on it is PAYEZ_TOKEN_PAGES_OFF (PAY-3220), unset by
+ * default and set only on a production host on Jon's word.
  *
- * AND THE CREDENTIAL IT HANDS OVER IS THE PRECONDITION FOR A REAL ATTACK ON
- * THIS SAME PACKAGE. The 246007 finding reduces to "a caller who KNOWS A
- * SESSION TOKEN can act on a session it does not own". The purpose of this
- * page is to put a live session token on the clipboard of whoever loads it. A
- * screen-share, a shoulder-surfed screenshot or a support call is enough.
- * Treat the rendered value as a live credential, because that is what it is.
+ * WHAT IT STILL HANDS OVER IS SENSITIVE. The decoded claims say who the
+ * signed-in person is, which roles they hold and how they authenticated, and
+ * the 246007 finding reduces to "a caller who KNOWS A SESSION TOKEN can act on
+ * a session it does not own": a page that once showed that token is the reason
+ * this one is treated as a production hazard.
  *
  * NOTE FOR MAINTAINERS: this warning must stay on THIS docstring, the one
  * attached to the exported declaration. An identical block placed higher in

package/src/pages/test-env/RefreshTokenPage.tsx

@@ -14,25 +14,22 @@ import { redactCredentials } from './redact-credentials';
  * `/api/test/force-expire`. That endpoint MUTATES SESSION STATE.
  *
  * ────────────────────────── WHY THIS WARNING EXISTS (QAPert 35000) ──────────────────────────
- * The force-expire HANDLER was fixed (244877: default-deny behind
- * ENABLE_TEST_ROUTES) and its docstring corrected to say so — but that fix
- * covered the ROUTE AND NOT THE PAGE THAT DRIVES IT. This page is a separate
+ * The force-expire HANDLER was fixed (244877) and its docstring corrected to
+ * say so — but that fix covered the ROUTE AND NOT THE PAGE THAT DRIVES IT. This page is a separate
  * public export carrying its own mount instructions, so a consumer can follow
  * these lines and never once read the handler's warning.
  *
- * THIS PAGE HAS NO ENV GATE OF ITS OWN. Mounting it is the gate. The two are
- * independent: mounting this page while ENABLE_TEST_ROUTES is unset gives you
- * a button that 404s — confusing, but safe. The unsafe configuration is
- * setting that flag anywhere this page is also reachable.
+ * THIS PAGE HAS NO ENV GATE OF ITS OWN, and since PAY-3216 neither has the
+ * handler it drives: mounting is the gate. Wherever this page and the
+ * force-expire route are both mounted, the button works.
  *
  * ────────────────────────── IF YOU MOUNT IT, MOUNT IT LIKE THIS ──────────────────────────
  * ```typescript
  * // app/test-env/refresh-token/page.tsx   — TEST/DEV ENVIRONMENTS ONLY
  * export { RefreshTokenPage as default } from '@payez/next-mvp/pages/test-env';
  * ```
- * Requires ENABLE_TEST_ROUTES=true IN THAT ENVIRONMENT ONLY for the button to
- * do anything. Never set it in production. If you do not need to exercise the
- * refresh flow, DO NOT MOUNT THIS AT ALL.
+ * The button needs /api/test/force-expire mounted too; there is no flag. If
+ * you do not need to exercise the refresh flow, DO NOT MOUNT THIS AT ALL.
  */
 export function RefreshTokenPage() {
   const { data: session } = authClient.useSession();

package/src/pages/test-env/guarded.tsx

@@ -1,81 +1,47 @@
 /**
- * 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.
  */
 import { notFound } from 'next/navigation';
-
+import { unstable_noStore as noStore } from 'next/cache';
+import { tokenPagesOff } from '../../lib/token-pages-switch';
 import { TestEnvPage as TestEnvPageUnguarded } from './TestEnvPage';
 import { JwtInspectPage as JwtInspectPageUnguarded } from './JwtInspectPage';
 import { RefreshTokenPage as RefreshTokenPageUnguarded } from './RefreshTokenPage';
 import { EmergencyLogoutPage as EmergencyLogoutPageUnguarded } from './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(): boolean {
-  return process.env.ENABLE_TEST_ROUTES === 'true';
-}
-
 export function TestEnvPage() {
-  if (!testRoutesEnabled()) notFound();
   return <TestEnvPageUnguarded />;
 }
 
+/** PAY-3220: per request, then the switch. notFound() throws, so nothing below it renders and no client code is sent. */
+function refuseWhenTokenPagesOff(): void {
+  noStore();
+  if (tokenPagesOff()) notFound();
+}
+
 export function JwtInspectPage() {
-  if (!testRoutesEnabled()) notFound();
+  refuseWhenTokenPagesOff();
   return <JwtInspectPageUnguarded />;
 }
 
 export function RefreshTokenPage() {
-  if (!testRoutesEnabled()) notFound();
+  refuseWhenTokenPagesOff();
   return <RefreshTokenPageUnguarded />;
 }
 
 export function EmergencyLogoutPage() {
-  if (!testRoutesEnabled()) notFound();
   return <EmergencyLogoutPageUnguarded />;
 }

package/src/pages/test-env/index.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.
+ * ── 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
@@ -65,9 +56,7 @@
  * ```
  */
 
-// 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.
 export {
     TestEnvPage,
     TestEnvPage as default,

package/src/routes/mfa/first-enrol-confirm.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/src/routes/mfa/first-enrol-enroll.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';