@lenne.tech/nest-server 12.0.0 → 12.1.0

package/src/core/common/persistence/neutral-populate.ts

@@ -0,0 +1,98 @@
+import { Logger } from '@nestjs/common';
+
+import { isObjectIdLike } from '../helpers/id.helper.js';
+import type { DataStore } from './data-store.interface.js';
+import { getModelDescriptor } from './model-metadata.registry.js';
+import { getRegisteredDataStore } from './persistence-runtime.registry.js';
+
+/** A populate option as `toPopulateOptions()` yields it */
+export interface NeutralPopulateOption {
+  /** Target model name, when the option overrides the field's `ref` */
+  model?: unknown;
+  path: string;
+  populate?: unknown;
+}
+
+const logger = new Logger('NeutralPopulate');
+
+/**
+ * Populate references of plain records the way Mongoose populate does, for stores without Mongoose documents (plan
+ * §3.6): per reference field, ONE `id $in` read through the target model's store — so its tenant layers, rights and
+ * row check apply to the loaded records as to any other read — then nested options, then the ids are replaced in
+ * place. An unresolved single reference becomes `null`, unresolved items of a reference list are dropped, as with
+ * Mongoose.
+ */
+export async function populateNeutral(
+  data: unknown,
+  options: ReadonlyArray<NeutralPopulateOption | string>,
+  modelName: string,
+): Promise<void> {
+  const records = (Array.isArray(data) ? data : [data]).filter(
+    (record): record is Record<string, any> => !!record && typeof record === 'object',
+  );
+  if (!records.length || !options.length) {
+    return;
+  }
+  const descriptor = getModelDescriptor(modelName);
+  for (const option of options) {
+    const entry = typeof option === 'string' ? { path: option } : option;
+    for (const path of String(entry.path ?? '')
+      .split(/\s+/)
+      .filter(Boolean)) {
+      const field = descriptor?.fields[path];
+      const target = typeof entry.model === 'string' ? entry.model : field?.ref;
+      if (!field || field.kind !== 'ref' || !target) {
+        continue;
+      }
+      const store: DataStore<any> | undefined = getRegisteredDataStore(target);
+      if (!store) {
+        logger.debug(`${modelName}.${path}: no store is registered for "${target}", the reference stays an id`);
+        continue;
+      }
+      const ids = new Set<string>();
+      for (const record of records) {
+        for (const id of idsOf(record[path])) {
+          ids.add(id);
+        }
+      }
+      if (!ids.size) {
+        continue;
+      }
+      const loaded = await store.find({ id: { $in: [...ids] } });
+      if (entry.populate) {
+        await populateNeutral(loaded, toList(entry.populate), target);
+      }
+      const byId = new Map(loaded.map((item) => [String(item.id), item]));
+      for (const record of records) {
+        const value = record[path];
+        if (Array.isArray(value)) {
+          record[path] = value.map((item) => byId.get(idOf(item))).filter((item) => item !== undefined);
+        } else if (value !== undefined && value !== null) {
+          record[path] = byId.get(idOf(value)) ?? null;
+        }
+      }
+    }
+  }
+}
+
+function toList(populate: unknown): Array<NeutralPopulateOption | string> {
+  return (Array.isArray(populate) ? populate : [populate]) as Array<NeutralPopulateOption | string>;
+}
+
+function idOf(value: unknown): string {
+  if (isObjectIdLike(value)) {
+    return value.toHexString();
+  }
+  if (value && typeof value === 'object') {
+    const nested = (value as { _id?: unknown; id?: unknown }).id ?? (value as { _id?: unknown })._id;
+    return String(nested ?? value);
+  }
+  return String(value);
+}
+
+function idsOf(value: unknown): string[] {
+  if (value === undefined || value === null) {
+    return [];
+  }
+  return (Array.isArray(value) ? value : [value]).filter((item) => item !== undefined && item !== null).map(idOf);
+}

package/src/core/common/persistence/persisted-model.decorator.ts

