@lenne.tech/nest-server 11.6.1 → 11.7.0

package/src/core/modules/better-auth/better-auth-auth.model.ts

@@ -0,0 +1,69 @@
+import { Field, ObjectType } from '@nestjs/graphql';
+
+import { Restricted } from '../../common/decorators/restricted.decorator';
+import { RoleEnum } from '../../common/enums/role.enum';
+import { BetterAuthSessionInfoModel, BetterAuthUserModel } from './better-auth-models';
+
+/**
+ * Better-Auth Authentication Response Model
+ *
+ * This model is returned by Better-Auth sign-in/sign-up mutations
+ * and provides a structure compatible with the existing auth system
+ * while supporting Better-Auth specific features like 2FA.
+ */
+@ObjectType({ description: 'Better-Auth Authentication Response' })
+@Restricted(RoleEnum.S_EVERYONE)
+export class BetterAuthAuthModel {
+  /**
+   * Whether the authentication was successful
+   */
+  @Field(() => Boolean, { description: 'Whether authentication was successful' })
+  success: boolean;
+
+  /**
+   * Whether 2FA verification is required
+   * When true, the client should prompt for 2FA code and call betterAuthVerify2FA
+   */
+  @Field(() => Boolean, {
+    description: 'Whether 2FA verification is required to complete sign-in',
+    nullable: true,
+  })
+  requiresTwoFactor?: boolean;
+
+  /**
+   * JWT token (only present if JWT plugin is enabled)
+   * Use this for Bearer token authentication
+   */
+  @Field(() => String, {
+    description: 'JWT token for Bearer authentication (if JWT plugin enabled)',
+    nullable: true,
+  })
+  token?: string;
+
+  /**
+   * Authenticated user
+   */
+  @Field(() => BetterAuthUserModel, {
+    description: 'Authenticated user',
+    nullable: true,
+  })
+  user?: BetterAuthUserModel;
+
+  /**
+   * Session information
+   */
+  @Field(() => BetterAuthSessionInfoModel, {
+    description: 'Session information',
+    nullable: true,
+  })
+  session?: BetterAuthSessionInfoModel;
+
+  /**
+   * Error message if authentication failed
+   */
+  @Field(() => String, {
+    description: 'Error message if authentication failed',
+    nullable: true,
+  })
+  error?: string;
+}

package/src/core/modules/better-auth/better-auth-models.ts

