@payez/next-mvp 4.1.20 → 4.4.0

package/src/auth/better-auth.ts

@@ -11,17 +11,29 @@
 
 import 'server-only';
 import { AsyncLocalStorage } from 'node:async_hooks';
+import { createHash } from 'crypto';
 import { decodeJwt } from 'jose';   // better-auth's own JWT dependency
 import { betterAuth } from 'better-auth';
 import { nextCookies } from 'better-auth/next-js';
 import { toNextJsHandler } from 'better-auth/next-js';
 import { magicLink, type MagicLinkOptions } from 'better-auth/plugins/magic-link';
+import { resolveClientKey } from '../lib/client-key';
+import { genericOAuth } from 'better-auth/plugins/generic-oauth';
 import type { IDPClientConfig } from '../lib/idp-client-config';
 import { getIDPClientConfig } from '../lib/idp-client-config';
 import { getAppSlug } from '../lib/app-slug';
 import { getRedis } from '../lib/redis';
 import { SESSION_TTL } from '../lib/session-store';
 
+/**
+ * 185121: short sha256 fingerprint for secrets/tokens in log lines — enough
+ * to tell "same" from "divergent", never enough to reconstruct. 12 hex chars
+ * = 48 bits; collision-tellable across a deployment, useless as a credential.
+ */
+export function secretFingerprint(value: string): string {
+  return createHash('sha256').update(value).digest('hex').slice(0, 12);
+}
+
 /**
  * Better Auth social provider config shape.
  */
@@ -32,6 +44,13 @@ export interface BetterAuthSocialProvider {
   prompt?: string;
   accessType?: 'offline' | 'online';
   hd?: string;
+  /**
+   * 260419: better-auth's ONLY guard against OAuth auto-provisioning
+   * (oauth2/link-account.mjs handleOAuthUserInfo: `if (disableSignUp) return
+   * {error:"signup disabled"}`). Unset means ANY unknown Google identity gets a
+   * local account created at callback. We wire it from the tenant's own policy.
+   */
+  disableSignUp?: boolean;
 }
 
 /**
@@ -60,7 +79,118 @@ export interface BetterAuthSocialProvider {
  * function. Outside that scope the store is undefined and the body simply omits
  * id_token, which is the correct additive behaviour.
  */
