@payez/next-mvp 4.4.5 → 4.4.7

package/src/lib/ensure-fresh-access-token.ts

@@ -46,6 +46,32 @@ export type EnsureFreshResult =
       accessTokenExpires: number;
       /** True if we refreshed (or a concurrent refresh completed); false if the stored token was already fresh. */
       refreshed: boolean;
+      /**
+       * CARD 320072. Is the token in THIS result actually in the session store?
+       *
+       * ON THIS BRANCH OF THE UNION IT IS ALWAYS `true`, AND THAT IS THE POINT.
+       * Every `ok: true` return either read the token back from the store or
+       * wrote it and confirmed the write. An unpersisted refresh does not reach
+       * an `ok: true` result at all — it returns `ok:false, SESSION_PERSIST_FAILED`
+       * from the other branch below.
+       *
+       * READ THIS BEFORE YOU DELETE THE FIELD. It is declared `boolean` rather
+       * than the literal `true` on purpose: it is the assertable witness that the
+       * escalation is still wired. If someone later re-weakens the persist site
+       * back to reporting success, this field is where that regression becomes
+       * visible to a test instead of invisible to everyone. Cases 2 and 7 in
+       * test/ensure-fresh-persist-failure.test.cjs assert on it.
+       *
+       * WHAT THIS COMMENT USED TO SAY, AND WHY IT IS GONE. It documented `false`
+       * as a live value on an ok:true result — "we hold a valid token that was
+       * not persisted" — because that WAS the contract before this merge, when
+       * the dropped write was reported as a success with a flag on it. Blending
+       * in the escalation made that sentence describe a state the code can no
+       * longer produce. A docblock asserting an impossible semantic is exactly
+       * the defect f5ac6dc3 was written to fix, one file over; reproducing it
+       * here while merging that fix would be absurd.
+       */
+      persisted: boolean;
     }
   | {
       ok: false;
@@ -113,7 +139,8 @@ export async function ensureFreshAccessToken(
   const msUntilExpiry = effectiveExpires - now;
 
   if (msUntilExpiry > safetyWindowMs) {
-    return { ok: true, accessToken: storedToken, accessTokenExpires: effectiveExpires, refreshed: false };
+    // Durable by construction: this token came OUT of the store and we wrote nothing.
+    return { ok: true, accessToken: storedToken, accessTokenExpires: effectiveExpires, refreshed: false, persisted: true };
   }
 
   if (!session.idpRefreshToken) {
@@ -152,6 +179,8 @@ export async function ensureFreshAccessToken(
                 accessToken: after.idpAccessToken,
                 accessTokenExpires: after.idpAccessTokenExpires,
                 refreshed: true,
+                // Read back from the store after the winner's refresh - durable.
+                persisted: true,
               };
             }
           }
@@ -188,6 +217,8 @@ export async function ensureFreshAccessToken(
           accessToken: latest.idpAccessToken,
           accessTokenExpires: latest.idpAccessTokenExpires,
           refreshed: true,
+          // Post-lock re-read: another caller already refreshed and stored this.
+          persisted: true,
         };
       }
     }
