@lenne.tech/nest-server 11.20.0 → 11.21.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nest-server",
-  "version": "11.20.0",
+  "version": "11.21.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",
@@ -75,7 +75,7 @@
   "dependencies": {
     "@apollo/server": "5.4.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",
@@ -92,7 +92,7 @@
     "@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",
@@ -133,20 +133,20 @@
     "@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.0",
+    "@vitest/ui": "4.1.0",
     "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.40.0",
+    "oxlint": "1.55.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.0"
   },
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -182,7 +182,9 @@
       "rollup@>=4.0.0 <4.59.0": "4.59.0",
       "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"
     },
     "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/db.helper.ts

@@ -550,6 +550,7 @@ export function removeUnresolvedReferences<T = any>(
   populated: T,
   populatedOptions: (PopulateOptions | string)[] | PopulateOptions | PopulateOptions[] | string,
   ignoreFirst = true,
+  visited: WeakSet<object> = new WeakSet(),
 ): T {
   // Check parameter
   if (!populated || !populatedOptions) {
@@ -558,21 +559,24 @@ export function removeUnresolvedReferences<T = any>(
 
   // Process array
   if (Array.isArray(populated)) {
-    populated.forEach((p) => removeUnresolvedReferences(p, populatedOptions, false));
+    if (visited.has(populated)) return populated;
+    visited.add(populated);
+    populated.forEach((p) => removeUnresolvedReferences(p, populatedOptions, false, visited));
     return populated;
   }
 
   // Process object
   if (typeof populated === 'object') {
-    // populatedOptions is an array
+    // populatedOptions is an array — iterate options for the same object
+    // Each option targets a different property path, so do not mark populated as visited here
     if (Array.isArray(populatedOptions)) {
       populatedOptions.forEach((po) =>
-        removeUnresolvedReferences(populated, ignoreFirst && typeof po === 'object' ? po.populate : po, false),
+        removeUnresolvedReferences(populated, ignoreFirst && typeof po === 'object' ? po.populate : po, false, visited),
       );
       return populated;
     }
 
-    // populatedOptions is a string
+    // populatedOptions is a string — leaf operation, no deep recursion risk
     if (typeof populatedOptions === 'string') {
       if (!['_id', 'id'].includes(populatedOptions) && populated[populatedOptions] instanceof Types.ObjectId) {
         populated[populatedOptions] = null;
@@ -580,13 +584,16 @@ export function removeUnresolvedReferences<T = any>(
       return populated;
     }
 
-    // populatedOptions is an PopulateOptions object
+    // populatedOptions is a PopulateOptions object
     if (populatedOptions.path) {
       const key = populatedOptions.path;
       if (!['_id', 'id'].includes(key) && populated[key] instanceof Types.ObjectId) {
         populated[key] = null;
       } else if (populatedOptions.populate) {
-        removeUnresolvedReferences(populated[key], populatedOptions.populate, false);
+        // Prevent circular reference loops when descending into nested populates
+        if (visited.has(populated as object)) return populated;
+        visited.add(populated as object);
+        removeUnresolvedReferences(populated[key], populatedOptions.populate, false, visited);
       }
     }
   }

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

@@ -413,12 +413,16 @@ export function combinePlain(...args: Record<any, any>[]): any {
 /**
  * Get deep frozen object
  */
-export function deepFreeze(object: any) {
+export function deepFreeze(object: any, visited: WeakSet<object> = new WeakSet()) {
   if (!object || typeof object !== 'object') {
     return object;
   }
+  if (visited.has(object)) {
+    return object;
+  }
+  visited.add(object);
   for (const [key, value] of Object.entries(object)) {
-    object[key] = deepFreeze(value);
+    object[key] = deepFreeze(value, visited);
   }
   return Object.freeze(object);
 }

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

@@ -109,24 +109,39 @@ 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) => {
       if (!this.config.removeSecretFields || !data || typeof data !== 'object') {
         return data;
       }
       if (Array.isArray(data)) {
+        if (visited.has(data)) return data;
+        visited.add(data);
         data.forEach(removeSecrets);
         return data;
       }
       if (!isPlainLike(data)) {
         return data;
       }
+      // Prevent infinite recursion on circular references
+      if (visited.has(data)) {
+        return data;
+      }
+      visited.add(data);
       for (const field of this.config.secretFields) {
         if (field in data && data[field] !== undefined) {
           data[field] = undefined;

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
  */
@@ -837,27 +834,67 @@ export interface IMultiTenancy {
    */
   enabled?: boolean;
 
-  /**
-   * Field name on `req.user` that contains the tenant identifier.
-   *
-   * **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.
-   *
-   * **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`.
-   *
-   * @default 'tenantId'
-   */
-  userField?: string;
-
   /**
    * 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.
+   *
+   * @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 }
+   * }
+   *
+   * // roles.ts
+   * import { createHierarchyRoles } from '@lenne.tech/nest-server';
+   * export const HR = createHierarchyRoles({ viewer: 1, editor: 2, manager: 2, admin: 3, owner: 4 });
+   *
+   * // resolver.ts
+   * @Roles(HR.EDITOR) // requires level >= 2 (editor, manager, admin, owner)
+   * ```
+   */
+  roleHierarchy?: Record<string, number>;
 }
 
 /**
@@ -1365,19 +1402,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 +1422,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());

package/src/core/common/plugins/mongoose-tenant.plugin.ts

@@ -1,3 +1,5 @@
+import { ForbiddenException } from '@nestjs/common';
+
 import { ConfigService } from '../services/config.service';
 import { RequestContext } from '../services/request-context.service';
 
@@ -15,18 +17,21 @@ import { RequestContext } from '../services/request-context.service';
  * - New documents get tenantId set automatically from context
  * - Aggregates get a $match stage prepended
  *
+ * **Filter modes:**
+ * - X-Tenant-Id header set → `{ tenantId: headerValue }` (single tenant)
+ * - No header + authenticated user → `{ tenantId: { $in: userTenantIds } }` (all user's tenants)
+ * - No header + no user → no filter (public/system routes)
+ *
  * **No filter applied when:**
  * - No RequestContext (system operations, cron jobs, migrations)
  * - `bypassTenantGuard` is active (via `RequestContext.runWithBypassTenantGuard()`)
  * - Schema's model name is in `excludeSchemas` config
- * - No user on request (public endpoints)
- *
- * **User without tenantId:**
- * - Filters by `{ tenantId: null }` — sees only data without tenant assignment
- * - Falsy values (undefined, null, empty string '') are all treated as "no tenant"
  */
 export function mongooseTenantPlugin(schema) {
-  // Only activate on schemas with a tenantId path
+  // Only activate on schemas with a tenantId path.
+  // CoreTenantMemberModel uses 'tenant' (not 'tenantId') intentionally, so this check
+  // excludes it at registration time. Additionally, 'TenantMember' is auto-added to
+  // excludeSchemas in CoreModule as defense-in-depth (see shouldBypass()).
   if (!schema.path('tenantId')) {
     return;
   }
@@ -54,22 +59,21 @@ export function mongooseTenantPlugin(schema) {
     schema.pre(hookName, function () {
       // Query hooks: `this` is a Mongoose Query — modelName is on `this.model`
       const modelName = this.model?.modelName;
-      const tenantId = resolveTenantId(modelName);
-      if (tenantId !== undefined) {
-        this.where({ tenantId });
+      const filter = resolveTenantFilter(modelName);
+      if (filter !== undefined) {
+        this.where(filter);
       }
     });
   }
 
   // === Save: set tenantId automatically on new documents ===
   // Intentional asymmetry: writes only set tenantId when truthy (not null).
-  // A user without tenantId creates "unassigned" documents, which the null-filter
-  // in query hooks will still make visible to them on reads.
+  // Only uses single tenantId from header — tenantIds array is for reads only.
   schema.pre('save', function () {
     if (this.isNew && !this['tenantId']) {
       // Document hooks: `this` is the document instance — modelName is on the constructor (the Model class)
       const modelName = (this.constructor as any).modelName;
-      const tenantId = resolveTenantId(modelName);
+      const tenantId = resolveSingleTenantId(modelName);
       if (tenantId) {
         this['tenantId'] = tenantId;
       }
@@ -80,7 +84,7 @@ export function mongooseTenantPlugin(schema) {
   schema.pre('insertMany', function (docs: any[]) {
     // Model-level hooks: `this` is the Model class itself — modelName is a direct property
     const modelName = this.modelName;
-    const tenantId = resolveTenantId(modelName);
+    const tenantId = resolveSingleTenantId(modelName);
     if (tenantId && Array.isArray(docs)) {
       for (const doc of docs) {
         if (!doc.tenantId) {
@@ -94,25 +98,27 @@ export function mongooseTenantPlugin(schema) {
   schema.pre('bulkWrite', function (ops: any[]) {
     // Model-level hooks: `this` is the Model class itself — modelName is a direct property
     const modelName = this.modelName;
-    const tenantId = resolveTenantId(modelName);
-    if (tenantId === undefined) return;
+    const filter = resolveTenantFilter(modelName);
+    if (filter === undefined) return;
+
+    const tenantId = resolveSingleTenantId(modelName);
 
     for (const op of ops) {
       if ('insertOne' in op) {
-        // Auto-set tenantId on insert (only if truthy, consistent with save hook)
+        // Auto-set tenantId on insert (only single tenantId, consistent with save hook)
         if (tenantId && !op.insertOne.document.tenantId) {
           op.insertOne.document.tenantId = tenantId;
         }
       } else if ('updateOne' in op) {
-        op.updateOne.filter = { ...op.updateOne.filter, tenantId };
+        op.updateOne.filter = { ...op.updateOne.filter, ...filter };
       } else if ('updateMany' in op) {
-        op.updateMany.filter = { ...op.updateMany.filter, tenantId };
+        op.updateMany.filter = { ...op.updateMany.filter, ...filter };
       } else if ('replaceOne' in op) {
-        op.replaceOne.filter = { ...op.replaceOne.filter, tenantId };
+        op.replaceOne.filter = { ...op.replaceOne.filter, ...filter };
       } else if ('deleteOne' in op) {
-        op.deleteOne.filter = { ...op.deleteOne.filter, tenantId };
+        op.deleteOne.filter = { ...op.deleteOne.filter, ...filter };
       } else if ('deleteMany' in op) {
-        op.deleteMany.filter = { ...op.deleteMany.filter, tenantId };
+        op.deleteMany.filter = { ...op.deleteMany.filter, ...filter };
       }
     }
   });
@@ -121,45 +127,72 @@ export function mongooseTenantPlugin(schema) {
   schema.pre('aggregate', function () {
     // Aggregate hooks: `this` is the Aggregation pipeline — the model is on the internal `_model` property
     const modelName = (this as any)._model?.modelName;
-    const tenantId = resolveTenantId(modelName);
-    if (tenantId !== undefined) {
-      this.pipeline().unshift({ $match: { tenantId } });
+    const filter = resolveTenantFilter(modelName);
+    if (filter !== undefined) {
+      this.pipeline().unshift({ $match: filter });
     }
   });
 }
 
 /**
- * Resolve tenant ID from RequestContext.
+ * Check common bypass conditions.
  *
- * @returns
- * - `undefined` → no filter should be applied
- * - `string` → filter by this tenant ID
- * - `null` → filter by `{ tenantId: null }` (user without tenant sees only unassigned data)
+ * @returns `true` if filtering should be skipped, `false` otherwise
  */
-function resolveTenantId(modelName?: string): string | null | undefined {
-  // Defense-in-depth: check config even if plugin is registered
+function shouldBypass(modelName?: string): boolean {
   const mtConfig = ConfigService.configFastButReadOnly?.multiTenancy;
-  if (!mtConfig || mtConfig.enabled === false) return undefined;
+  if (!mtConfig || mtConfig.enabled === false) return true;
 
   const context = RequestContext.get();
+  if (!context) return true;
+  if (context.bypassTenantGuard) return true;
+  if (modelName && mtConfig.excludeSchemas?.includes(modelName)) return true;
 
-  // No RequestContext (system operation, cron, migration) → no filter
-  if (!context) return undefined;
+  return false;
+}
 
-  // Explicit bypass
-  if (context.bypassTenantGuard) return undefined;
+/**
+ * Resolve tenant filter from RequestContext for read operations (queries, aggregates).
+ *
+ * Defense-in-depth: If a schema has tenantId but there is no valid tenant context,
+ * throws ForbiddenException instead of returning unfiltered data (Safety Net).
+ *
+ * @returns
+ * - `undefined` → no filter should be applied (bypass active or plugin disabled)
+ * - `{}` → empty filter (admin bypass without header — sees all data)
+ * - `{ tenantId: string }` → filter by single validated tenant
+ * - `{ tenantId: { $in: string[] } }` → filter by user's tenant memberships
+ * @throws ForbiddenException when tenantId-schema is accessed without valid tenant context
+ */
+function resolveTenantFilter(modelName?: string): Record<string, any> | undefined {
+  if (shouldBypass(modelName)) return undefined;
+
+  const context = RequestContext.get();
 
-  // Check excluded schemas (model names, e.g. ['User', 'Session'])
-  if (modelName && mtConfig.excludeSchemas?.includes(modelName)) return undefined;
+  // Validated tenant ID (set by CoreTenantGuard) → filter by it
+  const tenantId = context?.tenantId;
+  if (tenantId) return { tenantId };
 
-  const tenantId = context.tenantId;
+  // User has resolved memberships → filter by their tenants
+  const tenantIds = context?.tenantIds;
+  if (tenantIds) return { tenantId: { $in: tenantIds } };
 
-  // User has tenantId → filter by it (empty string is treated as falsy = no tenant)
-  if (tenantId) return tenantId;
+  // Admin bypass without header → no filter, sees all data
+  if (context?.isAdminBypass) return {};
 
-  // User is logged in but has no tenantId (undefined, null, or '') → null filter (sees only data without tenant)
-  if (context.currentUser) return null;
+  // SAFETY NET: Schema has tenantId but no valid tenant context.
+  // Throw instead of returning unfiltered data to prevent data leaks.
+  throw new ForbiddenException(
+    'Tenant context required: this data is tenant-scoped but no valid tenant context was provided',
+  );
+}
+
+/**
+ * Resolve single tenant ID for write operations (save, insertMany).
+ * Only returns a value when a specific tenant header is set.
+ */
+function resolveSingleTenantId(modelName?: string): string | undefined {
+  if (shouldBypass(modelName)) return undefined;
 
-  // No user (public endpoint) → no filter
-  return undefined;
+  return RequestContext.get()?.tenantId || undefined;
 }

package/src/core/common/services/request-context.service.ts

@@ -11,8 +11,14 @@ export interface IRequestContext {
   bypassRoleGuard?: boolean;
   /** When true, mongooseTenantPlugin skips tenant filtering */
   bypassTenantGuard?: boolean;
-  /** Tenant ID resolved from the current user */
+  /** Validated tenant ID (set by CoreTenantGuard after membership validation, not raw header) */
   tenantId?: string;
+  /** Tenant IDs from user's active tenant memberships (used when no specific header is set) */
+  tenantIds?: string[];
+  /** Tenant role of the current user in the active tenant */
+  tenantRole?: string;
+  /** When true, indicates admin bypass is active (admin without header sees all data) */
+  isAdminBypass?: boolean;
 }
 
 /**