@payez/next-mvp 4.1.10 → 4.1.20

package/dist/auth/better-auth.js

@@ -51,8 +51,11 @@ exports.configureBetterAuth = configureBetterAuth;
 exports.getBetterAuthInstance = getBetterAuthInstance;
 exports.getBetterAuthHandler = getBetterAuthHandler;
 exports.exchangeOAuthForIdpTokens = exchangeOAuthForIdpTokens;
+exports.storeIdpTokensInSession = storeIdpTokensInSession;
 exports.createAuthGetHandler = createAuthGetHandler;
 require("server-only");
+const node_async_hooks_1 = require("node:async_hooks");
+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");
@@ -64,6 +67,30 @@ const session_store_1 = require("../lib/session-store");
 /**
  * Build Better Auth social providers from IDP config.
  */
+/**
+ * REQUEST-SCOPED carrier for the provider's raw id_token. Card 138635.
+ *
+ * WHY THIS EXISTS: /api/ExternalAuth/oauth-callback mints an IDP bearer for any
+ * ASSERTED email — we send {provider, email} and nothing verifiable. The fix is
+ * for the IDP to require a provider-signed id_token and verify it itself. This
+ * is the client half: capture the token Better Auth already receives, and
+ * forward it. Additive — the IDP ignores it until its gate flips.
+ *
+ * WHY AsyncLocalStorage AND NOT REDIS (BAPert's ruling: forward, do not persist):
+ * an id_token is credential material. Writing it to the session record would put
+ * it one allow-list edit away from leaking out of /api/internal/session-data,
+ * and it would outlive the request that needed it. ALS scopes it to the single
+ * request, and it is gone when the request ends — nothing to expire, nothing to
+ * scrub, nothing to leak.
+ *
+ * SAFE BY CONSTRUCTION: getUserInfo (which fills this) and the post-callback
+ * exchange (which reads it) both run inside createAuthGetHandler's own request.
+ * VERIFIED, not assumed: better-auth.ts:452 awaits ba.GET(request) — the call
+ * that invokes getUserInfo — and the exchange follows at :465 in the SAME
+ * 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();
 function buildBetterAuthProviders(config) {
     const providers = {};
     for (const oauth of config.oauthProviders || []) {
@@ -93,6 +120,65 @@ function buildBetterAuthProviders(config) {
             accessType: rawAccessType === 'online' ? 'online' : rawAccessType === 'offline' ? 'offline' : undefined,
             hd: typeof rawHostedDomain === 'string' ? rawHostedDomain : undefined,
         };
+        /**
+         * CAPTURE THE RAW id_token — card 138635, client half.
+         *
+         * getUserInfo is the ONLY provider hook that receives the token set.
+         * mapProfileToUser cannot do this: it is handed the DECODED claims, and a
+         * signed JWT cannot be reconstructed from them. We need the raw token
+         * because the IDP must verify the signature ITSELF — a client-decoded
+         * claim is just another assertable field, which is the defect restated.
+         *
+         * ⚠ THIS REPLACES THE DEFAULT google getUserInfo ENTIRELY. Upstream calls
+         * `if (options.getUserInfo) return options.getUserInfo(token)` FIRST and
+         * returns our result verbatim, so everything the default did is now ours to
+         * do — including the `hd` hosted-domain restriction.
+         *
+         * `hd` IS NOT HYPOTHETICAL: it is wired from additionalParams.hd four lines
+         * above, so a client can restrict sign-in to a Google Workspace domain.
+         * Silently dropping it would let ANY Google account into a client that had
+         * restricted itself — a security regression introduced by a security fix.
+         * (Measured on 93: zero clients set it today. That is a reason to be
+         * careful, not a reason to skip it — it is configurable and unused, which
+         * is exactly the state in which a regression goes unnoticed.)
+         *
+         * SO WE DO NOT OVERRIDE AT ALL WHEN `hd` IS SET. We take the hook over
+         * ONLY where upstream's check is PROVABLY VACUOUS — its own first line is
+         * `if (!configuredHostedDomain) return true`. With no hd configured the
+         * default would return true unconditionally, so omitting it is equivalent
+         * by the library's own definition rather than by our judgement.
+         *
+         * A client that DOES set hd keeps the stock provider, keeps its domain
+         * restriction, and simply does not contribute an id_token yet. Losing a
+         * capability is an acceptable cost; silently losing a security control is
+         * not. (better-auth does not re-export the predicate through its public
+         * types, and reimplementing a security check is how two copies drift — so
+         * the honest move is to not need it.)
+         */
+        if (name === 'google' && !providers[name].hd) {
+            providers[name].getUserInfo = async (token) => {
+                if (!token?.idToken)
+                    return null;
+                // The only new behaviour: hand the raw token to this request's scope.
+                const scope = idTokenScope.getStore();
+                if (scope)
+                    scope.idToken = token.idToken;
+                // 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.
+                const claims = (0, jose_1.decodeJwt)(token.idToken);
+                return {
+                    user: {
+                        id: claims.sub,
+                        name: claims.name,
+                        email: claims.email,
+                        image: claims.picture,
+                        emailVerified: claims.email_verified,
+                    },
+                    data: claims,
+                };
+            };
+        }
     }
     return providers;
 }