@@ -276,12 +307,37 @@ export async function ensureFreshAccessToken(
         const tokenUnchanged =
           !!sentRefreshToken && postRefresh?.idpRefreshToken === sentRefreshToken;
         if (tokenUnchanged) {
-          await updateSession(sessionToken, {
+          /**
+           * 320072: this is the OTHER updateSession call in this file, and it
+           * does NOT escalate on a null return the way the persist site below
+           * does. Checked, not overlooked: reaching here requires
+           * `tokenUnchanged`, which requires `postRefresh?.idpRefreshToken` to
+           * equal the token we sent — so the CAS read three lines up already
+           * proved the row exists. A missing row makes tokenUnchanged false and
+           * routes to the else branch instead, so the dropped-write path is
+           * very nearly unreachable here.
+           *
+           * "Very nearly" is why the return IS still captured. The residual both
+           * halves of this merge identified is real: the row can expire between
+           * that CAS read and this write, in which case the dead refresh token is
+           * NOT cleared and the "we discarded it" claim in the error below is
+           * false. That costs nothing to observe and cannot be inferred from any
+           * other line, so it is warned rather than assumed — see `if (!cleared)`
+           * immediately below. The RESULT is unchanged either way: the session is
+           * unusable and we return the same non-ok payload.
+           */
+          const cleared = await updateSession(sessionToken, {
             idpRefreshToken: '',
             idpRefreshTokenExpires: undefined,
             refreshTokenClearedAt: Date.now(),
             refreshTokenClearedReason: `IDP_DISCARD_TOKEN:${code}`,
           });
+          if (!cleared) {
+            console.warn('[ENSURE-FRESH] discard-token clear did not persist - no canonical session row', {
+              code,
+              requestId,
+            });
+          }
         } else {
           // Concurrent refresh already rotated the token — our 401 is stale. Return the
           // freshly-rotated token directly so the loser succeeds without a retry round-trip
@@ -293,6 +349,8 @@ export async function ensureFreshAccessToken(
               accessToken: postRefresh.idpAccessToken,
               accessTokenExpires: postRefresh.idpAccessTokenExpires,
               refreshed: true,
+              // `postRefresh` is a store read, so this token is by definition stored.
+              persisted: true,
             };
           }
         }
@@ -351,7 +409,14 @@ export async function ensureFreshAccessToken(
     const hasNewRefresh = typeof newRefresh === 'string' && newRefresh.length > 0;
     const newKid = extractKidFromToken(newAccess);
 
-    await updateSession(sessionToken, {
+    // *** CARD 320072. CAPTURE THIS RETURN. ***
+    // `updateSession` returns null - and writes nothing - when the canonical
+    // session row is missing, which happens whenever the BA fallback above is what
+    // resolved this session. Discarding the return is what let this function
+    // report `ok:true, refreshed:true` for a refresh it had just thrown away.
+    // The full rationale for what we DO about it is at the `if (!persisted)`
+    // block below; this line only makes the answer available.
+    const persisted = await updateSession(sessionToken, {
       ...session,
       idpAccessToken: newAccess,
       idpAccessTokenExpires: accessTokenExpires,
@@ -371,7 +436,71 @@ export async function ensureFreshAccessToken(
       mfaValidityHours: decoded?.mfa_validity_hours ? parseInt(decoded.mfa_validity_hours) : session.mfaValidityHours,
     });
 
-    return { ok: true, accessToken: newAccess, accessTokenExpires, refreshed: true };
+    /**
+     * 320072: DO NOT REPORT SUCCESS FOR A WRITE THAT WAS DISCARDED.
+     *
+     * `updateSession` returns null when the canonical session row is absent,
+     * which silently throws away EVERYTHING above — the new access token, the
+     * rotated refresh token, decodedAccessToken, authenticationMethods,
+     * mfaVerified, mfaCompletedAt, mfaExpiresAt. This return value was
+     * previously ignored, and the line below then reported
+     * `ok: true, refreshed: true`.
+     *
+     * WHY THAT IS WORSE THAN A PLAIN LOST WRITE. By this point the exchange at
+     * the IDP has ALREADY HAPPENED, so if refresh tokens are single-use the
+     * token we sent is now spent and its replacement is the thing we just
+     * dropped. The stored credential is therefore dead, and every later attempt
+     * re-sends that same dead token and fails. The user is bounced to LOGIN —
+     * not to verify-code — with nothing in the logs naming the cause.
+     *
+     * It did not even surface as a wrong answer to our one caller: server/auth.ts
+     * calls getRedisSession immediately after us, which is this same `getSession`,
+     * so it finds the same missing row and returns a generic NO_SESSION one frame
+     * later. The false `ok: true` was thus invisible AND the real cause — a
+     * dropped persist — was reported as an unrelated missing session.
+     *
+     * Naming it here is the point: the failure is reported at its true cause,
+     * with a code that says the refresh succeeded and the PERSIST is what
+     * failed. Not retryable — retrying burns another refresh token the same way.
+     *
+     * This is the card's option (b), deliberately. Option (a) — teaching
+     * updateSession to write through to whichever store holds the session,
+     * mirroring the read fallback above — is the better end state but changes
+     * write-path storage semantics for every caller, which is not this card.
+     *
+     * AND IT IS ALSO LOGGED, WHICH IS NOT THE SAME THING (BAPert R1134 §7,
+     * re-affirmed in R1145 §2c). Returning a named code tells the CALLER. §7
+     * requires that `persisted:false` reach a log A HUMAN READS, because the one
+     * caller — server/auth.ts — converts every non-ok result into the same
+     * generic 401 and keeps no record of which code produced it. Without this
+     * line the distinction we just bought at the type level is erased one frame
+     * later and no operator ever sees the word PERSIST. The escalation is the
+     * contract; the warn is the evidence.
+     */
+    if (!persisted) {
+      console.warn('[ENSURE-FRESH] refresh succeeded but was NOT persisted - no canonical session row', {
+        requestId,
+        refreshTokenRotated: hasNewRefresh,
+        persisted: false,
+      });
+      return {
+        ok: false,
+        code: 'SESSION_PERSIST_FAILED',
+        message:
+          'Token refresh succeeded at the IDP but the session could not be persisted; the rotated tokens were discarded.',
+        status: 401,
+        terminal: true,
+        retryable: false,
+        discardToken: true,
+        resolution: 'REAUTHENTICATE',
+      };
+    }
+
+    // `persisted: true` is not decoration and not a leftover: the `if` above is
+    // the only way out for a dropped write, so by construction anything reaching
+    // this line WAS written. Keeping the field keeps the ok:true branch of
+    // EnsureFreshResult total (Cases 2 and 7 assert on it) — BAPert R1145 §2d.
+    return { ok: true, accessToken: newAccess, accessTokenExpires, refreshed: true, persisted: true };
   } finally {
     if (weHoldLock) {
       await releaseRefreshLock(sessionToken, requestId, releaseVersion);

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

@@ -42,6 +42,7 @@
 
 import 'server-only';
 import { createHash, randomUUID } from 'crypto';
+import { markNeverInResponse } from './never-in-response';
 // REDIS IS IMPORTED LAZILY, AND THAT IS LOAD-BEARING.
 // A module-scope `import redis from './redis'` drags ioredis into EVERY bundle that
 // touches this file - including instrumentation.ts. Next compiles the instrumentation
@@ -166,6 +167,81 @@ 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);
+    // PAY-1529: every secret this module resolves is registered as never-in-response HERE, the one place
+    // both fetch paths and the Redis read pass through, so the runtime backstop knows the value whichever
+    // handler later tries to serialize it.
+    markNeverInResponse(auth.value);
+    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);
+            const clientSecret = fromEnv || p.clientSecret;
+            markNeverInResponse(clientSecret);
+            return { ...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 +370,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 +432,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 +585,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 +668,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 +683,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 +749,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 +831,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 +849,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 +865,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 +884,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 +898,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 +972,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 +984,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/never-in-response.ts

@@ -0,0 +1,64 @@
+/**
+ * PAY-1529 runtime backstop: the signing secret and the OAuth provider client secrets must never be
+ * serialized into an HTTP response body.
+ *
+ * The build-time guard (test/secrets-never-in-response-source-guard.test.cjs) follows values through the
+ * source it can see. This is the layer for what it cannot see — a value that crosses a module boundary,
+ * a structuredClone / Object.assign copy, a helper in a consumer app. It tracks the secret by VALUE:
+ * the loader registers every resolved secret here at the moment it resolves it (applyEnvSecrets), and a
+ * response built with `secretSafeJson` / checked with `assertNoServerSecret` FAILS CLOSED — it throws,
+ * and the route answers 500 — if any registered value appears anywhere in the serialized body, under any
+ * key, at any depth, whatever the code that built it called it.
+ *
+ * Bounds, stated rather than implied:
+ *  - Values shorter than MIN_SECRET_LENGTH are not registered. A short string matches innocent bodies and
+ *    would turn this into an outage generator; real signing and provider secrets are far longer.
+ *  - It protects responses that go through it. Adoption is per handler; the build-time guard is what
+ *    covers the handlers that do not.
+ *  - Nothing here ever logs, returns or throws a secret value.
+ */
+import { NextResponse } from 'next/server';
+
+export const MIN_SECRET_LENGTH = 16;
+
+const registered = new Set<string>();
+
+/** Record a value that must never appear in a response body. Non-strings and short strings are ignored. */
+export function markNeverInResponse(value: unknown): void {
+    if (typeof value !== 'string' || value.length < MIN_SECRET_LENGTH) return;
+    registered.add(value);
+    // JSON escapes some characters, so the serialized form of a secret containing `"` or `\` differs from
+    // the raw value. Register that form too, or such a secret would pass through a JSON body unseen.
+    const escaped = JSON.stringify(value).slice(1, -1);
+    if (escaped !== value) registered.add(escaped);
+}
+
+export class SecretInResponseError extends Error {
+    constructor(where: string) {
+        // The message names the route, never the value.
+        super(`[PAY-1529] Refused to serialize a server secret into the response of ${where}`);
+        this.name = 'SecretInResponseError';
+    }
+}
+
+/** Throws SecretInResponseError if any registered secret appears in `body` once serialized. */
+export function assertNoServerSecret(body: unknown, where: string): void {
+    if (registered.size === 0 || body === undefined || body === null) return;
+    let text: string;
+    try {
+        text = typeof body === 'string' ? body : JSON.stringify(body);
+    } catch {
+        // Unserializable: NextResponse.json would throw on it anyway. Fail closed rather than guess.
+        throw new SecretInResponseError(where);
+    }
+    if (!text) return;
+    for (const secret of registered) {
+        if (text.includes(secret)) throw new SecretInResponseError(where);
+    }
+}
+
+/** NextResponse.json, refusing any body that carries a registered secret. */
+export function secretSafeJson<T>(body: T, init: ResponseInit | undefined, where: string): NextResponse<T> {
+    assertNoServerSecret(body, where);
+    return NextResponse.json(body, init);
+}

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(' ');
+}