@payez/next-mvp 4.4.5 → 4.4.6

package/src/lib/idp-client-config.ts

@@ -166,6 +166,75 @@ const OPERATOR_AUTH_SECRET = process.env.BETTER_AUTH_SECRET;
 const OPERATOR_NEXTAUTH_SECRET = process.env.NEXTAUTH_SECRET;
 let operatorOverrideLogged = false;
 
+// ============================================================================
+// PAY-1460 - SECRETS ARE ENV-FIRST
+// ============================================================================
+/**
+ * The IdP serves the signing secret and every OAuth provider client secret in the client config, to any
+ * caller holding a client assertion (PAY-1460). It cannot stop serving them while this package depends on
+ * them: every earlier version throws FATAL on an empty config authSecret, whatever the environment says.
+ *
+ * So both are now resolved ENV FIRST, config second:
+ *   signing secret   BETTER_AUTH_SECRET (canonical), NEXTAUTH_SECRET (legacy alias), then config authSecret.
+ *                    Uses the module-load snapshot above: this module publishes the config value into
+ *                    process.env, so a live read would mistake the IdP's value for the operator's.
+ *   provider secret  <PROVIDER>_CLIENT_SECRET, provider name upper-cased with non-alphanumerics as '_'
+ *                    (GOOGLE_CLIENT_SECRET, APPLE_CLIENT_SECRET, MICROSOFT_CLIENT_SECRET), then config.
+ *
+ * The FATAL on an empty signing secret is unchanged and still load-bearing: it now fires only when BOTH the
+ * environment and the config are empty.
+ *
+ * Values are never logged. The SOURCE of each is logged once per change. An env-sourced value is never
+ * written to the Redis config cache (stripEnvSecrets); a cache read re-applies the environment.
+ */
+export type SecretSource = string; // 'env:<VAR>' | 'idp-config' | 'none'
+
+export function providerSecretEnvVar(provider: string): string {
+    return `${String(provider).trim().toUpperCase().replace(/[^A-Z0-9]+/g, '_')}_CLIENT_SECRET`;
+}
+
+const loggedSecretSources = new Map<string, SecretSource>();
+function logSecretSource(what: string, source: SecretSource): void {
+    if (loggedSecretSources.get(what) === source) return;
+    loggedSecretSources.set(what, source);
+    console.log(`[IDP_CONFIG] ${what} source: ${source}`);
+}
+
+function resolveAuthSecret(fromConfig: string | undefined): { value: string; source: SecretSource } {
+    if (OPERATOR_AUTH_SECRET) return { value: OPERATOR_AUTH_SECRET, source: 'env:BETTER_AUTH_SECRET' };
+    if (OPERATOR_NEXTAUTH_SECRET) return { value: OPERATOR_NEXTAUTH_SECRET, source: 'env:NEXTAUTH_SECRET' };
+    if (fromConfig) return { value: fromConfig, source: 'idp-config' };
+    return { value: '', source: 'none' };
+}
+
+/** A copy of `config` with every secret resolved env-first. Never mutates (the argument may be cached). */
+function applyEnvSecrets(config: IDPClientConfig): IDPClientConfig {
+    const auth = resolveAuthSecret(config.authSecret);
+    logSecretSource('authSecret', auth.source);
+    return {
+        ...config,
+        authSecret: auth.value,
+        oauthProviders: (config.oauthProviders ?? []).map((p) => {
+            const envVar = providerSecretEnvVar(p.provider);
+            const fromEnv = process.env[envVar];
+            const source: SecretSource = fromEnv ? `env:${envVar}` : p.clientSecret ? 'idp-config' : 'none';
+            logSecretSource(`${p.provider} clientSecret`, source);
+            return { ...p, clientSecret: fromEnv || p.clientSecret };
+        }),
+    };
+}
+
+/** What may be persisted to Redis: env-sourced secrets are blanked (the environment re-supplies them on read). */
+function stripEnvSecrets(config: IDPClientConfig): IDPClientConfig {
+    return {
+        ...config,
+        authSecret: OPERATOR_AUTH_SECRET || OPERATOR_NEXTAUTH_SECRET ? '' : config.authSecret,
+        oauthProviders: (config.oauthProviders ?? []).map((p) =>
+            process.env[providerSecretEnvVar(p.provider)] ? { ...p, clientSecret: '' } : p
+        ),
+    };
+}
+
 /** Publish the resolved auth secret WITHOUT ever overwriting an operator-set value. */
 function publishAuthSecret(value: string, source: string): void {
     if (OPERATOR_AUTH_SECRET) {
@@ -294,7 +363,8 @@ async function setConfigInRedis(config: IDPClientConfig): Promise<void> {
         const key = getRedisConfigKey();
         const ttlSeconds = config.configCacheTtlSeconds || 300;
         const data: RedisCachedConfig = {
-            config,
+            // PAY-1460: never persist a secret the environment supplied.
+            config: stripEnvSecrets(config),
             expiresAt: Date.now() + (ttlSeconds * 1000)
         };
         // Store with TTL slightly longer than the logical expiry to allow for clock skew
@@ -355,7 +425,10 @@ export async function getIDPClientConfig(forceRefresh: boolean = false): Promise
 
     // Layer 2: Check Redis cache (skip if forceRefresh - startup should always get fresh data)
     if (!forceRefresh) {
-        const redisConfig = await getConfigFromRedis();
+        // PAY-1460: a cached entry never carries env-sourced secrets (stripEnvSecrets), so the
+        // environment is re-applied on read, BEFORE the emptiness test below.
+        const cachedRaw = await getConfigFromRedis();
+        const redisConfig = cachedRaw ? applyEnvSecrets(cachedRaw) : null;
         // A cached entry is only USABLE if it carries a secret — see the note
         // below. `redisConfig && !authSecret` must behave like a cache MISS, so
         // the emptiness test belongs here, in the condition that gates the
@@ -505,7 +578,7 @@ export async function getIDPClientConfig(forceRefresh: boolean = false): Promise
                 // This throw is what stops that. It is also what turned the
                 // 2026-08-05 nextauth_secret spelling bug into a loud FATAL instead
                 // of a silently forgeable app.
-                throw new Error('[IDP_CONFIG] FATAL: IDP did not return authSecret');
+                throw new Error('[IDP_CONFIG] FATAL: IDP did not return authSecret and neither BETTER_AUTH_SECRET nor NEXTAUTH_SECRET is set');
             }
 
             // Validated above — only now is it safe to cache or publish.
@@ -588,7 +661,7 @@ async function fetchConfigFromInternalIDP(internalIdpUrl: string, clientIdStr: s
 
     if (!resp.ok) {
         const txt = await resp.text().catch(() => 'Unknown error');
-        throw new Error(`[IDP_CONFIG] FATAL: Internal IDP returned ${resp.status} - ${txt}`);
+        throw new Error(`[IDP_CONFIG] FATAL: Internal IDP returned ${resp.status} (body ${txt.length} chars)`); // PAY-1427
     }
 
     const body: any = await resp.json().catch(() => null);
@@ -603,7 +676,7 @@ async function fetchConfigFromInternalIDP(internalIdpUrl: string, clientIdStr: s
         throw new Error(`[IDP_CONFIG] FATAL: Internal IDP response missing clientId. Got: ${JSON.stringify(Object.keys(configData))}`);
     }
 
-    const config: IDPClientConfig = {
+    const config: IDPClientConfig = applyEnvSecrets({
         clientId: String(rawClientId),
         clientSlug: configData.clientSlug ?? configData.client_slug ?? configData.slug ?? '',
         // Wire compatibility: accept new authSecret first, fall back to legacy
@@ -669,13 +742,13 @@ async function fetchConfigFromInternalIDP(internalIdpUrl: string, clientIdStr: s
             logoUrl: configData.branding?.logoUrl ?? configData.branding?.logo_url
         },
         baseClientUrl: configData.baseClientUrl ?? configData.base_client_url ?? configData.BaseClientUrl
-    };
+    });
 
     if (!config.authSecret) {
         // LOAD-BEARING — see the note on the external path's equivalent throw.
         // An empty secret reaching betterAuth() becomes the PUBLIC default, not an
         // error. Never replace this with a fallback.
-        throw new Error('[IDP_CONFIG] FATAL: Internal IDP did not return authSecret');
+        throw new Error('[IDP_CONFIG] FATAL: Internal IDP did not return authSecret and neither BETTER_AUTH_SECRET nor NEXTAUTH_SECRET is set');
     }
 
     console.log(`[IDP_CONFIG] Internal IDP config loaded for ${clientIdStr}`);
@@ -751,7 +824,8 @@ async function fetchConfigFromIDP(idpUrl: string, clientIdStr: string): Promise<
 
     if (!signingResp.ok) {
         const txt = await signingResp.text().catch(() => 'Unknown error');
-        throw new Error(`[IDP_CONFIG] FATAL: Failed to sign client assertion: ${signingResp.status} - ${txt}`);
+        // PAY-1427: the thrown message is logged by callers - body length only, never the upstream text.
+        throw new Error(`[IDP_CONFIG] FATAL: Failed to sign client assertion: ${signingResp.status} (body ${txt.length} chars)`);
     }
 
     const signingBody: any = await signingResp.json().catch(() => null);
@@ -768,7 +842,8 @@ async function fetchConfigFromIDP(idpUrl: string, clientIdStr: string): Promise<
     ) as string | undefined;
 
     if (!client_assertion) {
-        console.error('[IDP_CONFIG] FATAL: Full response body:', JSON.stringify(signingBody, null, 2));
+        // PAY-1427: never the full sign-client-assertion body (assertion material). Key names only.
+        console.error('[IDP_CONFIG] FATAL: sign-client-assertion response shape:', { keys: Object.keys(signingBody || {}), dataKeys: Object.keys(signingBody?.data || {}) });
         throw new Error(`[IDP_CONFIG] FATAL: IDP response missing client_assertion. Got keys: ${JSON.stringify(Object.keys(signingBody?.data || signingBody || {}))}`);
     }
 
@@ -783,43 +858,13 @@ async function fetchConfigFromIDP(idpUrl: string, clientIdStr: string): Promise<
             'X-Client-Id': clientIdStr,
             'X-Correlation-Id': randomUUID().replace(/-/g, ''),
         },
-        // 217917 PHASE 1: explicit opt-in for provider secrets.
-        //
-        // This broker is the ONLY consumer of oauth_providers[].client_secret
-        // (DotNetPert enumerated it: this file feeds auth/providers/oauth.ts,
-        // which performs the server-side code exchange). Every OTHER caller of
-        // ExternalAuth/client-config - notably every fielded acp-desktop - is
-        // pushed the same secrets today and reads none of them: the desktop is
-        // PKCE and dropped clientSecret from OAuthProviderConfig entirely.
-        //
-        // The IDP IGNORES this field today, so shipping it is a no-op and needs
-        // no coordination window. Phase 2 (DotNetPert, IDP side) makes
-        // client-config emit the secrets ONLY when the opt-in is present and
-        // redact otherwise - which is why phase 1 MUST be live first, or the
-        // broker loses the field and tenant OAuth sign-in dies.
-        //
-        // SCOPE, deliberately narrow - do NOT read this as a partial migration:
-        // the sibling path fetchConfigFromInternalIDP() hits a DIFFERENT
-        // endpoint (InternalClientConfig/{id}, GET) that is already
-        // authenticated with CONTAINERS_KEY, is not reachable by a desktop, and
-        // is therefore not part of 217917's exposure. It deliberately sends no
-        // opt-in. If phase 2's redaction is implemented in shared config-
-        // assembly code rather than in ExternalAuthController.GetClientConfig,
-        // it will ALSO strip the internal route and break this broker's other
-        // path with no opt-in to save it. Phase 2 must gate on the request.
-        //
-        // NOT A FIX ON ITS OWN: an attacker can set this flag too. Phase 2 ends
-        // the AUTOMATIC delivery of every tenant's provider secrets to every
-        // user laptop; it does not close disclosure to a determined caller.
-        // That residual is card 175047 (unauthenticated mint, global partner
-        // key) and 217917 does not close until 175047 lands or Jon accepts it.
-        body: JSON.stringify({ client_assertion, include_provider_secrets: true }),
+        body: JSON.stringify({ client_assertion }),
         cache: 'no-store'
     } as RequestInit);
 
     if (!configResp.ok) {
         const txt = await configResp.text().catch(() => 'Unknown error');
-        throw new Error(`[IDP_CONFIG] FATAL: Failed to fetch client config: ${configResp.status} - ${txt}`);
+        throw new Error(`[IDP_CONFIG] FATAL: Failed to fetch client config: ${configResp.status} (body ${txt.length} chars)`);
     }
 
     const configBody: any = await configResp.json().catch(() => null);
