@lenne.tech/nest-server 12.0.0 → 12.1.0

package/src/core/common/persistence/policies/tenant.policy.ts

@@ -0,0 +1,245 @@
+import { ForbiddenException, Logger } from '@nestjs/common';
+
+import { ConfigService } from '../../services/config.service.js';
+import { RequestContext } from '../../services/request-context.service.js';
+
+/**
+ * Tenant isolation decisions, shared by every data store.
+ *
+ * `mongooseTenantPlugin` applies them to Mongoose queries; a SQL store applies the same functions to its
+ * statements. A security fix therefore lands here once and reaches every database. The returned filters
+ * are neutral `Where` objects (`{ tenantId }`, `{ tenantId: { $in } }`) — the Mongo-operator subset every
+ * store understands.
+ */
+
+/** Models already warned about, so the message appears once per process rather than per query. */
+const isolationDisabledWarned = new Set<string>();
+
+/**
+ * Say out loud that isolation is off for a schema that was built for it.
+ *
+ * `excludeSchemas` is a legitimate feature — a genuinely global lookup table has no tenant. But this
+ * plugin only ever attaches to schemas that DECLARE a `tenantId` field, so reaching here means the
+ * author of that schema intended per-tenant rows and the configuration silently overrides them.
+ * Nothing said so, and the shape is easy to arrive at by accident: the framework's own documentation
+ * carried `excludeSchemas: ['User', 'Session']` in a copyable `@example` from 11.20.0 onwards, which
+ * on a project with per-tenant users switches filtering off for the user collection.
+ *
+ * A warning, not a boot failure. An ambiguous ROLE vocabulary fails the boot because its access
+ * decisions cannot be resolved coherently; this configuration is perfectly coherent — it is simply
+ * one nobody may make without noticing.
+ *
+ * The membership model is skipped: `CoreModule` adds it to `excludeSchemas` itself because
+ * membership is tenant-spanning by design, so warning about it would be the framework complaining
+ * about its own correct default.
+ */
+function warnIsolationDisabled(modelName: string): void {
+  if (isolationDisabledWarned.has(modelName)) {
+    return;
+  }
+  isolationDisabledWarned.add(modelName);
+
+  const membershipModel = ConfigService.configFastButReadOnly?.multiTenancy?.membershipModel ?? 'TenantMember';
+  if (modelName === membershipModel) {
+    return;
+  }
+
+  new Logger('mongooseTenantPlugin').warn(
+    `Tenant isolation is DISABLED for "${modelName}": the schema declares a tenantId field, but ` +
+      `"${modelName}" is listed in multiTenancy.excludeSchemas — so no tenant filter is applied and ` +
+      `every query on it sees every tenant's rows. Remove it from excludeSchemas unless this ` +
+      `collection is genuinely global.`,
+  );
+}
+
+/**
+ * Refuse a tenantId that is not the caller's own.
+ *
+ * Covers both directions of the same boundary:
+ * - creating a row with a FOREIGN tenantId → planting data in someone else's tenant;
+ * - changing an existing row's tenantId → moving data out of this one.
+ *
+ * Throwing rather than overwriting is deliberate. Silently rewriting the value would make a request
+ * that asked for something impossible look like it succeeded, and for tenant-scoped medical data
+ * "the write went somewhere other than you asked" is not a recoverable ambiguity.
+ */
+export function assertOwnTenant(value: unknown, ownTenantId: string, isNew: boolean): void {
+  if (value === undefined || value === null || value === ownTenantId) {
+    return;
+  }
+  throw new ForbiddenException(
+    isNew
+      ? `Cannot create a document in a foreign tenant (got "${String(value)}", own tenant is "${ownTenantId}")`
+      : `Cannot move a document to a foreign tenant (got "${String(value)}", own tenant is "${ownTenantId}")`,
+  );
+}
+
+/**
+ * Whether tenant isolation is off for this operation: multi-tenancy not configured, no request context
+ * (system work: cron, migration, seed), an active `runWithBypassTenantGuard()`, or the model listed in
+ * `excludeSchemas`.
+ *
+ * @returns `true` if filtering should be skipped, `false` otherwise
+ */
+export function isTenantPolicyBypassed(modelName?: string): boolean {
+  const mtConfig = ConfigService.configFastButReadOnly?.multiTenancy;
+  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)) {
+    warnIsolationDisabled(modelName);
+    return true;
+  }
+
+  return false;
+}
+
+/**
+ * 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
+ */
+export function resolveTenantFilter(modelName?: string): Record<string, any> | undefined {
+  if (isTenantPolicyBypassed(modelName)) return undefined;
+
+  const context = RequestContext.get();
+
+  // Validated tenant ID (set by CoreTenantGuard) → filter by it
+  const tenantId = context?.tenantId;
+  if (tenantId) return { tenantId };
+
+  // User has resolved memberships → filter by their tenants
+  const tenantIds = context?.tenantIds;
+  if (tenantIds) return { tenantId: { $in: tenantIds } };
+
+  // Admin bypass without header → no filter, sees all data
+  if (context?.isAdminBypass) return {};
+
+  // 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',
+  );
+}
+
+/**
+ * The tenant scope of the current operation as a database can enforce it (row-level security, plan §3.4): the same
+ * decision as `resolveTenantFilter()`, for the request rather than for one model — a transaction may touch several
+ * tables, and the scope must be right for every one of them.
+ *
+ * - `system`: isolation off (multi-tenancy not configured, no request context, `runWithBypassTenantGuard()`), or a
+ *   platform admin without a tenant header
+ * - `tenant` / `tenants`: the validated tenant, or the caller's memberships
+ * - `none`: a request without a valid tenant context — tenant-scoped data must be refused
+ */
+export type TenantScope =
+  | { kind: 'none' }
+  | { kind: 'system' }
+  | { kind: 'tenant'; tenantId: string }
+  | { kind: 'tenants'; tenantIds: readonly string[] };
+
+export function resolveTenantScope(): TenantScope {
+  if (isTenantPolicyBypassed()) {
+    return { kind: 'system' };
+  }
+  const context = RequestContext.get();
+  if (context?.tenantId) {
+    return { kind: 'tenant', tenantId: context.tenantId };
+  }
+  if (context?.tenantIds) {
+    return { kind: 'tenants', tenantIds: context.tenantIds };
+  }
+  if (context?.isAdminBypass) {
+    return { kind: 'system' };
+  }
+  return { kind: 'none' };
+}
+
+/**
+ * Resolve single tenant ID for write operations (save, insertMany).
+ * Only returns a value when a specific tenant header is set.
+ */
+export function resolveSingleTenantId(modelName?: string): string | undefined {
+  if (isTenantPolicyBypassed(modelName)) return undefined;
+
+  return RequestContext.get()?.tenantId || undefined;
+}
+
+/**
+ * The tenants whose rows the current operation may return, or `undefined` when it may return all of them
+ * (isolation bypassed, or a platform admin without a tenant header) — the same decision the read filter
+ * is built from.
+ */
+export function allowedTenantIds(modelName?: string): readonly string[] | undefined {
+  if (isTenantPolicyBypassed(modelName)) return undefined;
+
+  const context = RequestContext.get();
+  if (context?.tenantId) return [context.tenantId];
+  if (context?.tenantIds) return context.tenantIds;
+  if (context?.isAdminBypass) return undefined;
+  return [];
+}
+
+/**
+ * The after-layer of tenant isolation: refuse a result that contains a row of a tenant the caller may not
+ * read.
+ *
+ * The read filter (`resolveTenantFilter()`) already keeps such rows out, so on a correct path this never
+ * fires — it exists for the paths where the filter is not what decides: a query compiled for another
+ * database, a join, a native path, a filter built with the wrong scope. Rows that do not carry the field
+ * at all (a projection left it out) cannot be verified and pass; the filter applied to them regardless.
+ *
+ * @throws ForbiddenException naming the model, never the foreign tenant's id
+ */
+export function assertRowsInTenantScope(modelName: string | undefined, rows: unknown): void {
+  const allowed = allowedTenantIds(modelName);
+  if (!allowed) {
+    return;
+  }
+  for (const row of Array.isArray(rows) ? rows : [rows]) {
+    if (!row || typeof row !== 'object') {
+      continue;
+    }
+    const tenantId = (row as { tenantId?: unknown }).tenantId;
+    if (tenantId === undefined) {
+      continue;
+    }
+    if (tenantId === null || !allowed.includes(String(tenantId))) {
+      new Logger('TenantIsolation').error(
+        `A read of "${modelName ?? 'unknown model'}" returned a row of a tenant outside the caller's scope — ` +
+          'the read filter did not hold on this path; the result was withheld',
+      );
+      throw new ForbiddenException('Tenant isolation: the result contains data of another tenant');
+    }
+  }
+}
+
+/**
+ * Refuse a count that cannot be tenant-filtered (MongoDB's `estimatedDocumentCount()`, a SQL
+ * planner estimate): it reads collection metadata rather than running a query, so it would hand a
+ * tenant the row count of the WHOLE collection, i.e. every other tenant's volume. Callers that want a
+ * tenant's own count use a filtered count instead.
+ */
+export function assertUnfilterableCountAllowed(modelName?: string): void {
+  if (isTenantPolicyBypassed(modelName)) {
+    return;
+  }
+  const context = RequestContext.get();
+  if (context?.isAdminBypass && !context?.tenantId) {
+    return; // platform admin without a tenant header legitimately sees everything
+  }
+  throw new ForbiddenException(
+    "estimatedDocumentCount() cannot be tenant-filtered and would expose other tenants' row counts — " +
+      'use countDocuments() instead',
+  );
+}

