@lenne.tech/nest-server 11.10.0 → 11.10.2

package/src/core/modules/better-auth/better-auth-token.service.ts

@@ -0,0 +1,241 @@
+import { Injectable, Logger, Optional } from '@nestjs/common';
+import { InjectConnection } from '@nestjs/mongoose';
+import { Connection, Types } from 'mongoose';
+
+import { BetterAuthenticatedUser } from './better-auth.types';
+import { CoreBetterAuthService } from './core-better-auth.service';
+
+/**
+ * Result of token extraction from a request
+ */
+export interface TokenExtractionResult {
+  /** Source of the token (header or cookie) */
+  source: 'cookie' | 'header' | null;
+  /** The extracted token, if found */
+  token: null | string;
+}
+
+/**
+ * BetterAuthTokenService provides centralized token extraction and user loading
+ * for BetterAuth authentication.
+ *
+ * This service consolidates the token verification logic that was previously
+ * duplicated in AuthGuard and RolesGuard, providing:
+ * - Token extraction from Authorization header or cookies
+ * - JWT token verification via BetterAuth
+ * - Session token verification via database lookup
+ * - User loading from MongoDB with hasRole() capability
+ *
+ * @example
+ * ```typescript
+ * const token = this.tokenService.extractTokenFromRequest(request);
+ * if (token) {
+ *   const user = await this.tokenService.verifyAndLoadUser(token);
+ *   if (user) {
+ *     request.user = user;
+ *   }
+ * }
+ * ```
+ */
+@Injectable()
+export class BetterAuthTokenService {
+  private readonly logger = new Logger(BetterAuthTokenService.name);
+
+  constructor(
+    @Optional() private readonly betterAuthService?: CoreBetterAuthService,
+    @Optional() @InjectConnection() private readonly connection?: Connection,
+  ) {}
+
+  /**
+   * Extracts a token from the request's Authorization header or cookies.
+   *
+   * Checks in order:
+   * 1. Authorization header (Bearer token)
+   * 2. Session cookies (iam.session_token, better-auth.session_token, token)
+   *
+   * @param request - HTTP request object with headers and cookies
+   * @returns Token extraction result with token and source
+   */
+  extractTokenFromRequest(request: {
+    cookies?: Record<string, string>;
+    headers?: Record<string, string | string[] | undefined>;
+  }): TokenExtractionResult {
+    // Try Authorization header first
+    const authHeader = request.headers?.authorization || request.headers?.Authorization;
+    const headerValue = Array.isArray(authHeader) ? authHeader[0] : authHeader;
+
+    if (headerValue) {
+      if (headerValue.startsWith('Bearer ') || headerValue.startsWith('bearer ')) {
+        return { source: 'header', token: headerValue.substring(7) };
+      }
+    }
+
+    // Try cookies
+    if (request.cookies && this.betterAuthService) {
+      const cookieName = this.betterAuthService.getSessionCookieName();
+      const token =
+        request.cookies[cookieName] ||
+        request.cookies['better-auth.session_token'] ||
+        request.cookies['token'] ||
+        undefined;
+
+      if (token) {
+        return { source: 'cookie', token };
+      }
+    }
+
+    return { source: null, token: null };
+  }
+
+  /**
+   * Verifies a token (JWT or session) and loads the corresponding user from MongoDB.
+   *
+   * This method tries multiple verification strategies:
+   * 1. BetterAuth JWT verification (if JWT plugin is enabled)
+   * 2. BetterAuth session token lookup (database lookup)
+   *
+   * @param token - The token to verify
+   * @returns User object with hasRole method, or null if verification fails
+   */
+  async verifyAndLoadUser(token: string): Promise<BetterAuthenticatedUser | null> {
+    if (!this.betterAuthService || !this.connection) {
+      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 (error) {
+        // Check for token expiration
+        if (error instanceof Error && error.message.includes('expired')) {
+          this.logger.debug('JWT token expired');
+          throw error; // Re-throw for proper handling by guards
+        }
+        // Other JWT verification failures - try session token next
+        this.logger.debug(
+          `JWT verification failed, trying session: ${error instanceof Error ? error.message : 'Unknown error'}`,
+        );
+      }
+    }
+
+    // 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 (error) {
+      this.logger.debug(`Session lookup failed: ${error instanceof Error ? error.message : 'Unknown error'}`);
+    }
+
+    return null;
+  }
+
+  /**
+   * Creates a user object with hasRole method from a MongoDB document.
+   *
+   * @param user - Raw MongoDB user document
+   * @returns User object with hasRole method
+   */
+  createUserWithHasRole(user: Record<string, unknown>): BetterAuthenticatedUser {
+    return {
+      ...user,
+      _authenticatedViaBetterAuth: true,
+      hasRole: (roles: string[]): boolean => {
+        const userRoles = user.roles;
+        if (!userRoles || !Array.isArray(userRoles)) {
+          return false;
+        }
+        return roles.some((role) => userRoles.includes(role));
+      },
+      id: (user._id as Types.ObjectId)?.toString() || (user.id as string),
+    } as BetterAuthenticatedUser;
+  }
+
+  /**
+   * Loads a user from JWT payload using direct MongoDB query.
+   *
+   * @param payload - JWT payload with sub (user ID or iamId)
+   * @returns User object with hasRole method, or null if not found
+   */
+  private async loadUserFromPayload(payload: { [key: string]: unknown; sub: string }): Promise<BetterAuthenticatedUser | null> {
+    if (!this.connection) {
+      return null;
+    }
+
+    try {
+      const usersCollection = this.connection.collection('users');
+      let user: null | Record<string, unknown> = 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;
+      }
+
+      return this.createUserWithHasRole(user);
+    } catch (error) {
+      this.logger.debug(`Failed to load user from payload: ${error instanceof Error ? error.message : 'Unknown error'}`);
+      return null;
+    }
+  }
+
+  /**
+   * Loads a user from session result (from getSessionByToken).
+   *
+   * @param sessionUser - User object from session lookup
+   * @returns User object with hasRole method, or null if not found
+   */
+  private async loadUserFromSessionResult(sessionUser: {
+    email?: string;
+    id?: string;
+  }): Promise<BetterAuthenticatedUser | null> {
+    if (!this.connection || !sessionUser) {
+      return null;
+    }
+
+    try {
+      const usersCollection = this.connection.collection('users');
+      let user: null | Record<string, unknown> = 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;
+      }
+
+      return this.createUserWithHasRole(user);
+    } catch (error) {
+      this.logger.debug(`Failed to load user from session: ${error instanceof Error ? error.message : 'Unknown error'}`);
+      return null;
+    }
+  }
+}

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