@@ -832,7 +877,8 @@ async function fetchConfigFromIDP(idpUrl: string, clientIdStr: string): Promise<
     const configData = configBody?.data;
 
     if (!configData || typeof configData !== 'object') {
-        console.error('[IDP_CONFIG] FATAL: Full config response body:', JSON.stringify(configBody, null, 2));
+        // PAY-1427: never the full client-config body (client configuration / provider secrets). Key names only.
+        console.error('[IDP_CONFIG] FATAL: client-config response shape:', { keys: Object.keys(configBody || {}) });
         throw new Error('[IDP_CONFIG] FATAL: IDP client-config response missing data envelope');
     }
 
@@ -845,7 +891,7 @@ async function fetchConfigFromIDP(idpUrl: string, clientIdStr: string): Promise<
     // Map response to our interface (IDP returns camelCase or snake_case).
     // Wire compatibility: accept new authSecret first, fall back to legacy
     // nextAuthSecret/next_auth_secret while IDP rename rolls out.
-    const config: IDPClientConfig = {
+    const config: IDPClientConfig = applyEnvSecrets({
         clientId: String(rawClientId),
         clientSlug: configData.clientSlug ?? configData.client_slug ?? configData.slug ?? '',
         authSecret:
@@ -919,7 +965,7 @@ async function fetchConfigFromIDP(idpUrl: string, clientIdStr: string): Promise<
             logoUrl: configData.branding?.logoUrl ?? configData.branding?.logo_url
         },
         baseClientUrl: configData.baseClientUrl ?? configData.base_client_url ?? configData.BaseClientUrl
-    };
+    });
 
     // Debug: log what we got for baseClientUrl
     console.log(`[IDP_CONFIG] Parsed baseClientUrl:`, config.baseClientUrl, `| raw keys:`, Object.keys(configData).filter(k => k.toLowerCase().includes('client')));
