@lenne.tech/nest-server 11.7.1 → 11.7.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nest-server",
-  "version": "11.7.1",
+  "version": "11.7.3",
   "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/core/common/interfaces/server-options.interface.ts

@@ -274,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.
@@ -322,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.
@@ -410,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;
 }
 
 /**
@@ -505,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
@@ -598,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

@@ -101,8 +101,8 @@ export class CoreAuthController {
   @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(LegacyAuthRateLimitGuard, AuthGuard(AuthGuardStrategy.JWT))
+  @Roles(RoleEnum.S_USER)
+  @UseGuards(LegacyAuthRateLimitGuard)
   async logout(
     @CurrentUser() currentUser: ICoreAuthUser,
     @Tokens('token') token: string,

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

@@ -92,8 +92,8 @@ export class CoreAuthResolver {
    * @throws LegacyAuthDisabledException if legacy endpoints are disabled
    */
   @Mutation(() => Boolean, { description: 'Logout user (from specific device)' })
-  @Roles(RoleEnum.S_EVERYONE)
-  @UseGuards(LegacyAuthRateLimitGuard, AuthGuard(AuthGuardStrategy.JWT))
+  @Roles(RoleEnum.S_USER)
+  @UseGuards(LegacyAuthRateLimitGuard)
   async logout(
     @CurrentUser() currentUser: ICoreAuthUser,
     @Context() ctx: { res: ResponseType },

package/src/core/modules/auth/guards/roles.guard.ts

@@ -1,8 +1,12 @@
-import { ExecutionContext, Injectable, UnauthorizedException } from '@nestjs/common';
-import { Reflector } from '@nestjs/core';
+import { ExecutionContext, Injectable, Logger, Optional, UnauthorizedException } from '@nestjs/common';
+import { ModuleRef, Reflector } from '@nestjs/core';
 import { GqlExecutionContext } from '@nestjs/graphql';
+import { getConnectionToken } from '@nestjs/mongoose';
+import { Connection, Types } from 'mongoose';
+import { firstValueFrom, isObservable } from 'rxjs';
 
 import { RoleEnum } from '../../../common/enums/role.enum';
+import { BetterAuthService } from '../../better-auth/better-auth.service';
 import { AuthGuardStrategy } from '../auth-guard-strategy.enum';
 import { ExpiredTokenException } from '../exceptions/expired-token.exception';
 import { InvalidTokenException } from '../exceptions/invalid-token.exception';
@@ -14,16 +18,305 @@ import { AuthGuard } from './auth.guard';
  * The RoleGuard is activated by the Role decorator. It checks whether the current user has at least one of the
  * specified roles or is logged in when the S_USER role is set.
  * If this is not the case, an UnauthorizedException is thrown.
+ *
+ * MULTI-TOKEN SUPPORT:
+ * This guard supports multiple authentication token types:
+ * 1. Legacy JWT tokens (Passport JWT strategy)
+ * 2. BetterAuth JWT tokens (verified via BetterAuth service)
+ * 3. BetterAuth session tokens (verified via database lookup)
+ *
+ * When Passport JWT validation fails, the guard falls back to BetterAuth verification:
+ * - First tries JWT verification if the JWT plugin is enabled
+ * - Then tries session token lookup via MongoDB
+ *
+ * This enables users who sign in via IAM (/iam/sign-in/email) to access all protected endpoints,
+ * regardless of whether they use JWT or session-based authentication.
  */
 @Injectable()
 export class RolesGuard extends AuthGuard(AuthGuardStrategy.JWT) {
+  private readonly logger = new Logger(RolesGuard.name);
+  private betterAuthService: BetterAuthService | null = null;
+  private mongoConnection: Connection | null = null;
+  private servicesResolved = false;
+
   /**
-   * Integrate reflector
+   * Integrate reflector and moduleRef for lazy service resolution
    */
-  constructor(protected readonly reflector: Reflector) {
+  constructor(
+    protected readonly reflector: Reflector,
+    @Optional() private readonly moduleRef?: ModuleRef,
+  ) {
     super();
   }
 
+  /**
+   * Lazily resolve BetterAuth service and MongoDB connection
+   */
+  private resolveServices(): void {
+    if (this.servicesResolved || !this.moduleRef) {
+      return;
+    }
+
+    try {
+      this.betterAuthService = this.moduleRef.get(BetterAuthService, { strict: false });
+    } catch {
+      // BetterAuth not available - that's fine, we'll use Legacy JWT only
+    }
+
+    try {
+      // Get the Mongoose connection to query users directly
+      this.mongoConnection = this.moduleRef.get(getConnectionToken(), { strict: false });
+    } catch {
+      // MongoDB connection not available
+    }
+
+    this.servicesResolved = true;
+  }
+
+  /**
+   * Override canActivate to add BetterAuth JWT fallback
+   *
+   * Flow:
+   * 1. Try Passport JWT authentication (Legacy JWT)
+   * 2. If that fails, try BetterAuth JWT verification
+   * 3. If BetterAuth succeeds, load the user and proceed
+   */
+  override async canActivate(context: ExecutionContext): Promise<boolean> {
+    // Resolve services lazily
+    this.resolveServices();
+
+    // First, try the parent canActivate (Passport JWT)
+    try {
+      const result = super.canActivate(context);
+      return isObservable(result) ? await firstValueFrom(result) : await result;
+    } catch (passportError) {
+      // Passport JWT validation failed - try BetterAuth token fallback (JWT or session)
+      if (!this.betterAuthService?.isEnabled()) {
+        // BetterAuth not available - rethrow original error
+        throw passportError;
+      }
+
+      // Try to verify the token via BetterAuth (JWT or session token)
+      const user = await this.verifyBetterAuthTokenFromContext(context);
+      if (!user) {
+        // BetterAuth verification also failed - rethrow original Passport error
+        throw passportError;
+      }
+
+      // BetterAuth token is valid - set the user on the request
+      const request = this.getRequest(context);
+      if (request) {
+        request.user = user;
+      }
+
+      // Now call handleRequest with the BetterAuth-authenticated user to check roles
+      this.handleRequest(null, user, null, context);
+
+      return true;
+    }
+  }
+
+  /**
+   * Verify BetterAuth token (JWT or session) and load the corresponding user
+   *
+   * This method tries multiple verification strategies:
+   * 1. BetterAuth JWT verification (if JWT plugin is enabled)
+   * 2. BetterAuth session token lookup (database lookup)
+   *
+   * @param context - ExecutionContext to extract request from
+   * @returns User object if verification succeeds, null otherwise
+   */
+  private async verifyBetterAuthTokenFromContext(context: ExecutionContext): Promise<any> {
+    if (!this.betterAuthService || !this.mongoConnection) {
+      return null;
+    }
+
+    try {
+      // Get the raw HTTP request from multiple possible sources
+      let authHeader: string | undefined;
+
+      // Try GraphQL context first
+      try {
+        const gqlContext = GqlExecutionContext.create(context);
+        const ctx = gqlContext.getContext();
+        if (ctx?.req?.headers) {
+          authHeader = ctx.req.headers.authorization || ctx.req.headers.Authorization;
+        }
+      } catch {
+        // GraphQL context not available
+      }
+
+      // Fallback to HTTP context
+      if (!authHeader) {
+        try {
+          const httpRequest = context.switchToHttp().getRequest();
+          if (httpRequest?.headers) {
+            authHeader = httpRequest.headers.authorization || httpRequest.headers.Authorization;
+          }
+        } catch {
+          // HTTP context not available
+        }
+      }
+
+      let token: string | undefined;
+
+      if (authHeader?.startsWith('Bearer ')) {
+        token = authHeader.substring(7);
+      } else if (authHeader?.startsWith('bearer ')) {
+        // Handle lowercase 'bearer' as well
+        token = authHeader.substring(7);
+      }
+
+      if (!token) {
+        return null;
+      }
+
+      // Strategy 1: Try JWT verification (if JWT plugin is enabled)
+      if (this.betterAuthService.isJwtEnabled()) {
+        try {
+          const payload = await this.betterAuthService.verifyJwtToken(token);
+          if (payload?.sub) {
+            const user = await this.loadUserFromPayload(payload);
+            if (user) {
+              return user;
+            }
+          }
+        } catch {
+          // JWT verification failed - try session token next
+        }
+      }
+
+      // Strategy 2: Try session token lookup (database lookup)
+      try {
+        const sessionResult = await this.betterAuthService.getSessionByToken(token);
+        if (sessionResult?.user) {
+          return this.loadUserFromSessionResult(sessionResult.user);
+        }
+      } catch {
+        // Session lookup failed
+      }
+
+      return null;
+    } catch (error) {
+      this.logger.debug(
+        `BetterAuth token fallback failed: ${error instanceof Error ? error.message : 'Unknown error'}`,
+      );
+      return null;
+    }
+  }
+
+  /**
+   * Load user from JWT payload using direct MongoDB query
+   *
+   * @param payload - JWT payload with sub (user ID or iamId)
+   * @returns User object with hasRole method
+   */
+  private async loadUserFromPayload(payload: { [key: string]: any; sub: string }): Promise<any> {
+    if (!this.mongoConnection) {
+      return null;
+    }
+
+    try {
+      const usersCollection = this.mongoConnection.collection('users');
+      let user: any = null;
+
+      // Try to find by MongoDB _id first
+      if (Types.ObjectId.isValid(payload.sub)) {
+        user = await usersCollection.findOne({ _id: new Types.ObjectId(payload.sub) });
+      }
+
+      // If not found, try by iamId
+      if (!user) {
+        user = await usersCollection.findOne({ iamId: payload.sub });
+      }
+
+      if (!user) {
+        return null;
+      }
+
+      // Convert MongoDB document to user-like object with hasRole method
+      const userObject = {
+        ...user,
+        _authenticatedViaBetterAuth: true,
+        // Add hasRole method for role checking
+        hasRole: (roles: string[]): boolean => {
+          if (!user.roles || !Array.isArray(user.roles)) {
+            return false;
+          }
+          return roles.some((role) => user.roles.includes(role));
+        },
+        id: user._id?.toString(),
+      };
+
+      return userObject;
+    } catch (error) {
+      this.logger.debug(
+        `Failed to load user from payload: ${error instanceof Error ? error.message : 'Unknown error'}`,
+      );
+      return null;
+    }
+  }
+
+  /**
+   * Load user from session result (from getSessionByToken)
+   *
+   * @param sessionUser - User object from session lookup
+   * @returns User object with hasRole method
+   */
+  private async loadUserFromSessionResult(sessionUser: any): Promise<any> {
+    if (!this.mongoConnection || !sessionUser) {
+      return null;
+    }
+
+    try {
+      const usersCollection = this.mongoConnection.collection('users');
+
+      // The sessionUser might have id (BetterAuth ID) or email
+      // We need to find the corresponding user in our users collection
+      let user: any = null;
+
+      // Try to find by email (most reliable)
+      if (sessionUser.email) {
+        user = await usersCollection.findOne({ email: sessionUser.email });
+      }
+
+      // If not found by email, try by iamId
+      if (!user && sessionUser.id) {
+        user = await usersCollection.findOne({ iamId: sessionUser.id });
+      }
+
+      // If still not found, try by _id (if the ID looks like a MongoDB ObjectId)
+      if (!user && sessionUser.id && Types.ObjectId.isValid(sessionUser.id)) {
+        user = await usersCollection.findOne({ _id: new Types.ObjectId(sessionUser.id) });
+      }
+
+      if (!user) {
+        return null;
+      }
+
+      // Convert MongoDB document to user-like object with hasRole method
+      const userObject = {
+        ...user,
+        _authenticatedViaBetterAuth: true,
+        // Add hasRole method for role checking
+        hasRole: (roles: string[]): boolean => {
+          if (!user.roles || !Array.isArray(user.roles)) {
+            return false;
+          }
+          return roles.some((role) => user.roles.includes(role));
+        },
+        id: user._id?.toString(),
+      };
+
+      return userObject;
+    } catch (error) {
+      this.logger.debug(
+        `Failed to load user from session: ${error instanceof Error ? error.message : 'Unknown error'}`,
+      );
+      return null;
+    }
+  }
+
   /**
    * Handle request
    */
@@ -42,7 +335,7 @@ export class RolesGuard extends AuthGuard(AuthGuardStrategy.JWT) {
     }
 
     // Check roles
-    if (!roles || !roles.some(value => !!value)) {
+    if (!roles || !roles.some((value) => !!value)) {
       return user;
     }
 

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

@@ -114,7 +114,7 @@ export class LegacyAuthRateLimiter implements OnModuleInit {
     };
 
     if (this.config.enabled) {
-      this.logger.log(
+      this.logger.debug(
         `Legacy Auth rate limiting enabled: ${this.config.max} requests per ${this.config.windowSeconds}s`,
       );
     }

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

@@ -54,7 +54,9 @@ https://github.com/lenneTech/nest-server/tree/develop/src/server/modules/better-
 **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.
+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.
+
+**Note:** `@UseGuards(AuthGuard(JWT))` is NOT needed when using `@Roles(S_USER)` or `@Roles(ADMIN)` because `RolesGuard` already extends `AuthGuard(JWT)` internally.
 
 ---
 
@@ -136,13 +138,14 @@ const config = {
       enabled: false,
     },
   },
-  // BetterAuth configuration
+  // BetterAuth configuration (minimal - JWT enabled by default)
+  betterAuth: true,  // or betterAuth: {} for same effect
+
+  // OR with optional features:
   betterAuth: {
-    // enabled: true (default)
-    // basePath: '/iam' (default)
-    jwt: {},       // Enable JWT tokens
-    twoFactor: {}, // Enable 2FA
-    passkey: {},   // Enable Passkeys
+    twoFactor: {}, // Enable 2FA (opt-in)
+    passkey: {},   // Enable Passkeys (opt-in)
+    // JWT is already enabled by default
   },
 };
 ```
@@ -156,10 +159,8 @@ const config = {
       enabled: true, // Default - can disable after migration
     },
   },
-  // BetterAuth configuration
-  betterAuth: {
-    // ... same as above
-  },
+  // BetterAuth configuration (JWT enabled by default)
+  betterAuth: true,  // Minimal config, or use object for more options
 };
 ```