@lenne.tech/nest-server 11.18.0 → 11.20.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nest-server",
-  "version": "11.18.0",
+  "version": "11.20.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",
@@ -91,11 +91,10 @@
     "@nestjs/websockets": "11.1.16",
     "@tus/file-store": "2.0.0",
     "@tus/server": "2.3.0",
-
     "bcrypt": "6.0.0",
     "better-auth": "1.5.4",
     "class-transformer": "0.5.1",
-    "class-validator": "0.14.3",
+    "class-validator": "0.15.1",
     "compression": "1.8.1",
     "cookie-parser": "1.4.7",
     "dotenv": "17.3.1",
@@ -108,16 +107,17 @@
     "js-sha256": "0.11.1",
     "json-to-graphql-query": "2.3.0",
     "lodash": "4.17.23",
-    "mongodb": "7.0.0",
-    "mongoose": "9.2.4",
+    "mongodb": "7.1.0",
+    "mongoose": "9.3.0",
     "multer": "2.1.1",
     "node-mailjet": "6.0.11",
-    "nodemailer": "8.0.1",
+    "nodemailer": "8.0.2",
     "passport": "0.7.0",
     "passport-jwt": "4.0.1",
     "reflect-metadata": "0.2.2",
     "rfdc": "1.4.1",
     "rxjs": "7.8.2",