@@ -5,6 +5,8 @@
  * and reduce the need for `as any` casts throughout the codebase.
  */
 
+import { Types } from 'mongoose';
+
 import { BetterAuthSessionUser } from './core-better-auth-user.mapper';
 
 /**
@@ -23,6 +25,41 @@ export interface BetterAuth2FAResponse {
   user?: BetterAuthSessionUser;
 }
 
+/**
+ * Authenticated user object created from BetterAuth token verification.
+ *
+ * This interface represents a user that has been authenticated via BetterAuth
+ * (either JWT or session token). It includes the `hasRole` method for
+ * role-based access control and the `_authenticatedViaBetterAuth` flag
+ * to identify BetterAuth-authenticated users.
+ */
+export interface BetterAuthenticatedUser {
+  /** Allow additional properties from MongoDB document */
+  [key: string]: unknown;
+  /** Flag indicating this user was authenticated via BetterAuth */
+  _authenticatedViaBetterAuth: true;
+  /** MongoDB _id field */
+  _id?: Types.ObjectId;
+  /** User's email address */
+  email: string;
+  /** Whether user's email is verified */
+  emailVerified?: boolean;
+  /**
+   * Check if user has any of the specified roles
+   * @param roles - Array of role names to check
+   * @returns true if user has at least one of the roles
+   */
+  hasRole: (roles: string[]) => boolean;
+  /** User ID as string */
+  id: string;
+  /** User's assigned roles */
+  roles?: string[];
+  /** Whether the user is verified */
+  verified?: boolean;
+  /** Timestamp when user was verified */
+  verifiedAt?: Date;
+}
+
 /**
  * Better-Auth session response from getSession API
  */

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

