@lenne.tech/nest-server 11.27.6 → 11.28.0

package/src/core/common/exceptions/access-denied.exception.ts

@@ -0,0 +1,49 @@
+import { ForbiddenException, UnauthorizedException } from '@nestjs/common';
+
+import { ErrorCode } from '../../modules/error-code/error-codes';
+
+/**
+ * Creates the access error that matches the requester's auth state (RFC 9110, mirrors RolesGuard):
+ * **403 Forbidden** for authenticated requesters (a permission problem) and **401 Unauthorized**
+ * only when the requester is not authenticated.
+ *
+ * Frontends commonly treat 401 as "session expired" and auto-logout (the `@lenne.tech/nuxt-extensions`
+ * auth interceptor patches `$fetch`/`fetch` globally and does exactly this), so a mere permission
+ * error must never surface as 401 — it would kick a logged-in user out of the whole app.
+ *
+ * This is a **factory, not a class**, on purpose: it returns the *native* Nest exceptions, so
+ * `instanceof ForbiddenException` / `instanceof UnauthorizedException` and `@Catch(...)` filters in
+ * consuming projects keep working, and the REST wire body (which `HttpExceptionLogFilter` builds via
+ * `{ ...exception }`, including `name`) stays identical to what it was before. A custom
+ * `HttpException` subclass would satisfy neither.
+ *
+ * The default messages are the same translatable `ErrorCode`s the role guards throw (`#LTNS_xxxx:`
+ * marker → resolvable by the frontend error-translation layer). Pass an explicit `message` only
+ * where a raw string is genuinely required; prefer logging request-specific detail (class names,
+ * field names) over returning it to the client.
+ *
+ * @param user The **requesting** user (never the target object). The decision key is `user.id`: an
+ *   id that is present — even a falsy one like `0` or `''` — counts as authenticated, while
+ *   `undefined`, `null` or no user at all does not. This mirrors how `check()` defines "logged in"
+ *   (`S_USER` requires `user?.id`).
+ * @param message Overrides the default `ErrorCode`. Omit it to stay consistent with `RolesGuard`.
+ *
+ * @example
+ * // 403 for an authenticated user who lacks a right, 401 for an anonymous requester:
+ * throw accessDeniedException(currentUser);
+ *
+ * @see src/core/modules/auth/guards/roles.guard.ts — the pre-existing 401/403 pattern this mirrors
+ * @see migration-guides/11.27.7-to-11.28.0.md
+ */
+export function accessDeniedException(
+  user: { id?: unknown } | null | undefined,
+  message?: string,
+): ForbiddenException | UnauthorizedException {
+  // A present id means authenticated. `!!user?.id` would misjudge falsy-but-real ids (0, '') as
+  // anonymous and hand an authenticated user the very 401 this mechanism exists to avoid.
+  const authenticated = user?.id !== undefined && user?.id !== null;
+
+  return authenticated
+    ? new ForbiddenException(message ?? ErrorCode.ACCESS_DENIED)
+    : new UnauthorizedException(message ?? ErrorCode.UNAUTHORIZED);
+}

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

