@payez/next-mvp 4.1.10 → 4.1.20

package/src/auth/better-auth.ts

@@ -1,455 +1,708 @@
-/**
- * Better Auth Configuration
- *
- * Primary auth configuration. Replaces the former NextAuth auth-options.ts.
- *
- * Architecture: No database adapter — Better Auth runs in stateless mode
- * with JWE cookie cache. User management stays on IDP, sessions on Redis.
- *
- * @see BETTER-AUTH-MIGRATION-SPEC.md
- */
-
-import 'server-only';
-import { betterAuth } from 'better-auth';
-import { nextCookies } from 'better-auth/next-js';
-import { toNextJsHandler } from 'better-auth/next-js';
-import { magicLink, type MagicLinkOptions } from 'better-auth/plugins/magic-link';
-import type { IDPClientConfig } from '../lib/idp-client-config';
-import { getIDPClientConfig } from '../lib/idp-client-config';
-import { getAppSlug } from '../lib/app-slug';
-import { getRedis } from '../lib/redis';
-import { SESSION_TTL } from '../lib/session-store';
-
-/**
- * Better Auth social provider config shape.
- */
-export interface BetterAuthSocialProvider {
-  clientId: string;
-  clientSecret: string;
-  scope?: string[];
-  prompt?: string;
-  accessType?: 'offline' | 'online';
-  hd?: string;
-}
-
-/**
- * Build Better Auth social providers from IDP config.
- */
-export function buildBetterAuthProviders(
-  config: IDPClientConfig
-): Record<string, BetterAuthSocialProvider> {
-  const providers: Record<string, BetterAuthSocialProvider> = {};
-
-  for (const oauth of config.oauthProviders || []) {
-    if (!oauth.enabled) continue;
-    const name = oauth.provider.toLowerCase();
-    const additionalParams = oauth.additionalParams ?? {};
-    const rawPrompt = additionalParams.prompt;
-    const rawAccessType = additionalParams.accessType ?? additionalParams.access_type;
-    const rawHostedDomain = additionalParams.hd;
-
-    // Ensure profile scope is present for Google so avatar image is returned
-    const scopes = oauth.scopes?.split(' ') || [];
-    if (name === 'google' && !scopes.includes('profile')) {
-      scopes.push('profile');
-    }
-
-    providers[name] = {
-      clientId: oauth.clientId,
-      clientSecret: oauth.clientSecret,
-      scope: scopes.length > 0 ? scopes : undefined,
-      // Google is overly eager to reuse the last account unless we
-      // explicitly ask for account selection on each social login.
-      prompt: typeof rawPrompt === 'string'
-        ? rawPrompt
-        : name === 'google'
-          ? 'select_account'
-          : undefined,
-      accessType: rawAccessType === 'online' ? 'online' : rawAccessType === 'offline' ? 'offline' : undefined,
-      hd: typeof rawHostedDomain === 'string' ? rawHostedDomain : undefined,
-    };
-  }
-
-  return providers;
-}
-
-/**
- * Optional configuration for `createBetterAuthInstance`.
- *
- * - `magicLink`: if provided, registers Better Auth's magic-link plugin.
- *   The host app supplies its own `sendMagicLink` callback — typically a
- *   fetch to its email service (e.g. ACP's `/v1/auth/magic-link/email`).
- *   Omit the `magicLink` key entirely to skip the plugin; the consuming
- *   app will not have a magic-link flow.
- */
-export interface CreateBetterAuthInstanceOptions {
-  magicLink?: MagicLinkOptions;
-}
-
-/**
- * Create Better Auth instance from IDP config.
- *
- * No database — runs in stateless mode with JWE cookie cache.
- * Call after getIDPClientConfig() resolves.
- */
-export function createBetterAuthInstance(
-  idpConfig: IDPClientConfig,
-  opts: CreateBetterAuthInstanceOptions = {}
-) {
-  const appSlug = idpConfig.clientSlug || getAppSlug();
-
-  // 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';
-
-  return betterAuth({
-    baseURL,
-    secret: idpConfig.authSecret as string,
-
-    socialProviders: buildBetterAuthProviders(idpConfig),
-
-    // Trust the app's own origin + any configured base URL
-    trustedOrigins: [
-      rawBaseURL,
-      baseURL,
-      ...(idpConfig.baseClientUrl ? [idpConfig.baseClientUrl] : []),
-      'http://localhost:3000',
-      'http://localhost:3400',
-      'http://localhost:3600',
-    ],
-
-    // Redis-backed session storage via secondaryStorage
-    secondaryStorage: {
-      get: async (key: string) => {
-        try {
-          return await getRedis().get(`ba:${appSlug}:${key}`);
-        } catch { return null; }
-      },
-      set: async (key: string, value: string, ttl?: number) => {
-        try {
-          const redis = getRedis();
-          if (ttl) {
-            await redis.setex(`ba:${appSlug}:${key}`, ttl, value);
-          } else {
-            await redis.setex(`ba:${appSlug}:${key}`, SESSION_TTL, value);
-          }
-        } catch { /* Redis unavailable — cookie cache still works */ }
-      },
-      delete: async (key: string) => {
-        try {
-          await getRedis().del(`ba:${appSlug}:${key}`);
-        } catch { /* ignore */ }
-      },
-    },
-
-    session: {
-      // Cookie cache DISABLED — Redis is canonical for session liveness.
-      //
-      // Previously: enabled with maxAge 300 + refreshCache false. That cached
-      // a decoded session in process memory for 5 minutes, bypassing Redis
-      // reads during the window. Consequence: if the canonical app session
-      // at `{slug}:{token}` was evicted, refreshed, or rotated mid-window,
-      // Better Auth's in-memory copy stayed alive — and callers got
-      // contradictory answers depending on whether they consulted Better
-      // Auth (alive per cache) or Redis (dead/rotated). Documented contradiction
-      // visible in production traces: viability 200 + idp-token 200 +
-      // getFreshIdpToken NO_SESSION terminal within milliseconds.
-      //
-      // Trade-off: every Better Auth getSession() call now incurs one Redis
-      // read on the secondary-storage path. Latency cost is acceptable
-      // (sub-ms in-region) and the alternative is duplicate Layer-1
-      // workarounds in every consumer app — already shipped in idealvibe.online
-      // at b6a91f6.
-      cookieCache: {
-        enabled: false,
-        maxAge: 300,
-        refreshCache: false,
-      },
-    },
-
-    // Cookie prefix must match slim-middleware expectations ({slug}.session-token)
-    advanced: {
-      cookiePrefix: appSlug,
-      cookies: {
-        session_token: {
-          name: `${appSlug}.session-token`,
-        },
-      },
-    },
-
-    plugins: [
-      nextCookies(),
-      ...(opts.magicLink ? [magicLink(opts.magicLink)] : []),
-    ],
-  });
-}
-
-/**
- * Better Auth is always enabled (NextAuth removed in 4.0).
- */
-export function isBetterAuthEnabled(): boolean {
-  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: any = null;
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-let initPromise: Promise<any> | null = null;
-let configuredOpts: CreateBetterAuthInstanceOptions = {};
-
-// Expose for server-side session access (decode-session.ts)
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export { cachedInstance as __betterAuthInstance };
-
-/**
- * Configure Better Auth instance options for this process.
- *
- * Must be called before the first auth request — before
- * `getBetterAuthInstance()` caches an instance. Typically called once at
- * app startup, e.g. from Next.js `instrumentation.ts` or an equivalent
- * server bootstrap hook.
- *
- * Throws if called after the instance has already been resolved: options
- * cannot be applied retroactively.
- */
-export function configureBetterAuth(opts: CreateBetterAuthInstanceOptions): void {
-  if (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;
-}
-
-export async function getBetterAuthInstance() {
-  if (cachedInstance) return cachedInstance;
-
-  if (!initPromise) {
-    initPromise = getIDPClientConfig(true).then(config => {
-      const instance = createBetterAuthInstance(config, configuredOpts);
-      cachedInstance = instance;
-      console.log('[BETTER_AUTH] Instance created for', config.clientSlug || config.clientId);
-      return instance;
-    });
-  }
-
-  return initPromise;
-}
-
-/**
- * Get flag-gated auth handler for Next.js route.
- *
- * When USE_BETTER_AUTH=true, returns Better Auth handlers.
- * Otherwise returns null (auth disabled).
- *
- * Usage in host app route:
- * ```ts
- * import { getBetterAuthHandler } from '@payez/next-mvp/auth/better-auth';
- *
- * export async function GET(req: Request) {
- *   const ba = await getBetterAuthHandler();
- *   if (ba) return ba.GET(req);
- * }
- * ```
- */
-export async function getBetterAuthHandler(): Promise<{ GET: (req: Request) => Promise<Response>; POST: (req: Request) => Promise<Response> } | null> {
-  if (!isBetterAuthEnabled()) return null;
-
-  const auth = await getBetterAuthInstance();
-  return toNextJsHandler(auth);
-}
-
-/**
- * Exchange OAuth identity for IDP tokens and store in the BA Redis session.
- *
- * Call this from the OAuth callback route AFTER better-auth has processed the
- * callback and created the session. Reads the session token from the Set-Cookie
- * header of the response to find the BA Redis key.
- *
- * This replaces the old databaseHooks approach which doesn't fire in stateless mode.
- */
-export async function exchangeOAuthForIdpTokens(
-  sessionToken: string,
-  provider: string = 'google'
-): Promise<boolean> {
-  try {
-    const config = await getIDPClientConfig();
-    const appSlug = config.clientSlug || getAppSlug();
-    const baKey = `ba:${appSlug}:${sessionToken}`;
-
-    // Read the BA session from Redis
-    const baRaw = await getRedis().get(baKey).catch(() => null);
-    if (!baRaw) {
-      console.warn('[BETTER_AUTH] exchangeOAuthForIdpTokens: session not found in Redis for token', sessionToken.substring(0, 10));
-      return false;
-    }
-
-    const baData = JSON.parse(baRaw);
-    const email = baData?.user?.email;
-    const name = baData?.user?.name;
-    const image = baData?.user?.image;
-    const baUserId = baData?.session?.userId || baData?.user?.id;
-
-    if (!email) {
-      console.warn('[BETTER_AUTH] exchangeOAuthForIdpTokens: no email in session');
-      return false;
-    }
-
-    // Call IDP oauth-callback
-    const idpUrl = process.env.IDP_URL || '';
-    if (!idpUrl) {
-      console.warn('[BETTER_AUTH] No IDP_URL configured, skipping token exchange');
-      return false;
-    }
-
-    console.log('[BETTER_AUTH] Exchanging OAuth identity for IDP tokens:', email);
-
-    const oauthRes = await fetch(`${idpUrl}/api/ExternalAuth/oauth-callback`, {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({
-        provider,
-        provider_account_id: email,  // Cross-System Identity Standard v1.1: always use verified email, never opaque session IDs
-        email,
-        name,
-        image,
-        client_id: config.clientSlug || String(config.clientId),
-      }),
-    });
-
-    const oauthResText = await oauthRes.text();
-    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);
-      return false;
-    }
-
-    let idpData: any;
-    try { idpData = JSON.parse(oauthResText); } catch { return false; }
-    const result = idpData?.data?.result || idpData?.data || idpData;
-
-    if (!result?.access_token) {
-      console.warn('[BETTER_AUTH] IDP oauth-callback returned no access_token. Keys:', Object.keys(result || {}));
-      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.
-    const hasRefreshToken = !!result.refresh_token;
-    const requiresTwoFactor = result.user?.requiresTwoFactor ?? result.requiresTwoFactor ?? !hasRefreshToken;
-    const idpTokenData = {
-      idpAccessToken: result.access_token,
-      idpRefreshToken: result.refresh_token,
-      idpAccessTokenExpires: result.expires_in
-        ? Date.now() + result.expires_in * 1000
-        : Date.now() + 15 * 60 * 1000,
-      userId: String(result.user?.user_id || result.user?.id || result.user_id || baUserId),
-      email: result.user?.email || result.email || email,
-      name: result.user?.full_name || result.user?.name || result.name || name,
-      image: image,
-      roles: result.user?.roles || result.roles || [],
-      mfaVerified: !requiresTwoFactor,
-      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)
-    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.
-    try {
-      const { getSessionPrefix } = await import('../lib/app-slug');
-      const canonicalKey = `${getSessionPrefix()}${sessionToken}`;
-      await getRedis().setex(canonicalKey, SESSION_TTL, JSON.stringify({
-        ...idpTokenData,
-        oauthProvider: provider,
-      }));
-    } 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));
-    return false;
-  }
-}
-
-/**
- * Create a production-ready GET handler for the auth catch-all route.
- *
- * Wraps better-auth's GET handler with:
- * - OAuth state error recovery (redirects to login instead of error page)
- * - IDP token exchange after successful OAuth callback
- *
- * Usage in host app:
- * ```ts
- * import { createAuthGetHandler, getBetterAuthHandler } from '@payez/next-mvp/auth/better-auth';
- * export const GET = createAuthGetHandler('/account-auth/login');
- * export async function POST(req: Request) {
- *   const ba = await getBetterAuthHandler();
- *   return ba!.POST(req);
- * }
- * ```
- */
-export function createAuthGetHandler(loginPath: string = '/account-auth/login') {
-  return async function GET(request: Request): Promise<Response> {
-    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);
-      }
-    }
-
-    // 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: string) => 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: any) {
-        console.error('[BETTER_AUTH] IDP token exchange failed:', err.message);
-      }
-    }
-
-    return response;
-  };
-}
+/**
+ * Better Auth Configuration
+ *
+ * Primary auth configuration. Replaces the former NextAuth auth-options.ts.
+ *
+ * Architecture: No database adapter — Better Auth runs in stateless mode
+ * with JWE cookie cache. User management stays on IDP, sessions on Redis.
+ *
+ * @see BETTER-AUTH-MIGRATION-SPEC.md
+ */
+
+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';
+import { magicLink, type MagicLinkOptions } from 'better-auth/plugins/magic-link';
+import type { IDPClientConfig } from '../lib/idp-client-config';
+import { getIDPClientConfig } from '../lib/idp-client-config';
+import { getAppSlug } from '../lib/app-slug';
+import { getRedis } from '../lib/redis';
+import { SESSION_TTL } from '../lib/session-store';
+
+/**
+ * Better Auth social provider config shape.
+ */
+export interface BetterAuthSocialProvider {
+  clientId: string;
+  clientSecret: string;
+  scope?: string[];
+  prompt?: string;
+  accessType?: 'offline' | 'online';
+  hd?: string;
+}
+
+/**
+ * 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> {
+  const providers: Record<string, BetterAuthSocialProvider> = {};
+
+  for (const oauth of config.oauthProviders || []) {
+    if (!oauth.enabled) continue;
+    const name = oauth.provider.toLowerCase();
+    const additionalParams = oauth.additionalParams ?? {};
+    const rawPrompt = additionalParams.prompt;
+    const rawAccessType = additionalParams.accessType ?? additionalParams.access_type;
+    const rawHostedDomain = additionalParams.hd;
+
+    // Ensure profile scope is present for Google so avatar image is returned
+    const scopes = oauth.scopes?.split(' ') || [];
+    if (name === 'google' && !scopes.includes('profile')) {
+      scopes.push('profile');
+    }
+
+    providers[name] = {
+      clientId: oauth.clientId,
+      clientSecret: oauth.clientSecret,
+      scope: scopes.length > 0 ? scopes : undefined,
+      // Google is overly eager to reuse the last account unless we
+      // explicitly ask for account selection on each social login.
+      prompt: typeof rawPrompt === 'string'
+        ? rawPrompt
+        : name === 'google'
+          ? 'select_account'
+          : undefined,
+      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;
+}
+
+/**
+ * Optional configuration for `createBetterAuthInstance`.
+ *
+ * - `magicLink`: if provided, registers Better Auth's magic-link plugin.
+ *   The host app supplies its own `sendMagicLink` callback — typically a
+ *   fetch to its email service (e.g. ACP's `/v1/auth/magic-link/email`).
+ *   Omit the `magicLink` key entirely to skip the plugin; the consuming
+ *   app will not have a magic-link flow.
+ */
+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'];
+}
+
+/**
+ * Create Better Auth instance from IDP config.
+ *
+ * No database — runs in stateless mode with JWE cookie cache.
+ * Call after getIDPClientConfig() resolves.
+ */
+export function createBetterAuthInstance(
+  idpConfig: IDPClientConfig,
+  opts: CreateBetterAuthInstanceOptions = {}
+) {
+  const appSlug = idpConfig.clientSlug || getAppSlug();
+
+  // 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';
+
+  return betterAuth({
+    baseURL,
+    secret: idpConfig.authSecret as string,
+
+    socialProviders: buildBetterAuthProviders(idpConfig),
+
+    // Trust the app's own origin + any configured base URL
+    trustedOrigins: [
+      rawBaseURL,
+      baseURL,
+      ...(idpConfig.baseClientUrl ? [idpConfig.baseClientUrl] : []),
+      'http://localhost:3000',
+      'http://localhost:3400',
+      'http://localhost:3600',
+    ],
+
+    // Redis-backed session storage via secondaryStorage
+    secondaryStorage: {
+      get: async (key: string) => {
+        try {
+          return await getRedis().get(`ba:${appSlug}:${key}`);
+        } catch { return null; }
+      },
+      set: async (key: string, value: string, ttl?: number) => {
+        try {
+          const redis = getRedis();
+          if (ttl) {
+            await redis.setex(`ba:${appSlug}:${key}`, ttl, value);
+          } else {
+            await redis.setex(`ba:${appSlug}:${key}`, SESSION_TTL, value);
+          }
+        } catch { /* Redis unavailable — cookie cache still works */ }
+      },
+      delete: async (key: string) => {
+        try {
+          await getRedis().del(`ba:${appSlug}:${key}`);
+        } catch { /* ignore */ }
+      },
+    },
+
+    session: {
+      // Cookie cache DISABLED — Redis is canonical for session liveness.
+      //
+      // Previously: enabled with maxAge 300 + refreshCache false. That cached
+      // a decoded session in process memory for 5 minutes, bypassing Redis
+      // reads during the window. Consequence: if the canonical app session
+      // at `{slug}:{token}` was evicted, refreshed, or rotated mid-window,
+      // Better Auth's in-memory copy stayed alive — and callers got
+      // contradictory answers depending on whether they consulted Better
+      // Auth (alive per cache) or Redis (dead/rotated). Documented contradiction
+      // visible in production traces: viability 200 + idp-token 200 +
+      // getFreshIdpToken NO_SESSION terminal within milliseconds.
+      //
+      // Trade-off: every Better Auth getSession() call now incurs one Redis
+      // read on the secondary-storage path. Latency cost is acceptable
+      // (sub-ms in-region) and the alternative is duplicate Layer-1
+      // workarounds in every consumer app — already shipped in idealvibe.online
+      // at b6a91f6.
+      cookieCache: {
+        enabled: false,
+        maxAge: 300,
+        refreshCache: false,
+      },
+    },
+
+    // Cookie prefix must match slim-middleware expectations ({slug}.session-token)
+    advanced: {
+      cookiePrefix: appSlug,
+      cookies: {
+        session_token: {
+          name: `${appSlug}.session-token`,
+        },
+      },
+    },
+
+    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 ?? []),
+    ],
+  });
+}
+
+/**
+ * Better Auth is always enabled (NextAuth removed in 4.0).
+ */
+export function isBetterAuthEnabled(): boolean {
+  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: any = null;
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let initPromise: Promise<any> | null = null;
+let configuredOpts: CreateBetterAuthInstanceOptions = {};
+
+// Expose for server-side session access (decode-session.ts)
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export { cachedInstance as __betterAuthInstance };
+
+/**
+ * Configure Better Auth instance options for this process.
+ *
+ * Must be called before the first auth request — before
+ * `getBetterAuthInstance()` caches an instance. Typically called once at
+ * app startup, e.g. from Next.js `instrumentation.ts` or an equivalent
+ * server bootstrap hook.
+ *
+ * Throws if called after the instance has already been resolved: options
+ * cannot be applied retroactively.
+ */
+export function configureBetterAuth(opts: CreateBetterAuthInstanceOptions): void {
+  if (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;
+}
+
+export async function getBetterAuthInstance() {
+  if (cachedInstance) return cachedInstance;
+
+  if (!initPromise) {
+    initPromise = getIDPClientConfig(true).then(config => {
+      const instance = createBetterAuthInstance(config, configuredOpts);
+      cachedInstance = instance;
+      console.log('[BETTER_AUTH] Instance created for', config.clientSlug || config.clientId);
+      return instance;
+    });
+  }
+
+  return initPromise;
+}
+
+/**
+ * Get flag-gated auth handler for Next.js route.
+ *
+ * When USE_BETTER_AUTH=true, returns Better Auth handlers.
+ * Otherwise returns null (auth disabled).
+ *
+ * Usage in host app route:
+ * ```ts
+ * import { getBetterAuthHandler } from '@payez/next-mvp/auth/better-auth';
+ *
+ * export async function GET(req: Request) {
+ *   const ba = await getBetterAuthHandler();
+ *   if (ba) return ba.GET(req);
+ * }
+ * ```
+ */
+export async function getBetterAuthHandler(): Promise<{ GET: (req: Request) => Promise<Response>; POST: (req: Request) => Promise<Response> } | null> {
+  if (!isBetterAuthEnabled()) return null;
+
+  const auth = await getBetterAuthInstance();
+  return toNextJsHandler(auth);
+}
+
+/**
+ * Exchange OAuth identity for IDP tokens and store in the BA Redis session.
+ *
+ * Call this from the OAuth callback route AFTER better-auth has processed the
+ * callback and created the session. Reads the session token from the Set-Cookie
+ * header of the response to find the BA Redis key.
+ *
+ * This replaces the old databaseHooks approach which doesn't fire in stateless mode.
+ */
+export async function exchangeOAuthForIdpTokens(
+  sessionToken: string,
+  provider: string = 'google'
+): Promise<boolean> {
+  try {
+    const config = await getIDPClientConfig();
+    const appSlug = config.clientSlug || getAppSlug();
+    const baKey = `ba:${appSlug}:${sessionToken}`;
+
+    // Read the BA session from Redis
+    const baRaw = await getRedis().get(baKey).catch(() => null);
+    if (!baRaw) {
+      console.warn('[BETTER_AUTH] exchangeOAuthForIdpTokens: session not found in Redis for token', sessionToken.substring(0, 10));
+      return false;
+    }
+
+    const baData = JSON.parse(baRaw);
+    const email = baData?.user?.email;
+    const name = baData?.user?.name;
+    const image = baData?.user?.image;
+    const baUserId = baData?.session?.userId || baData?.user?.id;
+
+    if (!email) {
+      console.warn('[BETTER_AUTH] exchangeOAuthForIdpTokens: no email in session');
+      return false;
+    }
+
+    // Call IDP oauth-callback
+    const idpUrl = process.env.IDP_URL || '';
+    if (!idpUrl) {
+      console.warn('[BETTER_AUTH] No IDP_URL configured, skipping token exchange');
+      return false;
+    }
+
+    console.log('[BETTER_AUTH] Exchanging OAuth identity for IDP tokens:', email);
+
+    const oauthRes = await fetch(`${idpUrl}/api/ExternalAuth/oauth-callback`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        provider,
+        provider_account_id: email,  // Cross-System Identity Standard v1.1: always use verified email, never opaque session IDs
+        email,
+        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();
+    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);
+      return false;
+    }
+
+    let idpData: any;
+    try { idpData = JSON.parse(oauthResText); } catch { return false; }
+    const result = idpData?.data?.result || idpData?.data || idpData;
+
+    if (!result?.access_token) {
+      console.warn('[BETTER_AUTH] IDP oauth-callback returned no access_token. Keys:', Object.keys(result || {}));
+      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.
+    //
+    // 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 = {
+      idpAccessToken: result.access_token,
+      idpRefreshToken: result.refresh_token,
+      idpAccessTokenExpires: result.expires_in
+        ? Date.now() + result.expires_in * 1000
+        : Date.now() + 15 * 60 * 1000,
+      userId: String(result.user?.user_id || result.user?.id || result.user_id || baUserId),
+      email: result.user?.email || result.email || email,
+      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
+      // 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,
+    };
+
+    // 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));
+
+    // 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: authProvider,
+      }));
+    } catch (canonicalErr) {
+      console.warn('[BETTER_AUTH] Failed to write canonical session:', canonicalErr instanceof Error ? canonicalErr.message : String(canonicalErr));
+    }
+
+    return true;
+  } catch (err) {
+    console.error('[BETTER_AUTH] storeIdpTokensInSession failed:', err instanceof Error ? err.message : String(err));
+    return false;
+  }
+}
+
+/**
+ * Create a production-ready GET handler for the auth catch-all route.
+ *
+ * Wraps better-auth's GET handler with:
+ * - OAuth state error recovery (redirects to login instead of error page)
+ * - IDP token exchange after successful OAuth callback
+ *
+ * Usage in host app:
+ * ```ts
+ * import { createAuthGetHandler, getBetterAuthHandler } from '@payez/next-mvp/auth/better-auth';
+ * export const GET = createAuthGetHandler('/account-auth/login');
+ * export async function POST(req: Request) {
+ *   const ba = await getBetterAuthHandler();
+ *   return ba!.POST(req);
+ * }
+ * ```
+ */
+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 });
+    }
+
+    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);
+      }
+    }
+
+    // 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: string) => 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: any) {
+        console.error('[BETTER_AUTH] IDP token exchange failed:', err.message);
+      }
+    }
+
+    return response;
+    });
+  };
+}