@payez/next-mvp 4.1.21 → 4.4.1

package/dist/auth/better-auth.js

@@ -43,10 +43,12 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.__betterAuthInstance = void 0;
+exports.secretFingerprint = secretFingerprint;
+exports.buildIdpOAuthProviderConfig = buildIdpOAuthProviderConfig;
 exports.buildBetterAuthProviders = buildBetterAuthProviders;
 exports.createBetterAuthInstance = createBetterAuthInstance;
 exports.isBetterAuthEnabled = isBetterAuthEnabled;
+exports.__getBetterAuthInstance = __getBetterAuthInstance;
 exports.configureBetterAuth = configureBetterAuth;
 exports.getBetterAuthInstance = getBetterAuthInstance;
 exports.getBetterAuthHandler = getBetterAuthHandler;
@@ -55,15 +57,26 @@ exports.storeIdpTokensInSession = storeIdpTokensInSession;
 exports.createAuthGetHandler = createAuthGetHandler;
 require("server-only");
 const node_async_hooks_1 = require("node:async_hooks");
+const crypto_1 = require("crypto");
 const jose_1 = require("jose"); // better-auth's own JWT dependency
 const better_auth_1 = require("better-auth");
 const next_js_1 = require("better-auth/next-js");
 const next_js_2 = require("better-auth/next-js");
 const magic_link_1 = require("better-auth/plugins/magic-link");
