@lenne.tech/nest-server 11.13.4 → 11.14.0

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

@@ -0,0 +1,225 @@
+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/modules/tus/INTEGRATION-CHECKLIST.md

@@ -8,18 +8,19 @@
 
 ## Do You Need This Checklist?
 
-| Scenario | Checklist Needed? |
-|----------|-------------------|
-| Use TUS with defaults (everyone can upload) | No - works automatically |
-| Require authentication for uploads | Yes - Step 1 |
-| Custom upload handling (notifications, etc.) | Yes - Step 2 |
-| Disable TUS completely | No - just use `TusModule.forRoot({ config: false })` |
+| Scenario                                     | Checklist Needed?                                    |
+| -------------------------------------------- | ---------------------------------------------------- |
+| Use TUS with defaults (everyone can upload)  | No - works automatically                             |
+| Require authentication for uploads           | Yes - Step 1                                         |
+| Custom upload handling (notifications, etc.) | Yes - Step 2                                         |
+| Disable TUS completely                       | No - just use `TusModule.forRoot({ config: false })` |
 
 ---
 
 ## Reference Implementation
 
 **Local (in your node_modules):**
+
 ```
 node_modules/@lenne.tech/nest-server/src/server/server.module.ts
 ```
@@ -116,13 +117,13 @@ TusModule.forRoot({
     path: '/uploads',
     expiration: { expiresIn: '12h' },
   },
-})
+});
 ```
 
 ### Disable TUS
 
 ```typescript
