@lenne.tech/nest-server 11.7.0 → 11.7.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nest-server",
-  "version": "11.7.0",
+  "version": "11.7.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",

package/src/config.env.ts

@@ -14,6 +14,16 @@ const config: { [env: string]: IServerOptions } = {
   // Development environment
   // ===========================================================================
   development: {
+    // Legacy Auth endpoint controls (for migration to BetterAuth)
+    // Set to false after all users have migrated to BetterAuth (IAM)
+    // See: .claude/rules/module-deprecation.md
+    auth: {
+      legacyEndpoints: {
+        enabled: true, // Set to false to disable legacy auth endpoints (returns HTTP 410)
+        // graphql: true, // Optionally disable only GraphQL endpoints
+        // rest: true,    // Optionally disable only REST endpoints
+      },
+    },
     automaticObjectIdFiltering: true,
     betterAuth: {
       basePath: '/iam',
@@ -162,11 +172,21 @@ const config: { [env: string]: IServerOptions } = {
   // Local environment
   // ===========================================================================
   local: {
+    // Legacy Auth endpoint controls (for migration to BetterAuth)
+    // Set to false after all users have migrated to BetterAuth (IAM)
+    // See: .claude/rules/module-deprecation.md
+    auth: {
+      legacyEndpoints: {
+        enabled: true, // Set to false to disable legacy auth endpoints (returns HTTP 410)
+        // graphql: true, // Optionally disable only GraphQL endpoints
+        // rest: true,    // Optionally disable only REST endpoints
+      },
+    },
     automaticObjectIdFiltering: true,
     betterAuth: {
       basePath: '/iam',
       baseUrl: 'http://localhost:3000',
-      // enabled: true by default - set false to explicitly disable
+      enabled: true, // Enable for Scenario 2 (Legacy + IAM) testing
       jwt: {
         enabled: true,
         expiresIn: '15m',
@@ -179,7 +199,7 @@ const config: { [env: string]: IServerOptions } = {
       },
       rateLimit: {
         enabled: true,
-        max: 20,
+        max: 100, // Higher limit for local testing
         message: 'Too many requests, please try again later.',
         skipEndpoints: ['/session', '/callback'],
         strictEndpoints: ['/sign-in', '/sign-up', '/forgot-password', '/reset-password'],
@@ -321,6 +341,16 @@ const config: { [env: string]: IServerOptions } = {
   // Production environment
   // ===========================================================================
   production: {
+    // Legacy Auth endpoint controls (for migration to BetterAuth)
+    // Set to false after all users have migrated to BetterAuth (IAM)
+    // See: .claude/rules/module-deprecation.md
+    auth: {
+      legacyEndpoints: {
+        enabled: process.env.LEGACY_AUTH_ENABLED !== 'false', // Disable via env var
+        // graphql: true, // Optionally disable only GraphQL endpoints
+        // rest: true,    // Optionally disable only REST endpoints
+      },
+    },
     automaticObjectIdFiltering: true,
     betterAuth: {
       basePath: '/iam',

package/src/core/common/interfaces/server-options.interface.ts

@@ -22,6 +22,170 @@ import { MailjetOptions } from './mailjet-options.interface';
  */
 export type BetterAuthFieldType = 'boolean' | 'date' | 'json' | 'number' | 'number[]' | 'string' | 'string[]';
 
+/**
+ * Interface for Auth configuration
+ *
+ * This configuration controls the authentication system behavior.
+ * In v11.x, Legacy Auth (CoreAuthService) is the default.
+ * In a future version, BetterAuth (IAM) will become the default.
+ *
+ * @since 11.7.1
+ *
+ * ## Migration Roadmap
+ *
+ * ### v11.x (Current)
+ * - Legacy Auth is the default and required for GraphQL Subscriptions
+ * - BetterAuth can be used alongside Legacy Auth
+ * - Use `legacyEndpoints.enabled: false` after all users migrated to IAM
+ *
+ * ### Future Version (Planned)
+ * - BetterAuth becomes the default
+ * - Legacy Auth becomes optional (must be explicitly enabled)
+ * - CoreModule.forRoot signature simplifies to `CoreModule.forRoot(options)`
+ *
+ * @see https://github.com/lenneTech/nest-server/blob/develop/.claude/rules/module-deprecation.md
+ */
+export interface IAuth {
+  /**
+   * Configuration for legacy auth endpoints
+   *
+   * Legacy endpoints include:
+   * - GraphQL: signIn, signUp, signOut, refreshToken mutations
+   * - REST: /api/auth/* endpoints
+   *
+   * These can be disabled once all users have migrated to BetterAuth (IAM).
+   *
+   * @example
+   * ```typescript
+   * auth: {
+   *   legacyEndpoints: {
+   *     enabled: false // Disable all legacy endpoints after migration
+   *   }
+   * }
+   * ```
+   */
+  legacyEndpoints?: IAuthLegacyEndpoints;
+
+  /**
+   * Prevent user enumeration via unified error messages
+   *
+   * When enabled, authentication errors return a generic "Invalid credentials"
+   * message instead of specific messages like "Unknown email" or "Wrong password".
+   *
+   * This prevents attackers from determining whether an email address exists
+   * in the system, but reduces UX clarity for legitimate users.
+   *
+   * @since 11.7.x
+   * @default false (backward compatible - specific error messages)
+   *
+   * @example
+   * ```typescript
+   * auth: {
+   *   preventUserEnumeration: true // Returns "Invalid credentials" for all auth errors
+   * }
+   * ```
+   */
+  preventUserEnumeration?: boolean;
+
+  /**
+   * Rate limiting configuration for Legacy Auth endpoints
+   *
+   * Protects against brute-force attacks on signIn, signUp, and other
+   * authentication endpoints.
+   *
+   * Follows the same pattern as `betterAuth.rateLimit`.
+   *
+   * @since 11.7.x
+   * @default { enabled: false }
+   *
+   * @example
+   * ```typescript
+   * auth: {
+   *   rateLimit: {
+   *     enabled: true,
+   *     max: 10,
+   *     windowSeconds: 60,
+   *     message: 'Too many login attempts, please try again later.',
+   *   }
+   * }
+   * ```
+   */
+  rateLimit?: IAuthRateLimit;
+}
+
+/**
+ * Interface for Legacy Auth endpoints configuration
+ *
+ * These endpoints are part of the Legacy Auth system (CoreAuthService).
+ * In a future version, BetterAuth (IAM) will become the default and these endpoints
+ * can be disabled once all users have migrated.
+ *
+ * @since 11.7.1
+ * @see https://github.com/lenneTech/nest-server/blob/develop/.claude/rules/module-deprecation.md
+ */
+export interface IAuthLegacyEndpoints {
+  /**
+   * Whether legacy auth endpoints are enabled.
+   *
+   * Set to false to disable all legacy auth endpoints (GraphQL and REST).
+   * Use this after all users have migrated to BetterAuth (IAM).
+   *
+   * Check migration status via the `betterAuthMigrationStatus` query.
+   *
+   * @default true
+   */
+  enabled?: boolean;
+
+  /**
+   * Whether legacy GraphQL auth endpoints are enabled.
+   * Affects: signIn, signUp, signOut, refreshToken mutations
+   *
+   * @default true (inherits from `enabled`)
+   */
+  graphql?: boolean;
+
+  /**
+   * Whether legacy REST auth endpoints are enabled.
+   * Affects: /api/auth/sign-in, /api/auth/sign-up, etc.
+   *
+   * @default true (inherits from `enabled`)
+   */
+  rest?: boolean;
+}
+
+/**
+ * Interface for Legacy Auth rate limiting configuration
+ *
+ * Same structure as IBetterAuthRateLimit for consistency.
+ *
+ * @since 11.7.x
+ */
+export interface IAuthRateLimit {
+  /**
+   * Whether rate limiting is enabled
+   * @default false
+   */
+  enabled?: boolean;
+
+  /**
+   * Maximum number of requests within the time window
+   * @default 10
+   */
+  max?: number;
+
+  /**
+   * Custom message when rate limit is exceeded
+   * @default 'Too many requests, please try again later.'
+   */
+  message?: string;
+
+  /**
+   * Time window in seconds
+   * @default 60
+   */
+  windowSeconds?: number;
+}
+
 /**
  * Interface for better-auth configuration
  */
@@ -110,22 +274,29 @@ export interface IBetterAuth {
 
   /**
    * JWT plugin configuration for API clients.
-   * Enabled by default when this config block is present.
-   * Set `enabled: false` to explicitly disable.
+   *
+   * **Default: Enabled** - JWT is enabled by default when BetterAuth is enabled.
+   * This ensures a minimal config (`betterAuth: true`) provides full functionality.
+   *
+   * Accepts:
+   * - `true` or `{}`: Enable with defaults (same as not specifying)
+   * - `{ expiresIn: '1h' }`: Enable with custom settings
+   * - `false` or `{ enabled: false }`: Explicitly disable
+   * - `undefined`: Enabled with defaults (JWT is on by default)
+   *
+   * @example
+   * ```typescript
+   * // JWT is enabled by default, no config needed
+   * betterAuth: true,
+   *
+   * // Customize JWT expiry
+   * betterAuth: { jwt: { expiresIn: '1h' } },
+   *
+   * // Explicitly disable JWT (session-only mode)
+   * betterAuth: { jwt: false },
+   * ```
    */
-  jwt?: {
-    /**
-     * Whether JWT plugin is enabled.
-     * @default true (when jwt config block is present)
-     */
-    enabled?: boolean;
-
-    /**
-     * JWT expiration time
-     * @default '15m'
-     */
-    expiresIn?: string;
-  };
+  jwt?: boolean | IBetterAuthJwtConfig;
 
   /**
    * Advanced Better-Auth options passthrough.
@@ -158,34 +329,22 @@ export interface IBetterAuth {
 
   /**
    * Passkey/WebAuthn configuration.
-   * Enabled by default when this config block is present.
-   * Set `enabled: false` to explicitly disable.
+   *
+   * Accepts:
+   * - `true` or `{}`: Enable with defaults
+   * - `{ rpName: 'My App' }`: Enable with custom settings
+   * - `false` or `{ enabled: false }`: Disable
+   * - `undefined`: Disabled (default)
+   *
+   * @example
+   * ```typescript
+   * passkey: true,       // Enable with defaults
+   * passkey: {},         // Enable with defaults
+   * passkey: { rpName: 'My App', rpId: 'example.com' }, // Enable with custom settings
+   * passkey: false,      // Disable
+   * ```
    */
-  passkey?: {
-    /**
-     * Whether passkey authentication is enabled.
-     * @default true (when passkey config block is present)
-     */
-    enabled?: boolean;
-
-    /**
-     * Origin URL for WebAuthn
-     * e.g. 'http://localhost:3000'
-     */
-    origin?: string;
-
-    /**
-     * Relying Party ID (usually the domain)
-     * e.g. 'localhost' or 'example.com'
-     */
-    rpId?: string;
-
-    /**
-     * Relying Party Name (displayed to users)
-     * e.g. 'My Application'
-     */
-    rpName?: string;
-  };
+  passkey?: boolean | IBetterAuthPasskeyConfig;
 
   /**
    * Additional Better-Auth plugins to include.
@@ -246,22 +405,68 @@ export interface IBetterAuth {
 
   /**
    * Two-factor authentication configuration.
-   * Enabled by default when this config block is present.
-   * Set `enabled: false` to explicitly disable.
+   *
+   * Accepts:
+   * - `true` or `{}`: Enable with defaults
+   * - `{ appName: 'My App' }`: Enable with custom settings
+   * - `false` or `{ enabled: false }`: Disable
+   * - `undefined`: Disabled (default)
+   *
+   * @example
+   * ```typescript
+   * twoFactor: true,     // Enable with defaults
+   * twoFactor: {},       // Enable with defaults
+   * twoFactor: { appName: 'My App' }, // Enable with custom app name
+   * twoFactor: false,    // Disable
+   * ```
    */
-  twoFactor?: {
-    /**
-     * App name shown in authenticator apps
-     * e.g. 'My Application'
-     */
-    appName?: string;
+  twoFactor?: boolean | IBetterAuthTwoFactorConfig;
+}
 
-    /**
-     * Whether 2FA is enabled.
-     * @default true (when twoFactor config block is present)
-     */
-    enabled?: boolean;
-  };
+/**
+ * JWT plugin configuration for Better-Auth
+ */
+export interface IBetterAuthJwtConfig {
+  /**
+   * Whether JWT plugin is enabled.
+   * @default true (when config block is present)
+   */
+  enabled?: boolean;
+
+  /**
+   * JWT expiration time
+   * @default '15m'
+   */
+  expiresIn?: string;
+}
+
+/**
+ * Passkey/WebAuthn plugin configuration for Better-Auth
+ */
+export interface IBetterAuthPasskeyConfig {
+  /**
+   * Whether passkey authentication is enabled.
+   * @default true (when config block is present)
+   */
+  enabled?: boolean;
+
+  /**
+   * Origin URL for WebAuthn
+   * e.g. 'http://localhost:3000'
+   */
+  origin?: string;
+
+  /**
+   * Relying Party ID (usually the domain)
+   * e.g. 'localhost' or 'example.com'
+   */
+  rpId?: string;
+
+  /**
+   * Relying Party Name (displayed to users)
+   * e.g. 'My Application'
+   */
+  rpName?: string;
 }
 
 /**
@@ -341,6 +546,23 @@ export interface IBetterAuthSocialProvider {
   enabled?: boolean;
 }
 
+/**
+ * Two-factor authentication plugin configuration for Better-Auth
+ */
+export interface IBetterAuthTwoFactorConfig {
+  /**
+   * App name shown in authenticator apps
+   * e.g. 'My Application'
+   */
+  appName?: string;
+
+  /**
+   * Whether 2FA is enabled.
+   * @default true (when config block is present)
+   */
+  enabled?: boolean;
+}
+
 /**
  * Interface for additional user fields in Better-Auth
  * @see https://www.better-auth.com/docs/concepts/users-accounts#additional-fields
@@ -413,6 +635,17 @@ export interface IJwt {
  * Options for the server
  */
 export interface IServerOptions {
+  /**
+   * Authentication system configuration
+   *
+   * Controls Legacy Auth endpoints and behavior.
+   * In a future version, this will also control BetterAuth as the default system.
+   *
+   * @since 11.7.1
+   * @see IAuth
+   */
+  auth?: IAuth;
+
   /**
    * Automatically detect ObjectIds in string values in FilterQueries
    * and expand them as OR query with string and ObjectId.
@@ -423,10 +656,23 @@ export interface IServerOptions {
   automaticObjectIdFiltering?: boolean;
 
   /**
-   * Configuration for better-auth authentication framework
+   * Configuration for better-auth authentication framework.
    * See: https://better-auth.com
+   *
+   * Accepts:
+   * - `true`: Enable with all defaults (including JWT)
+   * - `false`: Disable BetterAuth completely
+   * - `{ ... }`: Enable with custom configuration
+   * - `undefined`: Disabled (default for backward compatibility)
+   *
+   * @example
+   * ```typescript
+   * betterAuth: true,  // Enable with defaults (JWT enabled)
+   * betterAuth: { baseUrl: 'https://example.com' },  // Custom config
+   * betterAuth: false, // Explicitly disabled
+   * ```
    */
-  betterAuth?: IBetterAuth;
+  betterAuth?: boolean | IBetterAuth;
 
   /**
    * Configuration for Brevo

package/src/core/modules/auth/core-auth.controller.ts

@@ -1,9 +1,12 @@
 import { Body, Controller, Get, ParseBoolPipe, Post, Query, Res, UseGuards } from '@nestjs/common';
 import {
-  ApiBody, ApiCreatedResponse,
+  ApiBody,
+  ApiCreatedResponse,
+  ApiGoneResponse,
   ApiOkResponse,
   ApiOperation,
   ApiQuery,
+  ApiTooManyRequestsResponse,
 } from '@nestjs/swagger';
 import { Response as ResponseType } from 'express';
 
@@ -14,13 +17,38 @@ import { RoleEnum } from '../../common/enums/role.enum';
 import { ConfigService } from '../../common/services/config.service';
 import { AuthGuardStrategy } from './auth-guard-strategy.enum';
 import { CoreAuthModel } from './core-auth.model';
+import { LegacyAuthDisabledException } from './exceptions/legacy-auth-disabled.exception';
 import { AuthGuard } from './guards/auth.guard';
+import { LegacyAuthRateLimitGuard } from './guards/legacy-auth-rate-limit.guard';
 import { CoreAuthSignInInput } from './inputs/core-auth-sign-in.input';
 import { CoreAuthSignUpInput } from './inputs/core-auth-sign-up.input';
 import { ICoreAuthUser } from './interfaces/core-auth-user.interface';
 import { CoreAuthService } from './services/core-auth.service';
 import { Tokens } from './tokens.decorator';
 
+/**
+ * Authentication controller for REST endpoints
+ *
+ * This controller provides Legacy Auth endpoints via REST.
+ * In a future version, BetterAuth (IAM) will become the default.
+ *
+ * ## Disabling Legacy Endpoints
+ *
+ * After all users have migrated to BetterAuth (IAM), these endpoints
+ * can be disabled via configuration:
+ *
+ * ```typescript
+ * auth: {
+ *   legacyEndpoints: {
+ *     enabled: false, // Disable all legacy endpoints
+ *     // or
+ *     rest: false     // Disable only REST endpoints
+ *   }
+ * }
+ * ```
+ *
+ * @see https://github.com/lenneTech/nest-server/blob/develop/.claude/rules/module-deprecation.md
+ */
 @ApiCommonErrorResponses()
 @Controller('auth')
 @Roles(RoleEnum.ADMIN)
@@ -33,63 +61,123 @@ export class CoreAuthController {
     protected readonly configService: ConfigService,
   ) {}
 
+  // ===========================================================================
+  // Helper - Legacy Endpoint Check
+  // ===========================================================================
+
+  /**
+   * Check if legacy REST endpoints are enabled
+   *
+   * Throws LegacyAuthDisabledException if:
+   * - config.auth.legacyEndpoints.enabled is false
+   * - config.auth.legacyEndpoints.rest is false
+   *
+   * @throws LegacyAuthDisabledException
+   */
+  protected checkLegacyRESTEnabled(endpointName: string): void {
+    const authConfig = this.configService.getFastButReadOnly('auth');
+    const legacyConfig = authConfig?.legacyEndpoints;
+
+    // Check if legacy endpoints are globally disabled
+    if (legacyConfig?.enabled === false) {
+      throw new LegacyAuthDisabledException(endpointName);
+    }
+
+    // Check if REST endpoints specifically are disabled
+    if (legacyConfig?.rest === false) {
+      throw new LegacyAuthDisabledException(endpointName);
+    }
+  }
+
   /**
    * Logout user (from specific device)
+   *
+   * @deprecated Will be replaced by BetterAuth signOut in a future version
+   * @throws LegacyAuthDisabledException if legacy endpoints are disabled
    */
+  @ApiGoneResponse({ description: 'Legacy Auth endpoints are disabled' })
   @ApiOkResponse({ type: Boolean })
   @ApiOperation({ description: 'Logs a user out from a specific device' })
   @ApiQuery({ description: 'If all devices should be logged out,', name: 'allDevices', required: false, type: Boolean })
+  @ApiTooManyRequestsResponse({ description: 'Rate limit exceeded' })
   @Get('logout')
-  @Roles(RoleEnum.S_EVERYONE)
-  @UseGuards(AuthGuard(AuthGuardStrategy.JWT))
+  @Roles(RoleEnum.S_USER)
+  @UseGuards(LegacyAuthRateLimitGuard)
   async logout(
     @CurrentUser() currentUser: ICoreAuthUser,
     @Tokens('token') token: string,
     @Res({ passthrough: true }) res: ResponseType,
     @Query('allDevices', new ParseBoolPipe({ optional: true })) allDevices?: boolean,
   ): Promise<boolean> {
+    this.checkLegacyRESTEnabled('logout');
     const result = await this.authService.logout(token, { allDevices, currentUser });
     return this.processCookies(res, result);
   }
 
   /**
    * Refresh token (for specific device)
+   *
+   * @deprecated Will be replaced by BetterAuth session refresh in a future version
+   * @throws LegacyAuthDisabledException if legacy endpoints are disabled
    */
+  @ApiGoneResponse({ description: 'Legacy Auth endpoints are disabled' })
   @ApiOkResponse({ type: CoreAuthModel })
   @ApiOperation({ description: 'Refresh token (for specific device)' })
+  @ApiTooManyRequestsResponse({ description: 'Rate limit exceeded' })
   @Get('refresh-token')
   @Roles(RoleEnum.S_EVERYONE)
-  @UseGuards(AuthGuard(AuthGuardStrategy.JWT_REFRESH))
+  @UseGuards(LegacyAuthRateLimitGuard, AuthGuard(AuthGuardStrategy.JWT_REFRESH))
   async refreshToken(
     @CurrentUser() user: ICoreAuthUser,
     @Tokens('refreshToken') refreshToken: string,
     @Res({ passthrough: true }) res: ResponseType,
   ): Promise<CoreAuthModel> {
+    this.checkLegacyRESTEnabled('refresh-token');
     const result = await this.authService.refreshTokens(user, refreshToken);
     return this.processCookies(res, result);
   }
 
   /**
    * Sign in user via email and password (on specific device)
+   *
+   * @deprecated Will be replaced by BetterAuth signIn in a future version
+   * @throws LegacyAuthDisabledException if legacy endpoints are disabled
    */
   @ApiCreatedResponse({ description: 'Signed in successfully', type: CoreAuthModel })
+  @ApiGoneResponse({ description: 'Legacy Auth endpoints are disabled' })
   @ApiOperation({ description: 'Sign in via email and password' })
+  @ApiTooManyRequestsResponse({ description: 'Rate limit exceeded' })
   @Post('signin')
   @Roles(RoleEnum.S_EVERYONE)
-  async signIn(@Res({ passthrough: true }) res: ResponseType, @Body() input: CoreAuthSignInInput): Promise<CoreAuthModel> {
+  @UseGuards(LegacyAuthRateLimitGuard)
+  async signIn(
+    @Res({ passthrough: true }) res: ResponseType,
+    @Body() input: CoreAuthSignInInput,
+  ): Promise<CoreAuthModel> {
+    this.checkLegacyRESTEnabled('signin');
     const result = await this.authService.signIn(input);
     return this.processCookies(res, result);
   }
 
   /**
    * Register a new user account (on specific device)
+   *
+   * @deprecated Will be replaced by BetterAuth signUp in a future version
+   * @throws LegacyAuthDisabledException if legacy endpoints are disabled
    */
   @ApiBody({ type: CoreAuthSignUpInput })
   @ApiCreatedResponse({ type: CoreAuthSignUpInput })
+  @ApiGoneResponse({ description: 'Legacy Auth endpoints are disabled' })
   @ApiOperation({ description: 'Sign up via email and password' })
+  @ApiTooManyRequestsResponse({ description: 'Rate limit exceeded' })
   @Post('signup')
   @Roles(RoleEnum.S_EVERYONE)
-  async signUp(@Res({ passthrough: true }) res: ResponseType, @Body() input: CoreAuthSignUpInput): Promise<CoreAuthModel> {
+  @UseGuards(LegacyAuthRateLimitGuard)
+  async signUp(
+    @Res({ passthrough: true }) res: ResponseType,
+    @Body() input: CoreAuthSignUpInput,
+  ): Promise<CoreAuthModel> {
+    this.checkLegacyRESTEnabled('signup');
     const result = await this.authService.signUp(input);
     return this.processCookies(res, result);
   }