@@ -188,6 +274,9 @@ function createBetterAuthInstance(idpConfig, opts = {}) {
         plugins: [
             (0, next_js_1.nextCookies)(),
             ...(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.
+            ...(opts.plugins ?? []),
         ],
     });
 }
@@ -306,6 +395,30 @@ async function exchangeOAuthForIdpTokens(sessionToken, provider = 'google') {
                 name,
                 image,
                 client_id: config.clientSlug || String(config.clientId),
+                /**
+                 * Card 138635 — the RAW provider id_token, forwarded verbatim.
+                 *
+                 * Every other field in this body is an ASSERTION. The endpoint mints an
+                 * IDP bearer from them today with no cryptographic check of any kind,
+                 * which is why it is a complete authentication bypass and why it has
+                 * been publicly reachable for 488 days.
+                 *
+                 * This field is the only one the IDP can VERIFY: signature against
+                 * Google's JWKS, plus iss / exp / aud, and then read email_verified
+                 * from the verified claims. Additive — the IDP ignores it until its
+                 * gate flips, so this cannot break a login on its own.
+                 *
+                 * RAW, AND NOTHING DERIVED FROM IT (BAPert's ruling). We do NOT send a
+                 * decoded email_verified. A client-computed verification flag is a body
+                 * field with a better story: an attacker posts email_verified:true and
+                 * the defect is rebuilt one layer up. The IDP verifies for itself or
+                 * the fix is theatre.
+                 *
+                 * Absent when this runs outside the OAuth callback scope — the key is
+                 * simply omitted rather than sent null, so "we never captured one" stays
+                 * distinguishable from "the provider issued none".
+                 */
+                ...(idTokenScope.getStore()?.idToken ? { id_token: idTokenScope.getStore().idToken } : {}),
             }),
         });
         const oauthResText = await oauthRes.text();
@@ -327,8 +440,20 @@ async function exchangeOAuthForIdpTokens(sessionToken, provider = 'google') {
             return false;
         }
         // Build IDP token data
