@lenne.tech/nest-server 11.27.5 → 11.27.7

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/cookies.helper.ts

@@ -273,8 +273,7 @@ export const LOCALHOST_URL_ENVS: readonly string[] = ['ci', 'e2e', 'local'];
 const API_HOST_LABEL = 'api.';
 
 /**
- * Normalizes a URL string to its http(s) origin, or `undefined` when it is not a usable
- * http(s) URL.
+ * Parses a URL string into a `URL`, or returns `undefined` when it is not a usable http(s) URL.
  *
  * The `protocol` guard is security-relevant, not cosmetic: `URL.origin` serializes to the
  * literal string `'null'` for opaque origins (any non-special scheme, e.g. `custom://host`).
@@ -282,7 +281,7 @@ const API_HOST_LABEL = 'api.';
  * `credentials: true` allowlist would grant credentialed access to any site able to frame a
  * sandboxed document.
  */
-function toHttpOrigin(value: string): string | undefined {
+function toHttpUrl(value: string): undefined | URL {
   let url: URL;
   try {
     url = new URL(value);
@@ -294,7 +293,15 @@ function toHttpOrigin(value: string): string | undefined {
     return undefined;
   }
 
-  return url.origin;
+  return url;
+}
+
+/**
+ * Normalizes a URL string to its http(s) origin, or `undefined` when it is not a usable
+ * http(s) URL. See {@link toHttpUrl} for why the protocol guard matters.
+ */
+function toHttpOrigin(value: string): string | undefined {
+  return toHttpUrl(value)?.origin;
 }
 
 /**
@@ -316,7 +323,8 @@ function isLocalhostUrl(value: string | undefined): boolean {
 }
 
 /**
- * Whether stripping the leading `api.` label from the hostname leaves a deployable host.
+ * The hostname with its leading `api.` label removed, or `undefined` when the label is absent
+ * or stripping it would not leave a deployable host.
  *
  * Guards two cases where a naive strip produces a bogus origin:
  * - `api.dev` → `dev` — a bare TLD. `api.dev`/`api.io`/`api.co` are registrable domains, so
@@ -326,14 +334,65 @@ function isLocalhostUrl(value: string | undefined): boolean {
  *   `URL` setter for special schemes, so the strip would appear to succeed but do nothing.
  *
  * `localhost` is the one legitimate single-label host (`api.localhost` → `localhost`).
+ *
+ * Exported for reuse by BetterAuth's `deriveCookieDomainFromUrls()`, so the cookie-domain
+ * derivation shares this bare-TLD/empty guard instead of re-implementing a naive `api.`-strip.
  */
-function canStripApiLabel(hostname: string): boolean {
+export function strippedApiHostname(hostname: string): string | undefined {
   if (!hostname.startsWith(API_HOST_LABEL)) {
-    return false;
+    return undefined;
   }
 
   const remainder = hostname.slice(API_HOST_LABEL.length);
-  return remainder === 'localhost' || remainder.includes('.');
+  if (remainder !== 'localhost' && !remainder.includes('.')) {
+    return undefined;
+  }
+
+  return remainder;
+}
+
+/**
+ * Derives the app origin from an already-parsed API base `URL` by stripping a leading `api.`
+ * label from its hostname. Mutates and re-serializes the passed `URL`, so callers must not
+ * reuse it afterwards. Shared by {@link deriveAppUrlFromBaseUrl} (string entry point) and
+ * {@link resolveServerUrls} (which parses `baseUrl` once and threads the result through).
+ */
+function deriveAppOriginFromUrl(url: URL): string {
+  const stripped = strippedApiHostname(url.hostname);
+  if (stripped !== undefined) {
+    url.hostname = stripped;
+  }
+
+  return url.origin;
+}
+
+/**
+ * Whether stripping the `api.` label from `baseUrl` names a host the API itself is NOT served
+ * from — i.e. API and app are separated by HOST rather than by PORT.
+ *
+ * {@link LOCALHOST_URL_DEFAULTS} encode a port split: one host, API on `:3000`, app on `:3001`.
+ * `http://api.localhost:3000` and `https://api.localhost` are both that shape — the label
+ * strips to the bare `localhost` the API already answers on, so only the port tells app and API
+ * apart, and the flat `http://localhost:3001` default is the right answer.
+ *
+ * `https://api.crm.localhost` (as served by `lt dev up` behind Caddy) strips to the sibling host
+ * `crm.localhost`, which the API never answers on. There the derivation names the real app
+ * origin and must win over the flat default.
+ *
+ * Keyed on the stripped LABEL, never on the presence of a port: a host split stays a host split
+ * behind a non-default port (`https://api.crm.localhost:8443` → `https://crm.localhost:8443`),
+ * and a port split stays a port split on the default port (`https://api.localhost`).
+ *
+ * Takes an already-parsed `URL` (or `undefined` for an unparseable/absent `baseUrl`) so the
+ * caller parses `baseUrl` only once.
+ */
+function separatesApiAndAppByHost(url: undefined | URL): boolean {
+  if (!url) {
+    return false;
+  }
+
+  const stripped = strippedApiHostname(url.hostname);
+  return stripped !== undefined && stripped !== 'localhost';
 }
 
 /**
@@ -341,6 +400,8 @@ function canStripApiLabel(hostname: string): boolean {
  * label from the hostname (e.g. `https://api.example.com` → `https://example.com`,
  * `https://api.dev.example.com` → `https://dev.example.com`).
  *
+ * The port is preserved (`https://api.example.com:8443` → `https://example.com:8443`).
+ *
  * Returns the origin unchanged when there is no strippable `api.` prefix, and returns the
  * input unchanged when it is not an http(s) URL — callers decide what to do with a value
  * they cannot normalize.
@@ -348,17 +409,8 @@ function canStripApiLabel(hostname: string): boolean {
  * @since 11.27.5
  */
 export function deriveAppUrlFromBaseUrl(baseUrl: string): string {
-  const origin = toHttpOrigin(baseUrl);
-  if (!origin) {
-    return baseUrl;
-  }
-
-  const url = new URL(origin);
-  if (canStripApiLabel(url.hostname)) {
-    url.hostname = url.hostname.slice(API_HOST_LABEL.length);
-  }
-
-  return url.origin;
+  const url = toHttpUrl(baseUrl);
+  return url ? deriveAppOriginFromUrl(url) : baseUrl;
 }
 
 /**
@@ -378,15 +430,22 @@ export interface IResolvedServerUrls {
  * Resolves the effective app/API URLs for a server configuration.
  *
  * `baseUrl`: explicit → localhost default (local/ci/e2e only) → none.
- * `appUrl`: explicit → localhost default (local/ci/e2e with a localhost `baseUrl`) →
- * derived from `baseUrl` → none.
+ * `appUrl`: explicit → derived from a host-split localhost `baseUrl` (local/ci/e2e) →
+ * localhost default (local/ci/e2e with a localhost `baseUrl`) → derived from `baseUrl` → none.
+ *
+ * The localhost defaults assume a PORT split (API `:3000`, app `:3001`, one host). A localhost
+ * `baseUrl` whose `api.` label strips to a SIBLING host — `https://api.crm.localhost` from
+ * `lt dev up` — derives that host on whatever port it carries, because the flat
+ * `http://localhost:3001` default would name a host the app never serves from. See
+ * {@link separatesApiAndAppByHost}.
  *
  * `baseUrl` is returned verbatim (not origin-normalized) because BetterAuth passes it
  * straight through as its `baseURL`; normalization for origin matching is the caller's job.
  *
  * @param input.deriveAppUrl - Set to `false` to disable the `api.`-strip derivation. The
  *                             localhost defaults are unaffected — they are an explicit,
- *                             documented behavior of the `local`/`ci`/`e2e` environments.
+ *                             documented behavior of the `local`/`ci`/`e2e` environments, and
+ *                             a host-split localhost `baseUrl` falls back to them.
  *
  * @since 11.27.5
  */
@@ -409,13 +468,29 @@ export function resolveServerUrls(input: {
     return { appUrl: input.appUrl, appUrlSource: 'explicit', baseUrl, baseUrlSource };
   }
 
-  // API on :3000 and app on :3001 — deriving from baseUrl would yield the API's own origin.
-  if (usesLocalhostDefaults && isLocalhostUrl(baseUrl)) {
+  const mayDerive = input.deriveAppUrl !== false;
+
+  // Parse `baseUrl` once and reuse the result for both the host-split check and the derivation
+  // below (the localhost check keeps its own string parse — its loopback-IP matching differs
+  // from `toHttpUrl`'s http(s)-only guard). Gated on `mayDerive`: both consumers of
+  // `parsedBaseUrl` sit behind it (the host-split check via short-circuit, the derivation via its
+  // own guard), so with `deriveAppUrl: false` the parse is never needed and is skipped entirely.
+  const parsedBaseUrl = baseUrl && mayDerive ? toHttpUrl(baseUrl) : undefined;
+
+  // API on :3000 and app on :3001 — deriving from a port-split baseUrl would yield the API's
+  // own origin. A baseUrl that splits API and app by host instead (`https://api.crm.localhost`,
+  // from `lt dev up`) derives the real app origin, so prefer it over the flat default.
+  // `separatesApiAndAppByHost` is evaluated last, so every deployed (non-localhost) environment
+  // short-circuits before paying for the parse.
+  if (usesLocalhostDefaults && isLocalhostUrl(baseUrl) && !(mayDerive && separatesApiAndAppByHost(parsedBaseUrl))) {
     return { appUrl: LOCALHOST_URL_DEFAULTS.appUrl, appUrlSource: 'localhost-default', baseUrl, baseUrlSource };
   }
 
-  if (baseUrl && input.deriveAppUrl !== false) {
-    return { appUrl: deriveAppUrlFromBaseUrl(baseUrl), appUrlSource: 'derived', baseUrl, baseUrlSource };
+  if (baseUrl && mayDerive) {
+    // `parsedBaseUrl` is mutated by `deriveAppOriginFromUrl`; a non-http(s) `baseUrl` (parse
+    // failed) is returned verbatim, matching `deriveAppUrlFromBaseUrl`.
+    const appUrl = parsedBaseUrl ? deriveAppOriginFromUrl(parsedBaseUrl) : baseUrl;
+    return { appUrl, appUrlSource: 'derived', baseUrl, baseUrlSource };
   }
 
   return { appUrl: undefined, appUrlSource: 'none', baseUrl, baseUrlSource };

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