-TusModule.forRoot({ config: false })
+TusModule.forRoot({ config: false });
 ```
 
 ---
@@ -140,11 +141,11 @@ TusModule.forRoot({ config: false })
 
 ## Common Mistakes
 
-| Mistake | Symptom | Fix |
-|---------|---------|-----|
-| Forgot to register custom controller | Default S_EVERYONE permissions | Add `controller: TusController` to forRoot() |
-| Custom controller missing @Roles | No authentication required | Add `@Roles(RoleEnum.S_USER)` to controller class |
-| Using wrong endpoint path | 404 on upload | Ensure client uses same path as config |
+| Mistake                              | Symptom                        | Fix                                               |
+| ------------------------------------ | ------------------------------ | ------------------------------------------------- |
+| Forgot to register custom controller | Default S_EVERYONE permissions | Add `controller: TusController` to forRoot()      |
+| Custom controller missing @Roles     | No authentication required     | Add `@Roles(RoleEnum.S_USER)` to controller class |
+| Using wrong endpoint path            | 404 on upload                  | Ensure client uses same path as config            |
 
 ---
 
@@ -173,4 +174,4 @@ upload.start();
 ## Detailed Documentation
 
 - **README.md:** `node_modules/@lenne.tech/nest-server/src/core/modules/tus/README.md`
-- **GitHub:** https://github.com/lenneTech/nest-server/blob/develop/src/core/modules/tus/README.md
+- **GitHub:** https://github.com/lenneTech/nest-server/blob/develop/src/core/modules/tus/README.md

package/src/core/modules/tus/README.md

@@ -12,12 +12,12 @@ Integration of the [tus.io](https://tus.io) resumable upload protocol with @lenn
 TusModule.forRoot({
   config: {
     maxSize: 100 * 1024 * 1024, // 100 MB instead of 50 GB default
-    path: '/uploads',           // Custom path instead of /tus
+    path: '/uploads', // Custom path instead of /tus
   },
-})
+});
 
 // To disable:
-TusModule.forRoot({ config: false })
+TusModule.forRoot({ config: false });
 ```
 
 **Quick Links:** [Integration Checklist](./INTEGRATION-CHECKLIST.md) | [Endpoints](#endpoints) | [Configuration](#configuration) | [Client Usage](#client-usage)
@@ -47,14 +47,14 @@ TusModule.forRoot({ config: false })
 
 ### TUS Protocol Extensions (All Enabled by Default)
 
-| Extension | Description |
-|-----------|-------------|
-| **creation** | Create new uploads via POST |
-| **creation-with-upload** | Include data in creation request |
-| **termination** | Delete incomplete uploads |
-| **expiration** | Auto-cleanup of abandoned uploads |
-| **checksum** | Verify data integrity |
-| **concatenation** | Combine multiple uploads |
+| Extension                | Description                       |
+| ------------------------ | --------------------------------- |
+| **creation**             | Create new uploads via POST       |
+| **creation-with-upload** | Include data in creation request  |
+| **termination**          | Delete incomplete uploads         |
+| **expiration**           | Auto-cleanup of abandoned uploads |
+| **checksum**             | Verify data integrity             |
+| **concatenation**        | Combine multiple uploads          |
 
 ---
 
@@ -87,13 +87,13 @@ TUS is **enabled by default** with the following configuration:
 
 All endpoints are handled by the TUS protocol via `@tus/server`:
 
-| Method | Endpoint | Description |
-|--------|----------|-------------|
-| OPTIONS | `/tus` | Get server capabilities |
-| POST | `/tus` | Create new upload |
-| HEAD | `/tus/:id` | Get upload status/offset |
-| PATCH | `/tus/:id` | Continue upload |
-| DELETE | `/tus/:id` | Terminate upload |
+| Method  | Endpoint   | Description              |
+| ------- | ---------- | ------------------------ |
+| OPTIONS | `/tus`     | Get server capabilities  |
+| POST    | `/tus`     | Create new upload        |
+| HEAD    | `/tus/:id` | Get upload status/offset |
+| PATCH   | `/tus/:id` | Continue upload          |
+| DELETE  | `/tus/:id` | Terminate upload         |
 
 ### CORS Headers
 
@@ -115,10 +115,10 @@ The TUS server automatically handles CORS headers for browser-based clients:
 
 ```typescript
 // In server.module.ts
-TusModule.forRoot({ config: false })
+TusModule.forRoot({ config: false });
 
 // Or via environment config
-tus: false
+tus: false;
 ```
 
 ### Custom Configuration
@@ -148,29 +148,30 @@ TusModule.forRoot({
       expiresIn: '12h', // Cleanup after 12 hours
     },
   },
-})
+});
 ```
 
 ### Configuration Options
 
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `enabled` | boolean | `true` | Enable/disable TUS |
-| `path` | string | `/tus` | Endpoint path |
-| `maxSize` | number | 50 GB | Maximum file size in bytes |
-| `allowedTypes` | string[] | undefined | Allowed MIME types (all if undefined) |
-| `allowedHeaders` | string[] | `[]` | Additional custom headers (TUS headers already included) |
-| `uploadDir` | string | `uploads/tus` | Temporary upload directory |
-| `creation` | boolean | `true` | Enable creation extension |
-| `creationWithUpload` | boolean | `true` | Enable creation-with-upload extension |
-| `termination` | boolean | `true` | Enable termination extension |
-| `expiration` | boolean \| object | `{ expiresIn: '24h' }` | Expiration configuration |
-| `checksum` | boolean | `true` | Enable checksum extension |
-| `concatenation` | boolean | `true` | Enable concatenation extension |
+| Option               | Type              | Default                | Description                                              |
+| -------------------- | ----------------- | ---------------------- | -------------------------------------------------------- |
+| `enabled`            | boolean           | `true`                 | Enable/disable TUS                                       |
+| `path`               | string            | `/tus`                 | Endpoint path                                            |
+| `maxSize`            | number            | 50 GB                  | Maximum file size in bytes                               |
+| `allowedTypes`       | string[]          | undefined              | Allowed MIME types (all if undefined)                    |
+| `allowedHeaders`     | string[]          | `[]`                   | Additional custom headers (TUS headers already included) |
+| `uploadDir`          | string            | `uploads/tus`          | Temporary upload directory                               |
+| `creation`           | boolean           | `true`                 | Enable creation extension                                |
+| `creationWithUpload` | boolean           | `true`                 | Enable creation-with-upload extension                    |
+| `termination`        | boolean           | `true`                 | Enable termination extension                             |
+| `expiration`         | boolean \| object | `{ expiresIn: '24h' }` | Expiration configuration                                 |
+| `checksum`           | boolean           | `true`                 | Enable checksum extension                                |
+| `concatenation`      | boolean           | `true`                 | Enable concatenation extension                           |
 
 **Note on `allowedHeaders`:**
 
 `@tus/server` already includes all TUS protocol headers by default:
+
 - Authorization, Content-Type, Location, Tus-Extension, Tus-Max-Size
 - Tus-Resumable, Tus-Version, Upload-Concat, Upload-Defer-Length
 - Upload-Length, Upload-Metadata, Upload-Offset, X-HTTP-Method-Override
@@ -281,7 +282,7 @@ Then register with custom controller:
 // server.module.ts
 TusModule.forRoot({
   controller: TusController,
-})
+});
 ```
 
 ### Custom Upload Handler