@@ -0,0 +1,110 @@
+/**
+ * Cloning / freezing helpers.
+ *
+ * These live in their own file — instead of `input.helper.ts` — so that `config.service` can reach
+ * them without importing `input.helper`, which imports `restricted.decorator` behind it.
+ *
+ * That edge closed a runtime cycle:
+ *
+ *   restricted.decorator → tenant/core-tenant.helpers → config.service → input.helper
+ *                        → restricted.decorator
+ *
+ * so `input.helper` evaluated while `restricted.decorator` was still initializing. Nothing crashed,
+ * but only because every cross-cycle dereference sat inside a function body. A single top-level line
+ * in `input.helper` — a module-level alias of `checkRestricted`, an `@Restricted`-decorated class,
+ * `design:type` metadata — would have thrown under SWC → CommonJS:
+ *
+ *   ReferenceError: Cannot access 'checkRestricted' before initialization
+ *
+ * …in the file that drives field-level access control, on a compiler this repo's default build never
+ * runs, with a green test suite. Moving these two pure functions out removes the edge, so the cycle
+ * no longer exists rather than merely being disarmed.
+ *
+ * This file imports only Node built-ins, lodash and rfdc — no framework code — so it can never be
+ * part of a cycle itself. Keep it that way.
+ *
+ * `input.helper` re-exports both functions, so every existing import path keeps working.
+ * See .claude/rules/architecture.md → "DI Token Placement (SWC-Safe)".
+ */
+import * as inspector from 'inspector';
+import _ = require('lodash');
+import rfdc = require('rfdc');
+import * as util from 'util';
+
+/**
+ * Get clone of object
+ *
+ * @param object Object to clone
+ * @param options Options for cloning
+ * @param options.checkResult Whether to check the result of the cloning process
+ * @param options.circles Keeping track of circular references will slow down performance with an additional 25% overhead.
+ *                        Even if an object doesn't have any circular references, the tracking overhead is the cost.
+ *                        By default if an object with a circular reference is passed to rfdc, it will throw
+ *                        (similar to how JSON.stringify would throw). Use the circles option to detect and preserve
+ *                        circular references in the object. If performance is important, try removing the circular
+ *                        reference from the object (set to undefined) and then add it back manually after cloning
+ *                        instead of using this option.
+ * @param options.proto Copy prototype properties as well as own properties into the new object.
+ *                      It's marginally faster to allow enumerable properties on the prototype to be copied into the
+ *                      cloned object (not onto it's prototype, directly onto the object).
+ */
+export function clone(object: any, options?: { checkResult?: boolean; circles?: boolean; proto?: boolean }) {
+  const config = {
+    checkResult: true,
+    circles: true,
+    debug: inspector.url() !== undefined,
+    proto: false,
+    ...options,
+  };
+
+  try {
+    const cloned = rfdc(config)(object);
+    if (config.checkResult && !util.isDeepStrictEqual(object, cloned)) {
+      throw new Error('Cloned object differs from original object');
+    }
+    return cloned;
+  } catch (e) {
+    if (!config.circles) {
+      if (config.debug) {
+        console.debug(e, config, object, 'automatic try to use rfdc with circles');
+      }
+      try {
+        const clonedWithCircles = rfdc({
+          ...config,
+          circles: true,
+        })(object);
+        if (config.checkResult && !util.isDeepStrictEqual(object, clonedWithCircles)) {
+          throw new Error('Cloned object differs from original object', { cause: e });
+        }
+        return clonedWithCircles;
+      } catch (innerError) {
+        if (config.debug) {
+          console.debug(innerError, 'rfcd with circles did not work => automatic use of _.clone!');
+        }
+        return _.cloneDeep(object);
+      }
+    } else {
+      if (config.debug) {
+        console.debug(e, config, object, 'automatic try to use _.clone instead rfdc');
+      }
+      return _.cloneDeep(object);
+    }
+  }
+}
+
+/**
+ * Get deep frozen object
+ */
+export function deepFreeze(object: any, visited: WeakSet<object> = new WeakSet()) {
+  if (!object || typeof object !== 'object') {
+    return object;
+  }
+  if (visited.has(object)) {
+    return object;
+  }
+  visited.add(object);
+  for (const [key, value] of Object.entries(object)) {
+    object[key] = deepFreeze(value, visited);
+  }
+  return Object.freeze(object);
+}

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

@@ -1,5 +1,4 @@
 import { FieldNode, GraphQLResolveInfo, SelectionNode } from 'graphql';
-import _ = require('lodash');
 import { Document, Model, PopulateOptions, Query, Types } from 'mongoose';
 
 import { ResolveSelector } from '../interfaces/resolve-selector.interface';
@@ -7,8 +6,19 @@ import { CoreModel } from '../models/core-model.model';
 import { FieldSelection } from '../types/field-selection.type';
 import { IdsType } from '../types/ids.type';
 import { StringOrObjectId } from '../types/string-or-object-id.type';
+import { equalIds, getObjectIds, getStringIds } from './id.helper';
 import { removePropertiesDeep } from './input.helper';
 
