@payez/next-mvp 4.8.0 → 4.8.2

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

@@ -1,81 +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 />;
-}
+/**
+ * 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,77 +1,77 @@
-/**
- * ⚠️ TEST-ENVIRONMENT DEBUG PAGES — NONE OF THESE BELONG IN PRODUCTION. ⚠️
- *
- * ────────────────────────── 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.
- *
- * 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';
- *
- * // app/test-env/jwt-inspect/page.tsx
- * export { JwtInspectPage as default } from '@payez/next-mvp/pages/test-env';
- *
- * // app/test-env/refresh-token/page.tsx
- * export { RefreshTokenPage as default } from '@payez/next-mvp/pages/test-env';
- *
- * // app/test-env/emergency-logout/page.tsx
- * export { EmergencyLogoutPage as default } from '@payez/next-mvp/pages/test-env';
- * ```
- */
-
-// 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';
+/**
+ * ⚠️ TEST-ENVIRONMENT DEBUG PAGES — NONE OF THESE BELONG IN PRODUCTION. ⚠️
+ *
+ * ────────────────────────── 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.
+ *
+ * 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';
+ *
+ * // app/test-env/jwt-inspect/page.tsx
+ * export { JwtInspectPage as default } from '@payez/next-mvp/pages/test-env';
+ *
+ * // app/test-env/refresh-token/page.tsx
+ * export { RefreshTokenPage as default } from '@payez/next-mvp/pages/test-env';
+ *
+ * // app/test-env/emergency-logout/page.tsx
+ * export { EmergencyLogoutPage as default } from '@payez/next-mvp/pages/test-env';
+ * ```
+ */
+
+// 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/pages/test-env/redact-credentials.ts

