@lenne.tech/nest-server 11.6.2 → 11.7.1

package/src/core/modules/auth/services/legacy-auth-rate-limiter.service.ts

@@ -0,0 +1,283 @@
+import { Injectable, Logger, OnModuleInit } from '@nestjs/common';
+
+import { IAuthRateLimit } from '../../../common/interfaces/server-options.interface';
+import { ConfigService } from '../../../common/services/config.service';
+
+/**
+ * Rate limit entry for tracking requests
+ */
+interface RateLimitEntry {
+  count: number;
+  resetTime: number;
+}
+
+/**
+ * Result of a rate limit check
+ *
+ * @internal This interface is identical to BetterAuthRateLimiter's RateLimitResult.
+ * Use the exported RateLimitResult from better-auth module if needed externally.
+ */
+interface RateLimitResult {
+  /** Whether the request is allowed */
+  allowed: boolean;
+  /** Current request count in the window */
+  current: number;
+  /** Maximum requests allowed */
+  limit: number;
+  /** Number of remaining requests in the window */
+  remaining: number;
+  /** Seconds until the rate limit resets */
+  resetIn: number;
+}
+
+/**
+ * Default rate limiting configuration
+ */
+const DEFAULT_CONFIG: Required<IAuthRateLimit> = {
+  enabled: false,
+  max: 10,
+  message: 'Too many requests, please try again later.',
+  windowSeconds: 60,
+};
+
+/**
+ * In-memory rate limiter for Legacy Auth endpoints
+ *
+ * This service provides rate limiting to protect against brute-force attacks
+ * on authentication endpoints. It uses an in-memory store with automatic cleanup.
+ *
+ * Features:
+ * - Configurable request limits and time windows
+ * - Automatic cleanup of expired entries
+ * - IP-based tracking
+ * - Auto-configuration from ConfigService
+ *
+ * Configuration via config.env.ts:
+ * ```typescript
+ * auth: {
+ *   rateLimit: {
+ *     enabled: true,
+ *     max: 10,
+ *     windowSeconds: 60,
+ *     message: 'Too many login attempts, please try again later.',
+ *   }
+ * }
+ * ```
+ *
+ * @since 11.7.x
+ */
+@Injectable()
+export class LegacyAuthRateLimiter implements OnModuleInit {
+  private readonly logger = new Logger(LegacyAuthRateLimiter.name);
+  private readonly store = new Map<string, RateLimitEntry>();
+  private config: Required<IAuthRateLimit> = DEFAULT_CONFIG;
+  private cleanupInterval: NodeJS.Timeout | null = null;
+
+  constructor() {
+    // Start cleanup interval (every 5 minutes)
+    this.startCleanup();
+  }
+
+  /**
+   * Auto-configure from ConfigService on module initialization
+   */
+  onModuleInit(): void {
+    const rateLimitConfig = ConfigService.getFastButReadOnly<IAuthRateLimit>('auth.rateLimit');
+    if (rateLimitConfig) {
+      this.configure(rateLimitConfig);
+    }
+  }
+
+  /**
+   * Configure the rate limiter
+   *
+   * Follows the "presence implies enabled" pattern:
+   * - If config is undefined/null: rate limiting is disabled (backward compatible)
+   * - If config is an object (even empty {}): rate limiting is enabled by default
+   * - Unless `enabled: false` is explicitly set to disable while pre-configuring
+   *
+   * @param config - Rate limiting configuration (presence implies enabled)
+   */
+  configure(config: IAuthRateLimit | null | undefined): void {
+    // If config is not provided, rate limiting stays 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,
+    };
+
+    if (this.config.enabled) {
+      this.logger.log(
+        `Legacy Auth rate limiting enabled: ${this.config.max} requests per ${this.config.windowSeconds}s`,
+      );
+    }
+  }
+
+  /**
+   * Check if a request is allowed under the rate limit
+   *
+   * @param ip - Client IP address
+   * @param endpoint - Endpoint name (e.g., 'signIn', 'signUp')
+   * @returns Rate limit check result
+   */
+  check(ip: string, endpoint: string): RateLimitResult {
+    // If rate limiting is disabled, always allow
+    if (!this.config.enabled) {
+      return {
+        allowed: true,
+        current: 0,
+        limit: Infinity,
+        remaining: Infinity,
+        resetIn: 0,
+      };
+    }
+
+    const limit = this.config.max;
+    const key = `${ip}:${endpoint}`;
+    const now = Date.now();
+
+    // Get or create entry
+    let entry = this.store.get(key);
+
+    if (!entry || now >= entry.resetTime) {
+      // Create new entry or reset expired one
+      entry = {
+        count: 1,
+        resetTime: now + this.config.windowSeconds * 1000,
+      };
+      this.store.set(key, entry);
+
+      return {
+        allowed: true,
+        current: 1,
+        limit,
+        remaining: limit - 1,
+        resetIn: this.config.windowSeconds,
+      };
+    }
+
+    // Increment count
+    entry.count++;
+
+    const resetIn = Math.ceil((entry.resetTime - now) / 1000);
+    const allowed = entry.count <= limit;
+    const remaining = Math.max(0, limit - entry.count);
+
+    if (!allowed) {
+      this.logger.warn(`Rate limit exceeded for IP ${this.maskIp(ip)} on ${endpoint}: ${entry.count}/${limit}`);
+    }
+
+    return {
+      allowed,
+      current: entry.count,
+      limit,
+      remaining,
+      resetIn,
+    };
+  }
+
+  /**
+   * Get the configured error message
+   */
+  getMessage(): string {
+    return this.config.message;
+  }
+
+  /**
+   * Check if rate limiting is enabled
+   */
+  isEnabled(): boolean {
+    return this.config.enabled;
+  }
+
+  /**
+   * Reset rate limit for a specific IP (useful for testing or admin override)
+   *
+   * @param ip - Client IP address
+   */
+  reset(ip: string): void {
+    for (const key of this.store.keys()) {
+      if (key.startsWith(`${ip}:`)) {
+        this.store.delete(key);
+      }
+    }
+  }
+
+  /**
+   * Clear all rate limit entries (useful for testing)
+   */
+  clear(): void {
+    this.store.clear();
+  }
+
+  /**
+   * Get statistics about the rate limiter
+   */
+  getStats(): { activeEntries: number; enabled: boolean } {
+    return {
+      activeEntries: this.store.size,
+      enabled: this.config.enabled,
+    };
+  }
+
+  /**
+   * Stop the cleanup interval (for graceful shutdown)
+   */
+  onModuleDestroy(): void {
+    if (this.cleanupInterval) {
+      clearInterval(this.cleanupInterval);
+      this.cleanupInterval = null;
+    }
+  }
+
+  /**
+   * Mask IP address for logging (privacy)
+   */
+  private maskIp(ip: string): string {
+    if (ip.includes('.')) {
+      // IPv4: show first two octets
+      const parts = ip.split('.');
+      return `${parts[0]}.${parts[1]}.*.*`;
+    }
+    // IPv6: show first segment
+    const parts = ip.split(':');
+    return `${parts[0]}:****`;
+  }
+
+  /**
+   * Start periodic cleanup of expired entries
+   */
+  private startCleanup(): void {
+    // Clean up every 5 minutes
+    this.cleanupInterval = setInterval(
+      () => {
+        const now = Date.now();
+        let cleaned = 0;
+
+        for (const [key, entry] of this.store.entries()) {
+          if (now >= entry.resetTime) {
+            this.store.delete(key);
+            cleaned++;
+          }
+        }
+
+        if (cleaned > 0) {
+          this.logger.debug(`Cleaned up ${cleaned} expired rate limit entries`);
+        }
+      },
+      5 * 60 * 1000,
+    );
+
+    // Prevent the interval from keeping the process alive
+    if (this.cleanupInterval.unref) {
+      this.cleanupInterval.unref();
+    }
+  }
+}

