From ca566494f54a4b1b2098ff51a46fb74c567eb5b3 Mon Sep 17 00:00:00 2001
From: Kai Haase <kai.haase@lenne.tech>
Date: Fri, 6 Feb 2026 01:17:44 +0100
Subject: [PATCH] 11.13.2: Add BetterAuthRolesGuard to fix DI issues with
 AuthGuard mixin in autoRegister:false mode

---
 .claude/rules/better-auth.md                  | 136 +++++
 migration-guides/11.12.x-to-11.13.0.md        |  16 +
 package-lock.json                             |   4 +-
 package.json                                  |   2 +-
 spectaql.yml                                  |   2 +-
 src/config.env.ts                             |  15 +-
 src/core.module.ts                            | 122 +++-
 .../interfaces/server-options.interface.ts    |  39 ++
 src/core/modules/auth/core-auth.module.ts     |  12 +-
 src/core/modules/auth/guards/roles.guard.ts   |  45 +-
 src/core/modules/better-auth/CUSTOMIZATION.md | 520 ++++++++++++++++++
 .../better-auth/INTEGRATION-CHECKLIST.md      |  15 +
 src/core/modules/better-auth/README.md        |  25 +-
 .../better-auth/better-auth-roles.guard.ts    | 205 +++++++
 .../core-better-auth-api.middleware.ts        |   6 +
 .../better-auth/core-better-auth.module.ts    |  95 +++-
 src/core/modules/better-auth/index.ts         |   1 +
 ...better-auth-autoregister-false.e2e-spec.ts | 230 ++++++++
 ...etter-auth-module-registration.e2e-spec.ts | 361 ++++++++++++
 19 files changed, 1824 insertions(+), 27 deletions(-)
 create mode 100644 src/core/modules/better-auth/CUSTOMIZATION.md
 create mode 100644 src/core/modules/better-auth/better-auth-roles.guard.ts
 create mode 100644 tests/stories/better-auth-autoregister-false.e2e-spec.ts
 create mode 100644 tests/stories/better-auth-module-registration.e2e-spec.ts

diff --git a/.claude/rules/better-auth.md b/.claude/rules/better-auth.md
index 1011f58..4832093 100644
--- a/.claude/rules/better-auth.md
+++ b/.claude/rules/better-auth.md
@@ -117,6 +117,140 @@ When changes affect existing test expectations:
 3. **Update test** to match new correct behavior
 4. **Document** why the test was changed in commit message
 
+## 4. Customization Patterns
+
+When a project needs custom BetterAuth behavior, follow these patterns:
+
+### Module Registration Patterns
+
+| Pattern | Use When | Configuration |
+|---------|----------|---------------|
+| **Zero-Config** | No customization needed | `CoreModule.forRoot(envConfig)` |
+| **Config-based** | Custom Controller/Resolver | `betterAuth: { controller, resolver }` in config |
+| **Separate Module** | Full control, additional providers | `betterAuth: { autoRegister: false }` |
+
+### Pattern Selection Decision Tree
+
+1. Does the project need custom Controller or Resolver?
+   - No → Use Zero-Config (Pattern 1)
+   - Yes → Continue to 2
+
+2. Does the project need additional providers or complex module structure?
+   - No → Use Config-based (Pattern 2) - add `controller`/`resolver` to `betterAuth` config
+   - Yes → Use Separate Module (Pattern 3) - set `autoRegister: false`
+
+### Critical: Resolver Decorator Re-declaration
+
+When customizing the Resolver, **ALL decorators MUST be re-declared**:
+
+```typescript
+// WRONG - method won't appear in GraphQL schema!
+override async betterAuthSignUp(...) {
+  return super.betterAuthSignUp(...);
+}
+
+// CORRECT - all decorators re-declared
+@Mutation(() => BetterAuthAuthModel)
+@Roles(RoleEnum.S_EVERYONE)
+override async betterAuthSignUp(...) {
+  return super.betterAuthSignUp(...);
+}
+```
+
+**Why:** GraphQL schema is built from decorators at compile time. Parent class is `isAbstract: true`.
+
+### Email Template Customization
+
+Templates are resolved in order:
+1. `<template>-<locale>.ejs` in project templates
+2. `<template>.ejs` in project templates
+3. `<template>-<locale>.ejs` in nest-server (fallback)
+4. `<template>.ejs` in nest-server (fallback)
+
+To override: Create `src/templates/email-verification-de.ejs` in the project.
+
+### Avoiding "forRoot() called twice" Warning
+
+If you see this warning, the project has duplicate registration:
+
+**Solutions:**
+1. Move `controller`/`resolver` to `config.betterAuth` (Pattern 2)
+2. Set `betterAuth.autoRegister: false` (Pattern 3)
+
+**See:** `src/core/modules/better-auth/CUSTOMIZATION.md` for complete documentation.
+
+## 5. RolesGuard Architecture
+
+### Two Guard Implementations
+
+The BetterAuth module provides two RolesGuard implementations:
+
+| Guard | Used In | Key Characteristics |
+|-------|---------|---------------------|
+| `RolesGuard` | Legacy + Hybrid Mode | Extends `AuthGuard(JWT)`, supports Passport |
+| `BetterAuthRolesGuard` | IAM-Only Mode | No Passport, no constructor dependencies |
+
+### Why BetterAuthRolesGuard Exists
+
+**Problem:** `AuthGuard()` from `@nestjs/passport` is a **mixin** that generates `design:paramtypes` metadata. When `RolesGuard extends AuthGuard(JWT)` is registered as `APP_GUARD` in a dynamic module (Pattern 3: `autoRegister: false`), NestJS DI fails to inject `Reflector` and `ModuleRef`.
+
+**Error:** `Reflector not available - RolesGuard cannot function without it`
+
+**Solution:** `BetterAuthRolesGuard` with NO constructor dependencies:
+
+```typescript
+@Injectable()
+export class BetterAuthRolesGuard implements CanActivate {
+  // NO constructor dependencies - avoids mixin DI conflict
+
+  async canActivate(context: ExecutionContext): Promise<boolean> {
+    // Use Reflect.getMetadata directly (not NestJS Reflector)
+    const roles = Reflect.getMetadata('roles', context.getHandler());
+
+    // Access services via static module reference
+    const tokenService = CoreBetterAuthModule.getTokenServiceInstance();
+
+    // ... role checking logic identical to RolesGuard
+  }
+}
+```
+
+### Guard Selection Logic
+
+In `CoreBetterAuthModule.createDeferredModule()`:
+
+```typescript
+// IAM-Only Mode: Use BetterAuthRolesGuard (no Passport dependency)
+providers: [
+  BetterAuthRolesGuard,
+  { provide: APP_GUARD, useExisting: BetterAuthRolesGuard },
+]
+```
+
+In `CoreAuthModule` (Legacy Mode):
+
+```typescript
+// Legacy Mode: Use RolesGuard (extends AuthGuard for Passport support)
+providers: [
+  { provide: APP_GUARD, useClass: RolesGuard },
+]
+```
+
+### Security Equivalence
+
+Both guards implement identical security logic:
+- Same `@Roles()` decorator processing
+- Same role checks (S_USER, S_EVERYONE, S_VERIFIED, S_SELF, S_CREATOR, S_NO_ONE)
+- Same token verification (via BetterAuthTokenService)
+- Same error responses (401 Unauthorized, 403 Forbidden)
+
+### When Working on Guards
+
+1. **Changes to role logic** → Update BOTH guards
+2. **New system roles** → Add to BOTH guards
+3. **Token verification changes** → Update `BetterAuthTokenService` (shared by both)
+4. **Testing** → Test both Legacy Mode and IAM-Only Mode
+
 ## Summary
 
 | Principle | Requirement |
@@ -124,3 +258,5 @@ When changes affect existing test expectations:
 | Standard Compliance | Stay close to Better-Auth, minimize custom code |
 | Security | Maximum security, thorough review before completion |
 | Testing | Full coverage, all tests pass, security tests included |
+| Customization | Use correct registration pattern, re-declare Resolver decorators |
+| Guards | Maintain both RolesGuard and BetterAuthRolesGuard in sync |
diff --git a/migration-guides/11.12.x-to-11.13.0.md b/migration-guides/11.12.x-to-11.13.0.md
index 9a759bb..cfdc816 100644
--- a/migration-guides/11.12.x-to-11.13.0.md
+++ b/migration-guides/11.12.x-to-11.13.0.md
@@ -581,11 +581,27 @@ Full reference for REST, GraphQL, and cookie-based testing:
 
 - **README:** [src/core/modules/better-auth/README.md](../src/core/modules/better-auth/README.md)
 - **Integration Checklist:** [src/core/modules/better-auth/INTEGRATION-CHECKLIST.md](../src/core/modules/better-auth/INTEGRATION-CHECKLIST.md)
+- **Customization Guide:** [src/core/modules/better-auth/CUSTOMIZATION.md](../src/core/modules/better-auth/CUSTOMIZATION.md)
 - **Reference Implementation:** `src/server/modules/iam/`
 - **Key Files:**
   - `core-better-auth-email-verification.service.ts` - Email verification logic and template resolution
   - `core-better-auth-signup-validator.service.ts` - Sign-up validation with configurable required fields
 
+### Module Registration Patterns
+
+When customizing BetterAuth, use the appropriate registration pattern:
+
+| Pattern | Use When | Configuration |
+|---------|----------|---------------|
+| **Zero-Config** | No customization | `CoreModule.forRoot(envConfig)` |
+| **Config-based** | Custom Controller/Resolver | `betterAuth: { controller, resolver }` |
+| **Separate Module** | Full control, additional providers | `betterAuth: { autoRegister: false }` |
+
+**See [CUSTOMIZATION.md](../src/core/modules/better-auth/CUSTOMIZATION.md) for detailed guidance on:**
+- Customizing Controller, Resolver, and Services
+- Email template customization (EJS and Brevo)
+- Avoiding the "forRoot() called twice" warning
+
 ---
 
 ## References
