@lenne.tech/nest-server 11.34.1 → 11.35.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nest-server",
-  "version": "11.34.1",
+  "version": "11.35.0",
   "description": "Modern, fast, powerful Node.js web framework in TypeScript based on Nest with a GraphQL API and a connection to MongoDB (or other databases).",
   "keywords": [
     "node",

package/src/core/common/decorators/nested-type.registry.ts

@@ -0,0 +1,42 @@
+/**
+ * Which CLASS a model property declares — the only record of that fact at runtime.
+ *
+ * DELIBERATELY IMPORT-FREE. Two files need this map and they sit on opposite ends of an import
+ * edge: `unified-field.decorator` writes it (and already imports `restricted.decorator` for
+ * `@Restricted`), while `restricted.decorator` reads it. Keeping the map here means the reader adds
+ * no import back into the writer — `restricted.decorator` drives field-level access control and its
+ * position on zero import cycles is a defended property, not an accident.
+ * See `.claude/rules/architecture.md` → "DI Token Placement (SWC-Safe)".
+ *
+ * WHY IT EXISTS AT ALL: TypeScript types are erased, and `design:type` degrades to `Array` for a
+ * typed array and is only emitted for decorated properties. So a nested value read out of MongoDB —
+ * an embedded subdocument, or an array of them — arrives as a PLAIN object whose constructor is
+ * `Object`. Nothing on the value itself can say what it was declared as, which means nothing can
+ * find the `@Restricted` / validation metadata that belongs to it. This map is what closes that gap.
+ *
+ * Filled by `@UnifiedField()` for every non-primitive property. A property declared without
+ * `@UnifiedField` is absent, and consumers must treat "absent" as "unknown", never as "no
+ * restrictions" — see `checkRestricted()` for how that is handled.
+ */
+
+/** Key: `${className}.${propertyName}` — value: the declared (element) type. */
+export const nestedTypeRegistry = new Map<string, any>();
+
+/**
+ * The class a property of `ownerClass` declares, or `undefined` when nothing recorded it.
+ *
+ * Walks the PROTOTYPE CHAIN of the class, because `@UnifiedField()` registers under the class it was
+ * applied to — a property inherited from a base model is recorded under the BASE class name, and a
+ * lookup that only tried the leaf would miss it.
+ */
+export function resolveNestedType(ownerClass: unknown, propertyKey: string): any {
+  let current: any = ownerClass;
+  while (current && current !== Object && typeof current === 'function') {
+    const found = nestedTypeRegistry.get(`${current.name}.${propertyKey}`);
+    if (found) {
+      return found;
+    }
+    current = Object.getPrototypeOf(current);
+  }
+  return undefined;
+}

package/src/core/common/decorators/restricted.decorator.ts

@@ -22,17 +22,37 @@
  * See .claude/rules/architecture.md → "DI Token Placement (SWC-Safe)".
  */
 import 'reflect-metadata';
+import { Logger } from '@nestjs/common';
 import _ = require('lodash');
 
 import { ProcessType } from '../enums/process-type.enum';
-import { RoleEnum } from '../enums/role.enum';
+// isSystemRole comes from the role.enum LEAF (import-free), not from core-tenant.helpers, so this
+// adds no new import edge to a file whose TDZ-immunity is a deliberate safety property.
+import { isSystemRole, RoleEnum } from '../enums/role.enum';
 import { accessDeniedException } from '../exceptions/access-denied.exception';
+// From the import-free LEAF, never from unified-field.decorator: that file imports THIS one for
+// `@Restricted`, so reading the map from there would put this file back on an import cycle.
+import { resolveNestedType } from './nested-type.registry';
+// From an import-free LEAF: the marker is read here and in both interceptors, and this file's
+// position on zero import cycles is a defended property.
+import {
+  hasRestrictionsCheckedMarker,
+  hasUnrecognizedRestrictionsFlag,
+  RESTRICTIONS_CHECKED_KEY,
+} from './restrictions-checked.marker';
 // Import from the id.helper LEAF, never from db.helper: db.helper imports input.helper, which
 // imports this file back — that cycle is what the extraction removed. See id.helper's docblock.
 import { equalIds, getIncludedIds } from '../helpers/id.helper';
 import { RequestContext } from '../services/request-context.service';
 import { RequireAtLeastOne } from '../types/required-at-least-one.type';
-import { checkRoleAccess } from '../../modules/tenant/core-tenant.helpers';
+import { checkRoleAccess, resolveGlobalAndTenantRoles } from '../../modules/tenant/core-tenant.helpers';
+
+export {
+  hasRestrictionsCheckedMarker,
+  hasUnrecognizedRestrictionsFlag,
+  markRestrictionsChecked,
+  RESTRICTIONS_CHECKED_KEY,
+} from './restrictions-checked.marker';
 
 /**
  * Restricted meta key
@@ -121,6 +141,66 @@ export function getRestricted(object: unknown, propertyKey?: string): Restricted
   return metadata;
 }
 
+/**
+ * Resolve the NON-system portion of a field's required roles against the requester.
+ *
+ * Two things must be filtered before the roles reach `checkRoleAccess`, because that function
+ * matches non-hierarchy roles by exact string against a SINGLE available role — the tenant
+ * membership role, when a tenant context is active:
+ *
+ * 1. **System roles.** `S_SELF`, `S_CREATOR`, `S_VERIFIED`, `S_USER` and `S_EVERYONE` are decided
+ *    by the dedicated checks in `checkRestricted` (ownership, verification, session). Passing them
+ *    on means a membership role literally named `'s_self'` satisfies `@Restricted(S_SELF)` on
+ *    ARBITRARY records — no ownership is ever compared. `CoreTenantGuard` already filters these at
+ *    its own call site; this is the same filter for the field-level path.
+ *
+ * 2. **Global-only roles.** `RoleEnum.ADMIN` is platform authority and must be answered from
+ *    `user.roles`, never from a customer-assigned membership role.
+ *
+ * Declared as a hoisted `function` so it stays temporal-dead-zone immune — this file sits on no
+ * import cycle today and the property is defended deliberately (see `.claude/rules/architecture.md`).
+ */
+function checkFieldRoleAccess(roles: string[], user: any): boolean {
+  const { global: globalRoles, tenant: tenantRoles } = resolveGlobalAndTenantRoles(
+    roles.filter((role) => !isSystemRole(role)),
+  );
+
+  if (globalRoles.some((role) => user?.roles?.includes(role))) {
+    return true;
+  }
+
+  // The length guard is NOT redundant: checkRoleAccess returns TRUE for an empty required-roles
+  // list, so calling it with no tenant roles would unlock a field that only required a global one.
+  return tenantRoles.length > 0 && checkRoleAccess(tenantRoles, user?.roles, RequestContext.get()?.tenantRole);
+}
+
+/** Emitted at most once per process — a per-object warning on a hot path would be noise, not signal. */
+let unrecognizedFlagWarned = false;
+
+/**
+ * Warn once when an object carries `_objectAlreadyCheckedForRestrictions` without the framework marker.
+ *
+ * Declared as a hoisted `function` like everything else in this file, so it stays temporal-dead-zone
+ * immune. Uses the Nest `Logger` rather than `console.warn` for two reasons: it is the convention every
+ * other framework warning follows, and `console` output from a hot path is forwarded over vitest's
+ * worker RPC — a late one produces `Closing rpc while "onUserConsoleLog" was pending` in whichever
+ * spec happens to be tearing down. `@nestjs/common` is an external package and already in this file's
+ * transitive graph via `accessDeniedException`, so it adds no project import edge.
+ */
+function warnUnrecognizedRestrictionsFlag(data: unknown): void {
+  if (unrecognizedFlagWarned || !hasUnrecognizedRestrictionsFlag(data)) {
+    return;
+  }
+  unrecognizedFlagWarned = true;
+  new Logger('Restricted').warn(
+    `[Restricted] An object carries "${RESTRICTIONS_CHECKED_KEY}" without the framework marker, so it ` +
+      'is being CHECKED rather than skipped. Since 11.35.0 the opt-out is only honoured for objects ' +
+      'marked via markRestrictionsChecked() — a plain truthy property could arrive from the database ' +
+      'or a payload and would switch off field-level access control. If you set it deliberately, call ' +
+      'markRestrictionsChecked(obj); if this came from stored data, remove the field.',
+  );
+}
+
 /**
  * Check data for restricted properties (properties with `Restricted` decorator)
  * For special Roles and member of group checking the dbObject must be set in options
@@ -150,6 +230,7 @@ export function checkRestricted(
     throwError?: boolean;
   } = {},
   processedObjects: WeakSet<object> = new WeakSet(),
+  declaredType?: any,
 ) {
   // Act like Roles handling: checkObjectItself = false & mergeRoles = true
   // For Input: throwError = true
@@ -168,16 +249,52 @@ export function checkRestricted(
   };
 
   // Primitives
-  if (!data || typeof data !== 'object' || (config.noteCheckedObjects && data._objectAlreadyCheckedForRestrictions)) {
+  // The "already checked" opt-out is recognised by the framework's MARKER, never by a truthy property
+  // of that name: nothing in src/ ever wrote the property, so a truthy one could only have come from
+  // outside — and a document carrying it disabled every field-level check for that object, silently,
+  // on the output path. See restrictions-checked.marker.ts.
+  if (!data || typeof data !== 'object' || (config.noteCheckedObjects && hasRestrictionsCheckedMarker(data))) {
     return data;
   }
 
+  // Say it out loud when the KEY is present without the marker. Two very different callers land here
+  // and they want opposite answers — a project that used to set the flag by hand has lost its opt-out,
+  // a document that carries it from a raw write has lost a bypass it should never have had. A warning
+  // states the situation without guessing which; honouring the value is what the marker exists to stop.
+  warnUnrecognizedRestrictionsFlag(data);
+
   // Prevent infinite recursion
   if (processedObjects.has(data)) {
     return data;
   }
   processedObjects.add(data);
 
+  // WHERE the restriction metadata for `data` lives.
+  //
+  // For an instance of a model class this is simply its constructor, and reading it off the object
+  // works — which is why the top level has always been checked correctly. One level down it stops
+  // working: `CoreModel.map()` is a shallow `Object.assign`, `prepareOutput()` maps only the target
+  // model, and `ResponseModelInterceptor` maps only the top-level item. So an embedded subdocument
+  // read out of MongoDB arrives as a PLAIN object whose constructor is `Object` — and `Object`
+  // carries no `@Restricted` metadata, so every nested restriction silently evaluated to "no
+  // restrictions at all" and the field was returned in full. `declaredType` closes that: the type
+  // the PARENT declared for this property, looked up in the nested-type registry.
+  //
+  // An unregistered nested type still resolves to nothing, exactly as before — the framework cannot
+  // invent a declaration. That is deliberate rather than fail-closed: nested values also legitimately
+  // hold free-form JSON, `Map`s and scalars, and refusing those would break far more than it
+  // protects. Declare nested types with `@UnifiedField({ type: () => X })` to have them enforced.
+  const metadataOwner: any =
+    data.constructor && data.constructor !== Object
+      ? data.constructor
+      : typeof declaredType === 'function'
+        ? declaredType
+        : undefined;
+  // What `Reflect.getMetadata` must walk for PROPERTY lookups: the instance when there is one, the
+  // declared class's prototype otherwise (metadata for property decorators is defined there, and
+  // Reflect traverses the prototype chain either way).
+  const metadataTarget: any = !metadataOwner || data.constructor === metadataOwner ? data : metadataOwner.prototype;
+
   // Array
   if (Array.isArray(data)) {
     if (data.length === 0) {
@@ -189,15 +306,18 @@ export function checkRestricted(
     // Per-item checks are only needed when S_CREATOR or S_SELF restrictions exist
     // (because createdBy/id differ per item).
     const sample = data[0];
-    if (
-      sample &&
-      typeof sample === 'object' &&
-      !Array.isArray(sample) &&
-      sample.constructor &&
-      sample.constructor !== Object
-    ) {
+    // The element type: the sample's own class, or — for an array of embedded subdocuments, which
+    // arrive as plain objects — the type the parent property declared. `declaredType` is the ELEMENT
+    // type here: `@UnifiedField({ isArray: true, type: () => X })` registers `X`, not `X[]`.
+    const sampleOwner: any =
+      sample && typeof sample === 'object' && !Array.isArray(sample) && sample.constructor !== Object
+        ? sample.constructor
+        : typeof declaredType === 'function'
+          ? declaredType
+          : undefined;
+    if (sample && typeof sample === 'object' && !Array.isArray(sample) && sampleOwner) {
       // Check class-level restrictions once
-      const classRestrictions = getRestricted(sample.constructor) || [];
+      const classRestrictions = getRestricted(sampleOwner) || [];
       if (classRestrictions.length) {
         const hasCreatorOrSelf = classRestrictions.some(
           (r) =>
@@ -223,7 +343,7 @@ export function checkRestricted(
           // also validates the class-level restriction as a standalone gate. With the
           // default checkObjectItself=false, class restrictions are merged into each
           // property's restrictions (properties get stripped if the class restriction denies).
-          const sampleResult = checkRestricted(sample, user, config, processedObjects);
+          const sampleResult = checkRestricted(sample, user, config, processedObjects, declaredType);
           if (sampleResult === undefined || sampleResult === null) {
             // Class-level restriction blocks access → entire array is blocked
             if (config.throwError) {
@@ -236,7 +356,7 @@ export function checkRestricted(
           // are O(1) lookups, but we still need to recurse into nested properties per item.
           const result = [sampleResult];
           for (let i = 1; i < data.length; i++) {
-            result.push(checkRestricted(data[i], user, config, processedObjects));
+            result.push(checkRestricted(data[i], user, config, processedObjects, declaredType));
           }
           if (!config.throwError && config.removeUndefinedFromResultArray) {
             return result.filter((item) => item !== undefined);
@@ -247,7 +367,7 @@ export function checkRestricted(
     }
 
     // Fallback: plain objects, mixed types, or S_CREATOR/S_SELF checks needed
-    let result = data.map((item) => checkRestricted(item, user, config, processedObjects));
+    let result = data.map((item) => checkRestricted(item, user, config, processedObjects, declaredType));
     if (!config.throwError && config.removeUndefinedFromResultArray) {
       result = result.filter((item) => item !== undefined);
     }
@@ -256,7 +376,7 @@ export function checkRestricted(
 
   // Check function
   const validateRestricted = (restricted) => {
-    if (config.noteCheckedObjects && data?._objectAlreadyCheckedForRestrictions) {
+    if (config.noteCheckedObjects && hasRestrictionsCheckedMarker(data)) {
       return true;
     }
 
@@ -320,7 +440,7 @@ export function checkRestricted(
           ((owner && 'createdBy' in owner && equalIds(owner.createdBy, user)) ||
             (config.allowCreatorOfParent && owner && !('createdBy' in owner) && config.isCreatorOfParent))) ||
         (roles.includes(RoleEnum.S_VERIFIED) && (user?.verified || user?.verifiedAt || user?.emailVerified)) ||
-        (user?.id && checkRoleAccess(roles, user?.roles, RequestContext.get()?.tenantRole))
+        (user?.id && checkFieldRoleAccess(roles, user))
       ) {
         valid = true;
       }
@@ -375,7 +495,7 @@ export function checkRestricted(
   };
 
   // Check data object
-  const objectRestrictions = getRestricted(data.constructor) || [];
+  const objectRestrictions = getRestricted(metadataOwner) || [];
   if (config.checkObjectItself) {
     const objectIsValid = validateRestricted(objectRestrictions);
     if (!objectIsValid) {
@@ -403,8 +523,9 @@ export function checkRestricted(
       continue;
     }
 
-    // Check restricted
-    const restricted = getRestricted(data, propertyKey) || [];
+    // Check restricted. `metadataTarget` is `data` for a real instance and the declared class's
+    // prototype for a plain nested object — see its definition above.
+    const restricted = getRestricted(metadataTarget, propertyKey) || [];
     const concatenatedRestrictions =
       config.mergeRoles && objectRestrictions.length ? _.uniq(objectRestrictions.concat(restricted)) : restricted;
     const valid = validateRestricted(concatenatedRestrictions);
@@ -420,8 +541,15 @@ export function checkRestricted(
         equalIds(parent, user) ||
         (parent && 'createdBy' in parent ? equalIds(parent.createdBy, user) : config.isCreatorOfParent);
 
-      // Check deep
-      data[propertyKey] = checkRestricted(data[propertyKey], user, config, processedObjects);
+      // Check deep — carrying the type this property DECLARES, so a nested plain object (an
+      // embedded subdocument, or an array of them) can still be matched against its own metadata.
+      data[propertyKey] = checkRestricted(
+        data[propertyKey],
+        user,
+        config,
+        processedObjects,
+        metadataOwner ? resolveNestedType(metadataOwner, propertyKey) : undefined,
+      );
     } else {
       if (config.debug) {
         console.debug(

package/src/core/common/decorators/restrictions-checked.marker.ts

@@ -0,0 +1,87 @@
+/**
+ * "This object has already been checked" — as a MARKER the framework sets, not a property data carries.
+ *
+ * WHY THIS FILE EXISTS: three places short-circuit on
+ * `_objectAlreadyCheckedForRestrictions` — `checkRestricted()` returns the object untouched,
+ * `CheckSecurityInterceptor` skips `securityCheck()`, and `ResponseModelInterceptor` skips the
+ * Plain→Model conversion. The opt-out is legitimate: without it one response is checked three times.
+ *
+ * What was NOT legitimate is how it was recognised. Every read was a plain truthy test on a
+ * well-known property name, and nothing in `src/` ever wrote it — so the only way the flag could ever
+ * be set was from outside the framework. Which means a document carrying
+ * `_objectAlreadyCheckedForRestrictions: true` — from a raw write, a `strict: false` schema, a
+ * restored export — disabled EVERY field-level access check for that object, silently, on the output
+ * path where a skipped check produces no error at all. That is a data-shaped authorization switch,
+ * and data must never be able to flip one.
+ *
+ * The fix keeps the feature and removes the forgeability: the marker's VALUE is a module-private
+ * symbol. JSON, BSON and any client payload can produce the key, and none of them can produce that
+ * value. The property is also non-enumerable, so it never reaches a response body and cannot re-enter
+ * through a round trip as exactly the data shape above.
+ *
+ * DELIBERATELY IMPORT-FREE, so `restricted.decorator` (whose position on zero import cycles is a
+ * defended property) and both interceptors can read it without a new import edge between them.
+ * See `.claude/rules/architecture.md` → "DI Token Placement (SWC-Safe)".
+ */
+
+/**
+ * The property name, unchanged since it is part of the observable API — a project may look for it.
+ * Only the way it is RECOGNISED changed.
+ */
+export const RESTRICTIONS_CHECKED_KEY = '_objectAlreadyCheckedForRestrictions';
+
+/**
+ * The only value that counts as "checked". Module-private on purpose: it is not exported, so nothing
+ * outside this file — and nothing that arrives as data — can reproduce it.
+ */
+const MARKER = Symbol('restrictionsChecked');
+
+/**
+ * Mark an object as already checked, so the framework's own layers do not check it again.
+ *
+ * Non-enumerable and non-writable: it must not appear in `Object.keys()`, in `JSON.stringify()` or in
+ * a Mongoose write. `configurable: true` so the same object can be re-marked without throwing.
+ *
+ * Returns the object, so it can be used inline.
+ */
+export function markRestrictionsChecked<T>(data: T): T {
+  if (!data || typeof data !== 'object') {
+    return data;
+  }
+  Object.defineProperty(data, RESTRICTIONS_CHECKED_KEY, {
+    configurable: true,
+    enumerable: false,
+    value: MARKER,
+    writable: false,
+  });
+  return data;
+}
+
+/**
+ * Has the framework marked this object as checked?
+ *
+ * The identity comparison is the whole point — `!!data[KEY]` would be satisfied by any truthy value,
+ * including one that came out of the database.
+ */
+export function hasRestrictionsCheckedMarker(data: unknown): boolean {
+  return !!data && typeof data === 'object' && (data as Record<string, unknown>)[RESTRICTIONS_CHECKED_KEY] === MARKER;
+}
+
+/**
+ * Does this object carry the KEY without the marker — i.e. an unforgeable-looking value that is not
+ * actually the marker?
+ *
+ * Used to warn once rather than to decide anything. Two callers can produce this state, and they want
+ * opposite answers: a project that used to set the flag by hand (`obj[KEY] = true`) has silently lost
+ * its opt-out and should hear about it, while a document that carries the field from a raw write has
+ * silently LOST a bypass it should never have had. A warning names the situation without guessing
+ * which one it is; treating it as "checked" is what this file exists to stop.
+ */
+export function hasUnrecognizedRestrictionsFlag(data: unknown): boolean {
+  return (
+    !!data &&
+    typeof data === 'object' &&
+    RESTRICTIONS_CHECKED_KEY in (data as object) &&
+    (data as Record<string, unknown>)[RESTRICTIONS_CHECKED_KEY] !== MARKER
+  );
+}

package/src/core/common/decorators/unified-field.decorator.ts

@@ -22,11 +22,12 @@ import {
 import { GraphQLScalarType, isEnumType } from 'graphql';
 
 import { RoleEnum } from '../enums/role.enum';
+// Re-exported below so no import path broke. The map moved into an import-free leaf because
+// `restricted.decorator` — which this file imports — now READS it; see that leaf's docblock.
+import { nestedTypeRegistry } from './nested-type.registry';
 import { Restricted, RestrictedType } from './restricted.decorator';
 
-// Registry to store nested type information for validation
-// Key: `${className}.${propertyName}`, Value: nested type constructor
-export const nestedTypeRegistry = new Map<string, any>();
+export { nestedTypeRegistry, resolveNestedType } from './nested-type.registry';
 
 /**
  * Registry to map enum objects to their names.

package/src/core/common/enums/role.enum.ts

@@ -60,3 +60,119 @@ export enum RoleEnum {
   // User must be logged in (see context user, e.g. @CurrentUser)
   S_USER = 's_user',
 }
+
+/**
+ * Prefix that marks a role as a system role (runtime-context check, never a stored role).
+ *
+ * This is the single source of truth for the prefix. Anything deriving the system-role rule —
+ * guards, the `@Restricted` evaluation, the storage guards — must build on it rather than
+ * hard-coding `'s_'` again.
+ */
+export const SYSTEM_ROLE_PREFIX = 's_';
+
+/**
+ * Is this role a system role, by the exact rule the runtime checks use?
+ *
+ * Case-SENSITIVE on purpose: `hasRole()` and `checkRoleAccess()` compare role strings exactly,
+ * so `'S_SELF'` is a different string from `'s_self'` and never grants anything. Widening this
+ * to case-insensitive would make the guards treat a legitimately-named project role such as
+ * `'S_Manager'` as a system role and change access decisions.
+ *
+ * Use this for RUNTIME checks. To decide whether a value may be STORED in `user.roles`, use
+ * {@link looksLikeSystemRole} — that question deserves the stricter, defensive answer.
+ *
+ * Declared as a hoisted `function` (not a `const` arrow) so it stays temporal-dead-zone immune
+ * on any import cycle — see `.claude/rules/architecture.md` → "DI Token Placement (SWC-Safe)".
+ */
+export function isSystemRole(role: string): boolean {
+  return typeof role === 'string' && role.startsWith(SYSTEM_ROLE_PREFIX);
+}
+
+/**
+ * Could this value be mistaken for a system role once stored in `user.roles`?
+ *
+ * Deliberately BROADER than {@link isSystemRole}: trims surrounding whitespace and ignores case.
+ * A stored `' s_self'` or `'S_SELF'` grants nothing today, because `hasRole()` compares exactly —
+ * but that is an accident of the comparison, not a decision. Both become live the moment anything
+ * normalizes roles (a Mongoose `trim: true`, a CSV/LDAP import, a project sanitizer), and both
+ * pass an eyeball review as legitimate roles in the meantime.
+ *
+ * This is the predicate the storage guards use. It is intentionally strict enough to also reject
+ * a project role that merely happens to start with `s_` (e.g. `'s_manager'`) — the framework
+ * cannot tell those apart from a system role, and a false rejection is recoverable by renaming
+ * while a false acceptance is a silent authorization hole.
+ */
+export function looksLikeSystemRole(role: unknown): boolean {
+  return typeof role === 'string' && role.trim().toLowerCase().startsWith(SYSTEM_ROLE_PREFIX);
+}
+
+/**
+ * Roles that carry GLOBAL, platform-wide authority and can therefore never be satisfied by a
+ * tenant membership role.
+ *
+ * The distinction exists because membership roles are customer-assigned free text: `addMember()`
+ * takes any non-empty string, and whoever may manage members is typically a tenant owner — a
+ * customer. If a membership role were compared by plain string equality against a framework role,
+ * that customer could mint platform-wide authority for themselves simply by naming their tenant
+ * role `'admin'`.
+ *
+ * The two levels are meant to be expressed separately:
+ * - **global admin** → `RoleEnum.ADMIN` in `user.roles` — access to every tenant
+ * - **tenant admin** → a membership role such as `'tenantAdmin'` / `'spaceAdmin'` — one tenant only
+ *
+ * Required roles from this set are always resolved against `user.roles`, never against
+ * `membership.role`, no matter what the tenant header says.
+ */
+export const GLOBAL_ONLY_ROLES: readonly string[] = [RoleEnum.ADMIN];
+
+/**
+ * Is this a role that only the platform may grant (never a tenant)?
+ *
+ * Hoisted `function` for the same temporal-dead-zone reason as {@link isSystemRole}.
+ */
+export function isGlobalOnlyRole(role: string): boolean {
+  return typeof role === 'string' && GLOBAL_ONLY_ROLES.includes(role);
+}
+
+/**
+ * Could this value be mistaken for a global-only role once stored?
+ *
+ * Stands to {@link isGlobalOnlyRole} exactly as {@link looksLikeSystemRole} stands to
+ * {@link isSystemRole}: the runtime rule is exact (so `'ADMIN'` never grants anything), while the
+ * storage rule is defensive, because `' Admin '` reads as legitimate in a members list and becomes
+ * live the moment anything normalizes role strings.
+ */
+export function looksLikeGlobalOnlyRole(role: unknown): boolean {
+  if (typeof role !== 'string') {
+    return false;
+  }
+  const normalized = role.trim().toLowerCase();
+  return GLOBAL_ONLY_ROLES.some((globalRole) => globalRole.toLowerCase() === normalized);
+}
+
+/**
+ * Is this value unusable as a tenant MEMBERSHIP role?
+ *
+ * True for system roles (which are runtime-context checks, not stored roles) and for global-only
+ * roles (which would cross the tenant boundary). Used to refuse such values at assignment time, so
+ * the dangerous membership never comes into existence in the first place.
+ *
+ * Uses the DEFENSIVE variant of both predicates — see {@link looksLikeSystemRole} and
+ * {@link looksLikeGlobalOnlyRole} for why storage deserves the stricter answer than runtime.
+ */
+export function isForbiddenMembershipRole(role: unknown): boolean {
+  return looksLikeSystemRole(role) || looksLikeGlobalOnlyRole(role);
+}
+
+/**
+ * `class-validator` `@Matches()` pattern that ACCEPTS everything {@link looksLikeSystemRole}
+ * rejects, and vice versa.
+ *
+ * A negative lookahead, so a value is valid exactly when it does NOT begin (after optional leading
+ * whitespace, case-insensitively) with the system-role prefix. Kept next to the predicate it
+ * mirrors so the two cannot drift; `@Matches` needs a pattern and cannot take a function.
+ *
+ * Anchored with no quantifier over the input, so it is linear in input length — a 100 KB value
+ * costs the same as a 10-character one, with no backtracking to exploit.
+ */
+export const SYSTEM_ROLE_REJECT_PATTERN = new RegExp(`^(?!\\s*${SYSTEM_ROLE_PREFIX})`, 'i');

package/src/core/common/helpers/execution-context-request.helper.ts

@@ -0,0 +1,102 @@
+/**
+ * The request-like object a guard decides on, for EVERY transport — including the GraphQL WebSocket.
+ *
+ * WHY THIS EXISTS: all three role guards resolved the request the same way, and all three got the
+ * WebSocket wrong in the same way:
+ *
+ * ```typescript
+ * ctx.getContext()?.req || context.switchToHttp().getRequest()
+ * ```
+ *
+ * A subscription's GraphQL context is the graphql-ws `extra` object, which has no `req`. The HTTP
+ * fallback then runs on a GraphQL context, where `switchToHttp().getRequest()` yields the resolver's
+ * ROOT value — `undefined` at subscribe time. So the guards were handed nothing, and what they did
+ * with nothing differed in the worst possible way:
+ *
+ * - `CoreTenantGuard` hit `if (!request) return true` and GRANTED access without deciding anything.
+ *   With multi-tenancy active the role guard PASSES non-system roles through to it, so `@Roles()` on a
+ *   subscription was checked by nobody at all: a plain `member` reached a `tenantAdmin`-gated
+ *   subscription and received its messages.
+ * - Without multi-tenancy the role guard found no token and refused EVERYONE, so the same decorator
+ *   silently meant "locked" instead of "open".
+ *
+ * Both are wrong, and the first is a hole. Everything a guard needs is present on the subscription
+ * context — `CoreModule`'s `onConnect` records the authenticated `user` and the client's
+ * `connectionParams` as `headers` — it was simply never looked at.
+ *
+ * DELIBERATELY IMPORT-FREE apart from the Nest types it is typed against, so it stays usable from
+ * `src/core/common/**` and from `src/core/modules/**` alike without adding an import edge between
+ * them. See `.claude/rules/architecture.md` → "DI Token Placement (SWC-Safe)".
+ */
+import type { ExecutionContext } from '@nestjs/common';
+
+/**
+ * The shape a guard reads and writes. It is deliberately loose: on HTTP this IS the Express request,
+ * and on a WebSocket it is the graphql-ws `extra` object, which a guard may annotate the same way
+ * (`tenantId`, `tenantRole`, …) — those writes are inert on that path, because the Mongoose plugins
+ * read the WebSocket's tenant scope from `RequestContext` instead (see `graphql-ws-context.helper`).
+ */
+export interface GuardRequestLike {
+  [key: string]: any;
+  headers?: Record<string, any>;
+  user?: any;
+}
+
+/**
+ * Is this object plausibly a request/subscription context rather than a resolver root value?
+ *
+ * The check is on the KEYS a guard actually reads. A payload object that happens to carry a `user`
+ * field would otherwise be mistaken for an authenticated request — and a subscription payload very
+ * plausibly does (`pubSub.publish('userCreated', user)`), which would turn the PUBLISHED user into
+ * the apparent caller. Requiring the graphql-ws marker (`socket` / `request` / `connectionParams`)
+ * rules that out: a payload does not carry those.
+ */
+function isSubscriptionContext(value: any): boolean {
+  return (
+    !!value && typeof value === 'object' && ('socket' in value || 'connectionParams' in value || 'request' in value)
+  );
+}
+
+/**
+ * Resolve the object a guard should decide on.
+ *
+ * Order matters:
+ *  1. `ctx.getContext().req` — HTTP GraphQL, and the shape every existing consumer expects.
+ *  2. The graphql-ws subscription context itself, when it looks like one (see above).
+ *  3. `switchToHttp().getRequest()` — REST controllers. On a GraphQL context this returns the
+ *     resolver root, which is why it comes LAST and why step 2 must not fall through to it.
+ *
+ * @returns the request-like object, or `undefined` when the context carries none. A guard must treat
+ *   `undefined` as "no information", never as "permitted" — that conflation is what this file fixes.
+ */
+export function resolveGuardRequest(
+  context: ExecutionContext,
+  gqlContextOf: (context: ExecutionContext) => any,
+): GuardRequestLike | undefined {
+  let gqlContext: any;
+  try {
+    gqlContext = gqlContextOf(context);
+  } catch {
+    gqlContext = undefined;
+  }
+
+  if (gqlContext?.req) {
+    return gqlContext.req;
+  }
+
+  if (isSubscriptionContext(gqlContext)) {
+    // Normalize the two names the transports use, so a guard reads `headers` unconditionally:
+    // `graphql-ws` gets them from CoreModule's onConnect, `subscriptions-transport-ws` from its own,
+    // and the raw upgrade request is the fallback for a custom onConnect that forwards neither.
+    if (!gqlContext.headers) {
+      gqlContext.headers = gqlContext.connectionParams ?? gqlContext.request?.headers ?? {};
+    }
+    return gqlContext;
+  }
+
+  try {
+    return context.switchToHttp().getRequest();
+  } catch {
+    return undefined;
+  }
+}