@lenne.tech/nest-server 11.34.1 → 11.35.0

package/src/core/common/helpers/graphql-ws-context.helper.ts

@@ -0,0 +1,192 @@
+// `require`, NOT an ESM import: `@nestjs/graphql` builds the schema with the instance Node's CJS
+// cache holds, and graphql REFUSES a schema "from another module or realm". An ESM import can resolve
+// to a second copy of the module (a bundler's interop namespace, or a duplicated install), and the
+// wrapper would then reject the very schema it was handed. The repo already uses this form for
+// `graphql-upload` and `lodash` for the same reason.
+import graphql = require('graphql');
+
+import { getTenantContextResolver } from '../services/core-tenant-context.registry';
+import { ConfigService } from '../services/config.service';
+import { IRequestContext, RequestContext } from '../services/request-context.service';
+
+/**
+ * A `RequestContext` for GraphQL operations that arrive over a WEBSOCKET.
+ *
+ * WHY THIS EXISTS — the gap it closes is a silent, complete tenant bypass:
+ *
+ * `RequestContextMiddleware` is Express middleware (`consumer.apply(...).forRoutes('*')`). A
+ * WebSocket UPGRADE is not a `request` event, so it traverses no middleware — and `CoreTenantGuard`
+ * cannot help either, because its `getRequest()` looks for `context.req`, which a subscription
+ * context (the graphql-ws `extra` object) does not have, so the guard returns `true` without
+ * deciding anything.
+ *
+ * The consequence was invisible from the query itself. `mongooseTenantPlugin.shouldBypass()` reads
+ * "no RequestContext" as "system operation, no filter" — correct for a cron job or a migration, and
+ * exactly wrong here. So a tenant-scoped read performed while delivering a subscription message
+ * returned EVERY tenant's rows, and the plugin's own safety net (which throws when a tenant-scoped
+ * schema is touched without a tenant) never fired, because there was no context to notice.
+ *
+ * WHERE IT HOOKS IN: `GqlSubscriptionService` reads `execute` and `subscribe` off the GraphQL module
+ * options and hands them to BOTH WebSocket transports (`graphql-ws` and `subscriptions-transport-ws`),
+ * defaulting to graphql-js's own. Those two functions are the only place where the whole WS operation
+ * — including every field resolver and the `resolve`/`filter` callbacks of a subscription — is
+ * reachable as one call. HTTP does not go through them (Apollo runs its own pipeline), so wrapping
+ * them touches the WS path only.
+ *
+ * THE ASYNC-ITERATOR PART IS LOAD-BEARING. `subscribe()` returns an AsyncIterator, and graphql-js
+ * runs the per-event execution — `resolve`, `filter`, every field resolver — inside that iterator's
+ * `next()`, which the transport pulls LONG AFTER `subscribe()` returned. Establishing the context
+ * only around the `subscribe()` call therefore covers the initial subscribe and nothing else: the
+ * store is gone by the time the first message is delivered. Wrapping `next()` (and `return`/`throw`)
+ * is what puts every delivered message inside the context.
+ */
+
+/** Minimal shape of what graphql-js `execute`/`subscribe` receive. */
+interface GraphQlArgs {
+  contextValue?: any;
+  [key: string]: any;
+}
+
+type ExecuteFn = (args: GraphQlArgs) => any;
+
+/**
+ * Read the tenant header out of whatever the transport left on the context.
+ *
+ * Both WS transports are covered, and the reason there are three sources is that they genuinely
+ * differ: `graphql-ws` gets `extra.headers` from `CoreModule`'s `onConnect` (the client's
+ * `connectionParams`), `subscriptions-transport-ws` returns `{ headers }` from its own `onConnect`,
+ * and the raw upgrade request is the fallback for a project with a custom `onConnect` that forwards
+ * neither. Header names are matched case-insensitively — `connectionParams` are client-supplied JSON
+ * and arrive with whatever casing the client used, unlike Node's lower-cased HTTP headers.
+ */
+function readTenantHeader(contextValue: any): string | undefined {
+  const headerName = (ConfigService.configFastButReadOnly?.multiTenancy?.headerName ?? 'x-tenant-id').toLowerCase();
+  const sources = [contextValue?.headers, contextValue?.connectionParams, contextValue?.request?.headers];
+  for (const source of sources) {
+    if (!source || typeof source !== 'object') {
+      continue;
+    }
+    for (const [key, value] of Object.entries(source as Record<string, unknown>)) {
+      if (key.toLowerCase() === headerName && typeof value === 'string' && value) {
+        return value;
+      }
+    }
+  }
+  return undefined;
+}
+
+/** The user the connection authenticated as, as `CoreModule`'s `onConnect` recorded it. */
+function readUser(contextValue: any): any {
+  return contextValue?.user ?? contextValue?.extra?.user ?? undefined;
+}
+
+/**
+ * Build the context for one WebSocket operation.
+ *
+ * Returns `undefined` when the operation is NOT a WebSocket one (an HTTP context carries `req`, and
+ * the middleware has already established a context for it) — wrapping that again would replace a
+ * live, lazily-evaluated context with a snapshot.
+ */
+export async function buildWsRequestContext(contextValue: any): Promise<IRequestContext | undefined> {
+  if (!contextValue || typeof contextValue !== 'object' || contextValue.req) {
+    return undefined;
+  }
+
+  const user = readUser(contextValue);
+  const context: IRequestContext = { currentUser: user };
+
+  // Language: same source as the HTTP path, when the transport carried it.
+  const acceptLanguage =
+    contextValue.headers?.['accept-language'] ??
+    contextValue.connectionParams?.['accept-language'] ??
+    contextValue.request?.headers?.['accept-language'];
+  if (typeof acceptLanguage === 'string') {
+    context.language = acceptLanguage;
+  }
+
+  const resolver = getTenantContextResolver();
+  if (resolver) {
+    // A failure here must NOT be answered with an unscoped context — that is the leak this file
+    // exists to close. Leaving the tenant fields unset makes the plugin's safety net refuse
+    // tenant-scoped reads, which is the safe direction.
+    try {
+      Object.assign(context, await resolver.resolve(user, readTenantHeader(contextValue)));
+    } catch {
+      // Intentionally swallowed: see above. Non-tenant operations keep working.
+    }
+  }
+
+  return context;
+}
+
+/**
+ * Run an AsyncIterator's pulls inside `context`.
+ *
+ * `next()` is where graphql-js executes the per-event selection set, so this is what carries the
+ * context into every delivered message rather than only into the initial subscribe.
+ */
+export function withRequestContextAsyncIterator<T>(
+  iterator: AsyncIterator<T> & { [Symbol.asyncIterator]?: () => AsyncIterator<T> },
+  context: IRequestContext,
+): AsyncIterableIterator<T> {
+  const wrapped: AsyncIterableIterator<T> = {
+    next: (...args: [] | [undefined]) => RequestContext.run(context, () => iterator.next(...(args as []))),
+    [Symbol.asyncIterator]() {
+      return wrapped;
+    },
+  };
+  if (iterator.return) {
+    wrapped.return = (value?: any) => RequestContext.run(context, () => iterator.return!(value));
+  }
+  if (iterator.throw) {
+    wrapped.throw = (error?: any) => RequestContext.run(context, () => iterator.throw!(error));
+  }
+  return wrapped;
+}
+
+/** Is this an AsyncIterator (a subscription source) rather than a plain execution result? */
+function isAsyncIterable(value: any): boolean {
+  return !!value && typeof value === 'object' && typeof value[Symbol.asyncIterator] === 'function';
+}
+
+/**
+ * Wrap graphql-js `execute` so a query/mutation sent over the WebSocket runs in a request context.
+ *
+ * Not only subscriptions: `graphql-ws` carries queries and mutations too, and those had the same gap.
+ */
+export function createRequestContextAwareExecute(execute: ExecuteFn): ExecuteFn {
+  return async (args: GraphQlArgs) => {
+    const context = await buildWsRequestContext(args?.contextValue);
+    if (!context) {
+      return execute(args);
+    }
+    return RequestContext.run(context, () => execute(args));
+  };
+}
+
+/** Wrap graphql-js `subscribe` so both the subscribe AND every delivered message run in a context. */
+export function createRequestContextAwareSubscribe(subscribe: ExecuteFn): ExecuteFn {
+  return async (args: GraphQlArgs) => {
+    const context = await buildWsRequestContext(args?.contextValue);
+    if (!context) {
+      return subscribe(args);
+    }
+    const result = await RequestContext.run(context, () => subscribe(args));
+    return isAsyncIterable(result) ? withRequestContextAsyncIterator(result as AsyncIterator<any>, context) : result;
+  };
+}
+
+/**
+ * The pair `CoreModule` installs — graphql's own `execute` / `subscribe`, wrapped.
+ *
+ * Zero-arg factories rather than pre-built constants so nothing is captured at module-evaluation
+ * time, and so `core.module.ts` needs no graphql import of its own (see the `require` note at the top
+ * of this file for why that import form matters).
+ */
+export function buildRequestContextAwareExecute(): (args: GraphQlArgs) => any {
+  return createRequestContextAwareExecute(graphql.execute as any);
+}
+
+export function buildRequestContextAwareSubscribe(): (args: GraphQlArgs) => any {
+  return createRequestContextAwareSubscribe(graphql.subscribe as any);
+}

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

