@lenne.tech/nest-server 11.20.1 → 11.21.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nest-server",
-  "version": "11.20.1",
+  "version": "11.21.1",
   "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",
@@ -73,26 +73,26 @@
     "node": ">= 20"
   },
   "dependencies": {
-    "@apollo/server": "5.4.0",
+    "@apollo/server": "5.5.0",
     "@as-integrations/express5": "1.1.2",
-    "@better-auth/passkey": "1.5.4",
+    "@better-auth/passkey": "1.5.5",
     "@getbrevo/brevo": "3.0.1",
     "@nestjs/apollo": "13.2.4",
-    "@nestjs/common": "11.1.16",
-    "@nestjs/core": "11.1.16",
+    "@nestjs/common": "11.1.17",
+    "@nestjs/core": "11.1.17",
     "@nestjs/graphql": "13.2.4",
     "@nestjs/jwt": "11.0.2",
     "@nestjs/mongoose": "11.0.4",
     "@nestjs/passport": "11.0.5",
-    "@nestjs/platform-express": "11.1.16",
+    "@nestjs/platform-express": "11.1.17",
     "@nestjs/schedule": "6.1.1",
     "@nestjs/swagger": "11.2.6",
     "@nestjs/terminus": "11.1.1",
-    "@nestjs/websockets": "11.1.16",
+    "@nestjs/websockets": "11.1.17",
     "@tus/file-store": "2.0.0",
     "@tus/server": "2.3.0",
     "bcrypt": "6.0.0",
-    "better-auth": "1.5.4",
+    "better-auth": "1.5.5",
     "class-transformer": "0.5.1",
     "class-validator": "0.15.1",
     "compression": "1.8.1",
@@ -100,18 +100,18 @@
     "dotenv": "17.3.1",
     "ejs": "5.0.1",
     "express": "5.2.1",
-    "graphql": "16.13.1",
+    "graphql": "16.13.2",
     "graphql-query-complexity": "1.1.0",
     "graphql-subscriptions": "3.0.0",
     "graphql-upload": "15.0.2",
     "js-sha256": "0.11.1",
     "json-to-graphql-query": "2.3.0",
     "lodash": "4.17.23",
-    "mongodb": "7.1.0",
-    "mongoose": "9.3.0",
+    "mongodb": "7.1.1",
+    "mongoose": "9.3.3",
     "multer": "2.1.1",
     "node-mailjet": "6.0.11",
-    "nodemailer": "8.0.2",
+    "nodemailer": "8.0.4",
     "passport": "0.7.0",
     "passport-jwt": "4.0.1",
     "reflect-metadata": "0.2.2",
@@ -122,31 +122,31 @@
   },
   "devDependencies": {
     "@compodoc/compodoc": "1.2.1",
-    "@nestjs/cli": "11.0.16",
-    "@nestjs/schematics": "11.0.9",
-    "@nestjs/testing": "11.1.16",
+    "@nestjs/cli": "11.0.17",
+    "@nestjs/schematics": "11.0.10",
+    "@nestjs/testing": "11.1.17",
     "@swc/cli": "0.8.0",
-    "@swc/core": "1.15.18",
+    "@swc/core": "1.15.21",
     "@types/compression": "1.8.1",
     "@types/cookie-parser": "1.4.10",
     "@types/ejs": "3.1.5",
     "@types/express": "5.0.6",
     "@types/lodash": "4.17.24",
     "@types/multer": "2.1.0",
-    "@types/node": "25.4.0",
+    "@types/node": "25.5.0",
     "@types/nodemailer": "7.0.11",
     "@types/passport": "1.0.17",
     "@types/supertest": "7.2.0",
-    "@vitest/coverage-v8": "4.0.18",
-    "@vitest/ui": "4.0.18",
+    "@vitest/coverage-v8": "4.1.2",
+    "@vitest/ui": "4.1.2",
     "ansi-colors": "4.1.3",
     "find-file-up": "2.0.1",
     "husky": "9.1.7",
     "nodemon": "3.1.14",
     "npm-watch": "0.13.0",
     "otpauth": "9.5.0",
-    "oxfmt": "0.38.0",
-    "oxlint": "1.53.0",
+    "oxfmt": "0.43.0",
+    "oxlint": "1.58.0",
     "rimraf": "6.1.3",
     "supertest": "7.2.2",
     "ts-node": "10.9.2",
@@ -157,7 +157,7 @@
     "vite": "7.3.1",
     "vite-plugin-node": "7.0.0",
     "vite-tsconfig-paths": "6.1.1",
-    "vitest": "4.0.18"
+    "vitest": "4.1.2"
   },
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -179,10 +179,21 @@
       "minimatch@<3.1.4": "3.1.4",
       "minimatch@>=9.0.0 <9.0.7": "9.0.7",
       "minimatch@>=10.0.0 <10.2.3": "10.2.4",