+    "ts-morph": "27.0.2",
     "yuml-diagram": "1.2.0"
   },
   "devDependencies": {
@@ -133,7 +133,7 @@
     "@types/express": "5.0.6",
     "@types/lodash": "4.17.24",
     "@types/multer": "2.1.0",
-    "@types/node": "25.3.5",
+    "@types/node": "25.4.0",
     "@types/nodemailer": "7.0.11",
     "@types/passport": "1.0.17",
     "@types/supertest": "7.2.0",
@@ -145,11 +145,10 @@
     "nodemon": "3.1.14",
     "npm-watch": "0.13.0",
     "otpauth": "9.5.0",
-    "oxfmt": "0.36.0",
-    "oxlint": "1.51.0",
+    "oxfmt": "0.38.0",
+    "oxlint": "1.53.0",
     "rimraf": "6.1.3",
     "supertest": "7.2.2",
-    "ts-morph": "27.0.2",
     "ts-node": "10.9.2",
     "tsconfig-paths": "4.2.0",
     "tus-js-client": "4.3.1",
@@ -181,9 +180,9 @@
       "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",
-      "serialize-javascript@<=7.0.2": "7.0.4",
       "ajv@<6.14.0": "6.14.0",
-      "ajv@>=7.0.0-alpha.0 <8.18.0": "8.18.0"
+      "ajv@>=7.0.0-alpha.0 <8.18.0": "8.18.0",
+      "file-type@>=13.0.0 <21.3.1": "21.3.1"
     },
     "onlyBuiltDependencies": [
       "bcrypt",

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

@@ -53,7 +53,7 @@ export interface IAuth {
    *
    * Legacy endpoints include:
    * - GraphQL: signIn, signUp, signOut, refreshToken mutations
-   * - REST: /api/auth/* endpoints
+   * - REST: /auth/* endpoints
    *
    * These can be disabled once all users have migrated to BetterAuth (IAM).
    *
@@ -156,7 +156,7 @@ export interface IAuthLegacyEndpoints {
 
   /**
    * Whether legacy REST auth endpoints are enabled.
-   * Affects: /api/auth/sign-in, /api/auth/sign-up, etc.
+   * Affects: /auth/sign-in, /auth/sign-up, etc.
    *
    * @default true (inherits from `enabled`)
    */
@@ -816,6 +816,50 @@ export interface IJwt {
   signInOptions?: JwtSignOptions;
 }
 
+/**
+ * Multi-tenancy configuration
+ *
+ * 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
+ */
+export interface IMultiTenancy {
+  /**
+   * Explicitly disable multi-tenancy even when config is present.
+   * When undefined/true and the config object exists, the feature is enabled.
+   * @default true (when config object is present)
+   */
+  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.
+   * @example ['User', 'Session']
+   */
+  excludeSchemas?: string[];
+}
+
 /**
  * Options for the server
  */
@@ -1318,6 +1362,42 @@ export interface IServerOptions {
     uri: string;
   };
 
+  /**
+   * 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.
+   *
+   * Follows the "presence implies enabled" pattern:
+   * - `undefined`: Disabled (no overhead, backward compatible)
+   * - `{}`: Enabled with defaults
+   * - `{ userField: 'organizationId' }`: Enabled with custom user field
+   * - `{ 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
+   * @default undefined (disabled)
+   *
+   * @example
+   * ```typescript
+   * // Enable with defaults
+   * multiTenancy: {},
+   *
+   * // Enable with excluded schemas
+   * multiTenancy: {
+   *   excludeSchemas: ['User', 'Session'],
+   * },
+   *
+   * // Custom user field
+   * multiTenancy: {
+   *   userField: 'organizationId',
+   * },
+   * ```
+   */
+  multiTenancy?: IMultiTenancy;
+
   /**
    * Permissions report module (development tool).
    *

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

@@ -1,11 +1,12 @@
 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';
 
 /**
  * Middleware that wraps each request in a RequestContext (AsyncLocalStorage).
- * Uses a lazy getter for currentUser so that the user is resolved at access time,
+ * Uses lazy getters for currentUser and tenantId so that they are resolved at access time,
  * not at middleware execution time. This ensures that auth middleware that runs
  * after this middleware still sets req.user before it's read.
  */
@@ -19,6 +20,12 @@ export class RequestContextMiddleware implements NestMiddleware {
       get language() {
         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;
+      },
     };
     RequestContext.run(context, () => next());
   }

package/src/core/common/plugins/mongoose-audit-fields.plugin.ts

@@ -4,11 +4,16 @@ import { RequestContext } from '../services/request-context.service';
  * Mongoose plugin that automatically sets createdBy/updatedBy fields.
  * Uses RequestContext (AsyncLocalStorage) to access the current user.
  *
+ * Handles save(), findOneAndUpdate(), updateOne(), updateMany(), replaceOne(),
+ * findOneAndReplace(), insertMany(), and bulkWrite() operations.
+ *
  * Behavior:
  * - No user context (system operations, seeding): fields are not set
  * - New documents: sets createdBy (if not already set) and updatedBy
  * - Existing documents on save: sets updatedBy
  * - Update operations: sets updatedBy
+ * - Replace operations: sets updatedBy (and createdBy for upserts)
+ * - Bulk operations: sets createdBy/updatedBy per document/operation
  *
  * Only activates on schemas that have createdBy and/or updatedBy fields defined.
  */
@@ -70,5 +75,84 @@ export function mongooseAuditFieldsPlugin(schema) {
     schema.pre('findOneAndUpdate', updateHook);
     schema.pre('updateOne', updateHook);
     schema.pre('updateMany', updateHook);
+
+    // Replace hooks: flat replacement doc (no $set/$setOnInsert)
+    const replaceHook = function () {
+      const currentUser = RequestContext.getCurrentUser();
+      if (!currentUser?.id) {
+        return;
+      }
+
+      const replacement = this.getUpdate();
+      if (!replacement) {
+        return;
+      }
+
+      replacement['updatedBy'] = currentUser.id;
+
+      // For upsert replacements: set createdBy if not already present
+      if (hasCreatedBy && !replacement['createdBy']) {
+        replacement['createdBy'] = currentUser.id;
+      }
+    };
+
+    schema.pre('replaceOne', replaceHook);
+    schema.pre('findOneAndReplace', replaceHook);
   }
+
+  // Bulk operation hooks (needed when either createdBy or updatedBy is present)
+  // Pre-insertMany hook (Mongoose 9: first arg is docs array)
+  schema.pre('insertMany', function (docs) {
+    const currentUser = RequestContext.getCurrentUser();
+    if (!currentUser?.id) return;
+    if (!Array.isArray(docs)) return;
+
+    for (const doc of docs) {
+      if (hasCreatedBy && !doc.createdBy) {
+        doc.createdBy = currentUser.id;
+      }
+      if (hasUpdatedBy) {
+        doc.updatedBy = currentUser.id;
+      }
+    }
+  });
+
+  // Pre-bulkWrite hook
+  schema.pre('bulkWrite', function (ops) {
+    const currentUser = RequestContext.getCurrentUser();
+    if (!currentUser?.id) return;
+
+    for (const op of ops) {
+      if ('insertOne' in op) {
+        if (hasCreatedBy && !op.insertOne.document.createdBy) {
+          op.insertOne.document.createdBy = currentUser.id;
+        }
+        if (hasUpdatedBy) {
+          op.insertOne.document.updatedBy = currentUser.id;
+        }
+      } else if ('updateOne' in op || 'updateMany' in op) {
+        const update = 'updateOne' in op ? op.updateOne.update : op.updateMany.update;
+        if (!update) continue;
+        if (hasUpdatedBy) {
+          update['updatedBy'] = currentUser.id;
+          if (update.$set) {
+            update.$set['updatedBy'] = currentUser.id;
+          }
+        }
+        if (hasCreatedBy && !update['createdBy'] && !update.$set?.['createdBy']) {
+          if (!update.$setOnInsert) update.$setOnInsert = {};
+          if (!update.$setOnInsert['createdBy']) {
+            update.$setOnInsert['createdBy'] = currentUser.id;
+          }
+        }
+      } else if ('replaceOne' in op) {
+        if (hasUpdatedBy) {
+          op.replaceOne.replacement['updatedBy'] = currentUser.id;
+        }
+        if (hasCreatedBy && !op.replaceOne.replacement['createdBy']) {
+          op.replaceOne.replacement['createdBy'] = currentUser.id;
+        }
+      }
+    }
+  });
 }

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