@@ -931,7 +977,7 @@ async function fetchConfigFromIDP(idpUrl: string, clientIdStr: string): Promise<
     if (!config.authSecret) {
         // LOAD-BEARING — empty must fail here, never downstream. betterAuth()
         // silently substitutes a public constant for an empty secret.
-        throw new Error('[IDP_CONFIG] FATAL: authSecret is empty after parsing');
+        throw new Error('[IDP_CONFIG] FATAL: authSecret is empty after parsing and neither BETTER_AUTH_SECRET nor NEXTAUTH_SECRET is set');
     }
 
     // Success - reset failure tracking

package/src/lib/idp-fetch.ts

@@ -58,7 +58,7 @@ async function ensureFreshAccessToken(req: NextRequest): Promise<{ sessionToken?
   const sessionToken = (token?.sessionToken || token?.redisSessionId) as string | undefined;
   console.log('[IDP_FETCH] ensureFreshAccessToken:', {
     hasToken: !!token,
-    sessionToken: sessionToken?.substring(0, 20) + '...',
+    hasSessionToken: !!sessionToken, // PAY-1427 / BAPert 58829: no token material in logs, not even a stub (was a 20-char prefix)
     pathname: req.nextUrl.pathname
   });
   if (!sessionToken) {

package/src/lib/password-rules.ts

@@ -0,0 +1,50 @@
+/**
+ * PAY-1591: the one sentence that states the password rules on the recovery set-password step.
+ *
+ * Built ONLY from the policy the IdP reported (usePasswordValidation.policy). A rule that is off is not stated, and with
+ * no policy at all we state no number: telling a user "at least 8 characters" when the client is configured for 12 is
+ * the same defect as saying nothing, one step later.
+ */
+export interface PasswordPolicyLike {
+  min_length?: number;
+  require_uppercase?: boolean;
+  require_lowercase?: boolean;
+  require_digit?: boolean;
+  require_special?: boolean;
+}
+
+export function passwordRulesText(policy: PasswordPolicyLike | undefined | null): string {
+  if (!policy || typeof policy.min_length !== 'number') {
+    return "Use a password that meets this site's rules. We'll show what is missing as you type.";
+  }
+  const parts = [`at least ${policy.min_length} characters`];
+  if (policy.require_uppercase) parts.push('an upper-case letter');
+  if (policy.require_lowercase) parts.push('a lower-case letter');
+  if (policy.require_digit) parts.push('a number');
+  if (policy.require_special) parts.push('a symbol');
+  const [first, ...rest] = parts;
+  return rest.length ? `Your password needs ${first}, with ${rest.join(', ')}.` : `Your password needs ${first}.`;
+}
+
+/**
+ * PAY-1591: the IdP's reset refusal names WHICH rules failed as codes (error.details.rules). This is the closed set the
+ * portal accepts and the one plain sentence for each. Anything outside it is dropped, never displayed or forwarded.
+ */
+export const PASSWORD_RULE_SENTENCES: Readonly<Record<string, string>> = {
+  min_length: 'Use a longer password.',
+  uppercase: 'Add an upper-case letter.',
+  lowercase: 'Add a lower-case letter.',
+  digit: 'Add a number.',
+  special: 'Add a symbol.',
+  unique_chars: 'Use more different characters.',
+  recent_password: "Choose a password you haven't used recently.",
+};
+
+export function knownPasswordRules(rules: unknown): string[] {
+  if (!Array.isArray(rules)) return [];
+  return rules.filter((r): r is string => typeof r === 'string' && Object.prototype.hasOwnProperty.call(PASSWORD_RULE_SENTENCES, r));
+}
+
+export function passwordRuleSentences(rules: string[]): string {
+  return rules.map((r) => PASSWORD_RULE_SENTENCES[r]).join(' ');
+}

package/src/lib/safe-error-response.ts

@@ -0,0 +1,126 @@
+/**
+ * PAY-1438: what a USER-FACING handler may put in an error response.
+ *
+ * Several of these routes are reachable before authentication (session check, viability probe,
+ * logout, auth status, refresh-viability), so whatever lands in the body reaches an anonymous caller.
+ *
+ * Class A - an EXCEPTION: its text (ioredis `connect ECONNREFUSED host:port`, undici `fetch failed`,
+ * JSON parse errors quoting payload bytes) stays server-side. The response carries a fixed message,
+ * a code and a correlationId; the log line carries the exception and the same id.
+ *
+ * Class B - an IDP ERROR ENVELOPE ({ success, message, error: { code, message, details, support } }):
+ * never passed through whole. Only the display contract is projected: code, message, resolution,
+ * request_id - each only when it is a string. `details` (free-form, may carry validation internals
+ * or exception data) is dropped, except for the password-policy messages change-password's UI reads.
+ */
+
+import { knownPasswordRules } from './password-rules';
+
+export interface IdpErrorProjection {
+  code?: string;
+  message?: string;
+  resolution?: string;
+  request_id?: string;
+}
+
+const str = (v: unknown): string | undefined => (typeof v === 'string' ? v : undefined);
+
+/** Log an exception with a fresh correlationId and return the id for the response body. */
+export function logExceptionWithCorrelation(tag: string, err: unknown): string {
+  const correlationId = globalThis.crypto.randomUUID();
+  console.error(tag, { correlationId, error: err });
+  return correlationId;
+}
+
+/** Whitelisted projection of an IDP error envelope: code / message / resolution / request_id only. */
+export function projectIdpError(json: unknown): IdpErrorProjection {
+  if (!json || typeof json !== 'object') return {};
+  const top = json as Record<string, unknown>;
+  const err = top.error && typeof top.error === 'object' ? (top.error as Record<string, unknown>) : {};
+  const support = err.support && typeof err.support === 'object' ? (err.support as Record<string, unknown>) : {};
+  const out: IdpErrorProjection = {};
+  const code = str(err.code) ?? str(top.code) ?? str(top.error_code);
+  const message = str(err.message) ?? str(top.message);
+  const resolution = str(err.resolution) ?? str(top.resolution);
+  const requestId = str(support.request_id) ?? str(top.request_id);
+  if (code !== undefined) out.code = code;
+  if (message !== undefined) out.message = message;
+  if (resolution !== undefined) out.resolution = resolution;
+  if (requestId !== undefined) out.request_id = requestId;
+  return out;
+}
+
+/**
+ * change-password's `details`: the security pages show `details.value[0].message` (else
+ * `details.message`) as the password-policy error (QAPert census on PAY-1438). Keep exactly those
+ * strings; drop everything else.
+ */
+export function projectPasswordPolicyDetails(details: unknown): { message?: string; value?: Array<{ message: string }> } | undefined {
+  if (!details || typeof details !== 'object') return undefined;
+  const d = details as Record<string, unknown>;
+  const out: { message?: string; value?: Array<{ message: string }> } = {};
+  if (Array.isArray(d.value)) {
+    const value = d.value
+      .map((v) => (v && typeof v === 'object' ? str((v as Record<string, unknown>).message) : undefined))
+      .filter((m): m is string => m !== undefined)
+      .map((message) => ({ message }));
+    if (value.length) out.value = value;
+  }
+  const message = str(d.message);
+  if (message !== undefined) out.message = message;
+  return out.value || out.message !== undefined ? out : undefined;
+}
+
+/**
+ * For proxies that used to pass the IDP response through WHOLE on every status (account recovery,
+ * reset-password, passkey sign-in - all anonymous): on a non-OK status, return the same envelope
+ * SHAPE callers already read (`message`, `error.code`, `error.message`) built only from the
+ * whitelisted projection. The success path keeps its passthrough.
+ */
+export function idpErrorEnvelope(json: unknown, fallbackMessage = 'Request failed'): {
+  success: false;
+  message: string;
+  error: { code?: string; message: string; resolution?: string };
+  request_id?: string;
+} {
+  const p = projectIdpError(json);
+  const message = p.message ?? fallbackMessage;
+  const error: { code?: string; message: string; resolution?: string } = { message };
+  if (p.code !== undefined) error.code = p.code;
+  if (p.resolution !== undefined) error.resolution = p.resolution;
+  const out: { success: false; message: string; error: typeof error; request_id?: string } = { success: false, message, error };
+  if (p.request_id !== undefined) out.request_id = p.request_id;
+  return out;
+}
+
+/**
+ * PAY-1591: the IdP refuses a reset password with error.details = { code: 'password_policy', rules: [codes], requirements:
+ * [English] }. This route is anonymous, so only the CODES cross, and only the known ones: never `requirements`, never an
+ * unknown string. Returns undefined when this is NOT a password-policy refusal, and [] when it is one but names no rule we know
+ * (the caller must be able to tell a refused password from a dead recovery session).
+ */
+/**
+ * True only when the IdP EXPLICITLY says the recovery token itself is unusable: details.code token_expired / token_used, or an
+ * ASP.NET Identity `InvalidToken` error in details.value (what the served IdP sends when ResetPasswordAsync refuses a used or
+ * expired token, AccountController.ResetPassword line ~699 at b5c56e6c0). Only this boolean crosses the anonymous route, never the
+ * Identity error text. Anything else is NOT a dead-link signal (rigpert 60822): an older IdP sends a weak-password refusal with
+ * no code at all, and calling that 'link expired' loops the user.
+ */
+export function projectResetTokenInvalid(json: unknown): boolean {
+  if (!json || typeof json !== 'object') return false;
+  const top = json as Record<string, unknown>;
+  const err = top.error && typeof top.error === 'object' ? (top.error as Record<string, unknown>) : {};
+  const details = (err.details && typeof err.details === 'object' ? err.details : top.details && typeof top.details === 'object' ? top.details : null) as Record<string, unknown> | null;
+  if (!details) return false;
+  if (details.code === 'token_expired' || details.code === 'token_used') return true;
+  return Array.isArray(details.value) && details.value.some((v) => !!v && typeof v === 'object' && (v as Record<string, unknown>).code === 'InvalidToken');
+}
+
+export function projectPasswordPolicyRules(json: unknown): string[] | undefined {
+  if (!json || typeof json !== 'object') return undefined;
+  const top = json as Record<string, unknown>;
+  const err = top.error && typeof top.error === 'object' ? (top.error as Record<string, unknown>) : {};
+  const details = (err.details && typeof err.details === 'object' ? err.details : top.details && typeof top.details === 'object' ? top.details : null) as Record<string, unknown> | null;
+  if (!details || details.code !== 'password_policy') return undefined;
+  return knownPasswordRules(details.rules);
+}

package/src/lib/session-cookie-shape.ts

@@ -39,11 +39,16 @@ import {
  * instead of degrading to one clean Redis-canonical lookup (or a genuine
  * 401 if the record really is gone).
  *
- * No signature is verified for the BA-hmac shape here — same posture the
- * pre-existing JWS fallback already took (see auth.ts's `getSession` Path B
- * comment): Redis is the liveness authority downstream, so a forged token
- * still has to land on a live session record to do anything. This function
- * only recovers the CANDIDATE token; callers must still look it up.
+ * No signature is verified here, and none CAN be: this module is secret-free
+ * and synchronous. It only CLASSIFIES and recovers the candidate token.
+ *
+ * PAY-1476: the earlier claim that "Redis is the liveness authority, so a
+ * forged token still has to land on a live session record" was the defect.
+ * A LEAKED token lands on a live record by definition, so without a signature
+ * check the token string alone was a bearer credential. The candidate token
+ * returned here must NEVER be handed to the session store directly: go through
+ * server/verified-session-token.ts resolveVerifiedSessionToken, which verifies
+ * the HMAC (ba-hmac) or the JWS signature first.
  */
 
 export type SessionCookieShape = 'jws' | 'ba-hmac';
@@ -90,20 +95,18 @@ export function extractSessionTokenFromCookieValue(rawValue: string | null | und
   return null;
 }
 
-/** Extract the session token from the Better Auth session cookie WITHOUT
- *  going through Better Auth's `auth.api.getSession()`. Handles both
- *  single-cookie and chunked-cookie cases (Better Auth chunks long values
- *  across `{name}.0`, `{name}.1`, …), and BOTH cookie shapes the codebase
- *  has minted — JWS (legacy NextAuth) and BA-hmac (current Better Auth,
- *  `{token}.{hmac}`) — via `extractSessionTokenFromCookieValue` (183047:
- *  the shape-blind version of this function is what turned a single
- *  BA-primary miss into total, secret-independent fallback failure for
- *  every current cookie, since Better Auth never mints the JWS shape this
- *  used to require). No signature check — Redis is the liveness gate, so
- *  an attacker forging a token still has to land on a real Redis session
- *  (infeasible against high-entropy UUIDs). Returns null if no cookie is
- *  present or neither known shape matches. */
-export function extractSessionTokenFromCookie(request: Request): string | null {
+/** The RAW session-cookie value from a Request, WITHOUT going through Better
+ *  Auth's `auth.api.getSession()`. Handles single and chunked cookies (Better
+ *  Auth chunks long values across `{name}.0`, `{name}.1`, …) and every name the
+ *  cookie is minted under (240654).
+ *
+ *  PAY-1476: this used to be `extractSessionTokenFromCookie`, which returned the
+ *  TOKEN with "No signature check — Redis is the liveness gate". That turned any
+ *  leaked token into a bearer credential. It now returns the raw value only, so
+ *  the one way to get a token out of a request cookie is
+ *  server/verified-session-token.ts resolveVerifiedSessionTokenFromRequest.
+ *  Returns null if no session cookie is present. */
+export function extractSessionCookieValue(request: Request): string | null {
   const cookieHeader = request.headers.get('cookie');
   if (!cookieHeader) return null;
 
@@ -178,7 +181,5 @@ export function extractSessionTokenFromCookie(request: Request): string | null {
     }
   }
 
-  if (!rawJwt) return null;
-
-  return extractSessionTokenFromCookieValue(rawJwt)?.token ?? null;
+  return rawJwt || null;
 }