@@ -0,0 +1,61 @@
+/**
+ * Persistence options a model class declares in code.
+ */
+export interface PersistedModelOptions {
+  /**
+   * Name of the data source the model is stored in (a key of `database.sources`). The configuration's
+   * `database.models` wins over this declaration, so operations can move a model without a code change.
+   * @default the default source
+   */
+  dataSource?: string;
+}
+
+const PERSISTED_MODEL_OPTIONS = Symbol('PERSISTED_MODEL_OPTIONS');
+
+/**
+ * Every class decorated with `@PersistedModel`, by class name. `SchemaFactory.createForClass()` keeps no reference to
+ * its class, so a model registered as `{ name, schema }` is matched to its declaration through the name
+ */
+const declaredByName = new Map<string, Function[]>();
+
+/**
+ * Declare where a model is stored.
+ *
+ * @example
+ * ```typescript
+ * @PersistedModel({ dataSource: 'logs' })
+ * @Schema({ timestamps: true })
+ * export class AuditEntry extends CorePersistenceModel { … }
+ * ```
+ */
+export function PersistedModel(options: PersistedModelOptions): ClassDecorator {
+  return (target) => {
+    Reflect.defineMetadata(PERSISTED_MODEL_OPTIONS, { ...options }, target);
+    const classes = declaredByName.get(target.name) ?? [];
+    if (!classes.includes(target)) {
+      declaredByName.set(target.name, [...classes, target]);
+    }
+  };
+}
+
+/** The options a class declared with `@PersistedModel` (inherited from a parent class), if any. */
+export function getPersistedModelOptions(target: Function): PersistedModelOptions | undefined {
+  return Reflect.getMetadata(PERSISTED_MODEL_OPTIONS, target);
+}
+
+/**
+ * The options declared for the model registered under `name` without its class: those of the `@PersistedModel` class
+ * of that name. Two decorated classes of that name that name different sources cannot be told apart — the
+ * registration must pass `model:` (or `dataSource:`) then, so this throws instead of guessing.
+ */
+export function getPersistedModelOptionsByName(name: string): PersistedModelOptions | undefined {
+  const classes = declaredByName.get(name) ?? [];
+  const sources = new Set(classes.map((target) => getPersistedModelOptions(target)?.dataSource));
+  if (sources.size > 1) {
+    throw new Error(
+      `@PersistedModel: ${classes.length} classes named "${name}" declare different data sources; pass \`model\` ` +
+        `(or \`dataSource\`) in CorePersistenceModule.forFeature() to say which one this model is`,
+    );
+  }
+  return classes.length ? getPersistedModelOptions(classes[0]) : undefined;
+}

package/src/core/common/persistence/persistence-runtime.registry.ts

