Enhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active
TypeScript aianthropicartifactsawsazurechatgptchatgpt-cloneclaudeclonedeepseekgeminigooglegpt-5librechatmcpo1openairesponses-apivisionwebui
🏛️ refactor: Extract Engine-Neutral Tenant Policy (#15575)
Danny Avila64d807bd0ae0
diff --git a/packages/data-schemas/src/models/plugins/tenantIsolation.ts b/packages/data-schemas/src/models/plugins/tenantIsolation.tsindex 1450610345..9173215024 100644--- a/packages/data-schemas/src/models/plugins/tenantIsolation.ts+++ b/packages/data-schemas/src/models/plugins/tenantIsolation.ts@@ -1,79 +1,33 @@-import type { Schema, Query, Aggregate, UpdateQuery } from 'mongoose';-import { getTenantId, SYSTEM_TENANT_ID } from '~/config/tenantContext';-import logger from '~/config/winston';+import type { Schema, Query, Aggregate } from 'mongoose';+import type { TenantDocument, TenantUpdate } from '~/tenant/policy';+import {+ tenantFilter,+ scopeReplacement,+ currentTenantScope,+ resolveTenantScope,+ stampTenantOnDocument,+ sanitizeTenantMutation,+ resetTenantStrictCache,+ warnOnInvalidStrictSetting,+} from '~/tenant/policy';-let _strictMode: boolean | undefined;--function isStrict(): boolean {- return (_strictMode ??= process.env.TENANT_ISOLATION_STRICT === 'true');-}+/**+ * Mongoose binding for the engine-neutral tenant-isolation policy.+ *+ * Every rule enforced here is defined in `~/tenant/policy`; this module only+ * adapts Mongoose's middleware surface to it, so a second storage engine can+ * reuse the same decisions without reimplementing them.+ *//** Resets the cached strict-mode flag. Exposed for test teardown only. */export function _resetStrictCache(): void {- _strictMode = undefined;+ resetTenantStrictCache();}-if (- process.env.TENANT_ISOLATION_STRICT &&- process.env.TENANT_ISOLATION_STRICT !== 'true' &&- process.env.TENANT_ISOLATION_STRICT !== 'false'-) {- logger.warn(- `[TenantIsolation] TENANT_ISOLATION_STRICT="${process.env.TENANT_ISOLATION_STRICT}" ` +- 'is not "true" or "false"; defaulting to non-strict mode.',- );-}+warnOnInvalidStrictSetting();const TENANT_ISOLATION_APPLIED = Symbol.for('librechat:tenantIsolation');-const VALUE_OPERATORS = ['$set', '$setOnInsert'] as const;-const STRIP_OPERATORS = ['$unset', '$rename'] as const;--/**- * Strips `tenantId` from update payloads when it matches the current tenant- * (or no context is active). Throws on cross-tenant mutations.- *- * `$unset`/`$rename` always strip — unsetting/renaming tenantId is never valid.- * Empty operator objects are removed after stripping to avoid MongoDB errors.- */-function sanitizeTenantIdMutation(update: UpdateQuery<unknown> | null): void {- if (!update) {- return;- }-- const currentTenantId = getTenantId();-- for (const op of VALUE_OPERATORS) {- const payload = update[op] as Record<string, unknown> | undefined;- if (payload && 'tenantId' in payload) {- if (currentTenantId && payload.tenantId !== currentTenantId) {- throw new Error('[TenantIsolation] Cross-tenant tenantId mutation is not allowed');- }- delete payload.tenantId;- if (Object.keys(payload).length === 0) {- delete (update as Record<string, unknown>)[op];- }- }- }-- for (const op of STRIP_OPERATORS) {- const payload = update[op] as Record<string, unknown> | undefined;- if (payload && 'tenantId' in payload) {- delete payload.tenantId;- if (Object.keys(payload).length === 0) {- delete (update as Record<string, unknown>)[op];- }- }- }-- if ('tenantId' in update) {- if (currentTenantId && update.tenantId !== currentTenantId) {- throw new Error('[TenantIsolation] Cross-tenant tenantId mutation is not allowed');- }- delete (update as Record<string, unknown>).tenantId;- }-}-/*** Mongoose schema plugin that enforces tenant-level data isolation.*@@ -91,47 +45,38 @@ export function applyTenantIsolation(schema: Schema): void {s[TENANT_ISOLATION_APPLIED] = true;const queryMiddleware = function (this: Query<unknown, unknown>) {- const tenantId = getTenantId();-- if (!tenantId && isStrict()) {- throw new Error('[TenantIsolation] Query attempted without tenant context in strict mode');+ const filter = tenantFilter(resolveTenantScope('Query'));+ if (filter) {+ this.where(filter);}-- if (!tenantId || tenantId === SYSTEM_TENANT_ID) {- return;- }-- this.where({ tenantId });};const updateGuard = function (this: Query<unknown, unknown>) {- const tenantId = getTenantId();- if (tenantId === SYSTEM_TENANT_ID) {+ const scope = currentTenantScope();+ if (scope.kind === 'system') {return;}- sanitizeTenantIdMutation(this.getUpdate() as UpdateQuery<unknown> | null);- const update = this.getUpdate() as Record<string, unknown> | null;- if (update && Object.keys(update).length === 0) {+ const result = sanitizeTenantMutation(scope, this.getUpdate() as TenantUpdate | null, 'guard');+ if (result.changed) {+ this.setUpdate(result.update);+ }++ if (result.emptied) {this.where({ _id: { $in: [] } });this.setOptions({ upsert: false });}};const replaceGuard = function (this: Query<unknown, unknown>) {- const tenantId = getTenantId();- if (tenantId === SYSTEM_TENANT_ID) {- return;- }- const replacement = this.getUpdate() as Record<string, unknown> | null;- if (!replacement) {+ const scope = currentTenantScope();+ if (scope.kind === 'system') {return;}- if ('tenantId' in replacement && replacement.tenantId !== tenantId) {- throw new Error('[TenantIsolation] Modifying tenantId via replacement is not allowed');- }- if (tenantId && !('tenantId' in replacement)) {- replacement.tenantId = tenantId;++ const result = scopeReplacement(scope, this.getUpdate() as TenantDocument | null);+ if (result.changed && result.replacement) {+ this.setUpdate(result.replacement);}};@@ -156,60 +101,27 @@ export function applyTenantIsolation(schema: Schema): void {schema.pre('findOneAndReplace', replaceGuard);schema.pre('aggregate', function (this: Aggregate<unknown>) {- const tenantId = getTenantId();-- if (!tenantId && isStrict()) {- throw new Error(- '[TenantIsolation] Aggregate attempted without tenant context in strict mode',- );+ const filter = tenantFilter(resolveTenantScope('Aggregate'));+ if (filter) {+ this.pipeline().unshift({ $match: filter });}-- if (!tenantId || tenantId === SYSTEM_TENANT_ID) {- return;- }-- this.pipeline().unshift({ $match: { tenantId } });});schema.pre('save', function () {- const tenantId = getTenantId();-- if (!tenantId && isStrict()) {- throw new Error('[TenantIsolation] Save attempted without tenant context in strict mode');- }-- if (tenantId && tenantId !== SYSTEM_TENANT_ID) {- if (!this.tenantId) {- this.tenantId = tenantId;- } else if (isStrict() && this.tenantId !== tenantId) {- throw new Error(- '[TenantIsolation] Document tenantId does not match current tenant context',- );- }- }+ stampTenantOnDocument(resolveTenantScope('Save'), this as unknown as TenantDocument);});schema.pre('insertMany', function (next, docs) {- const tenantId = getTenantId();-- if (!tenantId && isStrict()) {- return next(- new Error('[TenantIsolation] insertMany attempted without tenant context in strict mode'),- );- }-- if (tenantId && tenantId !== SYSTEM_TENANT_ID && Array.isArray(docs)) {- for (const doc of docs) {- if (!doc.tenantId) {- doc.tenantId = tenantId;- } else if (isStrict() && doc.tenantId !== tenantId) {- return next(- new Error('[TenantIsolation] Document tenantId does not match current tenant context'),- );+ try {+ const scope = resolveTenantScope('insertMany');+ if (Array.isArray(docs)) {+ for (const doc of docs) {+ stampTenantOnDocument(scope, doc as TenantDocument);}}+ } catch (error) {+ return next(error as Error);}-next();});}diff --git a/packages/data-schemas/src/tenant/policy.spec.ts b/packages/data-schemas/src/tenant/policy.spec.tsnew file mode 100644index 0000000000..d72143bcee--- /dev/null+++ b/packages/data-schemas/src/tenant/policy.spec.ts@@ -0,0 +1,295 @@+import type { TenantScope } from './policy';+import {+ tenantFilter,+ scopeReplacement,+ currentTenantScope,+ resolveTenantScope,+ TenantIsolationError,+ stampTenantOnDocument,+ sanitizeTenantMutation,+ resetTenantStrictCache,+} from './policy';+import { tenantStorage, SYSTEM_TENANT_ID } from '~/config/tenantContext';++/**+ * The tenant policy is engine-neutral: these tests run with no database and no+ * Mongoose model. A storage engine that satisfies this contract inherits tenant+ * isolation without reimplementing any of its rules.+ */++const SCOPED: TenantScope = { kind: 'scoped', tenantId: 'tenant-a' };+const SYSTEM: TenantScope = { kind: 'system' };+const UNSCOPED: TenantScope = { kind: 'unscoped' };++const withStrict = async (value: boolean, fn: () => void | Promise<void>): Promise<void> => {+ const previous = process.env.TENANT_ISOLATION_STRICT;+ process.env.TENANT_ISOLATION_STRICT = String(value);+ resetTenantStrictCache();+ try {+ await fn();+ } finally {+ if (previous === undefined) {+ delete process.env.TENANT_ISOLATION_STRICT;+ } else {+ process.env.TENANT_ISOLATION_STRICT = previous;+ }+ resetTenantStrictCache();+ }+};++afterEach(() => {+ resetTenantStrictCache();+});++describe('currentTenantScope', () => {+ it('reports unscoped with no ambient context', () => {+ expect(currentTenantScope()).toEqual({ kind: 'unscoped' });+ });++ it('reports the active tenant', async () => {+ const scope = await tenantStorage.run({ tenantId: 'tenant-a' }, async () =>+ currentTenantScope(),+ );+ expect(scope).toEqual({ kind: 'scoped', tenantId: 'tenant-a' });+ });++ it('reports system for the cross-tenant sentinel', async () => {+ const scope = await tenantStorage.run({ tenantId: SYSTEM_TENANT_ID }, async () =>+ currentTenantScope(),+ );+ expect(scope).toEqual({ kind: 'system' });+ });++ it('never throws in strict mode', async () => {+ await withStrict(true, () => {+ expect(currentTenantScope()).toEqual({ kind: 'unscoped' });+ });+ });+});++describe('resolveTenantScope', () => {+ it('fails closed in strict mode and names the operation', async () => {+ await withStrict(true, () => {+ expect(() => resolveTenantScope('Query')).toThrow(+ '[TenantIsolation] Query attempted without tenant context in strict mode',+ );+ expect(() => resolveTenantScope('Query')).toThrow(TenantIsolationError);+ });+ });++ it('passes through when not strict', async () => {+ await withStrict(false, () => {+ expect(resolveTenantScope('Query')).toEqual({ kind: 'unscoped' });+ });+ });++ it('lets an active tenant through strict mode', async () => {+ await withStrict(true, async () => {+ const scope = await tenantStorage.run({ tenantId: 'tenant-a' }, async () =>+ resolveTenantScope('Query'),+ );+ expect(scope).toEqual({ kind: 'scoped', tenantId: 'tenant-a' });+ });+ });++ it('lets the system sentinel through strict mode', async () => {+ await withStrict(true, async () => {+ const scope = await tenantStorage.run({ tenantId: SYSTEM_TENANT_ID }, async () =>+ resolveTenantScope('Query'),+ );+ expect(scope).toEqual({ kind: 'system' });+ });+ });+});++describe('tenantFilter', () => {+ it('restricts to the active tenant', () => {+ expect(tenantFilter(SCOPED)).toEqual({ tenantId: 'tenant-a' });+ });++ it('does not restrict system or unscoped reads', () => {+ expect(tenantFilter(SYSTEM)).toBeUndefined();+ expect(tenantFilter(UNSCOPED)).toBeUndefined();+ });+});++describe('sanitizeTenantMutation (guard mode)', () => {+ it('refuses a cross-tenant $set', () => {+ expect(() =>+ sanitizeTenantMutation(SCOPED, { $set: { tenantId: 'tenant-b' } }, 'guard'),+ ).toThrow('[TenantIsolation] Cross-tenant tenantId mutation is not allowed');+ });++ it('refuses a cross-tenant top-level value', () => {+ expect(() => sanitizeTenantMutation(SCOPED, { tenantId: 'tenant-b' }, 'guard')).toThrow(+ TenantIsolationError,+ );+ });++ it('strips a matching tenantId rather than writing it', () => {+ const result = sanitizeTenantMutation(+ SCOPED,+ { $set: { tenantId: 'tenant-a', name: 'x' } },+ 'guard',+ );+ expect(result.update).toEqual({ $set: { name: 'x' } });+ expect(result.changed).toBe(true);+ expect(result.emptied).toBe(false);+ });++ it('drops an operator left empty by stripping', () => {+ const result = sanitizeTenantMutation(SCOPED, { $set: { tenantId: 'tenant-a' } }, 'guard');+ expect(result.update).toEqual({});+ expect(result.emptied).toBe(true);+ });++ it('always strips $unset and $rename without throwing', () => {+ const result = sanitizeTenantMutation(+ SCOPED,+ { $unset: { tenantId: '' }, $rename: { tenantId: 'other' } },+ 'guard',+ );+ expect(result.update).toEqual({});+ expect(result.emptied).toBe(true);+ });++ it('strips silently when no tenant is active', () => {+ const result = sanitizeTenantMutation(UNSCOPED, { $set: { tenantId: 'tenant-b' } }, 'guard');+ expect(result.update).toEqual({});+ });++ it('leaves untouched payloads by reference', () => {+ const update = { $set: { name: 'x' } };+ const result = sanitizeTenantMutation(SCOPED, update, 'guard');+ expect(result.update).toBe(update);+ expect(result.changed).toBe(false);+ });++ it('never mutates the caller payload', () => {+ const update = { $set: { tenantId: 'tenant-a', name: 'x' }, $inc: { n: 1 } };+ sanitizeTenantMutation(SCOPED, update, 'guard');+ expect(update).toEqual({ $set: { tenantId: 'tenant-a', name: 'x' }, $inc: { n: 1 } });+ });++ it('leaves a system-scoped payload alone so cross-tenant writes stay possible', () => {+ const update = { $set: { tenantId: 'tenant-b', name: 'x' } };+ const result = sanitizeTenantMutation(SYSTEM, update, 'guard');+ expect(result.update).toBe(update);+ expect(result.changed).toBe(false);+ });++ it('treats a missing payload as empty', () => {+ expect(sanitizeTenantMutation(SCOPED, null, 'guard')).toEqual({+ update: {},+ emptied: false,+ changed: false,+ });+ });+});++describe('sanitizeTenantMutation (strip mode)', () => {+ it('strips a cross-tenant value instead of throwing', () => {+ const result = sanitizeTenantMutation(+ SCOPED,+ { $set: { tenantId: 'tenant-b', name: 'x' } },+ 'strip',+ );+ expect(result.update).toEqual({ $set: { name: 'x' } });+ });++ it('strips every operator and the top level', () => {+ const result = sanitizeTenantMutation(+ SCOPED,+ {+ tenantId: 'tenant-b',+ $set: { tenantId: 'tenant-b' },+ $setOnInsert: { tenantId: 'tenant-b' },+ $unset: { tenantId: '' },+ $rename: { tenantId: 'x' },+ },+ 'strip',+ );+ expect(result.update).toEqual({});+ expect(result.emptied).toBe(true);+ });+});++describe('scopeReplacement', () => {+ it('stamps the active tenant when the replacement omits it', () => {+ const result = scopeReplacement(SCOPED, { name: 'x' });+ expect(result.replacement).toEqual({ name: 'x', tenantId: 'tenant-a' });+ expect(result.changed).toBe(true);+ });++ it('accepts a replacement naming the active tenant', () => {+ const replacement = { name: 'x', tenantId: 'tenant-a' };+ const result = scopeReplacement(SCOPED, replacement);+ expect(result.replacement).toBe(replacement);+ expect(result.changed).toBe(false);+ });++ it('refuses a replacement naming another tenant', () => {+ expect(() => scopeReplacement(SCOPED, { tenantId: 'tenant-b' })).toThrow(+ '[TenantIsolation] Modifying tenantId via replacement is not allowed',+ );+ });++ it('refuses any asserted tenantId when no tenant is active', () => {+ expect(() => scopeReplacement(UNSCOPED, { tenantId: 'tenant-b' })).toThrow(+ TenantIsolationError,+ );+ });++ it('leaves system replacements alone', () => {+ const replacement = { name: 'x', tenantId: 'tenant-b' };+ const result = scopeReplacement(SYSTEM, replacement);+ expect(result.replacement).toBe(replacement);+ expect(result.changed).toBe(false);+ });++ it('never mutates the caller replacement', () => {+ const replacement = { name: 'x' };+ scopeReplacement(SCOPED, replacement);+ expect(replacement).toEqual({ name: 'x' });+ });+});++describe('stampTenantOnDocument', () => {+ it('stamps the active tenant onto a new document', () => {+ const document: Record<string, unknown> = { name: 'x' };+ stampTenantOnDocument(SCOPED, document);+ expect(document.tenantId).toBe('tenant-a');+ });++ it('leaves a matching tenantId in place', () => {+ const document: Record<string, unknown> = { tenantId: 'tenant-a' };+ stampTenantOnDocument(SCOPED, document);+ expect(document.tenantId).toBe('tenant-a');+ });++ it('tolerates a mismatched tenantId when not strict', async () => {+ await withStrict(false, () => {+ const document: Record<string, unknown> = { tenantId: 'tenant-b' };+ stampTenantOnDocument(SCOPED, document);+ expect(document.tenantId).toBe('tenant-b');+ });+ });++ it('refuses a mismatched tenantId in strict mode', async () => {+ await withStrict(true, () => {+ expect(() => stampTenantOnDocument(SCOPED, { tenantId: 'tenant-b' })).toThrow(+ '[TenantIsolation] Document tenantId does not match current tenant context',+ );+ });+ });++ it('does not stamp system or unscoped writes', () => {+ const systemDocument: Record<string, unknown> = { name: 'x' };+ stampTenantOnDocument(SYSTEM, systemDocument);+ expect(systemDocument.tenantId).toBeUndefined();++ const unscopedDocument: Record<string, unknown> = { name: 'x' };+ stampTenantOnDocument(UNSCOPED, unscopedDocument);+ expect(unscopedDocument.tenantId).toBeUndefined();+ });+});diff --git a/packages/data-schemas/src/tenant/policy.ts b/packages/data-schemas/src/tenant/policy.tsnew file mode 100644index 0000000000..c693ec310b--- /dev/null+++ b/packages/data-schemas/src/tenant/policy.ts@@ -0,0 +1,244 @@+import { getTenantId, SYSTEM_TENANT_ID } from '~/config/tenantContext';+import logger from '~/config/winston';++/**+ * Engine-neutral tenant-isolation policy.+ *+ * Every rule that decides what tenant scoping means lives here as a pure+ * function over plain objects. Storage engines bind these rules to their own+ * query surface (see `~/models/plugins/tenantIsolation` for the Mongoose+ * binding); no rule in this module may reference an engine's types.+ */++/** Resolved tenant scope for the current async context. */+export type TenantScope =+ | { readonly kind: 'scoped'; readonly tenantId: string }+ | { readonly kind: 'system' }+ | { readonly kind: 'unscoped' };++/** A document-shaped payload the policy may stamp or inspect. */+export type TenantDocument = Record<string, unknown> & { tenantId?: unknown };++/** An update payload expressed with MongoDB-style mutation operators. */+export type TenantUpdate = Record<string, unknown>;++/**+ * How a payload carrying `tenantId` is handled.+ *+ * - `guard` — a cross-tenant value throws; a matching value is stripped.+ * - `strip` — every value is stripped silently, never throws.+ */+export type TenantMutationMode = 'guard' | 'strip';++export class TenantIsolationError extends Error {+ constructor(message: string) {+ super(message);+ this.name = 'TenantIsolationError';+ }+}++const SYSTEM_SCOPE: TenantScope = { kind: 'system' };+const UNSCOPED: TenantScope = { kind: 'unscoped' };++const VALUE_OPERATORS = ['$set', '$setOnInsert'] as const;+const STRIP_OPERATORS = ['$unset', '$rename'] as const;++let strictMode: boolean | undefined;++/** True when `TENANT_ISOLATION_STRICT=true`, i.e. missing context fails closed. */+export function isTenantIsolationStrict(): boolean {+ return (strictMode ??= process.env.TENANT_ISOLATION_STRICT === 'true');+}++/** Resets the cached strict-mode flag. Exposed for test teardown only. */+export function resetTenantStrictCache(): void {+ strictMode = undefined;+}++export function warnOnInvalidStrictSetting(): void {+ const raw = process.env.TENANT_ISOLATION_STRICT;+ if (raw && raw !== 'true' && raw !== 'false') {+ logger.warn(+ `[TenantIsolation] TENANT_ISOLATION_STRICT="${raw}" ` ++ 'is not "true" or "false"; defaulting to non-strict mode.',+ );+ }+}++/**+ * Reads the tenant scope without enforcing strict mode.+ * Use for guards that run after a scoping check has already fired.+ */+export function currentTenantScope(): TenantScope {+ const tenantId = getTenantId();+ if (!tenantId) {+ return UNSCOPED;+ }+ if (tenantId === SYSTEM_TENANT_ID) {+ return SYSTEM_SCOPE;+ }+ return { kind: 'scoped', tenantId };+}++/**+ * Reads the tenant scope, failing closed when strict mode is on and no+ * context is active. `operation` names the caller in the thrown message.+ */+export function resolveTenantScope(operation: string): TenantScope {+ const scope = currentTenantScope();+ if (scope.kind === 'unscoped' && isTenantIsolationStrict()) {+ throw new TenantIsolationError(+ `[TenantIsolation] ${operation} attempted without tenant context in strict mode`,+ );+ }+ return scope;+}++/** The filter fragment that restricts reads and writes to the active tenant. */+export function tenantFilter(scope: TenantScope): { tenantId: string } | undefined {+ return scope.kind === 'scoped' ? { tenantId: scope.tenantId } : undefined;+}++/** Result of sanitizing an update payload against the active scope. */+export interface TenantMutationResult {+ /** The payload to send to the engine — the input itself when nothing changed. */+ readonly update: TenantUpdate;+ /** True when sanitizing removed every remaining instruction. */+ readonly emptied: boolean;+ /** True when the payload differs from the input and must be written back. */+ readonly changed: boolean;+}++/**+ * Removes caller-supplied `tenantId` from an update payload — top level and+ * inside mutation operators. Application code never controls `tenantId`.+ *+ * `guard` mode leaves system-scoped payloads untouched: a deliberate+ * cross-tenant operation is the one caller allowed to set `tenantId`.+ * `strip` mode ignores the scope and always strips.+ *+ * Copy-on-write: the input is never mutated, and the same reference is+ * returned when there was nothing to strip.+ */+export function sanitizeTenantMutation(+ scope: TenantScope,+ update: TenantUpdate | null | undefined,+ mode: TenantMutationMode,+): TenantMutationResult {+ if (!update) {+ return { update: {}, emptied: false, changed: false };+ }++ if (mode === 'guard' && scope.kind === 'system') {+ return { update, emptied: false, changed: false };+ }++ let next: TenantUpdate | null = null;+ const draft = (): TenantUpdate => (next ??= { ...update });++ for (const operator of VALUE_OPERATORS) {+ const payload = update[operator] as Record<string, unknown> | undefined;+ if (!payload || !('tenantId' in payload)) {+ continue;+ }+ assertSameTenant(scope, payload.tenantId, mode);+ const { tenantId: _stripped, ...rest } = payload;+ writeOperator(draft(), operator, rest);+ }++ for (const operator of STRIP_OPERATORS) {+ const payload = update[operator] as Record<string, unknown> | undefined;+ if (!payload || !('tenantId' in payload)) {+ continue;+ }+ const { tenantId: _stripped, ...rest } = payload;+ writeOperator(draft(), operator, rest);+ }++ if ('tenantId' in update) {+ assertSameTenant(scope, update.tenantId, mode);+ delete draft().tenantId;+ }++ const result = next ?? update;+ return {+ update: result,+ emptied: Object.keys(result).length === 0,+ changed: next != null,+ };+}++function writeOperator(+ target: TenantUpdate,+ operator: string,+ rest: Record<string, unknown>,+): void {+ if (Object.keys(rest).length === 0) {+ delete target[operator];+ return;+ }+ target[operator] = rest;+}++function assertSameTenant(scope: TenantScope, value: unknown, mode: TenantMutationMode): void {+ if (mode === 'strip') {+ return;+ }+ if (scope.kind === 'scoped' && value !== scope.tenantId) {+ throw new TenantIsolationError(+ '[TenantIsolation] Cross-tenant tenantId mutation is not allowed',+ );+ }+}++/**+ * Validates a whole-document replacement and stamps the active tenant onto it.+ *+ * Copy-on-write, like `sanitizeTenantMutation`. A replacement that names any+ * tenant other than the active one is refused — including when no context is+ * active, where no `tenantId` may be asserted at all.+ */+export function scopeReplacement(+ scope: TenantScope,+ replacement: TenantDocument | null | undefined,+): { readonly replacement: TenantDocument | null; readonly changed: boolean } {+ if (!replacement || scope.kind === 'system') {+ return { replacement: replacement ?? null, changed: false };+ }++ const tenantId = scope.kind === 'scoped' ? scope.tenantId : undefined;++ if ('tenantId' in replacement && replacement.tenantId !== tenantId) {+ throw new TenantIsolationError(+ '[TenantIsolation] Modifying tenantId via replacement is not allowed',+ );+ }++ if (tenantId && !('tenantId' in replacement)) {+ return { replacement: { ...replacement, tenantId }, changed: true };+ }++ return { replacement, changed: false };+}++/**+ * Stamps the active tenant onto a document being inserted.+ *+ * A document that already names a different tenant is refused in strict mode+ * and passed through otherwise, preserving pre-tenancy backfill behaviour.+ * Mutates in place — insert paths own the documents they hand us.+ */+export function stampTenantOnDocument(scope: TenantScope, document: TenantDocument): void {+ if (scope.kind !== 'scoped') {+ return;+ }+ if (!document.tenantId) {+ document.tenantId = scope.tenantId;+ return;+ }+ if (isTenantIsolationStrict() && document.tenantId !== scope.tenantId) {+ throw new TenantIsolationError(+ '[TenantIsolation] Document tenantId does not match current tenant context',+ );+ }+}diff --git a/packages/data-schemas/src/utils/tenantBulkWrite.ts b/packages/data-schemas/src/utils/tenantBulkWrite.tsindex e8e104ca72..a3ac63b662 100644--- a/packages/data-schemas/src/utils/tenantBulkWrite.ts+++ b/packages/data-schemas/src/utils/tenantBulkWrite.ts@@ -1,17 +1,17 @@import type { AnyBulkWriteOperation, Model, MongooseBulkWriteOptions } from 'mongoose';import type { BulkWriteResult } from 'mongodb';-import { getTenantId, SYSTEM_TENANT_ID } from '~/config/tenantContext';+import type { TenantScope, TenantUpdate } from '~/tenant/policy';+import {+ resolveTenantScope,+ resetTenantStrictCache,+ sanitizeTenantMutation,+ isTenantIsolationStrict,+} from '~/tenant/policy';import logger from '~/config/winston';-let _strictMode: boolean | undefined;--function isStrict(): boolean {- return (_strictMode ??= process.env.TENANT_ISOLATION_STRICT === 'true');-}-/** Resets the cached strict-mode flag. Exposed for test teardown only. */export function _resetBulkWriteStrictCache(): void {- _strictMode = undefined;+ resetTenantStrictCache();}/**@@ -25,10 +25,10 @@ export function _resetBulkWriteStrictCache(): void {* 2. **Injects** `tenantId` into operation filters and insert documents when a* tenant context is active.*- * Unlike the Mongoose middleware guard (`sanitizeTenantIdMutation`), which throws- * on cross-tenant values, this wrapper strips silently. Throwing mid-batch would- * abort the entire write for one bad field; the filter injection already scopes- * every operation to the correct tenant.+ * Unlike the query middleware, which throws on cross-tenant values, this wrapper+ * strips silently (`strip` mode). Throwing mid-batch would abort the entire write+ * for one bad field; the filter injection already scopes every operation to the+ * correct tenant.** Behavior:* - **tenantId present** (normal request): sanitize + inject into filters/documents.@@ -41,27 +41,18 @@ export async function tenantSafeBulkWrite<T>(ops: AnyBulkWriteOperation[],options?: MongooseBulkWriteOptions,): Promise<BulkWriteResult> {- const tenantId = getTenantId();+ const scope = resolveTenantScope(`bulkWrite on ${model.modelName}`);// Strip tenantId from update documents unconditionally — application code// must never control tenantId via update payloads regardless of context.- const sanitized = ops.map(sanitizeBulkOp).filter((op): op is AnyBulkWriteOperation => op != null);-- if (!tenantId) {- if (isStrict()) {- throw new Error(- `[TenantIsolation] bulkWrite on ${model.modelName} attempted without tenant context in strict mode`,- );- }- return sanitized.length > 0 ? model.bulkWrite(sanitized, options) : EMPTY_BULK_RESULT;- }+ const sanitized = ops+ .map((op) => sanitizeBulkOp(op, scope))+ .filter((op): op is AnyBulkWriteOperation => op != null);- if (tenantId === SYSTEM_TENANT_ID) {- return sanitized.length > 0 ? model.bulkWrite(sanitized, options) : EMPTY_BULK_RESULT;- }+ const prepared =+ scope.kind === 'scoped' ? sanitized.map((op) => injectTenantId(op, scope.tenantId)) : sanitized;- const injected = sanitized.map((op) => injectTenantId(op, tenantId));- return injected.length > 0 ? model.bulkWrite(injected, options) : EMPTY_BULK_RESULT;+ return prepared.length > 0 ? model.bulkWrite(prepared, options) : EMPTY_BULK_RESULT;}/** Returned when all ops are dropped after sanitization. Single shared instance. */@@ -76,19 +67,20 @@ const EMPTY_BULK_RESULT = Object.freeze({}) as unknown as BulkWriteResult;/** Strips tenantId from update documents. Returns null if the op becomes empty. */-function sanitizeBulkOp(op: AnyBulkWriteOperation): AnyBulkWriteOperation | null {+function sanitizeBulkOp(+ op: AnyBulkWriteOperation,+ scope: TenantScope,+): AnyBulkWriteOperation | null {if ('updateOne' in op) {const { update, ...rest } = op.updateOne;- const stripped = stripTenantIdFromUpdate(update as Record<string, unknown>);- return Object.keys(stripped).length === 0 ? null : { updateOne: { ...rest, update: stripped } };+ const result = sanitizeTenantMutation(scope, update as TenantUpdate, 'strip');+ return result.emptied ? null : { updateOne: { ...rest, update: result.update } };}if ('updateMany' in op) {const { update, ...rest } = op.updateMany;- const stripped = stripTenantIdFromUpdate(update as Record<string, unknown>);- return Object.keys(stripped).length === 0- ? null- : { updateMany: { ...rest, update: stripped } };+ const result = sanitizeTenantMutation(scope, update as TenantUpdate, 'strip');+ return result.emptied ? null : { updateMany: { ...rest, update: result.update } };}return op;@@ -135,7 +127,7 @@ function injectTenantId(op: AnyBulkWriteOperation, tenantId: string): AnyBulkWri};}- if (isStrict()) {+ if (isTenantIsolationStrict()) {throw new Error('[TenantIsolation] Unknown bulkWrite operation type in strict mode — refusing to pass through without tenant injection',);@@ -145,36 +137,3 @@ function injectTenantId(op: AnyBulkWriteOperation, tenantId: string): AnyBulkWri);return op;}--const MUTATION_OPS = ['$set', '$unset', '$setOnInsert', '$rename'] as const;--/**- * Strips `tenantId` from a bulk-write update document — both top-level- * and inside mutation operators. Allocates only when stripping is needed.- */-function stripTenantIdFromUpdate(update: Record<string, unknown>): Record<string, unknown> {- let result: Record<string, unknown> | null = null;-- if ('tenantId' in update) {- const { tenantId: _tenantId, ...rest } = update;- result = rest;- }-- for (const op of MUTATION_OPS) {- const source = result ?? update;- const payload = source[op] as Record<string, unknown> | undefined;- if (payload && 'tenantId' in payload) {- if (!result) {- result = { ...update };- }- const { tenantId: _tenantId, ...rest } = payload;- if (Object.keys(rest).length > 0) {- result[op] = rest;- } else {- delete result[op];- }- }- }-- return result ?? update;-}