@lenne.tech/nest-server 11.21.2 → 11.22.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nest-server",
-  "version": "11.21.2",
+  "version": "11.22.0",
   "description": "Modern, fast, powerful Node.js web framework in TypeScript based on Nest with a GraphQL API and a connection to MongoDB (or other databases).",
   "keywords": [
     "node",
@@ -168,7 +168,11 @@
   "files": [
     "dist/**/*",
     "src/**/*",
-    "bin/**/*"
+    "bin/**/*",
+    "CLAUDE.md",
+    ".claude/rules/**/*",
+    "docs/**/*",
+    "migration-guides/**/*"
   ],
   "watch": {
     "build:dev": "src"
@@ -191,7 +195,8 @@
       "picomatch@>=4.0.0 <4.0.4": "4.0.4",
       "path-to-regexp@>=8.0.0 <8.4.0": "8.4.1",
       "kysely@>=0.26.0 <0.28.15": "0.28.15",
-      "lodash@>=4.0.0 <4.18.0": "4.18.1"
+      "lodash@>=4.0.0 <4.18.0": "4.18.1",
+      "defu@<=6.1.4": "6.1.6"
     },
     "onlyBuiltDependencies": [
       "bcrypt",

package/src/core/common/interfaces/server-options.interface.ts

@@ -2117,16 +2117,12 @@ interface IBetterAuthBase {
    * Custom controller class to use instead of the default CoreBetterAuthController.
    * The class should extend CoreBetterAuthController.
    *
-   * This allows projects to customize REST endpoints via config instead of creating
-   * a separate module. Use this with CoreModule.forRoot(envConfig) (IAM-only mode).
-   *
-   * @example
+   * @deprecated Since 11.22.0 — Use the `overrides` parameter on `CoreModule.forRoot()` instead:
    * ```typescript
-   * // config.env.ts
-   * betterAuth: {
-   *   controller: IamController,
-   * }
+   * CoreModule.forRoot(envConfig, { betterAuth: { controller: IamController } })
    * ```
+   * This separates class references from environment configuration. The config field
+   * still works for backward compatibility but `overrides` takes precedence.
    *
    * @since 11.14.0
    */
@@ -2342,16 +2338,12 @@ interface IBetterAuthBase {
    * Custom resolver class to use instead of the default DefaultBetterAuthResolver.
    * The class should extend CoreBetterAuthResolver.
    *
-   * This allows projects to customize GraphQL operations via config instead of creating
-   * a separate module. Use this with CoreModule.forRoot(envConfig) (IAM-only mode).
-   *
-   * @example
+   * @deprecated Since 11.22.0 — Use the `overrides` parameter on `CoreModule.forRoot()` instead:
    * ```typescript
-   * // config.env.ts
-   * betterAuth: {
-   *   resolver: IamResolver,
-   * }
+   * CoreModule.forRoot(envConfig, { betterAuth: { resolver: IamResolver } })
    * ```
+   * This separates class references from environment configuration. The config field
+   * still works for backward compatibility but `overrides` takes precedence.
    *
    * @since 11.14.0
    */
@@ -2663,3 +2655,78 @@ interface IBetterAuthWithPasskey extends IBetterAuthBase {
    */
   trustedOrigins: string[];
 }
+
+/**
+ * Override default implementations of core module components.
+ *
+ * Use this as the second parameter of `CoreModule.forRoot()` to replace
+ * default controllers, resolvers, or services with project-specific implementations.
+ *
+ * This keeps class references (code) separate from environment configuration (strings/numbers)
+ * and ensures each module's `forRoot()` is called exactly once — preventing duplicate
+ * controller registration.
+ *
+ * Each core module that supports customization has a typed entry here.
+ * Only specified components are overridden — unset fields use defaults.
+ *
+ * @example
+ * ```typescript
+ * // IAM-only mode with overrides
+ * CoreModule.forRoot(envConfig, {
+ *   errorCode: { controller: ErrorCodeController, service: ErrorCodeService },
+ *   betterAuth: { resolver: BetterAuthResolver },
+ * })
+ *
+ * // Legacy mode with overrides
+ * CoreModule.forRoot(CoreAuthService, AuthModule.forRoot(envConfig.jwt), envConfig, {
+ *   errorCode: { controller: ErrorCodeController, service: ErrorCodeService },
+ *   betterAuth: { controller: BetterAuthController, resolver: BetterAuthResolver },
+ * })
+ * ```
+ *
+ * @since 11.22.0
+ */
+export interface ICoreModuleOverrides {
+  /**
+   * Override BetterAuth controller and/or resolver.
+   *
+   * The custom controller must extend `CoreBetterAuthController`.
+   * The custom resolver must extend `CoreBetterAuthResolver` and re-declare
+   * all GraphQL decorators (`@Mutation`, `@Query`, `@Roles`).
+   *
+   * @example
+   * ```typescript
+   * {
+   *   betterAuth: {
+   *     controller: BetterAuthController,
+   *     resolver: BetterAuthResolver,
+   *   },
+   * }
+   * ```
+   */
+  betterAuth?: {
+    controller?: Type<any>;
+    resolver?: Type<any>;
+  };
+
+  /**
+   * Override ErrorCode controller and/or service.
+   *
+   * The custom controller can be standalone (recommended) or extend `CoreErrorCodeController`.
+   * The custom service must extend `CoreErrorCodeService`.
+   *
+   * @example
+   * ```typescript
+   * {
+   *   errorCode: {
+   *     controller: ErrorCodeController,
+   *     service: ErrorCodeService,
+   *   },
+   * }
+   * ```
+   */
+  errorCode?: {
+    controller?: Type<any>;
+    service?: Type<any>;
+  };
+}

package/src/core/modules/better-auth/CUSTOMIZATION.md

@@ -41,29 +41,23 @@ export class ServerModule {}
 - Default `CoreBetterAuthController` and `DefaultBetterAuthResolver` are registered
 - No additional configuration needed
 
-### Pattern 2: Config-based Controller/Resolver (Recommended for Customization)
+### Pattern 2: Overrides Parameter (Recommended for Customization)
 
 **Use when:** Need custom Controller or Resolver, but don't need a separate module.
 
-```typescript
-// config.env.ts
-import { IamController } from './server/modules/iam/iam.controller';
-import { IamResolver } from './server/modules/iam/iam.resolver';
-
-const config = {
-  betterAuth: {
-    controller: IamController, // Custom controller class
-    resolver: IamResolver, // Custom resolver class
-    // ... other betterAuth config
-  },
-};
-```
-
 ```typescript
 // server.module.ts
+import { IamController } from './modules/iam/iam.controller';
+import { IamResolver } from './modules/iam/iam.resolver';
+
 @Module({
   imports: [
-    CoreModule.forRoot(envConfig), // Uses custom controller/resolver from config
+    CoreModule.forRoot(envConfig, {
+      betterAuth: {
+        controller: IamController,
+        resolver: IamResolver,
+      },
+    }),
   ],
 })
 export class ServerModule {}
@@ -71,9 +65,22 @@ export class ServerModule {}
 
 **What happens:**
 
-- CoreModule passes `controller`/`resolver` to `CoreBetterAuthModule.forRoot()`
+- CoreModule passes overrides to `CoreBetterAuthModule.forRoot()`
 - Your custom classes are registered instead of defaults
 - Single registration point, no duplicate imports
+- Class references stay separate from environment config
+
+**Alternative:** Set `controller`/`resolver` directly in config (backward compatible):
+
+```typescript
+// config.env.ts — still works but overrides parameter is preferred
+const config = {
+  betterAuth: {
+    controller: IamController,
+    resolver: IamResolver,
+  },
+};
+```
 
 ### Pattern 3: Separate Module (autoRegister: false)
 

package/src/core/modules/better-auth/INTEGRATION-CHECKLIST.md

@@ -23,11 +23,11 @@
 
 ### Registration Patterns (Quick Reference)
 
-| Pattern             | Use When                           | Configuration                                      |
-| ------------------- | ---------------------------------- | -------------------------------------------------- |
-| **Zero-Config**     | No customization needed            | Just use `CoreModule.forRoot(envConfig)`           |
-| **Config-based**    | Custom Controller/Resolver         | Add `controller`/`resolver` to `betterAuth` config |
-| **Separate Module** | Full control, additional providers | Set `autoRegister: false` in config                |
+| Pattern                     | Use When                           | Configuration                                                                                 |
+| --------------------------- | ---------------------------------- | --------------------------------------------------------------------------------------------- |
+| **Zero-Config**             | No customization needed            | Just use `CoreModule.forRoot(envConfig)`                                                      |
+| **Overrides** (recommended) | Custom Controller/Resolver         | Pass `overrides` to `CoreModule.forRoot(envConfig, { betterAuth: { controller, resolver } })` |
+| **Separate Module**         | Full control, additional providers | Set `autoRegister: false` in config                                                           |
 
 **Details:** See [CUSTOMIZATION.md](./CUSTOMIZATION.md#module-registration-patterns)
 

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

@@ -1019,32 +1019,36 @@ export class CoreBetterAuthUserMapper {
       const migrationPercentage = totalUsers > 0 ? Math.round((fullyMigratedUsers / totalUsers) * 100 * 100) / 100 : 0;
 
       // Get emails of pending users (limit to 100)
-      const pendingUsers = await usersCollection
-        .aggregate([
-          {
-            $lookup: {
-              as: 'accounts',
-              foreignField: 'userId',
-              from: 'account',
-              localField: '_id',
-            },
-          },
-          {
-            $match: {
-              $or: [
-                { iamId: { $exists: false } },
-                { iamId: null },
-                {
-                  $and: [{ iamId: { $exists: true, $ne: null } }, { 'accounts.providerId': { $ne: 'credential' } }],
-                },
-              ],
-            },
-          },
-          { $limit: 100 },
-          { $project: { email: 1 } },
-        ])
+      // Two-phase approach: first get users without iamId (no $lookup needed),
+      // then check users with iamId but missing credential account
+      const usersWithoutIamId = await usersCollection
+        .find({ $or: [{ iamId: { $exists: false } }, { iamId: null }] })
+        .limit(100)
+        .project({ email: 1 })
         .toArray();
-      const pendingUserEmails = pendingUsers.map((u) => u.email).filter(Boolean);
+
+      const remaining = 100 - usersWithoutIamId.length;
+      let usersWithIamButNoAccount: { email?: string }[] = [];
+      if (remaining > 0) {
+        usersWithIamButNoAccount = await usersCollection
+          .aggregate([
+            { $match: { iamId: { $exists: true, $ne: null } } },
+            {
+              $lookup: {
+                as: 'accounts',
+                foreignField: 'userId',
+                from: 'account',
+                localField: '_id',
+              },
+            },
+            { $match: { 'accounts.providerId': { $ne: 'credential' } } },
+            { $limit: remaining },
+            { $project: { email: 1 } },
+          ])
+          .toArray();
+      }
+
+      const pendingUserEmails = [...usersWithoutIamId, ...usersWithIamButNoAccount].map((u) => u.email).filter(Boolean);
 
       // Can disable legacy auth only if ALL users are fully migrated
       const canDisableLegacyAuth = totalUsers > 0 && fullyMigratedUsers === totalUsers;

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

@@ -88,15 +88,19 @@ export class CoreBetterAuthService implements OnModuleInit {
     try {
       const db = this.connection.db;
 
-      // Session collection: token lookup (getSessionByToken) and user+expiry lookup (getActiveSessionForUser)
-      await db.collection('session').createIndex({ token: 1 });
-      await db.collection('session').createIndex({ userId: 1, expiresAt: 1 });
-
-      // Users collection: iamId lookup (mapSessionUser uses $or with email and iamId)
-      // email is typically already indexed by Mongoose schema, but iamId may not be
-      await db.collection('users').createIndex({ iamId: 1 }, { sparse: true });
-
-      this.logger.debug('Performance indices ensured on session and users collections');
+      // All indices are idempotent (no-op if already exists) and independent — run in parallel
+      await Promise.all([
+        // Session: token lookup (getSessionByToken) and user+expiry lookup (getActiveSessionForUser)
+        db.collection('session').createIndex({ token: 1 }),
+        db.collection('session').createIndex({ userId: 1, expiresAt: 1 }),
+        // Users: iamId lookup (mapSessionUser uses $or with email and iamId)
+        db.collection('users').createIndex({ iamId: 1 }, { sparse: true }),
+        // Account: userId lookup ($lookup in getMigrationStatus) and providerId filtering
+        db.collection('account').createIndex({ userId: 1 }),
+        db.collection('account').createIndex({ providerId: 1, userId: 1 }),
+      ]);
+
+      this.logger.debug('Performance indices ensured on session, users, and account collections');
     } catch (error) {
       // Non-fatal: indices improve performance but are not required for correctness
       this.logger.warn(`Could not create performance indices: ${error instanceof Error ? error.message : 'unknown'}`);

package/src/core/modules/error-code/INTEGRATION-CHECKLIST.md

@@ -141,16 +141,15 @@ NestJS @Global() modules use "first wins" for provider registration. Without thi
 
 **Update:** `src/server/server.module.ts`
 
+Use the `overrides` parameter of `CoreModule.forRoot()` (recommended since v11.22.0):
+
 ```typescript
-import { ErrorCodeModule as CoreErrorCodeModule } from '@lenne.tech/nest-server';
 import { ErrorCodeService } from './modules/error-code/error-code.service';
 
 @Module({
   imports: [
-    CoreModule.forRoot(...),
-    // Register with custom service
-    CoreErrorCodeModule.forRoot({
-      service: ErrorCodeService,
+    CoreModule.forRoot(envConfig, {
+      errorCode: { service: ErrorCodeService },
     }),
     // ... other modules
   ],
@@ -158,6 +157,22 @@ import { ErrorCodeService } from './modules/error-code/error-code.service';
 export class ServerModule {}
 ```
 
+**Alternative** (for complex setups): disable auto-registration and import separately:
+
+```typescript
+import { ErrorCodeModule as CoreErrorCodeModule } from '@lenne.tech/nest-server';
+import { ErrorCodeService } from './modules/error-code/error-code.service';
+
+@Module({
+  imports: [
+    CoreModule.forRoot({ ...envConfig, errorCode: { autoRegister: false } }),
+    CoreErrorCodeModule.forRoot({ service: ErrorCodeService }),
+    // ... other modules
+  ],
+})
+export class ServerModule {}
+```
+
 ---
 
 ## Scenario C: Custom Controller (For Custom Routes)
@@ -168,7 +183,7 @@ Use this when you need:
 - Different route paths
 - Additional REST endpoints
 
-**No custom module needed!** Use Core `ErrorCodeModule.forRoot()` with your custom controller and service.
+**No custom module needed!** Use the `overrides` parameter of `CoreModule.forRoot()`.
 
 ### 1. Create Files
 
@@ -183,13 +198,29 @@ Files needed:
 
 **No `error-code.module.ts` needed!**
 
-### 2. Disable Auto-Registration
+### 2. Register via CoreModule.forRoot() Overrides (Recommended)
 
-Same as Scenario B, Step 3.
+**Update:** `src/server/server.module.ts`
 
-### 3. Register via Core ErrorCodeModule
+```typescript
+import { ErrorCodeController } from './modules/error-code/error-code.controller';
+import { ErrorCodeService } from './modules/error-code/error-code.service';
 
-**Update:** `src/server/server.module.ts`
+@Module({
+  imports: [
+    CoreModule.forRoot(envConfig, {
+      errorCode: {
+        controller: ErrorCodeController,
+        service: ErrorCodeService,
+      },
+    }),
+    // ... other modules
+  ],
+})
+export class ServerModule {}
+```
+
+**Alternative** (for complex setups): disable auto-registration and import separately:
 
 ```typescript
 import { ErrorCodeModule } from '@lenne.tech/nest-server';
@@ -198,8 +229,7 @@ import { ErrorCodeService } from './modules/error-code/error-code.service';
 
 @Module({
   imports: [
-    CoreModule.forRoot(...),
-    // Use Core ErrorCodeModule with custom service and controller
+    CoreModule.forRoot({ ...envConfig, errorCode: { autoRegister: false } }),
     ErrorCodeModule.forRoot({
       controller: ErrorCodeController,
       service: ErrorCodeService,

package/src/core/modules/error-code/error-code.module.ts

@@ -12,8 +12,10 @@ import { IErrorCodeModuleConfig } from './interfaces/error-code.interfaces';
  *
  * @example
  * ```typescript
- * // Basic usage (auto-register in CoreModule)
- * // No explicit import needed - included in CoreModule
+ * // Basic usage (auto-register in CoreModule via overrides)
+ * CoreModule.forRoot(envConfig, {
+ *   errorCode: { controller: ErrorCodeController, service: ErrorCodeService },
+ * })
  *
  * // Extended usage (with custom error registry - RECOMMENDED)
  * const ProjectErrors = {
@@ -25,13 +27,6 @@ import { IErrorCodeModuleConfig } from './interfaces/error-code.interfaces';
  * } as const satisfies IErrorRegistry;
  *
  * ErrorCodeModule.forRoot({ additionalErrorRegistry: ProjectErrors })
- *
- * // Extended usage (with custom controller and service)
- * ErrorCodeModule.forRoot({
- *   additionalErrorRegistry: ProjectErrors,
- *   controller: ErrorCodeController,
- *   service: ErrorCodeService,
- * })
  * ```
  */
 @Global()

package/src/core/modules/tenant/INTEGRATION-CHECKLIST.md

@@ -121,7 +121,18 @@ Normal (non-hierarchy) roles also work:
 async viewAuditLog(...) { ... }
 ```
 
-### 8. Skip Tenant Check for Non-Tenant Endpoints
+### 8. System Roles as OR Alternatives
+
+System roles (`S_EVERYONE`, `S_USER`, `S_VERIFIED`) are checked as OR alternatives **before** real role checks in `CoreTenantGuard`. If a system role grants access, real roles in the same `@Roles()` are alternatives, not requirements.
+
+When `X-Tenant-Id` header is present and a system role grants access:
+
+- `S_EVERYONE`: public — membership is optionally enriched but never blocks
+- `S_USER`/`S_VERIFIED`: membership is validated (403 if not a member; admin bypass applies)
+
+`@SkipTenantCheck()` suppresses membership validation for `S_USER`/`S_VERIFIED` paths — authentication/verification is still enforced, but no membership check runs even with a header present.
+
+### 9. Skip Tenant Check for Non-Tenant Endpoints
 
 Use `@SkipTenantCheck()` for endpoints that intentionally work without tenant context:
 
@@ -133,7 +144,7 @@ import { SkipTenantCheck, Roles, RoleEnum } from '@lenne.tech/nest-server';
 async listMyTenants() { ... }
 ```
 
-### 9. BetterAuth (IAM) Coexistence
+### 10. BetterAuth (IAM) Coexistence
 
 When both `multiTenancy` and `betterAuth` are active, IAM endpoints (sign-in, sign-up, session, etc.)
 automatically skip tenant validation when no `X-Tenant-Id` header is sent (`betterAuth.skipTenantCheck: true`, default).

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

@@ -138,9 +138,33 @@ Roles not in `roleHierarchy` use exact match — no higher role can compensate:
 async auditLog(@CurrentTenant() tenantId: string) { ... }
 ```
 
+### System Roles as OR Alternatives
+
+When `@Roles()` includes system roles (`S_EVERYONE`, `S_USER`, `S_VERIFIED`), `CoreTenantGuard` checks them **before** real roles in priority order. If a system role is satisfied, access is granted immediately — real roles in the same decorator are OR alternatives, not additional requirements.
+
+```typescript
+@Roles(RoleEnum.ADMIN)    // Class: admin can always access all methods
+@Controller('users')
+class UserController {
+  @Roles(RoleEnum.S_USER)  // Method: any authenticated user (extends class ADMIN via OR)
+  getProfile() { ... }     // → admin OR authenticated user can access
+
+  @Roles(RoleEnum.S_EVERYONE) // Method: public endpoint (extends class ADMIN via OR)
+  getPublicInfo() { ... }     // → anyone can access
+}
+```
+
+**Method-level system roles take precedence** for the system role check. Class `@Roles(S_EVERYONE)` does not make a method `@Roles(S_USER)` endpoint public — the method's `S_USER` applies.
+
+| System Role | No Header             | Header Present                                     |
+| ----------- | --------------------- | -------------------------------------------------- |
+| S_EVERYONE  | Pass (public)         | Pass + optional tenant context enrichment          |
+| S_USER      | Pass if authenticated | Pass if authenticated member; admin bypass applies |
+| S_VERIFIED  | Pass if verified      | Pass if verified member; admin bypass applies      |
+
 ### Tenant Context Rule
 
-**When a tenant header is present:** Only `membership.role` is checked. `user.roles` is ignored (except ADMIN bypass).
+**When a tenant header is present:** For real role checks, only `membership.role` is checked. `user.roles` is ignored (except ADMIN bypass). For system role checks (`S_USER`, `S_VERIFIED`), membership is validated to set tenant context (`tenantId`, `tenantRole`), but access depends on membership existence, not role level.
 
 **When no tenant header:** `user.roles` is checked instead. Hierarchy roles use level comparison, normal roles use exact match.
 
@@ -161,6 +185,7 @@ async listMyTenants() { ... }
 ```
 
 Note: `@SkipTenantCheck()` with hierarchy roles still checks `user.roles` (no tenant context).
+It also suppresses tenant membership validation for `S_USER`/`S_VERIFIED` system role paths — when set, these roles still enforce authentication/verification but skip the membership check even when a tenant header is present.
 
 ### Admin Bypass