@payez/next-mvp 4.1.21 → 4.4.0

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

@@ -30,16 +30,41 @@ function decodeJwtPayload(token: string): any {
 }
 
 /**
- * Session Inspector Page
+ * ⚠️ DEBUG PAGE THAT DISPLAYS AND COPIES LIVE CREDENTIALS — DO NOT MOUNT
+ * IN PRODUCTION. ⚠️
  *
- * Debug page for inspecting session data from Redis.
- * Shows user info, roles, 2FA status, and tokens.
+ * 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.
  *
- * Usage in consuming app:
+ * ────────────────────────── 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.
+ *
+ * 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.
+ *
+ * NOTE FOR MAINTAINERS: this warning must stay on THIS docstring, the one
+ * attached to the exported declaration. An identical block placed higher in
+ * the file does NOT reach the emitted .d.ts — measured, after I made exactly
+ * that mistake — so it would warn no consumer at all.
+ *
+ * ────────────────────────── IF YOU MOUNT IT, MOUNT IT LIKE THIS ──────────────────────────
  * ```typescript
- * // app/test-env/jwt-inspect/page.tsx
+ * // app/test-env/jwt-inspect/page.tsx   — TEST/DEV ENVIRONMENTS ONLY
  * export { JwtInspectPage as default } from '@payez/next-mvp/pages/test-env';
  * ```
+ * Gate the whole /test-env segment in your middleware, per environment. If you
+ * are not actively debugging token contents, DO NOT MOUNT THIS AT ALL — the
+ * safest configuration is the absence of the route.
  */
 export function JwtInspectPage() {
   const { data: sessionData, isPending } = authClient.useSession();
@@ -84,6 +109,111 @@ export function JwtInspectPage() {
     }
   }, [serverSession, session]);
 