@@ -5,7 +5,8 @@ import { ConfigService } from '../services/config.service';
 
 /**
  * Mongoose plugin that automatically hashes passwords before saving to the database.
- * Handles save(), findOneAndUpdate(), updateOne(), and updateMany() operations.
+ * Handles save(), findOneAndUpdate(), updateOne(), updateMany(), replaceOne(),
+ * findOneAndReplace(), insertMany(), and bulkWrite() operations.
  *
  * Prevents plaintext passwords from being stored even when developers bypass
  * CrudService.process() and use direct Mongoose operations.
@@ -38,6 +39,45 @@ export function mongoosePasswordPlugin(schema) {
   schema.pre('updateMany', async function () {
     await hashUpdatePassword(this.getUpdate());
   });
+
+  // Pre-replaceOne hook (replacement doc is a flat object, hashUpdatePassword handles it)
+  schema.pre('replaceOne', async function () {
+    await hashUpdatePassword(this.getUpdate());
+  });
+
+  // Pre-findOneAndReplace hook
+  schema.pre('findOneAndReplace', async function () {
+    await hashUpdatePassword(this.getUpdate());
+  });
+
+  // Pre-insertMany hook (Mongoose 9: first arg is docs array)
+  schema.pre('insertMany', async function (docs) {
+    if (!Array.isArray(docs)) return;
+    for (const doc of docs) {
+      if (doc.password) {
+        doc.password = await hashPassword(doc.password);
+      }
+    }
+  });
+
+  // Pre-bulkWrite hook
+  schema.pre('bulkWrite', async function (ops) {
+    for (const op of ops) {
+      if ('insertOne' in op) {
+        if (op.insertOne.document?.password) {
+          op.insertOne.document.password = await hashPassword(op.insertOne.document.password);
+        }
+      } else if ('updateOne' in op) {
+        await hashUpdatePassword(op.updateOne.update);
+      } else if ('updateMany' in op) {
+        await hashUpdatePassword(op.updateMany.update);
+      } else if ('replaceOne' in op) {
+        if (op.replaceOne.replacement?.password) {
+          op.replaceOne.replacement.password = await hashPassword(op.replaceOne.replacement.password);
+        }
+      }
+    }
+  });
 }
 
 export async function hashUpdatePassword(update: any) {

package/src/core/common/plugins/mongoose-role-guard.plugin.ts

@@ -10,6 +10,9 @@ const logger = new Logger('mongooseRoleGuardPlugin');
  * Mongoose plugin that prevents unauthorized users from escalating roles.
  * Uses RequestContext (AsyncLocalStorage) to access the current user.
  *
+ * Handles save(), findOneAndUpdate(), updateOne(), updateMany(), replaceOne(),
+ * findOneAndReplace(), insertMany(), and bulkWrite() operations.
+ *
  * **When are role changes allowed?**
  * 1. No user context (system operations, seeding, CLI scripts) → allowed
  * 2. No currentUser on request (e.g. signUp — user not logged in) → allowed
@@ -22,7 +25,8 @@ const logger = new Logger('mongooseRoleGuardPlugin');
  * - Logged-in non-admin user without bypass → blocked
  * - On save (new): roles set to `[]`
  * - On save (existing): roles reverted to original
- * - On update: roles stripped from update object
+ * - On update/replace: roles stripped from update/replacement object
+ * - On insertMany/bulkWrite: roles set to `[]` on inserted documents
  *
  * **Configuration** via `security.mongooseRoleGuardPlugin`:
  * - `true` — Only ADMIN can assign roles (default)
@@ -83,6 +87,62 @@ export function mongooseRoleGuardPlugin(schema) {
   schema.pre('updateMany', function () {
     handleUpdateRoleGuard(this.getUpdate());
   });
+
+  // Pre-replaceOne hook (replacement doc is flat, handleUpdateRoleGuard handles update.roles)
+  schema.pre('replaceOne', function () {
+    handleUpdateRoleGuard(this.getUpdate());
+  });
+
+  // Pre-findOneAndReplace hook
+  schema.pre('findOneAndReplace', function () {
+    handleUpdateRoleGuard(this.getUpdate());
+  });
+
+  // Pre-insertMany hook (Mongoose 9: first arg is docs array)
+  schema.pre('insertMany', function (docs) {
+    if (!Array.isArray(docs)) return;
+    if (!docs.some((doc) => doc.roles?.length > 0)) return;
+    if (isRoleChangeAllowed()) return;
+
+    const currentUser = RequestContext.getCurrentUser();
+    logger.debug(`Stripped unauthorized roles from insertMany by user ${currentUser?.id || 'unknown'}`);
+    for (const doc of docs) {
+      if (doc.roles) {
+        doc.roles = [];
+      }
+    }
+  });
+
+  // Pre-bulkWrite hook
+  schema.pre('bulkWrite', function (ops) {
+    const hasAnyRoleChange = ops.some((op) => {
+      if ('insertOne' in op) return !!op.insertOne.document?.roles?.length;
+      if ('updateOne' in op) return hasRolesInUpdate(op.updateOne.update);
+      if ('updateMany' in op) return hasRolesInUpdate(op.updateMany.update);
+      if ('replaceOne' in op) return !!op.replaceOne.replacement?.roles?.length;
+      return false;
+    });
+    if (!hasAnyRoleChange) return;
+    if (isRoleChangeAllowed()) return;
+
+    const currentUser = RequestContext.getCurrentUser();
+    logger.debug(`Stripped unauthorized roles from bulkWrite by user ${currentUser?.id || 'unknown'}`);
+    for (const op of ops) {
+      if ('insertOne' in op) {
+        if (op.insertOne.document?.roles) {
+          op.insertOne.document.roles = [];
+        }
+      } else if ('updateOne' in op) {
+        handleUpdateRoleGuard(op.updateOne.update);
+      } else if ('updateMany' in op) {
+        handleUpdateRoleGuard(op.updateMany.update);
+      } else if ('replaceOne' in op) {
+        if (op.replaceOne.replacement?.roles) {
+          delete op.replaceOne.replacement.roles;
+        }
+      }
+    }
+  });
 }
 
 /**
@@ -120,6 +180,10 @@ function isRoleChangeAllowed(): boolean {
   return false;
 }
 
+function hasRolesInUpdate(update: any): boolean {
+  return !!(update?.roles || update?.$set?.roles || update?.$push?.roles || update?.$addToSet?.roles);
+}
+
 function handleUpdateRoleGuard(update: any) {
   if (!update) {
     return;

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

@@ -0,0 +1,165 @@
+import { ConfigService } from '../services/config.service';
+import { RequestContext } from '../services/request-context.service';
+
+/**
+ * Mongoose plugin that provides automatic tenant-based data isolation.
+ * Only activates on schemas that have a `tenantId` path defined.
+ *
+ * Follows the same pattern as mongooseRoleGuardPlugin and mongooseAuditFieldsPlugin:
+ * - Plain function, registered globally in connectionFactory
+ * - Reads RequestContext (AsyncLocalStorage) and ConfigService.configFastButReadOnly
+ * - Activates conditionally based on schema structure
+ *
+ * **Behavior:**
+ * - Queries are automatically filtered by the current user's tenantId
+ * - New documents get tenantId set automatically from context
+ * - Aggregates get a $match stage prepended
+ *
+ * **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
+  if (!schema.path('tenantId')) {
+    return;
+  }
+
+  // Performance index
+  schema.index({ tenantId: 1 });
+
+  // === Query filter hooks (explicit names, no regex → no double-filtering) ===
+  const queryHooks = [
+    'find',
+    'findOne',
+    'findOneAndUpdate',
+    'findOneAndDelete',
+    'findOneAndReplace',
+    'countDocuments',
+    'distinct',
+    'updateOne',
+    'updateMany',
+    'deleteOne',
+    'deleteMany',
+    'replaceOne',
+  ];
+
+  for (const hookName of queryHooks) {
+    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 });
+      }
+    });
+  }
+
+  // === 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.
+  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);
+      if (tenantId) {
+        this['tenantId'] = tenantId;
+      }
+    }
+  });
+
+  // === insertMany (Mongoose 9: first arg is docs array, no next callback) ===
+  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);
+    if (tenantId && Array.isArray(docs)) {
+      for (const doc of docs) {
+        if (!doc.tenantId) {
+          doc.tenantId = tenantId;
+        }
+      }
+    }
+  });
+
+  // === bulkWrite: filter queries and auto-set tenantId on inserts ===
+  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;
+
+    for (const op of ops) {
+      if ('insertOne' in op) {
+        // Auto-set tenantId on insert (only if truthy, 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 };
+      } else if ('updateMany' in op) {
+        op.updateMany.filter = { ...op.updateMany.filter, tenantId };
+      } else if ('replaceOne' in op) {
+        op.replaceOne.filter = { ...op.replaceOne.filter, tenantId };
+      } else if ('deleteOne' in op) {
+        op.deleteOne.filter = { ...op.deleteOne.filter, tenantId };
+      } else if ('deleteMany' in op) {
+        op.deleteMany.filter = { ...op.deleteMany.filter, tenantId };
+      }
+    }
+  });
+
+  // === Aggregate: prepend $match stage ===
+  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 } });
+    }
+  });
+}
+
+/**
+ * Resolve tenant ID from RequestContext.
+ *
+ * @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)
+ */
+function resolveTenantId(modelName?: string): string | null | undefined {
+  // Defense-in-depth: check config even if plugin is registered
+  const mtConfig = ConfigService.configFastButReadOnly?.multiTenancy;
+  if (!mtConfig || mtConfig.enabled === false) return undefined;
+
+  const context = RequestContext.get();
+
+  // No RequestContext (system operation, cron, migration) → no filter
+  if (!context) return undefined;
+
+  // Explicit bypass
+  if (context.bypassTenantGuard) return undefined;
+
+  // Check excluded schemas (model names, e.g. ['User', 'Session'])
+  if (modelName && mtConfig.excludeSchemas?.includes(modelName)) return undefined;
+
+  const tenantId = context.tenantId;
+
+  // User has tenantId → filter by it (empty string is treated as falsy = no tenant)
+  if (tenantId) return tenantId;
+
+  // User is logged in but has no tenantId (undefined, null, or '') → null filter (sees only data without tenant)
+  if (context.currentUser) return null;
+
+  // No user (public endpoint) → no filter
+  return undefined;
+}

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

