@lenne.tech/nest-server 11.8.0 → 11.10.0

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

@@ -3,17 +3,17 @@ import { Request, Response } from 'express';
 
 import { Roles } from '../../common/decorators/roles.decorator';
 import { RoleEnum } from '../../common/enums/role.enum';
-import { BetterAuthAuthModel } from './better-auth-auth.model';
+import { CoreBetterAuthAuthModel } from './core-better-auth-auth.model';
 import {
-  BetterAuth2FASetupModel,
-  BetterAuthFeaturesModel,
-  BetterAuthPasskeyChallengeModel,
-  BetterAuthPasskeyModel,
-  BetterAuthSessionModel,
-} from './better-auth-models';
-import { BetterAuthUserMapper } from './better-auth-user.mapper';
-import { BetterAuthService } from './better-auth.service';
+  CoreBetterAuth2FASetupModel,
+  CoreBetterAuthFeaturesModel,
+  CoreBetterAuthPasskeyChallengeModel,
+  CoreBetterAuthPasskeyModel,
+  CoreBetterAuthSessionModel,
+} from './core-better-auth-models';
+import { CoreBetterAuthUserMapper } from './core-better-auth-user.mapper';
 import { CoreBetterAuthResolver } from './core-better-auth.resolver';
+import { CoreBetterAuthService } from './core-better-auth.service';
 
 /**
  * Default BetterAuth GraphQL Resolver
@@ -28,11 +28,11 @@ import { CoreBetterAuthResolver } from './core-better-auth.resolver';
  * @example
  * ```typescript
  * // In your project - src/server/modules/better-auth/better-auth.resolver.ts
- * @Resolver(() => BetterAuthAuthModel)
+ * @Resolver(() => CoreBetterAuthAuthModel)
  * export class BetterAuthResolver extends CoreBetterAuthResolver {
  *   constructor(
- *     betterAuthService: BetterAuthService,
- *     userMapper: BetterAuthUserMapper,
+ *     betterAuthService: CoreBetterAuthService,
+ *     userMapper: CoreBetterAuthUserMapper,
  *     private readonly emailService: EmailService,
  *   ) {
  *     super(betterAuthService, userMapper);
@@ -51,12 +51,12 @@ import { CoreBetterAuthResolver } from './core-better-auth.resolver';
  * }
  * ```
  */
-@Resolver(() => BetterAuthAuthModel)
+@Resolver(() => CoreBetterAuthAuthModel)
 @Roles(RoleEnum.ADMIN)
