@payez/next-mvp 4.14.0 → 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@payez/next-mvp",
-  "version": "4.14.0",
+  "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",

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

package/src/auth/better-auth.ts

@@ -27,13 +27,13 @@ import {
   type IdpVerifiedClaims,
 } from './idp-oauth';
 import type { IDPClientConfig } from '../lib/idp-client-config';
-import { getIDPClientConfig } from '../lib/idp-client-config';
+import { getIDPClientConfig, providerSecretEnvVar } from '../lib/idp-client-config';
 import { getAppSlug, assertAppSlugMatchesIdp } from '../lib/app-slug';
 import { getRedis } from '../lib/redis';
 import { createSingleFlight, type SingleFlight } from '../lib/single-flight';
 import { SESSION_TTL } from '../lib/session-store';
 import { tokenLogId } from '../lib/token-log-id';
-import { errForLog } from '../lib/log-safe';
+import { errForLog, logSafeName } from '../lib/log-safe';
 import { warnIfMagicLinkBelowFix } from './better-auth-exposure';
 import { noStore } from '../lib/no-store';
 
@@ -277,6 +277,28 @@ export function buildIdpOAuthProviderConfig(appBaseUrl?: string): IdpOAuthProvid
   };
 }
 
+/**
+ * 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 function missingProviderCredentials(
+  name: string,
+  oauth: { clientId?: string | null; clientSecret?: string | null }
+): Array<'clientId' | 'clientSecret'> {
+  const required: Array<'clientId' | 'clientSecret'> =
+    name === 'google' ? ['clientId', 'clientSecret'] : ['clientId'];
+  return required.filter((field) => String(oauth[field] ?? '').trim() === '');
+}
+
+
 export function buildBetterAuthProviders(
   config: IDPClientConfig
 ): Record<string, BetterAuthSocialProvider> {
@@ -285,6 +307,26 @@ export function buildBetterAuthProviders(
   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 ${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=${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/src/lib/idp-client-config.ts

@@ -44,7 +44,7 @@ import 'server-only';
 import { createHash, randomUUID } from 'crypto';
 import { markNeverInResponse } from './never-in-response';
 import { clientSecretBody, warnIfProviderSecretRedacted } from './payez-client-secret';
-import { errForLog } from './log-safe';
+import { errForLog, logSafeName } from './log-safe';
 // REDIS IS IMPORTED LAZILY, AND THAT IS LOAD-BEARING.
 // A module-scope `import redis from './redis'` drags ioredis into EVERY bundle that
 // touches this file - including instrumentation.ts. Next compiles the instrumentation
@@ -225,7 +225,7 @@ function applyEnvSecrets(config: IDPClientConfig): IDPClientConfig {
             const envVar = providerSecretEnvVar(p.provider);
             const fromEnv = process.env[envVar];
             const source: SecretSource = fromEnv ? `env:${envVar}` : p.clientSecret ? 'idp-config' : 'none';
-            logSecretSource(`${p.provider} clientSecret`, source);
+            logSecretSource(`${logSafeName(p.provider)} clientSecret`, source);
             const clientSecret = fromEnv || p.clientSecret;
             markNeverInResponse(clientSecret);
             return { ...p, clientSecret };

package/src/lib/log-safe.ts

@@ -28,3 +28,12 @@ export function errForLog(err: unknown): string {
   const code = closed ? ` code=${closed}` : '';
   return `error=${name}${status}${code}`;
 }
+
+/**
+ * A provider name (or any other IdP-supplied identifier) for a log line: lower-cased, then anything outside [a-z0-9_-] becomes '?',
+ * so a name carrying a newline cannot forge a second log line (Nextpert-Scout 102543 LOW 1; the shared helper per 104626, used at
+ * every site that logs an IdP provider name: better-auth.ts, payez-client-secret.ts, idp-client-config.ts).
+ */
+export function logSafeName(name: unknown): string {
+  return String(name ?? '').toLowerCase().replace(/[^a-z0-9_-]/g, '?');
+}

package/src/lib/payez-client-secret.ts

@@ -5,6 +5,7 @@
  * what it sent before. The value is never logged and never leaves in a response (markNeverInResponse).
  */
 import { markNeverInResponse } from './never-in-response';
+import { logSafeName } from './log-safe';
 
 export const CLIENT_SECRET_ENV = 'PAYEZ_CLIENT_SECRET';
 
@@ -34,6 +35,6 @@ export function warnIfProviderSecretRedacted(
         if (process.env[envVarFor(p.provider)]) continue;
         if (warnedProviders.has(p.provider)) continue;
         warnedProviders.add(p.provider);
-        console.warn(`[IDP_CONFIG] PAYEZ_PROVIDER_SECRET_MISSING_REDACTED provider=${p.provider}`);
+        console.warn(`[IDP_CONFIG] PAYEZ_PROVIDER_SECRET_MISSING_REDACTED provider=${logSafeName(p.provider)}`);
     }
 }

package/src/lib/token-pages-switch.ts

@@ -0,0 +1,44 @@
+/**
+ * PAY-3220 (ruled Win 105653 s1, on NextPert-MB's Mac 105619): the ONE production switch for the two token-showing
+ * test-env pages (JwtInspectPage, RefreshTokenPage) and the route the refresh page drives (POST /api/test/force-expire).
+ *
+ *   PAYEZ_TOKEN_PAGES_OFF   unset or empty            -> ON  (every page works as today; the default everywhere)
+ *                           true / 1 / yes / on       -> OFF (any letter case)
+ *                           false / 0 / no / off      -> ON  (any letter case), no warning
+ *                           anything else             -> OFF, and ONE warning per process naming the variable
+ *
+ * Why an unrecognised value is OFF (the ruling's one change to the recommendation): nobody sets this variable except to
+ * turn the pages off, on Jon's word, on a production host. A mistyped attempt to turn them off must not leave
+ * token-showing pages on in production with only a log line to say so.
+ *
+ * Read from the server's process environment on every call, never captured at module scope (a module constant would be
+ * whatever the build host had). It is not NEXT_PUBLIC_, so it never reaches a client bundle, and no request input
+ * (cookie, header, query string, body, session) is consulted: only whoever can change the host's environment can turn it.
+ *
+ * Set ONLY on a production host, ONLY on Jon's word, on the day production is real. It is never in a tracked .env file.
+ * The switch is not counted as set until the production roll's served check reads both pages and force-expire back as
+ * 404 by request (BAPert-MB 105629 s3).
+ */
+export const TOKEN_PAGES_OFF_ENV = 'PAYEZ_TOKEN_PAGES_OFF';
+
+const OFF_WORDS = new Set(['true', '1', 'yes', 'on']);
+const ON_WORDS = new Set(['false', '0', 'no', 'off']);
+let warnedUnrecognised = false;
+
+export function tokenPagesOff(): boolean {
+  const raw = process.env[TOKEN_PAGES_OFF_ENV];
+  if (raw === undefined) return false;
+  const value = raw.trim().toLowerCase();
+  if (value === '') return false;
+  if (OFF_WORDS.has(value)) return true;
+  if (ON_WORDS.has(value)) return false;
+  if (!warnedUnrecognised) {
+    warnedUnrecognised = true;
+    // The variable's NAME only. The value is not a secret, but nothing about it helps the reader of this line.
+    console.warn(
+      `[test-env] ${TOKEN_PAGES_OFF_ENV} is set to a value that is not recognised (true/1/yes/on or false/0/no/off); ` +
+        'the token pages are OFF: jwt-inspect, refresh-token and POST /api/test/force-expire answer 404.',
+    );
+  }
+  return true;
+}

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