fix(better-auth): 2FA cookie handling and test infrastructure

- Fix 2FA sign-in to use native Better Auth handler for cookie handling
- When 2FA is required, forward to native handler to ensure session cookie is set
- Add returnResponse option to TestHelper for header inspection
- Add critical test: validates Set-Cookie header with two_factor token
- Update migration guide with 2FA cookie bugfix documentation

This commit preserves the current working state before refactoring
to use Better Auth hooks for cleaner architecture.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: kaihaase

migration-guides/11.9.x-to-11.10.x.md

@@ -181,6 +181,28 @@ Additionally, new endpoints are available for backup codes.
 
 ---
 
+## Bugfixes
+
+### 2FA Session Token Cookie Handling
+
+**Fixed Issue:** When signing in with 2FA enabled, the temporary session token was not being set as a cookie. This caused the 2FA verification step (`/iam/two-factor/verify-totp`) to fail with 401 Unauthorized because the browser couldn't authenticate the request.
+
+**What was happening:**
+1. User signs in with email/password
+2. Server returns `requiresTwoFactor: true` but no cookie was set
+3. User enters TOTP code
+4. Request fails because there's no session token to identify the 2FA flow
+
+**What's fixed:**
+1. User signs in with email/password
+2. Server returns `requiresTwoFactor: true` AND sets the temporary session token as a cookie
+3. User enters TOTP code
+4. Browser automatically sends the session cookie → verification succeeds
+
+**No action required** - this is a bugfix that improves 2FA functionality without requiring any code changes.
+
+---
+
 ## Detailed Migration Steps
 
 ### Step 1: Update Package

package-lock.json