@@ -198,10 +198,26 @@ export class GridFSHelper {
   }
 
   /**
-   * Find file metadata by filename
+   * Find file metadata by filename — the MOST RECENT file with that name.
+   *
+   * The sort is load-bearing, not cosmetic. `bucket.find({ filename })` returns natural order,
+   * which in practice is the OLDEST document first, while `openDownloadStreamByName()` defaults to
+   * `revision: -1` — the NEWEST. Filenames are unique in no store and are client-supplied, so with
+   * two files of one name this method answered one document and the download served another: an
+   * ownership rule built on `getRawFileInfoByName()` approved the caller's own file and the stream
+   * handed over the other one.
+   *
+   * Newest-first (rather than oldest-first) because it is the BYTES semantics that must not move:
+   * GridFS treats a re-upload under the same name as a new revision and serves the latest, so
+   * aligning the metadata lookup with that keeps every existing download answering the same bytes
+   * and only corrects the document describing them. `_id` breaks the tie, so two files written in
+   * the same millisecond still order totally.
    */
   static async findFileByName(bucket: GridFSBucket, filename: string): Promise<GridFSFileInfo | null> {
-    const files = await bucket.find({ filename }).toArray();
+    // `uploadDate` FIRST: MongoDB applies sort keys in document order, so leading with `_id` would
+    // make the tie-break the primary key and could disagree with the driver's own by-name revision
+    // order (which sorts on `uploadDate` alone).
+    const files = await bucket.find({ filename }, { limit: 1, sort: { uploadDate: -1, _id: -1 } }).toArray();
     return files.length > 0 ? GridFSHelper.normalizeFileInfo(files[0]) : null;
   }
 

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