package/src/core/modules/better-auth/INTEGRATION-CHECKLIST.md

@@ -0,0 +1,254 @@
+# BetterAuth Integration Checklist
+
+**For integrating BetterAuth into projects using `@lenne.tech/nest-server`.**
+
+> **Estimated time:** 10-15 minutes
+
+---
+
+## Choose Your Scenario
+
+| Scenario | Use When | CoreModule Signature | Steps |
+|----------|----------|---------------------|-------|
+| **New Project (IAM-Only)** | Starting fresh, no legacy users | `CoreModule.forRoot(envConfig)` | 1-6 |
+| **Existing Project (Migration)** | Have legacy users to migrate | `CoreModule.forRoot(AuthService, AuthModule, envConfig)` | 1-6 |
+
+**Key difference:** New projects disable Legacy endpoints, existing projects keep them enabled during migration.
+
+---
+
+## Reference Implementation
+
+All files you need to create are already implemented as reference in the package:
+
+**Local (in your node_modules):**
+```
+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
+
+**Also see the UserService integration:**
+- Local: `node_modules/@lenne.tech/nest-server/src/server/modules/user/user.service.ts`
+- GitHub: https://github.com/lenneTech/nest-server/blob/develop/src/server/modules/user/user.service.ts
+
+---
+
+## Required Files (Create in Order)
+
+### 1. BetterAuth Module
+**Create:** `src/server/modules/better-auth/better-auth.module.ts`
+**Copy from:** `node_modules/@lenne.tech/nest-server/src/server/modules/better-auth/better-auth.module.ts`
+
+---
+
+### 2. BetterAuth Controller
+**Create:** `src/server/modules/better-auth/better-auth.controller.ts`
+**Copy from:** `node_modules/@lenne.tech/nest-server/src/server/modules/better-auth/better-auth.controller.ts`
+
+---
+
+### 3. BetterAuth Resolver (CRITICAL!)
+**Create:** `src/server/modules/better-auth/better-auth.resolver.ts`
+**Copy from:** `node_modules/@lenne.tech/nest-server/src/server/modules/better-auth/better-auth.resolver.ts`
+
+**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`, `@UseGuards` decorators in the child class for the methods to appear in the GraphQL schema.
+
+---
+
+### 4. Update UserService (CRITICAL!)
+**Modify:** `src/server/modules/user/user.service.ts`
+**Reference:** `node_modules/@lenne.tech/nest-server/src/server/modules/user/user.service.ts`
+
+**Required changes:**
+
+1. Add import:
+   ```typescript
+   import { BetterAuthUserMapper } from '@lenne.tech/nest-server';
+   ```
+
+2. Add constructor parameter:
+   ```typescript
+   @Optional() private readonly betterAuthUserMapper?: BetterAuthUserMapper,
+   ```
+
+3. Pass to super() via options object:
+   ```typescript
+   super(configService, emailService, mainDbModel, mainModelConstructor, { betterAuthUserMapper });
+   ```
+
+**WHY is this critical?**
+The `BetterAuthUserMapper` enables bidirectional password synchronization:
+- User signs up via BetterAuth → password synced to Legacy Auth (bcrypt hash)
+- User changes password → synced between both systems
+- **Without this, users can only authenticate via ONE system!**
+
+---
+
+### 5. Update ServerModule
+**Modify:** `src/server/server.module.ts`
+**Reference:** `node_modules/@lenne.tech/nest-server/src/server/server.module.ts`
+
+#### For New Projects (IAM-Only) - Recommended:
+```typescript
+@Module({
+  imports: [
+    CoreModule.forRoot(envConfig),  // Simplified signature
+    BetterAuthModule.forRoot({
+      config: envConfig.betterAuth,
+      fallbackSecrets: [envConfig.jwt?.secret],
+    }),
+    // ... other modules
+  ],
+})
+export class ServerModule {}
+```
+
+#### For Existing Projects (Migration):
+```typescript
+@Module({
+  imports: [
+    CoreModule.forRoot(AuthService, AuthModule.forRoot(envConfig.jwt), envConfig),
+    BetterAuthModule.forRoot({
+      config: envConfig.betterAuth,
+      fallbackSecrets: [envConfig.jwt?.secret],
+    }),
+    // ... other modules
+  ],
+})
+export class ServerModule {}
+```
+
+---
+
+### 6. Update config.env.ts
+**Modify:** `src/config.env.ts`
+**Reference:** `node_modules/@lenne.tech/nest-server/src/config.env.ts`
+
+#### For New Projects (IAM-Only):
+```typescript
+const config = {
+  // Disable Legacy Auth endpoints
+  auth: {
+    legacyEndpoints: {
+      enabled: false,
+    },
+  },
+  // BetterAuth configuration
+  betterAuth: {
+    // enabled: true (default)
+    // basePath: '/iam' (default)
+    jwt: {},       // Enable JWT tokens
+    twoFactor: {}, // Enable 2FA
+    passkey: {},   // Enable Passkeys
+  },
+};
+```
+
+#### For Existing Projects (Migration):
+```typescript
+const config = {
+  // Keep Legacy Auth endpoints enabled during migration
+  auth: {
+    legacyEndpoints: {
+      enabled: true, // Default - can disable after migration
+    },
+  },
+  // BetterAuth configuration
+  betterAuth: {
+    // ... same as above
+  },
+};
+```
+
+---
+
+## Verification Checklist
+
+After integration, verify:
+
+- [ ] `npm run build` succeeds without errors
+- [ ] `npm test` passes
+- [ ] GraphQL Playground shows `betterAuthEnabled` query
+- [ ] REST endpoint `GET /iam/session` responds
+- [ ] Sign-up via BetterAuth creates user in database with `iamId`
+- [ ] Sign-in via BetterAuth works correctly
+
+### Additional checks for Migration scenario:
+- [ ] Sign-in via Legacy Auth works for BetterAuth-created users
+- [ ] Sign-in via BetterAuth works for Legacy-created users
+- [ ] `betterAuthMigrationStatus` query shows correct counts
+
+---
+
+## Common Mistakes
+
+| Mistake | Symptom | Fix |
+|---------|---------|-----|
+| Forgot to re-declare decorators in Resolver | GraphQL endpoints missing (404) | Copy resolver from reference, keep ALL decorators |
+| Forgot `BetterAuthUserMapper` in UserService | Auth systems not synced, users can't cross-authenticate | Add `@Optional()` parameter and pass to super() |
+| Missing `fallbackSecrets` in ServerModule | Session issues without explicit secret | Add `fallbackSecrets: [envConfig.jwt?.secret, ...]` |
+| Wrong `basePath` in config | 404 on BetterAuth endpoints | Ensure basePath matches controller (default: `/iam`) |
+| Using wrong CoreModule signature | Build errors or missing features | New projects: 1-parameter, Existing: 3-parameter |
+| AuthResolver override missing `checkLegacyGraphQLEnabled()` | Legacy endpoint disabling doesn't work (no HTTP 410) | Call `this.checkLegacyGraphQLEnabled('signIn')` in overrides |
+
+---
+
+## Important: AuthResolver Override Pattern
+
+If your project has a custom `AuthResolver` that extends `CoreAuthResolver` and overrides `signIn()` or `signUp()`, you **MUST** call the protected check method:
+
+```typescript
+// src/server/modules/auth/auth.resolver.ts
+@Mutation(() => Auth)
+override async signIn(...): Promise<Auth> {
+  this.checkLegacyGraphQLEnabled('signIn');  // Required!
+  const result = await this.authService.signIn(input, serviceOptions);
+  return this.processCookies(ctx, result);
+}
+```
+
+**WHY?** When `auth.legacyEndpoints.enabled: false`, this method throws `LegacyAuthDisabledException` (HTTP 410). Without this call, legacy endpoints remain accessible even when configured as disabled.
+
+See: `.claude/rules/module-inheritance.md` for the full pattern.
+
+---
+
+## Client-Side Configuration
+
+Clients must be configured to use the correct base path and hash passwords:
+
+```typescript
+// auth-client.ts (e.g., for Nuxt/Vue)
+import { createAuthClient } from 'better-auth/vue';
+import { sha256 } from '~/utils/crypto';
+
+const baseClient = createAuthClient({
+  baseURL: import.meta.env.VITE_API_URL,
+  basePath: '/iam',  // Must match server config
+  plugins: [...],
+});
+
+// Wrap signIn/signUp to hash passwords before sending
+export const authClient = {
+  ...baseClient,
+  signIn: {
+    ...baseClient.signIn,
+    email: async (params) => {
+      const hashedPassword = await sha256(params.password);
+      return baseClient.signIn.email({ ...params, password: hashedPassword });
+    },
+  },
+  // ... same for signUp, resetPassword, etc.
+};
+```
+
+---
+
+## Detailed Documentation
+
+For complete configuration options, API reference, and advanced topics:
+- **README.md:** `node_modules/@lenne.tech/nest-server/src/core/modules/better-auth/README.md`
+- **GitHub:** https://github.com/lenneTech/nest-server/blob/develop/src/core/modules/better-auth/README.md