-        // CRITICAL: If the IDP withholds refresh_token without setting requiresTwoFactor,
-        // treat missing refresh token as "2FA required" so middleware redirects to verify-code.
+        // 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.
+        //
+        // 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;
         const idpTokenData = {
@@ -342,31 +467,125 @@ 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: !requiresTwoFactor,
+            mfaVerified: false, // Always false post-OAuth — see IDP-2FA-BUG note above
+            // Cards 141688/141741 — RELAYED, NOT DERIVED.
+            //
+            // The IDP already decides this (ExternalAuthController:943 and :2024,
+            // WO 113023): "enroll_mfa" = no CONFIRMED method, "mfa_verify" = a
+            // confirmed method exists, null = fully authenticated. It was emitted
+            // here and dropped on this line — `idpTokenData` is built field-by-field,
+            // so anything not named is silently discarded. Both downstream consumers
+            // (the middleware gate and the verify-code page) then reasoned in its
+            // absence and sent zero-method users to a page they cannot act on.
+            //
+            // WIRE NAME IS SNAKE: `next_step`, per [JsonPropertyName("next_step")] on
+            // BOTH OAuthCallbackResponse and ExternalTokenResponse. Reading
+            // `result.nextStep` here would be `undefined` forever and fail silently —
+            // the same camel/snake break `requires_two_factor` already cost us once.
+            //
+            // Do NOT recompute this from a method query. The IDP owns the fact; it is
+            // already usable-aware (confirmed and not revoked, per DotNetPert), which
+            // is the distinction that decides correctness: a revoked-TOTP user has
+            // count>0 but usable=0, and deriving it locally would let through exactly
+            // the users we must challenge.
+            // No `?? null`: if the response has no `next_step` at all (older IDP
+            // build, or a path that does not set it), that is UNKNOWN, not "fully
+            // authenticated". Defaulting it to null here would manufacture a
+            // clean-bill-of-health the IDP never gave and fail open at the gate.
+            nextStep: result.next_step,
             idpClientId: result.client_id ? String(result.client_id) : undefined,
             merchantId: result.merchant_id ? String(result.merchant_id) : undefined,
         };
-        // Store in BA Redis session (for decodeSession)
+        // Storage is shared with the passkey sign-in path — see storeIdpTokensInSession.
+        const stored = await storeIdpTokensInSession(sessionToken, idpTokenData, provider);
+        if (stored)
+            console.log('[BETTER_AUTH] IDP tokens stored in session for', email);
+        return stored;
+    }
+    catch (err) {
+        console.error('[BETTER_AUTH] IDP token exchange failed:', err instanceof Error ? err.message : String(err));
+        return false;
+    }
+}
+/**
+ * Write IDP tokens into an EXISTING Better Auth session. Storage only — this
+ * function never acquires tokens and never decides who the caller is.
+ *
+ * ── WHY THIS IS SPLIT OUT (BAPert ruling, 2026-08-04) ────────────────────────
+ *
+ * `exchangeOAuthForIdpTokens` above does TWO things: it ACQUIRES tokens by
+ * POSTing to `/api/ExternalAuth/oauth-callback`, and then it STORES them. Only
+ * the second half is reusable, and the first half is actively dangerous to
+ * reuse:
+ *
+ *   oauth-callback mints an IDP bearer from an ASSERTED EMAIL with no
+ *   cryptographic verification of any kind (card 138635).
+ *
+ * Passkey sign-in already holds something strictly better — a grant issued by
+ * `/api/ExternalAuth/passwordless/passkey/verify`, which checked a real
+ * signature against a registered credential. Routing that through
+ * oauth-callback to obtain a session would DOWNGRADE a cryptographically
+ * verified assertion into an unverified one, make passkey sign-in weaker than
+ * its own ceremony, and inherit 138635 wholesale.
+ *
+ * That is not hypothetical: "do what the OAuth path does" is the obvious
+ * implementation and it is the wrong one. Splitting acquisition from storage is
+ * what makes the wrong one hard to write by accident.
+ *
+ * ── WHAT CALLERS MUST HAVE DONE FIRST ───────────────────────────────────────
+ *
+ * A Better Auth session must ALREADY EXIST for `sessionToken`. This function
+ * enriches; it does not create. Better Auth owns session creation and cookie
+ * signing, and nothing in this package should replicate either — the cookie is
+ * `{token}.{base64(hmac)}` with standard padding, signed with the runtime
+ * `authSecret` from Redis, and hand-rolling that produces a session which
+ * decodes but does not authenticate.
+ *
+ * @param sessionToken  the Better Auth session token (from its Set-Cookie)
+ * @param idpTokenData  tokens + identity, already obtained by the CALLER'S OWN
+ *                      verified route. Built field-by-field by the caller so an
+ *                      unnamed field cannot ride along silently.
+ * @param authProvider  provenance label recorded on the canonical row. Written
+ *                      to the historical `oauthProvider` key, which predates
+ *                      non-OAuth callers; the NAME is legacy, the VALUE should
+ *                      state what actually authenticated ('passkey', 'google').
+ */
+async function storeIdpTokensInSession(sessionToken, idpTokenData, authProvider) {
+    try {
+        const config = await (0, idp_client_config_1.getIDPClientConfig)();
+        const appSlug = config.clientSlug || (0, app_slug_1.getAppSlug)();
+        const baKey = `ba:${appSlug}:${sessionToken}`;
+        const baRaw = await (0, redis_1.getRedis)().get(baKey).catch(() => null);
+        if (!baRaw) {
+            // No session to enrich. Do NOT create one as a fallback: a session
+            // conjured here would carry no Better Auth cookie, so it would be
+            // unreachable by the browser and invisible to every other consumer —
+            // failing as "silently signed out" rather than as an error.
+            console.warn('[BETTER_AUTH] storeIdpTokensInSession: no BA session for token', sessionToken.substring(0, 10));
+            return false;
+        }
+        const baData = JSON.parse(baRaw);
         baData.idpTokens = idpTokenData;
         await (0, redis_1.getRedis)().setex(baKey, session_store_1.SESSION_TTL, JSON.stringify(baData));
-        // Write to canonical session store so refresh handler and token lifecycle can find the tokens.
-        // Key format: {sessionPrefix}{token} — same key that getSession() reads from.
+        // Canonical store — the key getSession() reads, used by the refresh handler
+        // and token lifecycle. A failure here leaves the BA session correct and the
+        // canonical row missing, so it is warned and not fatal: the user is signed
+        // in, and refresh degrades rather than the sign-in failing outright.
         try {
             const { getSessionPrefix } = await Promise.resolve().then(() => __importStar(require('../lib/app-slug')));
             const canonicalKey = `${getSessionPrefix()}${sessionToken}`;
             await (0, redis_1.getRedis)().setex(canonicalKey, session_store_1.SESSION_TTL, JSON.stringify({
                 ...idpTokenData,
-                oauthProvider: provider,
+                oauthProvider: authProvider,
             }));
         }
         catch (canonicalErr) {
             console.warn('[BETTER_AUTH] Failed to write canonical session:', canonicalErr instanceof Error ? canonicalErr.message : String(canonicalErr));
         }
-        console.log('[BETTER_AUTH] IDP tokens stored in session for', email);
         return true;
     }
     catch (err) {
-        console.error('[BETTER_AUTH] IDP token exchange failed:', err instanceof Error ? err.message : String(err));
+        console.error('[BETTER_AUTH] storeIdpTokensInSession failed:', err instanceof Error ? err.message : String(err));
         return false;
     }
 }