@@ -346,13 +347,13 @@ query {
 
 The following metadata is stored with each GridFS file:
 
-| Field | Source |
-|-------|--------|
-| `filename` | From TUS `Upload-Metadata` header |
-| `contentType` | From TUS `filetype` metadata |
-| `tusUploadId` | Original TUS upload ID |
-| `originalMetadata` | All TUS metadata |
-| `uploadedAt` | Completion timestamp |
+| Field              | Source                            |
+| ------------------ | --------------------------------- |
+| `filename`         | From TUS `Upload-Metadata` header |
+| `contentType`      | From TUS `filetype` metadata      |
+| `tusUploadId`      | Original TUS upload ID            |
+| `originalMetadata` | All TUS metadata                  |
+| `uploadedAt`       | Completion timestamp              |
 
 ---
 
@@ -363,6 +364,7 @@ The following metadata is stored with each GridFS file:
 **Cause:** TUS server not initialized
 
 **Solutions:**
+
 1. Check if TUS is disabled in config (`tus: false`)
 2. Verify MongoDB connection is established
 3. Check server logs for initialization errors
@@ -372,6 +374,7 @@ The following metadata is stored with each GridFS file:
 **Cause:** Upload expired or server restarted
 
 **Solutions:**
+
 1. Check expiration configuration (default: 24h)
 2. Increase `expiration.expiresIn` if needed
 3. Client should handle `onError` and create new upload
@@ -381,6 +384,7 @@ The following metadata is stored with each GridFS file:
 **Cause:** Missing or incorrect CORS configuration
 
 **Solutions:**
+
 1. Verify client sends correct headers
 2. Check that `Tus-Resumable` header is included
 3. Ensure server CORS allows TUS headers
@@ -390,6 +394,7 @@ The following metadata is stored with each GridFS file:
 **Cause:** Upload incomplete or migration failed
 
 **Solutions:**
+
 1. Verify upload completed (check `onSuccess` callback)
 2. Check server logs for migration errors
 3. Verify MongoDB GridFS bucket exists (`fs.files`, `fs.chunks`)
@@ -399,6 +404,7 @@ The following metadata is stored with each GridFS file:
 **Cause:** File exceeds `maxSize` limit
 
 **Solutions:**
+
 1. Increase `maxSize` in configuration
 2. Check for proxy/nginx upload limits
 3. Verify client `chunkSize` is reasonable
@@ -436,4 +442,4 @@ The following metadata is stored with each GridFS file:
 - [tus.io Protocol](https://tus.io/protocols/resumable-upload)
 - [tus-js-client](https://github.com/tus/tus-js-client)
 - [@tus/server](https://github.com/tus/tus-node-server)
-- [FileModule Documentation](../file/README.md)
+- [FileModule Documentation](../file/README.md)

package/src/core/modules/user/core-user.service.ts

@@ -121,8 +121,7 @@ export abstract class CoreUserService<
   /**
    * Get verified state of user by token
    */
-  // eslint-disable-next-line unused-imports/no-unused-vars
-  async getVerifiedState(token: string, serviceOptions?: ServiceOptions): Promise<boolean> {
+  async getVerifiedState(token: string, _serviceOptions?: ServiceOptions): Promise<boolean> {
     const user = await this.mainDbModel.findOne({ verificationToken: token }).exec();
 
     if (!user) {

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
 // =====================================================================================================================

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

@@ -22,15 +22,7 @@ export class AuthModule {
     return {
       controllers: [AuthController],
       exports: [AuthController, AuthResolver, CoreAuthModule, AuthService],
-      imports: [
-        CoreAuthModule.forRoot(UserModule, UserService, {
-          ...options,
-          ...{
-            // imports: [], // Integrate additional Services here to resolve dependencies
-            // providers: [] // Integrate additional Providers here to resolve dependencies
-          },
-        }),
-      ],
+      imports: [CoreAuthModule.forRoot(UserModule, UserService, { ...options })],
       module: AuthModule,
       providers: [AuthController, AuthResolver, AuthService, EmailService],
     };

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

@@ -107,7 +107,9 @@ export class BetterAuthResolver extends CoreBetterAuthResolver {
     nullable: true,
   })
   @Roles(RoleEnum.S_USER)
-  override async betterAuthListPasskeys(@Context() ctx: { req: Request }): Promise<CoreBetterAuthPasskeyModel[] | null> {
+  override async betterAuthListPasskeys(
+    @Context() ctx: { req: Request },
+  ): Promise<CoreBetterAuthPasskeyModel[] | null> {
     return super.betterAuthListPasskeys(ctx);
   }