-      "rollup@>=4.0.0 <4.59.0": "4.59.0",
+      "rollup@>=4.0.0 <4.60.1": "4.60.1",
       "ajv@<6.14.0": "6.14.0",
       "ajv@>=7.0.0-alpha.0 <8.18.0": "8.18.0",
-      "file-type@>=13.0.0 <21.3.1": "21.3.1"
+      "file-type@>=13.0.0 <21.3.2": "21.3.2",
+      "undici@>=7.0.0 <7.24.0": "7.24.3",
+      "yauzl@<3.2.1": "3.2.1",
+      "flatted@<=3.4.1": "3.4.2",
+      "srvx@<0.11.13": "0.11.13",
+      "handlebars@>=4.0.0 <4.7.9": "4.7.9",
+      "brace-expansion@<1.1.13": "1.1.13",
+      "brace-expansion@>=4.0.0 <5.0.5": "5.0.5",
+      "picomatch@<2.3.2": "2.3.2",
+      "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"
     },
     "onlyBuiltDependencies": [
       "bcrypt",

package/src/core/common/decorators/restricted.decorator.ts

@@ -5,7 +5,9 @@ import _ = require('lodash');
 import { ProcessType } from '../enums/process-type.enum';
 import { RoleEnum } from '../enums/role.enum';
 import { equalIds, getIncludedIds } from '../helpers/db.helper';
+import { RequestContext } from '../services/request-context.service';
 import { RequireAtLeastOne } from '../types/required-at-least-one.type';
+import { checkRoleAccess } from '../../modules/tenant/core-tenant.helpers';
 
 /**
  * Restricted meta key
@@ -61,7 +63,14 @@ export const getRestricted = (object: unknown, propertyKey?: string): Restricted
  */
 export const checkRestricted = (
   data: any,
-  user: { emailVerified?: any; hasRole: (roles: string[]) => boolean; id: any; verified?: any; verifiedAt?: any },
+  user: {
+    emailVerified?: any;
+    hasRole: (roles: string[]) => boolean;
+    id: any;
+    roles?: string[];
+    verified?: any;
+    verifiedAt?: any;
+  },
   options: {
     allowCreatorOfParent?: boolean;
     checkObjectItself?: boolean;
@@ -163,7 +172,8 @@ export const checkRestricted = (
         (roles.includes(RoleEnum.S_CREATOR) &&
           (('createdBy' in data && equalIds(data.createdBy, user)) ||
             (config.allowCreatorOfParent && !('createdBy' in data) && config.isCreatorOfParent))) ||
-        (roles.includes(RoleEnum.S_VERIFIED) && (user?.verified || user?.verifiedAt || user?.emailVerified))
+        (roles.includes(RoleEnum.S_VERIFIED) && (user?.verified || user?.verifiedAt || user?.emailVerified)) ||
+        (user?.id && checkRoleAccess(roles, user?.roles, RequestContext.get()?.tenantRole))
       ) {
         valid = true;
       }

package/src/core/common/helpers/input.helper.ts

@@ -783,15 +783,30 @@ export function processDeep(
     specialProperties?: string[];
   },
 ): any {
-  // Set options
-  const { processedObjects, specialClasses, specialFunctions, specialProperties } = {
-    processedObjects: new WeakMap(),
-    specialClasses: [],
-    specialFunctions: [],
-    specialProperties: [],
-    ...options,
+  // Set options once and reuse for all recursive calls (avoids creating new objects per property)
+  const resolvedOptions = {
+    processedObjects: options?.processedObjects ?? new WeakMap(),
+    specialClasses: options?.specialClasses ?? [],
+    specialFunctions: options?.specialFunctions ?? [],
+    specialProperties: options?.specialProperties ?? [],
   };
 
+  return processDeepInternal(data, func, resolvedOptions);
+}
+
+/** Internal recursive implementation that reuses the resolved options object */
+function processDeepInternal(
+  data: any,
+  func: (data: any) => any,
+  options: {
+    processedObjects: WeakMap<any, boolean>;
+    specialClasses: ((new (args: any[]) => any) | string)[];
+    specialFunctions: string[];
+    specialProperties: string[];
+  },
+): any {
+  const { processedObjects, specialClasses, specialFunctions, specialProperties } = options;
+
   // Check for falsifiable values
   if (!data) {
     return func(data);
@@ -806,7 +821,7 @@ export function processDeep(
 
   // Process array
   if (Array.isArray(data)) {
-    return func(data.map((item) => processDeep(item, func, { processedObjects, specialClasses })));
+    return func(data.map((item) => processDeepInternal(item, func, options)));
   }
 
   // Process object
@@ -826,7 +841,7 @@ export function processDeep(
       }
     }
     for (const [key, value] of Object.entries(data)) {
-      data[key] = processDeep(value, func, { processedObjects, specialClasses });
+      data[key] = processDeepInternal(value, func, options);
     }
     return func(data);
   }

package/src/core/common/interceptors/check-security.interceptor.ts

@@ -62,18 +62,17 @@ export class CheckSecurityInterceptor implements NestInterceptor {
 
       // Check data
       if (data && typeof data === 'object' && typeof data.securityCheck === 'function') {
-        const dataJson = JSON.stringify(data);
+        // Only capture pre-check state when debug is active (JSON.stringify is expensive)
+        const dataJson = this.config.debug ? JSON.stringify(data) : undefined;
         const response = data.securityCheck(user, force);
-        new Promise(() => {
-          if (this.config.debug && dataJson !== JSON.stringify(response)) {
-            const id = getStringIds(data);
-            console.debug(
-              'CheckSecurityInterceptor: securityCheck changed data of type',
-              data.constructor.name,
-              id && !Array.isArray(id) ? `with ID: ${id}` : '',
-            );
-          }
-        });
+        if (this.config.debug && dataJson !== JSON.stringify(response)) {
+          const id = getStringIds(data);
+          console.debug(
+            'CheckSecurityInterceptor: securityCheck changed data of type',
+            data.constructor.name,
+            id && !Array.isArray(id) ? `with ID: ${id}` : '',
+          );
+        }
         if (response && !data._doNotCheckSecurityDeep) {
           for (const key of Object.keys(response)) {
             response[key] = check(response[key]);
@@ -109,12 +108,19 @@ export class CheckSecurityInterceptor implements NestInterceptor {
     // Fallback: Remove known secret fields regardless of model type (recursive into plain objects)
     const isPlainLike = (val: any): boolean => {
       if (!val || typeof val !== 'object' || Array.isArray(val)) return false;
-      // Skip Streams, Buffers, Dates, RegExps and other special objects
+      // Skip Streams, Buffers, Dates, RegExps, Maps, Sets
       if (typeof val.pipe === 'function') return false;
       if (Buffer.isBuffer(val)) return false;
       if (val instanceof Date || val instanceof RegExp) return false;
+      if (val instanceof Map || val instanceof Set) return false;
+      // Skip Mongoose documents and BSON types (they have circular internal references)
+      if (val.$__ !== undefined || val._bsontype !== undefined) return false;
       const proto = Object.getPrototypeOf(val);
-      return proto === null || proto === Object.prototype || typeof val.constructor === 'function';
+      // Only recurse into actual plain objects (created via {} or Object.create(null)).
+      // Previously used `typeof val.constructor === 'function'` which was too broad and
+      // caused infinite recursion on Mongoose Schema.Types.Mixed fields whose internal
+      // objects (Schema, SchemaType) have circular references.
+      return proto === null || proto === Object.prototype;
     };
     const visited = new WeakSet();
     const removeSecrets = (data: any) => {

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

@@ -817,15 +817,12 @@ export interface IJwt {
 }
 
 /**
- * Multi-tenancy configuration
+ * Multi-tenancy configuration for automatic tenant-based data isolation.
  *
  * Follows the "presence implies enabled" pattern:
  * - `undefined`: Feature disabled (no overhead)
  * - `{}`: Feature enabled with defaults
  * - `{ enabled: false }`: Pre-configured but disabled
- */
-/**
- * Multi-tenancy configuration for automatic tenant-based data isolation.
  *
  * @since 11.20.0
  */
@@ -838,26 +835,85 @@ export interface IMultiTenancy {
   enabled?: boolean;
 
   /**
-   * Field name on `req.user` that contains the tenant identifier.
+   * Model names (NOT collection names) to exclude from tenant filtering.
+   * These schemas will not have tenant isolation applied.
+   * The TenantMember model is always excluded automatically.
+   * @example ['User', 'Session']
+   */
+  excludeSchemas?: string[];
+
+  /**
+   * Header name for tenant selection.
+   * The header value contains the tenant ID for the current request.
+   * @default 'x-tenant-id'
+   * @since 11.21.0
+   */
+  headerName?: string;
+
+  /**
+   * Mongoose model name for the membership collection.
+   * Must be registered via MongooseModule.forFeature().
+   * @default 'TenantMember'
+   * @since 11.21.0
+   */
+  membershipModel?: string;
+
+  /**
+   * Whether system admins (RoleEnum.ADMIN) bypass the membership check.
+   * When true, admins can access any tenant without being a member.
+   * @default true
+   * @since 11.21.0
+   */
+  adminBypass?: boolean;
+
+  /**
+   * Custom role hierarchy for tenant membership roles.
+   * Keys = role names (stored in membership documents), values = numeric levels.
+   * Higher value = more privileges. Multiple roles can share the same level.
+   *
+   * Hierarchy roles use level comparison: a higher level includes all lower levels.
+   * Roles NOT in this config are treated as "normal roles" with exact match semantics.
+   *
+   * Use `createHierarchyRoles(hierarchy)` to generate type-safe constants for decorators.
    *
-   * **Important:** This only controls which property on `req.user` is read.
-   * The document schema field name is always `tenantId` and is not configurable.
-   * Example: `userField: 'organizationId'` reads `req.user.organizationId` but
-   * filters/sets the `tenantId` field on documents.
+   * @default { member: 1, manager: 2, owner: 3 }
+   * @since 11.21.0
+   *
+   * @example
+   * ```typescript
+   * // config.env.ts
+   * multiTenancy: {
+   *   roleHierarchy: { viewer: 1, editor: 2, manager: 2, admin: 3, owner: 4 }
+   * }
    *
-   * **Falsy values:** If the resolved value is falsy (undefined, null, or empty string ''),
-   * the user is treated as having no tenant — they will only see documents with `tenantId: null`.
+   * // roles.ts
+   * import { createHierarchyRoles } from '@lenne.tech/nest-server';
+   * export const HR = createHierarchyRoles({ viewer: 1, editor: 2, manager: 2, admin: 3, owner: 4 });
    *
-   * @default 'tenantId'
+   * // resolver.ts
+   * @Roles(HR.EDITOR) // requires level >= 2 (editor, manager, admin, owner)
+   * ```
    */
-  userField?: string;
+  roleHierarchy?: Record<string, number>;
 
   /**
-   * Model names (NOT collection names) to exclude from tenant filtering.
-   * These schemas will not have tenant isolation applied.
-   * @example ['User', 'Session']
+   * TTL in milliseconds for the tenant guard's in-memory membership cache.
+   * The cache avoids repeated DB lookups when the same user accesses the same tenant.
+   * Set to 0 to disable caching (useful for testing or security-critical deployments).
+   *
+   * **Important:** This cache is process-local. In horizontally scaled deployments
+   * (multiple server instances), membership changes on one instance are not reflected
+   * on other instances until the TTL expires. For security-sensitive deployments,
+   * reduce the TTL or set to 0 to disable.
+   *
+   * Note: `CoreBetterAuthUserMapper` has an independent 15-second user cache for
+   * roles and verified status. Both caches affect revocation latency. To control both,
+   * set this to 0 and override `USER_CACHE_TTL_MS` in a custom mapper.
+   *
+   * @default 30000 (30 seconds)
+   * @since 11.21.1
    */
-  excludeSchemas?: string[];
+  cacheTtlMs?: number;
 }
 
 /**
@@ -1365,19 +1421,19 @@ export interface IServerOptions {
   /**
    * Multi-tenancy configuration for tenant-based data isolation.
    *
-   * When enabled, a global Mongoose plugin automatically filters all queries
-   * by `tenantId`, ensuring tenant isolation in a shared database.
+   * When enabled, provides header-based tenant selection with membership validation.
+   * The active tenant is determined by the X-Tenant-Id header on each request.
+   * A global Mongoose plugin automatically filters all queries by `tenantId`.
    *
    * Follows the "presence implies enabled" pattern:
    * - `undefined`: Disabled (no overhead, backward compatible)
-   * - `{}`: Enabled with defaults
-   * - `{ userField: 'organizationId' }`: Enabled with custom user field
+   * - `{}`: Enabled with defaults (X-Tenant-Id header, admin bypass)
    * - `{ enabled: false }`: Pre-configured but disabled
    *
    * The plugin activates automatically on any schema that has a `tenantId` field.
    * Schemas without `tenantId` are not affected.
    *
-   * @since 11.20.0
+   * @since 11.21.0
    * @default undefined (disabled)
    *
    * @example
@@ -1385,14 +1441,10 @@ export interface IServerOptions {
    * // Enable with defaults
    * multiTenancy: {},
    *
-   * // Enable with excluded schemas
+   * // Enable with excluded schemas and custom header
    * multiTenancy: {
    *   excludeSchemas: ['User', 'Session'],
-   * },
-   *
-   * // Custom user field
-   * multiTenancy: {
-   *   userField: 'organizationId',
+   *   headerName: 'x-tenant-id',
    * },
    * ```
    */

package/src/core/common/middleware/request-context.middleware.ts

@@ -1,7 +1,6 @@
 import { Injectable, NestMiddleware } from '@nestjs/common';
 import { NextFunction, Request, Response } from 'express';
 
-import { ConfigService } from '../services/config.service';
 import { IRequestContext, RequestContext } from '../services/request-context.service';
 
 /**
@@ -21,10 +20,18 @@ export class RequestContextMiddleware implements NestMiddleware {
         return req.headers?.['accept-language'] || undefined;
       },
       get tenantId() {
-        const config = ConfigService.configFastButReadOnly?.multiTenancy;
-        if (!config || config.enabled === false) return undefined;
-        const field = config.userField ?? 'tenantId';
-        return (req as any).user?.[field] ?? undefined;
+        // Only return tenant ID set by CoreTenantGuard (after membership validation).
+        // The raw header is NEVER used for plugin filtering.
+        return (req as any).tenantId ?? undefined;
+      },
+      get tenantIds() {
+        return (req as any).tenantIds ?? undefined;
+      },
+      get tenantRole() {
+        return (req as any).tenantRole ?? undefined;
+      },
+      get isAdminBypass() {
+        return (req as any).isAdminBypass ?? false;
       },
     };
     RequestContext.run(context, () => next());