@@ -9,6 +9,10 @@ export interface IRequestContext {
   language?: string;
   /** When true, mongooseRoleGuardPlugin allows role changes regardless of user permissions */
   bypassRoleGuard?: boolean;
+  /** When true, mongooseTenantPlugin skips tenant filtering */
+  bypassTenantGuard?: boolean;
+  /** Tenant ID resolved from the current user */
+  tenantId?: string;
 }
 
 /**
@@ -66,4 +70,37 @@ export class RequestContext {
     };
     return this.storage.run(context, fn);
   }
+
+  static getTenantId(): string | undefined {
+    return this.storage.getStore()?.tenantId;
+  }
+
+  static isBypassTenantGuard(): boolean {
+    return this.storage.getStore()?.bypassTenantGuard === true;
+  }
+
+  /**
+   * Run a function with tenant guard bypass enabled.
+   * The current context is preserved; only bypassTenantGuard is added.
+   *
+   * Use this for cross-tenant operations, e.g.:
+   * - Admin dashboards viewing all tenants
+   * - Cron jobs processing data across tenants
+   * - Migration scripts
+   *
+   * @example
+   * ```typescript
+   * const allOrders = await RequestContext.runWithBypassTenantGuard(async () => {
+   *   return this.orderService.find();
+   * });
+   * ```
+   */
+  static runWithBypassTenantGuard<T>(fn: () => T): T {
+    const currentStore = this.storage.getStore();
+    const context: IRequestContext = {
+      ...currentStore,
+      bypassTenantGuard: true,
+    };
+    return this.storage.run(context, fn);
+  }
 }

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

@@ -344,7 +344,9 @@ export class CoreBetterAuthResolver {
         // 3. session.token (session-based fallback)
         const tokenResponse = response as any;
         const rawToken =
-          tokenResponse.accessToken || tokenResponse.token || (hasSession(response) ? response.session.token : undefined);
+          tokenResponse.accessToken ||
+          tokenResponse.token ||
+          (hasSession(response) ? response.session.token : undefined);
         const token = await this.resolveJwtToken(rawToken);
 
         return {