@lenne.tech/nest-server 11.6.2 → 11.7.0

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

@@ -8,8 +8,13 @@
  * - Two-Factor Authentication (TOTP)
  * - Passkey/WebAuthn authentication
  * - Social Login (Google, GitHub, Apple)
- * - Legacy password handling for migration
  * - Rate limiting for brute-force protection
+ * - Parallel operation with Legacy Auth (bcrypt compatible)
+ *
+ * Extension points:
+ * - CoreBetterAuthController: Abstract controller for REST extension
+ * - CoreBetterAuthResolver: Abstract resolver for GraphQL extension (isAbstract: true)
+ * - BetterAuthController/BetterAuthResolver: Default implementations
  */
 
 export * from './better-auth-auth.model';
@@ -23,3 +28,5 @@ export * from './better-auth.module';
 export * from './better-auth.resolver';
 export * from './better-auth.service';
 export * from './better-auth.types';
+export * from './core-better-auth.controller';
+export * from './core-better-auth.resolver';

package/src/core.module.ts

@@ -229,8 +229,9 @@ export class CoreModule implements NestModule {
       imports.push(CoreHealthCheckModule);
     }
 
-    // Add BetterAuthModule - enabled by default unless explicitly disabled
-    if (config.betterAuth?.enabled !== false) {
+    // Add BetterAuthModule only if autoRegister is explicitly true
+    // By default (autoRegister: false), projects integrate via an extended module in their project
+    if (config.betterAuth?.enabled !== false && config.betterAuth?.autoRegister === true) {
       imports.push(
         BetterAuthModule.forRoot({
           config: config.betterAuth || {},

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

@@ -0,0 +1,41 @@
+import { Controller } from '@nestjs/common';
+
+import { Roles } from '../../../core/common/decorators/roles.decorator';
+import { RoleEnum } from '../../../core/common/enums/role.enum';
+import { ConfigService } from '../../../core/common/services/config.service';
+import { BetterAuthUserMapper } from '../../../core/modules/better-auth/better-auth-user.mapper';
+import { BetterAuthService } from '../../../core/modules/better-auth/better-auth.service';
+import { CoreBetterAuthController } from '../../../core/modules/better-auth/core-better-auth.controller';
+
+/**
+ * Server BetterAuth REST Controller
+ *
+ * This controller extends CoreBetterAuthController and can be customized
+ * for project-specific requirements (e.g., sending welcome emails,
+ * custom validation, audit logging).
+ *
+ * @example
+ * ```typescript
+ * // Add custom behavior after sign-up
+ * override async signUp(res: Response, input: BetterAuthSignUpInput) {
+ *   const result = await super.signUp(res, input);
+ *
+ *   if (result.success && result.user) {
+ *     await this.emailService.sendWelcomeEmail(result.user.email);
+ *   }
+ *
+ *   return result;
+ * }
+ * ```
+ */
+@Controller('iam')
+@Roles(RoleEnum.ADMIN)
+export class BetterAuthController extends CoreBetterAuthController {
+  constructor(
+    protected override readonly betterAuthService: BetterAuthService,
+    protected override readonly userMapper: BetterAuthUserMapper,
+    protected override readonly configService: ConfigService,
+  ) {
+    super(betterAuthService, userMapper, configService);
+  }
+}

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

@@ -0,0 +1,88 @@
+import { DynamicModule, Module } from '@nestjs/common';
+
+import { IBetterAuth } from '../../../core/common/interfaces/server-options.interface';
+import { BetterAuthModule as CoreBetterAuthModule } from '../../../core/modules/better-auth/better-auth.module';
+import { BetterAuthController } from './better-auth.controller';
+import { BetterAuthResolver } from './better-auth.resolver';
+
+/**
+ * Options for BetterAuthModule.forRoot()
+ */
+export interface ServerBetterAuthModuleOptions {
+  /**
+   * Better-auth configuration from environment
+   */
+  config: IBetterAuth;
+
+  /**
+   * Fallback secrets for backwards compatibility with JWT config.
+   * If no betterAuth.secret is configured, these secrets are tried in order.
+   */
+  fallbackSecrets?: (string | undefined)[];
+}
+
+/**
+ * Server BetterAuthModule - Project-specific Better-Auth integration
+ *
+ * This module wraps the core BetterAuthModule and provides project-specific
+ * customization through the BetterAuthController and BetterAuthResolver.
+ *
+ * Following the same pattern as src/server/modules/auth/auth.module.ts:
+ * - Core module provides abstract/base functionality
+ * - Server module provides project-specific implementations
+ *
+ * @example
+ * ```typescript
+ * // In server.module.ts
+ * import { BetterAuthModule } from './modules/better-auth/better-auth.module';
+ *
+ * @Module({
+ *   imports: [
+ *     CoreModule.forRoot(CoreAuthService, AuthModule.forRoot(envConfig.jwt), {
+ *       ...envConfig,
+ *       betterAuth: { ...envConfig.betterAuth, autoRegister: false },
+ *     }),
+ *     BetterAuthModule.forRoot({
+ *       config: envConfig.betterAuth,
+ *       fallbackSecrets: [envConfig.jwt?.secret, envConfig.jwt?.refresh?.secret],
+ *     }),
+ *   ],
+ * })
+ * export class ServerModule {}
+ * ```
+ */
+@Module({})
+export class BetterAuthModule {
+  /**
+   * Creates a dynamic module with project-specific Better-Auth configuration
+   *
+   * @param options - Configuration options
+   * @returns Dynamic module configuration
+   */
+  static forRoot(options: ServerBetterAuthModuleOptions): DynamicModule {
+    const { config, fallbackSecrets } = options;
+
+    // If better-auth is explicitly disabled, return minimal module
+    if (config?.enabled === false) {
+      return {
+        exports: [],
+        module: BetterAuthModule,
+        providers: [],
+      };
+    }
+
+    return {
+      exports: [CoreBetterAuthModule],
+      imports: [
+        CoreBetterAuthModule.forRoot({
+          config,
+          controller: BetterAuthController,
+          fallbackSecrets,
+          resolver: BetterAuthResolver,
+        }),
+      ],
+      module: BetterAuthModule,
+      providers: [],
+    };
+  }
+}

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

@@ -0,0 +1,201 @@
+import { UseGuards } from '@nestjs/common';
+import { Args, Context, Mutation, Query, Resolver } from '@nestjs/graphql';
+import { Request, Response } from 'express';
+
+import { Roles } from '../../../core/common/decorators/roles.decorator';
+import { RoleEnum } from '../../../core/common/enums/role.enum';
+import { AuthGuardStrategy } from '../../../core/modules/auth/auth-guard-strategy.enum';
+import { AuthGuard } from '../../../core/modules/auth/guards/auth.guard';
+import { BetterAuthAuthModel } from '../../../core/modules/better-auth/better-auth-auth.model';
+import {
+  BetterAuth2FASetupModel,
+  BetterAuthFeaturesModel,
+  BetterAuthPasskeyChallengeModel,
+  BetterAuthPasskeyModel,
+  BetterAuthSessionModel,
+} from '../../../core/modules/better-auth/better-auth-models';
+import { BetterAuthUserMapper } from '../../../core/modules/better-auth/better-auth-user.mapper';
+import { BetterAuthService } from '../../../core/modules/better-auth/better-auth.service';
+import { CoreBetterAuthResolver } from '../../../core/modules/better-auth/core-better-auth.resolver';
+
+/**
+ * Server BetterAuth GraphQL Resolver
+ *
+ * This resolver extends CoreBetterAuthResolver and exposes all GraphQL operations.
+ * The `isAbstract: true` pattern in NestJS GraphQL requires concrete classes to
+ * explicitly override and decorate methods for them to be registered in the schema.
+ *
+ * Each method delegates to the parent implementation via `super.methodName()`.
+ * Override any method to add custom behavior (e.g., sending welcome emails after signup).
+ *
+ * @example
+ * ```typescript
+ * // Add custom behavior after sign-up
+ * override async betterAuthSignUp(email: string, password: string, name?: string) {
+ *   const result = await super.betterAuthSignUp(email, password, name);
+ *
+ *   if (result.success && result.user) {
+ *     await this.emailService.sendWelcomeEmail(result.user.email);
+ *   }
+ *
+ *   return result;
+ * }
+ * ```
+ */
+@Resolver(() => BetterAuthAuthModel)
+@Roles(RoleEnum.ADMIN)
+export class BetterAuthResolver extends CoreBetterAuthResolver {
+  constructor(
+    protected override readonly betterAuthService: BetterAuthService,
+    protected override readonly userMapper: BetterAuthUserMapper,
+  ) {
+    super(betterAuthService, userMapper);
+  }
+
+  // ===========================================================================
+  // Queries
+  // ===========================================================================
+
+  @Query(() => BetterAuthSessionModel, {
+    description: 'Get current Better-Auth session',
+    nullable: true,
+  })
+  @Roles(RoleEnum.S_USER)
+  @UseGuards(AuthGuard(AuthGuardStrategy.JWT))
+  override async betterAuthSession(@Context() ctx: { req: Request }): Promise<BetterAuthSessionModel | null> {
+    return super.betterAuthSession(ctx);
+  }
+
+  @Query(() => Boolean, { description: 'Check if Better-Auth is enabled' })
+  @Roles(RoleEnum.S_EVERYONE)
+  override betterAuthEnabled(): boolean {
+    return super.betterAuthEnabled();
+  }
+
+  @Query(() => BetterAuthFeaturesModel, { description: 'Get enabled Better-Auth features' })
+  @Roles(RoleEnum.S_EVERYONE)
+  override betterAuthFeatures(): BetterAuthFeaturesModel {
+    return super.betterAuthFeatures();
+  }
+
+  @Query(() => [BetterAuthPasskeyModel], {
+    description: 'List passkeys for the current user',
+    nullable: true,
+  })
+  @Roles(RoleEnum.S_USER)
+  @UseGuards(AuthGuard(AuthGuardStrategy.JWT))
+  override async betterAuthListPasskeys(@Context() ctx: { req: Request }): Promise<BetterAuthPasskeyModel[] | null> {
+    return super.betterAuthListPasskeys(ctx);
+  }
+
+  // ===========================================================================
+  // Authentication Mutations
+  // ===========================================================================
+
+  @Mutation(() => BetterAuthAuthModel, {
+    description: 'Sign in via Better-Auth (email/password)',
+  })
+  @Roles(RoleEnum.S_EVERYONE)
+  override async betterAuthSignIn(
+    @Args('email') email: string,
+    @Args('password') password: string,
+    @Context() ctx: { req: Request; res: Response },
+  ): Promise<BetterAuthAuthModel> {
+    return super.betterAuthSignIn(email, password, ctx);
+  }
+
+  @Mutation(() => BetterAuthAuthModel, {
+    description: 'Sign up via Better-Auth (email/password)',
+  })
+  @Roles(RoleEnum.S_EVERYONE)
+  override async betterAuthSignUp(
+    @Args('email') email: string,
+    @Args('password') password: string,
+    @Args('name', { nullable: true }) name?: string,
+  ): Promise<BetterAuthAuthModel> {
+    return super.betterAuthSignUp(email, password, name);
+  }
+
+  @Mutation(() => Boolean, { description: 'Sign out via Better-Auth' })
+  @Roles(RoleEnum.S_USER)
+  @UseGuards(AuthGuard(AuthGuardStrategy.JWT))
+  override async betterAuthSignOut(@Context() ctx: { req: Request }): Promise<boolean> {
+    return super.betterAuthSignOut(ctx);
+  }
+
+  // ===========================================================================
+  // 2FA Mutations
+  // ===========================================================================
+
+  @Mutation(() => BetterAuthAuthModel, {
+    description: 'Verify 2FA code during sign-in',
+  })
+  @Roles(RoleEnum.S_EVERYONE)
+  override async betterAuthVerify2FA(
+    @Args('code') code: string,
+    @Context() ctx: { req: Request },
+  ): Promise<BetterAuthAuthModel> {
+    return super.betterAuthVerify2FA(code, ctx);
+  }
+
+  @Mutation(() => BetterAuth2FASetupModel, {
+    description: 'Enable 2FA for the current user',
+  })
+  @Roles(RoleEnum.S_USER)
+  @UseGuards(AuthGuard(AuthGuardStrategy.JWT))
+  override async betterAuthEnable2FA(
+    @Args('password') password: string,
+    @Context() ctx: { req: Request },
+  ): Promise<BetterAuth2FASetupModel> {
+    return super.betterAuthEnable2FA(password, ctx);
+  }
+
+  @Mutation(() => Boolean, {
+    description: 'Disable 2FA for the current user',
+  })
+  @Roles(RoleEnum.S_USER)
+  @UseGuards(AuthGuard(AuthGuardStrategy.JWT))
+  override async betterAuthDisable2FA(
+    @Args('password') password: string,
+    @Context() ctx: { req: Request },
+  ): Promise<boolean> {
+    return super.betterAuthDisable2FA(password, ctx);
+  }
+
+  @Mutation(() => [String], {
+    description: 'Generate new backup codes for 2FA',
+    nullable: true,
+  })
+  @Roles(RoleEnum.S_USER)
+  @UseGuards(AuthGuard(AuthGuardStrategy.JWT))
+  override async betterAuthGenerateBackupCodes(@Context() ctx: { req: Request }): Promise<null | string[]> {
+    return super.betterAuthGenerateBackupCodes(ctx);
+  }
+
+  // ===========================================================================
+  // Passkey Mutations
+  // ===========================================================================
+
+  @Mutation(() => BetterAuthPasskeyChallengeModel, {
+    description: 'Get passkey registration challenge for WebAuthn',
+  })
+  @Roles(RoleEnum.S_USER)
+  @UseGuards(AuthGuard(AuthGuardStrategy.JWT))
+  override async betterAuthGetPasskeyChallenge(
+    @Context() ctx: { req: Request },
+  ): Promise<BetterAuthPasskeyChallengeModel> {
+    return super.betterAuthGetPasskeyChallenge(ctx);
+  }
+
+  @Mutation(() => Boolean, {
+    description: 'Delete a passkey by ID',
+  })
+  @Roles(RoleEnum.S_USER)
+  @UseGuards(AuthGuard(AuthGuardStrategy.JWT))
+  override async betterAuthDeletePasskey(
+    @Args('passkeyId') passkeyId: string,
+    @Context() ctx: { req: Request },
+  ): Promise<boolean> {
+    return super.betterAuthDeletePasskey(passkeyId, ctx);
+  }
+}

package/src/server/server.module.ts

@@ -10,6 +10,7 @@ import { CoreAuthService } from '../core/modules/auth/services/core-auth.service
 import { CronJobs } from './common/services/cron-jobs.service';
 import { AuthController } from './modules/auth/auth.controller';
 import { AuthModule } from './modules/auth/auth.module';
+import { BetterAuthModule } from './modules/better-auth/better-auth.module';
 import { FileModule } from './modules/file/file.module';
 import { ServerController } from './server.controller';
 
@@ -24,11 +25,12 @@ import { ServerController } from './server.controller';
   controllers: [ServerController, AuthController],
 
   // Export modules for reuse in other modules
-  exports: [CoreModule, AuthModule, FileModule],
+  exports: [CoreModule, AuthModule, BetterAuthModule, FileModule],
 
   // Include modules
   imports: [
     // Include CoreModule for standard processes
+    // Note: BetterAuthModule is imported manually below (autoRegister defaults to false)
     CoreModule.forRoot(CoreAuthService, AuthModule.forRoot(envConfig.jwt), envConfig),
 
     // Include cron job handling
@@ -38,6 +40,13 @@ import { ServerController } from './server.controller';
     // which will also include UserModule
     AuthModule.forRoot(envConfig.jwt),
 
+    // Include BetterAuthModule for better-auth integration
+    // This allows project-specific customization via BetterAuthResolver
+    BetterAuthModule.forRoot({
+      config: envConfig.betterAuth,
+      fallbackSecrets: [envConfig.jwt?.secret, envConfig.jwt?.refresh?.secret],
+    }),
+
     // Include FileModule for file handling
     FileModule,
   ],