@@ -389,45 +608,52 @@ async function exchangeOAuthForIdpTokens(sessionToken, provider = 'google') {
  */
 function createAuthGetHandler(loginPath = '/account-auth/login') {
     return async function GET(request) {
-        const ba = await getBetterAuthHandler();
-        if (!ba) {
-            return new Response('Auth handler not configured', { status: 500 });
-        }
-        const response = await ba.GET(request);
-        // Intercept auth errors (state mismatch, expired cookies) — redirect to login cleanly
-        if (response.status === 302) {
-            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);
+        // Card 138635: establish the request-scoped carrier for the provider's raw
+        // id_token. It must wrap BOTH ba.GET (which invokes getUserInfo, the only
+        // hook that sees the token) and the exchange below (which forwards it).
+        // Wrapping the whole handler is what makes "never persisted" achievable —
+        // the token exists only for the life of this request.
+        return idTokenScope.run({}, async () => {
+            const ba = await getBetterAuthHandler();
+            if (!ba) {
+                return new Response('Auth handler not configured', { status: 500 });
             }
-        }
-        // After successful OAuth callback: exchange Google identity for IDP tokens
-        const url = new URL(request.url);
-        if (url.pathname.includes('/callback/') && response.status === 302) {
-            try {
-                const auth = await getBetterAuthInstance();
-                if (auth?.api?.getSession) {
-                    const setCookies = response.headers.getSetCookie?.() || [];
-                    const cookieHeader = setCookies
-                        .map((c) => c.split(';')[0])
-                        .join('; ');
-                    const headers = new Headers();
-                    headers.set('cookie', cookieHeader);
-                    const session = await auth.api.getSession({ headers });
-                    if (session?.session?.token) {
-                        console.log('[BETTER_AUTH] Got session token from callback:', session.session.token.substring(0, 10), '| email:', session.user?.email);
-                        await exchangeOAuthForIdpTokens(session.session.token);
-                    }
-                    else {
-                        console.warn('[BETTER_AUTH] Could not get session after OAuth callback');
-                    }
+            const response = await ba.GET(request);
+            // Intercept auth errors (state mismatch, expired cookies) — redirect to login cleanly
+            if (response.status === 302) {
+                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);
                 }
             }
-            catch (err) {
-                console.error('[BETTER_AUTH] IDP token exchange failed:', err.message);
+            // After successful OAuth callback: exchange Google identity for IDP tokens
+            const url = new URL(request.url);
+            if (url.pathname.includes('/callback/') && response.status === 302) {
+                try {
+                    const auth = await getBetterAuthInstance();
+                    if (auth?.api?.getSession) {
+                        const setCookies = response.headers.getSetCookie?.() || [];
+                        const cookieHeader = setCookies
+                            .map((c) => c.split(';')[0])
+                            .join('; ');
+                        const headers = new Headers();
+                        headers.set('cookie', cookieHeader);
+                        const session = await auth.api.getSession({ headers });
+                        if (session?.session?.token) {
+                            console.log('[BETTER_AUTH] Got session token from callback:', session.session.token.substring(0, 10), '| email:', session.user?.email);
+                            await exchangeOAuthForIdpTokens(session.session.token);
+                        }
+                        else {
+                            console.warn('[BETTER_AUTH] Could not get session after OAuth callback');
+                        }
+                    }
+                }
+                catch (err) {
+                    console.error('[BETTER_AUTH] IDP token exchange failed:', err.message);
+                }
             }
-        }
-        return response;
+            return response;
+        });
     };
 }

package/dist/auth/utils/idp-client.d.ts

@@ -11,7 +11,7 @@
  * @version 1.0.0
  * @since auth-refactor-2026-01
  */
-import type { IdpLoginResponse, IdpOAuthCallbackResponse, IdpRefreshResponse, LoginCredentials } from '../types/auth-types';
+import type { IdpLoginResponse, IdpRefreshResponse, LoginCredentials } from '../types/auth-types';
 /**
  * Get IDP base URL. Throws if not configured.
  */
@@ -32,30 +32,21 @@ export declare function idpLogin(credentials: LoginCredentials, clientHeaders?:
     userAgent?: string;
 }): Promise<IdpLoginResponse>;
 /**
- * Register/authenticate OAuth user with IDP.
+ * idpOAuthCallback REMOVED 2026-08-05 (NextPert, BAPert 20168 / QAPert 20166).
  *
- * Called after OAuth provider (Google, etc.) redirects back.
- * Creates or retrieves IDP user and returns IDP tokens.
+ * It POSTed to /api/ExternalAuth/oauth-callback with provider, email, name,
+ * tokens and client_id — ALL ASSERTIONS, no id_token, nothing verifiable. After
+ * the 170003 fix (13436d56e) that call can only ever return 401.
  *
- * @param oauthData - Data from OAuth provider
- * @returns IDP response with tokens and user info
- */
-export declare function idpOAuthCallback(oauthData: {
-    provider: string;
-    providerAccountId: string;
-    email: string;
-    name?: string;
-    image?: string;
-    accessToken?: string;
-    refreshToken?: string;
-    expiresAt?: number;
-}): Promise<IdpOAuthCallbackResponse>;
-/**
- * Refresh an expired access token using the refresh token.
+ * It was a SECOND caller of the same endpoint, and only the first
+ * (better-auth.ts, card 138635) was hardened — the same duplicated-integration
+ * trap the viability code documents ("adding the relay to just one would leave
+ * an app that mounts THIS one still blind").
  *
- * @param refreshToken - The refresh token from previous login
- * @param mfaContext - MFA context to preserve across refresh
- * @returns New tokens or error
+ * It had no call sites and was not reachable through the package exports map
+ * (no ./auth/utils key, no wildcard), so removing it breaks nothing. Deleted
+ * rather than fixed, because an unreachable function whose only outcome is a
+ * 401 that LOOKS like a security success is a trap for whoever finds it next.
  */
 export declare function idpRefreshToken(refreshToken: string, mfaContext?: {
     amr?: string[];

package/dist/auth/utils/idp-client.js

@@ -16,7 +16,6 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.getIdpUrl = getIdpUrl;
 exports.getClientId = getClientId;
 exports.idpLogin = idpLogin;
-exports.idpOAuthCallback = idpOAuthCallback;
 exports.idpRefreshToken = idpRefreshToken;
 exports.idpVerify2FA = idpVerify2FA;
 exports.idpSend2FACode = idpSend2FACode;
@@ -133,90 +132,21 @@ function getLoginErrorMessage(status, responseData) {
 // OAUTH CALLBACK
 // ============================================================================
 /**
- * Register/authenticate OAuth user with IDP.
+ * idpOAuthCallback REMOVED 2026-08-05 (NextPert, BAPert 20168 / QAPert 20166).
  *
- * Called after OAuth provider (Google, etc.) redirects back.
- * Creates or retrieves IDP user and returns IDP tokens.
+ * It POSTed to /api/ExternalAuth/oauth-callback with provider, email, name,
+ * tokens and client_id — ALL ASSERTIONS, no id_token, nothing verifiable. After
+ * the 170003 fix (13436d56e) that call can only ever return 401.
  *
- * @param oauthData - Data from OAuth provider
- * @returns IDP response with tokens and user info
- */
-async function idpOAuthCallback(oauthData) {
-    const idpUrl = getIdpUrl();
-    const clientId = getClientId();
-    try {
-        const response = await fetch(`${idpUrl}/api/ExternalAuth/oauth-callback`, {
-            method: 'POST',
-            headers: {
-                'Content-Type': 'application/json',
-                'X-Client-Id': clientId,
-            },
-            body: JSON.stringify({
-                provider: oauthData.provider,
-                provider_account_id: oauthData.providerAccountId,
-                email: oauthData.email,
-                name: oauthData.name || '',
-                image: oauthData.image || '',
-                access_token: oauthData.accessToken || '',
-                refresh_token: oauthData.refreshToken || '',
-                expires_at: oauthData.expiresAt || 0,
-                client_id: clientId,
-            }),
-        });
-        if (!response.ok) {
-            const errorText = await response.text().catch(() => 'Unknown error');
-            console.error('[IDP_CLIENT] OAuth callback failed:', response.status, errorText);
-            return {
-                success: false,
-                error: {
-                    code: `HTTP_${response.status}`,
-                    message: 'OAuth registration failed',
-                },
-            };
-        }
-        const data = await response.json();
-        const responseData = data.data || data;
-        // Normalize snake_case to camelCase
-        return {
-            success: responseData.success !== false,
-            data: responseData.success !== false
-                ? {
-                    accessToken: responseData.accessToken || responseData.access_token,
-                    refreshToken: responseData.refreshToken || responseData.refresh_token,
-                    isNewUser: responseData.isNewUser ?? responseData.is_new_user ?? false,
-                    user: responseData.user
-                        ? {
-                            userId: responseData.user.userId || responseData.user.user_id,
-                            email: responseData.user.email || responseData.user.Email,
-                            fullName: responseData.user.fullName || responseData.user.full_name || responseData.user.name,
-                            roles: responseData.user.roles || [],
-                        }
-                        : undefined,
-                }
-                : undefined,
-            error: responseData.error,
-        };
-    }
-    catch (error) {
-        console.error('[IDP_CLIENT] OAuth callback request failed:', error);
-        return {
-            success: false,
-            error: {
-                code: 'NETWORK_ERROR',
-                message: 'Failed to connect to authentication service',
-            },
-        };
-    }
-}
-// ============================================================================
-// TOKEN REFRESH
-// ============================================================================
-/**
- * Refresh an expired access token using the refresh token.
+ * It was a SECOND caller of the same endpoint, and only the first
+ * (better-auth.ts, card 138635) was hardened — the same duplicated-integration
+ * trap the viability code documents ("adding the relay to just one would leave
+ * an app that mounts THIS one still blind").
  *
- * @param refreshToken - The refresh token from previous login
- * @param mfaContext - MFA context to preserve across refresh
- * @returns New tokens or error
+ * It had no call sites and was not reachable through the package exports map
+ * (no ./auth/utils key, no wildcard), so removing it breaks nothing. Deleted
+ * rather than fixed, because an unreachable function whose only outcome is a
+ * 401 that LOOKS like a security success is a trap for whoever finds it next.
  */
 async function idpRefreshToken(refreshToken, mfaContext) {
     const idpUrl = getIdpUrl();

package/dist/client/better-auth-client.d.ts

@@ -814,7 +814,13 @@ export declare const authClient: {
         isPending: boolean;
         isRefetching: boolean;
         error: import("@better-fetch/fetch").BetterFetchError | null;
-        refetch: (queryParams?: {
+        refetch: (queryParams
+        /**
+         * NextAuth-compatible signOut wrapper.
+         *
+         * Maps NextAuth signOut({ redirect, callbackUrl }) to Better Auth.
+         */
+        ?: {
             query?: import("better-auth/types").SessionQueryParams;
         } | undefined) => Promise<void>;
     };
@@ -988,7 +994,13 @@ export declare const useSession: () => {
     isPending: boolean;
     isRefetching: boolean;
     error: import("@better-fetch/fetch").BetterFetchError | null;
-    refetch: (queryParams?: {
+    refetch: (queryParams
+    /**
+     * NextAuth-compatible signOut wrapper.
+     *
+     * Maps NextAuth signOut({ redirect, callbackUrl }) to Better Auth.
+     */
+    ?: {
         query?: import("better-auth/types").SessionQueryParams;
     } | undefined) => Promise<void>;
 }, signIn: {

package/dist/lib/ensure-fresh-access-token.js

@@ -158,8 +158,16 @@ async function ensureFreshAccessToken(sessionToken, config, options = {}) {
         if (isOAuthSession && session.mfaVerified && acrValue === '1') {
             acrValue = '2';
         }
+        // WO-2: send the POST-lock current refresh token, not the pre-lock snapshot.
+        // `session` was read before we acquired the lock; a concurrent refresh that
+        // completed while we waited rotates the token, so the pre-lock value is stale
+        // and would draw an avoidable 401 (the CAS now catches the resulting wipe, but
+        // the round-trip is wasted). `latest` is the authoritative post-lock session.
+        // Auth-context (amr/acr/2FA) intentionally still derives from `session` — it is
+        // the identity context of THIS request, unchanged by a token rotation.
+        const sentRefreshToken = latest?.idpRefreshToken ?? session.idpRefreshToken;
         const body = {
-            refresh_token: session.idpRefreshToken,
+            refresh_token: sentRefreshToken,
             amr: authMethods,
             acr: acrValue,
         };
@@ -209,7 +217,10 @@ async function ensureFreshAccessToken(sessionToken, config, options = {}) {
                 // (the rotation-race wipe, QA 6873 site 1/2). Compare-and-skip if it changed;
                 // a concurrent rotation is NOT a terminal condition.
                 const postRefresh = await (0, session_store_1.getSession)(sessionToken);
-                const tokenUnchanged = !!session.idpRefreshToken && postRefresh?.idpRefreshToken === session.idpRefreshToken;
+                // CAS compares against the token we ACTUALLY SENT (WO-2: sentRefreshToken,
+                // the post-lock value), not the pre-lock snapshot — otherwise a token rotated
+                // between pre-lock read and our send would be misjudged.
+                const tokenUnchanged = !!sentRefreshToken && postRefresh?.idpRefreshToken === sentRefreshToken;
                 if (tokenUnchanged) {
                     await (0, session_store_1.updateSession)(sessionToken, {
                         idpRefreshToken: '',