+/**
+ * The ID helpers moved to `./id.helper` and are re-exported here so every existing import path keeps
+ * working. They were extracted because `restricted.decorator` needs `equalIds` / `getIncludedIds`,
+ * and pulling them from HERE put that decorator on a runtime import cycle
+ * (restricted.decorator → db.helper → input.helper → restricted.decorator) that is one top-level
+ * line away from an SWC temporal-dead-zone crash. `id.helper` imports no framework code, so it can
+ * never be part of a cycle. Do NOT move them back.
+ */
+export { equalIds, getIncludedIds, getObjectIds, getStringIds } from './id.helper';
+
 // =====================================================================================================================
 // Export functions
 // =====================================================================================================================
@@ -71,7 +81,9 @@ export function addIds(
   // Convert array
   if (['object', 'string'].includes(convert as string)) {
     for (let i = 0; i < result.length; i++) {
-      result[i] = convert === 'string' ? getStringId(result[i]) : getObjectIds(result[i]);
+      // getStringIds() delegates to the (module-private) getStringId() for a non-array argument, so
+      // this is the same conversion the removed private helper performed — result[i] is a single ID.
+      result[i] = convert === 'string' ? getStringIds(result[i]) : getObjectIds(result[i]);
     }
   }
 
@@ -97,20 +109,6 @@ export function checkStringIds(ids: string | string[]): boolean {
   return false;
 }
 
-/**
- * Checks if all IDs are equal
- */
-export function equalIds(...ids: IdsType[]): boolean {
-  if (!ids) {
-    return false;
-  }
-  const compare = getStringIds(ids[0]);
-  if (!compare) {
-    return false;
-  }
-  return ids.every((id) => getStringIds(id) === compare);
-}
-
 /**
  * Get (and remove) elements with specific IDs from array
  */
@@ -160,48 +158,6 @@ export function getElementsViaIds<T = any>(
   // Return elements
   return elements;
 }
-/**
- * Get included ids
- * @param includes IdsType, which should be checked if it contains the ID
- * @param ids IdsType, which should be included
- * @param convert If set the result array will be converted to pure type String array or ObjectId array
- * @return IdsType with IDs which are included, undefined if includes or ids are missing or null if none is included
- */
-export function getIncludedIds(includes: IdsType, ids: IdsType, convert?: 'string'): string[];
-export function getIncludedIds(includes: IdsType, ids: IdsType, convert?: 'object'): Types.ObjectId[];
-
-export function getIncludedIds<T = IdsType>(
-  includes: IdsType,
-  ids: IdsType | T,
-  convert?: 'object' | 'string',
-): null | T[] | undefined {
-  if (!includes || !ids) {
-    return undefined;
-  }
-
-  if (!Array.isArray(includes)) {
-    includes = [includes];
-  }
-
-  if (!Array.isArray(ids)) {
-    ids = [ids];
-  }
-
-  let result = [];
-  const includesStrings = getStringIds(includes);
-  for (const id of ids) {
-    if (includesStrings.includes(getStringIds(id))) {
-      result.push(id);
-    }
-  }
-
-  if (convert) {
-    result = convert === 'string' ? getStringIds(result) : getObjectIds(result);
-  }
-
-  return result.length ? result : null;
-}
-
 /**
  * Get indexes of IDs in an array
  */
@@ -252,18 +208,6 @@ export function getNextFieldNodes(nodes: readonly SelectionNode[]): FieldNode[]
   return result;
 }
 
-/**
- * Convert string(s) to ObjectId(s)
- */
-export function getObjectIds(ids: any[]): Types.ObjectId[];
-export function getObjectIds(ids: any): Types.ObjectId;
-export function getObjectIds<T extends any | any[]>(ids: T): Types.ObjectId | Types.ObjectId[] {
-  if (Array.isArray(ids)) {
-    return ids.map((id) => new Types.ObjectId(getStringId(id)));
-  }
-  return new Types.ObjectId(getStringId(ids));
-}
-
 /**
  * Get populate options from GraphQL resolve info
  */
@@ -356,55 +300,6 @@ export function getPopulatOptionsFromSelections(selectionNodes: readonly Selecti
   return populateOptions;
 }
 