+  // 248991 item 3 (QAPert 35021) - CREDENTIALS ARE REDACTED UNTIL DELIBERATELY
+  // REVEALED.
+  //
+  // Before this, loading the page put a live session token on screen and one
+  // click from the clipboard. That is the precondition the 246007 finding needs
+  // ("a caller who knows a session token can act on a session it does not own"),
+  // so this page was the supply side of the attack the same package was being
+  // hardened against. A screen-share, a screenshot or a support call was enough.
+  //
+  // The fix is deliberately NOT removing the tokens or the copy button: replaying
+  // a bearer in curl is the entire reason this tool exists, and a debug tool that
+  // cannot show you the thing you are debugging just gets replaced by a worse
+  // ad-hoc one. What changes is that exposure now requires an INTENTIONAL ACT per
+  // token, so the default state of a loaded page - the state a bystander, a
+  // screen-share or a screenshot captures - carries no usable credential.
+  //
+  // NOTE: this is a UI affordance, not an access control. Anyone who can load
+  // this page can still click reveal, and the values are in the network response
+  // either way. It shrinks accidental disclosure; it does not gate the route.
+  // The gate is mounting - see this file's docstring and index.ts.
+  const [revealed, setRevealed] = useState<Record<string, boolean>>({});
+
+  const maskToken = (value: string): string => {
+    if (value.length <= 12) return '\u2022'.repeat(Math.max(value.length, 8));
+    return `${value.slice(0, 6)}${'\u2022'.repeat(12)}${value.slice(-4)}  (${value.length} chars, hidden)`;
+  };
+
+  // Keys whose STRING values are live credentials. Anchored at the END of the key
+  // name on purpose: it catches sessionToken / accessToken / refreshToken /
+  // idpRefreshToken, while deliberately NOT catching the metadata beside them -
+  // accessTokenExpires, idpAccessTokenExpires, tokenType - which are safe and are
+  // the fields you actually want when debugging an expiry problem.
+  const CREDENTIAL_KEY = /(token|secret|password|apikey|credential)$/i;
+
+  // VALUE-SHAPE checks, because a key-name sweep has a blind spot that this page
+  // is squarely in: a credential under an innocuous key. Scout hit the same class
+  // elsewhere today (35297) - a postgres URL whose only key-name hit was a
+  // POINTER to the secret, while the actual password sat in the URL value and the
+  // sweep scored the file SAFE. Here the equivalents are a raw JWT parked under
+  // `jwt` / `bearer` / `authorization` / `cookie` - none of which end in `token`.
+  //
+  // JWT: three base64url segments. The length floors matter - without them
+  // "4.1.42" matches the three-segment shape and the package version would render
+  // as a redacted credential, which teaches people the redactor is broken.
+  const looksLikeJwt = (v: string): boolean => {
+    if (v.length < 40) return false;
+    const parts = v.split('.');
+    return parts.length === 3 && parts.every((p) => p.length >= 8 && /^[A-Za-z0-9_-]+$/.test(p));
+  };
+
+  // scheme://user:password@host - redact ONLY the password and keep the rest, so
+  // the URL stays usable for debugging. Masking the whole value would hide which
+  // host you are pointed at, which is usually the thing you opened this page for.
+  const URL_WITH_USERINFO = /^([a-z][a-z0-9+.-]*:\/\/)([^/\s:@]+):([^/\s@]+)@/i;
+
+  // Third value-shape check, on DotNetPert-Scout's 251951 rule: "a content-pattern
+  // sweep CANNOT find a credential that has no pattern." A PEM block defeats BOTH
+  // checks above and the key-name check as well - it has no key=value pair, its key
+  // name is usually something innocuous like `cert`, `pem`, `chain` or `data`, it is
+  // not three base64url segments so looksLikeJwt rejects it, and it is not a URL.
+  // He found a live wildcard TLS private key that had sat committed for 215 days for
+  // exactly this reason: it was never in anyone's search space, missed by
+  // construction rather than by carelessness.
+  //
+  // HONEST SCOPE: this is defence-in-depth, not a measured exposure. I have not seen
+  // PEM material in a session object and would not expect to. It is here because this
+  // dump renders WHATEVER the session carries, and the entire lesson of the two
+  // previous hardenings on this function is that the next credential arrives in a
+  // shape the current checks were not written for. Matching the armour band rather
+  // than the payload costs one regex.
+  // Matches the PEM ARMOUR BAND itself rather than enumerating key types. A first
+  // draft listed PRIVATE KEY / CERTIFICATE / RSA / EC / OPENSSH / PGP and a test
+  // caught it missing plain "-----BEGIN CERTIFICATE-----", because that header has
+  // no space before the closing dashes while "-----BEGIN RSA PRIVATE KEY-----" does.
+  // Enumerating the payload types is the same mistake as enumerating credential key
+  // names, one level down: it only ever covers the shapes already thought of.
+  // Requiring an alphanumeric after "BEGIN " keeps prose containing the word, and a
+  // bare "-----BEGIN-----", from matching.
+  const PEM_BLOCK = /-----BEGIN [A-Z0-9][A-Z0-9 ]*-----/;
+
+  // 248991 item 3, SECOND HALF. The masked fields above were only half the fix:
+  // the Raw Session Data block below re-rendered the SAME tokens in plain text via
+  // JSON.stringify, one click away behind a neutral "Click to expand" summary - and
+  // with them idpRefreshToken, which has NO other raw surface on this page (it is
+  // rendered as a boolean at the Refresh Token row precisely because it is the
+  // longest-lived credential of the three). Redacting per-field while dumping the
+  // whole object verbatim is not a partial fix, it is the appearance of one.
+  const redactCredentials = (value: unknown, keyName = ''): unknown => {
+    if (Array.isArray(value)) return value.map((v) => redactCredentials(v));
+    if (value && typeof value === 'object') {
+      return Object.fromEntries(
+        Object.entries(value as Record<string, unknown>).map(([k, v]) => [k, redactCredentials(v, k)]),
+      );
+    }
+    if (typeof value !== 'string' || value.length === 0) return value;
+    if (CREDENTIAL_KEY.test(keyName)) return maskToken(value);
+    // Key-name matching alone is not enough (DotNetPert-Scout 35297): a credential
+    // can sit under a key that is not credential-shaped at all. Two value-shape
+    // checks close the cases that actually reach a session object:
+    if (looksLikeJwt(value)) return maskToken(value);
+    if (PEM_BLOCK.test(value)) return '••• PEM block redacted (' + value.length + ' chars) •••';
+    if (URL_WITH_USERINFO.test(value)) return value.replace(URL_WITH_USERINFO, '$1$2:•••••@');
+    return value;
+  };
+
   const copyToClipboard = (text: string, label: string) => {
     navigator.clipboard.writeText(text);
     setCopied(label);
@@ -242,15 +372,28 @@ export function JwtInspectPage() {
               <div className="flex items-center justify-between mb-2">
                 <span className={labelClass}>Session Token (Redis Key):</span>
                 {displayExt.sessionToken && (
-                  <CopyButton
-                    onClick={() => copyToClipboard(displayExt.sessionToken, 'session')}
-                    copied={copied === 'session'}
-                    isDarkMode={isDarkMode}
-                  />
+                  <div className="flex items-center gap-2">
+                    <RevealButton
+                      revealed={!!revealed.session}
+                      onClick={() => setRevealed((r) => ({ ...r, session: !r.session }))}
+                      isDarkMode={isDarkMode}
+                    />
+                    {revealed.session && (
+                      <CopyButton
+                        onClick={() => copyToClipboard(displayExt.sessionToken, 'session')}
+                        copied={copied === 'session'}
+                        isDarkMode={isDarkMode}
+                      />
+                    )}
+                  </div>
                 )}
               </div>
               <code className={`block p-2 rounded text-xs break-all ${isDarkMode ? 'bg-slate-800' : 'bg-gray-100'}`}>
-                {displayExt.sessionToken || 'N/A'}
+                {displayExt.sessionToken
+                  ? revealed.session
+                    ? displayExt.sessionToken
+                    : maskToken(displayExt.sessionToken)
+                  : 'N/A'}
               </code>
             </div>
 
@@ -258,15 +401,28 @@ export function JwtInspectPage() {
               <div className="flex items-center justify-between mb-2">
                 <span className={labelClass}>Access Token (IDP):</span>
                 {displayExt.accessToken && (
-                  <CopyButton
-                    onClick={() => copyToClipboard(displayExt.accessToken, 'access')}
-                    copied={copied === 'access'}
-                    isDarkMode={isDarkMode}
-                  />
+                  <div className="flex items-center gap-2">
+                    <RevealButton
+                      revealed={!!revealed.access}
+                      onClick={() => setRevealed((r) => ({ ...r, access: !r.access }))}
+                      isDarkMode={isDarkMode}
+                    />
+                    {revealed.access && (
+                      <CopyButton
+                        onClick={() => copyToClipboard(displayExt.accessToken, 'access')}
+                        copied={copied === 'access'}
+                        isDarkMode={isDarkMode}
+                      />
+                    )}
+                  </div>
                 )}
               </div>
               <code className={`block p-2 rounded text-xs break-all max-h-24 overflow-auto ${isDarkMode ? 'bg-slate-800' : 'bg-gray-100'}`}>
-                {displayExt.accessToken || 'N/A'}
+                {displayExt.accessToken
+                  ? revealed.access
+                    ? displayExt.accessToken
+                    : maskToken(displayExt.accessToken)
+                  : 'N/A'}
               </code>
             </div>
 
@@ -370,11 +526,31 @@ export function JwtInspectPage() {
           </div>
         </div>
 
-        {/* Raw Session Data */}
+        {/* Raw Session Data - credentials redacted by default, see redactCredentials above */}
         <details className={`p-4 rounded-lg ${cardClass}`}>
-          <summary className="font-semibold cursor-pointer">Raw Session Data (Click to expand)</summary>
+          <summary className="font-semibold cursor-pointer">
+            Raw Session Data &mdash; credentials redacted (Click to expand)
+          </summary>
+          <div className="mt-3 flex items-center gap-3">
+            <RevealButton
+              revealed={!!revealed.raw}
+              onClick={() => setRevealed((r) => ({ ...r, raw: !r.raw }))}
+              isDarkMode={isDarkMode}
+            />
+            <span className={`text-xs ${labelClass}`}>
+              {revealed.raw
+                ? 'Showing LIVE credentials in plain text, including the refresh token.'
+                : 'Token values are masked. Structure, claims and expiry fields are unchanged.'}
+            </span>
+          </div>
           <pre className={`mt-4 text-xs overflow-auto p-3 rounded ${isDarkMode ? 'bg-slate-800' : 'bg-gray-100'}`}>
-            {JSON.stringify({ clientSession: session, serverSession: serverSession }, null, 2)}
+            {JSON.stringify(
+              revealed.raw
+                ? { clientSession: session, serverSession: serverSession }
+                : redactCredentials({ clientSession: session, serverSession: serverSession }),
+              null,
+              2,
+            )}
           </pre>
         </details>
       </div>
@@ -453,4 +629,43 @@ function CopyButton({
   );
 }
 
+/**
+ * Reveal toggle for a redacted credential (248991 item 3).
+ *
+ * Deliberately labelled "Reveal token" rather than something neutral like
+ * "Show": the label is the last chance to tell whoever is about to click it,
+ * possibly while screen-sharing, that a live credential is about to appear.
+ */
+function RevealButton({
+  revealed,
+  onClick,
+  isDarkMode,
+}: {
+  revealed: boolean;
+  onClick: () => void;
+  isDarkMode: boolean;
+}) {
+  return (
+    <button
+      onClick={onClick}
+      title={
+        revealed
+          ? 'Hide this credential again'
+          : 'Reveals a LIVE credential in plain text. Not while screen-sharing.'
+      }
+      className={`px-2 py-1 rounded text-xs ${
+        revealed
+          ? isDarkMode
+            ? 'bg-amber-700 hover:bg-amber-600 text-white'
+            : 'bg-amber-200 hover:bg-amber-300 text-amber-900'
+          : isDarkMode
+            ? 'bg-slate-700 hover:bg-slate-600 text-white'
+            : 'bg-gray-200 hover:bg-gray-300 text-gray-700'
+      }`}
+    >
+      {revealed ? 'Hide' : 'Reveal token'}
+    </button>
+  );
+}
+
 export default JwtInspectPage;

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

@@ -3,17 +3,33 @@ import React, { useState, useEffect } from "react";
 import { authClient } from '../../client/better-auth-client';
 
 /**
- * Refresh Token Test Page
+ * ⚠️ DEBUG PAGE THAT DRIVES A DESTRUCTIVE ENDPOINT — DO NOT MOUNT IN
+ * PRODUCTION. ⚠️
  *
- * Debug page for testing OAuth refresh token flow.
- * Shows current session state, allows manual refresh trigger,
- * and can force-expire tokens for testing.
+ * Refresh Token Test Page. Shows current session state, allows a manual
+ * refresh trigger, and FORCE-EXPIRES the access token via a button that POSTs
+ * `/api/test/force-expire`. That endpoint MUTATES SESSION STATE.
  *
- * Usage:
+ * ────────────────────────── 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
+ * 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.
+ *
+ * ────────────────────────── IF YOU MOUNT IT, MOUNT IT LIKE THIS ──────────────────────────
  * ```typescript
- * // app/test-env/refresh-token/page.tsx
+ * // 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.
  */
 export function RefreshTokenPage() {
   const { data: session } = authClient.useSession();

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

@@ -5,13 +5,25 @@ import { useState, useEffect } from 'react';
 import Link from 'next/link';
 
 /**
- * Test Environment Index Page
+ * ⚠️ DEBUG INDEX — DO NOT MOUNT IN PRODUCTION. ⚠️
  *
- * Debug tools index showing session status and links to debug pages.
+ * Test Environment Index Page. Shows session status and links to the other
+ * debug pages.
  *
- * Usage in consuming app:
+ * ────────────────────────── WHY THE INDEX IS ITS OWN FINDING (QAPert 35000 sweep) ──────────────────────────
+ * This page is DISCOVERY. On its own it only reads session status, so in
+ * isolation it looks like the harmless member of the set — but it
+ * ADVERTISES the sibling routes to anyone who reaches it, including the JWT
+ * inspector that puts a live session token on the clipboard. Mounting this
+ * turns four URLs somebody would otherwise have to guess into one linked
+ * index.
+ *
+ * If you mount the /test-env segment at all, gate the WHOLE SEGMENT in your
+ * middleware, per environment — not page by page.
+ *
+ * ────────────────────────── IF YOU MOUNT IT, MOUNT IT LIKE THIS ──────────────────────────
  * ```typescript
- * // app/test-env/page.tsx
+ * // app/test-env/page.tsx   — TEST/DEV ENVIRONMENTS ONLY
  * export { TestEnvPage as default } from '@payez/next-mvp/pages/test-env';
  * ```
  */

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

@@ -0,0 +1,81 @@
+/**
+ * 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.
+ *
+ * ── 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.
+ *
+ * ── 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.
+ *
+ * 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`.
+ */
+import { notFound } from 'next/navigation';
+
+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 />;
+}
+
+export function JwtInspectPage() {
+  if (!testRoutesEnabled()) notFound();
+  return <JwtInspectPageUnguarded />;
+}
+
+export function RefreshTokenPage() {
+  if (!testRoutesEnabled()) notFound();
+  return <RefreshTokenPageUnguarded />;
+}
+
+export function EmergencyLogoutPage() {
+  if (!testRoutesEnabled()) notFound();
+  return <EmergencyLogoutPageUnguarded />;
+}

package/src/pages/test-env/index.ts

@@ -1,9 +1,55 @@
 /**
- * Test Environment Pages
+ * ⚠️ TEST-ENVIRONMENT DEBUG PAGES — NONE OF THESE BELONG IN PRODUCTION. ⚠️
  *
- * Export debug pages for MVP consumers.
+ * ────────────────────────── READ BEFORE COPYING ANYTHING BELOW (QAPert 35000) ──────────────────────────
+ * This barrel is the SPREAD MECHANISM. It ships compiled into dist and into
+ * the .d.ts, so it reaches every consuming developer's editor as hover text,
+ * 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.
  *
- * Usage:
+ * NONE of these pages has an env gate of its own. Unlike the force-expire
+ * handler (ENABLE_TEST_ROUTES) or 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.
+ *
+ * They are not equally dangerous. In descending order:
+ *   JwtInspectPage       WORST. Copy-to-clipboard for the LIVE SESSION TOKEN
+ *                        and ACCESS TOKEN. A session token is exactly the
+ *                        precondition the 246007 finding needs.
+ *   TestEnvPage          The index. Harmless alone, but it ADVERTISES the
+ *                        other three to anyone who reaches it.
+ *   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.
+ *
+ * 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
+ * absence.
+ *
+ * Usage — TEST/DEV ENVIRONMENTS ONLY:
  * ```typescript
  * // app/test-env/page.tsx
  * export { TestEnvPage as default } from '@payez/next-mvp/pages/test-env';
@@ -19,7 +65,13 @@
  * ```
  */
 
-export { TestEnvPage, TestEnvPage as default } from './TestEnvPage';
-export { JwtInspectPage } from './JwtInspectPage';
-export { RefreshTokenPage } from './RefreshTokenPage';
-export { EmergencyLogoutPage } from './EmergencyLogoutPage';
+// 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.
+export {
+    TestEnvPage,
+    TestEnvPage as default,
+    JwtInspectPage,
+    RefreshTokenPage,
+    EmergencyLogoutPage,
+} from './guarded';

package/src/routes/auth/logout.ts

@@ -16,7 +16,7 @@
 
 import { NextRequest, NextResponse } from 'next/server';
 import { getSession } from '../../server/auth';
-import { deleteSession } from '../../lib/session-store';
+import { deleteSessionEverywhere } from '../../lib/session-store';
 import {
   getSessionCookieName,
   getSecureSessionCookieName,
@@ -48,10 +48,11 @@ export async function POST(req: NextRequest) {
 
     const sessionId = session.session?.token;
 
-    // Delete session from store (this also removes the refresh token)
+    // Delete session from EVERY store — canonical + BA secondary (181922).
+    // Canonical-only deletion let the ba: record resurrect the session.
     if (sessionId) {
       try {
-        await deleteSession(sessionId);
+        await deleteSessionEverywhere(sessionId);
         console.info('[LOGOUT_ROUTE] Session deleted from store');
       } catch (error) {
         console.warn('[LOGOUT_ROUTE] Failed to delete session:', error);

package/src/routes/auth/passkey-signin.ts

@@ -1,13 +1,13 @@
-/**
- * Ready-to-Use Passkey Sign-In Route (ANONYMOUS ceremony)
- *
- * @example
- * ```typescript
- * // app/api/passkey/sign-in/options/route.ts
- * export { POST } from '@payez/next-mvp/routes/auth/passkey-signin';
- * // (optionsPOST is exported as POST; mount verify at its own path:)
- * // app/api/passkey/sign-in/verify/route.ts
- * export { verifyPOST as POST } from '@payez/next-mvp/routes/auth/passkey-signin';
- * ```
- */
-export { optionsPOST, verifyPOST } from '../../api-handlers/auth/passkey-signin';
+/**
+ * Ready-to-Use Passkey Sign-In Route (ANONYMOUS ceremony)
+ *
+ * @example
+ * ```typescript
+ * // app/api/passkey/sign-in/options/route.ts
+ * export { POST } from '@payez/next-mvp/routes/auth/passkey-signin';
+ * // (optionsPOST is exported as POST; mount verify at its own path:)
+ * // app/api/passkey/sign-in/verify/route.ts
+ * export { verifyPOST as POST } from '@payez/next-mvp/routes/auth/passkey-signin';
+ * ```
+ */
+export { optionsPOST, verifyPOST } from '../../api-handlers/auth/passkey-signin';

package/src/routes/auth/refresh.ts

@@ -16,15 +16,44 @@
 
 import { createRefreshHandler } from '../../api-handlers/auth/refresh';
 
+/**
+ * Resolve the client id from environment variables.
+ *
+ * Was: `process.env.CLIENT_ID || process.env.NEXT_PUBLIC_IDP_CLIENT_ID || ''`
+ * That fallback to empty string made "we do not know the client" indistinguishable from
+ * "the client id is blank". Callers cannot tell absence from a known-empty value.
+ *
+ * Card 221076 / 223542: absence is now `null`, which is representable and still falsy,
+ * so existing `if (!clientId)` guards behave exactly as before.
+ * (Ported verbatim from qapert-nighthawk/221076, where this fix already existed;
+ * the qa/222363 line carried viability's half but never got refresh's.)
+ */
+function resolveClientId(): string | null {
+  const clientId = process.env.CLIENT_ID || process.env.NEXT_PUBLIC_IDP_CLIENT_ID;
+  if (clientId) {
+    return clientId;
+  }
+  return null;
+}
+
 // Configuration is read at runtime from environment.
 function getConfig() {
   const idpBaseUrl = process.env.IDP_URL;
   if (!idpBaseUrl) {
     throw new Error('[IDP_URL] FATAL: IDP_URL environment variable is REQUIRED.');
   }
+  const clientId = resolveClientId();
+  if (!clientId) {
+    // Card 221076 / 223542: absence must be detectable, not collapsed to a default.
+    console.warn(
+      '[REFRESH_ROUTE] No CLIENT_ID or NEXT_PUBLIC_IDP_CLIENT_ID configured. ' +
+        'Token refresh will be attempted, but the server cannot identify which client ' +
+        'initiated the request. This may fail if the IDP requires a client ID.'
+    );
+  }
   return {
     idpBaseUrl,
-    clientId: process.env.CLIENT_ID || process.env.NEXT_PUBLIC_IDP_CLIENT_ID || '',
+    clientId: clientId || 'payez_default_client', // Handler-safe fallback
     refreshEndpoint: process.env.REFRESH_ENDPOINT || '/api/ExternalAuth/refresh',
   };
 }