+const client_key_1 = require("../lib/client-key");
+const generic_oauth_1 = require("better-auth/plugins/generic-oauth");
 const idp_client_config_1 = require("../lib/idp-client-config");
 const app_slug_1 = require("../lib/app-slug");
 const redis_1 = require("../lib/redis");
 const session_store_1 = require("../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.
+ */
+function secretFingerprint(value) {
+    return (0, crypto_1.createHash)('sha256').update(value).digest('hex').slice(0, 12);
+}
 /**
  * Build Better Auth social providers from IDP config.
  */
@@ -90,7 +103,107 @@ const session_store_1 = require("../lib/session-store");
  * function. Outside that scope the store is undefined and the body simply omits
  * id_token, which is the correct additive behaviour.
  */
-const idTokenScope = new node_async_hooks_1.AsyncLocalStorage();
+/**
+ * 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;
+gScope[ID_TOKEN_SCOPE_KEY] ??= new node_async_hooks_1.AsyncLocalStorage();
+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.
+ */
+function buildIdpOAuthProviderConfig() {
+    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.
+         */
+    };
+}
 function buildBetterAuthProviders(config) {
     const providers = {};
     for (const oauth of config.oauthProviders || []) {
@@ -106,10 +219,38 @@ function buildBetterAuthProviders(config) {
         if (name === 'google' && !scopes.includes('profile')) {
             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'
@@ -161,8 +302,21 @@ function buildBetterAuthProviders(config) {
                     return null;
                 // The only new behaviour: hand the raw token to this request's scope.
                 const scope = idTokenScope.getStore();
-                if (scope)
+                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
                 // KEEP, never what we ACCEPT.
@@ -190,12 +344,21 @@ function buildBetterAuthProviders(config) {
  */
 function createBetterAuthInstance(idpConfig, opts = {}) {
     const appSlug = idpConfig.clientSlug || (0, app_slug_1.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)}` : '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
         || idpConfig.baseClientUrl
         || `http://localhost:${process.env.PORT || '3000'}`;
     const baseURL = rawBaseURL.replace(/\/+$/, '') + '/api/auth';
+    const idpOAuth = buildIdpOAuthProviderConfig();
     return (0, better_auth_1.betterAuth)({
         baseURL,
         secret: idpConfig.authSecret,
@@ -205,37 +368,133 @@ function createBetterAuthInstance(idpConfig, opts = {}) {
             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) => {
-                try {
-                    return await (0, redis_1.getRedis)().get(`ba:${appSlug}:${key}`);
-                }
-                catch {
-                    return null;
+                const value = await (0, redis_1.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, value, ttl) => {
-                try {
-                    const redis = (0, redis_1.getRedis)();
-                    if (ttl) {
-                        await redis.setex(`ba:${appSlug}:${key}`, ttl, value);
-                    }
-                    else {
-                        await redis.setex(`ba:${appSlug}:${key}`, session_store_1.SESSION_TTL, value);
-                    }
-                }
-                catch { /* Redis unavailable — cookie cache still works */ }
+                const redis = (0, redis_1.getRedis)();
+                await redis.setex(`ba:${appSlug}:${key}`, ttl ?? session_store_1.SESSION_TTL, value);
             },
             delete: async (key) => {
                 try {
                     await (0, redis_1.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 Promise.resolve().then(() => __importStar(require('../lib/session-store')));
+                    await deleteSession(key);
+                }
+                catch (err) {
+                    console.warn('[BETTER_AUTH] secondary delete: canonical store cleanup failed:', err);
+                }
             },
         },
         session: {
@@ -273,6 +532,9 @@ function createBetterAuthInstance(idpConfig, opts = {}) {
         },
         plugins: [
             (0, next_js_1.nextCookies)(),
+            // Exchange-move: present ONLY when the IDP's OAuth endpoints are
+            // configured. Absent otherwise, so this cannot alter existing behaviour.
+            ...(idpOAuth ? [(0, generic_oauth_1.genericOAuth)({ config: [idpOAuth] })] : []),
             ...(opts.magicLink ? [(0, magic_link_1.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.
@@ -286,16 +548,15 @@ function createBetterAuthInstance(idpConfig, opts = {}) {
 function isBetterAuthEnabled() {
     return true;
 }
-/**
- * Get Better Auth Next.js route handlers (GET, POST).
- * Initializes Better Auth from IDP config on first call, caches the instance.
- */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-let cachedInstance = null;
-exports.__betterAuthInstance = cachedInstance;
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-let initPromise = null;
-let configuredOpts = {};
+const STATE_KEY = '__payezBetterAuthState';
+const g = globalThis;
+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.
+function __getBetterAuthInstance() {
+    return state.cachedInstance;
+}
 /**
  * Configure Better Auth instance options for this process.
  *
@@ -308,24 +569,24 @@ let configuredOpts = {};
  * cannot be applied retroactively.
  */
 function configureBetterAuth(opts) {
-    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;
 }
 async function getBetterAuthInstance() {
-    if (cachedInstance)
-        return cachedInstance;
-    if (!initPromise) {
-        initPromise = (0, idp_client_config_1.getIDPClientConfig)(true).then(config => {
-            const instance = createBetterAuthInstance(config, configuredOpts);
-            exports.__betterAuthInstance = cachedInstance = instance;
+    if (state.cachedInstance)
+        return state.cachedInstance;
+    if (!state.initPromise) {
+        state.initPromise = (0, idp_client_config_1.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;
 }
 /**
  * Get flag-gated auth handler for Next.js route.
@@ -394,7 +655,7 @@ async function exchangeOAuthForIdpTokens(sessionToken, provider = 'google') {
                 email,
                 name,
                 image,
-                client_id: config.clientSlug || String(config.clientId),
+                client_id: (0, client_key_1.resolveClientKey)(config, 'auth/better-auth:oauth-callback').key ?? '',
                 /**
                  * Card 138635 — the RAW provider id_token, forwarded verbatim.
                  *
@@ -425,6 +686,42 @@ async function exchangeOAuthForIdpTokens(sessionToken, provider = 'google') {
         console.log('[BETTER_AUTH] IDP oauth-callback response:', oauthRes.status, oauthResText.substring(0, 500));
         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 = {};
+            if (forwarded) {
+                try {
+                    claims = (0, jose_1.decodeJwt)(forwarded);
+                }
+                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: (0, client_key_1.resolveClientKey)(config, 'auth/better-auth:oauth-callback').key ?? null,
+                idp_url: idpUrl,
+            });
             return false;
         }
         let idpData;
@@ -440,22 +737,67 @@ async function exchangeOAuthForIdpTokens(sessionToken, provider = 'google') {
             return false;
         }
         // 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 = (() => {
+            // 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,
@@ -467,7 +809,7 @@ async function exchangeOAuthForIdpTokens(sessionToken, provider = 'google') {
             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,
@@ -624,7 +966,43 @@ function createAuthGetHandler(loginPath = '/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 } });
                 }
             }
             // After successful OAuth callback: exchange Google identity for IDP tokens