@@ -0,0 +1,140 @@
+import { Field, ObjectType } from '@nestjs/graphql';
+
+import { Restricted } from '../../common/decorators/restricted.decorator';
+import { RoleEnum } from '../../common/enums/role.enum';
+
+/**
+ * Better-Auth User Model for GraphQL
+ */
+@ObjectType({ description: 'Better-Auth User' })
+@Restricted(RoleEnum.S_EVERYONE)
+export class BetterAuthUserModel {
+  @Field(() => String, { description: 'User ID' })
+  id: string;
+
+  @Field(() => String, { description: 'IAM provider user ID (e.g., Better-Auth)', nullable: true })
+  iamId?: string;
+
+  @Field(() => String, { description: 'Email address' })
+  email: string;
+
+  @Field(() => String, { description: 'Display name', nullable: true })
+  name?: string;
+
+  @Field(() => Boolean, { description: 'Email verified status', nullable: true })
+  emailVerified?: boolean;
+
+  @Field(() => Boolean, { description: 'User verified status', nullable: true })
+  verified?: boolean;
+
+  @Field(() => [String], { description: 'User roles', nullable: true })
+  roles?: string[];
+}
+
+/**
+ * Better-Auth Session Model for GraphQL
+ */
+@ObjectType({ description: 'Better-Auth Session' })
+@Restricted(RoleEnum.S_USER)
+export class BetterAuthSessionModel {
+  @Field(() => String, { description: 'Session ID' })
+  id: string;
+
+  @Field(() => Date, { description: 'Session expiration date' })
+  expiresAt: Date;
+
+  @Field(() => BetterAuthUserModel, { description: 'Session user' })
+  user: BetterAuthUserModel;
+}
+
+/**
+ * Better-Auth Session Info (simplified for responses)
+ */
+@ObjectType({ description: 'Better-Auth Session Info' })
+@Restricted(RoleEnum.S_EVERYONE)
+export class BetterAuthSessionInfoModel {
+  @Field(() => String, { description: 'Session ID', nullable: true })
+  id?: string;
+
+  @Field(() => String, { description: 'Session token', nullable: true })
+  token?: string;
+
+  @Field(() => Date, { description: 'Session expiration date', nullable: true })
+  expiresAt?: Date;
+}
+
+/**
+ * Better-Auth 2FA Setup Model (returned when enabling 2FA)
+ */
+@ObjectType({ description: 'Better-Auth 2FA setup data' })
+@Restricted(RoleEnum.S_USER)
+export class BetterAuth2FASetupModel {
+  @Field(() => Boolean, { description: 'Whether the operation was successful' })
+  success: boolean;
+
+  @Field(() => String, { description: 'TOTP URI for QR code generation', nullable: true })
+  totpUri?: string;
+
+  @Field(() => [String], { description: 'Backup codes for account recovery', nullable: true })
+  backupCodes?: string[];
+
+  @Field(() => String, { description: 'Error message if failed', nullable: true })
+  error?: string;
+}
+
+/**
+ * Better-Auth Passkey Model
+ */
+@ObjectType({ description: 'Better-Auth Passkey' })
+@Restricted(RoleEnum.S_USER)
+export class BetterAuthPasskeyModel {
+  @Field(() => String, { description: 'Passkey ID' })
+  id: string;
+
+  @Field(() => String, { description: 'Passkey name', nullable: true })
+  name?: string;
+
+  @Field(() => String, { description: 'Credential ID' })
+  credentialId: string;
+
+  @Field(() => Date, { description: 'Creation date' })
+  createdAt: Date;
+}
+
+/**
+ * Better-Auth Passkey Registration Challenge
+ */
+@ObjectType({ description: 'Better-Auth Passkey registration challenge' })
+@Restricted(RoleEnum.S_USER)
+export class BetterAuthPasskeyChallengeModel {
+  @Field(() => Boolean, { description: 'Whether the operation was successful' })
+  success: boolean;
+
+  @Field(() => String, { description: 'Challenge data (JSON)', nullable: true })
+  challenge?: string;
+
+  @Field(() => String, { description: 'Error message if failed', nullable: true })
+  error?: string;
+}
+
+/**
+ * Better-Auth features status
+ */
+@ObjectType({ description: 'Better-Auth features status' })
+@Restricted(RoleEnum.S_EVERYONE)
+export class BetterAuthFeaturesModel {
+  @Field(() => Boolean, { description: 'Whether Better-Auth is enabled' })
+  enabled: boolean;
+
+  @Field(() => Boolean, { description: 'Whether JWT plugin is enabled' })
+  jwt: boolean;
+
+  @Field(() => Boolean, { description: 'Whether 2FA is enabled' })
+  twoFactor: boolean;
+
+  @Field(() => Boolean, { description: 'Whether Passkey is enabled' })
+  passkey: boolean;
+
+  @Field(() => [String], { description: 'List of enabled social providers' })
+  socialProviders: string[];
+}

package/src/core/modules/better-auth/better-auth-rate-limit.middleware.ts