@@ -614,7 +614,7 @@ export class CoreBetterAuthController {
    * @param sessionUser - The user from Better-Auth session
    * @param _mappedUser - The synced user from legacy system (available for override customization)
    */
-  // eslint-disable-next-line unused-imports/no-unused-vars
+   
   protected mapUser(sessionUser: BetterAuthSessionUser, _mappedUser: any): CoreBetterAuthUserResponse {
     return {
       email: sessionUser.email,

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

@@ -9,11 +9,14 @@ import {
   Optional,
   Type,
 } from '@nestjs/common';
+import { APP_GUARD } from '@nestjs/core';
 import { getConnectionToken } from '@nestjs/mongoose';
 import mongoose, { Connection } from 'mongoose';
 
 import { IBetterAuth } from '../../common/interfaces/server-options.interface';
 import { ConfigService } from '../../common/services/config.service';
+import { RolesGuard } from '../auth/guards/roles.guard';
+import { BetterAuthTokenService } from './better-auth-token.service';
 import { BetterAuthInstance, createBetterAuthInstance } from './better-auth.config';
 import { DefaultBetterAuthResolver } from './better-auth.resolver';
 import { CoreBetterAuthApiMiddleware } from './core-better-auth-api.middleware';
@@ -79,6 +82,19 @@ export interface CoreBetterAuthModuleOptions {
    */
   fallbackSecrets?: (string | undefined)[];
 
+  /**
+   * Register RolesGuard as a global guard.
+   *
+   * This should be set to `true` for IAM-only setups (CoreModule.forRoot with 1 parameter)
+   * where CoreAuthModule is not imported (which normally registers RolesGuard globally).
+   *
+   * When `true`, all `@Roles()` decorators will be enforced automatically without
+   * needing explicit `@UseGuards(RolesGuard)` on each endpoint.
+   *
+   * @default false
+   */
+  registerRolesGuardGlobally?: boolean;
+
   /**
    * Custom resolver class to use instead of the default DefaultBetterAuthResolver.
    * The class must extend CoreBetterAuthResolver.
@@ -152,6 +168,7 @@ export class CoreBetterAuthModule implements NestModule, OnModuleInit {
   private static currentConfig: IBetterAuth | null = null;
   private static customController: null | Type<CoreBetterAuthController> = null;
   private static customResolver: null | Type<CoreBetterAuthResolver> = null;
+  private static shouldRegisterRolesGuardGlobally = false;
 
   /**
    * Gets the controller class to use (custom or default)
@@ -251,7 +268,7 @@ export class CoreBetterAuthModule implements NestModule, OnModuleInit {
    * @returns Dynamic module configuration
    */
   static forRoot(options: CoreBetterAuthModuleOptions): DynamicModule {
-    const { config: rawConfig, controller, fallbackSecrets, resolver } = options;
+    const { config: rawConfig, controller, fallbackSecrets, registerRolesGuardGlobally, resolver } = options;
 
     // Normalize config: true → {}, false/undefined → null
     const config = normalizeBetterAuthConfig(rawConfig);
@@ -262,6 +279,8 @@ export class CoreBetterAuthModule implements NestModule, OnModuleInit {
     this.customController = controller || null;
     // Store custom resolver if provided
     this.customResolver = resolver || null;
+    // Store whether to register RolesGuard globally (for IAM-only setups)
+    this.shouldRegisterRolesGuardGlobally = registerRolesGuardGlobally ?? false;
 
     // If better-auth is disabled (config is null or enabled: false), return minimal module
     // Note: We don't provide middleware classes when disabled because they depend on CoreBetterAuthService
@@ -270,7 +289,7 @@ export class CoreBetterAuthModule implements NestModule, OnModuleInit {
       this.logger.debug('BetterAuth is disabled - skipping initialization');
       this.betterAuthEnabled = false;
       return {
-        exports: [BETTER_AUTH_INSTANCE, CoreBetterAuthService, CoreBetterAuthUserMapper, CoreBetterAuthRateLimiter],
+        exports: [BETTER_AUTH_INSTANCE, CoreBetterAuthService, CoreBetterAuthUserMapper, CoreBetterAuthRateLimiter, BetterAuthTokenService],
         module: CoreBetterAuthModule,
         providers: [
           {
@@ -282,6 +301,7 @@ export class CoreBetterAuthModule implements NestModule, OnModuleInit {
           CoreBetterAuthService,
           CoreBetterAuthUserMapper,
           CoreBetterAuthRateLimiter,
+          BetterAuthTokenService,
         ],
       };
     }
@@ -306,7 +326,7 @@ export class CoreBetterAuthModule implements NestModule, OnModuleInit {
   static forRootAsync(): DynamicModule {
     return {
       controllers: [this.getControllerClass()],
-      exports: [BETTER_AUTH_INSTANCE, CoreBetterAuthService, CoreBetterAuthUserMapper, CoreBetterAuthRateLimiter],
+      exports: [BETTER_AUTH_INSTANCE, CoreBetterAuthService, CoreBetterAuthUserMapper, CoreBetterAuthRateLimiter, BetterAuthTokenService],
       imports: [],
       module: CoreBetterAuthModule,
       providers: [
@@ -380,6 +400,14 @@ export class CoreBetterAuthModule implements NestModule, OnModuleInit {
         CoreBetterAuthApiMiddleware,
         CoreBetterAuthRateLimiter,
         CoreBetterAuthRateLimitMiddleware,
+        // BetterAuthTokenService needs explicit factory to ensure proper dependency injection
+        {
+          inject: [CoreBetterAuthService, getConnectionToken()],
+          provide: BetterAuthTokenService,
+          useFactory: (betterAuthService: CoreBetterAuthService, connection: Connection) => {
+            return new BetterAuthTokenService(betterAuthService, connection);
+          },
+        },
         this.getResolverClass(),
       ],
     };
@@ -412,6 +440,7 @@ export class CoreBetterAuthModule implements NestModule, OnModuleInit {
     this.currentConfig = null;
     this.customController = null;
     this.customResolver = null;
+    this.shouldRegisterRolesGuardGlobally = false;
   }
 
   /**
@@ -421,7 +450,7 @@ export class CoreBetterAuthModule implements NestModule, OnModuleInit {
   private static createDeferredModule(config: IBetterAuth, fallbackSecrets?: (string | undefined)[]): DynamicModule {
     return {
       controllers: [this.getControllerClass()],
-      exports: [BETTER_AUTH_INSTANCE, CoreBetterAuthService, CoreBetterAuthUserMapper, CoreBetterAuthRateLimiter],
+      exports: [BETTER_AUTH_INSTANCE, CoreBetterAuthService, CoreBetterAuthUserMapper, CoreBetterAuthRateLimiter, BetterAuthTokenService],
       module: CoreBetterAuthModule,
       providers: [
         {
@@ -479,7 +508,25 @@ export class CoreBetterAuthModule implements NestModule, OnModuleInit {
         CoreBetterAuthApiMiddleware,
         CoreBetterAuthRateLimiter,
         CoreBetterAuthRateLimitMiddleware,
+        // BetterAuthTokenService needs explicit factory to ensure proper dependency injection
+        {
+          inject: [CoreBetterAuthService, getConnectionToken()],
+          provide: BetterAuthTokenService,
+          useFactory: (betterAuthService: CoreBetterAuthService, connection: Connection) => {
+            return new BetterAuthTokenService(betterAuthService, connection);
+          },
+        },
         this.getResolverClass(),
+        // Conditionally register RolesGuard globally for IAM-only setups
+        // In Legacy mode, RolesGuard is already registered globally via CoreAuthModule
+        ...(this.shouldRegisterRolesGuardGlobally
+          ? [
+              {
+                provide: APP_GUARD,
+                useClass: RolesGuard,
+              },
+            ]
+          : []),
       ],
     };
   }

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

@@ -195,7 +195,7 @@ export class CoreBetterAuthResolver {
   async betterAuthSignIn(
     @Args('email') email: string,
     @Args('password') password: string,
-    // eslint-disable-next-line unused-imports/no-unused-vars -- Reserved for future cookie/session handling
+     
     @Context() _ctx: { req: Request; res: Response },
   ): Promise<CoreBetterAuthAuthModel> {
     this.ensureEnabled();

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

@@ -201,6 +201,19 @@ export class CoreBetterAuthService {
     return this.config.baseUrl || 'http://localhost:3000';
   }
 
+  /**
+   * Gets the session cookie name based on the configured base path.
+   *
+   * The cookie name follows the pattern: `{basePath}.session_token`
+   * For example, with basePath '/iam', the cookie name is 'iam.session_token'
+   *
+   * @returns The session cookie name
+   */
+  getSessionCookieName(): string {
+    const basePath = this.getBasePath()?.replace(/^\//, '').replace(/\//g, '.') || 'iam';
+    return `${basePath}.session_token`;
+  }
+
   // ===================================================================================================================
   // JWT Token Methods
   // ===================================================================================================================

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

@@ -22,6 +22,7 @@
  * - DefaultBetterAuthResolver: Default resolver implementation (use as fallback)
  */
 
+export * from './better-auth-token.service';
 export * from './better-auth.config';
 export * from './better-auth.resolver';
 export * from './better-auth.types';

package/src/core.module.ts

@@ -262,6 +262,9 @@ export class CoreModule implements NestModule {
             config: betterAuthConfig === true ? {} : betterAuthConfig || {},
             // Pass JWT secrets for backwards compatibility fallback
             fallbackSecrets: [config.jwt?.secret, config.jwt?.refresh?.secret],
+            // In IAM-only mode, register RolesGuard globally to enforce @Roles() decorators
+            // In Legacy mode (autoRegister), RolesGuard is already registered via CoreAuthModule
+            registerRolesGuardGlobally: isIamOnlyMode,
           }),
         );
       }