@@ -3,6 +3,7 @@ import { Observable } from 'rxjs';
 import { map } from 'rxjs/operators';
 
 import { getContextData } from '../helpers/context.helper';
+import { hasRestrictionsCheckedMarker } from '../decorators/restrictions-checked.marker';
 import { getStringIds } from '../helpers/db.helper';
 import { processDeep } from '../helpers/input.helper';
 import { ConfigService } from '../services/config.service';
@@ -66,7 +67,9 @@ export class CheckSecurityInterceptor implements NestInterceptor {
       objectData = data;
 
       // Check if data already checked
-      if (this.config.noteCheckedObjects && data?._objectAlreadyCheckedForRestrictions) {
+      // Recognised by the framework MARKER, not by a truthy property of that name — see
+      // restrictions-checked.marker.ts for why a document must not be able to skip securityCheck().
+      if (this.config.noteCheckedObjects && hasRestrictionsCheckedMarker(data)) {
         return data;
       }
 

package/src/core/common/interceptors/response-model.interceptor.ts

@@ -6,6 +6,7 @@ import { resolveResponseModelClass } from '../helpers/interceptor.helper';
 import { CoreModel } from '../models/core-model.model';
 import { ConfigService } from '../services/config.service';
 import { ModelRegistry } from '../services/model-registry.service';
+import { hasRestrictionsCheckedMarker } from '../decorators/restrictions-checked.marker';
 
 /**
  * Interceptor that automatically converts plain objects and Mongoose documents
@@ -48,7 +49,7 @@ export class ResponseModelInterceptor implements NestInterceptor {
         }
 
         // Already processed by another interceptor
-        if (data._objectAlreadyCheckedForRestrictions) {
+        if (hasRestrictionsCheckedMarker(data)) {
           return data;
         }
 
@@ -90,7 +91,7 @@ export class ResponseModelInterceptor implements NestInterceptor {
     }
 
     // Already processed
-    if (item._objectAlreadyCheckedForRestrictions) {
+    if (hasRestrictionsCheckedMarker(item)) {
       return item;
     }
 

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

@@ -855,6 +855,41 @@ export interface IErrorCode {
  * therefore be expressed in `checkRights()`, not by a role name alone.
  */
 export interface IFileConfig {
+  /**
+   * WHICH PROJECT CLASS this deployment is — the per-file rule, as a declaration instead of code.
+   *
+   * The role knobs below are the coarse audience filter ("may this caller reach the route at all").
+   * They cannot express "…but only their own", because that sentence needs data. That is what
+   * `CoreFileService.checkRights()` is for — and shipping it only as an `@example` to copy went wrong
+   * twice in this framework's own history, both times permissively. So the four shapes are presets:
+   *
+   * | value             | project class                                                    |
+   * |-------------------|------------------------------------------------------------------|
+   * | `'custom'`        | you override `checkRights()` yourself — **the default**, the framework abstains |
+   * | `'public'`        | open: anyone may read and write; the role gate is the whole policy |
+   * | `'authenticated'` | login-restricted: every signed-in user may use every file         |
+   * | `'owner'`         | per-user: only the uploader, plus ADMIN                           |
+   * | `'tenant'`        | per-tenant: only within one's own validated tenant, plus ADMIN    |
+   *
+   * `'owner'` and `'tenant'` read `metadata.ownerId` / `metadata.tenantId`, which the service STAMPS
+   * as it writes once one of them is active — so an upload through `CoreFileService` is authorizable
+   * without any project code. Files written BEFORE the preset was enabled carry no such metadata and
+   * are therefore ADMIN-only; that is the fail-closed direction, and a one-off backfill fixes it.
+   *
+   * Two things this setting never does: it never overrides an explicit `checkRights()` override (the
+   * override IS the rule), and it never widens the role gate. `'public'` still requires
+   * `downloadRoles: [S_EVERYONE]` — declaring the class and opening the gate are two decisions on
+   * purpose.
+   *
+   * An UNKNOWN value resolves to `'owner'`, not to `'custom'`: a typo means somebody believes they
+   * have an ownership rule, and confirming that belief is the one error that cannot be seen from
+   * outside.
+   *
+   * @default 'custom'
+   * @since 11.35.0
+   */
+  access?: 'authenticated' | 'custom' | 'owner' | 'public' | 'tenant';
+
   /**
    * Roles allowed to DELETE files (`deleteFile` mutation).
    *
@@ -996,9 +1031,28 @@ export interface IMultiTenancy {
 
   /**
    * 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']
+   *
+   * **This is an OFF SWITCH for data isolation, per model.** A listed schema gets no tenant filter at
+   * all: every query on it sees every tenant's rows. That is correct for a genuinely global
+   * collection, and it is a data leak for anything else.
+   *
+   * A schema is only affected if it HAS a `tenantId` field — the plugin attaches to no other. So
+   * listing a model that declares `tenantId` overrides its author's intent, and since 11.35.0 the
+   * plugin logs a warning naming the model when that happens. **Do not list a model just because a
+   * `populate()` returns null** — that is the isolation working; scope the reference instead, or
+   * confirm the referenced collection really is global.
+   *
+   * `User` is the one to think hardest about. It belongs here only when users are GLOBAL (one account
+   * reaches several tenants, memberships carry the scope). If your users are per-tenant — they have a
+   * `tenantId` — listing `User` switches isolation off for the account collection, which is usually
+   * the last place you want it off. Earlier versions of this doc suggested `['User', 'Session']` as an
+   * example; that suggestion is withdrawn, because it is only right for the global-user model.
+   *
+   * The membership model (`multiTenancy.membershipModel`, default `TenantMember`) is added
+   * automatically and needs no entry — membership is tenant-spanning by design.
+   *
+   * @default []
+   * @example [] // start here; add a model only when you can say why it is global
    */
   excludeSchemas?: string[];
 
@@ -1039,23 +1093,86 @@ export interface IMultiTenancy {
    * @default { member: 1, manager: 2, owner: 3 }
    * @since 11.21.0
    *
+   * SECURITY: never name a tenant role after a GLOBAL role. `RoleEnum.ADMIN` (`'admin'`) and every
+   * other member of `GLOBAL_ONLY_ROLES` is rejected here — a tenant role of that name used to
+   * satisfy `@Roles(RoleEnum.ADMIN)` in tenant context, i.e. a customer could grant themselves
+   * platform authority. Use a tenant-specific name (`tenantAdmin`, `spaceAdmin`) instead, and
+   * declare your own platform-wide roles in {@link globalOnlyRoles}. The boot check refuses a
+   * hierarchy that violates this.
+   *
    * @example
    * ```typescript
    * // config.env.ts
    * multiTenancy: {
-   *   roleHierarchy: { viewer: 1, editor: 2, manager: 2, admin: 3, owner: 4 }
+   *   roleHierarchy: { viewer: 1, editor: 2, manager: 2, tenantAdmin: 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 });
+   * export const HR = createHierarchyRoles({ viewer: 1, editor: 2, manager: 2, tenantAdmin: 3, owner: 4 });
    *
    * // resolver.ts
-   * @Roles(HR.EDITOR) // requires level >= 2 (editor, manager, admin, owner)
+   * @Roles(HR.EDITOR) // requires level >= 2 (editor, manager, tenantAdmin, owner)
    * ```
    */
   roleHierarchy?: Record<string, number>;
 
+  /**
+   * Project-defined roles that carry GLOBAL (platform-wide) authority.
+   *
+   * `RoleEnum.ADMIN` is always treated this way; this option extends the set with your own.
+   * A role listed here is ALWAYS resolved against `user.roles` and NEVER against a tenant
+   * membership role — no matter what the `X-Tenant-Id` header says.
+   *
+   * **Why this matters.** Membership roles are customer-assigned free text, and in tenant context
+   * required roles are otherwise compared against `membership.role`. Without this list, a global
+   * endpoint guarded by `@Roles('auditor')` is reachable by any tenant member whose membership role
+   * happens to be `'auditor'` — granted by their own tenant owner, not by you.
+   *
+   * Declaring a role here is therefore a security statement: "only the platform may grant this".
+   * A role that appears BOTH here and in {@link roleHierarchy} fails the boot check, because it
+   * would have to be resolved against two different sources at once.
+   *
+   * @default [] (only RoleEnum.ADMIN is global)
+   * @since 11.35.0
+   *
+   * @example
+   * ```typescript
+   * multiTenancy: {
+   *   roleHierarchy:   { member: 1, tenantAdmin: 2, owner: 3 },  // per tenant
+   *   globalOnlyRoles: ['auditor', 'support'],                    // platform-wide
+   * }
+   * ```
+   */
+  globalOnlyRoles?: string[];
+
+  /**
+   * Refuse membership roles that are not declared anywhere (deny by default).
+   *
+   * When `true`, `addMember()` / `updateMemberRole()` accept only roles present in
+   * {@link roleHierarchy} or {@link additionalMembershipRoles}. When `false` (default, backward
+   * compatible), any non-reserved string is accepted.
+   *
+   * An undeclared membership role can never GRANT anything either way — the guards only match
+   * declared tenant roles — but with this on, the mistake surfaces as a 400 at assignment time
+   * instead of as a membership that silently authorizes nothing.
+   *
+   * @default false
+   * @since 11.35.0
+   */
+  strictMembershipRoles?: boolean;
+
+  /**
+   * Membership roles that are valid but carry no hierarchy level (exact-match roles).
+   *
+   * Only consulted when {@link strictMembershipRoles} is `true`. Use it for roles like `'auditor'`
+   * that are meaningful per tenant but do not sit in the level ordering.
+   *
+   * @default []
+   * @since 11.35.0
+   */
+  additionalMembershipRoles?: string[];
+
   /**
    * TTL in milliseconds for the tenant guard's in-memory membership cache.
    * The cache avoids repeated DB lookups when the same user accesses the same tenant.
@@ -2210,7 +2327,8 @@ export interface IServerOptions {
    *
    * // Enable with excluded schemas and custom header
    * multiTenancy: {
-   *   excludeSchemas: ['User', 'Session'],
+   *   // excludeSchemas turns isolation OFF per model — see IMultiTenancy.excludeSchemas
+   *   excludeSchemas: [],
    *   headerName: 'x-tenant-id',
    * },
    * ```
@@ -2852,6 +2970,20 @@ export interface IS3Config {
   presignedDownloads?:
     | boolean
     | {
+        /**
+         * Explicitly disable while keeping the settings around — the repo-wide
+         * "presence implies enabled, unless `enabled: false`" pattern.
+         *
+         * It is spelled out in the type because it is REACHABLE WITHOUT THE TYPE: `NEST_SERVER_CONFIG`
+         * and the `NSC__*` variables deliver plain JSON, so `{"enabled": false}` could always be set —
+         * and `CoreS3Service` used to read any object as "enabled", which meant presigned downloads
+         * came on while the boot warning (which does honour the key) stayed silent. Two code paths
+         * answering one question differently is how a bearer-capability download gets switched on by
+         * accident.
+         * @default true (when the config object is present)
+         */
+        enabled?: boolean;
+
         /**
          * Presigned URL validity in seconds.
          *

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

@@ -0,0 +1,193 @@
+import { BadRequestException } from '@nestjs/common';
+
+import { looksLikeSystemRole, SYSTEM_ROLE_PREFIX } from '../enums/role.enum';
+
+/**
+ * Mongoose plugin that refuses to STORE system roles (`s_*`) in a `roles` array.
+ *
+ * **This answers a different question than `mongooseRoleGuardPlugin`, which is why it is a
+ * separate plugin:**
+ *
+ * | Plugin | Question | Configurable | On violation |
+ * |--------|----------|--------------|--------------|
+ * | `mongooseRoleGuardPlugin` | WHO may change roles? | yes (`security.mongooseRoleGuardPlugin`) | strips the change |
+ * | `mongooseSystemRolePlugin` | WHICH values may be stored at all? | **no** | throws |
+ *
+ * Mixing the two would be a mistake in both directions: an ADMIN is allowed to change roles but
+ * still must not be able to store `s_self`, and a bypass (`runWithBypassRoleGuard()` / `force:
+ * true`) grants authority over the *change*, never permission to write a value that is invalid by
+ * construction. So this check runs FIRST and runs ALWAYS — for admins, for bypassed writes, for
+ * system operations with no user context.
+ *
+ * **Why storing one is dangerous:** `hasRole()` is a plain string intersection
+ * (`core-user.model.ts`), so a stored `'s_self'` satisfies every `S_SELF` check — including
+ * `updateUser` / `deleteUser` on ARBITRARY users (mail/password change → account takeover) —
+ * without the account carrying any real role. The rule "NEVER store S_ roles in user.roles" was
+ * documented for years; this is where it became enforced.
+ *
+ * **Why it throws rather than stripping:** silently dropping the value would hide a
+ * misconfiguration in an admin tool, which is exactly how the dormant skeleton key gets minted in
+ * the first place. A loud 400 is recoverable; a silent success is not observable.
+ *
+ * **Why the check is broader than the six `RoleEnum.S_*` members:** it rejects ANY value that
+ * looks like a system role after trimming and lower-casing (see {@link looksLikeSystemRole}).
+ * The framework cannot distinguish a future system role from a project role that happens to start
+ * with `s_`, and a false rejection is fixable by renaming while a false acceptance is a silent
+ * authorization hole. Projects using an `s_`-prefixed role name must rename it — see the
+ * 11.34.x-to-11.35.x migration guide.
+ *
+ * Registered unconditionally in `CoreModule` — unlike the configurable plugins beside it, there is
+ * no opt-out, because there is no legitimate reason to store one of these values.
+ */
+export function mongooseSystemRolePlugin(schema) {
+  schema.pre('save', function () {
+    if (!this.isModified('roles')) {
+      return;
+    }
+    // A NEW document has no stored baseline, so every value in it is being introduced.
+    assertNoSystemRoles(this['roles'], this.isNew ? [] : toRoleArray(this.$__.originalRoles));
+  });
+
+  // Capture the pre-modification value so the save hook above can tell an introduced value from a
+  // pre-existing one. `init` fires when a document is hydrated from the database.
+  schema.post('init', function () {
+    this.$__.originalRoles = Array.isArray(this['roles']) ? [...this['roles']] : undefined;
+  });
+
+  for (const op of ['findOneAndUpdate', 'updateOne', 'replaceOne', 'findOneAndReplace']) {
+    schema.pre(op, async function () {
+      await assertUpdateIntroducesNoSystemRoles(this);
+    });
+  }
+
+  // updateMany can span documents with different stored values, so there is no single baseline to
+  // compare against. Any system role in the update payload is refused outright.
+  schema.pre('updateMany', function () {
+    assertUpdateHasNoSystemRoles(this.getUpdate());
+  });
+
+  schema.pre('insertMany', function (docs) {
+    if (!Array.isArray(docs)) {
+      return;
+    }
+    for (const doc of docs) {
+      assertNoSystemRoles(doc?.roles);
+    }
+  });
+
+  schema.pre('bulkWrite', function (ops) {
+    if (!Array.isArray(ops)) {
+      return;
+    }
+    for (const op of ops) {
+      if ('insertOne' in op) {
+        assertNoSystemRoles(op.insertOne.document?.roles);
+      } else if ('updateOne' in op) {
+        assertUpdateHasNoSystemRoles(op.updateOne.update);
+      } else if ('updateMany' in op) {
+        assertUpdateHasNoSystemRoles(op.updateMany.update);
+      } else if ('replaceOne' in op) {
+        assertNoSystemRoles(op.replaceOne.replacement?.roles);
+      }
+    }
+  });
+}
+
+/** Normalize an unknown value to a string array; anything else becomes an empty baseline. */
+function toRoleArray(value: unknown): string[] {
+  return Array.isArray(value) ? value.filter((entry): entry is string => typeof entry === 'string') : [];
+}
+
+/**
+ * Throw if the write INTRODUCES a system role.
+ *
+ * `alreadyStored` is the document's current value. A system role that is already in there is NOT
+ * refused, and this is load-bearing rather than lenient: `CrudService.update()` writes the whole
+ * object back, so a login (`updateRefreshToken` → `update`) re-sends the stored `roles` verbatim.
+ * Refusing that would lock every already-contaminated account out of the system on upgrade — and
+ * would do the same, fleet-wide, to any project whose own role name happens to start with `s_`.
+ * An upgrade must not cause a login outage; cleaning up stored values is what the migration guide's
+ * audit query is for.
+ *
+ * Accepts anything: a non-array (nothing to check) and non-string elements (cannot be a system
+ * role) pass through untouched — type validation is not this plugin's job.
+ */
+function assertNoSystemRoles(roles: unknown, alreadyStored: string[] = []): void {
+  if (!Array.isArray(roles)) {
+    return;
+  }
+
+  const introduced = roles.filter((role) => looksLikeSystemRole(role) && !alreadyStored.includes(role));
+  if (introduced.length) {
+    throw new BadRequestException(
+      `System roles (${SYSTEM_ROLE_PREFIX}*) must never be stored in user.roles: ${introduced.join(', ')}`,
+    );
+  }
+}
+
+/**
+ * Query-level variant: resolves the affected document's stored roles before deciding.
+ *
+ * The lookup is skipped entirely unless the payload actually carries a system role, so the common
+ * case costs nothing — only a write that is about to be refused pays for one extra read.
+ */
+async function assertUpdateIntroducesNoSystemRoles(query: any): Promise<void> {
+  const update = query.getUpdate();
+  if (!update || !collectRoleValues(update).some((role) => looksLikeSystemRole(role))) {
+    return;
+  }
+
+  // Only now — the payload is suspicious, so the baseline is worth one read.
+  let stored: string[] = [];
+  try {
+    const current = await query.model.findOne(query.getFilter()).select('roles').lean().exec();
+    stored = toRoleArray(current?.roles);
+  } catch {
+    // A failed lookup must not turn into an allow: fall through with an empty baseline, which
+    // refuses the write. Failing closed is correct for an authorization invariant.
+  }
+
+  assertUpdateHasNoSystemRoles(update, stored);
+}
+
+/** Every roles value the update could write, flattened across the operators that can carry one. */
+function collectRoleValues(update: any): unknown[] {
+  const values: unknown[] = [
+    ...toRoleArray(update.roles),
+    ...toRoleArray(update.$set?.roles),
+    ...toRoleArray(update.$setOnInsert?.roles),
+  ];
+
+  for (const operator of [update.$push?.roles, update.$addToSet?.roles]) {
+    if (operator === undefined || operator === null) {
+      continue;
+    }
+    values.push(...(Array.isArray(operator?.$each) ? operator.$each : [operator]));
+  }
+
+  return values;
+}
+
+/**
+ * Check every operator through which a roles value can reach the document.
+ *
+ * `$pull` is deliberately NOT checked — removing an `s_*` value from a document that already has
+ * one is exactly the cleanup this release asks projects to perform, so it must stay possible.
+ */
+function assertUpdateHasNoSystemRoles(update: any, alreadyStored: string[] = []): void {
+  if (!update) {
+    return;
+  }
+
+  assertNoSystemRoles(update.roles, alreadyStored);
+  assertNoSystemRoles(update.$set?.roles, alreadyStored);
+  assertNoSystemRoles(update.$setOnInsert?.roles, alreadyStored);
+
+  // $push / $addToSet take either a bare value or a { $each: [...] } modifier
+  for (const operator of [update.$push?.roles, update.$addToSet?.roles]) {
+    if (operator === undefined || operator === null) {
+      continue;
+    }
+    assertNoSystemRoles(Array.isArray(operator?.$each) ? operator.$each : [operator], alreadyStored);
+  }
+}