@payez/next-mvp 4.8.1 → 4.8.3

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

@@ -1,1005 +1,1005 @@
-/* ============================================================================
- *  ONE VALUE, ONE VARIABLE NAME.  CLIENT_ID.
- *
- *  DO NOT INTRODUCE A SECOND ENV VAR CARRYING A VALUE THAT ALREADY HAS ONE.
- *  Not with a prefix. Not "just for the client side". Not "temporarily".
- *
- *  This value had THREE names before 2026-08-26:
- *      CLIENT_ID              read by 8 server files - the real one
- *      NEXT_PUBLIC_CLIENT_ID  read as a fallback in 6 places, ALL server-side
- *      NEXT_CLIENT_ID         read by lib/demo-mode.ts, and set by dev-broker.ps1,
- *                             which meant BROKER MODE NEVER PASSED THE CLIENT ID
- *                             TO THE CONFIG AT ALL. The bug was the extra name.
- *
- *  The NEXT_PUBLIC_ prefix exists so Next inlines a value into the BROWSER bundle.
- *  Nothing in the browser ever read it. So it bought nothing and merely LOOKED
- *  justified - which is worse than an obviously arbitrary name, because it stops
- *  the next person questioning it.
- *
- *  IF YOU NEED THIS VALUE SOMEWHERE NEW, READ CLIENT_ID. If you genuinely need it
- *  in browser code, that is a real Next constraint - raise it, do not quietly add
- *  a second spelling and leave the collision for someone else to measure.
- * ============================================================================ */
-/**
- * IDP Client Configuration
- *
- * Fetches full client configuration from IDP including:
- * - OAuth provider credentials (from Key Vault)
- * - 2FA/MFA settings
- * - Session configuration
- * - Better Auth signing secret
- * - Branding
- *
- * CACHING STRATEGY:
- * 1. In-memory cache (fastest, but lost on module reload in dev)
- * 2. Redis cache (survives module reloads, shared across instances)
- * 3. IDP fetch (when both caches miss)
- *
- * NO FALLBACKS. If IDP doesn't respond correctly, we fail loud.
- *
- * @version 2.0.0 - Added Redis-backed caching
- */
-
-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
-// hook for the EDGE runtime as well as node, and ioredis internally does
-// require('stream'), which does not exist on edge. The result was a BUILD ERROR in the
-// browser overlay for a code path the edge build never executes.
-//
-// The NEXT_RUNTIME check in instrumentation.ts is a RUNTIME guard; the bundler still
-// traces the import statically. Deferring the import to first use is what actually
-// keeps ioredis out of the graph. All four call sites below are already async.
-let _redisMod: typeof import('./redis').default | null = null;
-async function getRedis() {
-  if (!_redisMod) _redisMod = (await import('./redis')).default;
-  return _redisMod;
-}
-
-// ============================================================================
-// Types
-// ============================================================================
-
-export interface OAuthProviderConfig {
-    provider: string;
-    enabled: boolean;
-    clientId: string;
-    clientSecret: string;
-    scopes?: string;
-    additionalParams?: Record<string, any>;
-}
-
-export interface AuthSettings {
-    // 257255 / BAPert v34 DATA sites: these two are POLICY. They are OPTIONAL
-    // because a config document that does not carry a policy must produce a
-    // config with NO policy - not an invented one. Consumers must handle
-    // undefined; routes/auth/settings.ts refuses to serve when they are absent.
-    // The remaining fields below are operational tuning, not authorization, so
-    // their defaults are not in this class.
-    require2FA?: boolean;
-    allowed2FAMethods?: string[];
-    mfaGracePeriodHours: number;
-    mfaRememberDeviceDays: number;
-    sessionTimeoutMinutes: number;
-    idleTimeoutMinutes: number;
-    allowRememberMe: boolean;
-    rememberMeDays: number;
-    lockoutThreshold: number;
-    lockoutDurationMinutes: number;
-
-    /**
-     * 240447: tenant policy the IDP has always sent and this loader never read.
-     *
-     * The IDP emits these inside `auth_settings` on the internal client-config
-     * response (PayEz.Identity.Api InternalClientConfigController, the
-     * `auth_settings` object: allow_public_registration, allow_social_login,
-     * enable_password_reset — backed by IDPClientSecurityPolicy).
-     * routes/auth/settings was answering with hardcoded `true` literals
-     * carrying the comment "Could come from config.authSettings in future",
-     * so the portal advertised self-serve registration for a tenant whose IDP
-     * forbids it (measured same-client same-minute: IDP
-     * allow_public_registration=FALSE, portal allowPublicRegistration=TRUE).
-     *
-     * OPTIONAL ON PURPOSE — `undefined` must stay distinguishable from
-     * `false`. undefined = the IDP did not tell us (older IDP build, or
-     * auth_settings absent entirely); false = the IDP affirmatively said no.
-     * Collapsing the first into a boolean default is exactly how the previous
-     * hardcoded `true` became a lie that read like a measurement. Consumers
-     * must decide explicitly what an unknown means for them.
-     */
-    allowPublicRegistration?: boolean;
-    allowSocialLogin?: boolean;
-    enablePasswordReset?: boolean;
-}
-
-export interface BrandingConfig {
-    theme?: string;
-    primaryColor?: string;
-    secondaryColor?: string;
-    logoUrl?: string;
-}
-
-export interface IDPClientConfig {
-    clientId: string;
-    clientSlug: string;
-    /**
-     * Cryptographic secret used by Better Auth to sign session JWTs.
-     * Historically named "nextAuthSecret" — kept under the new name now.
-     */
-    authSecret: string;
-    configCacheTtlSeconds: number;
-    oauthProviders: OAuthProviderConfig[];
-    authSettings: AuthSettings;
-    branding: BrandingConfig;
-    baseClientUrl?: string; // Public base URL - sets IDENTITY_CLIENT_BASE_EXTERNAL_URL
-}
-
-// ============================================================================
-// Cache & Fetch Deduplication
-// ============================================================================
-
-/**
- * 261588 - THE OPERATOR'S SECRET, CAPTURED BEFORE THIS MODULE CAN CLOBBER IT.
- *
- * startup-init.ts:129 defers to an operator-set BETTER_AUTH_SECRET, and its sibling
- * comment says that override is INTENDED ('allows deployment override for beta/staging').
- * The config-refresh paths in this file then overwrote it minutes later, so a deliberate
- * deployment override survived startup and was silently swapped on the first refresh -
- * sessions signed before and after the swap carry DIFFERENT secrets. A real guard
- * neutralised by a later path that did not get the memo.
- *
- * *** WHY THIS IS A MODULE-LOAD SNAPSHOT AND NOT `if (!process.env.BETTER_AUTH_SECRET)`. ***
- * That naive guard is what the cache path uses (249808). It fixes the override, but it
- * also means that once ANY refresh has populated the variable, NO later refresh can ever
- * update it - so an IDP-side secret ROTATION silently stops propagating and the app keeps
- * signing with a retired key. That trades one silent failure for another.
- *
- * Snapshotting at module load separates the two cases properly:
- *   operator set it  -> never overwritten, for the process lifetime (the override is real)
- *   operator did not -> every refresh may publish, so rotation still works
- *
- * This is read ONCE, at import, before any function here has had a chance to write.
- */
-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) {
-        if (!operatorOverrideLogged) {
-            operatorOverrideLogged = true;
-            console.log(
-                `[IDP_CONFIG] BETTER_AUTH_SECRET was set by the deployment; keeping it and ignoring the ${source} value (261588). ` +
-                'Unset it if you want the IDP to supply the signing secret.'
-            );
-        }
-    } else {
-        process.env.BETTER_AUTH_SECRET = value;
-    }
-    if (!OPERATOR_NEXTAUTH_SECRET) {
-        process.env.NEXTAUTH_SECRET = value;
-    }
-}
-
-let cachedConfig: IDPClientConfig | null = null;
-let cacheExpiry: number = 0;
-let pendingFetch: Promise<IDPClientConfig> | null = null; // Prevents parallel fetches
-
-// ============================================================================
-// Redis Cache Configuration
-// ============================================================================
-
-const REDIS_CONFIG_KEY_PREFIX = 'idp_config:';
-
-/**
- * 263437 - THE CACHE KEY MUST NAME THE BACKEND THE VALUE CAME FROM.
- *
- * The key was `idp_config:{CLIENT_ID}` - client slug ONLY. The cached value is fully
- * determined by (backend origin, clientId): Layer 3 below fetches from
- * INTERNAL_IDP_URL || IDP_URL for CLIENT_ID. Two instances pointed at DIFFERENT IDP
- * backends but carrying the same slug are therefore indistinguishable to this cache,
- * and whichever writes last serves BOTH - with ITS backend's client scope.
- *
- * WHY NOT REDIS_INSTANCE_ID (the originally proposed discriminator):
- * it names the STORE, not the backend. Two legs on separate stores cannot collide in
- * the first place; put them on ONE store - the shape this fix exists to survive - and
- * they report the SAME instance id, so the keys recollide and the bug returns with a
- * fix sitting in front of it. A discriminator that is only distinct in the
- * configuration where the collision is already impossible discriminates nothing.
- *
- * SCOPE NOTE, so this is not over-read the way 273385 was: an undiscriminated key is a
- * LATENT hazard, not the explanation for any wrong-tenant symptom measured on the walk
- * rigs. Measured 2026-08-28 from three seats - the 93 and AKS legs were never on one
- * store, and each backend independently returns the same blob for this slug. If you are
- * chasing a wrong clientId, the value came from the IDP record, not from this cache.
- */
-function getConfigBackendTag(): string {
-    // Must mirror Layer 3's selection EXACTLY (INTERNAL_IDP_URL wins), or the key would
-    // name a backend the value did not come from.
-    const rawBackend = process.env.INTERNAL_IDP_URL || process.env.IDP_URL;
-    if (!rawBackend) {
-        throw new Error(
-            '[IDP_CONFIG] FATAL: INTERNAL_IDP_URL or IDP_URL must be set - the config cache key names the backend the cached value came from'
-        );
-    }
-
-    // ORIGIN, not the full URL: a path or trailing-slash difference is not a different
-    // backend, and letting it fork the key would silently halve the cache hit rate - a
-    // quieter bug in the same family. An unparseable value is used VERBATIM rather than
-    // collapsed to a constant, which would reintroduce the collision it is meant to stop.
-    let backendIdentity: string;
-    try {
-        backendIdentity = new URL(rawBackend).origin.toLowerCase();
-    } catch {
-        backendIdentity = rawBackend.trim().toLowerCase();
-    }
-
-    // A short digest, not the raw origin: keeps keys bounded and does not publish the
-    // internal topology to anyone holding KEYS on a shared store.
-    return createHash('sha256').update(backendIdentity).digest('hex').slice(0, 12);
-}
-
-function getRedisConfigKey(): string {
-    // ONE ENV VAR: CLIENT_ID. Collapsed 2026-08-26.
-    // There were three names for this value - CLIENT_ID, NEXT_PUBLIC_CLIENT_ID and
-    // NEXT_CLIENT_ID. The NEXT_PUBLIC_ prefix exists so Next inlines a value into the
-    // BROWSER bundle; nothing in the browser ever read it, so it bought nothing and
-    // merely looked justified. Verified before removal: all 7 consuming sites set
-    // CLIENT_ID in their env; none relied on the fallback.
-    //
-    // AND IT MUST THROW, NOT DEFAULT. This clientId is the REDIS CACHE KEY. The old
-    // `|| 'default'` meant an app that failed to set the id did not fail - it read and
-    // wrote config under `idp_config:default`, silently sharing one cache slot with
-    // every other misconfigured app, while Layer 3 THREW for that same missing value.
-    // Two behaviours for one missing variable, and the silent one owned the cache.
-    const clientId = process.env.CLIENT_ID;
-    if (!clientId) {
-        throw new Error(
-            '[IDP_CONFIG] FATAL: CLIENT_ID must be set - it is the config cache key, and defaulting it shares one cache entry across misconfigured apps'
-        );
-    }
-    return `${REDIS_CONFIG_KEY_PREFIX}${clientId}:${getConfigBackendTag()}`;
-}
-
-interface RedisCachedConfig {
-    config: IDPClientConfig;
-    expiresAt: number;
-}
-
-async function getConfigFromRedis(): Promise<IDPClientConfig | null> {
-    try {
-        const key = getRedisConfigKey();
-        const cached = await (await getRedis()).get(key);
-        if (!cached) return null;
-
-        const parsed: RedisCachedConfig = JSON.parse(cached);
-        if (Date.now() >= parsed.expiresAt) {
-            // Expired, delete it
-            await (await getRedis()).del(key);
-            return null;
-        }
-
-        return parsed.config;
-    } catch (error) {
-        console.warn('[IDP_CONFIG] Failed to read from Redis cache:', error);
-        return null;
-    }
-}
-
-async function setConfigInRedis(config: IDPClientConfig): Promise<void> {
-    try {
-        const key = getRedisConfigKey();
-        const ttlSeconds = config.configCacheTtlSeconds || 300;
-        const data: RedisCachedConfig = {
-            // 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
-        await (await getRedis()).set(key, JSON.stringify(data), 'EX', ttlSeconds + 10);
-    } catch (error) {
-        console.warn('[IDP_CONFIG] Failed to write to Redis cache:', error);
-    }
-}
-
-// ============================================================================
-// Circuit Breaker & Backoff State
-// ============================================================================
-
-let consecutiveFailures = 0;
-let lastFailureTime = 0;
-const MAX_FAILURES = 3;
-const CIRCUIT_OPEN_MS = 300000; // 5 minutes
-const MAX_BACKOFF_MS = 30000; // 30 seconds max backoff
-
-// ============================================================================
-// Main Functions
-// ============================================================================
-
-/**
- * Get IDP client configuration with multi-tier caching.
- *
- * Caching layers (checked in order):
- * 1. In-memory cache (fastest, lost on module reload in dev)
- * 2. Redis cache (survives module reloads)
- * 3. IDP fetch (when both caches miss)
- *
- * THROWS if IDP is unavailable or misconfigured. No fallbacks.
- */
-export async function getIDPClientConfig(forceRefresh: boolean = false): Promise<IDPClientConfig> {
-    const now = Date.now();
-
-    // Layer 1: Return in-memory cached if still valid (skip if forceRefresh)
-    //
-    // The `cachedConfig.authSecret` term is DEFENCE IN DEPTH, not redundancy.
-    // Both writers are validated (the fetch path checks before caching; the
-    // Redis path requires a non-empty secret to count as a hit), so in principle
-    // an empty config can no longer be cached. This makes that property TRUE AT
-    // THE POINT OF USE instead of only provable by reading the whole file —
-    // DotNetPert 21184 and DotNetPert-Scout 21178 both argued for guarding the
-    // return, and they are right that it is the shape that cannot drift: a
-    // future third writer, or a cache restored from an older build's Redis
-    // entry, is caught here regardless of what the writers do.
-    // The cost is one boolean; the failure it prevents is every session signed
-    // with a secret published on npm.
-    if (!forceRefresh && cachedConfig && cachedConfig.authSecret && now < cacheExpiry) {
-        return cachedConfig;
-    }
-
-    // If a fetch is already in progress, wait for it instead of starting another
-    if (pendingFetch) {
-        return pendingFetch;
-    }
-
-    // Layer 2: Check Redis cache (skip if forceRefresh - startup should always get fresh data)
-    if (!forceRefresh) {
-        // 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
-        // `return`, and not merely around the assignment inside it.
-        // ── 249808 FOLLOW-THROUGH: THE CACHE MAY NEVER *ESTABLISH* THE SECRET. ──
-        //
-        // The rule stated just above - "a cached entry is only USABLE if it
-        // carries a secret" - was right and did not go far enough. The cache
-        // must also never be the FIRST source of the signing secret, because
-        // this blob is unauthenticated (bare JSON.parse, no MAC, and its own
-        // `expiresAt` sits inside the attacker-writable value).
-        //
-        // Guarding the ASSIGNMENT (the earlier 4.1.39 fix) protects a secret
-        // that already exists. It does nothing when none exists yet - and that
-        // window is real: the graft CATCHES the FATAL that startup-init throws
-        // when the IDP is unreachable at boot (graft instrumentation.ts:65-69,
-        // "BETTER_AUTH_SECRET may be unavailable until then"), so the app can
-        // serve requests with no secret established. The first request would
-        // then take the signing key from the cache - which is the whole
-        // forgery vector, arriving through the back door of a fix that had
-        // closed the front one.
-        //
-        // So: with no trusted secret in hand, THIS CACHE ENTRY IS A MISS. Fall
-        // through to Layer 3, the IDP fetch, which is authoritative and already
-        // guarded to throw on an empty secret. Escalation to truth, exactly as
-        // the empty-secret case above does.
-        //
-        // Accepts either name, matching startup-init.ts:147 which verifies
-        // `BETTER_AUTH_SECRET || NEXTAUTH_SECRET` during the rename transition.
-        //
-        // COST, bounded: only while no secret is established does this force an
-        // IDP round trip. startup-init calls getIDPClientConfig(TRUE) and so
-        // skips Layer 2 regardless, meaning normal boot is unaffected; once the
-        // secret exists the cache serves every non-forced caller as before. The
-        // only behaviour that changes is in the window where the alternative was
-        // trusting an unauthenticated store for a signing key.
-        const haveTrustedSecret = !!(process.env.BETTER_AUTH_SECRET || process.env.NEXTAUTH_SECRET);
-        if (redisConfig && redisConfig.authSecret && haveTrustedSecret) {
-            // Restore to in-memory cache
-            cachedConfig = redisConfig;
-            cacheExpiry = Date.now() + ((redisConfig.configCacheTtlSeconds || 300) * 1000);
-
-            // Set BETTER_AUTH_SECRET from cached config (also set legacy
-            // NEXTAUTH_SECRET during the rename transition).
-            //
-            // ⚠ THE EMPTY CASE IS NOT A NO-OP — IT WAS, AND THAT WAS THE HOLE.
-            // The three FETCH paths (:225 external, :353 internal, post-parse)
-            // throw on an empty authSecret, because an empty secret reaching
-            // betterAuth() is silently replaced by the PUBLIC DEFAULT_SECRET
-            // (create-context.mjs:79) rather than rejected. This path used to
-            // just skip the assignment and `return redisConfig` below — so a
-            // cached config with an empty secret bypassed ALL THREE guards, and
-            // it is checked FIRST, before any of them. Redis persistence made it
-            // durable across restarts. Found by QAPert (21175) after I claimed
-            // the guards covered every path; they covered every FETCH path.
-            //
-            // Resolution is deliberately NOT a throw: a corrupt cache entry
-            // should not take the app down when the authoritative source is one
-            // call away. Treat it as a MISS and fall through to the fetch paths,
-            // which are guarded and will throw if the IDP is genuinely empty.
-            // That is escalation to truth, not a fallback that weakens the check.
-            // ── 249808: AN EXPLICIT BETTER_AUTH_SECRET NOW WINS OVER THE CACHE. ──
-            //
-            // These two assignments were UNCONDITIONAL. That made the Redis
-            // cache authoritative for the SESSION SIGNING KEY, and the cache is
-            // not a trusted input: getConfigFromRedis() does a bare JSON.parse
-            // with no signature or MAC, and its only freshness check is an
-            // `expiresAt` field that lives INSIDE the same attacker-writable
-            // blob. So anyone who could write that key chose the signing secret,
-            // and knowing the secret means minting a validly-signed session for
-            // any user — including one who has never logged in. Forgery, not
-            // theft: it survives flushing the store and revoking refresh tokens,
-            // because it needs neither.
-            //
-            // THE FILE ALREADY KNEW THE RIGHT PATTERN. Five lines below, a mere
-            // URL defers to an explicitly-configured value, with a comment
-            // blessing deployment override. startup-init.ts:129 defers on THIS
-            // VERY SECRET (`config.authSecret && !process.env.BETTER_AUTH_SECRET`).
-            // The signing key was the one value in the package taking an
-            // untrusted cache's word unconditionally — protected less carefully
-            // than a base URL.
-            //
-            // Deferring restores that consistency and makes an explicitly-set
-            // BETTER_AUTH_SECRET a REAL secret: a value the deployment owns and
-            // the cache cannot override.
-            //
-            // BOUND, stated so nobody over-reads this: it closes the vector only
-            // where BETTER_AUTH_SECRET IS ACTUALLY SET. Where it is unset the
-            // cache still supplies it and the exposure stands — so this is
-            // necessary, cheap and strictly-better, NOT sufficient on its own.
-            // Locking the store and setting the secret explicitly in every
-            // deployment remain required.
-            publishAuthSecret(redisConfig.authSecret, 'Redis-cached IDP config');
-
-            // Set IDENTITY_CLIENT_BASE_EXTERNAL_URL from cached config.
-            // Only set if not already defined (allows deployment override for beta/staging).
-            if (redisConfig.baseClientUrl && !process.env.IDENTITY_CLIENT_BASE_EXTERNAL_URL) {
-                process.env.IDENTITY_CLIENT_BASE_EXTERNAL_URL = redisConfig.baseClientUrl;
-            }
-
-            return redisConfig;
-        }
-    }
-
-    // Layer 3: Fetch from IDP
-    const internalIdpUrl = process.env.INTERNAL_IDP_URL;
-    const idpUrl = process.env.IDP_URL;
-    // CLIENT_ID only - see the note at the cache-key site above.
-    const clientIdStr = process.env.CLIENT_ID;
-
-    if (!clientIdStr) {
-        throw new Error('[IDP_CONFIG] FATAL: CLIENT_ID must be set');
-    }
-    if (!internalIdpUrl && !idpUrl) {
-        throw new Error('[IDP_CONFIG] FATAL: INTERNAL_IDP_URL or IDP_URL must be set');
-    }
-
-    // Start fetch and store promise so concurrent callers wait for same result
-    const fetcher = internalIdpUrl
-        ? fetchConfigFromInternalIDP(internalIdpUrl, clientIdStr)
-        : fetchConfigFromIDP(idpUrl!, clientIdStr);
-    pendingFetch = fetcher
-        .then(async config => {
-            // ── VALIDATE BEFORE CACHING. ORDER IS THE WHOLE FIX. ────────────
-            // This block used to assign cachedConfig and await setConfigInRedis
-            // FIRST and throw afterwards — so a response with an empty secret
-            // poisoned BOTH caches on its way to failing. The throw only stopped
-            // THAT call: the next one hit the in-memory layer (`return
-            // cachedConfig`), which has no guard because it is a cache read, and
-            // handed the empty config to betterAuth() — where empty silently
-            // becomes the public DEFAULT_SECRET. Redis made it survive restarts.
-            //
-            // Guarding every cached RETURN would also work, and DotNetPert-Scout
-            // (21178) is right that it is the more robust shape in general. But
-            // there are four such returns and one writer, and the invariant we
-            // actually want is "an unvalidated config is never cached at all".
-            // Enforce it where it is cheapest to keep true.
-            if (!config.authSecret) {
-                // ⚠ LOAD-BEARING THROW — DO NOT SOFTEN TO A DEFAULT OR A WARNING.
-                // better-auth does NOT treat an empty secret as missing: at
-                // create-context.mjs:79 it substitutes DEFAULT_SECRET
-                // ("better-auth-secret-12345678901234567890"), which ships in the
-                // PUBLIC npm package, and its !secret guard can then never fire.
-                // The only remaining protection there is an isProduction gate — so
-                // outside production an empty secret means every session is signed
-                // with a string anyone can read off npm and forge.
-                // 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 and neither BETTER_AUTH_SECRET nor NEXTAUTH_SECRET is set');
-            }
-
-            // Validated above — only now is it safe to cache or publish.
-            publishAuthSecret(config.authSecret, 'freshly-fetched IDP config');
-
-            // Cache with TTL from response (default 5 minutes)
-            cachedConfig = config;
-            cacheExpiry = Date.now() + ((config.configCacheTtlSeconds || 300) * 1000);
-
-            // Store in Redis for persistence across module reloads. This is the
-            // write that made a bad config outlive the process, so it must stay
-            // BELOW the guard, never above it.
-            await setConfigInRedis(config);
-
-            // Set IDENTITY_CLIENT_BASE_EXTERNAL_URL from config.
-            // Only set if not already defined (allows deployment override for beta/staging).
-            if (config.baseClientUrl && !process.env.IDENTITY_CLIENT_BASE_EXTERNAL_URL) {
-                process.env.IDENTITY_CLIENT_BASE_EXTERNAL_URL = config.baseClientUrl;
-                console.log("[IDP_CONFIG] Set IDENTITY_CLIENT_BASE_EXTERNAL_URL:", config.baseClientUrl);
-            }
-
-            return config;
-        })
-        .finally(() => {
-            pendingFetch = null; // Clear so next cache miss can fetch again
-        });
-
-    return pendingFetch;
-}
-
-/**
- * Clear the config cache (useful for testing or forced refresh)
- */
-export function clearConfigCache(): void {
-    cachedConfig = null;
-    cacheExpiry = 0;
-}
-
-/**
- * Clear the Redis config cache so the next fetch always goes to IDP.
- */
-export async function clearConfigRedisCache(): Promise<void> {
-    try {
-        const key = getRedisConfigKey();
-        await (await getRedis()).del(key);
-        console.log('[IDP_CONFIG] Redis cache cleared:', key);
-    } catch (error) {
-        console.warn('[IDP_CONFIG] Failed to clear Redis cache:', error);
-    }
-}
-
-/**
- * Get enabled OAuth providers from config
- */
-export function getEnabledProviders(config: IDPClientConfig): OAuthProviderConfig[] {
-    return config.oauthProviders?.filter(p => p.enabled) || [];
-}
-
-// ============================================================================
-// Internal Functions
-// ============================================================================
-
-async function fetchConfigFromInternalIDP(internalIdpUrl: string, clientIdStr: string): Promise<IDPClientConfig> {
-    const containersKey = process.env.CONTAINERS_KEY;
-    if (!containersKey) {
-        throw new Error('[IDP_CONFIG] FATAL: CONTAINERS_KEY is required when using INTERNAL_IDP_URL');
-    }
-
-    const url = `${internalIdpUrl.replace(/\/$/, '')}/InternalClientConfig/${encodeURIComponent(clientIdStr)}`;
-    console.log(`[IDP_CONFIG] Fetching config from internal IDP: ${url}`);
-
-    const resp = await fetch(url, {
-        method: 'GET',
-        headers: {
-            'Accept': 'application/json',
-            'Authorization': `Secret ${containersKey}`,
-        },
-        cache: 'no-store'
-    } as RequestInit);
-
-    if (!resp.ok) {
-        const txt = await resp.text().catch(() => 'Unknown error');
-        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);
-    if (!body) {
-        throw new Error('[IDP_CONFIG] FATAL: Internal IDP returned empty or invalid JSON');
-    }
-
-    const configData = body?.data ?? body;
-
-    const rawClientId = configData.clientId ?? configData.client_id;
-    if (rawClientId === undefined || rawClientId === null) {
-        throw new Error(`[IDP_CONFIG] FATAL: Internal IDP response missing clientId. Got: ${JSON.stringify(Object.keys(configData))}`);
-    }
-
-    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
-        // nextAuthSecret/next_auth_secret while IDP rename rolls out.
-        authSecret:
-            configData.authSecret ??
-            configData.auth_secret ??
-            configData.nextAuthSecret ??
-            configData.next_auth_secret ??
-            '',
-        configCacheTtlSeconds: configData.configCacheTtlSeconds ?? configData.config_cache_ttl_seconds ?? 300,
-        oauthProviders: (configData.oauthProviders ?? configData.oauth_providers ?? []).map((p: any) => ({
-            provider: p.provider ?? '',
-            enabled: p.enabled ?? false,
-            clientId: p.clientId ?? p.client_id ?? '',
-            clientSecret: p.clientSecret ?? p.client_secret ?? '',
-            scopes: p.scopes,
-            additionalParams: p.additionalParams ?? p.additional_params
-        })),
-        authSettings: {
-            // 257255: terminal `?? true` / `?? ['email','sms']` REMOVED. They
-            // made a document with NO auth policy indistinguishable from one
-            // carrying exactly those values, one layer below the route that
-            // reports policy - so even a corrected settings.ts would have
-            // validated a fabrication. Undefined now means "not carried".
-            require2FA: configData.authSettings?.require2FA ?? configData.auth_settings?.require_2fa,
-            allowed2FAMethods: configData.authSettings?.allowed2FAMethods ?? configData.auth_settings?.allowed_2fa_methods,
-            mfaGracePeriodHours: configData.authSettings?.mfaGracePeriodHours ?? configData.auth_settings?.mfa_grace_period_hours ?? 24,
-            mfaRememberDeviceDays: configData.authSettings?.mfaRememberDeviceDays ?? configData.auth_settings?.mfa_remember_device_days ?? 30,
-            sessionTimeoutMinutes: configData.authSettings?.sessionTimeoutMinutes ?? configData.auth_settings?.session_timeout_minutes ?? 60,
-            idleTimeoutMinutes: configData.authSettings?.idleTimeoutMinutes ?? configData.auth_settings?.idle_timeout_minutes ?? 15,
-            allowRememberMe: configData.authSettings?.allowRememberMe ?? configData.auth_settings?.allow_remember_me ?? true,
-            rememberMeDays: configData.authSettings?.rememberMeDays ?? configData.auth_settings?.remember_me_days ?? 30,
-            lockoutThreshold: configData.authSettings?.lockoutThreshold ?? configData.auth_settings?.lockout_threshold ?? 5,
-            lockoutDurationMinutes: configData.authSettings?.lockoutDurationMinutes ?? configData.auth_settings?.lockout_duration_minutes ?? 15,
-
-            // 240447: read the tenant policy the IDP already sends. Applied to
-            // BOTH parse paths (fetchConfigFromInternalIDP and
-            // fetchConfigFromIDP) — fixing one would leave the other silently
-            // omitting these, which is the partial-fix trap.
-            //
-            // Same dual-casing idiom as every field above, but with NO
-            // `?? default` tail, deliberately. The others default because a
-            // wrong timeout is a nuisance; a wrong registration flag is a LIE
-            // about what the tenant permits, and the hardcoded `true` in
-            // routes/auth/settings was exactly that lie. `undefined` has to
-            // survive to the consumer so it can decide, instead of being
-            // handed a guess wearing the costume of a measurement.
-            allowPublicRegistration:
-                configData.authSettings?.allowPublicRegistration ??
-                configData.auth_settings?.allow_public_registration,
-            allowSocialLogin:
-                configData.authSettings?.allowSocialLogin ??
-                configData.auth_settings?.allow_social_login,
-            enablePasswordReset:
-                configData.authSettings?.enablePasswordReset ??
-                configData.auth_settings?.enable_password_reset
-        },
-        branding: {
-            theme: configData.branding?.theme,
-            primaryColor: configData.branding?.primaryColor ?? configData.branding?.primary_color,
-            secondaryColor: configData.branding?.secondaryColor ?? configData.branding?.secondary_color,
-            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 and neither BETTER_AUTH_SECRET nor NEXTAUTH_SECRET is set');
-    }
-
-    console.log(`[IDP_CONFIG] Internal IDP config loaded for ${clientIdStr}`);
-    consecutiveFailures = 0;
-    return config;
-}
-
-async function fetchConfigFromIDP(idpUrl: string, clientIdStr: string): Promise<IDPClientConfig> {
-    // =========================================================================
-    // Circuit Breaker Check
-    // =========================================================================
-    if (consecutiveFailures >= MAX_FAILURES) {
-        const timeSinceFailure = Date.now() - lastFailureTime;
-        if (timeSinceFailure < CIRCUIT_OPEN_MS) {
-            // Circuit is open - return stale cache if available
-            // Stale cache is acceptable here; a stale config with NO SECRET is
-            // not. These two paths fire exactly when the IDP is unreachable —
-            // the worst moment to hand betterAuth() an empty secret, which it
-            // silently upgrades to the public DEFAULT_SECRET. Falling through to
-            // a hard failure is correct: unavailable beats forgeable.
-            if (cachedConfig && cachedConfig.authSecret) {
-                return cachedConfig;
-            }
-            throw new Error(`[IDP_CONFIG] Circuit breaker OPEN - no cached config available. Retry in ${Math.round((CIRCUIT_OPEN_MS - timeSinceFailure) / 1000)}s`);
-        }
-        // Half-open state: allow one request to test
-        consecutiveFailures = MAX_FAILURES - 1;
-    }
-
-    // =========================================================================
-    // Exponential Backoff Check
-    // =========================================================================
-    if (consecutiveFailures > 0) {
-        const backoffMs = Math.min(1000 * Math.pow(2, consecutiveFailures), MAX_BACKOFF_MS);
-        const timeSinceFailure = Date.now() - lastFailureTime;
-        if (timeSinceFailure < backoffMs) {
-            const remainingMs = backoffMs - timeSinceFailure;
-            // Return stale cache during backoff if available
-            // Stale cache is acceptable here; a stale config with NO SECRET is
-            // not. These two paths fire exactly when the IDP is unreachable —
-            // the worst moment to hand betterAuth() an empty secret, which it
-            // silently upgrades to the public DEFAULT_SECRET. Falling through to
-            // a hard failure is correct: unavailable beats forgeable.
-            if (cachedConfig && cachedConfig.authSecret) {
-                return cachedConfig;
-            }
-            throw new Error(`[IDP_CONFIG] In backoff period - retry in ${Math.round(remainingMs)}ms`);
-        }
-    }
-
-    try {
-    // Step 1: Get signed client assertion from IDP
-    const signingUrl = `${idpUrl.replace(/\/$/, '')}/api/ExternalAuth/sign-client-assertion`;
-
-    const signingPayload = {
-        issuer: clientIdStr,
-        subject: clientIdStr,
-        audience: 'urn:payez:externalauth:clientconfig',
-        expires_in: 60,
-    };
-
-    const signingResp = await fetch(signingUrl, {
-        method: 'POST',
-        headers: {
-            'Accept': 'application/json',
-            'Content-Type': 'application/json',
-            'X-Client-Id': clientIdStr,
-            'X-Correlation-Id': randomUUID().replace(/-/g, ''),
-        },
-        body: JSON.stringify(signingPayload),
-        cache: 'no-store'
-    } as RequestInit);
-
-    if (!signingResp.ok) {
-        const txt = await signingResp.text().catch(() => 'Unknown error');
-        // 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);
-
-    if (!signingBody) {
-        throw new Error('[IDP_CONFIG] FATAL: IDP returned empty or invalid JSON for sign-client-assertion');
-    }
-
-    // Per PayEz API standard: response is { success, data: { client_assertion }, ... }
-    // But IDP might use camelCase (clientAssertion) - check both
-    const client_assertion = (
-        signingBody?.data?.client_assertion ??
-        signingBody?.data?.clientAssertion
-    ) as string | undefined;
-
-    if (!client_assertion) {
-        // 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 || {}))}`);
-    }
-
-    // Step 2: Fetch client config using the assertion
-    const configUrl = `${idpUrl.replace(/\/$/, '')}/api/ExternalAuth/client-config`;
-
-    const configResp = await fetch(configUrl, {
-        method: 'POST',
-        headers: {
-            'Accept': 'application/json',
-            'Content-Type': 'application/json',
-            'X-Client-Id': clientIdStr,
-            'X-Correlation-Id': randomUUID().replace(/-/g, ''),
-        },
-        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} (body ${txt.length} chars)`);
-    }
-
-    const configBody: any = await configResp.json().catch(() => null);
-
-    if (!configBody) {
-        throw new Error('[IDP_CONFIG] FATAL: IDP returned empty or invalid JSON for client-config');
-    }
-
-    // Per PayEz API standard: response is wrapped in { success, data: {...} }
-    const configData = configBody?.data;
-
-    if (!configData || typeof configData !== 'object') {
-        // 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');
-    }
-
-    // Validate required fields - handle both number and string client_id
-    const rawClientId = configData.clientId ?? configData.client_id;
-    if (rawClientId === undefined || rawClientId === null) {
-        throw new Error(`[IDP_CONFIG] FATAL: IDP response missing clientId/client_id. Got: ${JSON.stringify(Object.keys(configData))}`);
-    }
-
-    // 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 = applyEnvSecrets({
-        clientId: String(rawClientId),
-        clientSlug: configData.clientSlug ?? configData.client_slug ?? configData.slug ?? '',
-        authSecret:
-            configData.authSecret ??
-            configData.auth_secret ??
-            configData.nextAuthSecret ??
-            configData.next_auth_secret ??
-            '',
-        configCacheTtlSeconds: configData.configCacheTtlSeconds ?? configData.config_cache_ttl_seconds ?? 300,
-        oauthProviders: (configData.oauthProviders ?? configData.oauth_providers ?? []).map((p: any) => ({
-            provider: p.provider ?? '',
-            enabled: p.enabled ?? false,
-            clientId: p.clientId ?? p.client_id ?? '',
-            clientSecret: p.clientSecret ?? p.client_secret ?? '',
-            scopes: p.scopes,
-            additionalParams: p.additionalParams ?? p.additional_params
-        })),
-        authSettings: {
-            require2FA: (() => {
-                // Check nested locations first (canonical)
-                const nested = configData.authSettings?.require2FA ?? configData.auth_settings?.require_2fa;
-                if (nested !== undefined) return nested;
-                // TRANSITION FALLBACK: Check top-level (deprecated)
-                const topLevel = configData.require2FA ?? configData.require_2fa;
-                if (topLevel !== undefined) {
-                    console.warn('[IDP_CONFIG] DEPRECATION: require2FA found at top-level. Should be nested under auth_settings. Update IDP.');
-                    return topLevel;
-                }
-                // 257255: was `return true`. A default here is a FABRICATED
-                // POLICY - QAPert measured the same client as require_2fa TRUE
-                // on AKS and FALSE on dev-93, so any constant is wrong in one
-                // environment by construction. Undefined = "not carried".
-                return undefined;
-            })(),
-            allowed2FAMethods: configData.authSettings?.allowed2FAMethods ?? configData.auth_settings?.allowed_2fa_methods,
-            mfaGracePeriodHours: configData.authSettings?.mfaGracePeriodHours ?? configData.auth_settings?.mfa_grace_period_hours ?? 24,
-            mfaRememberDeviceDays: configData.authSettings?.mfaRememberDeviceDays ?? configData.auth_settings?.mfa_remember_device_days ?? 30,
-            sessionTimeoutMinutes: configData.authSettings?.sessionTimeoutMinutes ?? configData.auth_settings?.session_timeout_minutes ?? 60,
-            idleTimeoutMinutes: configData.authSettings?.idleTimeoutMinutes ?? configData.auth_settings?.idle_timeout_minutes ?? 15,
-            allowRememberMe: configData.authSettings?.allowRememberMe ?? configData.auth_settings?.allow_remember_me ?? true,
-            rememberMeDays: configData.authSettings?.rememberMeDays ?? configData.auth_settings?.remember_me_days ?? 30,
-            lockoutThreshold: configData.authSettings?.lockoutThreshold ?? configData.auth_settings?.lockout_threshold ?? 5,
-            lockoutDurationMinutes: configData.authSettings?.lockoutDurationMinutes ?? configData.auth_settings?.lockout_duration_minutes ?? 15,
-
-            // 240447: read the tenant policy the IDP already sends. Applied to
-            // BOTH parse paths (fetchConfigFromInternalIDP and
-            // fetchConfigFromIDP) — fixing one would leave the other silently
-            // omitting these, which is the partial-fix trap.
-            //
-            // Same dual-casing idiom as every field above, but with NO
-            // `?? default` tail, deliberately. The others default because a
-            // wrong timeout is a nuisance; a wrong registration flag is a LIE
-            // about what the tenant permits, and the hardcoded `true` in
-            // routes/auth/settings was exactly that lie. `undefined` has to
-            // survive to the consumer so it can decide, instead of being
-            // handed a guess wearing the costume of a measurement.
-            allowPublicRegistration:
-                configData.authSettings?.allowPublicRegistration ??
-                configData.auth_settings?.allow_public_registration,
-            allowSocialLogin:
-                configData.authSettings?.allowSocialLogin ??
-                configData.auth_settings?.allow_social_login,
-            enablePasswordReset:
-                configData.authSettings?.enablePasswordReset ??
-                configData.auth_settings?.enable_password_reset
-        },
-        branding: {
-            theme: configData.branding?.theme,
-            primaryColor: configData.branding?.primaryColor ?? configData.branding?.primary_color,
-            secondaryColor: configData.branding?.secondaryColor ?? configData.branding?.secondary_color,
-            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')));
-
-    // Validate we got what we need
-    if (!config.clientId) {
-        throw new Error('[IDP_CONFIG] FATAL: clientId is empty or missing after parsing');
-    }
-    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 and neither BETTER_AUTH_SECRET nor NEXTAUTH_SECRET is set');
-    }
-
-    // Success - reset failure tracking
-    consecutiveFailures = 0;
-    return config;
-
-    } catch (error) {
-        // Track failure for circuit breaker
-        consecutiveFailures++;
-        lastFailureTime = Date.now();
-        console.error('[IDP_CONFIG] Fetch failed', {
-            consecutiveFailures,
-            maxFailures: MAX_FAILURES,
-            error: error instanceof Error ? error.message : String(error)
-        });
-        throw error;
-    }
-}
+/* ============================================================================
+ *  ONE VALUE, ONE VARIABLE NAME.  CLIENT_ID.
+ *
+ *  DO NOT INTRODUCE A SECOND ENV VAR CARRYING A VALUE THAT ALREADY HAS ONE.
+ *  Not with a prefix. Not "just for the client side". Not "temporarily".
+ *
+ *  This value had THREE names before 2026-08-26:
+ *      CLIENT_ID              read by 8 server files - the real one
+ *      NEXT_PUBLIC_CLIENT_ID  read as a fallback in 6 places, ALL server-side
+ *      NEXT_CLIENT_ID         read by lib/demo-mode.ts, and set by dev-broker.ps1,
+ *                             which meant BROKER MODE NEVER PASSED THE CLIENT ID
+ *                             TO THE CONFIG AT ALL. The bug was the extra name.
+ *
+ *  The NEXT_PUBLIC_ prefix exists so Next inlines a value into the BROWSER bundle.
+ *  Nothing in the browser ever read it. So it bought nothing and merely LOOKED
+ *  justified - which is worse than an obviously arbitrary name, because it stops
+ *  the next person questioning it.
+ *
+ *  IF YOU NEED THIS VALUE SOMEWHERE NEW, READ CLIENT_ID. If you genuinely need it
+ *  in browser code, that is a real Next constraint - raise it, do not quietly add
+ *  a second spelling and leave the collision for someone else to measure.
+ * ============================================================================ */
+/**
+ * IDP Client Configuration
+ *
+ * Fetches full client configuration from IDP including:
+ * - OAuth provider credentials (from Key Vault)
+ * - 2FA/MFA settings
+ * - Session configuration
+ * - Better Auth signing secret
+ * - Branding
+ *
+ * CACHING STRATEGY:
+ * 1. In-memory cache (fastest, but lost on module reload in dev)
+ * 2. Redis cache (survives module reloads, shared across instances)
+ * 3. IDP fetch (when both caches miss)
+ *
+ * NO FALLBACKS. If IDP doesn't respond correctly, we fail loud.
+ *
+ * @version 2.0.0 - Added Redis-backed caching
+ */
+
+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
+// hook for the EDGE runtime as well as node, and ioredis internally does
+// require('stream'), which does not exist on edge. The result was a BUILD ERROR in the
+// browser overlay for a code path the edge build never executes.
+//
+// The NEXT_RUNTIME check in instrumentation.ts is a RUNTIME guard; the bundler still
+// traces the import statically. Deferring the import to first use is what actually
+// keeps ioredis out of the graph. All four call sites below are already async.
+let _redisMod: typeof import('./redis').default | null = null;
+async function getRedis() {
+  if (!_redisMod) _redisMod = (await import('./redis')).default;
+  return _redisMod;
+}
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface OAuthProviderConfig {
+    provider: string;
+    enabled: boolean;
+    clientId: string;
+    clientSecret: string;
+    scopes?: string;
+    additionalParams?: Record<string, any>;
+}
+
+export interface AuthSettings {
+    // 257255 / BAPert v34 DATA sites: these two are POLICY. They are OPTIONAL
+    // because a config document that does not carry a policy must produce a
+    // config with NO policy - not an invented one. Consumers must handle
+    // undefined; routes/auth/settings.ts refuses to serve when they are absent.
+    // The remaining fields below are operational tuning, not authorization, so
+    // their defaults are not in this class.
+    require2FA?: boolean;
+    allowed2FAMethods?: string[];
+    mfaGracePeriodHours: number;
+    mfaRememberDeviceDays: number;
+    sessionTimeoutMinutes: number;
+    idleTimeoutMinutes: number;
+    allowRememberMe: boolean;
+    rememberMeDays: number;
+    lockoutThreshold: number;
+    lockoutDurationMinutes: number;
+
+    /**
+     * 240447: tenant policy the IDP has always sent and this loader never read.
+     *
+     * The IDP emits these inside `auth_settings` on the internal client-config
+     * response (PayEz.Identity.Api InternalClientConfigController, the
+     * `auth_settings` object: allow_public_registration, allow_social_login,
+     * enable_password_reset — backed by IDPClientSecurityPolicy).
+     * routes/auth/settings was answering with hardcoded `true` literals
+     * carrying the comment "Could come from config.authSettings in future",
+     * so the portal advertised self-serve registration for a tenant whose IDP
+     * forbids it (measured same-client same-minute: IDP
+     * allow_public_registration=FALSE, portal allowPublicRegistration=TRUE).
+     *
+     * OPTIONAL ON PURPOSE — `undefined` must stay distinguishable from
+     * `false`. undefined = the IDP did not tell us (older IDP build, or
+     * auth_settings absent entirely); false = the IDP affirmatively said no.
+     * Collapsing the first into a boolean default is exactly how the previous
+     * hardcoded `true` became a lie that read like a measurement. Consumers
+     * must decide explicitly what an unknown means for them.
+     */
+    allowPublicRegistration?: boolean;
+    allowSocialLogin?: boolean;
+    enablePasswordReset?: boolean;
+}
+
+export interface BrandingConfig {
+    theme?: string;
+    primaryColor?: string;
+    secondaryColor?: string;
+    logoUrl?: string;
+}
+
+export interface IDPClientConfig {
+    clientId: string;
+    clientSlug: string;
+    /**
+     * Cryptographic secret used by Better Auth to sign session JWTs.
+     * Historically named "nextAuthSecret" — kept under the new name now.
+     */
+    authSecret: string;
+    configCacheTtlSeconds: number;
+    oauthProviders: OAuthProviderConfig[];
+    authSettings: AuthSettings;
+    branding: BrandingConfig;
+    baseClientUrl?: string; // Public base URL - sets IDENTITY_CLIENT_BASE_EXTERNAL_URL
+}
+
+// ============================================================================
+// Cache & Fetch Deduplication
+// ============================================================================
+
+/**
+ * 261588 - THE OPERATOR'S SECRET, CAPTURED BEFORE THIS MODULE CAN CLOBBER IT.
+ *
+ * startup-init.ts:129 defers to an operator-set BETTER_AUTH_SECRET, and its sibling
+ * comment says that override is INTENDED ('allows deployment override for beta/staging').
+ * The config-refresh paths in this file then overwrote it minutes later, so a deliberate
+ * deployment override survived startup and was silently swapped on the first refresh -
+ * sessions signed before and after the swap carry DIFFERENT secrets. A real guard
+ * neutralised by a later path that did not get the memo.
+ *
+ * *** WHY THIS IS A MODULE-LOAD SNAPSHOT AND NOT `if (!process.env.BETTER_AUTH_SECRET)`. ***
+ * That naive guard is what the cache path uses (249808). It fixes the override, but it
+ * also means that once ANY refresh has populated the variable, NO later refresh can ever
+ * update it - so an IDP-side secret ROTATION silently stops propagating and the app keeps
+ * signing with a retired key. That trades one silent failure for another.
+ *
+ * Snapshotting at module load separates the two cases properly:
+ *   operator set it  -> never overwritten, for the process lifetime (the override is real)
+ *   operator did not -> every refresh may publish, so rotation still works
+ *
+ * This is read ONCE, at import, before any function here has had a chance to write.
+ */
+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) {
+        if (!operatorOverrideLogged) {
+            operatorOverrideLogged = true;
+            console.log(
+                `[IDP_CONFIG] BETTER_AUTH_SECRET was set by the deployment; keeping it and ignoring the ${source} value (261588). ` +
+                'Unset it if you want the IDP to supply the signing secret.'
+            );
+        }
+    } else {
+        process.env.BETTER_AUTH_SECRET = value;
+    }
+    if (!OPERATOR_NEXTAUTH_SECRET) {
+        process.env.NEXTAUTH_SECRET = value;
+    }
+}
+
+let cachedConfig: IDPClientConfig | null = null;
+let cacheExpiry: number = 0;
+let pendingFetch: Promise<IDPClientConfig> | null = null; // Prevents parallel fetches
+
+// ============================================================================
+// Redis Cache Configuration
+// ============================================================================
+
+const REDIS_CONFIG_KEY_PREFIX = 'idp_config:';
+
+/**
+ * 263437 - THE CACHE KEY MUST NAME THE BACKEND THE VALUE CAME FROM.
+ *
+ * The key was `idp_config:{CLIENT_ID}` - client slug ONLY. The cached value is fully
+ * determined by (backend origin, clientId): Layer 3 below fetches from
+ * INTERNAL_IDP_URL || IDP_URL for CLIENT_ID. Two instances pointed at DIFFERENT IDP
+ * backends but carrying the same slug are therefore indistinguishable to this cache,
+ * and whichever writes last serves BOTH - with ITS backend's client scope.
+ *
+ * WHY NOT REDIS_INSTANCE_ID (the originally proposed discriminator):
+ * it names the STORE, not the backend. Two legs on separate stores cannot collide in
+ * the first place; put them on ONE store - the shape this fix exists to survive - and
+ * they report the SAME instance id, so the keys recollide and the bug returns with a
+ * fix sitting in front of it. A discriminator that is only distinct in the
+ * configuration where the collision is already impossible discriminates nothing.
+ *
+ * SCOPE NOTE, so this is not over-read the way 273385 was: an undiscriminated key is a
+ * LATENT hazard, not the explanation for any wrong-tenant symptom measured on the walk
+ * rigs. Measured 2026-08-28 from three seats - the 93 and AKS legs were never on one
+ * store, and each backend independently returns the same blob for this slug. If you are
+ * chasing a wrong clientId, the value came from the IDP record, not from this cache.
+ */
+function getConfigBackendTag(): string {
+    // Must mirror Layer 3's selection EXACTLY (INTERNAL_IDP_URL wins), or the key would
+    // name a backend the value did not come from.
+    const rawBackend = process.env.INTERNAL_IDP_URL || process.env.IDP_URL;
+    if (!rawBackend) {
+        throw new Error(
+            '[IDP_CONFIG] FATAL: INTERNAL_IDP_URL or IDP_URL must be set - the config cache key names the backend the cached value came from'
+        );
+    }
+
+    // ORIGIN, not the full URL: a path or trailing-slash difference is not a different
+    // backend, and letting it fork the key would silently halve the cache hit rate - a
+    // quieter bug in the same family. An unparseable value is used VERBATIM rather than
+    // collapsed to a constant, which would reintroduce the collision it is meant to stop.
+    let backendIdentity: string;
+    try {
+        backendIdentity = new URL(rawBackend).origin.toLowerCase();
+    } catch {
+        backendIdentity = rawBackend.trim().toLowerCase();
+    }
+
+    // A short digest, not the raw origin: keeps keys bounded and does not publish the
+    // internal topology to anyone holding KEYS on a shared store.
+    return createHash('sha256').update(backendIdentity).digest('hex').slice(0, 12);
+}
+
+function getRedisConfigKey(): string {
+    // ONE ENV VAR: CLIENT_ID. Collapsed 2026-08-26.
+    // There were three names for this value - CLIENT_ID, NEXT_PUBLIC_CLIENT_ID and
+    // NEXT_CLIENT_ID. The NEXT_PUBLIC_ prefix exists so Next inlines a value into the
+    // BROWSER bundle; nothing in the browser ever read it, so it bought nothing and
+    // merely looked justified. Verified before removal: all 7 consuming sites set
+    // CLIENT_ID in their env; none relied on the fallback.
+    //
+    // AND IT MUST THROW, NOT DEFAULT. This clientId is the REDIS CACHE KEY. The old
+    // `|| 'default'` meant an app that failed to set the id did not fail - it read and
+    // wrote config under `idp_config:default`, silently sharing one cache slot with
+    // every other misconfigured app, while Layer 3 THREW for that same missing value.
+    // Two behaviours for one missing variable, and the silent one owned the cache.
+    const clientId = process.env.CLIENT_ID;
+    if (!clientId) {
+        throw new Error(
+            '[IDP_CONFIG] FATAL: CLIENT_ID must be set - it is the config cache key, and defaulting it shares one cache entry across misconfigured apps'
+        );
+    }
+    return `${REDIS_CONFIG_KEY_PREFIX}${clientId}:${getConfigBackendTag()}`;
+}
+
+interface RedisCachedConfig {
+    config: IDPClientConfig;
+    expiresAt: number;
+}
+
+async function getConfigFromRedis(): Promise<IDPClientConfig | null> {
+    try {
+        const key = getRedisConfigKey();
+        const cached = await (await getRedis()).get(key);
+        if (!cached) return null;
+
+        const parsed: RedisCachedConfig = JSON.parse(cached);
+        if (Date.now() >= parsed.expiresAt) {
+            // Expired, delete it
+            await (await getRedis()).del(key);
+            return null;
+        }
+
+        return parsed.config;
+    } catch (error) {
+        console.warn('[IDP_CONFIG] Failed to read from Redis cache:', error);
+        return null;
+    }
+}
+
+async function setConfigInRedis(config: IDPClientConfig): Promise<void> {
+    try {
+        const key = getRedisConfigKey();
+        const ttlSeconds = config.configCacheTtlSeconds || 300;
+        const data: RedisCachedConfig = {
+            // 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
+        await (await getRedis()).set(key, JSON.stringify(data), 'EX', ttlSeconds + 10);
+    } catch (error) {
+        console.warn('[IDP_CONFIG] Failed to write to Redis cache:', error);
+    }
+}
+
+// ============================================================================
+// Circuit Breaker & Backoff State
+// ============================================================================
+
+let consecutiveFailures = 0;
+let lastFailureTime = 0;
+const MAX_FAILURES = 3;
+const CIRCUIT_OPEN_MS = 300000; // 5 minutes
+const MAX_BACKOFF_MS = 30000; // 30 seconds max backoff
+
+// ============================================================================
+// Main Functions
+// ============================================================================
+
+/**
+ * Get IDP client configuration with multi-tier caching.
+ *
+ * Caching layers (checked in order):
+ * 1. In-memory cache (fastest, lost on module reload in dev)
+ * 2. Redis cache (survives module reloads)
+ * 3. IDP fetch (when both caches miss)
+ *
+ * THROWS if IDP is unavailable or misconfigured. No fallbacks.
+ */
+export async function getIDPClientConfig(forceRefresh: boolean = false): Promise<IDPClientConfig> {
+    const now = Date.now();
+
+    // Layer 1: Return in-memory cached if still valid (skip if forceRefresh)
+    //
+    // The `cachedConfig.authSecret` term is DEFENCE IN DEPTH, not redundancy.
+    // Both writers are validated (the fetch path checks before caching; the
+    // Redis path requires a non-empty secret to count as a hit), so in principle
+    // an empty config can no longer be cached. This makes that property TRUE AT
+    // THE POINT OF USE instead of only provable by reading the whole file —
+    // DotNetPert 21184 and DotNetPert-Scout 21178 both argued for guarding the
+    // return, and they are right that it is the shape that cannot drift: a
+    // future third writer, or a cache restored from an older build's Redis
+    // entry, is caught here regardless of what the writers do.
+    // The cost is one boolean; the failure it prevents is every session signed
+    // with a secret published on npm.
+    if (!forceRefresh && cachedConfig && cachedConfig.authSecret && now < cacheExpiry) {
+        return cachedConfig;
+    }
+
+    // If a fetch is already in progress, wait for it instead of starting another
+    if (pendingFetch) {
+        return pendingFetch;
+    }
+
+    // Layer 2: Check Redis cache (skip if forceRefresh - startup should always get fresh data)
+    if (!forceRefresh) {
+        // 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
+        // `return`, and not merely around the assignment inside it.
+        // ── 249808 FOLLOW-THROUGH: THE CACHE MAY NEVER *ESTABLISH* THE SECRET. ──
+        //
+        // The rule stated just above - "a cached entry is only USABLE if it
+        // carries a secret" - was right and did not go far enough. The cache
+        // must also never be the FIRST source of the signing secret, because
+        // this blob is unauthenticated (bare JSON.parse, no MAC, and its own
+        // `expiresAt` sits inside the attacker-writable value).
+        //
+        // Guarding the ASSIGNMENT (the earlier 4.1.39 fix) protects a secret
+        // that already exists. It does nothing when none exists yet - and that
+        // window is real: the graft CATCHES the FATAL that startup-init throws
+        // when the IDP is unreachable at boot (graft instrumentation.ts:65-69,
+        // "BETTER_AUTH_SECRET may be unavailable until then"), so the app can
+        // serve requests with no secret established. The first request would
+        // then take the signing key from the cache - which is the whole
+        // forgery vector, arriving through the back door of a fix that had
+        // closed the front one.
+        //
+        // So: with no trusted secret in hand, THIS CACHE ENTRY IS A MISS. Fall
+        // through to Layer 3, the IDP fetch, which is authoritative and already
+        // guarded to throw on an empty secret. Escalation to truth, exactly as
+        // the empty-secret case above does.
+        //
+        // Accepts either name, matching startup-init.ts:147 which verifies
+        // `BETTER_AUTH_SECRET || NEXTAUTH_SECRET` during the rename transition.
+        //
+        // COST, bounded: only while no secret is established does this force an
+        // IDP round trip. startup-init calls getIDPClientConfig(TRUE) and so
+        // skips Layer 2 regardless, meaning normal boot is unaffected; once the
+        // secret exists the cache serves every non-forced caller as before. The
+        // only behaviour that changes is in the window where the alternative was
+        // trusting an unauthenticated store for a signing key.
+        const haveTrustedSecret = !!(process.env.BETTER_AUTH_SECRET || process.env.NEXTAUTH_SECRET);
+        if (redisConfig && redisConfig.authSecret && haveTrustedSecret) {
+            // Restore to in-memory cache
+            cachedConfig = redisConfig;
+            cacheExpiry = Date.now() + ((redisConfig.configCacheTtlSeconds || 300) * 1000);
+
+            // Set BETTER_AUTH_SECRET from cached config (also set legacy
+            // NEXTAUTH_SECRET during the rename transition).
+            //
+            // ⚠ THE EMPTY CASE IS NOT A NO-OP — IT WAS, AND THAT WAS THE HOLE.
+            // The three FETCH paths (:225 external, :353 internal, post-parse)
+            // throw on an empty authSecret, because an empty secret reaching
+            // betterAuth() is silently replaced by the PUBLIC DEFAULT_SECRET
+            // (create-context.mjs:79) rather than rejected. This path used to
+            // just skip the assignment and `return redisConfig` below — so a
+            // cached config with an empty secret bypassed ALL THREE guards, and
+            // it is checked FIRST, before any of them. Redis persistence made it
+            // durable across restarts. Found by QAPert (21175) after I claimed
+            // the guards covered every path; they covered every FETCH path.
+            //
+            // Resolution is deliberately NOT a throw: a corrupt cache entry
+            // should not take the app down when the authoritative source is one
+            // call away. Treat it as a MISS and fall through to the fetch paths,
+            // which are guarded and will throw if the IDP is genuinely empty.
+            // That is escalation to truth, not a fallback that weakens the check.
+            // ── 249808: AN EXPLICIT BETTER_AUTH_SECRET NOW WINS OVER THE CACHE. ──
+            //
+            // These two assignments were UNCONDITIONAL. That made the Redis
+            // cache authoritative for the SESSION SIGNING KEY, and the cache is
+            // not a trusted input: getConfigFromRedis() does a bare JSON.parse
+            // with no signature or MAC, and its only freshness check is an
+            // `expiresAt` field that lives INSIDE the same attacker-writable
+            // blob. So anyone who could write that key chose the signing secret,
+            // and knowing the secret means minting a validly-signed session for
+            // any user — including one who has never logged in. Forgery, not
+            // theft: it survives flushing the store and revoking refresh tokens,
+            // because it needs neither.
+            //
+            // THE FILE ALREADY KNEW THE RIGHT PATTERN. Five lines below, a mere
+            // URL defers to an explicitly-configured value, with a comment
+            // blessing deployment override. startup-init.ts:129 defers on THIS
+            // VERY SECRET (`config.authSecret && !process.env.BETTER_AUTH_SECRET`).
+            // The signing key was the one value in the package taking an
+            // untrusted cache's word unconditionally — protected less carefully
+            // than a base URL.
+            //
+            // Deferring restores that consistency and makes an explicitly-set
+            // BETTER_AUTH_SECRET a REAL secret: a value the deployment owns and
+            // the cache cannot override.
+            //
+            // BOUND, stated so nobody over-reads this: it closes the vector only
+            // where BETTER_AUTH_SECRET IS ACTUALLY SET. Where it is unset the
+            // cache still supplies it and the exposure stands — so this is
+            // necessary, cheap and strictly-better, NOT sufficient on its own.
+            // Locking the store and setting the secret explicitly in every
+            // deployment remain required.
+            publishAuthSecret(redisConfig.authSecret, 'Redis-cached IDP config');
+
+            // Set IDENTITY_CLIENT_BASE_EXTERNAL_URL from cached config.
+            // Only set if not already defined (allows deployment override for beta/staging).
+            if (redisConfig.baseClientUrl && !process.env.IDENTITY_CLIENT_BASE_EXTERNAL_URL) {
+                process.env.IDENTITY_CLIENT_BASE_EXTERNAL_URL = redisConfig.baseClientUrl;
+            }
+
+            return redisConfig;
+        }
+    }
+
+    // Layer 3: Fetch from IDP
+    const internalIdpUrl = process.env.INTERNAL_IDP_URL;
+    const idpUrl = process.env.IDP_URL;
+    // CLIENT_ID only - see the note at the cache-key site above.
+    const clientIdStr = process.env.CLIENT_ID;
+
+    if (!clientIdStr) {
+        throw new Error('[IDP_CONFIG] FATAL: CLIENT_ID must be set');
+    }
+    if (!internalIdpUrl && !idpUrl) {
+        throw new Error('[IDP_CONFIG] FATAL: INTERNAL_IDP_URL or IDP_URL must be set');
+    }
+
+    // Start fetch and store promise so concurrent callers wait for same result
+    const fetcher = internalIdpUrl
+        ? fetchConfigFromInternalIDP(internalIdpUrl, clientIdStr)
+        : fetchConfigFromIDP(idpUrl!, clientIdStr);
+    pendingFetch = fetcher
+        .then(async config => {
+            // ── VALIDATE BEFORE CACHING. ORDER IS THE WHOLE FIX. ────────────
+            // This block used to assign cachedConfig and await setConfigInRedis
+            // FIRST and throw afterwards — so a response with an empty secret
+            // poisoned BOTH caches on its way to failing. The throw only stopped
+            // THAT call: the next one hit the in-memory layer (`return
+            // cachedConfig`), which has no guard because it is a cache read, and
+            // handed the empty config to betterAuth() — where empty silently
+            // becomes the public DEFAULT_SECRET. Redis made it survive restarts.
+            //
+            // Guarding every cached RETURN would also work, and DotNetPert-Scout
+            // (21178) is right that it is the more robust shape in general. But
+            // there are four such returns and one writer, and the invariant we
+            // actually want is "an unvalidated config is never cached at all".
+            // Enforce it where it is cheapest to keep true.
+            if (!config.authSecret) {
+                // ⚠ LOAD-BEARING THROW — DO NOT SOFTEN TO A DEFAULT OR A WARNING.
+                // better-auth does NOT treat an empty secret as missing: at
+                // create-context.mjs:79 it substitutes DEFAULT_SECRET
+                // ("better-auth-secret-12345678901234567890"), which ships in the
+                // PUBLIC npm package, and its !secret guard can then never fire.
+                // The only remaining protection there is an isProduction gate — so
+                // outside production an empty secret means every session is signed
+                // with a string anyone can read off npm and forge.
+                // 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 and neither BETTER_AUTH_SECRET nor NEXTAUTH_SECRET is set');
+            }
+
+            // Validated above — only now is it safe to cache or publish.
+            publishAuthSecret(config.authSecret, 'freshly-fetched IDP config');
+
+            // Cache with TTL from response (default 5 minutes)
+            cachedConfig = config;
+            cacheExpiry = Date.now() + ((config.configCacheTtlSeconds || 300) * 1000);
+
+            // Store in Redis for persistence across module reloads. This is the
+            // write that made a bad config outlive the process, so it must stay
+            // BELOW the guard, never above it.
+            await setConfigInRedis(config);
+
+            // Set IDENTITY_CLIENT_BASE_EXTERNAL_URL from config.
+            // Only set if not already defined (allows deployment override for beta/staging).
+            if (config.baseClientUrl && !process.env.IDENTITY_CLIENT_BASE_EXTERNAL_URL) {
+                process.env.IDENTITY_CLIENT_BASE_EXTERNAL_URL = config.baseClientUrl;
+                console.log("[IDP_CONFIG] Set IDENTITY_CLIENT_BASE_EXTERNAL_URL:", config.baseClientUrl);
+            }
+
+            return config;
+        })
+        .finally(() => {
+            pendingFetch = null; // Clear so next cache miss can fetch again
+        });
+
+    return pendingFetch;
+}
+
+/**
+ * Clear the config cache (useful for testing or forced refresh)
+ */
+export function clearConfigCache(): void {
+    cachedConfig = null;
+    cacheExpiry = 0;
+}
+
+/**
+ * Clear the Redis config cache so the next fetch always goes to IDP.
+ */
+export async function clearConfigRedisCache(): Promise<void> {
+    try {
+        const key = getRedisConfigKey();
+        await (await getRedis()).del(key);
+        console.log('[IDP_CONFIG] Redis cache cleared:', key);
+    } catch (error) {
+        console.warn('[IDP_CONFIG] Failed to clear Redis cache:', error);
+    }
+}
+
+/**
+ * Get enabled OAuth providers from config
+ */
+export function getEnabledProviders(config: IDPClientConfig): OAuthProviderConfig[] {
+    return config.oauthProviders?.filter(p => p.enabled) || [];
+}
+
+// ============================================================================
+// Internal Functions
+// ============================================================================
+
+async function fetchConfigFromInternalIDP(internalIdpUrl: string, clientIdStr: string): Promise<IDPClientConfig> {
+    const containersKey = process.env.CONTAINERS_KEY;
+    if (!containersKey) {
+        throw new Error('[IDP_CONFIG] FATAL: CONTAINERS_KEY is required when using INTERNAL_IDP_URL');
+    }
+
+    const url = `${internalIdpUrl.replace(/\/$/, '')}/InternalClientConfig/${encodeURIComponent(clientIdStr)}`;
+    console.log(`[IDP_CONFIG] Fetching config from internal IDP: ${url}`);
+
+    const resp = await fetch(url, {
+        method: 'GET',
+        headers: {
+            'Accept': 'application/json',
+            'Authorization': `Secret ${containersKey}`,
+        },
+        cache: 'no-store'
+    } as RequestInit);
+
+    if (!resp.ok) {
+        const txt = await resp.text().catch(() => 'Unknown error');
+        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);
+    if (!body) {
+        throw new Error('[IDP_CONFIG] FATAL: Internal IDP returned empty or invalid JSON');
+    }
+
+    const configData = body?.data ?? body;
+
+    const rawClientId = configData.clientId ?? configData.client_id;
+    if (rawClientId === undefined || rawClientId === null) {
+        throw new Error(`[IDP_CONFIG] FATAL: Internal IDP response missing clientId. Got: ${JSON.stringify(Object.keys(configData))}`);
+    }
+
+    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
+        // nextAuthSecret/next_auth_secret while IDP rename rolls out.
+        authSecret:
+            configData.authSecret ??
+            configData.auth_secret ??
+            configData.nextAuthSecret ??
+            configData.next_auth_secret ??
+            '',
+        configCacheTtlSeconds: configData.configCacheTtlSeconds ?? configData.config_cache_ttl_seconds ?? 300,
+        oauthProviders: (configData.oauthProviders ?? configData.oauth_providers ?? []).map((p: any) => ({
+            provider: p.provider ?? '',
+            enabled: p.enabled ?? false,
+            clientId: p.clientId ?? p.client_id ?? '',
+            clientSecret: p.clientSecret ?? p.client_secret ?? '',
+            scopes: p.scopes,
+            additionalParams: p.additionalParams ?? p.additional_params
+        })),
+        authSettings: {
+            // 257255: terminal `?? true` / `?? ['email','sms']` REMOVED. They
+            // made a document with NO auth policy indistinguishable from one
+            // carrying exactly those values, one layer below the route that
+            // reports policy - so even a corrected settings.ts would have
+            // validated a fabrication. Undefined now means "not carried".
+            require2FA: configData.authSettings?.require2FA ?? configData.auth_settings?.require_2fa,
+            allowed2FAMethods: configData.authSettings?.allowed2FAMethods ?? configData.auth_settings?.allowed_2fa_methods,
+            mfaGracePeriodHours: configData.authSettings?.mfaGracePeriodHours ?? configData.auth_settings?.mfa_grace_period_hours ?? 24,
+            mfaRememberDeviceDays: configData.authSettings?.mfaRememberDeviceDays ?? configData.auth_settings?.mfa_remember_device_days ?? 30,
+            sessionTimeoutMinutes: configData.authSettings?.sessionTimeoutMinutes ?? configData.auth_settings?.session_timeout_minutes ?? 60,
+            idleTimeoutMinutes: configData.authSettings?.idleTimeoutMinutes ?? configData.auth_settings?.idle_timeout_minutes ?? 15,
+            allowRememberMe: configData.authSettings?.allowRememberMe ?? configData.auth_settings?.allow_remember_me ?? true,
+            rememberMeDays: configData.authSettings?.rememberMeDays ?? configData.auth_settings?.remember_me_days ?? 30,
+            lockoutThreshold: configData.authSettings?.lockoutThreshold ?? configData.auth_settings?.lockout_threshold ?? 5,
+            lockoutDurationMinutes: configData.authSettings?.lockoutDurationMinutes ?? configData.auth_settings?.lockout_duration_minutes ?? 15,
+
+            // 240447: read the tenant policy the IDP already sends. Applied to
+            // BOTH parse paths (fetchConfigFromInternalIDP and
+            // fetchConfigFromIDP) — fixing one would leave the other silently
+            // omitting these, which is the partial-fix trap.
+            //
+            // Same dual-casing idiom as every field above, but with NO
+            // `?? default` tail, deliberately. The others default because a
+            // wrong timeout is a nuisance; a wrong registration flag is a LIE
+            // about what the tenant permits, and the hardcoded `true` in
+            // routes/auth/settings was exactly that lie. `undefined` has to
+            // survive to the consumer so it can decide, instead of being
+            // handed a guess wearing the costume of a measurement.
+            allowPublicRegistration:
+                configData.authSettings?.allowPublicRegistration ??
+                configData.auth_settings?.allow_public_registration,
+            allowSocialLogin:
+                configData.authSettings?.allowSocialLogin ??
+                configData.auth_settings?.allow_social_login,
+            enablePasswordReset:
+                configData.authSettings?.enablePasswordReset ??
+                configData.auth_settings?.enable_password_reset
+        },
+        branding: {
+            theme: configData.branding?.theme,
+            primaryColor: configData.branding?.primaryColor ?? configData.branding?.primary_color,
+            secondaryColor: configData.branding?.secondaryColor ?? configData.branding?.secondary_color,
+            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 and neither BETTER_AUTH_SECRET nor NEXTAUTH_SECRET is set');
+    }
+
+    console.log(`[IDP_CONFIG] Internal IDP config loaded for ${clientIdStr}`);
+    consecutiveFailures = 0;
+    return config;
+}
+
+async function fetchConfigFromIDP(idpUrl: string, clientIdStr: string): Promise<IDPClientConfig> {
+    // =========================================================================
+    // Circuit Breaker Check
+    // =========================================================================
+    if (consecutiveFailures >= MAX_FAILURES) {
+        const timeSinceFailure = Date.now() - lastFailureTime;
+        if (timeSinceFailure < CIRCUIT_OPEN_MS) {
+            // Circuit is open - return stale cache if available
+            // Stale cache is acceptable here; a stale config with NO SECRET is
+            // not. These two paths fire exactly when the IDP is unreachable —
+            // the worst moment to hand betterAuth() an empty secret, which it
+            // silently upgrades to the public DEFAULT_SECRET. Falling through to
+            // a hard failure is correct: unavailable beats forgeable.
+            if (cachedConfig && cachedConfig.authSecret) {
+                return cachedConfig;
+            }
+            throw new Error(`[IDP_CONFIG] Circuit breaker OPEN - no cached config available. Retry in ${Math.round((CIRCUIT_OPEN_MS - timeSinceFailure) / 1000)}s`);
+        }
+        // Half-open state: allow one request to test
+        consecutiveFailures = MAX_FAILURES - 1;
+    }
+
+    // =========================================================================
+    // Exponential Backoff Check
+    // =========================================================================
+    if (consecutiveFailures > 0) {
+        const backoffMs = Math.min(1000 * Math.pow(2, consecutiveFailures), MAX_BACKOFF_MS);
+        const timeSinceFailure = Date.now() - lastFailureTime;
+        if (timeSinceFailure < backoffMs) {
+            const remainingMs = backoffMs - timeSinceFailure;
+            // Return stale cache during backoff if available
+            // Stale cache is acceptable here; a stale config with NO SECRET is
+            // not. These two paths fire exactly when the IDP is unreachable —
+            // the worst moment to hand betterAuth() an empty secret, which it
+            // silently upgrades to the public DEFAULT_SECRET. Falling through to
+            // a hard failure is correct: unavailable beats forgeable.
+            if (cachedConfig && cachedConfig.authSecret) {
+                return cachedConfig;
+            }
+            throw new Error(`[IDP_CONFIG] In backoff period - retry in ${Math.round(remainingMs)}ms`);
+        }
+    }
+
+    try {
+    // Step 1: Get signed client assertion from IDP
+    const signingUrl = `${idpUrl.replace(/\/$/, '')}/api/ExternalAuth/sign-client-assertion`;
+
+    const signingPayload = {
+        issuer: clientIdStr,
+        subject: clientIdStr,
+        audience: 'urn:payez:externalauth:clientconfig',
+        expires_in: 60,
+    };
+
+    const signingResp = await fetch(signingUrl, {
+        method: 'POST',
+        headers: {
+            'Accept': 'application/json',
+            'Content-Type': 'application/json',
+            'X-Client-Id': clientIdStr,
+            'X-Correlation-Id': randomUUID().replace(/-/g, ''),
+        },
+        body: JSON.stringify(signingPayload),
+        cache: 'no-store'
+    } as RequestInit);
+
+    if (!signingResp.ok) {
+        const txt = await signingResp.text().catch(() => 'Unknown error');
+        // 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);
+
+    if (!signingBody) {
+        throw new Error('[IDP_CONFIG] FATAL: IDP returned empty or invalid JSON for sign-client-assertion');
+    }
+
+    // Per PayEz API standard: response is { success, data: { client_assertion }, ... }
+    // But IDP might use camelCase (clientAssertion) - check both
+    const client_assertion = (
+        signingBody?.data?.client_assertion ??
+        signingBody?.data?.clientAssertion
+    ) as string | undefined;
+
+    if (!client_assertion) {
+        // 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 || {}))}`);
+    }
+
+    // Step 2: Fetch client config using the assertion
+    const configUrl = `${idpUrl.replace(/\/$/, '')}/api/ExternalAuth/client-config`;
+
+    const configResp = await fetch(configUrl, {
+        method: 'POST',
+        headers: {
+            'Accept': 'application/json',
+            'Content-Type': 'application/json',
+            'X-Client-Id': clientIdStr,
+            'X-Correlation-Id': randomUUID().replace(/-/g, ''),
+        },
+        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} (body ${txt.length} chars)`);
+    }
+
+    const configBody: any = await configResp.json().catch(() => null);
+
+    if (!configBody) {
+        throw new Error('[IDP_CONFIG] FATAL: IDP returned empty or invalid JSON for client-config');
+    }
+
+    // Per PayEz API standard: response is wrapped in { success, data: {...} }
+    const configData = configBody?.data;
+
+    if (!configData || typeof configData !== 'object') {
+        // 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');
+    }
+
+    // Validate required fields - handle both number and string client_id
+    const rawClientId = configData.clientId ?? configData.client_id;
+    if (rawClientId === undefined || rawClientId === null) {
+        throw new Error(`[IDP_CONFIG] FATAL: IDP response missing clientId/client_id. Got: ${JSON.stringify(Object.keys(configData))}`);
+    }
+
+    // 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 = applyEnvSecrets({
+        clientId: String(rawClientId),
+        clientSlug: configData.clientSlug ?? configData.client_slug ?? configData.slug ?? '',
+        authSecret:
+            configData.authSecret ??
+            configData.auth_secret ??
+            configData.nextAuthSecret ??
+            configData.next_auth_secret ??
+            '',
+        configCacheTtlSeconds: configData.configCacheTtlSeconds ?? configData.config_cache_ttl_seconds ?? 300,
+        oauthProviders: (configData.oauthProviders ?? configData.oauth_providers ?? []).map((p: any) => ({
+            provider: p.provider ?? '',
+            enabled: p.enabled ?? false,
+            clientId: p.clientId ?? p.client_id ?? '',
+            clientSecret: p.clientSecret ?? p.client_secret ?? '',
+            scopes: p.scopes,
+            additionalParams: p.additionalParams ?? p.additional_params
+        })),
+        authSettings: {
+            require2FA: (() => {
+                // Check nested locations first (canonical)
+                const nested = configData.authSettings?.require2FA ?? configData.auth_settings?.require_2fa;
+                if (nested !== undefined) return nested;
+                // TRANSITION FALLBACK: Check top-level (deprecated)
+                const topLevel = configData.require2FA ?? configData.require_2fa;
+                if (topLevel !== undefined) {
+                    console.warn('[IDP_CONFIG] DEPRECATION: require2FA found at top-level. Should be nested under auth_settings. Update IDP.');
+                    return topLevel;
+                }
+                // 257255: was `return true`. A default here is a FABRICATED
+                // POLICY - QAPert measured the same client as require_2fa TRUE
+                // on AKS and FALSE on dev-93, so any constant is wrong in one
+                // environment by construction. Undefined = "not carried".
+                return undefined;
+            })(),
+            allowed2FAMethods: configData.authSettings?.allowed2FAMethods ?? configData.auth_settings?.allowed_2fa_methods,
+            mfaGracePeriodHours: configData.authSettings?.mfaGracePeriodHours ?? configData.auth_settings?.mfa_grace_period_hours ?? 24,
+            mfaRememberDeviceDays: configData.authSettings?.mfaRememberDeviceDays ?? configData.auth_settings?.mfa_remember_device_days ?? 30,
+            sessionTimeoutMinutes: configData.authSettings?.sessionTimeoutMinutes ?? configData.auth_settings?.session_timeout_minutes ?? 60,
+            idleTimeoutMinutes: configData.authSettings?.idleTimeoutMinutes ?? configData.auth_settings?.idle_timeout_minutes ?? 15,
+            allowRememberMe: configData.authSettings?.allowRememberMe ?? configData.auth_settings?.allow_remember_me ?? true,
+            rememberMeDays: configData.authSettings?.rememberMeDays ?? configData.auth_settings?.remember_me_days ?? 30,
+            lockoutThreshold: configData.authSettings?.lockoutThreshold ?? configData.auth_settings?.lockout_threshold ?? 5,
+            lockoutDurationMinutes: configData.authSettings?.lockoutDurationMinutes ?? configData.auth_settings?.lockout_duration_minutes ?? 15,
+
+            // 240447: read the tenant policy the IDP already sends. Applied to
+            // BOTH parse paths (fetchConfigFromInternalIDP and
+            // fetchConfigFromIDP) — fixing one would leave the other silently
+            // omitting these, which is the partial-fix trap.
+            //
+            // Same dual-casing idiom as every field above, but with NO
+            // `?? default` tail, deliberately. The others default because a
+            // wrong timeout is a nuisance; a wrong registration flag is a LIE
+            // about what the tenant permits, and the hardcoded `true` in
+            // routes/auth/settings was exactly that lie. `undefined` has to
+            // survive to the consumer so it can decide, instead of being
+            // handed a guess wearing the costume of a measurement.
+            allowPublicRegistration:
+                configData.authSettings?.allowPublicRegistration ??
+                configData.auth_settings?.allow_public_registration,
+            allowSocialLogin:
+                configData.authSettings?.allowSocialLogin ??
+                configData.auth_settings?.allow_social_login,
+            enablePasswordReset:
+                configData.authSettings?.enablePasswordReset ??
+                configData.auth_settings?.enable_password_reset
+        },
+        branding: {
+            theme: configData.branding?.theme,
+            primaryColor: configData.branding?.primaryColor ?? configData.branding?.primary_color,
+            secondaryColor: configData.branding?.secondaryColor ?? configData.branding?.secondary_color,
+            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')));
+
+    // Validate we got what we need
+    if (!config.clientId) {
+        throw new Error('[IDP_CONFIG] FATAL: clientId is empty or missing after parsing');
+    }
+    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 and neither BETTER_AUTH_SECRET nor NEXTAUTH_SECRET is set');
+    }
+
+    // Success - reset failure tracking
+    consecutiveFailures = 0;
+    return config;
+
+    } catch (error) {
+        // Track failure for circuit breaker
+        consecutiveFailures++;
+        lastFailureTime = Date.now();
+        console.error('[IDP_CONFIG] Fetch failed', {
+            consecutiveFailures,
+            maxFailures: MAX_FAILURES,
+            error: error instanceof Error ? error.message : String(error)
+        });
+        throw error;
+    }
+}