@payez/next-mvp 4.1.10 → 4.1.11

package/dist/auth/better-auth.js

@@ -327,8 +327,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,7 +354,7 @@ async function exchangeOAuthForIdpTokens(sessionToken, provider = 'google') {
             name: result.user?.full_name || result.user?.name || result.name || name,
             image: image,
             roles: result.user?.roles || result.roles || [],
-            mfaVerified: !requiresTwoFactor,
+            mfaVerified: false, // Always false post-OAuth — see IDP-2FA-BUG note above
             idpClientId: result.client_id ? String(result.client_id) : undefined,
             merchantId: result.merchant_id ? String(result.merchant_id) : undefined,
         };

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: '',

package/dist/lib/token-lifecycle.d.ts

@@ -31,6 +31,8 @@ export interface TokenError {
     error: 'NO_SESSION' | 'NO_TOKEN' | 'EXPIRED' | 'REFRESH_FAILED' | 'SESSION_EXPIRED_NO_REFRESH';
     message: string;
     terminal?: boolean;
+    code?: string;
+    resolution?: string;
 }
 export type EnsureFreshTokenResult = TokenResult | TokenError;
 /**

package/dist/lib/token-lifecycle.js

@@ -150,7 +150,16 @@ async function triggerRefresh(request, sessionToken, retryCount = 0) {
             // Don't retry - user must re-authenticate
             if (responseData.code === 'NO_REFRESH_TOKEN' || responseData.terminal === true) {
                 console.error('[TOKEN_LIFECYCLE] TERMINAL: Session has no refresh token - user must re-login');
-                return { success: false, terminal: true, code: responseData.code };
+                // WO-1: preserve the verbatim upstream reason. refresh.ts puts the human
+                // message in `error` and the code in `code`; carry both up so the consumer
+                // can tell the user WHY (not just "session expired") and stop a futile loop.
+                return {
+                    success: false,
+                    terminal: true,
+                    code: responseData.code,
+                    message: responseData.error,
+                    resolution: responseData.resolution,
+                };
             }
             // For other 401s, check if maybe session was refreshed by another request
             if (response.status === 401 && retryCount < maxRetries) {
@@ -318,12 +327,21 @@ async function ensureFreshToken(request) {
             if (!refreshResult.success) {
                 // Check for terminal state - session cannot be recovered
                 if (refreshResult.terminal) {
-                    console.error('[TOKEN_LIFECYCLE] TERMINAL: Session expired with no refresh token - redirect to login');
+                    console.error('[TOKEN_LIFECYCLE] TERMINAL: Session expired - redirect to login', {
+                        code: refreshResult.code,
+                        message: refreshResult.message,
+                    });
+                    // WO-1: keep `error` as the stable terminal category (existing consumers
+                    // branch on SESSION_EXPIRED_NO_REFRESH) but surface the verbatim upstream
+                    // reason via code/message/resolution so the user learns WHY and a genuinely
+                    // dead session (e.g. unapproved account) doesn't loop login→bounce→login.
                     return {
                         success: false,
                         error: 'SESSION_EXPIRED_NO_REFRESH',
-                        message: 'Session expired. Please sign in again.',
+                        message: refreshResult.message || 'Session expired. Please sign in again.',
                         terminal: true,
+                        code: refreshResult.code,
+                        resolution: refreshResult.resolution,
                     };
                 }
                 console.warn('[TOKEN_LIFECYCLE] Refresh failed');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@payez/next-mvp",
-  "version": "4.1.10",
+  "version": "4.1.11",
   "sideEffects": false,
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/auth/better-auth.ts

@@ -1,455 +1,467 @@
-/**
- * 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 { 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
+    // 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
+      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;
+  };
+}

package/src/lib/ensure-fresh-access-token.ts

@@ -206,8 +206,16 @@ export async function ensureFreshAccessToken(
       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: Record<string, unknown> = {
-      refresh_token: session.idpRefreshToken,
+      refresh_token: sentRefreshToken,
       amr: authMethods,
       acr: acrValue,
     };
@@ -255,8 +263,11 @@ export async function ensureFreshAccessToken(
         // (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 getSession(sessionToken);
+        // 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 =
-          !!session.idpRefreshToken && postRefresh?.idpRefreshToken === session.idpRefreshToken;
+          !!sentRefreshToken && postRefresh?.idpRefreshToken === sentRefreshToken;
         if (tokenUnchanged) {
           await updateSession(sessionToken, {
             idpRefreshToken: '',

package/src/lib/token-lifecycle.ts

@@ -46,6 +46,13 @@ export interface TokenError {
   error: 'NO_SESSION' | 'NO_TOKEN' | 'EXPIRED' | 'REFRESH_FAILED' | 'SESSION_EXPIRED_NO_REFRESH';
   message: string;
   terminal?: boolean;  // If true, don't retry - redirect to login
+  // WO-1 (genuine-dead refresh): the VERBATIM upstream reason from the IDP, preserved
+  // end-to-end so the consumer can surface an honest error + halt a futile re-auth loop
+  // (e.g. an unapproved user whose login mints a bearer but whose refresh terminally
+  // fails). `error` stays the stable category for existing consumers; `code`/`resolution`
+  // carry the real cause. Never soften — surface it.
+  code?: string;        // Upstream IDP error code (e.g. UNAUTHORIZED, USER_NOT_APPROVED)
+  resolution?: string;  // Upstream human-readable resolution hint, if any
 }
 
 export type EnsureFreshTokenResult = TokenResult | TokenError;
@@ -123,6 +130,8 @@ interface RefreshResult {
   success: boolean;
   terminal?: boolean;  // If true, session is dead - don't retry, redirect to login
   code?: string;       // Error code from refresh endpoint
+  message?: string;    // WO-1: verbatim human message from the refresh endpoint
+  resolution?: string; // WO-1: verbatim resolution hint from the refresh endpoint
 }
 
 /**
@@ -201,7 +210,16 @@ async function triggerRefresh(
       // Don't retry - user must re-authenticate
       if (responseData.code === 'NO_REFRESH_TOKEN' || responseData.terminal === true) {
         console.error('[TOKEN_LIFECYCLE] TERMINAL: Session has no refresh token - user must re-login');
-        return { success: false, terminal: true, code: responseData.code };
+        // WO-1: preserve the verbatim upstream reason. refresh.ts puts the human
+        // message in `error` and the code in `code`; carry both up so the consumer
+        // can tell the user WHY (not just "session expired") and stop a futile loop.
+        return {
+          success: false,
+          terminal: true,
+          code: responseData.code,
+          message: responseData.error,
+          resolution: responseData.resolution,
+        };
       }
 
       // For other 401s, check if maybe session was refreshed by another request
@@ -388,12 +406,21 @@ export async function ensureFreshToken(
       if (!refreshResult.success) {
         // Check for terminal state - session cannot be recovered
         if (refreshResult.terminal) {
-          console.error('[TOKEN_LIFECYCLE] TERMINAL: Session expired with no refresh token - redirect to login');
+          console.error('[TOKEN_LIFECYCLE] TERMINAL: Session expired - redirect to login', {
+            code: refreshResult.code,
+            message: refreshResult.message,
+          });
+          // WO-1: keep `error` as the stable terminal category (existing consumers
+          // branch on SESSION_EXPIRED_NO_REFRESH) but surface the verbatim upstream
+          // reason via code/message/resolution so the user learns WHY and a genuinely
+          // dead session (e.g. unapproved account) doesn't loop login→bounce→login.
           return {
             success: false,
             error: 'SESSION_EXPIRED_NO_REFRESH',
-            message: 'Session expired. Please sign in again.',
+            message: refreshResult.message || 'Session expired. Please sign in again.',
             terminal: true,
+            code: refreshResult.code,
+            resolution: refreshResult.resolution,
           };
         }