-export class BetterAuthResolver extends CoreBetterAuthResolver {
+export class DefaultBetterAuthResolver extends CoreBetterAuthResolver {
   constructor(
-    protected override readonly betterAuthService: BetterAuthService,
-    protected override readonly userMapper: BetterAuthUserMapper,
+    protected override readonly betterAuthService: CoreBetterAuthService,
+    protected override readonly userMapper: CoreBetterAuthUserMapper,
   ) {
     super(betterAuthService, userMapper);
   }
@@ -65,12 +65,12 @@ export class BetterAuthResolver extends CoreBetterAuthResolver {
   // Queries
   // ===========================================================================
 
-  @Query(() => BetterAuthSessionModel, {
+  @Query(() => CoreBetterAuthSessionModel, {
     description: 'Get current Better-Auth session',
     nullable: true,
   })
   @Roles(RoleEnum.S_USER)
-  override async betterAuthSession(@Context() ctx: { req: Request }): Promise<BetterAuthSessionModel | null> {
+  override async betterAuthSession(@Context() ctx: { req: Request }): Promise<CoreBetterAuthSessionModel | null> {
     return super.betterAuthSession(ctx);
   }
 
@@ -80,18 +80,18 @@ export class BetterAuthResolver extends CoreBetterAuthResolver {
     return super.betterAuthEnabled();
   }
 
-  @Query(() => BetterAuthFeaturesModel, { description: 'Get enabled Better-Auth features' })
+  @Query(() => CoreBetterAuthFeaturesModel, { description: 'Get enabled Better-Auth features' })
   @Roles(RoleEnum.S_EVERYONE)
-  override betterAuthFeatures(): BetterAuthFeaturesModel {
+  override betterAuthFeatures(): CoreBetterAuthFeaturesModel {
     return super.betterAuthFeatures();
   }
 
-  @Query(() => [BetterAuthPasskeyModel], {
+  @Query(() => [CoreBetterAuthPasskeyModel], {
     description: 'List passkeys for the current user',
     nullable: true,
   })
   @Roles(RoleEnum.S_USER)
-  override async betterAuthListPasskeys(@Context() ctx: { req: Request }): Promise<BetterAuthPasskeyModel[] | null> {
+  override async betterAuthListPasskeys(@Context() ctx: { req: Request }): Promise<CoreBetterAuthPasskeyModel[] | null> {
     return super.betterAuthListPasskeys(ctx);
   }
 
@@ -99,7 +99,7 @@ export class BetterAuthResolver extends CoreBetterAuthResolver {
   // Authentication Mutations
   // ===========================================================================
 
-  @Mutation(() => BetterAuthAuthModel, {
+  @Mutation(() => CoreBetterAuthAuthModel, {
     description: 'Sign in via Better-Auth (email/password)',
   })
   @Roles(RoleEnum.S_EVERYONE)
@@ -107,11 +107,11 @@ export class BetterAuthResolver extends CoreBetterAuthResolver {
     @Args('email') email: string,
     @Args('password') password: string,
     @Context() ctx: { req: Request; res: Response },
-  ): Promise<BetterAuthAuthModel> {
+  ): Promise<CoreBetterAuthAuthModel> {
     return super.betterAuthSignIn(email, password, ctx);
   }
 
-  @Mutation(() => BetterAuthAuthModel, {
+  @Mutation(() => CoreBetterAuthAuthModel, {
     description: 'Sign up via Better-Auth (email/password)',
   })
   @Roles(RoleEnum.S_EVERYONE)
@@ -119,7 +119,7 @@ export class BetterAuthResolver extends CoreBetterAuthResolver {
     @Args('email') email: string,
     @Args('password') password: string,
     @Args('name', { nullable: true }) name?: string,
-  ): Promise<BetterAuthAuthModel> {
+  ): Promise<CoreBetterAuthAuthModel> {
     return super.betterAuthSignUp(email, password, name);
   }
 
@@ -133,25 +133,25 @@ export class BetterAuthResolver extends CoreBetterAuthResolver {
   // 2FA Mutations
   // ===========================================================================
 
-  @Mutation(() => BetterAuthAuthModel, {
+  @Mutation(() => CoreBetterAuthAuthModel, {
     description: 'Verify 2FA code during sign-in',
   })
   @Roles(RoleEnum.S_EVERYONE)
   override async betterAuthVerify2FA(
     @Args('code') code: string,
     @Context() ctx: { req: Request },
-  ): Promise<BetterAuthAuthModel> {
+  ): Promise<CoreBetterAuthAuthModel> {
     return super.betterAuthVerify2FA(code, ctx);
   }
 
-  @Mutation(() => BetterAuth2FASetupModel, {
+  @Mutation(() => CoreBetterAuth2FASetupModel, {
     description: 'Enable 2FA for the current user',
   })
   @Roles(RoleEnum.S_USER)
   override async betterAuthEnable2FA(
     @Args('password') password: string,
     @Context() ctx: { req: Request },
-  ): Promise<BetterAuth2FASetupModel> {
+  ): Promise<CoreBetterAuth2FASetupModel> {
     return super.betterAuthEnable2FA(password, ctx);
   }
 
@@ -179,13 +179,13 @@ export class BetterAuthResolver extends CoreBetterAuthResolver {
   // Passkey Mutations
   // ===========================================================================
 
-  @Mutation(() => BetterAuthPasskeyChallengeModel, {
+  @Mutation(() => CoreBetterAuthPasskeyChallengeModel, {
     description: 'Get passkey registration challenge for WebAuthn',
   })
   @Roles(RoleEnum.S_USER)
   override async betterAuthGetPasskeyChallenge(
     @Context() ctx: { req: Request },
-  ): Promise<BetterAuthPasskeyChallengeModel> {
+  ): Promise<CoreBetterAuthPasskeyChallengeModel> {
     return super.betterAuthGetPasskeyChallenge(ctx);
   }
 

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

@@ -5,7 +5,7 @@
  * and reduce the need for `as any` casts throughout the codebase.
  */
 
-import { BetterAuthSessionUser } from './better-auth-user.mapper';
+import { BetterAuthSessionUser } from './core-better-auth-user.mapper';
 
 /**
  * Better-Auth 2FA verification response
@@ -68,8 +68,9 @@ export interface BetterAuthSignUpResponse {
 /**
  * Type guard to check if response has session
  * Preserves the original type while asserting session is defined
+ * Includes optional token for Better Auth session authentication
  */
-export function hasSession<T>(response: T): response is T & { session: { expiresAt: Date; id: string } } {
+export function hasSession<T>(response: T): response is T & { session: { expiresAt: Date; id: string; token?: string } } {
   return (
     response !== null &&
     typeof response === 'object' &&

package/src/core/modules/better-auth/core-better-auth-api.middleware.ts

@@ -0,0 +1,134 @@
+import { Injectable, Logger, NestMiddleware } from '@nestjs/common';
+import { NextFunction, Request, Response } from 'express';
+
+import { isProduction } from '../../common/helpers/logging.helper';
+import { extractSessionToken, sendWebResponse, toWebRequest } from './core-better-auth-web.helper';
+import { CoreBetterAuthService } from './core-better-auth.service';
+
+/**
+ * List of paths that are handled by CoreBetterAuthController
+ * These should NOT be forwarded to Better Auth's native handler
+ *
+ * Only paths with nest-server-specific logic belong here:
+ * - sign-in/email: Legacy user migration, password normalization
+ * - sign-up/email: User linking to own DB, password sync
+ * - sign-out: Custom cookie clearing
+ * - session: Custom response format with mapped user
+ *
+ * All other paths (Passkey, 2FA, etc.) go directly to Better Auth's
+ * native handler via this middleware for maximum compatibility.
+ */
+const CONTROLLER_HANDLED_PATHS = [
+  '/sign-in/email',
+  '/sign-up/email',
+  '/sign-out',
+  '/session',
+];
+
+/**
+ * Middleware that forwards Better Auth API requests to the native Better Auth handler.
+ *
+ * This middleware handles ALL Better Auth plugin functionality directly:
+ * - Passkey/WebAuthn (registration, authentication, management)
+ * - Two-Factor Authentication (TOTP enable, disable, verify)
+ * - Social Login OAuth flows
+ * - Magic link authentication
+ * - Email verification
+ *
+ * The middleware:
+ * 1. Checks if the request path starts with the Better Auth base path (e.g., /iam)
+ * 2. Skips paths that need nest-server-specific logic (sign-in, sign-up, session)
+ * 3. Extracts session token and signs cookies for Better Auth compatibility
+ * 4. Converts the Express request to a Web Standard Request
+ * 5. Calls Better Auth's native handler and sends the response
+ *
+ * IMPORTANT: Cookie signing is handled here to ensure Better Auth receives
+ * properly signed session cookies for all plugin endpoints.
+ */
+@Injectable()
+export class CoreBetterAuthApiMiddleware implements NestMiddleware {
+  private readonly logger = new Logger(CoreBetterAuthApiMiddleware.name);
+  private readonly isProd = isProduction();
+
+  constructor(private readonly betterAuthService: CoreBetterAuthService) {}
+
+  async use(req: Request, res: Response, next: NextFunction) {
+    // Skip if Better-Auth is not enabled
+    if (!this.betterAuthService.isEnabled()) {
+      return next();
+    }
+
+    const basePath = this.betterAuthService.getBasePath();
+    const requestPath = req.path;
+
+    // Only handle requests that start with the Better Auth base path
+    if (!requestPath.startsWith(basePath)) {
+      return next();
+    }
+
+    // Get the path relative to the base path
+    const relativePath = requestPath.slice(basePath.length);
+
+    // Skip paths that are handled by CoreBetterAuthController (nest-server-specific logic)
+    if (CONTROLLER_HANDLED_PATHS.some((path) => relativePath === path || relativePath.startsWith(`${path}/`))) {
+      return next();
+    }
+
+    // Get the Better Auth instance
+    const authInstance = this.betterAuthService.getInstance();
+    if (!authInstance) {
+      this.logger.warn('Better Auth instance not available');
+      return next();
+    }
+
+    if (!this.isProd) {
+      this.logger.debug(`Forwarding to Better Auth handler: ${req.method} ${requestPath}`);
+    }
+
+    try {
+      // Extract session token from cookies or Authorization header
+      const sessionToken = extractSessionToken(req, basePath);
+
+      // Get config for cookie signing
+      const config = this.betterAuthService.getConfig();
+
+      // Convert Express request to Web Standard Request with proper cookie signing
+      // This ensures Better Auth receives signed cookies for session validation
+      const webRequest = await toWebRequest(req, {
+        basePath,
+        baseUrl: this.betterAuthService.getBaseUrl(),
+        logger: this.logger,
+        secret: config.secret,
+        sessionToken,
+      });
+
+      // Call Better Auth's native handler
+      const response = await authInstance.handler(webRequest);
+
+      if (!this.isProd) {
+        this.logger.debug(`Better Auth handler response: ${response.status}`);
+      }
+
+      // Convert Web Standard Response to Express response using shared helper
+      await sendWebResponse(res, response);
+    } catch (error) {
+      // Log error with appropriate detail level
+      if (this.isProd) {
+        this.logger.error('Better Auth handler error');
+      } else {
+        this.logger.error(`Better Auth handler error: ${error instanceof Error ? error.message : 'Unknown error'}`);
+      }
+
+      // Send error response if headers not sent
+      if (!res.headersSent) {
+        const message = this.isProd
+          ? 'Authentication error'
+          : (error instanceof Error ? error.message : 'Unknown error');
+        res.status(500).json({
+          error: 'Authentication handler error',
+          message,
+        });
+      }
+    }
+  }
+}

package/src/core/modules/better-auth/{better-auth-auth.model.ts → core-better-auth-auth.model.ts}

@@ -2,7 +2,7 @@ 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';
+import { CoreBetterAuthSessionInfoModel, CoreBetterAuthUserModel } from './core-better-auth-models';
 
 /**
  * Better-Auth Authentication Response Model
@@ -13,7 +13,7 @@ import { BetterAuthSessionInfoModel, BetterAuthUserModel } from './better-auth-m
  */
 @ObjectType({ description: 'Better-Auth Authentication Response' })
 @Restricted(RoleEnum.S_EVERYONE)
-export class BetterAuthAuthModel {
+export class CoreBetterAuthAuthModel {
   /**
    * Whether the authentication was successful
    */
@@ -43,20 +43,20 @@ export class BetterAuthAuthModel {
   /**
    * Authenticated user
    */
-  @Field(() => BetterAuthUserModel, {
+  @Field(() => CoreBetterAuthUserModel, {
     description: 'Authenticated user',
     nullable: true,
   })
-  user?: BetterAuthUserModel;
+  user?: CoreBetterAuthUserModel;
 
   /**
    * Session information
    */
-  @Field(() => BetterAuthSessionInfoModel, {
+  @Field(() => CoreBetterAuthSessionInfoModel, {
     description: 'Session information',
     nullable: true,
   })
-  session?: BetterAuthSessionInfoModel;
+  session?: CoreBetterAuthSessionInfoModel;
 
   /**
    * Error message if authentication failed

package/src/core/modules/better-auth/{better-auth-migration-status.model.ts → core-better-auth-migration-status.model.ts}

@@ -8,7 +8,7 @@ import { Field, Int, ObjectType } from '@nestjs/graphql';
  * safe to disable Legacy Auth.
  */
 @ObjectType({ description: 'Migration status from Legacy Auth to Better-Auth (IAM)' })
-export class BetterAuthMigrationStatusModel {
+export class CoreBetterAuthMigrationStatusModel {
   /**
    * Total number of users in the system
    */

package/src/core/modules/better-auth/{better-auth-models.ts → core-better-auth-models.ts}

@@ -8,7 +8,7 @@ import { RoleEnum } from '../../common/enums/role.enum';
  */
 @ObjectType({ description: 'Better-Auth User' })
 @Restricted(RoleEnum.S_EVERYONE)
-export class BetterAuthUserModel {
+export class CoreBetterAuthUserModel {
   @Field(() => String, { description: 'User ID' })
   id: string;
 
@@ -36,15 +36,15 @@ export class BetterAuthUserModel {
  */
 @ObjectType({ description: 'Better-Auth Session' })
 @Restricted(RoleEnum.S_USER)
-export class BetterAuthSessionModel {
+export class CoreBetterAuthSessionModel {
   @Field(() => String, { description: 'Session ID' })
   id: string;
 
   @Field(() => Date, { description: 'Session expiration date' })
   expiresAt: Date;
 
-  @Field(() => BetterAuthUserModel, { description: 'Session user' })
-  user: BetterAuthUserModel;
+  @Field(() => CoreBetterAuthUserModel, { description: 'Session user' })
+  user: CoreBetterAuthUserModel;
 }
 
 /**
@@ -52,7 +52,7 @@ export class BetterAuthSessionModel {
  */
 @ObjectType({ description: 'Better-Auth Session Info' })
 @Restricted(RoleEnum.S_EVERYONE)
-export class BetterAuthSessionInfoModel {
+export class CoreBetterAuthSessionInfoModel {
   @Field(() => String, { description: 'Session ID', nullable: true })
   id?: string;
 
@@ -68,7 +68,7 @@ export class BetterAuthSessionInfoModel {
  */
 @ObjectType({ description: 'Better-Auth 2FA setup data' })
 @Restricted(RoleEnum.S_USER)
-export class BetterAuth2FASetupModel {
+export class CoreBetterAuth2FASetupModel {
   @Field(() => Boolean, { description: 'Whether the operation was successful' })
   success: boolean;
 
@@ -87,7 +87,7 @@ export class BetterAuth2FASetupModel {
  */
 @ObjectType({ description: 'Better-Auth Passkey' })
 @Restricted(RoleEnum.S_USER)
-export class BetterAuthPasskeyModel {
+export class CoreBetterAuthPasskeyModel {
   @Field(() => String, { description: 'Passkey ID' })
   id: string;
 
@@ -106,7 +106,7 @@ export class BetterAuthPasskeyModel {
  */
 @ObjectType({ description: 'Better-Auth Passkey registration challenge' })
 @Restricted(RoleEnum.S_USER)
-export class BetterAuthPasskeyChallengeModel {
+export class CoreBetterAuthPasskeyChallengeModel {
   @Field(() => Boolean, { description: 'Whether the operation was successful' })
   success: boolean;
 
@@ -122,7 +122,7 @@ export class BetterAuthPasskeyChallengeModel {
  */
 @ObjectType({ description: 'Better-Auth features status' })
 @Restricted(RoleEnum.S_EVERYONE)
-export class BetterAuthFeaturesModel {
+export class CoreBetterAuthFeaturesModel {
   @Field(() => Boolean, { description: 'Whether Better-Auth is enabled' })
   enabled: boolean;
 

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

@@ -1,8 +1,8 @@
 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';
+import { CoreBetterAuthRateLimiter, RateLimitResult } from './core-better-auth-rate-limiter.service';
+import { CoreBetterAuthService } from './core-better-auth.service';
 
 /**
  * Middleware that applies rate limiting to Better-Auth endpoints
@@ -30,10 +30,10 @@ import { BetterAuthService } from './better-auth.service';
  * ```
  */
 @Injectable()
-export class BetterAuthRateLimitMiddleware implements NestMiddleware {
+export class CoreBetterAuthRateLimitMiddleware implements NestMiddleware {
   constructor(
-    private readonly rateLimiter: BetterAuthRateLimiter,
-    private readonly betterAuthService: BetterAuthService,
+    private readonly rateLimiter: CoreBetterAuthRateLimiter,
+    private readonly betterAuthService: CoreBetterAuthService,
   ) {}
 
   use(req: Request, res: Response, next: NextFunction) {

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

@@ -74,8 +74,8 @@ const DEFAULT_CONFIG: Required<IBetterAuthRateLimit> = {
  * ```
  */
 @Injectable()
-export class BetterAuthRateLimiter {
-  private readonly logger = new Logger(BetterAuthRateLimiter.name);
+export class CoreBetterAuthRateLimiter {
+  private readonly logger = new Logger(CoreBetterAuthRateLimiter.name);
   private readonly store = new Map<string, RateLimitEntry>();
   private config: Required<IBetterAuthRateLimit> = DEFAULT_CONFIG;
   private cleanupInterval: NodeJS.Timeout | null = null;

package/src/core/modules/better-auth/{better-auth-user.mapper.ts → core-better-auth-user.mapper.ts}

@@ -17,6 +17,7 @@ const scryptPromise = (password: string, salt: string, keylen: number, options:
 };
 
 import { RoleEnum } from '../../common/enums/role.enum';
+import { maskEmail } from '../../common/helpers/logging.helper';
 
 /**
  * Interface for Better-Auth session user
@@ -97,8 +98,8 @@ export interface SyncedUserDocument {
  * - Legacy → IAM: Creates account entry in `accounts` from `users.password`
  */
 @Injectable()
-export class BetterAuthUserMapper {
-  private readonly logger = new Logger(BetterAuthUserMapper.name);
+export class CoreBetterAuthUserMapper {
+  private readonly logger = new Logger(CoreBetterAuthUserMapper.name);
 
   constructor(@Optional() @InjectConnection() private readonly connection?: Connection) {}
 
@@ -379,7 +380,7 @@ export class BetterAuthUserMapper {
         const sha256Match = await bcrypt.compare(sha256(plainPassword), legacyUser.password);
         if (!directMatch && !sha256Match) {
           // Security: Wrong password provided for migration - reject
-          this.logger.warn(`Migration password verification failed for ${userEmail}`);
+          this.logger.warn(`Migration password verification failed for ${maskEmail(userEmail)}`);
           return false;
         }
       } else {