@lenne.tech/nest-server 11.13.3 → 11.13.5

package/src/core/modules/system-setup/core-system-setup.service.ts

@@ -0,0 +1,226 @@
+import { ForbiddenException, Injectable, Logger, OnApplicationBootstrap } from '@nestjs/common';
+import { InjectConnection } from '@nestjs/mongoose';
+import { isEmail } from 'class-validator';
+import { Connection } from 'mongoose';
+
+import { ConfigService } from '../../common/services/config.service';
+import { CoreBetterAuthUserMapper } from '../better-auth/core-better-auth-user.mapper';
+import { CoreBetterAuthService } from '../better-auth/core-better-auth.service';
+import { ErrorCode } from '../error-code/error-codes';
+
+/**
+ * Input for creating the initial admin user
+ */
+export interface SystemSetupInitInput {
+  email: string;
+  name?: string;
+  password: string;
+}
+
+/**
+ * Response for successful init
+ */
+export interface SystemSetupInitResult {
+  email: string;
+  message: string;
+  success: boolean;
+}
+
+/**
+ * Response for setup status check
+ */
+export interface SystemSetupStatus {
+  betterAuthEnabled: boolean;
+  needsSetup: boolean;
+}
+
+/**
+ * CoreSystemSetupService provides initial admin creation for fresh deployments.
+ *
+ * This service allows creating the first admin user when the system has zero users.
+ * It bypasses BetterAuth's disableSignUp check by using the internal adapter directly,
+ * which is the same approach used by Better-Auth's own admin plugin.
+ *
+ * Security:
+ * - Only works when zero users exist in the database
+ * - Once any user exists, the init endpoint is permanently locked
+ * - Race conditions handled by MongoDB unique email index
+ */
+@Injectable()
+export class CoreSystemSetupService implements OnApplicationBootstrap {
+  private readonly logger = new Logger(CoreSystemSetupService.name);
+
+  constructor(
+    @InjectConnection() private readonly connection: Connection,
+    private readonly betterAuthService: CoreBetterAuthService,
+    private readonly userMapper: CoreBetterAuthUserMapper,
+    private readonly configService: ConfigService,
+  ) {}
+
+  /**
+   * Automatically create the initial admin on server start if configured via
+   * `systemSetup.initialAdmin` in config or ENV variables.
+   *
+   * Uses OnApplicationBootstrap (not OnModuleInit) to ensure BetterAuth
+   * is fully initialized before attempting user creation.
+   */
+  async onApplicationBootstrap(): Promise<void> {
+    const initialAdmin = this.configService.configFastButReadOnly?.systemSetup?.initialAdmin;
+
+    // No initialAdmin config at all → skip silently
+    if (!initialAdmin) {
+      return;
+    }
+
+    // Partial credentials → warn and skip
+    if (!initialAdmin.email || !initialAdmin.password) {
+      const missing = [
+        !initialAdmin.email && 'email',
+        !initialAdmin.password && 'password',
+      ].filter(Boolean).join(', ');
+      this.logger.warn(`Incomplete initialAdmin config - missing: ${missing}. Auto-creation skipped.`);
+      return;
+    }
+
+    // Validate email format (same validator as @IsEmail() decorator)
+    if (!isEmail(initialAdmin.email)) {
+      this.logger.warn(`Invalid initialAdmin email format: "${initialAdmin.email}". Auto-creation skipped.`);
+      return;
+    }
+
+    // Validate password is not empty/whitespace
+    if (!initialAdmin.password.trim()) {
+      this.logger.warn('Empty initialAdmin password. Auto-creation skipped.');
+      return;
+    }
+
+    const status = await this.getSetupStatus();
+    if (!status.needsSetup) {
+      return;
+    }
+
+    if (!status.betterAuthEnabled) {
+      this.logger.warn('Initial admin auto-creation skipped: BetterAuth not enabled');
+      return;
+    }
+
+    try {
+      const result = await this.createInitialAdmin({
+        email: initialAdmin.email,
+        name: initialAdmin.name,
+        password: initialAdmin.password,
+      });
+      this.logger.log(`Auto-created initial admin on startup: ${result.email}`);
+    } catch (error) {
+      if (error instanceof ForbiddenException) {
+        this.logger.log('Initial admin auto-creation skipped (users already exist)');
+      } else {
+        this.logger.warn(`Initial admin auto-creation failed: ${error instanceof Error ? error.message : 'Unknown error'}`);
+      }
+    }
+  }
+
+  /**
+   * Check if the system needs initial setup (zero users)
+   */
+  async getSetupStatus(): Promise<SystemSetupStatus> {
+    const userCount = await this.connection.collection('users').countDocuments({});
+    return {
+      betterAuthEnabled: this.betterAuthService.isEnabled(),
+      needsSetup: userCount === 0,
+    };
+  }
+
+  /**
+   * Create the initial admin user when zero users exist.
+   *
+   * Uses BetterAuth's internalAdapter to bypass disableSignUp,
+   * then syncs to nest-server users collection with admin role.
+   */
+  async createInitialAdmin(input: SystemSetupInitInput): Promise<SystemSetupInitResult> {
+    // Pre-check: only allow when zero users exist
+    const userCount = await this.connection.collection('users').countDocuments({});
+    if (userCount > 0) {
+      throw new ForbiddenException(ErrorCode.SYSTEM_SETUP_NOT_AVAILABLE);
+    }
+
+    // Ensure BetterAuth is enabled
+    if (!this.betterAuthService.isEnabled()) {
+      throw new ForbiddenException(ErrorCode.SYSTEM_SETUP_BETTERAUTH_REQUIRED);
+    }
+
+    const authInstance = this.betterAuthService.getInstance();
+    if (!authInstance) {
+      throw new ForbiddenException(ErrorCode.SYSTEM_SETUP_BETTERAUTH_REQUIRED);
+    }
+
+    try {
+      // Access BetterAuth internal context (same pattern as core-better-auth-api.middleware.ts)
+      const context = await authInstance.$context;
+
+      // Normalize password for IAM (SHA256 if plain text)
+      const normalizedPassword = this.userMapper.normalizePasswordForIam(input.password);
+
+      // Create user via internalAdapter (bypasses disableSignUp)
+      const iamUser = await context.internalAdapter.createUser({
+        email: input.email,
+        emailVerified: true,
+        name: input.name || input.email.split('@')[0],
+      });
+
+      if (!iamUser) {
+        throw new Error('Failed to create IAM user');
+      }
+
+      // Hash password and create credential account
+      const hashedPassword = await context.password.hash(normalizedPassword);
+      await context.internalAdapter.linkAccount({
+        accountId: iamUser.id,
+        password: hashedPassword,
+        providerId: 'credential',
+        userId: iamUser.id,
+      });
+
+      // Sync to nest-server users collection
+      const syncedUser = await this.userMapper.linkOrCreateUser({
+        email: iamUser.email,
+        emailVerified: true,
+        id: iamUser.id,
+        name: iamUser.name,
+      });
+
+      if (!syncedUser) {
+        throw new Error('Failed to sync user to nest-server collection');
+      }
+
+      // Set admin role directly
+      await this.connection
+        .collection('users')
+        .updateOne({ _id: syncedUser._id }, { $set: { roles: ['admin'], updatedAt: new Date() } });
+
+      // Sync password to Legacy Auth for backwards compatibility
+      await this.userMapper.syncPasswordToLegacy(iamUser.id, input.email, input.password);
+
+      this.logger.log(`Initial admin user created: ${input.email}`);
+
+      return {
+        email: input.email,
+        message: 'Initial admin user created successfully',
+        success: true,
+      };
+    } catch (error) {
+      // Handle duplicate email (race condition via MongoDB unique index)
+      if (error instanceof Error && (error.message?.includes('duplicate key') || error.message?.includes('E11000'))) {
+        throw new ForbiddenException(ErrorCode.SYSTEM_SETUP_NOT_AVAILABLE);
+      }
+
+      // Re-throw known exceptions
+      if (error instanceof ForbiddenException) {
+        throw error;
+      }
+
+      this.logger.error(`System setup failed: ${error instanceof Error ? error.message : 'Unknown error'}`);
+      throw new ForbiddenException(ErrorCode.SYSTEM_SETUP_NOT_AVAILABLE);
+    }
+  }
+}