@@ -0,0 +1,152 @@
+/**
+ * Process-wide state of the persistence layer: which models were registered, which store serves each, and the
+ * runtime that routes a model to its data source. Types-only imports — an import-free leaf, so every persistence
+ * file and the services may read it without forming a cycle (see `.claude/rules/architecture.md` → "DI Token
+ * Placement (SWC-Safe)").
+ */
+import type { DataStore } from './data-store.interface.js';
+import type { LockStore } from './lock-store.interface.js';
+
+/** A model as `CorePersistenceModule.forFeature()` registered it */
+export interface PersistedModelRegistration {
+  /** The source the model class declares with `@PersistedModel`, or the definition's `dataSource` */
+  declaredSource?: string;
+  name: string;
+  /** The model's Mongoose schema */
+  schema: unknown;
+}
+
+/**
+ * Routes a model to the store of its data source (plan §3.9). Installed by `CoreModule.forRoot()` when the
+ * configuration names a SQL source; without one, every model keeps its Mongoose store.
+ */
+export interface PersistenceRuntime {
+  close(): Promise<void>;
+  /** The lease store of the default source when it is a SQL database; `undefined` when it is MongoDB */
+  defaultLockStore(): Promise<LockStore | undefined>;
+  /** Closes what only the boot needs (the owner connections that migrate the schema), once every store exists */
+  releaseBootConnections(): Promise<void>;
+  /** The store of a model; `mongoModel` is its Mongoose model, used when the model stays on MongoDB */
+  resolveStore(name: string, mongoModel: unknown): Promise<DataStore<any>>;
+  /** The configured SQL sources, each with a ping (`SELECT 1` on its application connection) for the health check */
+  sqlSources(): { name: string; ping: () => Promise<void> }[];
+  /** The default source when it is a SQL database — where the framework keeps its migration state */
+  defaultSqlSource(): undefined | { engine?: string; ownerUrl?: string; url: string };
+  /** Sources and model routing for the Hub; connection URLs reduced to scheme and host */
+  describe(): PersistenceOverview;
+  /**
+   * Delete the rows whose TTL has passed, in every SQL table this application opened — what MongoDB's TTL monitor does
+   * for a collection. Answers per model with a TTL field how many rows went
+   */
+  sweepExpired(now?: Date): Promise<{ deleted: number; model: string }[]>;
+  /**
+   * Where Better-Auth keeps its data: the SQL source the `users` table is routed to, or `undefined` when the user model
+   * stays on MongoDB. Better-Auth and the user model share one row per user, so Better-Auth never decides this itself
+   */
+  iamStorage(): Promise<IamSqlStorage | undefined>;
+}
+
+/** The SQL source Better-Auth runs on — the one the `users` table lives in */
+export interface IamSqlStorage {
+  /**
+   * Bring the tables Better-Auth owns up to date. With the owner configured, `migrate` receives the OWNER's pool and runs
+   * while the framework's schema lock is held; the application role is then granted on `tables` and checked like on the
+   * framework's own tables. Without `ownerUrl`, `migrate` receives the application pool and must only verify.
+   */
+  applySchema(migrate: (pool: unknown, asOwner: boolean) => Promise<void>, tables: string[]): Promise<void>;
+  /** The application role's `pg` pool of that source — Better-Auth's own adapter runs on it */
+  pool: unknown;
+  /** Name of the data source */
+  source: string;
+  /** The store of the user model */
+  users: DataStore<any>;
+}
+
+/** What the data-source configuration resolved to, for operators (the Hub's persistence panel) */
+export interface PersistenceOverview {
+  defaultSource?: string;
+  models: { name: string; source?: string }[];
+  sources: { driver: string; engine?: string; host: string; name: string; ownerConfigured: boolean }[];
+}
+
+const models = new Map<string, PersistedModelRegistration>();
+/** Columns another library keeps in a framework table (Better-Auth's on `users`), per table */
+const foreignColumns = new Map<string, Set<string>>();
+const stores = new Map<string, DataStore<any>>();
+/**
+ * The store serving a model, keyed by the Mongoose model INSTANCE. Every application has its own connection and
+ * therefore its own model instances, so this lookup — unlike the by-name map above — can never hand one application
+ * the store another one (in the same process: tests) created.
+ */
+const storesByModel = new WeakMap<object, DataStore<any>>();
+let runtime: PersistenceRuntime | undefined;
+
+export function registerPersistedModel(registration: PersistedModelRegistration): void {
+  models.set(registration.name, registration);
+}
+
+export function getPersistedModels(): PersistedModelRegistration[] {
+  return [...models.values()];
+}
+
+/**
+ * Declare columns another library adds to a framework table: no field of the model declares them, but they are not
+ * left-overs of a removed field either — the schema evolution does not report them at every boot
+ */
+export function registerForeignColumns(table: string, columns: readonly string[]): void {
+  const known = foreignColumns.get(table) ?? new Set<string>();
+  columns.forEach((column) => known.add(column));
+  foreignColumns.set(table, known);
+}
+
+export function isForeignColumn(table: string, column: string): boolean {
+  return foreignColumns.get(table)?.has(column) ?? false;
+}
+
+/** Remember the store serving a model — the neutral populate loads references through it */
+export function registerDataStore(name: string, store: DataStore<any>): void {
+  stores.set(name, store);
+}
+
+export function getRegisteredDataStore(name: string): DataStore<any> | undefined {
+  return stores.get(name);
+}
+
+/**
+ * The store serving a model, for a service that holds the MongoDB connection: through the connection's Mongoose model
+ * while MongoDB is connected, by name without one (PostgreSQL alone, or `database: false`) — the store registered for
+ * the model is then the only one there is
+ */
+export function getModelStore(
+  connection: { models?: Record<string, unknown> } | null | undefined,
+  name: string,
+): DataStore<any> | undefined {
+  if (!connection) {
+    return getRegisteredDataStore(name);
+  }
+  const model = connection.models?.[name];
+  return model ? getStoreForModel(model) : undefined;
+}
+
+/**
+ * Remember which store serves the model behind a Mongoose model instance, so a service written against
+ * `@InjectModel()` runs on the store its model was routed to
+ */
+export function bindStoreToModel(model: unknown, store: DataStore<any>): void {
+  if (model && typeof model === 'function') {
+    storesByModel.set(model, store);
+  }
+}
+
+/** The store routed for the model behind this Mongoose model instance, when one was registered */
+export function getStoreForModel(model: unknown): DataStore<any> | undefined {
+  return model && typeof model === 'function' ? storesByModel.get(model) : undefined;
+}
+
+export function setPersistenceRuntime(value: PersistenceRuntime | undefined): void {
+  runtime = value;
+}
+
+export function getPersistenceRuntime(): PersistenceRuntime | undefined {
+  return runtime;
+}