@@ -0,0 +1,113 @@
+import { HttpException, HttpStatus, Injectable, NestMiddleware } from '@nestjs/common';
+import { NextFunction, Request, Response } from 'express';
+
+import { BetterAuthRateLimiter, RateLimitResult } from './better-auth-rate-limiter.service';
+import { BetterAuthService } from './better-auth.service';
+
+/**
+ * Middleware that applies rate limiting to Better-Auth endpoints
+ *
+ * This middleware:
+ * 1. Checks if rate limiting is enabled
+ * 2. Extracts the client IP address
+ * 3. Checks the rate limit for the current request
+ * 4. Returns 429 Too Many Requests if limit exceeded
+ * 5. Adds rate limit headers to the response
+ *
+ * Configuration is done via betterAuth.rateLimit in environment config.
+ *
+ * @example
+ * ```typescript
+ * // In config.env.ts
+ * betterAuth: {
+ *   enabled: true,
+ *   rateLimit: {
+ *     enabled: true,
+ *     max: 10,
+ *     windowSeconds: 60,
+ *   },
+ * }
+ * ```
+ */
+@Injectable()
+export class BetterAuthRateLimitMiddleware implements NestMiddleware {
+  constructor(
+    private readonly rateLimiter: BetterAuthRateLimiter,
+    private readonly betterAuthService: BetterAuthService,
+  ) {}
+
+  use(req: Request, res: Response, next: NextFunction) {
+    // Skip if Better-Auth is not enabled
+    if (!this.betterAuthService.isEnabled()) {
+      return next();
+    }
+
+    // Skip if rate limiting is not enabled
+    if (!this.rateLimiter.isEnabled()) {
+      return next();
+    }
+
+    // Get client IP
+    const ip = this.getClientIp(req);
+
+    // Get the path relative to basePath
+    const basePath = this.betterAuthService.getBasePath();
+    const path = req.path.startsWith(basePath) ? req.path.substring(basePath.length) : req.path;
+
+    // Check rate limit
+    const result = this.rateLimiter.check(ip, path);
+
+    // Add rate limit headers
+    this.addRateLimitHeaders(res, result);
+
+    // If not allowed, return 429
+    if (!result.allowed) {
+      throw new HttpException(
+        {
+          error: 'Too Many Requests',
+          message: this.rateLimiter.getMessage(),
+          retryAfter: result.resetIn,
+          statusCode: HttpStatus.TOO_MANY_REQUESTS,
+        },
+        HttpStatus.TOO_MANY_REQUESTS,
+      );
+    }
+
+    next();
+  }
+
+  /**
+   * Extract client IP address from request
+   * Handles proxied requests via X-Forwarded-For header
+   */
+  private getClientIp(req: Request): string {
+    // Check X-Forwarded-For header (for proxied requests)
+    const forwardedFor = req.headers['x-forwarded-for'];
+    if (forwardedFor) {
+      const ips = Array.isArray(forwardedFor) ? forwardedFor[0] : forwardedFor.split(',')[0];
+      return ips.trim();
+    }
+
+    // Check X-Real-IP header (nginx)
+    const realIp = req.headers['x-real-ip'];
+    if (realIp) {
+      return Array.isArray(realIp) ? realIp[0] : realIp;
+    }
+
+    // Fall back to connection remote address
+    return req.ip || req.socket?.remoteAddress || 'unknown';
+  }
+
+  /**
+   * Add standard rate limit headers to response
+   */
+  private addRateLimitHeaders(res: Response, result: RateLimitResult): void {
+    res.setHeader('X-RateLimit-Limit', result.limit.toString());
+    res.setHeader('X-RateLimit-Remaining', result.remaining.toString());
+    res.setHeader('X-RateLimit-Reset', result.resetIn.toString());
+
+    if (!result.allowed) {
+      res.setHeader('Retry-After', result.resetIn.toString());
+    }
+  }
+}

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