package/src/core.module.ts

@@ -24,6 +24,7 @@ import { CoreBetterAuthModule } from './core/modules/better-auth/core-better-aut
 import { CoreBetterAuthService } from './core/modules/better-auth/core-better-auth.service';
 import { ErrorCodeModule } from './core/modules/error-code/error-code.module';
 import { CoreHealthCheckModule } from './core/modules/health-check/core-health-check.module';
+import { CoreSystemSetupModule } from './core/modules/system-setup/core-system-setup.module';
 
 /**
  * Core module (dynamic)
@@ -143,9 +144,9 @@ export class CoreModule implements NestModule {
 
     // Build GraphQL driver configuration based on auth mode
     const graphQlDriverConfig = isIamOnlyMode
-      ? (isAutoRegisterDisabledEarly
+      ? isAutoRegisterDisabledEarly
         ? this.buildLazyIamGraphQlDriver(cors, options)
-        : this.buildIamOnlyGraphQlDriver(cors, options))
+        : this.buildIamOnlyGraphQlDriver(cors, options)
       : this.buildLegacyGraphQlDriver(AuthService, AuthModule, cors, options);
 
     const config: IServerOptions = merge(
@@ -261,16 +262,14 @@ export class CoreModule implements NestModule {
     // Determine if BetterAuth is explicitly disabled
     // In IAM-only mode: enabled by default (undefined = true), only false or { enabled: false } disables
     // In Legacy mode: disabled by default (undefined = false), must be explicitly enabled
-    const isExplicitlyDisabled = betterAuthConfig === false ||
-      (typeof betterAuthConfig === 'object' && betterAuthConfig?.enabled === false);
-    const isExplicitlyEnabled = betterAuthConfig === true ||
-      (typeof betterAuthConfig === 'object' && betterAuthConfig?.enabled !== false);
+    const isExplicitlyDisabled =
+      betterAuthConfig === false || (typeof betterAuthConfig === 'object' && betterAuthConfig?.enabled === false);
+    const isExplicitlyEnabled =
+      betterAuthConfig === true || (typeof betterAuthConfig === 'object' && betterAuthConfig?.enabled !== false);
 
     // IAM-only mode: enabled unless explicitly disabled
     // Legacy mode: enabled only if explicitly enabled
-    const isBetterAuthEnabled = isIamOnlyMode
-      ? !isExplicitlyDisabled
-      : isExplicitlyEnabled;
+    const isBetterAuthEnabled = isIamOnlyMode ? !isExplicitlyDisabled : isExplicitlyEnabled;
 
     const isAutoRegister = typeof betterAuthConfig === 'object' && betterAuthConfig?.autoRegister === true;
     // autoRegister: false means the project imports its own BetterAuthModule separately
@@ -304,6 +303,12 @@ export class CoreModule implements NestModule {
       }
     }
 
+    // Add CoreSystemSetupModule when BetterAuth is active
+    // Enabled by default - disable explicitly via systemSetup: { enabled: false }
+    if (isBetterAuthEnabled && config.systemSetup?.enabled !== false) {
+      imports.push(CoreSystemSetupModule);
+    }
+
     // Set exports
     const exports: any[] = [ConfigService, EmailService, TemplateService, MailjetService];
     if (!process.env.VITEST) {

package/src/index.ts

@@ -167,6 +167,14 @@ export * from './core/modules/health-check/core-health-check.service';
 
 export * from './core/modules/migrate';
 
+// =====================================================================================================================
+// Core - Modules - SystemSetup
+// =====================================================================================================================
+
+export * from './core/modules/system-setup/core-system-setup.controller';
+export * from './core/modules/system-setup/core-system-setup.module';
+export * from './core/modules/system-setup/core-system-setup.service';
+
 // =====================================================================================================================
 // Core - Modules - Tus
 // =====================================================================================================================