diff --git a/package-lock.json b/package-lock.json
index a1f55a4..e3cf9b4 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,12 +1,12 @@
 {
   "name": "@lenne.tech/nest-server",
-  "version": "11.13.1",
+  "version": "11.13.2",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@lenne.tech/nest-server",
-      "version": "11.13.1",
+      "version": "11.13.2",
       "license": "MIT",
       "dependencies": {
         "@apollo/server": "5.4.0",
diff --git a/package.json b/package.json
index 758598f..2b951aa 100755
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nest-server",
-  "version": "11.13.1",
+  "version": "11.13.2",
   "description": "Modern, fast, powerful Node.js web framework in TypeScript based on Nest with a GraphQL API and a connection to MongoDB (or other databases).",
   "keywords": [
     "node",
diff --git a/spectaql.yml b/spectaql.yml
index 06ffcd7..f449649 100644
--- a/spectaql.yml
+++ b/spectaql.yml
@@ -11,7 +11,7 @@ servers:
 info:
   title: lT Nest Server
   description: Modern, fast, powerful Node.js web framework in TypeScript based on Nest with a GraphQL API and a connection to MongoDB (or other databases).
-  version: 11.13.1
+  version: 11.13.2
   contact:
     name: lenne.Tech GmbH
     url: https://lenne.tech
diff --git a/src/config.env.ts b/src/config.env.ts
index da15d6f..0b39f97 100644
--- a/src/config.env.ts
+++ b/src/config.env.ts
@@ -265,11 +265,20 @@ const config: { [env: string]: IServerOptions } = {
     automaticObjectIdFiltering: true,
     baseUrl: process.env.BASE_URL,
     betterAuth: {
-      rateLimit: { enabled: process.env.RATE_LIMIT_ENABLED !== 'false', max: parseInt(process.env.RATE_LIMIT_MAX || '10', 10) },
+      rateLimit: {
+        enabled: process.env.RATE_LIMIT_ENABLED !== 'false',
+        max: parseInt(process.env.RATE_LIMIT_MAX || '10', 10),
+      },
       secret: process.env.BETTER_AUTH_SECRET,
       socialProviders: {
-        github: { clientId: process.env.SOCIAL_GITHUB_CLIENT_ID || '', clientSecret: process.env.SOCIAL_GITHUB_CLIENT_SECRET || '' },
-        google: { clientId: process.env.SOCIAL_GOOGLE_CLIENT_ID || '', clientSecret: process.env.SOCIAL_GOOGLE_CLIENT_SECRET || '' },
+        github: {
+          clientId: process.env.SOCIAL_GITHUB_CLIENT_ID || '',
+          clientSecret: process.env.SOCIAL_GITHUB_CLIENT_SECRET || '',
+        },
+        google: {
+          clientId: process.env.SOCIAL_GOOGLE_CLIENT_ID || '',
+          clientSecret: process.env.SOCIAL_GOOGLE_CLIENT_SECRET || '',
+        },
       },
       twoFactor: { appName: process.env.TWO_FACTOR_APP_NAME || 'Nest Server' },
     },
diff --git a/src/core.module.ts b/src/core.module.ts
index ef43534..0e6e342 100755
--- a/src/core.module.ts
+++ b/src/core.module.ts
@@ -137,9 +137,15 @@ export class CoreModule implements NestModule {
       };
     }
 
+    // Check if autoRegister: false for IAM-only mode (project imports its own BetterAuth module)
+    const rawBetterAuth = options?.betterAuth;
+    const isAutoRegisterDisabledEarly = typeof rawBetterAuth === 'object' && rawBetterAuth?.autoRegister === false;
+
     // Build GraphQL driver configuration based on auth mode
     const graphQlDriverConfig = isIamOnlyMode
-      ? this.buildIamOnlyGraphQlDriver(cors, options)
+      ? (isAutoRegisterDisabledEarly
+        ? this.buildLazyIamGraphQlDriver(cors, options)
+        : this.buildIamOnlyGraphQlDriver(cors, options))
       : this.buildLegacyGraphQlDriver(AuthService, AuthModule, cors, options);
 
     const config: IServerOptions = merge(
@@ -267,17 +273,27 @@ export class CoreModule implements NestModule {
       : isExplicitlyEnabled;
 
     const isAutoRegister = typeof betterAuthConfig === 'object' && betterAuthConfig?.autoRegister === true;
+    // autoRegister: false means the project imports its own BetterAuthModule separately
+    const isAutoRegisterDisabled = typeof betterAuthConfig === 'object' && betterAuthConfig?.autoRegister === false;
+
+    // Extract custom controller/resolver from config (Pattern 2: Config-based)
+    const configController = typeof betterAuthConfig === 'object' ? betterAuthConfig?.controller : undefined;
+    const configResolver = typeof betterAuthConfig === 'object' ? betterAuthConfig?.resolver : undefined;
 
     if (isBetterAuthEnabled) {
-      if (isIamOnlyMode || isAutoRegister) {
+      if ((isIamOnlyMode && !isAutoRegisterDisabled) || isAutoRegister) {
         imports.push(
           CoreBetterAuthModule.forRoot({
             config: betterAuthConfig === true ? {} : betterAuthConfig || {},
+            // Pass custom controller/resolver from config (Pattern 2)
+            controller: configController,
             // Pass JWT secrets for backwards compatibility fallback
             fallbackSecrets: [config.jwt?.secret, config.jwt?.refresh?.secret],
             // In IAM-only mode, register RolesGuard globally to enforce @Roles() decorators
             // In Legacy mode (autoRegister), RolesGuard is already registered via CoreAuthModule
             registerRolesGuardGlobally: isIamOnlyMode,
+            // Pass custom resolver from config (Pattern 2)
+            resolver: configResolver,
             // Pass server-level URLs for Passkey auto-detection
             // When env: 'local', defaults are: baseUrl=localhost:3000, appUrl=localhost:3001
             serverAppUrl: config.appUrl,
@@ -399,6 +415,108 @@ export class CoreModule implements NestModule {
     };
   }
 
+  /**
+   * Build a lazy GraphQL driver for IAM-only mode with autoRegister: false.
+   *
+   * When autoRegister: false, CoreBetterAuthModule is NOT imported by CoreModule,
+   * so we cannot use `imports` or `inject` to get BetterAuth services.
+   * Instead, we resolve them lazily via static getters on CoreBetterAuthModule.
+   * This is safe because `onConnect` is only called when a WebSocket connection is made,
+   * which happens after all modules are initialized.
+   */
+  private static buildLazyIamGraphQlDriver(cors: object, options: Partial<IServerOptions>) {
+    return {
+      useFactory: async () =>
+        Object.assign(
+          {
+            autoSchemaFile: 'schema.gql',
+            context: ({ req, res }) => ({ req, res }),
+            cors,
+            installSubscriptionHandlers: true,
+            subscriptions: {
+              'graphql-ws': {
+                context: ({ extra }) => extra,
+                onConnect: async (context: Context<any>) => {
+                  const { connectionParams, extra } = context;
+                  const enableAuth = options?.graphQl?.enableSubscriptionAuth ?? true;
+
+                  if (enableAuth) {
+                    const betterAuthService = CoreBetterAuthModule.getServiceInstance();
+                    const userMapper = CoreBetterAuthModule.getUserMapperInstance();
+
+                    if (!betterAuthService || !userMapper) {
+                      throw new UnauthorizedException('BetterAuth not initialized');
+                    }
+
+                    const headers = CoreModule.getHeaderFromArray(extra.request?.rawHeaders);
+                    const authToken: string =
+                      connectionParams?.Authorization?.split(' ')[1] ?? headers.Authorization?.split(' ')[1];
+
+                    if (authToken) {
+                      const { session, user: sessionUser } = await betterAuthService.getSession({
+                        headers: { authorization: `Bearer ${authToken}` },
+                      });
+
+                      if (!session || !sessionUser) {
+                        throw new UnauthorizedException('Invalid or expired session');
+                      }
+
+                      const user = await userMapper.mapSessionUser(sessionUser);
+                      if (!user) {
+                        throw new UnauthorizedException('User not found');
+                      }
+
+                      extra.user = user;
+                      extra.headers = connectionParams ?? headers;
+                      return extra;
+                    }
+
+                    throw new UnauthorizedException('Missing authentication token');
+                  }
+                },
+              },
+              'subscriptions-transport-ws': {
+                onConnect: async (connectionParams) => {
+                  const enableAuth = options?.graphQl?.enableSubscriptionAuth ?? true;
+
+                  if (enableAuth) {
+                    const betterAuthService = CoreBetterAuthModule.getServiceInstance();
+                    const userMapper = CoreBetterAuthModule.getUserMapperInstance();
+
+                    if (!betterAuthService || !userMapper) {
+                      throw new UnauthorizedException('BetterAuth not initialized');
+                    }
+
+                    const authToken: string = connectionParams?.Authorization?.split(' ')[1];
+
+                    if (authToken) {
+                      const { session, user: sessionUser } = await betterAuthService.getSession({
+                        headers: { authorization: `Bearer ${authToken}` },
+                      });
+
+                      if (!session || !sessionUser) {
+                        throw new UnauthorizedException('Invalid or expired session');
+                      }
+
+                      const user = await userMapper.mapSessionUser(sessionUser);
+                      if (!user) {
+                        throw new UnauthorizedException('User not found');
+                      }
+
+                      return { headers: connectionParams, user };
+                    }
+
+                    throw new UnauthorizedException('Missing authentication token');
+                  }
+                },
+              },
+            },
+          },
+          options?.graphQl?.driver,
+        ),
+    };
+  }
+
   /**
    * Build GraphQL driver configuration for Legacy Auth mode
    *
diff --git a/src/core/common/interfaces/server-options.interface.ts b/src/core/common/interfaces/server-options.interface.ts
index 7f4f26e..2005689 100644
--- a/src/core/common/interfaces/server-options.interface.ts
+++ b/src/core/common/interfaces/server-options.interface.ts
@@ -1,4 +1,5 @@
 import { ApolloDriverConfig } from '@nestjs/apollo';
+import { Type } from '@nestjs/common';
 import { GqlModuleAsyncOptions } from '@nestjs/graphql';
 import { JwtModuleOptions } from '@nestjs/jwt';
 import { JwtSignOptions } from '@nestjs/jwt/dist/interfaces';
@@ -1660,6 +1661,25 @@ interface IBetterAuthBase {
    */
   baseUrl?: string;
 
+  /**
+   * Custom controller class to use instead of the default CoreBetterAuthController.
+   * The class should extend CoreBetterAuthController.
+   *
+   * This allows projects to customize REST endpoints via config instead of creating
+   * a separate module. Use this with CoreModule.forRoot(envConfig) (IAM-only mode).
+   *
+   * @example
+   * ```typescript
+   * // config.env.ts
+   * betterAuth: {
+   *   controller: IamController,
+   * }
+   * ```
+   *
+   * @since 11.14.0
+   */
+  controller?: Type<any>;
+
   /**
    * Email/password authentication configuration.
    * Enabled by default.
@@ -1795,6 +1815,25 @@ interface IBetterAuthBase {
    */
   rateLimit?: IBetterAuthRateLimit;
 
+  /**
+   * Custom resolver class to use instead of the default DefaultBetterAuthResolver.
+   * The class should extend CoreBetterAuthResolver.
+   *
+   * This allows projects to customize GraphQL operations via config instead of creating
+   * a separate module. Use this with CoreModule.forRoot(envConfig) (IAM-only mode).
+   *
+   * @example
+   * ```typescript
+   * // config.env.ts
+   * betterAuth: {
+   *   resolver: IamResolver,
+   * }
+   * ```
+   *
+   * @since 11.14.0
+   */
+  resolver?: Type<any>;
+
   /**
    * Secret for better-auth session cookie signing.
    *
diff --git a/src/core/modules/auth/core-auth.module.ts b/src/core/modules/auth/core-auth.module.ts
index aea12de..86dd9ff 100644
--- a/src/core/modules/auth/core-auth.module.ts
+++ b/src/core/modules/auth/core-auth.module.ts
@@ -46,14 +46,20 @@ export class CoreAuthModule {
 
     // Process providers
     // Only register RolesGuard if not already registered (prevents duplicate with CoreBetterAuthModule)
+    // Note: We register RolesGuard as a regular provider first, then use useExisting
+    // to reference it as APP_GUARD. This ensures proper DI resolution even when
+    // RolesGuard extends a mixin (AuthGuard), which can interfere with useClass DI.
     const rolesGuardProvider = RolesGuardRegistry.isRegistered()
       ? []
       : (() => {
           RolesGuardRegistry.markRegistered('CoreAuthModule');
-          return [{ provide: APP_GUARD, useClass: RolesGuard }];
+          return [
+            RolesGuard, // Register as regular provider first
+            { provide: APP_GUARD, useExisting: RolesGuard }, // Reference the registered provider
+          ];
         })();
 
-    let providers = [
+    let providers: any[] = [
       // [Global] The GraphQLAuthGuard integrates the user into context
       ...rolesGuardProvider,
       {
@@ -81,7 +87,7 @@ export class CoreAuthModule {
       LegacyAuthRateLimitGuard,
     ];
     if (Array.isArray(options?.providers)) {
-      providers = imports.concat(options.providers);
+      providers = providers.concat(options.providers);
     }
 
     // Return CoreAuthModule
diff --git a/src/core/modules/auth/guards/roles.guard.ts b/src/core/modules/auth/guards/roles.guard.ts
index 59893c6..df6cb5c 100644
--- a/src/core/modules/auth/guards/roles.guard.ts
+++ b/src/core/modules/auth/guards/roles.guard.ts
@@ -1,4 +1,4 @@
-import { ExecutionContext, ForbiddenException, Injectable, Logger, Optional, UnauthorizedException } from '@nestjs/common';
+import { ExecutionContext, ForbiddenException, Inject, Injectable, Logger, Optional, UnauthorizedException } from '@nestjs/common';
 import { ModuleRef, Reflector } from '@nestjs/core';
 import { GqlExecutionContext } from '@nestjs/graphql';
 import { firstValueFrom, isObservable } from 'rxjs';
@@ -39,17 +39,52 @@ export class RolesGuard extends AuthGuard(AuthGuardStrategy.JWT) {
   private betterAuthService: CoreBetterAuthService | null = null;
   private tokenService: BetterAuthTokenService | null = null;
   private servicesResolved = false;
+  private resolvedReflector: null | Reflector = null;
 
   /**
    * Integrate reflector and moduleRef for lazy service resolution
+   *
+   * Note: Due to mixin inheritance from AuthGuard, NestJS DI may not inject dependencies correctly
+   * because the mixin generates its own design:paramtypes metadata that can override
+   * the child class's parameter metadata. Using explicit @Inject() decorators ensures
+   * NestJS uses token-based injection rather than positional metadata lookup.
+   *
+   * The ensureReflector() method provides an additional fallback by lazily resolving
+   * Reflector from moduleRef if initial injection fails.
    */
   constructor(
-    protected readonly reflector: Reflector,
-    @Optional() private readonly moduleRef?: ModuleRef,
+    @Inject(Reflector) protected readonly reflector: Reflector,
+    @Optional() @Inject(ModuleRef) private readonly moduleRef?: ModuleRef,
   ) {
     super();
   }
 
+  /**
+   * Ensure Reflector is available.
+   * Due to mixin inheritance from AuthGuard, NestJS DI may not inject Reflector correctly.
+   * This fallback resolves Reflector from moduleRef if not injected.
+   */
+  private ensureReflector(): Reflector {
+    if (this.reflector) {
+      return this.reflector;
+    }
+
+    if (this.resolvedReflector) {
+      return this.resolvedReflector;
+    }
+
+    if (this.moduleRef) {
+      try {
+        this.resolvedReflector = this.moduleRef.get(Reflector, { strict: false });
+        return this.resolvedReflector;
+      } catch {
+        this.logger.error('Failed to resolve Reflector from moduleRef');
+      }
+    }
+
+    throw new Error('Reflector not available - RolesGuard cannot function without it');
+  }
+
   /**
    * Lazily resolve BetterAuth services
    */
@@ -87,7 +122,7 @@ export class RolesGuard extends AuthGuard(AuthGuardStrategy.JWT) {
    */
   override async canActivate(context: ExecutionContext): Promise<boolean> {
     // Get roles FIRST to check if authentication is even needed
-    const reflectorRoles = this.reflector.getAll<string[][]>('roles', [context.getHandler(), context.getClass()]);
+    const reflectorRoles = this.ensureReflector().getAll<string[][]>('roles', [context.getHandler(), context.getClass()]);
     const roles: string[] = reflectorRoles[0]
       ? reflectorRoles[1]
         ? [...reflectorRoles[0], ...reflectorRoles[1]]
@@ -244,7 +279,7 @@ export class RolesGuard extends AuthGuard(AuthGuardStrategy.JWT) {
    */
   override handleRequest(err: Error | null, user: any, info: any, context: ExecutionContext) {
     // Get roles
-    const reflectorRoles = this.reflector.getAll<string[][]>('roles', [context.getHandler(), context.getClass()]);
+    const reflectorRoles = this.ensureReflector().getAll<string[][]>('roles', [context.getHandler(), context.getClass()]);
     const roles: string[] = reflectorRoles[0]
       ? reflectorRoles[1]
         ? [...reflectorRoles[0], ...reflectorRoles[1]]
diff --git a/src/core/modules/better-auth/CUSTOMIZATION.md b/src/core/modules/better-auth/CUSTOMIZATION.md
new file mode 100644
index 0000000..c6a1f5c
--- /dev/null
+++ b/src/core/modules/better-auth/CUSTOMIZATION.md
@@ -0,0 +1,520 @@
+# BetterAuth Customization Guide
+
+This guide describes how to customize the BetterAuth module in projects using `@lenne.tech/nest-server`.
+
+Use this guide when a project needs custom authentication behavior, modified endpoints, or custom email templates.
+
+---
+
+## Table of Contents
+
+- [Module Registration Patterns](#module-registration-patterns)
+- [Customizing Controller](#customizing-controller)
+- [Customizing Resolver](#customizing-resolver)
+- [Customizing Services](#customizing-services)
+- [Email Template Customization](#email-template-customization)
+- [Pattern Selection Guide](#pattern-selection-guide)
+
+---
+
+## Module Registration Patterns
+
+There are **three ways** to register BetterAuth in a project. Choose based on your customization needs.
+
+### Pattern 1: Zero-Config (Default)
+
+**Use when:** No customization needed, using default Controller/Resolver.
+
+```typescript
+// server.module.ts
+@Module({
+  imports: [
+    CoreModule.forRoot(envConfig),  // Auto-imports CoreBetterAuthModule
+  ],
+})
+export class ServerModule {}
+```
+
+**What happens:**
+- CoreModule automatically imports `CoreBetterAuthModule.forRoot()` with defaults
+- Default `CoreBetterAuthController` and `DefaultBetterAuthResolver` are registered
+- No additional configuration needed
+
+### Pattern 2: Config-based Controller/Resolver (Recommended for Customization)
+
+**Use when:** Need custom Controller or Resolver, but don't need a separate module.
+
+```typescript
+// config.env.ts
+import { IamController } from './server/modules/iam/iam.controller';
+import { IamResolver } from './server/modules/iam/iam.resolver';
+
+const config = {
+  betterAuth: {
+    controller: IamController,  // Custom controller class
+    resolver: IamResolver,      // Custom resolver class
+    // ... other betterAuth config
+  },
+};
+```
+
+```typescript
+// server.module.ts
+@Module({
+  imports: [
+    CoreModule.forRoot(envConfig),  // Uses custom controller/resolver from config
+  ],
+})
+export class ServerModule {}
+```
+
+**What happens:**
+- CoreModule passes `controller`/`resolver` to `CoreBetterAuthModule.forRoot()`
+- Your custom classes are registered instead of defaults
+- Single registration point, no duplicate imports
+
+### Pattern 3: Separate Module (autoRegister: false)
+
+**Use when:** Need full control, complex module with additional providers, or multiple custom services.
+
+```typescript
+// config.env.ts
+const config = {
+  betterAuth: {
+    autoRegister: false,  // CoreModule won't auto-import CoreBetterAuthModule
+    // ... other betterAuth config
+  },
+};
+```
+
+```typescript
+// iam.module.ts
+@Module({})
+export class IamModule {
+  static forRoot(): DynamicModule {
+    return {
+      exports: [CoreBetterAuthModule],
+      imports: [
+        CoreBetterAuthModule.forRoot({
+          controller: IamController,
+          resolver: IamResolver,
+          config: envConfig.betterAuth,
+          fallbackSecrets: [envConfig.jwt?.secret],
+        }),
+      ],
+      module: IamModule,
+      providers: [
+        // Additional custom providers
+        MyCustomAuthService,
+      ],
+    };
+  }
+}
+```
+
+```typescript
+// server.module.ts
+@Module({
+  imports: [
+    CoreModule.forRoot(envConfig),  // Does NOT import CoreBetterAuthModule
+    IamModule.forRoot(),            // Your module is the single registration point
+  ],
+})
+export class ServerModule {}
+```
+
+**What happens:**
+- CoreModule skips auto-import of CoreBetterAuthModule
+- Your IamModule is the only place CoreBetterAuthModule.forRoot() is called
+- Full control over module configuration and additional providers
+
+---
+
+## Customizing Controller
+
+### When to Customize
+
+- Add custom REST endpoints (e.g., `/iam/custom-verify`)
+- Modify response format
+- Add logging, analytics, or audit trails
+- Integrate with external services after sign-up/sign-in
+
+### How to Customize
+
+**Create:** `src/server/modules/iam/iam.controller.ts`
+
+```typescript
+import { Controller } from '@nestjs/common';
+import { CoreBetterAuthController } from '@lenne.tech/nest-server';
+
+@Controller('iam')
+export class IamController extends CoreBetterAuthController {
+  /**
+   * Override sign-up to add custom logic
+   */
+  override async signUp(res: Response, input: BetterAuthSignUpInput) {
+    // Custom pre-processing
+    const result = await super.signUp(res, input);
+    // Custom post-processing (e.g., send welcome email, analytics)
+    await this.sendWelcomeNotification(result.user);
+    return result;
+  }
+
+  /**
+   * Add completely new endpoint
+   */
+  @Post('custom-endpoint')
+  @Roles(RoleEnum.S_USER)
+  async customEndpoint(@Body() input: CustomInput) {
+    // Custom logic
+  }
+}
+```
+
+### Important Notes
+
+- Always extend `CoreBetterAuthController`
+- Use `@Controller('iam')` to maintain the same route prefix
+- Call `super.method()` when overriding to preserve core functionality
+- Add `@Roles()` decorators to new endpoints for security
+
+---
+
+## Customizing Resolver
+
+### When to Customize
+
+- Add custom GraphQL mutations/queries
+- Modify response format for GraphQL
+- Add field resolvers
+- Integrate with external services
+
+### How to Customize (CRITICAL!)
+
+**Create:** `src/server/modules/iam/iam.resolver.ts`
+
+```typescript
+import { Mutation, Query, Resolver } from '@nestjs/graphql';
+import {
+  BetterAuthAuthModel,
+  CoreBetterAuthResolver,
+  RoleEnum,
+  Roles
+} from '@lenne.tech/nest-server';
+
+@Resolver(() => BetterAuthAuthModel)
+export class IamResolver extends CoreBetterAuthResolver {
+  /**
+   * CRITICAL: Re-declare ALL decorators when overriding!
+   * GraphQL schema is built from decorators - parent's @Mutation/@Query are NOT inherited.
+   */
+  @Mutation(() => BetterAuthAuthModel, { description: 'Sign up via email' })
+  @Roles(RoleEnum.S_EVERYONE)
+  override async betterAuthSignUp(/* ... */) {
+    // Custom pre-processing
+    const result = await super.betterAuthSignUp(/* ... */);
+    // Custom post-processing
+    return result;
+  }
+
+  /**
+   * Add new GraphQL mutation
+   */
+  @Mutation(() => Boolean, { description: 'Custom verification' })
+  @Roles(RoleEnum.S_USER)
+  async customVerification(@CurrentUser() user: User) {
+    // Custom logic
+    return true;
+  }
+}
+```
+
+### CRITICAL: Decorator Re-declaration
+
+**WHY must ALL decorators be re-declared?**
+
+GraphQL schema is built from decorators at **compile time**. The parent class (`CoreBetterAuthResolver`) is marked as `isAbstract: true`, so its methods are **not** registered in the schema. You MUST re-declare `@Query`, `@Mutation`, `@Roles` decorators in the child class for the methods to appear in the GraphQL schema.
+
+```typescript
+// WRONG: Missing decorators - method won't appear in GraphQL schema!
+override async betterAuthSignUp(/* ... */) {
+  return super.betterAuthSignUp(/* ... */);
+}
+
+// CORRECT: All decorators re-declared
+@Mutation(() => BetterAuthAuthModel)
+@Roles(RoleEnum.S_EVERYONE)
+override async betterAuthSignUp(/* ... */) {
+  return super.betterAuthSignUp(/* ... */);
+}
+```
+
+---
+
+## Customizing Services
+
+### CoreBetterAuthService
+
+The main service handling Better-Auth operations. Extend when you need to:
+- Modify token generation
+- Add custom session handling
+- Integrate with external auth providers
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { CoreBetterAuthService } from '@lenne.tech/nest-server';
+
+@Injectable()
+export class CustomBetterAuthService extends CoreBetterAuthService {
+  // Custom methods or overrides
+}
+```
+
+### CoreBetterAuthEmailVerificationService
+
+Handles email verification. Extend when you need to:
+- Customize verification email content
+- Change verification flow
+- Add custom logging/analytics
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { CoreBetterAuthEmailVerificationService } from '@lenne.tech/nest-server';
+
+@Injectable()
+export class CustomEmailVerificationService extends CoreBetterAuthEmailVerificationService {
+  override async sendVerificationEmail(options: SendVerificationEmailOptions): Promise<void> {
+    // Custom logic before
+    await super.sendVerificationEmail(options);
+    // Custom logic after (e.g., analytics)
+  }
+}
+```
+
+### CoreBetterAuthUserMapper
+
+Handles user mapping between BetterAuth and nest-server User model. Extend when you need to:
+- Sync additional fields
+- Custom user creation logic
+- Integration with external user systems
+
+---
+
+## Email Template Customization
+
+### Template Resolution Order
+
+Email templates are resolved in this order:
+
+1. `<template>-<locale>.ejs` in **project templates directory**
+2. `<template>.ejs` in **project templates directory**
+3. `<template>-<locale>.ejs` in **nest-server templates** (fallback)
+4. `<template>.ejs` in **nest-server templates** (fallback)
+
+### Available Templates
+
+| Template | Purpose | Default Locales |
+|----------|---------|-----------------|
+| `email-verification` | Email verification after sign-up | `en`, `de` |
+| `password-reset` | Password reset email | `en` |
+| `welcome` | Welcome email (not used by default) | `en` |
+
+### How to Override Templates
+
+**Step 1:** Create templates directory in your project
+
+```bash
+mkdir -p src/templates
+```
+
+**Step 2:** Copy and modify the template
+
+```bash
+# Copy from nest-server (or create new)
+cp node_modules/@lenne.tech/nest-server/src/templates/email-verification-en.ejs src/templates/
+```
+
+**Step 3:** Configure templates path (if not default)
+
+```typescript
+// config.env.ts
+const config = {
+  templates: {
+    path: path.join(__dirname, 'templates'),
+  },
+};
+```
+
+### Template Variables
+
+Available variables in email templates:
+
+| Variable | Type | Description |
+|----------|------|-------------|
+| `name` | string | User's name or email prefix |
+| `link` | string | Verification/reset URL |
+| `appName` | string | Application name from package.json |
+| `expiresIn` | string | Human-readable expiration time (e.g., "24 hours") |
+
+### Example Template
+
+```html
+<!-- src/templates/email-verification-en.ejs -->
+<!DOCTYPE html>
+<html>
+<head>
+  <title>Verify your email - <%= appName %></title>
+</head>
+<body>
+  <h1>Hello <%= name %>,</h1>
+  <p>Please verify your email address by clicking the link below:</p>
+  <p><a href="<%= link %>">Verify Email</a></p>
+  <p>This link expires in <%= expiresIn %>.</p>
+  <p>Best regards,<br>The <%= appName %> Team</p>
+</body>
+</html>
+```
+
+### Using Brevo Templates
+
+For production, you can use Brevo (formerly Sendinblue) transactional templates:
+
+```typescript
+// config.env.ts
+const config = {
+  betterAuth: {
+    emailVerification: {
+      brevoTemplateId: 123,  // Your Brevo template ID
+      locale: 'de',
+    },
+  },
+  brevo: {
+    apiKey: process.env.BREVO_API_KEY,
+  },
+};
+```
+
+**Brevo template parameters:**
+- `name` - User's name
+- `link` - Verification URL
+- `appName` - Application name
+- `expiresIn` - Expiration time string
+
+### Email Verification Configuration
+
+```typescript
+// config.env.ts
+const config = {
+  betterAuth: {
+    emailVerification: {
+      enabled: true,                        // Default: true
+      locale: 'de',                         // Default: 'en'
+      template: 'email-verification',       // Default: 'email-verification'
+      expiresIn: 86400,                     // Default: 86400 (24 hours)
+      callbackURL: '/auth/verify-email',    // Frontend verification page
+      autoSignInAfterVerification: true,    // Default: true
+      resendCooldownSeconds: 60,            // Default: 60
+    },
+  },
+};
+```
+
+---
+
+## Pattern Selection Guide
+
+| Requirement | Recommended Pattern |
+|-------------|---------------------|
+| No customization needed | Pattern 1: Zero-Config |
+| Custom Controller only | Pattern 2: Config-based |
+| Custom Resolver only | Pattern 2: Config-based |
+| Custom Controller + Resolver | Pattern 2: Config-based |
+| Additional providers/services | Pattern 3: Separate Module |
+| Complex module with multiple exports | Pattern 3: Separate Module |
+| Need to avoid duplicate forRoot() warning | Pattern 2 or Pattern 3 |
+
+### Avoiding the "forRoot() called twice" Warning
+
+If you see this warning:
+```
+CoreBetterAuthModule.forRoot() was called more than once.
+```
+
+**Solutions:**
+
+1. **Config-based (Pattern 2):** Move `controller`/`resolver` to `config.betterAuth`
+2. **autoRegister: false (Pattern 3):** Set `betterAuth.autoRegister: false` in config
+
+**Why this happens:** CoreModule auto-imports `CoreBetterAuthModule.forRoot()` in IAM-only mode. If your project also calls `forRoot()` (e.g., in IamModule), it's called twice. NestJS silently ignores the second call, but your custom Controller/Resolver may not be registered.
+
+---
+
+## Reference Implementation
+
+All customization examples exist as working code in the package:
+
+**Local:**
+```
+node_modules/@lenne.tech/nest-server/src/server/modules/better-auth/
+```
+
+**GitHub:**
+https://github.com/lenneTech/nest-server/tree/develop/src/server/modules/better-auth
+
+---
+
+## RolesGuard Selection (Internal)
+
+The BetterAuth module uses different RolesGuard implementations depending on your configuration. **This is handled automatically - you don't need to do anything.**
+
+### Which Guard is Used?
+
+| Mode | Guard Used | Registered By |
+|------|------------|---------------|
+| **Legacy Mode** (3-param CoreModule.forRoot) | `RolesGuard` | `CoreAuthModule` |
+| **IAM-Only Mode** (1-param CoreModule.forRoot) | `BetterAuthRolesGuard` | `CoreBetterAuthModule` |
+
+```typescript
+// Legacy Mode → RolesGuard (extends Passport AuthGuard)
+CoreModule.forRoot(CoreAuthService, AuthModule.forRoot(jwt), envConfig)
+
+// IAM-Only Mode → BetterAuthRolesGuard (no Passport dependency)
+CoreModule.forRoot(envConfig)
+```
+
+### Why Two Guards?
+
+**RolesGuard** (Legacy + Hybrid Mode):
+- Extends `AuthGuard(AuthGuardStrategy.JWT)` from Passport
+- Supports both Legacy JWT and BetterAuth tokens
+- Requires `CoreAuthModule` to register the JWT strategy
+
+**BetterAuthRolesGuard** (IAM-Only Mode):
+- Does NOT extend AuthGuard (no Passport dependency)
+- Uses BetterAuth exclusively for token verification
+- Avoids DI issues that occur with Passport AuthGuard mixin in certain module configurations
+
+### Technical Background
+
+The `AuthGuard()` from `@nestjs/passport` is a **mixin** (a factory that returns a class). This mixin generates its own TypeScript `design:paramtypes` metadata, which can conflict with the child class's constructor parameters in certain NestJS DI contexts (specifically when registered as `APP_GUARD` in a dynamic module with `autoRegister: false`).
+
+`BetterAuthRolesGuard` avoids this by:
+1. Not extending any mixin
+2. Having no constructor dependencies (uses `Reflect.getMetadata` directly instead of NestJS Reflector)
+3. Accessing services via static module references
+
+### What You Need to Know
+
+**Nothing changes for you as a developer:**
+- Use `@Roles()` decorator as always
+- The correct guard is selected automatically
+- Both guards process `@Roles()` identically
+- Security behavior is identical
+
+---
+
+## Related Documentation
+
+- [README.md](./README.md) - Full BetterAuth documentation
+- [INTEGRATION-CHECKLIST.md](./INTEGRATION-CHECKLIST.md) - Quick integration steps
+- [Module Inheritance Pattern](../../../.claude/rules/module-inheritance.md) - Core architectural pattern
diff --git a/src/core/modules/better-auth/INTEGRATION-CHECKLIST.md b/src/core/modules/better-auth/INTEGRATION-CHECKLIST.md
index 6df8ae7..909bbfe 100644
--- a/src/core/modules/better-auth/INTEGRATION-CHECKLIST.md
+++ b/src/core/modules/better-auth/INTEGRATION-CHECKLIST.md
@@ -4,6 +4,11 @@
 
 > **Estimated time:** 10-15 minutes
 
+**Need customization?** See [CUSTOMIZATION.md](./CUSTOMIZATION.md) for:
+- Module registration patterns (Zero-Config, Config-based, Separate Module)
+- Controller, Resolver, and Service customization
+- Email template customization
+
 ---
 
 ## Choose Your Scenario
@@ -15,6 +20,16 @@
 
 **Key difference:** New projects disable Legacy endpoints, existing projects keep them enabled during migration.
 
+### Registration Patterns (Quick Reference)
+
+| Pattern | Use When | Configuration |
+|---------|----------|---------------|
+| **Zero-Config** | No customization needed | Just use `CoreModule.forRoot(envConfig)` |
+| **Config-based** | Custom Controller/Resolver | Add `controller`/`resolver` to `betterAuth` config |
+| **Separate Module** | Full control, additional providers | Set `autoRegister: false` in config |
+
+**Details:** See [CUSTOMIZATION.md](./CUSTOMIZATION.md#module-registration-patterns)
+
 ---
 
 ## Reference Implementation
diff --git a/src/core/modules/better-auth/README.md b/src/core/modules/better-auth/README.md
index 4e09d60..b2c7873 100644
--- a/src/core/modules/better-auth/README.md
+++ b/src/core/modules/better-auth/README.md
@@ -21,7 +21,7 @@ const config = {
 }
 ```
 
-**Quick Links:** [Integration Checklist](./INTEGRATION-CHECKLIST.md) | [REST API](#rest-api-endpoints) | [GraphQL API](#graphql-api) | [Configuration](#configuration)
+**Quick Links:** [Integration Checklist](./INTEGRATION-CHECKLIST.md) | [Customization Guide](./CUSTOMIZATION.md) | [REST API](#rest-api-endpoints) | [GraphQL API](#graphql-api) | [Configuration](#configuration)
 
 ---
 
@@ -34,6 +34,7 @@ const config = {
 - [REST API Endpoints](#rest-api-endpoints)
 - [GraphQL API](#graphql-api)
 - [CoreModule Signatures](#coremoduleforroot-signatures)
+- [Customization](#customization)
 - [Migration Roadmap](#migration-roadmap-legacy-auth--betterauth)
 - [Password Synchronization](#bidirectional-password-synchronization)
 - [Security Integration](#security-integration)
@@ -1386,6 +1387,28 @@ export class ServerModule {}
 
 ---
 
+## Customization
+
+BetterAuth supports extensive customization through inheritance and configuration.
+
+**See [CUSTOMIZATION.md](./CUSTOMIZATION.md) for the complete customization guide, including:**
+
+- **Module Registration Patterns** - Three ways to register BetterAuth (Zero-Config, Config-based, Separate Module)
+- **Customizing Controller** - Override REST endpoints, add new endpoints
+- **Customizing Resolver** - Override GraphQL mutations/queries (with critical decorator requirements)
+- **Customizing Services** - Extend `CoreBetterAuthService`, `CoreBetterAuthEmailVerificationService`
+- **Email Template Customization** - Override templates, use Brevo, localization
+
+### Quick Reference: Registration Patterns
+
+| Pattern | Use When | Configuration |
+|---------|----------|---------------|
+| **Zero-Config** | No customization | `CoreModule.forRoot(envConfig)` |
+| **Config-based** | Custom Controller/Resolver | `betterAuth: { controller, resolver }` |
+| **Separate Module** | Full control, additional providers | `betterAuth: { autoRegister: false }` |
+
+---
+
 ## Migration Roadmap (Legacy Auth → BetterAuth)
 
 Better-Auth is designed as the successor to Legacy Auth. This section describes the migration path.
diff --git a/src/core/modules/better-auth/better-auth-roles.guard.ts b/src/core/modules/better-auth/better-auth-roles.guard.ts
new file mode 100644
index 0000000..6b8e812
--- /dev/null
+++ b/src/core/modules/better-auth/better-auth-roles.guard.ts
@@ -0,0 +1,205 @@
+import { CanActivate, ExecutionContext, ForbiddenException, Injectable, Logger, UnauthorizedException } from '@nestjs/common';
+import { GqlExecutionContext } from '@nestjs/graphql';
+
+import { RoleEnum } from '../../common/enums/role.enum';
+import { ErrorCode } from '../error-code';
+import { BetterAuthTokenService } from './better-auth-token.service';
+import { BetterAuthenticatedUser } from './better-auth.types';
+import { CoreBetterAuthModule } from './core-better-auth.module';
+
+/**
+ * BetterAuth Roles Guard
+ *
+ * A simplified roles guard for BetterAuth (IAM-only) mode that does NOT extend AuthGuard.
+ * This avoids the mixin inheritance DI issues that occur with the standard RolesGuard.
+ *
+ * In IAM-only mode, authentication is handled by CoreBetterAuthMiddleware which:
+ * 1. Validates JWT tokens or session tokens
+ * 2. Sets req.user with the authenticated user (with _authenticatedViaBetterAuth flag)
+ *
+ * If the middleware hasn't set req.user (e.g., in test environments), this guard will
+ * try to verify the token directly using BetterAuthTokenService.
+ *
+ * No Passport integration is needed because BetterAuth handles all token validation.
+ *
+ * IMPORTANT: This guard has NO constructor dependencies. This is intentional because
+ * NestJS DI has issues resolving Reflector/ModuleRef for APP_GUARD providers in dynamic modules.
+ * Instead, we use Reflect.getMetadata directly to read decorator metadata, and access
+ * BetterAuthTokenService via CoreBetterAuthModule static reference.
+ */
+@Injectable()
+export class BetterAuthRolesGuard implements CanActivate {
+  private readonly logger = new Logger(BetterAuthRolesGuard.name);
+  private tokenService: BetterAuthTokenService | null = null;
+
+  /**
+   * Get BetterAuthTokenService lazily from CoreBetterAuthModule
+   * This avoids DI issues while still allowing token verification
+   */
+  private getTokenService(): BetterAuthTokenService | null {
+    if (!this.tokenService) {
+      this.tokenService = CoreBetterAuthModule.getTokenServiceInstance();
+    }
+    return this.tokenService;
+  }
+
+  /**
+   * Try to verify a BetterAuth token if user isn't already on the request.
+   * This handles cases where middleware didn't run (e.g., test environments).
+   */
+  private async verifyToken(request: any): Promise<BetterAuthenticatedUser | null> {
+    const tokenService = this.getTokenService();
+    if (!tokenService) {
+      return null;
+    }
+
+    try {
+      const { token } = tokenService.extractTokenFromRequest(request);
+      if (!token) {
+        return null;
+      }
+      return await tokenService.verifyAndLoadUser(token);
+    } catch (error) {
+      this.logger.debug(`Token verification failed: ${error instanceof Error ? error.message : 'Unknown error'}`);
+      return null;
+    }
+  }
+
+  async canActivate(context: ExecutionContext): Promise<boolean> {
+    // Get roles from decorator metadata using Reflect.getMetadata directly
+    // This avoids the need for NestJS Reflector which causes DI issues in dynamic modules
+    const handlerRoles = Reflect.getMetadata('roles', context.getHandler()) as string[] | undefined;
+    const classRoles = Reflect.getMetadata('roles', context.getClass()) as string[] | undefined;
+
+    // Combine handler and class roles (handler takes precedence, like Reflector.getAll)
+    const reflectorRoles: (string[] | undefined)[] = [handlerRoles, classRoles];
+    const roles: string[] = reflectorRoles[0]
+      ? reflectorRoles[1]
+        ? [...reflectorRoles[0], ...reflectorRoles[1]]
+        : reflectorRoles[0]
+      : reflectorRoles[1];
+
+    // Check if locked - always deny
+    if (roles && roles.includes(RoleEnum.S_NO_ONE)) {
+      throw new UnauthorizedException(ErrorCode.UNAUTHORIZED);
+    }
+
+    // If no roles required, or S_EVERYONE is set, allow access without authentication
+    if (!roles || !roles.some((value) => !!value) || roles.includes(RoleEnum.S_EVERYONE)) {
+      return true;
+    }
+
+    // Get request and check for user (set by BetterAuth middleware)
+    const request = this.getRequest(context);
+    let user = request?.user;
+
+    // If user isn't set (e.g., middleware didn't run in test environment),
+    // try to verify the token directly
+    if (!user) {
+      user = await this.verifyToken(request);
+      if (user && request) {
+        // Store the verified user on the request for downstream handlers
+        request.user = user;
+      }
+    }
+
+    // Check if user is authenticated
+    if (!user) {
+      throw new UnauthorizedException(ErrorCode.UNAUTHORIZED);
+    }
+
+    // Check S_USER role - any authenticated user is allowed
+    if (roles.includes(RoleEnum.S_USER)) {
+      return true;
+    }
+
+    // Check S_SELF role - user is accessing their own data
+    if (roles.includes(RoleEnum.S_SELF)) {
+      // Get the target object's ID from params or args
+      const targetId = this.getTargetId(context);
+      if (targetId && user.id === targetId) {
+        return true;
+      }
+    }
+
+    // Check S_CREATOR role - user created the object
+    if (roles.includes(RoleEnum.S_CREATOR)) {
+      // This requires the object to have a createdBy field
+      // Usually checked in services, but we can't access the object here
+      // Let it pass and check in the service/resolver
+      this.logger.debug('S_CREATOR check deferred to service layer');
+    }
+
+    // Check S_VERIFIED role - user's email is verified
+    if (roles.includes(RoleEnum.S_VERIFIED)) {
+      if (!user.verified && !user.verifiedAt && !user.emailVerified) {
+        throw new ForbiddenException(ErrorCode.ACCESS_DENIED);
+      }
+      return true;
+    }
+
+    // Check if user has required role
+    if (user.hasRole?.(roles)) {
+      return true;
+    }
+
+    // Check if user's roles array includes any of the required roles
+    if (user.roles && Array.isArray(user.roles)) {
+      const hasRequiredRole = roles.some((role) => user.roles.includes(role));
+      if (hasRequiredRole) {
+        return true;
+      }
+    }
+
+    // User doesn't have required role
+    throw new ForbiddenException(ErrorCode.ACCESS_DENIED);
+  }
+
+  /**
+   * Get request from execution context
+   * Handles both GraphQL and HTTP contexts
+   */
+  private getRequest(context: ExecutionContext): any {
+    // Try GraphQL context first
+    try {
+      const gqlContext = GqlExecutionContext.create(context);
+      const ctx = gqlContext.getContext();
+      if (ctx?.req) {
+        return ctx.req;
+      }
+    } catch {
+      // GraphQL context not available
+    }
+
+    // Fallback to HTTP context
+    return context.switchToHttp().getRequest();
+  }
+
+  /**
+   * Get target ID from context for S_SELF checks
+   */
+  private getTargetId(context: ExecutionContext): null | string {
+    // Try GraphQL args
+    try {
+      const gqlContext = GqlExecutionContext.create(context);
+      const args = gqlContext.getArgs();
+      if (args?.id) {
+        return args.id;
+      }
+    } catch {
+      // GraphQL context not available
+    }
+
+    // Try HTTP params
+    try {
+      const request = context.switchToHttp().getRequest();
+      if (request?.params?.id) {
+        return request.params.id;
+      }
+    } catch {
+      // HTTP context not available
+    }
+
+    return null;
+  }
+}
diff --git a/src/core/modules/better-auth/core-better-auth-api.middleware.ts b/src/core/modules/better-auth/core-better-auth-api.middleware.ts
index 2bec2e2..168ac3f 100644
--- a/src/core/modules/better-auth/core-better-auth-api.middleware.ts
+++ b/src/core/modules/better-auth/core-better-auth-api.middleware.ts
@@ -332,6 +332,12 @@ export class CoreBetterAuthApiMiddleware implements NestMiddleware {
         }
       }
 
+      // If Better Auth returned 404, the path is not handled by Better Auth.
+      // Call next() to let NestJS controllers handle it (e.g., custom controller endpoints).
+      if (response.status === 404) {
+        return next();
+      }
+
       // Convert Web Standard Response to Express response using shared helper
       await sendWebResponse(res, response);
     } catch (error) {
diff --git a/src/core/modules/better-auth/core-better-auth.module.ts b/src/core/modules/better-auth/core-better-auth.module.ts
index c50ae7c..72c982d 100644
--- a/src/core/modules/better-auth/core-better-auth.module.ts
+++ b/src/core/modules/better-auth/core-better-auth.module.ts
@@ -17,7 +17,7 @@ import { IBetterAuth } from '../../common/interfaces/server-options.interface';
 import { BrevoService } from '../../common/services/brevo.service';
 import { ConfigService } from '../../common/services/config.service';
 import { RolesGuardRegistry } from '../auth/guards/roles-guard-registry';
-import { RolesGuard } from '../auth/guards/roles.guard';
+import { BetterAuthRolesGuard } from './better-auth-roles.guard';
 import { BetterAuthTokenService } from './better-auth-token.service';
 import { BetterAuthInstance, createBetterAuthInstance } from './better-auth.config';
 import { DefaultBetterAuthResolver } from './better-auth.resolver';
@@ -228,6 +228,13 @@ export class CoreBetterAuthModule implements NestModule, OnModuleInit {
   // Static reference to email verification service for Better-Auth hooks (outside DI context)
   private static emailVerificationService: CoreBetterAuthEmailVerificationService | null = null;
   private static mongoConnection: Connection | null = null;
+  // Safety Net: Track if forRoot() has already been called to detect duplicate registration
+  private static forRootCalled = false;
+  private static cachedDynamicModule: DynamicModule | null = null;
+  // Static references for lazy GraphQL driver (autoRegister: false) and BetterAuthRolesGuard
+  private static serviceInstance: CoreBetterAuthService | null = null;
+  private static userMapperInstance: CoreBetterAuthUserMapper | null = null;
+  private static tokenServiceInstance: BetterAuthTokenService | null = null;
 
   /**
    * Gets the controller class to use (custom or default)
@@ -243,9 +250,38 @@ export class CoreBetterAuthModule implements NestModule, OnModuleInit {
     return this.customResolver || DefaultBetterAuthResolver;
   }
 
+  /**
+   * Gets the static CoreBetterAuthService instance.
+   * Used by the lazy GraphQL driver when autoRegister: false.
+   * Safe because onConnect is called only after module initialization.
+   */
+  static getServiceInstance(): CoreBetterAuthService | null {
+    return this.serviceInstance;
+  }
+
+  /**
+   * Gets the static CoreBetterAuthUserMapper instance.
+   * Used by the lazy GraphQL driver when autoRegister: false.
+   * Safe because onConnect is called only after module initialization.
+   */
+  static getUserMapperInstance(): CoreBetterAuthUserMapper | null {
+    return this.userMapperInstance;
+  }
+
+  /**
+   * Gets the static BetterAuthTokenService instance.
+   * Used by BetterAuthRolesGuard for token verification when user isn't already on request.
+   * Safe because guards are invoked only after module initialization.
+   */
+  static getTokenServiceInstance(): BetterAuthTokenService | null {
+    return this.tokenServiceInstance;
+  }
+
   constructor(
     @Optional() private readonly betterAuthService?: CoreBetterAuthService,
     @Optional() private readonly rateLimiter?: CoreBetterAuthRateLimiter,
+    @Optional() private readonly userMapper?: CoreBetterAuthUserMapper,
+    @Optional() private readonly tokenService?: BetterAuthTokenService,
   ) {}
 
   onModuleInit() {
@@ -254,6 +290,17 @@ export class CoreBetterAuthModule implements NestModule, OnModuleInit {
       CoreBetterAuthModule.logger.log('CoreBetterAuthModule ready');
     }
 
+    // Store static references for lazy GraphQL driver (autoRegister: false) and BetterAuthRolesGuard
+    if (this.betterAuthService) {
+      CoreBetterAuthModule.serviceInstance = this.betterAuthService;
+    }
+    if (this.userMapper) {
+      CoreBetterAuthModule.userMapperInstance = this.userMapper;
+    }
+    if (this.tokenService) {
+      CoreBetterAuthModule.tokenServiceInstance = this.tokenService;
+    }
+
     // Configure rate limiter with stored config
     if (this.rateLimiter && CoreBetterAuthModule.currentConfig?.rateLimit) {
       this.rateLimiter.configure(CoreBetterAuthModule.currentConfig.rateLimit);
@@ -368,6 +415,24 @@ export class CoreBetterAuthModule implements NestModule, OnModuleInit {
    * @returns Dynamic module configuration
    */
   static forRoot(options: CoreBetterAuthModuleOptions): DynamicModule {
+    // Safety Net: Detect duplicate forRoot() calls
+    // NestJS deduplicates DynamicModules by module class — the FIRST import wins,
+    // subsequent imports are silently ignored. This means custom controller/resolver
+    // from the second call would be lost. Return cached module with a warning.
+    if (this.forRootCalled && !process.env.VITEST) {
+      this.logger.warn(
+        'CoreBetterAuthModule.forRoot() was called more than once. ' +
+        'The second call is ignored by NestJS (DynamicModule deduplication). ' +
+        'Custom controller/resolver from the second call will NOT be registered. ' +
+        'Solutions: (1) Use betterAuth.controller/resolver in config, or ' +
+        '(2) Set betterAuth.autoRegister: false and import your module separately.',
+      );
+      if (this.cachedDynamicModule) {
+        return this.cachedDynamicModule;
+      }
+    }
+    this.forRootCalled = true;
+
     const {
       config: rawConfig,
       controller,
@@ -423,7 +488,7 @@ export class CoreBetterAuthModule implements NestModule, OnModuleInit {
     if (config === null || config?.enabled === false) {
       this.logger.debug('BetterAuth is disabled - skipping initialization');
       this.betterAuthEnabled = false;
-      return {
+      this.cachedDynamicModule = {
         exports: [BETTER_AUTH_INSTANCE, CoreBetterAuthService, CoreBetterAuthUserMapper, CoreBetterAuthRateLimiter, BetterAuthTokenService, CoreBetterAuthChallengeService],
         module: CoreBetterAuthModule,
         providers: [
@@ -442,6 +507,7 @@ export class CoreBetterAuthModule implements NestModule, OnModuleInit {
           // because they require ConfigService and have no purpose when BetterAuth is disabled
         ],
       };
+      return this.cachedDynamicModule;
     }
 
     // Enable middleware registration
@@ -453,12 +519,13 @@ export class CoreBetterAuthModule implements NestModule, OnModuleInit {
     // Always use deferred initialization to ensure MongoDB is ready
     // This prevents timing issues during application startup
     // Pass server-level URLs for Passkey auto-detection (using effective values from ConfigService fallback)
-    return this.createDeferredModule(config, {
+    this.cachedDynamicModule = this.createDeferredModule(config, {
       fallbackSecrets: effectiveFallbackSecrets,
       serverAppUrl: effectiveServerAppUrl,
       serverBaseUrl: effectiveServerBaseUrl,
       serverEnv: effectiveServerEnv,
     });
+    return this.cachedDynamicModule;
   }
 
   /**
@@ -622,6 +689,13 @@ export class CoreBetterAuthModule implements NestModule, OnModuleInit {
     this.shouldRegisterRolesGuardGlobally = false;
     this.rolesGuardExplicitlyDisabled = false;
     this.emailVerificationService = null;
+    this.mongoConnection = null;
+    // Safety Net: Reset duplicate-call detection
+    this.forRootCalled = false;
+    this.cachedDynamicModule = null;
+    // Lazy GraphQL driver: Reset service references
+    this.serviceInstance = null;
+    this.userMapperInstance = null;
     // Reset shared RolesGuard registry (shared with CoreAuthModule)
     RolesGuardRegistry.reset();
   }
@@ -822,17 +896,20 @@ export class CoreBetterAuthModule implements NestModule, OnModuleInit {
         },
         CoreBetterAuthChallengeService,
         this.getResolverClass(),
-        // Conditionally register RolesGuard globally for IAM-only setups
-        // In Legacy mode, RolesGuard is already registered globally via CoreAuthModule
+        // Conditionally register BetterAuthRolesGuard globally for IAM-only setups
+        // In Legacy mode, RolesGuard is registered globally via CoreAuthModule instead
         // Uses shared RolesGuardRegistry to prevent duplicate registration across modules
+        //
+        // Note: We use BetterAuthRolesGuard (not RolesGuard) in IAM-only mode because:
+        // - RolesGuard extends AuthGuard (a Passport mixin) which has DI metadata conflicts
+        // - BetterAuthRolesGuard is a simpler guard that only checks roles
+        // - Authentication is handled by CoreBetterAuthMiddleware (JWT/session validation)
         ...(this.shouldRegisterRolesGuardGlobally && !RolesGuardRegistry.isRegistered()
           ? (() => {
               RolesGuardRegistry.markRegistered('CoreBetterAuthModule');
               return [
-                {
-                  provide: APP_GUARD,
-                  useClass: RolesGuard,
-                },
+                BetterAuthRolesGuard,
+                { provide: APP_GUARD, useExisting: BetterAuthRolesGuard },
               ];
             })()
           : []),
diff --git a/src/core/modules/better-auth/index.ts b/src/core/modules/better-auth/index.ts
index 0442946..0d918c7 100644
--- a/src/core/modules/better-auth/index.ts
+++ b/src/core/modules/better-auth/index.ts
@@ -22,6 +22,7 @@
  * - DefaultBetterAuthResolver: Default resolver implementation (use as fallback)
  */
 
+export * from './better-auth-roles.guard';
 export * from './better-auth-token.service';
 export * from './better-auth.config';
 export * from './better-auth.resolver';
diff --git a/tests/stories/better-auth-autoregister-false.e2e-spec.ts b/tests/stories/better-auth-autoregister-false.e2e-spec.ts
new file mode 100644
index 0000000..22a5c8d
--- /dev/null
+++ b/tests/stories/better-auth-autoregister-false.e2e-spec.ts
@@ -0,0 +1,230 @@
+/**
+ * Story: BetterAuth autoRegister: false (Pattern 3)
+ *
+ * Tests that when autoRegister: false is set in betterAuth config,
+ * CoreModule does NOT import CoreBetterAuthModule. The project
+ * must import CoreBetterAuthModule.forRoot() separately.
+ *
+ * This is in a separate file because NestJS GraphQL schema generation
+ * has process-level side effects that can interfere when multiple
+ * NestJS apps with different resolvers are created in the same process.
+ */
+
+import { Controller, Get, Module } from '@nestjs/common';
+import { NestExpressApplication } from '@nestjs/platform-express';
+import { ScheduleModule } from '@nestjs/schedule';
+import { Test, TestingModule } from '@nestjs/testing';
+import { Server } from 'http';
+import { Db, MongoClient } from 'mongodb';
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+
+import {
+  CoreBetterAuthModule,
+  CoreModule,
+  CurrentUser,
+  HttpExceptionLogFilter,
+  RoleEnum,
+  Roles,
+  TestHelper,
+} from '../../src';
+import envConfig from '../../src/config.env';
+import { Any } from '../../src/core/common/scalars/any.scalar';
+import { DateScalar } from '../../src/core/common/scalars/date.scalar';
+import { JSON as JSONScalar } from '../../src/core/common/scalars/json.scalar';
+import { CronJobs } from '../../src/server/common/services/cron-jobs.service';
+
+// =================================================================================================
+// Security Test Controller
+// =================================================================================================
+
+@Controller('security-test')
+class SecurityTestController {
+  @Get('public')
+  @Roles(RoleEnum.S_EVERYONE)
+  getPublic() {
+    return { access: 'public' };
+  }
+
+  @Get('user-only')
+  @Roles(RoleEnum.S_USER)
+  getUserOnly(@CurrentUser() user: any) {
+    return { access: 'user-only', userId: user?.id };
+  }
+
+  @Get('admin-only')
+  @Roles(RoleEnum.ADMIN)
+  getAdminOnly(@CurrentUser() user: any) {
+    return { access: 'admin-only', userId: user?.id };
+  }
+
+  @Get('no-one')
+  @Roles(RoleEnum.S_NO_ONE)
+  getNoOne() {
+    return { access: 'no-one' };
+  }
+}
+
+const generateTestEmail = (prefix: string): string => {
+  return `reg-test-${prefix}-${Date.now()}-${Math.random().toString(36).substring(2, 8)}@test.com`;
+};
+
+// =================================================================================================
+// Tests
+// =================================================================================================
+
+describe('Story: BetterAuth autoRegister: false (Pattern 3)', () => {
+  let app: NestExpressApplication;
+  let httpServer: Server;
+  let testHelper: TestHelper;
+  let mongoClient: MongoClient;
+  let db: Db;
+  let userEmail: string;
+  let userPassword: string;
+  let userToken: string;
+
+  beforeAll(async () => {
+    CoreBetterAuthModule.reset();
+
+    const testConfig = {
+      ...envConfig,
+      betterAuth: {
+        ...envConfig.betterAuth,
+        autoRegister: false,
+        emailVerification: false,
+        enabled: true,
+        signUpChecks: false,
+      },
+    };
+
+    // When autoRegister: false, CoreModule does NOT import CoreBetterAuthModule.
+    // The project must import it separately (like this IamModule).
+    @Module({
+      controllers: [SecurityTestController],
+      exports: [CoreModule],
+      imports: [
+        CoreModule.forRoot(testConfig),
+        // Project's own BetterAuth module — the single registrant
+        CoreBetterAuthModule.forRoot({
+          config: testConfig.betterAuth,
+          fallbackSecrets: [testConfig.jwt?.secret, testConfig.jwt?.refresh?.secret],
+          registerRolesGuardGlobally: true,
+          serverAppUrl: testConfig.appUrl,
+          serverBaseUrl: testConfig.baseUrl,
+          serverEnv: testConfig.env,
+        }),
+        ScheduleModule.forRoot(),
+      ],
+      providers: [Any, CronJobs, DateScalar, JSONScalar],
+    })
+    class AutoRegisterFalseTestModule {}
+
+    const moduleFixture: TestingModule = await Test.createTestingModule({
+      imports: [AutoRegisterFalseTestModule],
+    }).compile();
+
+    app = moduleFixture.createNestApplication<NestExpressApplication>();
+    app.useGlobalFilters(new HttpExceptionLogFilter());
+    await app.init();
+
+    httpServer = app.getHttpServer();
+    await new Promise<void>((resolve) => {
+      httpServer.listen(0, '127.0.0.1', () => resolve());
+    });
+    const port = (httpServer.address() as any).port;
+    testHelper = new TestHelper(app, `ws://127.0.0.1:${port}/graphql`);
+
+    mongoClient = new MongoClient('mongodb://127.0.0.1:27017');
+    await mongoClient.connect();
+    db = mongoClient.db('nest-server-local');
+
+    // Create a test user
+    userEmail = generateTestEmail('autoregister-false');
+    userPassword = 'a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6test';
+
+    const signUp = await testHelper.rest('/iam/sign-up/email', {
+      method: 'POST',
+      payload: { email: userEmail, name: 'AutoRegister False Test', password: userPassword },
+      statusCode: 201,
+    });
+    userToken = signUp.token;
+  }, 60000);
+
+  afterAll(async () => {
+    // Cleanup test data
+    if (db) {
+      await db.collection('users').deleteMany({ email: { $regex: /^reg-test-autoregister-false/ } });
+      await db.collection('session').deleteMany({});
+      await db.collection('account').deleteMany({});
+    }
+    if (mongoClient) {
+      await mongoClient.close();
+    }
+    if (httpServer) {
+      await new Promise<void>((resolve) => httpServer.close(() => resolve()));
+    }
+    if (app) {
+      await app.close();
+    }
+    CoreBetterAuthModule.reset();
+  });
+
+  it('should have IAM endpoints from project-registered module', async () => {
+    const result = await testHelper.rest('/iam/features', {
+      method: 'GET',
+      statusCode: 200,
+    });
+    expect(result).toBeDefined();
+  });
+
+  it('should have RolesGuard globally registered', async () => {
+    // Public endpoint works
+    const publicResult = await testHelper.rest('/security-test/public', {
+      method: 'GET',
+      statusCode: 200,
+    });
+    expect(publicResult.access).toBe('public');
+
+    // Protected endpoint requires auth
+    await testHelper.rest('/security-test/user-only', {
+      method: 'GET',
+      statusCode: 401,
+    });
+  });
+
+  it('should enforce @Roles(S_USER) — 200 with auth', async () => {
+    const result = await testHelper.rest('/security-test/user-only', {
+      method: 'GET',
+      statusCode: 200,
+      token: userToken,
+    });
+    expect(result.access).toBe('user-only');
+    expect(result.userId).toBeDefined();
+  });
+
+  it('should enforce @Roles(ADMIN) — 403 without admin role', async () => {
+    await testHelper.rest('/security-test/admin-only', {
+      method: 'GET',
+      statusCode: 403,
+      token: userToken,
+    });
+  });
+
+  it('should enforce @Roles(S_NO_ONE) — 401 always', async () => {
+    // S_NO_ONE throws UnauthorizedException (401) in RolesGuard, not ForbiddenException (403)
+    await testHelper.rest('/security-test/no-one', {
+      method: 'GET',
+      statusCode: 401,
+      token: userToken,
+    });
+  });
+
+  it('should have middleware active (_authenticatedViaBetterAuth flag)', async () => {
+    // Authenticated request should succeed on protected endpoint
+    const result = await testHelper.rest('/security-test/user-only', {
+      method: 'GET',
+      statusCode: 200,
+      token: userToken,
+    });
+    expect(result.userId).toBeDefined();
+  });
+});
diff --git a/tests/stories/better-auth-module-registration.e2e-spec.ts b/tests/stories/better-auth-module-registration.e2e-spec.ts
new file mode 100644
index 0000000..b638804
--- /dev/null
+++ b/tests/stories/better-auth-module-registration.e2e-spec.ts
@@ -0,0 +1,361 @@
+/**
+ * Story: BetterAuth Module Registration
+ *
+ * Tests the three supported registration patterns for CoreBetterAuthModule:
+ *
+ * 1. Safety Net: Duplicate forRoot() calls don't crash, warning is logged
+ * 2. Config-based Controller/Resolver (Pattern 2): Custom controller/resolver via config
+ * 3. autoRegister: false (Pattern 3): Project imports its own BetterAuth module
+ * 4. Security verification: @Roles() enforcement across all patterns
+ * 5. core-auth.module.ts bug fix: providers.concat instead of imports.concat
+ */
+
+import { Controller, Get, Module } from '@nestjs/common';
+import { Query, Resolver } from '@nestjs/graphql';
+import { NestExpressApplication } from '@nestjs/platform-express';
+import { ScheduleModule } from '@nestjs/schedule';
+import { Test, TestingModule } from '@nestjs/testing';
+import { Server } from 'http';
+import { Db, MongoClient } from 'mongodb';
+import { afterAll, beforeAll, describe, expect, it, vi } from 'vitest';
+
+import {
+  CoreBetterAuthController,
+  CoreBetterAuthModule,
+  CoreBetterAuthResolver,
+  CoreModule,
+  CurrentUser,
+  HttpExceptionLogFilter,
+  RoleEnum,
+  Roles,
+  TestGraphQLType,
+  TestHelper,
+} from '../../src';
+import envConfig from '../../src/config.env';
+import { Any } from '../../src/core/common/scalars/any.scalar';
+import { DateScalar } from '../../src/core/common/scalars/date.scalar';
+import { JSON as JSONScalar } from '../../src/core/common/scalars/json.scalar';
+import { CoreBetterAuthAuthModel } from '../../src/core/modules/better-auth/core-better-auth-auth.model';
+import { CronJobs } from '../../src/server/common/services/cron-jobs.service';
+
+// =================================================================================================
+// Custom Controller for Config-based pattern test (Pattern 2)
+// =================================================================================================
+
+@Controller('iam')
+class CustomIamController extends CoreBetterAuthController {
+  /**
+   * Custom endpoint to verify this controller is active (not the default one)
+   */
+  @Get('custom-controller-check')
+  @Roles(RoleEnum.S_EVERYONE)
+  customControllerCheck() {
+    return { active: true, controller: 'CustomIamController' };
+  }
+}
+
+// =================================================================================================
+// Custom Resolver for Config-based pattern test (Pattern 2)
+// =================================================================================================
+
+@Resolver(() => CoreBetterAuthAuthModel)
+@Roles(RoleEnum.ADMIN)
+class CustomIamResolver extends CoreBetterAuthResolver {
+  @Query(() => Boolean, { description: 'Custom resolver check', name: 'customResolverCheck' })
+  @Roles(RoleEnum.S_EVERYONE)
+  customResolverCheck(): boolean {
+    return true;
+  }
+}
+
+// =================================================================================================
+// Test Helper: Security Test Controller (for all patterns)
+// =================================================================================================
+
+@Controller('security-test')
+class SecurityTestController {
+  @Get('public')
+  @Roles(RoleEnum.S_EVERYONE)
+  getPublic() {
+    return { access: 'public' };
+  }
+
+  @Get('user-only')
+  @Roles(RoleEnum.S_USER)
+  getUserOnly(@CurrentUser() user: any) {
+    return { access: 'user-only', userId: user?.id };
+  }
+
+  @Get('admin-only')
+  @Roles(RoleEnum.ADMIN)
+  getAdminOnly(@CurrentUser() user: any) {
+    return { access: 'admin-only', userId: user?.id };
+  }
+
+  @Get('no-one')
+  @Roles(RoleEnum.S_NO_ONE)
+  getNoOne() {
+    return { access: 'no-one' };
+  }
+}
+
+// =================================================================================================
+// Helper functions
+// =================================================================================================
+
+const generateTestEmail = (prefix: string): string => {
+  return `reg-test-${prefix}-${Date.now()}-${Math.random().toString(36).substring(2, 8)}@test.com`;
+};
+
+// =================================================================================================
+// Test Group 1: Safety Net (duplicate forRoot() detection)
+// =================================================================================================
+
+describe('Story: BetterAuth Module Registration', () => {
+  describe('1. Safety Net: Duplicate forRoot() detection', () => {
+    afterAll(() => {
+      CoreBetterAuthModule.reset();
+    });
+
+    it('should not crash on duplicate forRoot() calls', () => {
+      CoreBetterAuthModule.reset();
+
+      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+      const loggerWarnSpy = vi.fn();
+      const originalWarn = (CoreBetterAuthModule as any).logger.warn;
+      (CoreBetterAuthModule as any).logger.warn = loggerWarnSpy;
+
+      try {
+        // First call - should work normally
+        const module1 = CoreBetterAuthModule.forRoot({
+          config: { enabled: true, secret: 'test-secret-that-is-at-least-32-chars-long!' },
+        });
+        expect(module1).toBeDefined();
+        expect(module1.module).toBe(CoreBetterAuthModule);
+
+        // Second call - should return cached module with warning
+        // Note: In VITEST environment, the safety net allows reinit
+        // so we test the caching mechanism differently
+        const module2 = CoreBetterAuthModule.forRoot({
+          config: { enabled: true, secret: 'test-secret-that-is-at-least-32-chars-long!' },
+        });
+        expect(module2).toBeDefined();
+        expect(module2.module).toBe(CoreBetterAuthModule);
+      } finally {
+        (CoreBetterAuthModule as any).logger.warn = originalWarn;
+        warnSpy.mockRestore();
+      }
+    });
+
+    it('should reset forRootCalled state via reset()', () => {
+      CoreBetterAuthModule.reset();
+
+      // After reset, forRoot() should work fresh
+      const module = CoreBetterAuthModule.forRoot({
+        config: { enabled: true, secret: 'test-secret-that-is-at-least-32-chars-long!' },
+      });
+      expect(module).toBeDefined();
+
+      // Reset again for clean state
+      CoreBetterAuthModule.reset();
+    });
+
+    it('should cache disabled module correctly', () => {
+      CoreBetterAuthModule.reset();
+
+      const module = CoreBetterAuthModule.forRoot({
+        config: false,
+      });
+      expect(module).toBeDefined();
+      expect(module.module).toBe(CoreBetterAuthModule);
+
+      CoreBetterAuthModule.reset();
+    });
+  });
+
+  // =================================================================================================
+  // Test Group 2: Config-based Controller/Resolver (Pattern 2)
+  // =================================================================================================
+
+  describe('2. Config-based Controller/Resolver (Pattern 2)', () => {
+    let app: NestExpressApplication;
+    let httpServer: Server;
+    let testHelper: TestHelper;
+    let mongoClient: MongoClient;
+    let db: Db;
+    let userEmail: string;
+    let userPassword: string;
+    let userToken: string;
+
+    beforeAll(async () => {
+      CoreBetterAuthModule.reset();
+
+      const testConfig = {
+        ...envConfig,
+        betterAuth: {
+          ...envConfig.betterAuth,
+          controller: CustomIamController,
+          emailVerification: false,
+          enabled: true,
+          resolver: CustomIamResolver,
+          signUpChecks: false,
+        },
+      };
+
+      @Module({
+        controllers: [SecurityTestController],
+        exports: [CoreModule],
+        imports: [
+          CoreModule.forRoot(testConfig),
+          ScheduleModule.forRoot(),
+        ],
+        providers: [Any, CronJobs, DateScalar, JSONScalar],
+      })
+      class ConfigBasedTestModule {}
+
+      const moduleFixture: TestingModule = await Test.createTestingModule({
+        imports: [ConfigBasedTestModule],
+      }).compile();
+
+      app = moduleFixture.createNestApplication<NestExpressApplication>();
+      app.useGlobalFilters(new HttpExceptionLogFilter());
+      await app.init();
+
+      httpServer = app.getHttpServer();
+      await new Promise<void>((resolve) => {
+        httpServer.listen(0, '127.0.0.1', () => resolve());
+      });
+      const port = (httpServer.address() as any).port;
+      testHelper = new TestHelper(app, `ws://127.0.0.1:${port}/graphql`);
+
+      mongoClient = new MongoClient('mongodb://127.0.0.1:27017');
+      await mongoClient.connect();
+      db = mongoClient.db('nest-server-local');
+
+      // Create a test user
+      userEmail = generateTestEmail('config-pattern');
+      userPassword = 'a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6test';
+
+      const signUp = await testHelper.rest('/iam/sign-up/email', {
+        method: 'POST',
+        payload: { email: userEmail, name: 'Config Pattern Test', password: userPassword },
+        statusCode: 201,
+      });
+      userToken = signUp.token;
+    }, 60000);
+
+    afterAll(async () => {
+      // Cleanup test data
+      if (db) {
+        await db.collection('users').deleteMany({ email: { $regex: /^reg-test-config-pattern/ } });
+        await db.collection('session').deleteMany({});
+        await db.collection('account').deleteMany({});
+      }
+      if (mongoClient) {
+        await mongoClient.close();
+      }
+      if (httpServer) {
+        await new Promise<void>((resolve) => httpServer.close(() => resolve()));
+      }
+      if (app) {
+        await app.close();
+      }
+      CoreBetterAuthModule.reset();
+    });
+
+    it('should register CustomIamController (custom endpoint reachable)', async () => {
+      const result = await testHelper.rest('/iam/custom-controller-check', {
+        method: 'GET',
+        statusCode: 200,
+      });
+      expect(result.controller).toBe('CustomIamController');
+      expect(result.active).toBe(true);
+    });
+
+    it('should still have standard IAM endpoints via CustomIamController', async () => {
+      const result = await testHelper.rest('/iam/features', {
+        method: 'GET',
+        statusCode: 200,
+      });
+      expect(result).toBeDefined();
+    });
+
+    it('should register CustomIamResolver (custom query reachable)', async () => {
+      // testHelper.graphQl() with name returns data[name] directly, not the full response
+      const result = await testHelper.graphQl({
+        arguments: {},
+        name: 'customResolverCheck',
+        type: TestGraphQLType.QUERY,
+      });
+      expect(result).toBe(true);
+    });
+
+    // Security Tests
+    it('should enforce @Roles(S_EVERYONE) — 200 without auth', async () => {
+      const result = await testHelper.rest('/security-test/public', {
+        method: 'GET',
+        statusCode: 200,
+      });
+      expect(result.access).toBe('public');
+    });
+
+    it('should enforce @Roles(S_USER) — 401 without auth', async () => {
+      await testHelper.rest('/security-test/user-only', {
+        method: 'GET',
+        statusCode: 401,
+      });
+    });
+
+    it('should enforce @Roles(S_USER) — 200 with auth', async () => {
+      const result = await testHelper.rest('/security-test/user-only', {
+        method: 'GET',
+        statusCode: 200,
+        token: userToken,
+      });
+      expect(result.access).toBe('user-only');
+      expect(result.userId).toBeDefined();
+    });
+
+    it('should enforce @Roles(ADMIN) — 403 without admin role', async () => {
+      await testHelper.rest('/security-test/admin-only', {
+        method: 'GET',
+        statusCode: 403,
+        token: userToken,
+      });
+    });
+
+    it('should enforce @Roles(S_NO_ONE) — 401 always', async () => {
+      // S_NO_ONE throws UnauthorizedException (401) in RolesGuard, not ForbiddenException (403)
+      await testHelper.rest('/security-test/no-one', {
+        method: 'GET',
+        statusCode: 401,
+        token: userToken,
+      });
+    });
+  });
+
+  // =================================================================================================
+  // Test Group 3: autoRegister: false (Pattern 3)
+  // See: tests/stories/better-auth-autoregister-false.e2e-spec.ts (separate file
+  // because NestJS GraphQL schema generation has process-level side effects)
+  // =================================================================================================
+
+  // =================================================================================================
+  // Test Group 4: core-auth.module.ts bug fix verification
+  // =================================================================================================
+
+  describe('4. core-auth.module.ts bug fix: providers = providers.concat()', () => {
+    it('should use providers.concat, not imports.concat', async () => {
+      // Read the file and verify the fix is applied
+      const fs = await import('fs');
+      const content = fs.readFileSync(
+        require.resolve('../../src/core/modules/auth/core-auth.module.ts'),
+        'utf-8',
+      );
+      // The bug was: providers = imports.concat(options.providers)
+      // The fix is: providers = providers.concat(options.providers)
+      expect(content).toContain('providers = providers.concat(options.providers)');
+      expect(content).not.toContain('providers = imports.concat(options.providers)');
+    });
+  });
+});