package/src/core/common/persistence/persistence.tokens.ts

@@ -0,0 +1,9 @@
+/**
+ * DI tokens of the persistence layer. Import-free leaf — see `.claude/rules/architecture.md`
+ * → "DI Token Placement (SWC-Safe)".
+ */
+
+/** Injection token of the data store of a model, by model name. */
+export function getStoreToken(modelName: string): string {
+  return `DataStore:${modelName}`;
+}

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

@@ -0,0 +1,80 @@
+import { RequestContext } from '../../services/request-context.service.js';
+
+/**
+ * Audit-field decisions (`createdBy` / `updatedBy`), shared by every data store.
+ *
+ * `mongooseAuditFieldsPlugin` applies them to Mongoose documents and update objects; a SQL store applies
+ * the same functions to its rows and patches. Update objects use the Mongo-operator form (`$set`,
+ * `$setOnInsert`), which is also the neutral update language of the data store port.
+ */
+
+/** Which audit fields a model stores. */
+export interface AuditFieldPresence {
+  createdBy: boolean;
+  updatedBy: boolean;
+}
+
+/**
+ * The id the audit fields are stamped with: the current user's. `undefined` for system work (no
+ * user context: seeding, cron, migrations) — the fields are then left as they are.
+ */
+export function resolveAuditActorId(): string | undefined {
+  return RequestContext.getCurrentUser()?.id || undefined;
+}
+
+/**
+ * Stamp a document that is being written whole (create, or save of an existing document):
+ * `createdBy` only on a NEW document that does not carry one yet, `updatedBy` always.
+ */
+export function stampAuditOnWrite(
+  doc: Record<string, any>,
+  actorId: string,
+  fields: AuditFieldPresence,
+  isNew: boolean,
+): void {
+  if (fields.createdBy && isNew && !doc['createdBy']) {
+    doc['createdBy'] = actorId;
+  }
+  if (fields.updatedBy) {
+    doc['updatedBy'] = actorId;
+  }
+}
+
+/**
+ * Stamp an update object: `updatedBy` flat and inside `$set`, and `createdBy` via `$setOnInsert` for
+ * the upsert case — unless the update already sets `createdBy`, which would make the two operators
+ * collide on one path.
+ */
+export function stampAuditOnUpdate(update: Record<string, any>, actorId: string, fields: AuditFieldPresence): void {
+  if (fields.updatedBy) {
+    update['updatedBy'] = actorId;
+    if (update.$set) {
+      update.$set['updatedBy'] = actorId;
+    }
+  }
+  if (fields.createdBy && !update['createdBy'] && !update.$set?.['createdBy']) {
+    if (!update.$setOnInsert) {
+      update.$setOnInsert = {};
+    }
+    if (!update.$setOnInsert['createdBy']) {
+      update.$setOnInsert['createdBy'] = actorId;
+    }
+  }
+}
+
+/**
+ * Stamp a replacement document (no operators): `updatedBy`, and `createdBy` when absent — for the
+ * upsert case, where the replacement becomes a new document.
+ */
+export function stampAuditOnReplace(
+  replacement: Record<string, any>,
+  actorId: string,
+  fields: AuditFieldPresence,
+): void {
+  if (fields.updatedBy) {
+    replacement['updatedBy'] = actorId;
+  }
+  if (fields.createdBy && !replacement['createdBy']) {
+    replacement['createdBy'] = actorId;
+  }
+}

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