package/src/core/common/persistence/routed-model.guard.ts

@@ -0,0 +1,107 @@
+import type { DataStore } from './data-store.interface.js';
+import { UnsupportedCapabilityError } from './unsupported-capability.error.js';
+
+/**
+ * Static Mongoose model methods that read or write the collection. `where` / `$where` start a query, and `insertOne`
+ * writes through the document's `$save`, not through `save` — each is a way in of its own
+ */
+const MODEL_DATA_METHODS = [
+  '$where',
+  'aggregate',
+  'bulkSave',
+  'bulkWrite',
+  'countDocuments',
+  'create',
+  'deleteMany',
+  'deleteOne',
+  'distinct',
+  'estimatedDocumentCount',
+  'exists',
+  'find',
+  'findAndCount',
+  'findById',
+  'findByIdAndDelete',
+  'findByIdAndUpdate',
+  'findOne',
+  'findOneAndDelete',
+  'findOneAndReplace',
+  'findOneAndUpdate',
+  'insertMany',
+  'insertOne',
+  'replaceOne',
+  'updateMany',
+  'updateOne',
+  'watch',
+  'where',
+] as const;
+
+/** Document methods that write the collection; Mongoose defines `$save` as a separate reference to `save` */
+const DOCUMENT_DATA_METHODS = ['$save', 'deleteOne', 'replaceOne', 'save', 'updateOne'] as const;
+
+/**
+ * Make the Mongoose model of a model routed to a SQL store refuse every data access.
+ *
+ * The Mongoose model stays registered — `@InjectModel()` keeps resolving, the schema and the name stay readable, and
+ * services that run on the routed store through `CrudService` use nothing else of it. But a direct call
+ * (`this.mainDbModel.findByIdAndUpdate(…)`, `doc.save()`) would read and write MongoDB while the rest of the model
+ * lives in the SQL database: its data split across two databases, silently. Refusing with a named error turns that
+ * into the first thing a project notices. Applied to the model INSTANCE of one application (its own connection), so
+ * another application in the same process is unaffected.
+ */
+export function guardRoutedModel(model: unknown, store: DataStore<any>): void {
+  if (!model || typeof model !== 'function') {
+    return;
+  }
+  const target = model as unknown as Record<string, unknown> & { modelName: string; prototype: object };
+  const refuse = (method: string) =>
+    function refused(): never {
+      throw new UnsupportedCapabilityError(
+        `${target.modelName}.${method}() reaches MongoDB, but ${target.modelName} is stored on ${store.driver} — ` +
+          'use the data store (this.dataStore in a CrudService, or @InjectStore()) instead',
+      );
+    };
+  for (const method of MODEL_DATA_METHODS) {
+    if (typeof target[method] === 'function') {
+      Object.defineProperty(target, method, { configurable: true, value: refuse(method), writable: true });
+    }
+  }
+  for (const method of DOCUMENT_DATA_METHODS) {
+    Object.defineProperty(target.prototype, method, { configurable: true, value: refuse(method), writable: true });
+  }
+}
+
+const STAND_IN_MODEL = Symbol('lt:stand-in-model');
+
+/** Whether `@InjectModel()` received a stand-in — no MongoDB connection exists */
+export function isStandInModel(model: unknown): boolean {
+  return !!model && (model as Record<symbol, unknown>)[STAND_IN_MODEL] === true;
+}
+
+/**
+ * What `@InjectModel()` receives for a model where no MongoDB connection exists (a project on PostgreSQL alone): an
+ * object shaped like a Mongoose model — `modelName`, `schema`, a prototype — whose data methods all refuse. A service
+ * that only received `@InjectModel()` follows the store bound to it (`bindStoreToModel()`), exactly as with a real
+ * model routed to SQL; a direct `Model.find()` names the cause instead of failing somewhere inside Mongoose.
+ */
+export function standInModel(modelName: string, schema: unknown): unknown {
+  const standIn = function StandInModel(): never {
+    throw new UnsupportedCapabilityError(`new ${modelName}() is a Mongoose document, and no MongoDB is configured`);
+  } as unknown as Record<string, unknown> & { prototype: object };
+  Object.defineProperty(standIn, 'modelName', { value: modelName });
+  Object.defineProperty(standIn, STAND_IN_MODEL, { value: true });
+  Object.defineProperty(standIn, 'schema', { value: schema });
+  const refuse = (method: string) =>
+    function refused(): never {
+      throw new UnsupportedCapabilityError(
+        `${modelName}.${method}() reaches MongoDB, and no MongoDB is configured — use the data store ` +
+          '(this.dataStore in a CrudService, or @InjectStore())',
+      );
+    };
+  for (const method of MODEL_DATA_METHODS) {
+    Object.defineProperty(standIn, method, { configurable: true, value: refuse(method), writable: true });
+  }
+  for (const method of DOCUMENT_DATA_METHODS) {
+    Object.defineProperty(standIn.prototype, method, { configurable: true, value: refuse(method), writable: true });
+  }
+  return standIn;
+}