@payez/next-mvp 4.14.0 → 4.15.0

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog — @payez/next-mvp
 
+## 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.

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/lib/idp-client-config.js

@@ -162,7 +162,7 @@ function applyEnvSecrets(config) {
             const envVar = providerSecretEnvVar(p.provider);
             const fromEnv = process.env[envVar];
             const source = fromEnv ? `env:${envVar}` : p.clientSecret ? 'idp-config' : 'none';
-            logSecretSource(`${p.provider} clientSecret`, source);
+            logSecretSource(`${(0, log_safe_1.logSafeName)(p.provider)} clientSecret`, source);
             const clientSecret = fromEnv || p.clientSecret;
             (0, never_in_response_1.markNeverInResponse)(clientSecret);
             return { ...p, clientSecret };

package/dist/lib/log-safe.d.ts

@@ -17,3 +17,9 @@ export declare function closedCodeForLog(code: unknown): string | null;
  * `NonError`; a status outside 100-599 is dropped; a code outside the closed token shape is dropped.
  */
 export declare function errForLog(err: unknown): string;
+/**
+ * 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 declare function logSafeName(name: unknown): string;

package/dist/lib/log-safe.js

@@ -13,6 +13,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.closedCodeForLog = closedCodeForLog;
 exports.errForLog = errForLog;
+exports.logSafeName = logSafeName;
 /** An upstream `code` is loggable only if it is a closed token (UPPER_SNAKE). Anything else, including free text, becomes null. */
 function closedCodeForLog(code) {
     return typeof code === 'string' && /^[A-Z0-9_]{1,64}$/.test(code) ? code : null;
@@ -30,3 +31,11 @@ function errForLog(err) {
     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).
+ */
+function logSafeName(name) {
+    return String(name ?? '').toLowerCase().replace(/[^a-z0-9_-]/g, '?');
+}

package/dist/lib/payez-client-secret.js

@@ -10,6 +10,7 @@ exports.warnIfProviderSecretRedacted = warnIfProviderSecretRedacted;
  * what it sent before. The value is never logged and never leaves in a response (markNeverInResponse).
  */
 const never_in_response_1 = require("./never-in-response");
+const log_safe_1 = require("./log-safe");
 exports.CLIENT_SECRET_ENV = 'PAYEZ_CLIENT_SECRET';
 /** `{ client_secret }` when the env var is set to a non-blank value, else `{}`. Spread it into a JSON body. */
 function clientSecretBody() {
@@ -36,6 +37,6 @@ function warnIfProviderSecretRedacted(redactedHeader, providers, envVarFor) {
         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=${(0, log_safe_1.logSafeName)(p.provider)}`);
     }
 }

package/dist/lib/token-pages-switch.d.ts

@@ -0,0 +1,23 @@
+/**
+ * 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 declare const TOKEN_PAGES_OFF_ENV = "PAYEZ_TOKEN_PAGES_OFF";
+export declare function tokenPagesOff(): boolean;

package/dist/lib/token-pages-switch.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TOKEN_PAGES_OFF_ENV = void 0;
+exports.tokenPagesOff = tokenPagesOff;
+/**
+ * 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).
+ */
+exports.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;
+function tokenPagesOff() {
+    const raw = process.env[exports.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] ${exports.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/dist/pages/test-env/JwtInspectPage.d.ts

@@ -3,23 +3,25 @@
  * 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/dist/pages/test-env/JwtInspectPage.js

@@ -39,23 +39,25 @@ function decodeJwtPayload(token) {
  * 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/dist/pages/test-env/RefreshTokenPage.d.ts

@@ -7,25 +7,22 @@
  * `/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 declare function RefreshTokenPage(): import("react/jsx-runtime").JSX.Element;
 export default RefreshTokenPage;

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

@@ -17,25 +17,22 @@ const redact_credentials_1 = require("./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.
  */
 function RefreshTokenPage() {
     const { data: session } = better_auth_client_1.authClient.useSession();