@@ -0,0 +1,69 @@
+import bcrypt from 'bcrypt';
+import { sha256 } from 'js-sha256';
+
+import { ConfigService } from '../../services/config.service.js';
+
+/**
+ * Password hashing decisions, shared by every data store: a plaintext password never reaches storage,
+ * whichever API wrote it. `mongoosePasswordPlugin` applies them to Mongoose writes; a SQL store applies
+ * the same functions to its rows and patches.
+ */
+
+export async function hashUpdatePassword(update: any) {
+  if (!update) {
+    return;
+  }
+  if (update.password) {
+    update.password = await hashPassword(update.password);
+  }
+  if (update.$set?.password) {
+    update.$set.password = await hashPassword(update.$set.password);
+  }
+}
+
+// Compiled RegExp cache (built once on first call)
+let compiledSkipPatterns: RegExp[] | null = null;
+
+/**
+ * Reset the compiled skip patterns cache.
+ * Use in test environments where ConfigService is reset between test suites.
+ */
+export function resetSkipPatternsCache(): void {
+  compiledSkipPatterns = null;
+}
+
+function getSkipPatterns(): RegExp[] {
+  if (compiledSkipPatterns !== null) {
+    return compiledSkipPatterns;
+  }
+  const pluginConfig = ConfigService.configFastButReadOnly?.security?.mongoosePasswordPlugin;
+  if (pluginConfig && typeof pluginConfig === 'object' && 'skipPatterns' in pluginConfig && pluginConfig.skipPatterns) {
+    compiledSkipPatterns = (pluginConfig.skipPatterns as (string | RegExp)[]).map((p) =>
+      p instanceof RegExp ? p : new RegExp(p),
+    );
+  } else {
+    compiledSkipPatterns = [];
+  }
+  return compiledSkipPatterns;
+}
+
+export async function hashPassword(password: string): Promise<string> {
+  // Already BCrypt-hashed → skip
+  if (/^\$2[aby]\$\d+\$/.test(password)) {
+    return password;
+  }
+
+  // Check configured skip patterns (e.g. sentinel/lock values)
+  const skipPatterns = getSkipPatterns();
+  if (skipPatterns.some((pattern) => pattern.test(password))) {
+    return password;
+  }
+
+  // SHA256 pre-hash if configured and password is not already SHA256
+  const sha256Enabled = ConfigService.configFastButReadOnly?.sha256;
+  if (sha256Enabled && !/^[a-f0-9]{64}$/i.test(password)) {
+    password = sha256(password);
+  }
+
+  return bcrypt.hash(password, 10);
+}

package/src/core/common/persistence/policies/role-guard.policy.ts