@@ -0,0 +1,326 @@
+import { Injectable, Logger } from '@nestjs/common';
+
+import { IBetterAuthRateLimit } from '../../common/interfaces/server-options.interface';
+
+/**
+ * Result of a rate limit check
+ */
+export 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;
+}
+
+/**
+ * Rate limit entry for tracking requests
+ */
+interface RateLimitEntry {
+  count: number;
+  resetTime: number;
+}
+
+/**
+ * Default rate limiting configuration
+ */
+const DEFAULT_CONFIG: Required<IBetterAuthRateLimit> = {
+  enabled: false,
+  max: 10,
+  message: 'Too many requests, please try again later.',
+  skipEndpoints: ['/session', '/callback'],
+  strictEndpoints: ['/sign-in', '/sign-up', '/forgot-password', '/reset-password'],
+  windowSeconds: 60,
+};
+
+/**
+ * In-memory rate limiter for Better-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
+ * - Stricter limits for sensitive endpoints (sign-in, sign-up, etc.)
+ * - Skip list for endpoints that don't need rate limiting
+ * - Automatic cleanup of expired entries
+ * - IP-based tracking
+ *
+ * @example
+ * ```typescript
+ * const result = rateLimiter.check('192.168.1.1', '/iam/sign-in');
+ * if (!result.allowed) {
+ *   throw new TooManyRequestsException(rateLimiter.getMessage());
+ * }
+ * ```
+ */
+@Injectable()
+export class BetterAuthRateLimiter {
+  private readonly logger = new Logger(BetterAuthRateLimiter.name);
+  private readonly store = new Map<string, RateLimitEntry>();
+  private config: Required<IBetterAuthRateLimit> = DEFAULT_CONFIG;
+  private cleanupInterval: NodeJS.Timeout | null = null;
+
+  constructor() {
+    // Start cleanup interval (every 5 minutes)
+    this.startCleanup();
+  }
+
+  /**
+   * Configure the rate limiter
+   *
+   * @param config - Rate limiting configuration
+   */
+  configure(config: IBetterAuthRateLimit | undefined): void {
+    this.config = {
+      ...DEFAULT_CONFIG,
+      ...config,
+      // Ensure arrays are properly merged
+      skipEndpoints: config?.skipEndpoints ?? DEFAULT_CONFIG.skipEndpoints,
+      strictEndpoints: config?.strictEndpoints ?? DEFAULT_CONFIG.strictEndpoints,
+    };
+
+    if (this.config.enabled) {
+      this.logger.log(`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 path - Request path (relative to basePath)
+   * @returns Rate limit check result
+   */
+  check(ip: string, path: string): RateLimitResult {
+    // If rate limiting is disabled, always allow
+    if (!this.config.enabled) {
+      return {
+        allowed: true,
+        current: 0,
+        limit: Infinity,
+        remaining: Infinity,
+        resetIn: 0,
+      };
+    }
+
+    // Check if this endpoint should skip rate limiting
+    if (this.shouldSkip(path)) {
+      return {
+        allowed: true,
+        current: 0,
+        limit: Infinity,
+        remaining: Infinity,
+        resetIn: 0,
+      };
+    }
+
+    // Determine the limit for this endpoint
+    const limit = this.getLimit(path);
+    const key = this.getKey(ip, path);
+    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 ${path}: ${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 {
+    // Remove all entries for this IP
+    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;
+    }
+  }
+
+  /**
+   * Determine if an endpoint should skip rate limiting
+   */
+  private shouldSkip(path: string): boolean {
+    return this.config.skipEndpoints.some((skip) => path === skip || path.endsWith(skip) || path.includes(skip));
+  }
+
+  /**
+   * Get the rate limit for an endpoint
+   * Strict endpoints get half the normal limit
+   */
+  private getLimit(path: string): number {
+    const isStrict = this.config.strictEndpoints.some(
+      (strict) => path === strict || path.endsWith(strict) || path.includes(strict),
+    );
+
+    return isStrict ? Math.ceil(this.config.max / 2) : this.config.max;
+  }
+
+  /**
+   * Generate a unique key for rate limiting
+   * Uses IP + endpoint category to allow different limits per endpoint type
+   */
+  private getKey(ip: string, path: string): string {
+    // Group similar endpoints together
+    const endpoint = this.normalizeEndpoint(path);
+    return `${ip}:${endpoint}`;
+  }
+
+  /**
+   * Normalize endpoint path for consistent grouping
+   */
+  private normalizeEndpoint(path: string): string {
+    // Remove query strings
+    const cleanPath = path.split('?')[0];
+
+    // Group callback endpoints
+    if (cleanPath.includes('/callback/')) {
+      return 'callback';
+    }
+
+    // Extract the last segment as the endpoint identifier
+    const segments = cleanPath.split('/').filter(Boolean);
+    return segments[segments.length - 1] || 'root';
+  }
+
+  /**
+   * 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();
+    }
+  }
+}