@lenne.tech/nest-server 11.21.2 → 11.22.0

package/.claude/rules/architecture.md

@@ -0,0 +1,79 @@
+# Code Architecture
+
+## Framework Stack
+
+- **NestJS** - Server framework
+- **GraphQL** - API layer (Apollo Server)
+- **MongoDB** - Database (Mongoose ODM)
+
+## Two-Layer Structure
+
+1. **Core Layer** (`src/core/`) - Reusable framework components (exported to consumers)
+2. **Server Layer** (`src/server/`) - Internal test/demo implementation (not exported)
+
+## Core Module (`src/core.module.ts`)
+
+- Dynamic module providing base functionality
+- Configures GraphQL with Apollo Server (can be disabled via `graphQl: false`), MongoDB with Mongoose
+- Provides global services: ConfigService, EmailService, TemplateService
+- Sets up security interceptors, validation pipes, complexity plugins (when GraphQL enabled)
+- Handles GraphQL subscriptions with authentication
+
+## Configuration System (`src/config.env.ts`)
+
+Environment-based configuration (development, local, production) with multiple sources:
+
+- Direct environment variables in config file
+- `NEST_SERVER_CONFIG` JSON environment variable
+- `NSC__*` prefixed single environment variables
+
+Key areas: JWT, MongoDB, GraphQL, email, security, static assets
+
+## Core Common Components (`src/core/common/`)
+
+| Type | Components |
+|------|------------|
+| **Decorators** | `@Restricted()`, `@Roles()`, `@CurrentUser()`, `@UnifiedField()` |
+| **Helpers** | Database, GraphQL, filtering, validation utilities |
+| **Security** | Response/security interceptors, input validation pipes |
+| **Scalars** | Custom GraphQL scalars (Date, JSON, Any) |
+| **Services** | CRUD operations, email (Mailjet/SMTP), template rendering |
+
+## Core Modules (`src/core/modules/`)
+
+| Module | Purpose |
+|--------|---------|
+| **Auth** | JWT authentication, refresh tokens, role-based access |
+| **BetterAuth** | Modern auth integration (2FA, Passkey, Social) |
+| **ErrorCode** | Centralized error codes with unique identifiers |
+| **File** | File upload/download with GridFS storage |
+| **HealthCheck** | Application health monitoring |
+| **Migrate** | Database migration utilities |
+| **SystemSetup** | Initial admin creation for fresh deployments |
+| **Tus** | Resumable file uploads via tus.io protocol |
+| **User** | Core user management functionality |
+
+## Security Implementation
+
+- `@Restricted()` - Field-level access control
+- `@Roles()` - Method-level authorization
+- `CheckResponseInterceptor` - Filters restricted fields
+- `CheckSecurityInterceptor` - Processes `securityCheck()` methods
+
+## Model Inheritance
+
+- `CorePersistenceModel` - Base for database entities
+- `CoreModel` - Base for GraphQL types
+- Automatic ID handling with custom Mongoose plugin
+
+## Input Validation
+
+- `MapAndValidatePipe` - Automatic validation with inheritance-aware checking
+- `@UnifiedField()` - Single decorator for GraphQL, Swagger, and validation (replaces separate `@Field`, `@ApiProperty`, `@IsOptional`, etc.)
+- Automatic input property whitelisting — properties without `@UnifiedField` are stripped (default) or rejected
+- `@UnifiedField({ exclude: true })` — explicitly exclude a property from input (hidden from schema, rejected at runtime)
+- `@UnifiedField({ exclude: false })` — explicitly re-enable a property excluded by a parent class
+- Configurable via `security.mapAndValidatePipe.nonWhitelistedFields`: `'strip'` (default), `'error'`, or `false`
+- Custom decorator parameters (`@CurrentUser()`, `@RESTServiceOptions()`, etc.) and basic types (`String`, `Number`, etc.) are skipped — no validation or whitelist check
+- Recursive nested object/array checking via `nestedTypeRegistry`
+- Core args classes for filtering/pagination

package/.claude/rules/better-auth.md