@@ -0,0 +1,74 @@
+import { RoleEnum } from '../../enums/role.enum.js';
+import { ConfigService } from '../../services/config.service.js';
+import { RequestContext } from '../../services/request-context.service.js';
+
+/**
+ * Role-assignment decisions (who may change `roles`), shared by every data store.
+ *
+ * `mongooseRoleGuardPlugin` applies them to Mongoose documents and update objects; a SQL store applies
+ * the same functions to its writes. This answers WHO may change roles (configurable, bypassable, strips
+ * the change); which VALUES may exist at all is the system-role policy's question.
+ */
+
+/**
+ * Check if the current user is allowed to modify roles.
+ * Returns true if:
+ * - No user context (system operation)
+ * - bypassRoleGuard is active (via RequestContext.runWithBypassRoleGuard())
+ * - User has ADMIN role
+ * - User has one of the configured allowedRoles
+ */
+export function isRoleChangeAllowed(): boolean {
+  const currentUser = RequestContext.getCurrentUser();
+  // No user context (system operation) → allow
+  if (!currentUser) {
+    return true;
+  }
+  // Explicit bypass (e.g. signUp with default roles, authorized service operations)
+  if (RequestContext.isBypassRoleGuard()) {
+    return true;
+  }
+  // Admin → always allow
+  if (currentUser.hasRole?.([RoleEnum.ADMIN]) || currentUser.roles?.includes(RoleEnum.ADMIN)) {
+    return true;
+  }
+
+  // Check configured allowedRoles
+  const pluginConfig = ConfigService.configFastButReadOnly?.security?.mongooseRoleGuardPlugin;
+  if (pluginConfig && typeof pluginConfig === 'object' && 'allowedRoles' in pluginConfig && pluginConfig.allowedRoles) {
+    const allowedRoles: string[] = pluginConfig.allowedRoles as string[];
+    if (currentUser.roles?.some((role: string) => allowedRoles.includes(role))) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+/** Whether an update object (flat or with operators) touches `roles`. */
+export function updateChangesRoles(update: any): boolean {
+  return !!(
+    update?.roles ||
+    update?.$set?.roles ||
+    update?.$push?.roles ||
+    update?.$addToSet?.roles ||
+    update?.$pull?.roles
+  );
+}
+
+/** Remove every change to `roles` from an update object, in all operator forms. */
+export function stripRoleChanges(update: any): void {
+  delete update.roles;
+  if (update.$set?.roles) {
+    delete update.$set.roles;
+  }
+  if (update.$push?.roles) {
+    delete update.$push.roles;
+  }
+  if (update.$addToSet?.roles) {
+    delete update.$addToSet.roles;
+  }
+  if (update.$pull?.roles) {
+    delete update.$pull.roles;
+  }
+}

package/src/core/common/persistence/policies/system-role.policy.ts

@@ -0,0 +1,90 @@
+import { BadRequestException } from '@nestjs/common';
+
+import { looksLikeSystemRole, SYSTEM_ROLE_PREFIX } from '../../enums/role.enum.js';
+
+/**
+ * System-role decisions (which role VALUES may be stored at all), shared by every data store.
+ *
+ * `mongooseSystemRolePlugin` applies them to Mongoose writes; a SQL store applies the same functions and
+ * backs them with a `CHECK` constraint. Unconditional by design: being ADMIN or holding a bypass is
+ * authority over a role change, never permission to store a value that is invalid by construction.
+ */
+
+/** Normalize an unknown value to a string array; anything else becomes an empty baseline. */
+export 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.
+ */
+export 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(', ')}`,
+    );
+  }
+}
+
+/** Whether an update object carries a system role in any operator form — the cheap pre-check before a baseline read. */
+export function updateMayIntroduceSystemRoles(update: any): boolean {
+  return collectRoleValues(update).some((role) => looksLikeSystemRole(role));
+}
+
+/** Every roles value the update could write, flattened across the operators that can carry one. */
+export 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.
+ */
+export 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);
+  }
+}