@lenne.tech/nest-server 11.34.1 → 11.35.1

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);
+  }
+}