@@ -80,7 +80,7 @@
   "dependencies": {
     "@apollo/server": "5.2.0",
     "@as-integrations/express5": "1.1.2",
-    "@better-auth/passkey": "1.4.8-beta.4",
+    "@better-auth/passkey": "^1.4.16",
     "@getbrevo/brevo": "3.0.1",
     "@nestjs/apollo": "13.2.3",
     "@nestjs/common": "11.1.9",
@@ -98,7 +98,7 @@
     "@tus/server": "2.3.0",
     "apollo-server-core": "3.13.0",
     "bcrypt": "6.0.0",
-    "better-auth": "1.4.8-beta.4",
+    "better-auth": "^1.4.16",
     "class-transformer": "0.5.1",
     "class-validator": "0.14.3",
     "compression": "1.8.1",
@@ -147,6 +147,7 @@
     "@typescript-eslint/parser": "8.50.0",
     "@vitest/coverage-v8": "4.0.16",
     "@vitest/ui": "4.0.16",
+    "otpauth": "9.4.1",
     "ansi-colors": "4.1.3",
     "eslint": "9.39.2",
     "eslint-config-prettier": "10.1.8",

package.json

@@ -19,9 +19,9 @@ import { EmailService } from './core/common/services/email.service';
 import { MailjetService } from './core/common/services/mailjet.service';
 import { ModelDocService } from './core/common/services/model-doc.service';
 import { TemplateService } from './core/common/services/template.service';
-import { BetterAuthUserMapper } from './core/modules/better-auth/better-auth-user.mapper';
-import { BetterAuthModule } from './core/modules/better-auth/better-auth.module';
-import { BetterAuthService } from './core/modules/better-auth/better-auth.service';
+import { CoreBetterAuthUserMapper } from './core/modules/better-auth/core-better-auth-user.mapper';
+import { CoreBetterAuthModule } from './core/modules/better-auth/core-better-auth.module';
+import { CoreBetterAuthService } from './core/modules/better-auth/core-better-auth.service';
 import { ErrorCodeModule } from './core/modules/error-code/error-code.module';
 import { CoreHealthCheckModule } from './core/modules/health-check/core-health-check.module';
 
@@ -86,8 +86,8 @@ export class CoreModule implements NestModule {
    *
    * **Requirements:**
    * - Configure `betterAuth` in your config (enabled by default)
-   * - Create BetterAuthModule, Resolver, and Controller in your project
-   * - Inject BetterAuthUserMapper in UserService
+   * - Create CoreBetterAuthModule, Resolver, and Controller in your project
+   * - Inject CoreBetterAuthUserMapper in UserService
    *
    * ### Legacy + IAM Signature (For existing projects)
    *
@@ -246,8 +246,8 @@ export class CoreModule implements NestModule {
       imports.push(CoreHealthCheckModule);
     }
 
-    // Add BetterAuthModule based on mode
-    // IAM-only mode: Always register BetterAuthModule (required for subscription auth)
+    // Add CoreBetterAuthModule based on mode
+    // IAM-only mode: Always register CoreBetterAuthModule (required for subscription auth)
     // Legacy mode: Only register if autoRegister is explicitly true
     // betterAuth can be: boolean | IBetterAuth | undefined
     const betterAuthConfig = config.betterAuth;
@@ -258,7 +258,7 @@ export class CoreModule implements NestModule {
     if (isBetterAuthEnabled) {
       if (isIamOnlyMode || isAutoRegister) {
         imports.push(
-          BetterAuthModule.forRoot({
+          CoreBetterAuthModule.forRoot({
             config: betterAuthConfig === true ? {} : betterAuthConfig || {},
             // Pass JWT secrets for backwards compatibility fallback
             fallbackSecrets: [config.jwt?.secret, config.jwt?.refresh?.secret],
@@ -289,14 +289,14 @@ export class CoreModule implements NestModule {
   /**
    * Build GraphQL driver configuration for IAM-only mode
    *
-   * Uses BetterAuthService for subscription authentication via JWT tokens.
+   * Uses CoreBetterAuthService for subscription authentication via JWT tokens.
    * This is the recommended mode for new projects.
    */
   private static buildIamOnlyGraphQlDriver(cors: object, options: Partial<IServerOptions>) {
     return {
-      imports: [BetterAuthModule],
-      inject: [BetterAuthService, BetterAuthUserMapper],
-      useFactory: async (betterAuthService: BetterAuthService, userMapper: BetterAuthUserMapper) =>
+      imports: [CoreBetterAuthModule],
+      inject: [CoreBetterAuthService, CoreBetterAuthUserMapper],
+      useFactory: async (betterAuthService: CoreBetterAuthService, userMapper: CoreBetterAuthUserMapper) =>
         Object.assign(
           {
             autoSchemaFile: 'schema.gql',

src/core.module.ts

@@ -6,7 +6,7 @@ import { Connection, Types } from 'mongoose';
 import { firstValueFrom, isObservable } from 'rxjs';
 
 import { RoleEnum } from '../../../common/enums/role.enum';
-import { BetterAuthService } from '../../better-auth/better-auth.service';
+import { CoreBetterAuthService } from '../../better-auth/core-better-auth.service';
 import { ErrorCode } from '../../error-code';
 import { AuthGuardStrategy } from '../auth-guard-strategy.enum';
 import { ExpiredTokenException } from '../exceptions/expired-token.exception';
@@ -36,7 +36,7 @@ import { AuthGuard } from './auth.guard';
 @Injectable()
 export class RolesGuard extends AuthGuard(AuthGuardStrategy.JWT) {
   private readonly logger = new Logger(RolesGuard.name);
-  private betterAuthService: BetterAuthService | null = null;
+  private betterAuthService: CoreBetterAuthService | null = null;
   private mongoConnection: Connection | null = null;
   private servicesResolved = false;
 
@@ -59,7 +59,7 @@ export class RolesGuard extends AuthGuard(AuthGuardStrategy.JWT) {
     }
 
     try {
-      this.betterAuthService = this.moduleRef.get(BetterAuthService, { strict: false });
+      this.betterAuthService = this.moduleRef.get(CoreBetterAuthService, { strict: false });
     } catch {
       // BetterAuth not available - that's fine, we'll use Legacy JWT only
     }
@@ -168,6 +168,47 @@ export class RolesGuard extends AuthGuard(AuthGuardStrategy.JWT) {
         token = authHeader.substring(7);
       }
 
+      // If no token in header, try cookies (for REST endpoints)
+      if (!token) {
+        let cookies: Record<string, string> | undefined;
+
+        // Try GraphQL context first
+        try {
+          const gqlContext = GqlExecutionContext.create(context);
+          const ctx = gqlContext.getContext();
+          if (ctx?.req?.cookies) {
+            cookies = ctx.req.cookies;
+          }
+        } catch {
+          // GraphQL context not available
+        }
+
+        // Fallback to HTTP context
+        if (!cookies) {
+          try {
+            const httpRequest = context.switchToHttp().getRequest();
+            if (httpRequest?.cookies) {
+              cookies = httpRequest.cookies;
+            }
+          } catch {
+            // HTTP context not available
+          }
+        }
+
+        // Extract session token from cookies (try multiple cookie names)
+        if (cookies) {
+          // Get the basePath for cookie name (e.g., 'iam' -> 'iam.session_token')
+          const basePath = this.betterAuthService.getBasePath?.()?.replace(/^\//, '').replace(/\//g, '.') || 'iam';
+          const basePathCookie = `${basePath}.session_token`;
+
+          token =
+            cookies[basePathCookie] ||
+            cookies['better-auth.session_token'] ||
+            cookies['token'] ||
+            undefined;
+        }
+      }
+
       if (!token) {
         return null;
       }