@@ -0,0 +1,262 @@
+---
+paths: src/core/modules/better-auth/**
+---
+
+# Better-Auth Module Development Rules
+
+These rules apply when working in `src/core/modules/better-auth/`.
+
+## 1. Maximize Better-Auth Standard Compliance
+
+When making changes to the Better-Auth module:
+
+- **Stay as close as possible to Better-Auth's standard behavior**
+- **Minimize custom implementations** - use Better-Auth's built-in functionality wherever possible
+- **Never bypass or disable security mechanisms** provided by Better-Auth
+- **Maintain update compatibility** - changes must not break when Better-Auth releases updates
+
+### Rationale
+
+Better-Auth is a security-critical library. Custom implementations:
+- May introduce security vulnerabilities
+- Can break with Better-Auth updates
+- Add maintenance burden
+- May not benefit from Better-Auth's security audits
+
+### Example: Adapter Pattern
+
+When extending functionality (e.g., JWT mode for Passkey), prefer adapter patterns:
+
+```typescript
+// GOOD: Adapter that bridges to Better-Auth's mechanisms
+// - Uses Better-Auth's verificationToken
+// - Lets Better-Auth handle all WebAuthn logic
+// - Only bridges the cookie gap for JWT mode
+
+// BAD: Custom implementation that replaces Better-Auth logic
+// - Stores challenges separately
+// - Implements own verification
+// - Bypasses Better-Auth's security checks
+```
+
+## 2. Security-First Implementation
+
+All Better-Auth code must be implemented with maximum security:
+
+### Mandatory Security Measures
+
+1. **Cryptographically secure IDs** - Use `crypto.randomBytes(32)` for tokens/IDs
+2. **TTL-based expiration** - All temporary data must have automatic cleanup
+3. **One-time use** - Tokens/challenges must be deleted after use
+4. **Secrets protection** - Never expose internal tokens to clients
+5. **Cookie signing** - Use proper HMAC signatures for cookies
+
+### Security Review Checklist
+
+Before completing any Better-Auth changes:
+
+- [ ] No secrets/tokens exposed to client (only opaque IDs)
+- [ ] All temporary data has TTL-based expiration
+- [ ] One-time tokens are deleted after use
+- [ ] Cryptographically secure random generation used
+- [ ] No OWASP Top 10 vulnerabilities introduced
+- [ ] Cookie signing uses proper HMAC with application secret
+- [ ] Rate limiting considered for authentication endpoints
+- [ ] Input validation on all user-supplied data
+
+### Example: Challenge Storage
+
+```typescript
+// Security measures applied:
+// 1. challengeId: 256-bit entropy (crypto.randomBytes(32))
+// 2. verificationToken: never sent to client
+// 3. TTL index: automatic MongoDB cleanup
+// 4. One-time use: deleted after verification
+// 5. User binding: challenges tied to specific user
+```
+
+## 3. Comprehensive Testing Requirements
+
+All Better-Auth changes require comprehensive tests:
+
+### Test Requirements
+
+1. **New functionality tests** - Cover all new features completely
+2. **Security tests** - Verify authentication/authorization works correctly
+3. **Edge case tests** - Token expiration, invalid input, race conditions
+4. **Regression tests** - Existing tests must pass (adapt if needed)
+
+### Pre-Commit Checklist
+
+Before completing any Better-Auth changes:
+
+```bash
+# All tests must pass
+pnpm test
+
+# Specific test file for targeted changes
+pnpm test -- tests/stories/better-auth-*.ts
+```
+
+### Test Categories for Better-Auth
+
+| Category | Focus | Example Tests |
+|----------|-------|---------------|
+| Authentication | Login/logout flows | `better-auth-api.story.test.ts` |
+| Authorization | Role-based access | `better-auth-rest-security.e2e-spec.ts` |
+| Security | Token validation, rate limiting | `better-auth-rate-limit.story.test.ts` |
+| Integration | Module initialization | `better-auth-integration.story.test.ts` |
+| Plugins | 2FA, Passkey, Social Login | `better-auth-plugins.story.test.ts` |
+
+### Adapting Existing Tests
+
+When changes affect existing test expectations:
+
+1. **Understand why** the test was written that way
+2. **Verify the change is correct** - not breaking intended behavior
+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)` |
+| **Overrides Parameter** (recommended) | Custom Controller/Resolver | `CoreModule.forRoot(envConfig, { betterAuth: { controller, resolver } })` |
+| **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 Overrides Parameter (Pattern 2) - pass `{ betterAuth: { controller, resolver } }` as second arg to `CoreModule.forRoot()`
+   - 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. Use the `overrides` parameter on `CoreModule.forRoot()` (Pattern 2): `CoreModule.forRoot(envConfig, { betterAuth: { controller, resolver } })`
+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 |
+|-----------|-------------|
+| 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 |

package/.claude/rules/configurable-features.md

@@ -0,0 +1,308 @@
+# Configurable Features Pattern
+
+This document describes the standard pattern for implementing optional, configurable features in @lenne.tech/nest-server.
+
+## "Presence Implies Enabled" Pattern
+
+When implementing configurable features, follow this pattern for activation logic:
+
+### Rules
+
+1. **No configuration** (`undefined` or `null`): Feature is **disabled** (backward compatible)
+2. **Empty object** (`{}`): Feature is **enabled** with all default values
+3. **Partial configuration** (`{ max: 5 }`): Feature is **enabled**, missing values use defaults
+4. **Explicit disable** (`{ enabled: false, ... }`): Feature is **disabled**, allows pre-configuration
+
+### Benefits
+
+- **Backward Compatible**: Existing projects without config continue to work unchanged
+- **Efficient**: No need to set `enabled: true` redundantly when already providing config
+- **Flexible**: Can pre-configure without activating via `enabled: false`
+- **Intuitive**: Providing a config object signals intent to use the feature
+
+### Implementation Example
+
+```typescript
+interface IFeatureConfig {
+  enabled?: boolean;  // Optional - presence of config implies true
+  max?: number;
+  windowSeconds?: number;
+}
+
+const DEFAULT_CONFIG: Required<IFeatureConfig> = {
+  enabled: false,  // Default is false, but overridden by presence
+  max: 10,
+  windowSeconds: 60,
+};
+
+class FeatureService {
+  private config: Required<IFeatureConfig> = DEFAULT_CONFIG;
+
+  /**
+   * Configure the feature
+   *
+   * Follows the "presence implies enabled" pattern:
+   * - If config is undefined/null: feature stays disabled (backward compatible)
+   * - If config is an object (even empty {}): feature is enabled by default
+   * - Unless `enabled: false` is explicitly set
+   */
+  configure(config: IFeatureConfig | undefined | null): void {
+    // No config = stay disabled (backward compatible)
+    if (config === undefined || config === null) {
+      return;
+    }
+
+    // Presence of config implies enabled, unless explicitly disabled
+    const enabled = config.enabled !== false;
+
+    this.config = {
+      ...DEFAULT_CONFIG,
+      ...config,
+      enabled,
+    };
+  }
+}
+```
+
+### Usage Examples
+
+```typescript
+// config.env.ts
+
+// Feature disabled (no config)
+// rateLimit: undefined  // or just don't define it
+
+// Feature enabled with all defaults
+auth: {
+  rateLimit: {}
+}
+
+// Feature enabled with custom max
+auth: {
+  rateLimit: { max: 20 }
+}
+
+// Feature enabled with full configuration
+auth: {
+  rateLimit: {
+    max: 10,
+    windowSeconds: 60,
+    message: 'Too many requests'
+  }
+}
+
+// Pre-configured but disabled (for testing or gradual rollout)
+auth: {
+  rateLimit: {
+    enabled: false,
+    max: 10,
+    windowSeconds: 60
+  }
+}
+```
+
+## Boolean Shorthand Pattern
+
+For simple enable/disable scenarios, support `boolean | object` configuration:
+
+### Rules
+
+1. **`true`**: Feature is **enabled** with all default values
+2. **`false`**: Feature is **disabled**
+3. **`{}`**: Feature is **enabled** with all default values (same as `true`)
+4. **`{ option: value }`**: Feature is **enabled** with custom settings
+5. **`{ enabled: false }`**: Feature is **disabled** (allows pre-configuration)
+6. **`undefined`**: Feature is **disabled** (default)
+
+### Benefits
+
+- **Concise**: `jwt: true` instead of `jwt: {}`
+- **Readable**: Clear intent at a glance
+- **Flexible**: Can still use objects for customization
+
+### Implementation Example
+
+```typescript
+// Interface definition
+interface IBetterAuth {
+  jwt?: boolean | IBetterAuthJwtConfig;
+  twoFactor?: boolean | IBetterAuthTwoFactorConfig;
+  passkey?: boolean | IBetterAuthPasskeyConfig;
+}
+
+interface IBetterAuthJwtConfig {
+  enabled?: boolean;
+  expiresIn?: string;
+}
+
+// Helper functions
+function isPluginEnabled<T extends { enabled?: boolean }>(
+  config: boolean | T | undefined
+): boolean {
+  if (config === undefined) return false;
+  if (typeof config === 'boolean') return config;
+  return config.enabled !== false;
+}
+
+function getPluginConfig<T extends { enabled?: boolean }>(
+  config: boolean | T | undefined
+): T | undefined {
+  if (!isPluginEnabled(config)) return undefined;
+  if (typeof config === 'boolean') return {} as T;
+  return config;
+}
+
+// Usage in build logic
+const jwtConfig = getPluginConfig(config.jwt);
+if (jwtConfig) {
+  plugins.push(jwt({ expirationTime: jwtConfig.expiresIn || '15m' }));
+}
+```
+
+### Usage Examples
+
+```typescript
+// config.env.ts
+
+betterAuth: {
+  // Boolean shorthand - enable with defaults
+  jwt: true,
+  twoFactor: true,
+  passkey: true,
+}
+
+// Equivalent to:
+betterAuth: {
+  jwt: {},
+  twoFactor: {},
+  passkey: {},
+}
+
+// Mixed - some with defaults, some customized
+betterAuth: {
+  jwt: true,                        // Enable with defaults
+  twoFactor: { appName: 'My App' }, // Enable with custom settings
+  passkey: false,                   // Explicitly disabled
+}
+
+// Pre-configured but disabled
+betterAuth: {
+  jwt: { enabled: false, expiresIn: '1h' }, // Ready to enable later
+}
+```
+
+## Applied Features
+
+This pattern is currently applied to:
+
+| Feature | Config Path | Pattern | Default Values |
+|---------|-------------|---------|----------------|
+| Legacy Auth Rate Limiting | `auth.rateLimit` | Presence Implies Enabled | `max: 10`, `windowSeconds: 60` |
+| BetterAuth Rate Limiting | `betterAuth.rateLimit` | Presence Implies Enabled | `max: 10`, `windowSeconds: 60` |
+| BetterAuth JWT Plugin | `betterAuth.jwt` | Boolean Shorthand | `expiresIn: '15m'` |
+| BetterAuth 2FA Plugin | `betterAuth.twoFactor` | Boolean Shorthand | `appName: 'Nest Server'` |
+| BetterAuth Passkey Plugin | `betterAuth.passkey` | Boolean Shorthand | `rpName: 'Nest Server'` |
+| BetterAuth Cross-Subdomain Cookies | `betterAuth.crossSubDomainCookies` | Boolean Shorthand | `domain: auto (appUrl → baseUrl without api. prefix)` |
+| BetterAuth Disable Sign-Up | `betterAuth.emailAndPassword.disableSignUp` | Explicit Boolean | `false` (sign-up enabled) |
+| System Setup | `systemSetup` | Enabled by Default (when BetterAuth active) | `initialAdmin: undefined` |
+| GraphQL | `graphQl` | Explicit Disable (`false`) | Enabled (full GraphQL stack) |
+| Mongoose Password Plugin | `security.mongoosePasswordPlugin` | Boolean Shorthand | `true` (enabled), `skipPatterns: []` |
+| Mongoose Role Guard Plugin | `security.mongooseRoleGuardPlugin` | Boolean Shorthand | `true` (enabled), `allowedRoles: []`. Bypass: `RequestContext.runWithBypassRoleGuard()` or `force: true` |
+| Mongoose Audit Fields Plugin | `security.mongooseAuditFieldsPlugin` | Boolean Shorthand | `true` (enabled) |
+| Response Model Interceptor | `security.responseModelInterceptor` | Boolean Shorthand | `true` (enabled), `debug: false` |
+| Translate Response Interceptor | `security.translateResponseInterceptor` | Boolean Shorthand | `true` (enabled) |
+| Secret Fields Removal | `security.secretFields` | Array | `['password', 'verificationToken', ...]` |
+| Multi-Tenancy | `multiTenancy` | Presence Implies Enabled | `headerName: 'x-tenant-id'`, `membershipModel: 'TenantMember'`, `adminBypass: true`, `excludeSchemas: []`, `roleHierarchy: { member: 1, manager: 2, owner: 3 }`, `cacheTtlMs: 30000` (0 disables, process-local). System roles (`S_EVERYONE`, `S_USER`, `S_VERIFIED`) are checked as OR alternatives before real roles; method-level system roles take precedence; membership validated for context when system role grants access + header present. Hierarchy roles use level comparison, normal roles use exact match. Use `DefaultHR` or `createHierarchyRoles()` for type-safe role constants. Bypass: `RequestContext.runWithBypassTenantGuard()`. Cache invalidation: `CoreTenantGuard.invalidateUser(userId)` / `invalidateAll()` |
+| BetterAuth Tenant Skip | `betterAuth.skipTenantCheck` | Explicit Boolean | `true` (default). When `true` and no `X-Tenant-Id` header is sent, IAM endpoints (controller + resolver) skip `CoreTenantGuard` tenant validation. When header IS present, normal membership validation runs regardless. Set `false` for tenant-aware auth scenarios (subdomain-based, invite links, SSO per tenant) |
+
+## Module Override Pattern (via `ICoreModuleOverrides`)
+
+For replacing default controllers, resolvers, or services of auto-registered core modules.
+
+### Why a separate `overrides` parameter?
+
+NestJS registers controllers at module scan time — there is no mechanism to replace them after registration.
+When `CoreModule.forRoot()` auto-registers a module (e.g., ErrorCodeModule), the only way to use a custom controller
+is to pass it **before** registration happens. A separate `overrides` parameter on `CoreModule.forRoot()` keeps
+class references (code) cleanly separated from environment configuration (strings/numbers).
+
+### Usage
+
+```typescript
+// IAM-only mode
+CoreModule.forRoot(envConfig, {
+  errorCode: { controller: ErrorCodeController, service: ErrorCodeService },
+  betterAuth: { resolver: BetterAuthResolver },
+})
+
+// Legacy mode
+CoreModule.forRoot(CoreAuthService, AuthModule.forRoot(envConfig.jwt), envConfig, {
+  errorCode: { controller: ErrorCodeController, service: ErrorCodeService },
+})
+```
+
+### Available Override Fields
+
+| Module | Fields | Description |
+|--------|--------|-------------|
+| `errorCode` | `controller`, `service` | Custom error code endpoint and/or service |
+| `betterAuth` | `controller`, `resolver` | Custom IAM REST controller and/or GraphQL resolver |
+
+### Rules
+
+1. Overrides take precedence over `betterAuth.controller`/`resolver` in config (backward compatible)
+2. Only auto-registered modules are affected — `autoRegister: false` modules are imported separately
+3. The `ICoreModuleOverrides` interface enforces type safety per module
+
+### Alternative: `autoRegister: false`
+
+For complex setups requiring additional providers or a custom module structure, disable auto-registration
+and import the module separately:
+
+```typescript
+// config.env.ts
+errorCode: { autoRegister: false }
+betterAuth: { autoRegister: false }
+
+// server.module.ts
+@Module({
+  imports: [
+    CoreModule.forRoot(envConfig),
+    ErrorCodeModule.forRoot({ controller: MyController, service: MyService }),
+    BetterAuthModule.forRoot({ controller: MyController, resolver: MyResolver }),
+  ],
+})
+```
+
+## Checklist for New Configurable Features
+
+When adding a new configurable feature:
+
+### For "Presence Implies Enabled" Pattern:
+
+- [ ] Define interface with `enabled?: boolean` as optional property
+- [ ] Set `enabled: false` in DEFAULT_CONFIG
+- [ ] Implement "presence implies enabled" logic in configure method
+- [ ] Document all default values in interface JSDoc
+- [ ] Add tests for: undefined config, empty object, partial config, explicit disable
+
+### For "Boolean Shorthand" Pattern:
+
+- [ ] Define separate interface for config options (e.g., `IBetterAuthJwtConfig`)
+- [ ] Use union type: `property?: boolean | IPropertyConfig`
+- [ ] Implement `isPluginEnabled()` helper for boolean/object handling
+- [ ] Implement `getPluginConfig()` helper to normalize to object
+- [ ] Add tests for: `true`, `false`, `{}`, `{ option: value }`, `{ enabled: false }`, `undefined`
+
+### For "Module Override" Pattern:
+
+- [ ] Add override fields to `ICoreModuleOverrides` interface
+- [ ] Pass overrides through in `CoreModule.forRoot()` to the module's `forRoot()`
+- [ ] Ensure the module's `forRoot()` accepts controller/resolver/service parameters
+- [ ] Update this document with the new override fields
+- [ ] Update module's INTEGRATION-CHECKLIST.md
+
+### For Both Patterns:
+
+- [ ] Update this document with the new feature
+- [ ] Export new interfaces in `src/index.ts` (if needed)