@payez/next-mvp 4.1.11 → 4.1.20

package/src/api-handlers/session/viability.ts

@@ -1,143 +1,162 @@
-/**
- * Session Viability Check API Handler for `@payez/next-mvp`
- *
- * This API route is called by the middleware to securely check if a session is valid.
- */
-
-import { NextRequest, NextResponse } from 'next/server';
-import { getSession as getRedisSession, getBetterAuthSession } from '../../lib/session-store';
-import { getSession } from '../../server/auth';
-import { isInitializationFailed, ensureInitialized } from '../../lib/startup-init';
-import { getIDPClientConfig } from '../../lib/idp-client-config';
-
-export async function GET(req: NextRequest) {
-  try {
-    // Ensure initialization is complete (auth signing secret resolved from IDP)
-    if (!process.env.BETTER_AUTH_SECRET && !process.env.NEXTAUTH_SECRET) {
-      try {
-        await ensureInitialized();
-      } catch (error) {
-        // Initialization failed - return 503
-        console.error('[API Viability] Initialization failed - returning 503');
-        return NextResponse.json(
-          {
-            error: 'Service Unavailable',
-            message: 'Authentication service is not properly configured',
-            code: 'AUTH_NOT_INITIALIZED'
-          },
-          { status: 503 }
-        );
-      }
-    }
-
-    // Double-check after initialization attempt
-    if (isInitializationFailed()) {
-      console.error('[API Viability] Initialization failed - returning 503');
-      return NextResponse.json(
-        {
-          error: 'Service Unavailable',
-          message: 'Authentication service is not properly configured',
-          code: 'AUTH_NOT_INITIALIZED'
-        },
-        { status: 503 }
-      );
-    }
-
-    // Get session from Better Auth
-    const betterAuthSession = await getSession(req);
-
-    // Debug logging
-    if (!betterAuthSession) {
-      console.warn('[VIABILITY] getSession returned null');
-    }
-
-    const sessionToken = betterAuthSession?.session?.token as string | undefined;
-    if (betterAuthSession && sessionToken) {
-      // Try legacy session store first, then Better Auth format
-      let sessionData = await getRedisSession(sessionToken);
-      if (!sessionData) {
-        // Better Auth stores sessions with ba:{appSlug}:{token} prefix
-        sessionData = await getBetterAuthSession(sessionToken);
-        if (sessionData) {
-          console.log('[VIABILITY] Found session in Better Auth store');
-        }
-      }
-      if (sessionData) {
-        // The session exists in Redis
-
-        // Check if access token is expired (for middleware decision-making)
-        const accessTokenExpires = sessionData.idpAccessTokenExpires || 0;
-        const accessTokenExpired = accessTokenExpires < Date.now();
-
-        // Get requires2FA from cached client config (client-wide setting)
-        let requires2FA = true; // Default to true for security
-        try {
-          const cachedConfig = await getIDPClientConfig();
-          requires2FA = cachedConfig.authSettings?.require2FA ?? true;
-        } catch (e) {
-          console.warn('[API Viability] Could not get client config, defaulting requires2FA to true');
-        }
-
-        // CRITICAL: OAuth sessions without refresh token always need 2FA completion
-        // to obtain a refresh token from the IDP. The OAuth callback sets mfaVerified=false
-        // when no refresh_token is present. This must override the client config.
-        if (sessionData.mfaVerified === false && !sessionData.idpRefreshToken) {
-          requires2FA = true;
-        }
-
-        // CRITICAL: Check if MFA has expired (2FA TTL enforcement)
-        // The session may have mfaVerified=true from days ago, but if mfaExpiresAt
-        // has passed, we must treat 2FA as incomplete to force re-verification.
-        const mfaExpiresAt = sessionData.mfaExpiresAt || 0;
-        const mfaExpired = mfaExpiresAt > 0 && mfaExpiresAt < Date.now();
-        // Check both field names for compatibility (mfaVerified is the normalized name)
-        const sessionMfaComplete = sessionData.mfaVerified ?? (sessionData as any).twoFactorComplete ?? false;
-        const effectiveTwoFactorComplete = sessionMfaComplete && !mfaExpired;
-
-        console.log('[VIABILITY] Session 2FA check:', {
-          sessionToken: sessionToken.substring(0, 8) + '...',
-          mfaVerified: sessionData.mfaVerified,
-          twoFactorComplete: (sessionData as any).twoFactorComplete,
-          sessionMfaComplete,
-          mfaExpired,
-          effectiveTwoFactorComplete,
-        });
-
-        if (mfaExpired && sessionMfaComplete) {
-          console.warn('[API Viability] MFA expired - forcing 2FA re-verification', {
-            mfaExpiresAt: new Date(mfaExpiresAt).toISOString(),
-            now: new Date().toISOString(),
-            hoursExpiredAgo: ((Date.now() - mfaExpiresAt) / (1000 * 60 * 60)).toFixed(1)
-          });
-        }
-
-        const response = {
-          authenticated: true,
-          sessionToken, // Include token for middleware tracking
-          // 2FA fields - critical for middleware redirect logic
-          requires2FA, // From cached client config (client-wide setting)
-          twoFactorComplete: effectiveTwoFactorComplete, // From session, BUT respects MFA TTL
-          // Token status for refresh decisions
-          accessTokenExpired,
-          hasRefreshToken: !!sessionData.idpRefreshToken
-        };
-        return NextResponse.json(response);
-      }
-
-      // CRITICAL: Cookie exists but Redis session is missing (stale cookie state)
-      // Return sessionToken so middleware can detect this and clear the stale cookie
-      console.warn('[VIABILITY] Stale cookie detected - session not in Redis');
-      return NextResponse.json({
-        authenticated: false,
-        sessionToken // Include token to enable stale cookie detection
-      });
-    }
-
-    // If there's no token at all, it's not authenticated
-    return NextResponse.json({ authenticated: false });
-
-  } catch (error) {
-    console.error('[API Viability] Error checking session viability:', error);
-    return NextResponse.json({ authenticated: false }, { status: 500 });
-  }
+/**
+ * Session Viability Check API Handler for `@payez/next-mvp`
+ *
+ * This API route is called by the middleware to securely check if a session is valid.
+ */
+
+import { NextRequest, NextResponse } from 'next/server';
+import { getSession as getRedisSession, getBetterAuthSession } from '../../lib/session-store';
+import { getSession } from '../../server/auth';
+import { isInitializationFailed, ensureInitialized } from '../../lib/startup-init';
+import { getIDPClientConfig } from '../../lib/idp-client-config';
+
+export async function GET(req: NextRequest) {
+  try {
+    // Ensure initialization is complete (auth signing secret resolved from IDP)
+    if (!process.env.BETTER_AUTH_SECRET && !process.env.NEXTAUTH_SECRET) {
+      try {
+        await ensureInitialized();
+      } catch (error) {
+        // Initialization failed - return 503
+        console.error('[API Viability] Initialization failed - returning 503');
+        return NextResponse.json(
+          {
+            error: 'Service Unavailable',
+            message: 'Authentication service is not properly configured',
+            code: 'AUTH_NOT_INITIALIZED'
+          },
+          { status: 503 }
+        );
+      }
+    }
+
+    // Double-check after initialization attempt
+    if (isInitializationFailed()) {
+      console.error('[API Viability] Initialization failed - returning 503');
+      return NextResponse.json(
+        {
+          error: 'Service Unavailable',
+          message: 'Authentication service is not properly configured',
+          code: 'AUTH_NOT_INITIALIZED'
+        },
+        { status: 503 }
+      );
+    }
+
+    // Get session from Better Auth
+    const betterAuthSession = await getSession(req);
+
+    // Debug logging
+    if (!betterAuthSession) {
+      console.warn('[VIABILITY] getSession returned null');
+    }
+
+    const sessionToken = betterAuthSession?.session?.token as string | undefined;
+    if (betterAuthSession && sessionToken) {
+      // Try legacy session store first, then Better Auth format
+      let sessionData = await getRedisSession(sessionToken);
+      if (!sessionData) {
+        // Better Auth stores sessions with ba:{appSlug}:{token} prefix
+        sessionData = await getBetterAuthSession(sessionToken);
+        if (sessionData) {
+          console.log('[VIABILITY] Found session in Better Auth store');
+        }
+      }
+      if (sessionData) {
+        // The session exists in Redis
+
+        // Check if access token is expired (for middleware decision-making)
+        const accessTokenExpires = sessionData.idpAccessTokenExpires || 0;
+        const accessTokenExpired = accessTokenExpires < Date.now();
+
+        // Get requires2FA from cached client config (client-wide setting)
+        let requires2FA = true; // Default to true for security
+        try {
+          const cachedConfig = await getIDPClientConfig();
+          requires2FA = cachedConfig.authSettings?.require2FA ?? true;
+        } catch (e) {
+          console.warn('[API Viability] Could not get client config, defaulting requires2FA to true');
+        }
+
+        // CRITICAL: OAuth sessions without refresh token always need 2FA completion
+        // to obtain a refresh token from the IDP. The OAuth callback sets mfaVerified=false
+        // when no refresh_token is present. This must override the client config.
+        if (sessionData.mfaVerified === false && !sessionData.idpRefreshToken) {
+          requires2FA = true;
+        }
+
+        // CRITICAL: Check if MFA has expired (2FA TTL enforcement)
+        // The session may have mfaVerified=true from days ago, but if mfaExpiresAt
+        // has passed, we must treat 2FA as incomplete to force re-verification.
+        const mfaExpiresAt = sessionData.mfaExpiresAt || 0;
+        const mfaExpired = mfaExpiresAt > 0 && mfaExpiresAt < Date.now();
+        // Check both field names for compatibility (mfaVerified is the normalized name)
+        const sessionMfaComplete = sessionData.mfaVerified ?? (sessionData as any).twoFactorComplete ?? false;
+        const effectiveTwoFactorComplete = sessionMfaComplete && !mfaExpired;
+
+        console.log('[VIABILITY] Session 2FA check:', {
+          sessionToken: sessionToken.substring(0, 8) + '...',
+          mfaVerified: sessionData.mfaVerified,
+          twoFactorComplete: (sessionData as any).twoFactorComplete,
+          sessionMfaComplete,
+          mfaExpired,
+          effectiveTwoFactorComplete,
+        });
+
+        if (mfaExpired && sessionMfaComplete) {
+          console.warn('[API Viability] MFA expired - forcing 2FA re-verification', {
+            mfaExpiresAt: new Date(mfaExpiresAt).toISOString(),
+            now: new Date().toISOString(),
+            hoursExpiredAgo: ((Date.now() - mfaExpiresAt) / (1000 * 60 * 60)).toFixed(1)
+          });
+        }
+
+        const response = {
+          authenticated: true,
+          sessionToken, // Include token for middleware tracking
+          // 2FA fields - critical for middleware redirect logic
+          requires2FA, // From cached client config (client-wide setting)
+          twoFactorComplete: effectiveTwoFactorComplete, // From session, BUT respects MFA TTL
+          // Cards 141688/141741 — the IDP's routing decision, relayed verbatim.
+          //
+          // THIS IS THE SECOND IMPLEMENTATION OF VIABILITY. The other is
+          // routes/auth/viability.ts, which is what the admin graft mounts.
+          // Both are publicly exported entry points, so both can be a consumer's
+          // only source of this answer. Adding the relay to just one would leave
+          // an app that mounts THIS one still blind to enroll_mfa — the exact
+          // seam these cards are about, reopened one export over.
+          //
+          // 'enroll_mfa' = no USABLE method, the user cannot complete a
+          // challenge. 'mfa_verify' = usable method exists. null = nothing due.
+          // NOT a completion signal: twoFactorComplete still owns that.
+          //
+          // No `?? null`: undefined (never captured — every session minted
+          // before this change) must stay distinguishable from null (the IDP
+          // said nothing is outstanding). Defaulting to null would tell the
+          // gate that every pre-existing session is fully authenticated,
+          // including zero-method users who must be routed to enrol.
+          nextStep: sessionData.nextStep,
+          // Token status for refresh decisions
+          accessTokenExpired,
+          hasRefreshToken: !!sessionData.idpRefreshToken
+        };
+        return NextResponse.json(response);
+      }
+
+      // CRITICAL: Cookie exists but Redis session is missing (stale cookie state)
+      // Return sessionToken so middleware can detect this and clear the stale cookie
+      console.warn('[VIABILITY] Stale cookie detected - session not in Redis');
+      return NextResponse.json({
+        authenticated: false,
+        sessionToken // Include token to enable stale cookie detection
+      });
+    }
+
+    // If there's no token at all, it's not authenticated
+    return NextResponse.json({ authenticated: false });
+
+  } catch (error) {
+    console.error('[API Viability] Error checking session viability:', error);
+    return NextResponse.json({ authenticated: false }, { status: 500 });
+  }
 }

package/src/auth/better-auth.ts

@@ -10,6 +10,8 @@
  */
 
 import 'server-only';
+import { AsyncLocalStorage } from 'node:async_hooks';
+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';
@@ -35,6 +37,31 @@ export interface BetterAuthSocialProvider {
 /**
  * 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 AsyncLocalStorage<{ idToken?: string }>();
+
 export function buildBetterAuthProviders(
   config: IDPClientConfig
 ): Record<string, BetterAuthSocialProvider> {
@@ -68,6 +95,66 @@ export function buildBetterAuthProviders(
       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] as unknown as Record<string, unknown>).getUserInfo = async (token: { idToken?: string }) => {
+        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 = decodeJwt(token.idToken) as Record<string, any>;
+        return {
+          user: {
+            id: claims.sub,
+            name: claims.name,
+            email: claims.email,
+            image: claims.picture,
+            emailVerified: claims.email_verified,
+          },
+          data: claims,
+        };
+      };
+    }
   }
 
   return providers;
@@ -84,6 +171,27 @@ export function buildBetterAuthProviders(
  */
 export interface CreateBetterAuthInstanceOptions {
   magicLink?: MagicLinkOptions;
+  /**
+   * Extra Better Auth plugins supplied by the consuming app.
+   *
+   * WHY THIS EXISTS — session minting is not delegable any other way. BA's
+   * `setSessionCookie` requires a `GenericEndpointContext`, which only BA's own
+   * endpoint machinery constructs, so an app that must mint a session for an
+   * identity established OUTSIDE BA's built-in providers (passkey sign-in being
+   * the first) cannot do it from a route handler. It needs a real BA endpoint,
+   * and endpoints only arrive via plugins.
+   *
+   * Deliberately GENERIC. The package gains "an app may supply plugins" rather
+   * than any knowledge of passkeys — the alternative was teaching this file
+   * about a specific auth method, which is how a package accumulates a consumer's
+   * feature list.
+   *
+   * The alternative to this option is an app hand-rolling the session cookie
+   * (`{token}.{base64(hmac)}`, standard padding, runtime `authSecret` from
+   * Redis). That fails as a session which DECODES BUT DOES NOT AUTHENTICATE —
+   * so this option exists specifically to make that shortcut unnecessary.
+   */
+  plugins?: Parameters<typeof betterAuth>[0]['plugins'];
 }
 
 /**
@@ -183,6 +291,9 @@ export function createBetterAuthInstance(
     plugins: [
       nextCookies(),
       ...(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.
+      ...(opts.plugins ?? []),
     ],
   });
 }
@@ -322,6 +433,30 @@ export async function exchangeOAuthForIdpTokens(
         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 } : {}),
       }),
     });
 
@@ -371,31 +506,130 @@ export async function exchangeOAuthForIdpTokens(
       image: image,
       roles: result.user?.roles || result.roles || [],
       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').
+ */
+export async function storeIdpTokensInSession(
+  sessionToken: string,
+  idpTokenData: Record<string, unknown>,
+  authProvider: string,
+): Promise<boolean> {
+  try {
+    const config = await getIDPClientConfig();
+    const appSlug = config.clientSlug || getAppSlug();
+    const baKey = `ba:${appSlug}:${sessionToken}`;
+
+    const baRaw = await 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 getRedis().setex(baKey, 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 import('../lib/app-slug');
       const canonicalKey = `${getSessionPrefix()}${sessionToken}`;
       await getRedis().setex(canonicalKey, 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;
   }
 }
@@ -419,6 +653,12 @@ export async function exchangeOAuthForIdpTokens(
  */
 export function createAuthGetHandler(loginPath: string = '/account-auth/login') {
   return async function GET(request: Request): Promise<Response> {
+    // 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 });
@@ -463,5 +703,6 @@ export function createAuthGetHandler(loginPath: string = '/account-auth/login')
     }
 
     return response;
+    });
   };
 }

package/src/auth/unauthenticated-routes.ts

@@ -1,3 +1,3 @@
-// src/auth/unauthenticated-routes.ts
-// Re-exporting from route-config for backward compatibility
+// src/auth/unauthenticated-routes.ts
+// Re-exporting from route-config for backward compatibility
 export * from './route-config';