@@ -1,96 +1,96 @@
-/**
- * redact-credentials - what the test-env debug pages may show of a credential: a stable hash and a length, never
- * characters of the value (PAY-1470, BAPert rulings 59022 and 59040).
- *
- * PAY-1481 item 2 (QAPert, PR 186 review 59083): this was a DENYLIST (keys ending in token/secret/password/...).
- * Opaque credentials under `tokens.access`, `redisSessionId`, `sid`, `authorization`, `cookie`, `backupCodes[]` and
- * `code` passed unmasked. It is now an ALLOWLIST: a string is shown only when its key is a known DISPLAYABLE field
- * (identity, roles, timestamps, provider and flag metadata, standard JWT claims). Every other string - an unknown
- * key, an array item under an unknown key, a top-level string - becomes maskToken. A new field is hidden until
- * someone decides it is displayable, which is the safe direction for a page reachable in production builds.
- *
- * Kept from the denylist era, and applied EVEN under a displayable key, because a credential can sit under an
- * innocent name: a JWT (three base64url segments, length floors so "4.1.42" is not one), a PEM armour band, and the
- * password in scheme://user:password@host. Numbers, booleans and null are never credentials and stay readable.
- *
- * There is no Reveal and no copy. "Never renders token material" includes click-to-reveal (59040).
- */
-import { tokenLogId } from '../../lib/token-log-id';
-
-/** A stable, non-reversible stand-in for a credential: `h:<12 hex>  (<n> chars, hidden)`. */
-export function maskToken(value: string): string {
-  return `${tokenLogId(value)}  (${value.length} chars, hidden)`;
-}
-
-/**
- * Keys whose string values are displayable. Exact names (case-insensitive), plus timestamp / flag suffix patterns.
- * An exact listed key wins (tokenType is metadata); otherwise a key naming a credential (CREDENTIAL_NAME) is refused.
- */
-const DISPLAYABLE_KEYS = new Set(
-  [
-    // identity
-    'id', 'userId', 'user_id', 'sub', 'email', 'name', 'given_name', 'family_name', 'preferred_username', 'image',
-    'picture', 'locale', 'phone_number_verified',
-    // authorisation metadata
-    'role', 'roles', 'scope', 'scopes', 'permissions', 'authenticationMethods', 'authenticationLevel', 'amr', 'acr',
-    'oauthProvider', 'provider', 'providerId', 'tokenType', 'token_type', 'type', 'typ', 'alg', 'kid', 'iss', 'aud',
-    'azp', 'jti',
-    // client / tenant
-    'clientId', 'client_id', 'idpClientId', 'clientSlug', 'slug', 'tenant', 'tenantId', 'merchantId', 'appSlug',
-    // result / status fields of the test-env routes
-    'status', 'statusText', 'success', 'action', 'message', 'error', 'reason', 'outcome', 'source', 'shape', 'mode',
-  ].map((k) => k.toLowerCase()),
-);
-/** Timestamps, durations and booleans-as-strings by suffix: expires, accessTokenExpires, mfaCompletedAt, iat... */
-const DISPLAYABLE_SUFFIX = /(expires|_at|iat|exp|nbf|hours|seconds|verified|required|enabled|count|version)$/i;
-/** camelCase timestamps (createdAt, mfaCompletedAt): tested on the ORIGINAL key so `format` / `chat` do not match. */
-const CAMEL_AT = /[a-z0-9]At$/;
-/** A key that names a credential is never displayable, whatever suffix it has (e.g. refreshTokenCreatedAt stays OK
- *  because it names a TIME; `authorization`, `cookie`, `sid`, `code` are credentials). */
-const CREDENTIAL_NAME = /(token|secret|password|passwd|apikey|api_key|credential|authorization|cookie|^sid$|session_?id$|^code$|codes?$|otp|pin$|signature|private)/i;
-
-const URL_WITH_USERINFO = /^([a-z][a-z0-9+.-]*:\/\/)([^/\s:@]+):([^/\s@]+)@/i;
-const PEM_BLOCK = /-----BEGIN [A-Z0-9][A-Z0-9 ]*-----/;
-
-function 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));
-}
-
-/** Is a string under this key displayable? Credential names lose even when a timestamp suffix matches. */
-export function isDisplayableKey(keyName: string): boolean {
-  if (!keyName) return false;
-  const k = keyName.toLowerCase();
-  // 1. An exact, deliberately listed field (tokenType is metadata even though it says "token").
-  if (DISPLAYABLE_KEYS.has(k)) return true;
-  // 2. A key naming a credential is refused - unless what it names is a TIME about it (accessTokenExpires).
-  const namesTime = /(expires|_at|iat|exp|nbf|hours|seconds)$/i.test(k) || CAMEL_AT.test(keyName);
-  if (CREDENTIAL_NAME.test(k) && !namesTime) return false;
-  // 3. Metadata by suffix: timestamps, durations, flags, counts, versions, URLs (userinfo is still masked).
-  return DISPLAYABLE_SUFFIX.test(k) || CAMEL_AT.test(keyName) || /url$/i.test(k);
-}
-
-/** A deep copy of `value` in which every string not under a displayable key is replaced by maskToken. */
-export function redactCredentials(value: unknown, keyName = ''): unknown {
-  // Array items inherit the array's key: backupCodes[] items are credentials, roles[] items are not.
-  if (Array.isArray(value)) return value.map((v) => redactCredentials(v, keyName));
-  if (value && typeof value === 'object') {
-    return Object.fromEntries(
-      Object.entries(value as Record<string, unknown>).map(([k, v]) => [k, redactCredentials(v, k)]),
-    );
-  }
-  // NightHawk (PR 204 review): a numeric OTP / code under a credential-named key is a credential too.
-  if (typeof value === 'number' && keyName && !isDisplayableKey(keyName) && CREDENTIAL_NAME.test(keyName)) {
-    return maskToken(String(value));
-  }
-  if (typeof value !== 'string' || value.length === 0) return value;
-  if (looksLikeJwt(value)) return maskToken(value);
-  if (PEM_BLOCK.test(value)) return '••• PEM block redacted (' + value.length + ' chars) •••';
-  if (!isDisplayableKey(keyName)) return maskToken(value);
-  let shown = value;
-  if (URL_WITH_USERINFO.test(shown)) shown = shown.replace(URL_WITH_USERINFO, '$1$2:•••••@');
-  // NightHawk (PR 204 review): a URL's query and fragment carry tokens (?token=, #access_token=). Names stay, values go.
-  shown = shown.replace(/([?&#][^=&#\s]+=)[^&#\s]*/g, '$1•••');
-  return shown;
-}
+/**
+ * redact-credentials - what the test-env debug pages may show of a credential: a stable hash and a length, never
+ * characters of the value (PAY-1470, BAPert rulings 59022 and 59040).
+ *
+ * PAY-1481 item 2 (QAPert, PR 186 review 59083): this was a DENYLIST (keys ending in token/secret/password/...).
+ * Opaque credentials under `tokens.access`, `redisSessionId`, `sid`, `authorization`, `cookie`, `backupCodes[]` and
+ * `code` passed unmasked. It is now an ALLOWLIST: a string is shown only when its key is a known DISPLAYABLE field
+ * (identity, roles, timestamps, provider and flag metadata, standard JWT claims). Every other string - an unknown
+ * key, an array item under an unknown key, a top-level string - becomes maskToken. A new field is hidden until
+ * someone decides it is displayable, which is the safe direction for a page reachable in production builds.
+ *
+ * Kept from the denylist era, and applied EVEN under a displayable key, because a credential can sit under an
+ * innocent name: a JWT (three base64url segments, length floors so "4.1.42" is not one), a PEM armour band, and the
+ * password in scheme://user:password@host. Numbers, booleans and null are never credentials and stay readable.
+ *
+ * There is no Reveal and no copy. "Never renders token material" includes click-to-reveal (59040).
+ */
+import { tokenLogId } from '../../lib/token-log-id';
+
+/** A stable, non-reversible stand-in for a credential: `h:<12 hex>  (<n> chars, hidden)`. */
+export function maskToken(value: string): string {
+  return `${tokenLogId(value)}  (${value.length} chars, hidden)`;
+}
+
+/**
+ * Keys whose string values are displayable. Exact names (case-insensitive), plus timestamp / flag suffix patterns.
+ * An exact listed key wins (tokenType is metadata); otherwise a key naming a credential (CREDENTIAL_NAME) is refused.
+ */
+const DISPLAYABLE_KEYS = new Set(
+  [
+    // identity
+    'id', 'userId', 'user_id', 'sub', 'email', 'name', 'given_name', 'family_name', 'preferred_username', 'image',
+    'picture', 'locale', 'phone_number_verified',
+    // authorisation metadata
+    'role', 'roles', 'scope', 'scopes', 'permissions', 'authenticationMethods', 'authenticationLevel', 'amr', 'acr',
+    'oauthProvider', 'provider', 'providerId', 'tokenType', 'token_type', 'type', 'typ', 'alg', 'kid', 'iss', 'aud',
+    'azp', 'jti',
+    // client / tenant
+    'clientId', 'client_id', 'idpClientId', 'clientSlug', 'slug', 'tenant', 'tenantId', 'merchantId', 'appSlug',
+    // result / status fields of the test-env routes
+    'status', 'statusText', 'success', 'action', 'message', 'error', 'reason', 'outcome', 'source', 'shape', 'mode',
+  ].map((k) => k.toLowerCase()),
+);
+/** Timestamps, durations and booleans-as-strings by suffix: expires, accessTokenExpires, mfaCompletedAt, iat... */
+const DISPLAYABLE_SUFFIX = /(expires|_at|iat|exp|nbf|hours|seconds|verified|required|enabled|count|version)$/i;
+/** camelCase timestamps (createdAt, mfaCompletedAt): tested on the ORIGINAL key so `format` / `chat` do not match. */
+const CAMEL_AT = /[a-z0-9]At$/;
+/** A key that names a credential is never displayable, whatever suffix it has (e.g. refreshTokenCreatedAt stays OK
+ *  because it names a TIME; `authorization`, `cookie`, `sid`, `code` are credentials). */
+const CREDENTIAL_NAME = /(token|secret|password|passwd|apikey|api_key|credential|authorization|cookie|^sid$|session_?id$|^code$|codes?$|otp|pin$|signature|private)/i;
+
+const URL_WITH_USERINFO = /^([a-z][a-z0-9+.-]*:\/\/)([^/\s:@]+):([^/\s@]+)@/i;
+const PEM_BLOCK = /-----BEGIN [A-Z0-9][A-Z0-9 ]*-----/;
+
+function 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));
+}
+
+/** Is a string under this key displayable? Credential names lose even when a timestamp suffix matches. */
+export function isDisplayableKey(keyName: string): boolean {
+  if (!keyName) return false;
+  const k = keyName.toLowerCase();
+  // 1. An exact, deliberately listed field (tokenType is metadata even though it says "token").
+  if (DISPLAYABLE_KEYS.has(k)) return true;
+  // 2. A key naming a credential is refused - unless what it names is a TIME about it (accessTokenExpires).
+  const namesTime = /(expires|_at|iat|exp|nbf|hours|seconds)$/i.test(k) || CAMEL_AT.test(keyName);
+  if (CREDENTIAL_NAME.test(k) && !namesTime) return false;
+  // 3. Metadata by suffix: timestamps, durations, flags, counts, versions, URLs (userinfo is still masked).
+  return DISPLAYABLE_SUFFIX.test(k) || CAMEL_AT.test(keyName) || /url$/i.test(k);
+}
+
+/** A deep copy of `value` in which every string not under a displayable key is replaced by maskToken. */
+export function redactCredentials(value: unknown, keyName = ''): unknown {
+  // Array items inherit the array's key: backupCodes[] items are credentials, roles[] items are not.
+  if (Array.isArray(value)) return value.map((v) => redactCredentials(v, keyName));
+  if (value && typeof value === 'object') {
+    return Object.fromEntries(
+      Object.entries(value as Record<string, unknown>).map(([k, v]) => [k, redactCredentials(v, k)]),
+    );
+  }
+  // NightHawk (PR 204 review): a numeric OTP / code under a credential-named key is a credential too.
+  if (typeof value === 'number' && keyName && !isDisplayableKey(keyName) && CREDENTIAL_NAME.test(keyName)) {
+    return maskToken(String(value));
+  }
+  if (typeof value !== 'string' || value.length === 0) return value;
+  if (looksLikeJwt(value)) return maskToken(value);
+  if (PEM_BLOCK.test(value)) return '••• PEM block redacted (' + value.length + ' chars) •••';
+  if (!isDisplayableKey(keyName)) return maskToken(value);
+  let shown = value;
+  if (URL_WITH_USERINFO.test(shown)) shown = shown.replace(URL_WITH_USERINFO, '$1$2:•••••@');
+  // NightHawk (PR 204 review): a URL's query and fragment carry tokens (?token=, #access_token=). Names stay, values go.
+  shown = shown.replace(/([?&#][^=&#\s]+=)[^&#\s]*/g, '$1•••');
+  return shown;
+}