-/**
- * Get IDs from string of ObjectId array in a flat string array
- */
-export function getStringIds(elements: any[], options?: { deep?: boolean; unique?: boolean }): string[];
-
-export function getStringIds(elements: any, options?: { deep?: boolean; unique?: boolean }): string;
-
-export function getStringIds<T extends any | any[]>(
-  elements: T,
-  options?: { deep?: boolean; unique?: boolean },
-): string | string[] {
-  // Process options
-  const { deep, unique } = {
-    deep: false,
-    unique: false,
-    ...options,
-  };
-
-  // Check elements
-  if (!elements) {
-    return elements as any;
-  }
-
-  // Init ids
-  let ids = [];
-
-  // Process non array
-  if (!Array.isArray(elements)) {
-    return getStringId(elements);
-  }
-
-  // Process array
-  for (const element of elements) {
-    if (Array.isArray(element)) {
-      if (deep) {
-        ids = ids.concat(getStringIds(element, { deep }));
-      }
-    } else {
-      const id = getStringId(element);
-      if (id) {
-        ids.push(id);
-      }
-    }
-  }
-
-  // Return (unique) ID array
-  return unique ? _.uniq(ids) : ids;
-}
-
 /**
  * Convert all ObjectIds to strings
  */
@@ -664,45 +559,3 @@ export async function setPopulates<T = Document | Query<any, any>>(
 // =====================================================================================================================
 // Not exported helper functions
 // =====================================================================================================================
-/**
- * Get ID of element as string
- */
-function getStringId(element: any): string {
-  // Check element
-  if (!element) {
-    return element;
-  }
-
-  // Buffer handling
-  if (element instanceof Buffer) {
-    return element.toString();
-  }
-
-  // String handling
-  if (typeof element === 'string') {
-    return element;
-  }
-
-  // Object handling
-  if (typeof element === 'object') {
-    if (element instanceof Types.ObjectId) {
-      return element.toHexString();
-    }
-
-    if (element.id) {
-      if (element.id instanceof Buffer && element.toHexString) {
-        return element.toHexString();
-      }
-      return getStringId(element.id);
-    } else if (element._id) {
-      return getStringId(element._id);
-    }
-  }
-
-  // Other types
-  if (typeof element.toString === 'function') {
-    return element.toString();
-  }
-
-  return undefined;
-}

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

@@ -0,0 +1,198 @@
+/**
+ * ID helpers.
+ *
+ * These live in their own file — instead of `db.helper.ts` — so that files which need nothing but
+ * ID comparison can reach them without importing `db.helper`, which drags in GraphQL, Mongoose
+ * models and `input.helper` behind it.
+ *
+ * That was not an aesthetic choice. `restricted.decorator.ts` needs exactly two of these functions
+ * (`equalIds`, `getIncludedIds`), and importing them from `db.helper` put it on a real runtime
+ * cycle:
+ *
+ *   restricted.decorator → db.helper → input.helper → restricted.decorator
+ *
+ * `input.helper` therefore evaluated while `restricted.decorator` was still initializing. Nothing
+ * crashed, but only because every cross-cycle dereference happened to sit inside a function body:
+ * a single top-level line in `input.helper` (a module-level alias, an `@Restricted`-decorated class,
+ * `design:type` metadata) would have thrown under SWC → CommonJS:
+ *
+ *   ReferenceError: Cannot access 'checkRestricted' before initialization
+ *
+ * …in the file that drives field-level access control, on a compiler this repo's default build never
+ * runs. Moving the ID cluster into this leaf removes the `restricted.decorator → db.helper` edge
+ * outright, so the cycle no longer exists rather than merely being disarmed.
+ *
+ * This file imports only Mongoose's `Types`, lodash, and a type — no framework code — so it can
+ * never be part of a cycle itself. Keep it that way.
+ *
+ * `db.helper` re-exports all four public functions, so every existing import path keeps working.
+ * See .claude/rules/architecture.md → "DI Token Placement (SWC-Safe)".
+ */
+import _ = require('lodash');
+import { Types } from 'mongoose';
+
+import { IdsType } from '../types/ids.type';
+
+/**
+ * Checks if all IDs are equal
+ */
+export function equalIds(...ids: IdsType[]): boolean {
+  if (!ids) {
+    return false;
+  }
+  const compare = getStringIds(ids[0]);
+  if (!compare) {
+    return false;
+  }
+  return ids.every((id) => getStringIds(id) === compare);
+}
+
+/**
+ * Get included ids
+ * @param includes IdsType, which should be checked if it contains the ID
+ * @param ids IdsType, which should be included
+ * @param convert If set the result array will be converted to pure type String array or ObjectId array
+ * @return IdsType with IDs which are included, undefined if includes or ids are missing or null if none is included
+ */
+export function getIncludedIds(includes: IdsType, ids: IdsType, convert?: 'string'): string[];
+export function getIncludedIds(includes: IdsType, ids: IdsType, convert?: 'object'): Types.ObjectId[];
+
+export function getIncludedIds<T = IdsType>(
+  includes: IdsType,
+  ids: IdsType | T,
+  convert?: 'object' | 'string',
+): null | T[] | undefined {
+  if (!includes || !ids) {
+    return undefined;
+  }
+
+  if (!Array.isArray(includes)) {
+    includes = [includes];
+  }
+
+  if (!Array.isArray(ids)) {
+    ids = [ids];
+  }
+
+  let result = [];
+  const includesStrings = getStringIds(includes);
+  for (const id of ids) {
+    if (includesStrings.includes(getStringIds(id))) {
+      result.push(id);
+    }
+  }
+
+  if (convert) {
+    result = convert === 'string' ? getStringIds(result) : getObjectIds(result);
+  }
+
+  return result.length ? result : null;
+}
+
+/**
+ * Convert string(s) to ObjectId(s)
+ */
+export function getObjectIds(ids: any[]): Types.ObjectId[];
+export function getObjectIds(ids: any): Types.ObjectId;
+export function getObjectIds<T extends any | any[]>(ids: T): Types.ObjectId | Types.ObjectId[] {
+  if (Array.isArray(ids)) {
+    return ids.map((id) => new Types.ObjectId(getStringId(id)));
+  }
+  return new Types.ObjectId(getStringId(ids));
+}
+
+/**
+ * Get IDs from string of ObjectId array in a flat string array
+ */
+export function getStringIds(elements: any[], options?: { deep?: boolean; unique?: boolean }): string[];
+
+export function getStringIds(elements: any, options?: { deep?: boolean; unique?: boolean }): string;
+
+export function getStringIds<T extends any | any[]>(
+  elements: T,
+  options?: { deep?: boolean; unique?: boolean },
+): string | string[] {
+  // Process options
+  const { deep, unique } = {
+    deep: false,
+    unique: false,
+    ...options,
+  };
+
+  // Check elements
+  if (!elements) {
+    return elements as any;
+  }
+
+  // Init ids
+  let ids = [];
+
+  // Process non array
+  if (!Array.isArray(elements)) {
+    return getStringId(elements);
+  }
+
+  // Process array
+  for (const element of elements) {
+    if (Array.isArray(element)) {
+      if (deep) {
+        ids = ids.concat(getStringIds(element, { deep }));
+      }
+    } else {
+      const id = getStringId(element);
+      if (id) {
+        ids.push(id);
+      }
+    }
+  }
+
+  // Return (unique) ID array
+  return unique ? _.uniq(ids) : ids;
+}
+
+// =====================================================================================================================
+// Not exported helper functions
+// =====================================================================================================================
+
+/**
+ * Get ID of element as string
+ */
+function getStringId(element: any): string {
+  // Check element
+  if (!element) {
+    return element;
+  }
+
+  // Buffer handling
+  if (element instanceof Buffer) {
+    return element.toString();
+  }
+
+  // String handling
+  if (typeof element === 'string') {
+    return element;
+  }
+
+  // Object handling
+  if (typeof element === 'object') {
+    if (element instanceof Types.ObjectId) {
+      return element.toHexString();
+    }
+
+    if (element.id) {
+      if (element.id instanceof Buffer && element.toHexString) {
+        return element.toHexString();
+      }
+      return getStringId(element.id);
+    } else if (element._id) {
+      return getStringId(element._id);
+    }
+  }
+
+  // Other types
+  if (typeof element.toString === 'function') {
+    return element.toString();
+  }
+
+  return undefined;
+}