-const idTokenScope = new AsyncLocalStorage<{ idToken?: string }>();
+/**
+ * ON globalThis FOR THE SAME REASON THE BETTER AUTH INSTANCE IS (181814, see STATE_KEY
+ * below) — and it was NOT, which is the whole defect.
+ *
+ * This module is loaded more than once per process: instrumentation and the auth route
+ * are different chunks with their own module registries. `state` was moved to globalThis
+ * so both copies share the Better Auth INSTANCE. This AsyncLocalStorage was left in
+ * module scope, so each copy got its own.
+ *
+ * The result, measured on UMI 2026-08-26 against idp.payez.net:
+ *
+ *   copy A builds the instance   -> the getUserInfo closure captures A's idTokenScope
+ *   copy B serves the callback   -> createAuthGetHandler runs .run({}) on B's
+ *   getUserInfo fires, reads A   -> getStore() is undefined, `if (scope)` skips
+ *   the exchange reads B         -> empty, so id_token is omitted from the body
+ *
+ * Sign-in SUCCEEDS at every visible step. The user gets a session, an avatar, an email.
+ * The IDP then answers 401 UNVERIFIED_ASSERTION with reason="id_token missing"
+ * (confirmed in its own logs, correlationId 0HNO2755RESR1) — so the client half of 138635
+ * has been shipping as a no-op wherever the module double-loads, and the security fix it
+ * exists to deliver never arrived. A shared instance plus a per-copy scope is the worst
+ * combination: everything looks wired, and the one field that proves identity is dropped.
+ *
+ * globalThis is per-process and per-runtime, which is exactly the lifetime a request-scoped
+ * carrier needs to be reachable from every copy that might run inside the request.
+ */
+const ID_TOKEN_SCOPE_KEY = '__payezIdTokenScope';
+const gScope = globalThis as unknown as Record<
+  string,
+  AsyncLocalStorage<{ idToken?: string }> | undefined
+>;
+gScope[ID_TOKEN_SCOPE_KEY] ??= new AsyncLocalStorage<{ idToken?: string }>();
+const idTokenScope = gScope[ID_TOKEN_SCOPE_KEY]!;
+
+/**
+ * EXCHANGE-MOVE (175047): route OAuth through OUR IDP instead of holding
+ * provider credentials in the app.
+ *
+ * ARCHITECTURE LOCKED (BAPert 21318): genericOAuth pointed at the IDP - NOT at
+ * Google - which is simultaneously pkce + no-secret AND route-through-IDP, and
+ * is uniform with the ratified desktop leg. The IDP holds the provider secret
+ * and performs the provider exchange server-side.
+ *
+ * ── CUSTOM SHAPE, NEVER A PROVIDER PRESET ───────────────────────────────────
+ * QAPert-NightHawk 21304: better-auth's provider-PRESET shape makes
+ * clientSecret REQUIRED again. Same plugin, two config shapes, opposite answers
+ * on whether we need a secret. This builds the generic/custom shape
+ * deliberately; reaching for a preset because it looks tidier would silently
+ * kill keyless-on-web and nobody would connect the two changes.
+ *
+ * ── OPT-IN, AND NOT A FALLBACK ──────────────────────────────────────────────
+ * Returns null unless the IDP's OAuth endpoints are explicitly configured. That
+ * makes this ADDITIVE: the existing socialProviders path keeps working until an
+ * operator turns this on. It is NOT a runtime failover - nothing silently
+ * chooses between them, because a silent chooser is how a migration ends up
+ * half-applied and undetectable.
+ *
+ * ⚠ WHAT MUST MOVE TO THE IDP WITH THIS (flagged in 21317, not solvable here):
+ * the app stops talking to Google, so it can no longer capture the raw
+ * id_token that oauth-callback verifies today, and the per-provider settings
+ * below stop being ours to set - profile scope, prompt=select_account,
+ * accessType, and hd (hosted-domain, a SECURITY control). The IDP's own
+ * exchange must verify signature/iss/aud/exp itself and preserve those four, or
+ * they are lost silently.
+ */
+export function buildIdpOAuthProviderConfig(): {
+  providerId: string;
+  discoveryUrl: string;
+  clientId: string;
+  pkce: true;
+  scopes: string[];
+} | null {
+  const discoveryUrl = process.env.IDP_OAUTH_DISCOVERY_URL;
+  const clientId = process.env.CLIENT_ID;
+  if (!discoveryUrl || !clientId) return null;
+
+  return {
+    providerId: 'payez-idp',
+    discoveryUrl,
+    clientId,
+    // NO clientSecret. The whole point: this app is not a credential holder.
+    pkce: true,
+    scopes: ['openid', 'email', 'profile'],
+
+    /**
+     * ⚠ DO NOT ADD `authentication: 'basic'` HERE. IT SILENTLY BREAKS KEYLESS.
+     *
+     * Found by QAPert-NightHawk (21348) — the second config trap in this plugin
+     * after the preset one, and the same shape: a field that looks like a
+     * harmless transport detail and quietly changes whether we are a public
+     * client at all.
+     *
+     * @better-auth/core validate-authorization-code.mjs:
+     *     if (authentication === "basic") {
+     *       headers.authorization = `Basic ${base64(`${clientId}:${clientSecret ?? ""}`)}`;
+     *     } else {
+     *       body.set("client_id", clientId);
+     *       if (options.clientSecret) body.set("client_secret", options.clientSecret);
+     *     }
+     *
+     * Note what the 'basic' branch does with NO secret: it sends an EMPTY
+     * password, `Basic base64("<clientId>:")`. That is not "no authentication",
+     * it is WRONG authentication — we would be presenting ourselves as a
+     * confidential client with a blank credential. The default branch is the
+     * one that produces a genuine public-client PKCE request.
+     *
+     * Leaving this field UNSET is load-bearing, which is exactly why it needs a
+     * comment: nothing about an absent field advertises that its absence is a
+     * decision.
+     */
+  };
+}
 
 export function buildBetterAuthProviders(
   config: IDPClientConfig
@@ -81,10 +211,40 @@ export function buildBetterAuthProviders(
       scopes.push('profile');
     }
 
+    /**
+     * 224721: better-auth's google provider UNCONDITIONALLY seeds its default
+     * scopes ['email','profile','openid'] and then pushes our `scope` verbatim
+     * (@better-auth/core social-providers/google.mjs createAuthorizationURL) —
+     * the row's "openid email profile" reached Google as
+     * "email profile openid openid email profile". Semantically harmless
+     * (Google dedupes) but sloppy on a URL a demo audience can read. Hand over
+     * only what the defaults do not already cover; undefined when nothing
+     * remains, so the provider emits exactly its default set.
+     */
+    const GOOGLE_DEFAULT_SCOPES = ['email', 'profile', 'openid'];
+    const wireScopes =
+      name === 'google'
+        ? scopes.filter((s) => !GOOGLE_DEFAULT_SCOPES.includes(s))
+        : scopes;
+
     providers[name] = {
       clientId: oauth.clientId,
       clientSecret: oauth.clientSecret,
-      scope: scopes.length > 0 ? scopes : undefined,
+      scope: wireScopes.length > 0 ? wireScopes : undefined,
+      /**
+       * 260419 — CLOSE THE SECOND SELF-SERVE PROVISIONING DOOR. 259805 gated
+       * the signup BFF on allow_public_registration, but the social lane never
+       * touches that code: better-auth creates the user through its own
+       * internalAdapter at the OAuth callback, and its ONLY guard is this flag.
+       *
+       * Wired from the tenant's own policy, explicit-true-opens: the IDP config
+       * keeps allowPublicRegistration UNDEFINED when the tenant never answered
+       * (idp-client-config.ts, the no-fabricated-default rule), and an
+       * unanswered policy question must not provision accounts. That matches
+       * the FE's silent-default-is-decline posture for the "Create account"
+       * affordance. A tenant that wants Google self-serve says so.
+       */
+      disableSignUp: config.authSettings?.allowPublicRegistration !== true,
       // Google is overly eager to reuse the last account unless we
       // explicitly ask for account selection on each social login.
       prompt: typeof rawPrompt === 'string'
@@ -137,7 +297,22 @@ export function buildBetterAuthProviders(
 
         // The only new behaviour: hand the raw token to this request's scope.
         const scope = idTokenScope.getStore();
-        if (scope) scope.idToken = token.idToken;
+        if (scope) {
+          scope.idToken = token.idToken;
+        } else {
+          // NOT a silent skip. A missing scope here means 138635 degrades to a no-op:
+          // the login still succeeds, and the IDP rejects the exchange with
+          // reason="id_token missing" a second later, with nothing connecting the two.
+          // That cost a day on UMI. If this fires, the OAuth callback is running outside
+          // createAuthGetHandler — either the route mounts the bare
+          // `routes/auth/nextauth` re-export instead of createAuthGetHandler, or this
+          // module has double-loaded and the scope is not shared (see 181814 above).
+          console.warn(
+            '[BETTER_AUTH] id_token captured but NO REQUEST SCOPE to put it in — it will ' +
+              'NOT be forwarded and the IDP exchange will fail UNVERIFIED_ASSERTION. ' +
+              'Check that GET is createAuthGetHandler(), not routes/auth/nextauth.',
+          );
+        }
 
         // Mirrors the upstream default (google.mjs) verbatim, minus the hd
         // branch that cannot fire here — so overriding the hook changes WHAT WE
@@ -206,6 +381,17 @@ export function createBetterAuthInstance(
 ) {
   const appSlug = idpConfig.clientSlug || getAppSlug();
 
+  // 185121 line 1: name the secret this instance PINNED, as a hash, never the
+  // secret. 183047's surviving fork is HMAC-fail vs record-miss; an HMAC-fail
+  // caused by a divergent secret is only diagnosable if every instance
+  // creation logged WHICH secret it bound. Both init paths (this module's
+  // getBetterAuthInstance and server/auth.ts getAuthInstance) funnel through
+  // here, so this one line covers both; getAuthInstance adds its own line
+  // naming the path, because it previously created an instance INVISIBLY.
+  console.log(
+    `[BETTER_AUTH] createBetterAuthInstance: slug=${appSlug} authSecret ${idpConfig.authSecret ? `sha256:${secretFingerprint(idpConfig.authSecret as string)}` : 'ABSENT'}`
+  );
+
   // Resolve base URL: BETTER_AUTH_URL env > IDP config > localhost fallback
   // Must include /api/auth since that's where the catch-all route is mounted
   const rawBaseURL = process.env.BETTER_AUTH_URL
@@ -213,6 +399,8 @@ export function createBetterAuthInstance(
     || `http://localhost:${process.env.PORT || '3000'}`;
   const baseURL = rawBaseURL.replace(/\/+$/, '') + '/api/auth';
 
+  const idpOAuth = buildIdpOAuthProviderConfig();
+
   return betterAuth({
     baseURL,
     secret: idpConfig.authSecret as string,
@@ -224,32 +412,137 @@ export function createBetterAuthInstance(
       rawBaseURL,
       baseURL,
       ...(idpConfig.baseClientUrl ? [idpConfig.baseClientUrl] : []),
-      'http://localhost:3000',
-      'http://localhost:3400',
-      'http://localhost:3600',
+      // MEASURED 2026-08-26: this list ended with the literals localhost:3000, :3400
+      // and :3600. payez_idp_admin_web runs on :3200 - correctly configured, with
+      // BETTER_AUTH_URL=http://localhost:3200 - and every GET /api/auth/get-session
+      // returned 400, because the port it actually runs on was not one of the three
+      // someone had typed in. A config-shaped constant is not configuration.
+      //
+      // The app's own origin is already covered by rawBaseURL/baseURL above; the dev
+      // origin is DERIVED from PORT, and anything genuinely external comes from
+      // BETTER_AUTH_TRUSTED_ORIGINS (comma-separated).
+      `http://localhost:${process.env.PORT || '3000'}`,
+      ...(process.env.BETTER_AUTH_TRUSTED_ORIGINS
+        ? process.env.BETTER_AUTH_TRUSTED_ORIGINS.split(',').map((o) => o.trim()).filter(Boolean)
+        : []),
     ],
 
     // Redis-backed session storage via secondaryStorage
     secondaryStorage: {
+      /**
+       * 170033 (QAPert 22654, load-bearing precondition for 183483): DO NOT
+       * swallow a Redis failure into `null` here.
+       *
+       * `null` from `get` is Better Auth's OWN signal for "no session at this
+       * key" (see node_modules/better-auth db/internal-adapter.mjs
+       * `findSession`: `if (!sessionStringified ...) return null`). Catching
+       * a Redis error and returning `null` therefore told better-auth "this
+       * session does not exist" when the true state was "the store could not
+       * be asked" — indistinguishable from a genuine sign-out. With
+       * `cookieCache` disabled (session.cookieCache.enabled above), EVERY
+       * `getSession()` call hits this path for real, so a Redis blip
+       * manufactured a `200 { session: null }` for every live session at
+       * once — the exact channel 183483's client-side guard (verify-code
+       * page's session-liveness check) was built to survive, and the one it
+       * could not survive while this swallow stood: a fabricated "no
+       * session" 200 is not distinguishable from a real one by any client.
+       *
+       * Letting the error propagate is safe: better-auth's own router
+       * (better-call/dist/router.mjs) wraps every endpoint handler in a
+       * top-level try/catch and converts an uncaught throw to a genuine
+       * `500`, not a crash. A `500` IS the "inconclusive" signal 183483's
+       * corrected client guard already knows how to hold a session through —
+       * so a Redis outage now surfaces as "couldn't check" instead of
+       * silently lying "confirmed logged out".
+       */
       get: async (key: string) => {
-        try {
-          return await getRedis().get(`ba:${appSlug}:${key}`);
-        } catch { return null; }
+        const value = await getRedis().get(`ba:${appSlug}:${key}`);
+        // 185121 line 2: the 183047 discriminator. A null here means
+        // RECORD-MISS — the store was reachable and the key is absent. If the
+        // record IS present but BA still rejects the session, this line does
+        // NOT fire and the failure is upstream of storage (HMAC/secret gate).
+        // BA-primary logs nothing on failure, so without this line the two
+        // surviving forks are indistinguishable in the artifact. Key is
+        // fingerprinted: it embeds the session token.
+        if (value === null) {
+          console.warn(
+            `[BETTER_AUTH] secondaryStorage.get MISS ba:${appSlug}:sha256:${secretFingerprint(key)} — record absent, store reachable`
+          );
+        }
+        return value;
       },
+      /**
+       * 170033 fix 1 — DO NOT SWALLOW A FAILED WRITE. A SESSION THAT WAS NOT
+       * PERSISTED IS NOT A SESSION.
+       *
+       * This previously caught every Redis error and returned normally, so
+       * better-auth was told the session had been stored when nothing had been
+       * written. The user got a successful login, a session cookie, and a
+       * rendered signed-in shell on top of a store that holds no session — and
+       * the very next `getSession()` reads `null` and signs them straight back
+       * out. Nothing logged, nothing thrown, no banner: a login that "worked"
+       * and a sign-out nobody can explain.
+       *
+       * Letting it propagate is the same contract `get` above already relies on:
+       * better-auth's router (better-call/dist/router.mjs) wraps every endpoint
+       * handler and converts an uncaught throw into a genuine 500. A 500 on the
+       * login write is honest — "we could not store your session" — and it is
+       * distinguishable by any client from a successful login, which a swallowed
+       * failure is not.
+       *
+       * THE COMMENT THIS REPLACES SAID "Redis unavailable — cookie cache still
+       * works". It does not: `session.cookieCache.enabled` is FALSE (see below).
+       * The comment described a safety net that had been removed, which is why
+       * this swallow looked survivable to every reader who trusted it (170033
+       * fix 3).
+       */
       set: async (key: string, value: string, ttl?: number) => {
-        try {
-          const redis = getRedis();
-          if (ttl) {
-            await redis.setex(`ba:${appSlug}:${key}`, ttl, value);
-          } else {
-            await redis.setex(`ba:${appSlug}:${key}`, SESSION_TTL, value);
-          }
-        } catch { /* Redis unavailable — cookie cache still works */ }
+        const redis = getRedis();
+        await redis.setex(`ba:${appSlug}:${key}`, ttl ?? SESSION_TTL, value);
       },
       delete: async (key: string) => {
         try {
           await getRedis().del(`ba:${appSlug}:${key}`);
-        } catch { /* ignore */ }
+        } catch (err) {
+          /**
+           * 170033 fix 2 — a failed delete must be VISIBLE, not `/* ignore *\/`.
+           *
+           * Deliberately logged rather than thrown, and the distinction is not
+           * timidity: the CANONICAL store is what decides session liveness (see
+           * 181922 below), and its delete runs immediately after this one and is
+           * NOT swallowed. So a BA record that outlives its canonical twin does
+           * not authenticate anyone — throwing here would fail a sign-out that
+           * actually succeeded where it counts.
+           *
+           * What was unacceptable is that it happened SILENTLY. A revocation
+           * that half-failed left no trace anywhere, so the leftover key could
+           * only ever be found by someone already reading the keyspace for
+           * another reason. `error`, not `warn`: this is a revocation that did
+           * not complete, not a retryable blip.
+           */
+          console.error(
+            `[BETTER_AUTH] secondary delete FAILED for ba:${appSlug}:${key} — ` +
+            `the better-auth session record may still exist. Canonical delete ` +
+            `below is what governs liveness; if it also failed, the session is ` +
+            `NOT revoked:`,
+            err
+          );
+        }
+        /**
+         * 181922 — teardown is BOTH stores. BA's sign-out deletes only its
+         * secondary record; the canonical {slug}:sess:{token} would survive
+         * and keep the session alive (a replayed cookie still authenticates).
+         * `key` here IS the session token (the ba: prefix is applied above),
+         * so the canonical delete is one call. This also fires on session
+         * rotation/expiry deletions, which is correct: a session BA drops
+         * must not live on in the canonical store.
+         */
+        try {
+          const { deleteSession } = await import('../lib/session-store');
+          await deleteSession(key);
+        } catch (err) {
+          console.warn('[BETTER_AUTH] secondary delete: canonical store cleanup failed:', err);
+        }
       },
     },
 
@@ -290,6 +583,9 @@ export function createBetterAuthInstance(
 
     plugins: [
       nextCookies(),
+      // Exchange-move: present ONLY when the IDP's OAuth endpoints are
+      // configured. Absent otherwise, so this cannot alter existing behaviour.
+      ...(idpOAuth ? [genericOAuth({ config: [idpOAuth] })] : []),
       ...(opts.magicLink ? [magicLink(opts.magicLink)] : []),
       // App-supplied plugins last: they may depend on the built-ins above, and
       // ordering is BA's own concern once they are in the array.
@@ -308,16 +604,36 @@ export function isBetterAuthEnabled(): boolean {
 /**
  * Get Better Auth Next.js route handlers (GET, POST).
  * Initializes Better Auth from IDP config on first call, caches the instance.
+ *
+ * STATE LIVES ON globalThis, NOT IN MODULE SCOPE (181814, measured 2026-08-07):
+ * under Turbopack, instrumentation.ts and the /api/auth/[...all] route are
+ * different chunks and each loads its OWN copy of this module. Module-level
+ * `configuredOpts` set by configureBetterAuth() in instrumentation never
+ * reached the copy getBetterAuthInstance() read in the route — measured
+ * identity probe: sameInstance=false, route-side plugins=["next-cookies"]
+ * while the instrumentation-side instance carried every configured plugin.
+ * No throw anywhere (the double-init guard never sees the other copy), core
+ * auth green, plugin routes 404. globalThis is per-process, per-runtime —
+ * exactly the scope this state must have.
  */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-let cachedInstance: any = null;
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-let initPromise: Promise<any> | null = null;
-let configuredOpts: CreateBetterAuthInstanceOptions = {};
+interface BetterAuthModuleState {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  cachedInstance: any;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  initPromise: Promise<any> | null;
+  configuredOpts: CreateBetterAuthInstanceOptions;
+}
 
-// Expose for server-side session access (decode-session.ts)
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export { cachedInstance as __betterAuthInstance };
+const STATE_KEY = '__payezBetterAuthState';
+const g = globalThis as unknown as Record<string, BetterAuthModuleState | undefined>;
+g[STATE_KEY] ??= { cachedInstance: null, initPromise: null, configuredOpts: {} };
+const state = g[STATE_KEY];
+
+// Expose for server-side session access (decode-session.ts). A getter so the
+// export tracks the SHARED state, not a chunk-local snapshot.
+export function __getBetterAuthInstance(): unknown {
+  return state.cachedInstance;
+}
 
 /**
  * Configure Better Auth instance options for this process.
@@ -331,28 +647,28 @@ export { cachedInstance as __betterAuthInstance };
  * cannot be applied retroactively.
  */
 export function configureBetterAuth(opts: CreateBetterAuthInstanceOptions): void {
-  if (cachedInstance) {
+  if (state.cachedInstance) {
     throw new Error(
       '[BETTER_AUTH] configureBetterAuth() must run before the instance is first resolved. ' +
       'Call it in Next.js instrumentation.ts or an equivalent startup hook.'
     );
   }
-  configuredOpts = opts;
+  state.configuredOpts = opts;
 }
 
 export async function getBetterAuthInstance() {
-  if (cachedInstance) return cachedInstance;
+  if (state.cachedInstance) return state.cachedInstance;
 
-  if (!initPromise) {
-    initPromise = getIDPClientConfig(true).then(config => {
-      const instance = createBetterAuthInstance(config, configuredOpts);
-      cachedInstance = instance;
+  if (!state.initPromise) {
+    state.initPromise = getIDPClientConfig(true).then(config => {
+      const instance = createBetterAuthInstance(config, state.configuredOpts);
+      state.cachedInstance = instance;
       console.log('[BETTER_AUTH] Instance created for', config.clientSlug || config.clientId);
       return instance;
     });
   }
 
-  return initPromise;
+  return state.initPromise;
 }
 
 /**
@@ -432,7 +748,7 @@ export async function exchangeOAuthForIdpTokens(
         email,
         name,
         image,
-        client_id: config.clientSlug || String(config.clientId),
+        client_id: resolveClientKey(config, 'auth/better-auth:oauth-callback').key ?? '',
         /**
          * Card 138635 — the RAW provider id_token, forwarded verbatim.
          *
@@ -465,6 +781,42 @@ export async function exchangeOAuthForIdpTokens(
 
     if (!oauthRes.ok) {
       console.error('[BETTER_AUTH] IDP oauth-callback failed:', oauthRes.status);
+
+      /**
+       * WHY THIS LOGS ONLY ON FAILURE, AND WHY IT LOGS THESE FIELDS.
+       *
+       * UNVERIFIED_ASSERTION has exactly two causes and the response body cannot tell
+       * them apart: we sent no id_token for the IDP to verify, or we sent one whose
+       * signature/aud/iss the IDP rejected. Without this line the operator sees a 401 on
+       * a login that visibly succeeded and has nowhere to go — which is where UMI sat on
+       * 2026-08-26.
+       *
+       * NEVER THE TOKEN ITSELF. An id_token is credential material and this whole code
+       * path exists to keep it out of anything persistent; a log file is persistent. We
+       * print presence, length, and the three claims that decide verification. `aud` is
+       * the Google client id — not a secret, and the single most likely mismatch, since
+       * the IDP checks it against what IT has registered for this client.
+       */
+      const forwarded = idTokenScope.getStore()?.idToken;
+      let claims: Record<string, unknown> = {};
+      if (forwarded) {
+        try {
+          claims = decodeJwt(forwarded) as Record<string, unknown>;
+        } catch {
+          claims = { decode: 'FAILED — not a well-formed JWT' };
+        }
+      }
+      console.error('[BETTER_AUTH] exchange diagnostics:', {
+        id_token_forwarded: !!forwarded,
+        id_token_length: forwarded ? forwarded.length : 0,
+        // Absent id_token => the IDP had nothing to verify. Present => compare these
+        // against the client's registered Google credentials on the IDP.
+        aud: claims.aud ?? null,
+        iss: claims.iss ?? null,
+        email_verified: claims.email_verified ?? null,
+        sent_client_id: resolveClientKey(config, 'auth/better-auth:oauth-callback').key ?? null,
+        idp_url: idpUrl,
+      });
       return false;
     }
 
@@ -478,22 +830,69 @@ export async function exchangeOAuthForIdpTokens(
     }
 
     // Build IDP token data
-    // ORIGINAL INTENT: IDP withholds refresh_token until 2FA is complete, so
-    // !hasRefreshToken was a reliable "2FA required" signal.
     //
-    // BUG [IDP-2FA-BUG]: IDP is currently returning refresh_token on the initial
-    // oauth-callback even for require_2fa tenants that haven't done 2FA yet.
-    // This made !hasRefreshToken=false → requiresTwoFactor=false → mfaVerified=true,
-    // bypassing the 2FA gate entirely.
+    // 170007 CONTRACT (BAPert ruling on 121350, agreed with DotNetPert
+    // 2026-08-08 — see mail thread, not re-derived here):
+    //   1. The IDP emits `requires_two_factor` (snake_case, both serializers,
+    //      per the estate law) as a NON-NULLABLE bool on OAuthCallbackResponse
+    //      (PayEz.DTOs OAuthCallbackResponse.cs) — ALWAYS present. No IDP
+    //      change needed or wanted: emitting a second, camelCase name for the
+    //      same fact would be the dialect problem the estate law exists to
+    //      prevent, not a fix.
+    //   2. Read requires_two_factor (snake) ONLY. CORRECTED mid-review:
+    //      BAPert's first draft of this contract said "read both casings,
+    //      defensively" — DotNetPert rejected that: a dual-casing client-side
+    //      read gives one fact two wire names just as surely as a dual-casing
+    //      IDP emit would, and it is the exact audience-dialect mistake
+    //      (186443) made deliberately instead of by accident. This package
+    //      previously read camel ONLY (card 170083, now corrected — it must
+    //      NOT record "emit both casings" as the IDP-side fix), which is why
+    //      this line silently fell through to the heuristic below on every
+    //      real call. The fix is reading the one name the IDP actually sends,
+    //      not tolerating both.
+    //   3. The old !hasRefreshToken fallback (IDP-2FA-BUG below) is RETIRED,
+    //      not patched. DotNetPert traced ExternalAuthController's
+    //      oauth-callback: IssueRefreshToken and RequiresTwoFactor both derive
+    //      from the SAME isFullyAuthenticated variable, so they cannot
+    //      disagree on this path — the divergence this fallback existed for
+    //      is not present here. Worse, the heuristic would currently produce
+    //      the RIGHT answer by coincidence, which hides the day it stops
+    //      being derived from one variable.
+    //   4. requires_two_factor is non-nullable, so reaching the `true`
+    //      default below means the response ISN'T an OAuthCallbackResponse at
+    //      all (wrong endpoint / error body / failed parse) — logged as that,
+    //      not as "2FA status unknown". Fail-closed to requiresTwoFactor=true
+    //      either way (rule 3).
+    //   5. mfaVerified = !requiresTwoFactor, computed fresh from THIS
+    //      response — no hardcoding, no carrying a prior session value
+    //      forward (that half of the monotonic-OR defect lived in
+    //      refresh.ts / ensure-fresh-access-token.ts, fixed separately).
     //
-    // FIX: Always set mfaVerified=false on the initial OAuth exchange.
-    // The tenant's require_2fa setting is enforced by the viability endpoint
-    // (tenantRequiresTwoFactor=true), which redirects to verify-code whenever
-    // mfaVerified=false. After real 2FA, transitionTo2FASession() sets it true.
-    // Revert this comment + restore `mfaVerified: !requiresTwoFactor` once the
-    // IDP correctly withholds refresh_token until post-2FA.
-    const hasRefreshToken = !!result.refresh_token;
-    const requiresTwoFactor = result.user?.requiresTwoFactor ?? result.requiresTwoFactor ?? !hasRefreshToken;
+    // PRIOR STATE, for the record: this used to hardcode mfaVerified=false on
+    // every OAuth exchange as a blunt workaround for a since-disproven IDP
+    // bug, which itself caused every Google user to be sent to /mfa even on
+    // require_2fa=FALSE tenants (NextPert 13450's blocker, failing T4 on the
+    // demo tenant). That workaround is removed along with the bug it worked
+    // around.
+    const requiresTwoFactor: boolean = (() => {
+      // SNAKE ONLY (BAPert's corrected ruling, 2026-08-08): reading camel as
+      // a "defensive" secondary would give one fact two wire names — exactly
+      // the audience-dialect mistake (186443) being made deliberately. The
+      // estate law is explicit-snake-per-field-both-serializers; the IDP
+      // already complies (OAuthCallbackResponse.cs, both System.Text.Json
+      // and Newtonsoft). No IDP change, no camel read, no dual-casing.
+      const v = result.requires_two_factor ?? result.user?.requires_two_factor;
+      if (v === undefined) {
+        console.warn(
+          '[BETTER_AUTH] oauth-callback response has no requires_two_factor field at all — ' +
+            'unexpected response shape (requires_two_factor is non-nullable on OAuthCallbackResponse; ' +
+            'this is not "2FA status unknown", it means we are not looking at an oauth-callback response). ' +
+            'Defaulting requiresTwoFactor=true (fail closed).',
+        );
+        return true;
+      }
+      return !!v;
+    })();
     const idpTokenData = {
       idpAccessToken: result.access_token,
       idpRefreshToken: result.refresh_token,
@@ -505,7 +904,7 @@ export async function exchangeOAuthForIdpTokens(
       name: result.user?.full_name || result.user?.name || result.name || name,
       image: image,
       roles: result.user?.roles || result.roles || [],
-      mfaVerified: false, // Always false post-OAuth — see IDP-2FA-BUG note above
+      mfaVerified: !requiresTwoFactor, // re-derived fresh — see 170007 contract above
       // Cards 141688/141741 — RELAYED, NOT DERIVED.
       //
       // The IDP already decides this (ExternalAuthController:943 and :2024,
@@ -671,7 +1070,43 @@ export function createAuthGetHandler(loginPath: string = '/account-auth/login')
       const location = response.headers.get('location') || '';
       if (location.includes('/api/auth/error') || location.includes('please_restart')) {
         console.warn('[BETTER_AUTH] OAuth state error, redirecting to login');
-        return Response.redirect(new URL(loginPath, request.url), 302);
+        // *** DO NOT "TIDY" THIS BACK TO Response.redirect(). IT THROWS. (328439) ***
+        // Response.redirect() REQUIRES an absolute URL — measured, on the leg's own
+        // runtime and again on node 24:
+        //     Response.redirect('/account-auth/login', 302)
+        //       -> TypeError: Failed to parse URL from /account-auth/login
+        // That requirement is the whole cause of the bug this replaces. The old line
+        // was:
+        //     return Response.redirect(new URL(loginPath, request.url), 302);
+        // `request.url` inside a containerised Next standalone server carries the
+        // LISTEN address, not the address the browser used, so a container bound to
+        // 0.0.0.0:8080 handed the browser `http://0.0.0.0:8080/sign-in` — an address
+        // that can NEVER load (net::ERR_ADDRESS_INVALID, confirmed in a real browser
+        // by QAPert). Reload cannot recover it, because the address is invalid rather
+        // than down. It fired on the ORDINARY path: the oauth_state cookie is
+        // Max-Age=600, so anyone spending >10 minutes at Google's account chooser
+        // landed on a dead tab.
+        //
+        // A RELATIVE Location header is legal (RFC 7231 §7.1.2) and the browser
+        // resolves it against the origin it is ACTUALLY on, so no origin has to be
+        // guessed, configured, or derived from a header. This is the same shape the
+        // app's own middleware already emits successfully (307 + relative), which is
+        // why page redirects survived while this one did not.
+        //
+        // WHY NOT REBUILD FROM BETTER_AUTH_URL / rawBaseURL, the other proposal:
+        //   (a) rawBaseURL is NOT in scope here — it is a local inside
+        //       createBetterAuthInstance (~:397), a different function ~676 lines up.
+        //       Reaching it means recomputing the env precedence or exporting a
+        //       helper, i.e. more moving parts for a strictly worse result.
+        //   (b) It would reintroduce a guessed origin and make this path depend on
+        //       BETTER_AUTH_URL being set correctly per leg. Relative needs no env.
+        //   (c) Anything Host-derived would open host-header injection on a redirect
+        //       that is currently host-INVARIANT. Relative keeps that property.
+        //
+        // Works whether loginPath is relative (package default '/account-auth/login',
+        // and the graft passes '/sign-in') or absolute — an absolute Location is also
+        // legal, so a consumer passing a full URL still behaves.
+        return new Response(null, { status: 302, headers: { location: loginPath } });
       }
     }