@lenne.tech/nest-server 11.27.5 → 11.27.7

package/migration-guides/11.27.6-to-11.27.7.md

@@ -0,0 +1,374 @@
+# Migration Guide: 11.27.6 → 11.27.7
+
+## Overview
+
+| Category | Details |
+|----------|---------|
+| **Breaking Changes** | None |
+| **New Features** | None. Four new leaf modules (`core-better-auth.constants.ts`, `core-better-auth.registry.ts`, `id.helper.ts`, `clone.helper.ts`) — the tokens and helpers they hold were already public and stay reachable from their old locations. The registry is module-internal and deliberately **not** exported. |
+| **Public API** | Unchanged. Verified by diffing the full export surface of `src/index.ts` on both versions: **nothing removed, nothing renamed**. |
+| **Bugfixes** | **(1)** Applications compiled with **SWC** (`nest start -b swc`, `nest build -b swc`) no longer crash at startup with `ReferenceError: Cannot access 'BETTER_AUTH_INSTANCE' before initialization` when BetterAuth is enabled. **(2)** A direct import of `core/common/inputs/combined-filter.input` no longer crashes under SWC with `ReferenceError: Cannot access 'CombinedFilterInput' before initialization`. **(3)** A consumer setting `betterAuth.options.advanced.defaultCookieAttributes` no longer silently strips the `Secure` flag from session cookies on an `https://` deployment. |
+| **Security** | See bugfix (3). If your project sets `advanced.defaultCookieAttributes` for any reason (cookie partitioning, a custom domain) **and** runs on an `https://` baseURL, your session cookies were being sent without `Secure`. Updating fixes this with no action required. |
+| **Deprecations** | The BetterAuth DI tokens re-exported from `core-better-auth.module` / `core-better-auth.service` are now marked deprecated in their docblocks. Import them from `core-better-auth.constants` (or the package root) instead. Both paths keep working. |
+| **Toolchain** | The framework repo moved to **pnpm 11** (see the note below). **npm consumers are unaffected** — you do not inherit the framework's `packageManager` or `pnpm-workspace.yaml`. Relevant only if you contribute to the framework or mirror its toolchain. |
+| **Migration Effort** | **npm mode:** 0 minutes (automatic) — `pnpm update` is enough. **Vendor mode:** see the note below — the BetterAuth change is an atomic file set. |
+
+This is a **startup-crash + cookie-security bugfix release**. No source-code or
+config changes are required in consuming projects.
+
+---
+
+## Toolchain: pnpm 11 (framework contributors only)
+
+**npm consumers of `@lenne.tech/nest-server` can ignore this section** — installing the
+package does not import our package manager or its config.
+
+The framework repo itself upgraded from pnpm 10 to **pnpm 11**, for one concrete reason:
+**`pnpm audit` is broken on every pnpm 10.x** — npm retired the legacy audit endpoint
+(HTTP 410) and only pnpm 11 uses the working bulk-advisory endpoint. The upgrade also
+required migrating pnpm's config, because pnpm 11 has breaking changes:
+
+- **The `pnpm` field in `package.json` is gone.** All pnpm settings moved to
+  `pnpm-workspace.yaml`: `overrides`, `allowBuilds`, `nodeLinker`, `autoInstallPeers`,
+  `strictPeerDependencies`, `peerDependencyRules`. `.npmrc` is now auth/registry only.
+- **`allowBuilds` replaced `onlyBuiltDependencies`** — a map that must classify *every*
+  package with an install script as `true` (build it, e.g. `bcrypt`) or `false` (don't,
+  e.g. the `@scarf/scarf` telemetry). An unclassified build-script package makes
+  `pnpm install` exit non-zero.
+- **Security overrides pruned 36 → 9.** Only entries still load-bearing (removing them
+  lets the package resolve back into its vulnerable range) were kept; `pnpm audit` on
+  pnpm 11 confirms the pruned set is still clean.
+
+CI (`pnpm/action-setup`) and Docker (`corepack`) follow the `packageManager` field, so no
+workflow or Dockerfile edits were needed — they use pnpm 11 automatically.
+
+**If you develop against or vendor the framework's toolchain:** switch to pnpm 11
+(`corepack use pnpm@11` or let corepack follow `packageManager`), and move any
+`package.json#pnpm` settings you have into `pnpm-workspace.yaml`. See
+`.claude/rules/package-management.md` for the full pattern.
+
+---
+
+## Quick Migration
+
+No code changes required.
+
+```bash
+# Update package
+pnpm add @lenne.tech/nest-server@11.27.7
+
+# Verify build
+pnpm run build
+
+# Run tests
+pnpm test
+```
+
+---
+
+## What's Fixed in 11.27.7
+
+### Startup crash under the SWC compiler
+
+**The symptom.** With BetterAuth enabled and the app started or built via SWC:
+
+```
+ReferenceError: Cannot access 'BETTER_AUTH_INSTANCE' before initialization
+    at core-better-auth.module.ts
+    at core-better-auth.service.ts
+```
+
+This affected anyone using `nest start -b swc` / `nest build -b swc` — including
+the `start:dev:swc` and `start:local:swc` scripts shipped in the starter. Projects
+building with the default `tsc` builder were **not** affected.
+
+**The bug.** The three BetterAuth dependency-injection tokens were split across two
+files that imported each other:
+
+- `BETTER_AUTH_INSTANCE` was declared in `core-better-auth.module.ts`
+- `BETTER_AUTH_CONFIG` and `BETTER_AUTH_COOKIE_DOMAIN` were declared in `core-better-auth.service.ts`
+
+The service imported the first token from the module, and the module imported the
+other two — plus the service class itself — back from the service. A genuine import
+cycle.
+
+The cycle alone would have been survivable. What made it fatal is *when* the token
+is read: `@Inject(BETTER_AUTH_INSTANCE)` is a **constructor-parameter decorator**,
+and decorator arguments are evaluated when the class is *defined* — that is, while
+the module is still initializing. On a cycle, the importing side reads a `const`
+that is still in its temporal dead zone.
+
+Under `tsc`/CommonJS the evaluation order happened to work out. Under SWC it did
+not, and the app died at startup.
+
+**The fix.** All three tokens moved into a new **import-free leaf module**,
+`core-better-auth.constants.ts`. A file with zero imports can never be
+mid-evaluation when someone imports it — in any module system, under any compiler —
+so the initialization order is now deterministic everywhere.
+
+A second leaf, `core-better-auth.registry.ts`, does the same for the
+`BetterAuthTokenService` reference that `BetterAuthRolesGuard` looks up statically,
+removing the last import cycle inside the module. As a side effect this also fixes a
+test-isolation leak: `CoreBetterAuthModule.reset()` previously did not clear that
+reference, so a token service could survive into the next testing module.
+
+---
+
+## Deprecations
+
+The tokens are still re-exported from their old locations, so **every existing import
+keeps working**:
+
+```typescript
+// Still works (now @deprecated)
+import { BETTER_AUTH_INSTANCE } from '@lenne.tech/nest-server/dist/core/modules/better-auth/core-better-auth.module';
+import { BETTER_AUTH_CONFIG } from '@lenne.tech/nest-server/dist/core/modules/better-auth/core-better-auth.service';
+
+// Preferred
+import { BETTER_AUTH_CONFIG, BETTER_AUTH_INSTANCE } from '@lenne.tech/nest-server';
+```
+
+Importing from the package root (`@lenne.tech/nest-server`) was already the
+recommended path and is unaffected — **most projects need to change nothing.**
+
+The deprecated re-exports will be removed in a future MINOR.
+
+> **The token string values are unchanged** (`'BETTER_AUTH_INSTANCE'`,
+> `'BETTER_AUTH_CONFIG'`, `'BETTER_AUTH_COOKIE_DOMAIN'`), so `@Inject('BETTER_AUTH_INSTANCE')`
+> written as a string literal keeps resolving. A new unit test pins these values
+> precisely because they are part of the public contract.
+
+---
+
+## Vendor Mode: five atomic file sets
+
+Projects that vendor the framework core (`projects/api/src/core/`) sync via the
+`/lt-dev:backend:update-nest-server-core` agent rather than `pnpm update`.
+
+Every change in this release works the same way: a symbol moved into a new **leaf**
+file, and its old home now re-exports it. That makes each one an **atomic set** —
+adopt the edits without the new file and you get an unresolvable import and a broken
+build.
+
+**Seven files are new.** If a sync is interrupted, verify all seven exist before
+building:
+
+```
+core/modules/better-auth/core-better-auth.constants.ts
+core/modules/better-auth/core-better-auth.registry.ts
+core/modules/ai/core-ai.constants.ts
+core/modules/ai/interfaces/ai-interaction-record.interface.ts
+core/modules/tus/tus.constants.ts
+core/common/helpers/id.helper.ts
+core/common/helpers/clone.helper.ts
+```
+
+> **Expect merge conflicts on locally-patched files.** If your project has local edits
+> in `db.helper.ts`, `input.helper.ts`, `filter.input.ts`, `restricted.decorator.ts`
+> or any `ai/services/*.service.ts`, this release moves code *out* of them — the sync
+> will conflict there. The resolution is always the same: keep your local logic, keep
+> the new `import` + `export … from` lines pointing at the leaf, and do not restore the
+> declarations that moved out.
+
+**Set 1 — BetterAuth DI tokens**
+
+| File | Change |
+|------|--------|
+| `core/modules/better-auth/core-better-auth.constants.ts` | 🆕 the token leaf |
+| `core/modules/better-auth/core-better-auth.registry.ts` | 🆕 the token-service leaf |
+| `core/modules/better-auth/core-better-auth.module.ts` | takes tokens from the constants leaf; delegates the token-service lookup to the registry |
+| `core/modules/better-auth/core-better-auth.service.ts` | takes tokens from the constants leaf |
+| `core/modules/better-auth/better-auth-roles.guard.ts` | reads the registry instead of importing the module |
+| `core/modules/better-auth/index.ts` | exports the constants leaf (the registry is deliberately **not** exported — it is module-internal) |
+
+**Set 2 — core helpers** (this is what takes `restricted.decorator` off its cycles)
+
+| File | Change |
+|------|--------|
+| `core/common/helpers/id.helper.ts` | 🆕 the ID cluster (`equalIds`, `getIncludedIds`, `getStringIds`, `getObjectIds`) |
+| `core/common/helpers/clone.helper.ts` | 🆕 `clone`, `deepFreeze` |
+| `core/common/helpers/db.helper.ts` | ID cluster removed; **re-exports it** from `id.helper` |
+| `core/common/helpers/input.helper.ts` | `clone`/`deepFreeze` removed; **re-exports them** from `clone.helper`; takes `equalIds` from `id.helper` |
+| `core/common/services/config.service.ts` | takes `clone`/`deepFreeze` from `clone.helper` |
+| `core/common/decorators/restricted.decorator.ts` | takes the ID helpers from `id.helper`; its three exports become hoisted `function` declarations |
+
+**Set 3 — filter inputs**
+
+| File | Change |
+|------|--------|
+| `core/common/inputs/filter.input.ts` | now declares **both** `CombinedFilterInput` (first) and `FilterInput` — the order is load-bearing |
+| `core/common/inputs/combined-filter.input.ts` | reduced to a re-export shim |
+
+**Set 4 — AI module** (22 DI tokens + the type that closed the last AI cycle)
+
+| File | Change |
+|------|--------|
+| `core/modules/ai/core-ai.constants.ts` | 🆕 all 22 `AI_*_MODEL` / `AI_*_CLASS` tokens |
+| `core/modules/ai/interfaces/ai-interaction-record.interface.ts` | 🆕 `AiInteractionRecord` |
+| `core/modules/ai/services/*.service.ts` (11 files) | tokens removed; each **re-exports its own** from the constants leaf |
+| `core/modules/ai/services/core-ai.service.ts` | `AiInteractionRecord` removed; **re-exports it** from the interface leaf |
+| `core/modules/ai/services/core-ai-interaction.service.ts` | takes the type from the interface leaf — no longer imports `core-ai.service` at all |
+| `core/modules/ai/index.ts` | exports the interface leaf |
+
+> If your project registered custom AI models via these tokens, nothing changes —
+> the values are unchanged and every old import path still resolves.
+
+**Set 5 — TUS module**
+
+| File | Change |
+|------|--------|
+| `core/modules/tus/tus.constants.ts` | 🆕 `TUS_CONFIG` |
+| `core/modules/tus/tus.module.ts` | token removed; **re-exports it** from the leaf |
+
+---
+
+> ### Do not "clean up" the re-export lines
+>
+> `db.helper.ts`, `input.helper.ts`, `combined-filter.input.ts`, `core-better-auth.module.ts`,
+> `core-better-auth.service.ts`, `tus.module.ts`, `core-ai.service.ts` and all eleven
+> `ai/services/*.service.ts` files now carry `export { … } from './…'` lines that look
+> exactly like dead code.
+>
+> They are not. They are the *entire* backward-compatibility layer: this package has no
+> `exports` map, so consumers deep-import these files directly, and deleting one line
+> breaks every one of them — **with nothing turning red**, because the symbol is still
+> exported from the package root.
+>
+> The framework pins them with a test (`tests/unit/import-cycle-invariants.spec.ts`) for
+> exactly this reason. Keep the equivalent lines in your vendored copy.
+
+---
+
+## Also fixed: `CombinedFilterInput` crashed on a direct import
+
+Same bug class, different module. `FilterInput` and `CombinedFilterInput` lived in
+two files that imported each other, and `FilterInput` referenced
+`CombinedFilterInput` **eagerly** — in a decorator argument and in the `design:type`
+metadata `emitDecoratorMetadata` emits. Under SWC:
+
+```
+require('.../core/common/inputs/combined-filter.input.js')
+→ ReferenceError: Cannot access 'CombinedFilterInput' before initialization
+```
+
+This only stayed hidden because importing from the package root pulls `filter.input`
+in first. A **deep import** of `combined-filter.input` — plausible in vendor mode or
+in a unit test — hit the crash.
+
+Both classes now live in `filter.input.ts` (declaration order matters), and
+`combined-filter.input.ts` re-exports `CombinedFilterInput`. **Every existing import
+path still resolves**, including deep imports of either file.
+
+---
+
+## Also fixed (security): `Secure` could be stripped from session cookies
+
+If a project sets `betterAuth.options.advanced.defaultCookieAttributes` — for cookie
+partitioning, a custom domain, anything — that object **wholesale-replaced** the
+framework's own `{ secure: true }`, because the merge was shallow. On an `https://`
+baseURL the result was session cookies without the `Secure` attribute, forwarded
+verbatim by BetterAuth's native handlers (2FA verify, social callback, magic link).
+No error, no warning.
+
+```ts
+// Before 11.27.7 — on an https baseURL:
+betterAuth: { options: { advanced: { defaultCookieAttributes: { partitioned: true } } } }
+// → Set-Cookie: iam.session_token=…; HttpOnly; SameSite=Lax        ← Secure GONE
+```
+
+The merge is now deep for that one key: `secure: true` is the base and your keys
+spread over it. An **explicit** `{ secure: false }` still wins — this guards against
+silent clobbering, not against a deliberate choice.
+
+**No action required.** If you set `defaultCookieAttributes` and run on HTTPS, the
+fix applies automatically on update.
+
+---
+
+## New: SWC regression guard
+
+The bug had the worst possible failure profile — **it passed a fully green CI and
+crashed only for consumers.** `nest build` uses `tsc`, and vitest runs SWC through
+Vite's module runner, whose getter-based live bindings tolerate import cycles. So
+neither the build nor 2000+ tests could see it.
+
+A new check step closes that hole:
+
+```bash
+pnpm run check:swc-tdz
+# = nest build -b swc -p tsconfig.swc-tdz.json && node scripts/check-swc-tdz.mjs
+```
+
+It compiles with SWC to CommonJS and loads **every compiled module as its own entry
+point** under Node's CJS loader — the exact path that fails.
+
+Loading only the package barrel is *not* sufficient, and that is not a theoretical
+point: whether such a cycle throws depends on which module the graph is entered
+through. The `CombinedFilterInput` crash above was invisible to a barrel-only load,
+because the barrel happens to pull `filter.input` in first. Requiring each file
+separately is what surfaces it.
+
+It builds into its own throwaway directory (`dist-swc-tdz/`, removed on success,
+kept on failure so you can inspect the emit), so it never touches your real `dist/`.
+It is wired into `check:raw` — ahead of the test step, so a cycle fails in seconds
+rather than after the full suite — and into the CI workflow.
+
+### Copying it into your own project
+
+**Worth doing if you build or run with SWC** (`nest start -b swc`, `start:dev:swc`):
+it costs a few seconds, needs no database, and is the only thing that catches this
+bug class.
+
+Note that `scripts/` is **not** part of the published npm package, so you cannot
+copy it out of `node_modules`. Take the three pieces from the repository:
+
+- [`scripts/check-swc-tdz.mjs`](https://github.com/lenneTech/nest-server/blob/develop/scripts/check-swc-tdz.mjs)
+- [`tsconfig.swc-tdz.json`](https://github.com/lenneTech/nest-server/blob/develop/tsconfig.swc-tdz.json)
+- the `check:swc-tdz` script entry in `package.json`, plus `dist-swc-tdz` in `.gitignore`
+
+Then add `pnpm run check:swc-tdz` to your own `check` chain (before the tests, so it
+fails fast) and to CI.
+
+> **Vendor-mode projects should treat this as required, not optional.** You copy
+> `src/core/` into your own tree, where a local edit can re-introduce exactly this
+> kind of cycle — and your `tsc` build and your test suite will both stay green while
+> it does.
+
+---
+
+## Compatibility Notes
+
+| Pattern | Status |
+|---------|--------|
+| Importing tokens from `@lenne.tech/nest-server` (package root) | ✅ Unchanged |
+| Deep-importing tokens from `core-better-auth.module` / `.service` | ✅ Works, now `@deprecated` |
+| `@Inject('BETTER_AUTH_INSTANCE')` as a string literal | ✅ Unchanged (values pinned by test) |
+| Custom `{ provide: BETTER_AUTH_INSTANCE, useValue: ... }` overrides | ✅ Unchanged |
+| Extending `BetterAuthRolesGuard` | ✅ Unchanged public behavior |
+| `CoreBetterAuthModule.getTokenServiceInstance()` | ✅ Unchanged (now delegates to the registry) |
+| Building with `tsc` (default) | ✅ Was never affected |
+| Building with SWC | ✅ **Fixed** |
+
+---
+
+## Troubleshooting
+
+**`ReferenceError: Cannot access 'BETTER_AUTH_INSTANCE' before initialization`**
+You are still on ≤ 11.27.6 with an SWC build. Update to 11.27.7.
+
+**Vendor mode: `Cannot find module './core-better-auth.constants'`**
+The sync did not create the new leaf file(s). Re-run the core update and confirm
+both `core-better-auth.constants.ts` and `core-better-auth.registry.ts` exist in
+`src/core/modules/better-auth/`.
+
+**Deprecation warnings on the token imports**
+Expected. Switch the import to the package root (`@lenne.tech/nest-server`) or to
+`core-better-auth.constants`. No behavior change either way.
+
+---
+
+## Module Documentation
+
+- [BetterAuth README](../src/core/modules/better-auth/README.md)
+- [BetterAuth Integration Checklist](../src/core/modules/better-auth/INTEGRATION-CHECKLIST.md)
+- [BetterAuth Customization](../src/core/modules/better-auth/CUSTOMIZATION.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nest-server",
-  "version": "11.27.5",
+  "version": "11.27.7",
   "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",
@@ -23,9 +23,10 @@
     "build:dev": "pnpm run build",
     "c": "pnpm run check",
     "check": "node scripts/check.mjs",
-    "check:raw": "pnpm audit && pnpm run format:check && pnpm run lint && pnpm test && pnpm run build && bash scripts/check-server-start.sh",
-    "check:fix": "pnpm install && pnpm audit --fix && pnpm run format && pnpm run lint:fix && pnpm test && pnpm run build && bash scripts/check-server-start.sh",
-    "check:naf": "pnpm install && pnpm run format && pnpm run lint:fix && pnpm test && pnpm run build && bash scripts/check-server-start.sh",
+    "check:raw": "pnpm audit && pnpm run format:check && pnpm run lint && pnpm run check:swc-tdz && pnpm test && pnpm run build && bash scripts/check-server-start.sh",
+    "check:fix": "pnpm install && pnpm audit --fix && pnpm run format && pnpm run lint:fix && pnpm run check:swc-tdz && pnpm test && pnpm run build && bash scripts/check-server-start.sh",
+    "check:naf": "pnpm install && pnpm run format && pnpm run lint:fix && pnpm run check:swc-tdz && pnpm test && pnpm run build && bash scripts/check-server-start.sh",
+    "check:swc-tdz": "nest build -b swc -p tsconfig.swc-tdz.json && node scripts/check-swc-tdz.mjs",
     "cf": "pnpm run check:fix",
     "cnaf": "pnpm run check:naf",
     "docs": "pnpm run docs:ci && open http://127.0.0.1:8080/ && open ./public/index.html && compodoc -p tsconfig.json -s ",
@@ -48,8 +49,9 @@
     "start:dev:swc": "nest start -b swc -w --type-check",
     "start:local": "NODE_ENV=local nodemon",
     "start:local:swc": "NODE_ENV=local nest start -b swc -w --type-check",
-    "test": "pnpm run vitest",
-    "test:ci": "pnpm run vitest:ci",
+    "test": "pnpm run vitest:unit && pnpm run vitest",
+    "test:ci": "pnpm run vitest:unit && pnpm run vitest:ci",
+    "test:cov": "pnpm run vitest:unit:cov && pnpm run vitest:cov",
     "test:e2e": "pnpm run vitest",
     "prepack": "pnpm run prestart:prod",
     "prepublishOnly": "pnpm run lint && pnpm run test:ci",
@@ -59,6 +61,7 @@
     "vitest:cov": "NODE_ENV=e2e vitest run --coverage --config vitest-e2e.config.ts",
     "vitest:watch": "NODE_ENV=e2e vitest --config vitest-e2e.config.ts",
     "vitest:unit": "vitest run --config vitest.config.ts",
+    "vitest:unit:cov": "vitest run --coverage --config vitest.config.ts",
     "test:unit:watch": "vitest --config vitest.config.ts",
     "test:types": "tsc --noEmit --skipLibCheck -p tests/types/tsconfig.json",
     "test:cleanup": "find tests -type f \\( -name '*.txt' -o -name '*.bin' \\) -not -name '.gitkeep' -delete && echo 'Test artifacts cleaned up'",
@@ -72,7 +75,7 @@
     "url": "https://github.com/lenneTech/nest-server/issues"
   },
   "engines": {
-    "node": ">= 20"
+    "node": ">= 22"
   },
   "dependencies": {
     "@apollo/server": "5.5.1",
@@ -181,101 +184,5 @@
   "watch": {
     "build:dev": "src"
   },
-  "packageManager": "pnpm@10.33.2",
-  "pnpm": {
-    "//overrides": {
-      "axios@<1.16.0": "Security: Multiple CVEs in axios <1.15.2 (SSRF via NO_PROXY, prototype pollution, header injection, CRLF injection in form-data, XSRF leakage, auth bypass, response tampering, no_proxy IP alias bypass, streamed upload/response bypass, toFormData DoS, null byte injection) - transitive via @getbrevo/brevo and node-mailjet. Remove when @getbrevo/brevo and node-mailjet ship axios>=1.16.0",
-      "fast-uri@<3.1.2": "Security: host confusion (GHSA-3vp4-mxqf-vmh4) and path traversal (GHSA-q4mq-mw7v-xq57) in fast-uri <3.1.2 - transitive via @compodoc/compodoc>@angular-devkit/schematics>@angular-devkit/core>ajv",
-      "@babel/plugin-transform-modules-systemjs@>=7.12.0 <7.29.4": "Security: prototype pollution-based variable shadowing (GHSA-7p7r-hpq8-6w8q) generates unsafe code - transitive via @compodoc/compodoc>@babel/preset-env",
-      "minimatch@<3.1.5": "Security: RegExp DoS (GHSA-p8p7-x288-28g6) - transitive via @getbrevo/brevo>rewire>eslint",
-      "minimatch@>=9.0.0 <9.0.9": "Security: RegExp DoS - transitive via @nestjs/cli>@swc/cli",
-      "minimatch@>=10.0.0 <10.2.5": "Security: RegExp DoS - transitive via @nestjs/apollo>ts-morph>@ts-morph/common and nodemon",
-      "ajv@<6.14.0": "Security: prototype pollution - transitive via @getbrevo/brevo>rewire>eslint",
-      "ajv@>=7.0.0-alpha.0 <8.18.0": "Security: prototype pollution - transitive via @nestjs/cli>@angular-devkit",
-      "undici@>=7.0.0 <7.28.0": "Security: various CVEs <7.28.0 (incl. high) - transitive via @compodoc/compodoc>cheerio + better-auth",
-      "piscina@<4.9.3": "Security: high CVE in piscina <4.9.3 - transitive via the build/test toolchain",
-      "@babel/core@<7.29.6": "Security: @babel/core <7.29.6 advisory - transitive via @compodoc/compodoc>@babel/preset-env",
-      "handlebars@>=4.0.0 <4.7.9": "Security: prototype pollution (GHSA-q42p-pg8m-cqh6) - transitive via @compodoc/compodoc",
-      "brace-expansion@<1.1.13": "Security: RegExp DoS - transitive via eslint>minimatch",
-      "brace-expansion@>=4.0.0 <5.0.6": "Security: RegExp DoS - Large numeric range defeats brace expansion (GHSA-jxxr-4gwj-5jf2) - transitive via nodemon>minimatch and @ts-morph/common>minimatch and @compodoc/compodoc>glob>minimatch",
-      "picomatch@<2.3.2": "Security: ReDoS - transitive via @nestjs/graphql>fast-glob>micromatch and @compodoc/compodoc>chokidar",
-      "picomatch@>=4.0.0 <4.0.4": "Security: ReDoS - transitive via vitest and vite",
-      "path-to-regexp@>=8.0.0 <8.4.2": "Security: ReDoS (GHSA-rhx6-c78j-4q9w) - transitive via express>router",
-      "kysely@>=0.26.0 <0.28.17": "Security: JSON-path traversal injection via unsanitized input (SQL injection) - transitive via better-auth>@better-auth/passkey>@better-auth/core",
-      "@protobufjs/utf8@<=1.1.0": "Security: overlong UTF-8 decoding - transitive via @apollo/server>@apollo/usage-reporting-protobuf",
-      "ws@>=8.0.0 <8.21.0": "Security: Memory exhaustion DoS + uninitialized memory disclosure (GHSA-96hv-2xvq-fx4p) - transitive via @nestjs/graphql",
-      "ws@>=7.0.0 <7.5.11": "Security: Memory exhaustion DoS in ws 7.x (GHSA-96hv-2xvq-fx4p) - transitive via @nestjs/graphql>subscriptions-transport-ws",
-      "qs@>=6.11.1 <=6.15.1": "Security: remotely triggerable DoS in qs.stringify with comma-format arrays (GHSA-q8mj-m7cp-5q26) - transitive via @compodoc/compodoc>body-parser",
-      "lodash@>=4.0.0 <4.18.0": "Security: CVE in lodash@4.17.x - transitive via @nestjs/graphql. 4.18.1 is the latest patched version",
-      "defu@<=6.1.6": "Security: prototype pollution via __proto__ key - transitive via better-auth",
-      "follow-redirects@<=1.15.11": "Security: Custom Authentication Headers leak on cross-domain redirect (GHSA-r4q5-vmmm-2653) - transitive via axios>@getbrevo/brevo and axios>node-mailjet",
-      "uuid@<14.0.0": "Security: Missing buffer bounds check in v3/v5/v6 (GHSA-w5hq-g745-h8pq) - transitive via @compodoc/compodoc and @compodoc/compodoc>@compodoc/live-server>http-auth",
-      "postcss@<8.5.10": "Security: XSS via Unescaped </style> in CSS Stringify Output (GHSA-qx2v-qp2m-jg93) - transitive via vite. Remove when vite ships with postcss>=8.5.10",
-      "form-data@<4.0.6": "Security: CRLF injection via unescaped multipart field names/filenames (GHSA-hmw2-7cc7-3qxx) - transitive via @getbrevo/brevo>axios and node-mailjet>axios",
-      "vite@>=8.0.0 <8.0.16": "Security: fs.deny bypass on Windows alternate paths + file read CVEs - transitive via better-auth>vitest",
-      "hono@<4.12.25": "Security: multiple CVEs <4.12.25 (prototype pollution, bodyLimit/Vary bypass, JWT NumericDate) - transitive via @nestjs/terminus>prisma>@prisma/dev",
-      "nodemailer@<9.0.1": "Security: email/header injection CVEs <9.0.1 - direct dependency",
-      "multer@<2.2.0": "Security: unhandled multipart errors / DoS <2.2.0 - transitive via @nestjs/platform-express",
-      "js-yaml@<4.2.0": "Security: special-character handling / prototype pollution (patched in 4.2.0; 4.1.2 was never published) - transitive via @nestjs/swagger",
-      "@xhmikosr/decompress@<11.1.3": "Security: archive extraction can create files/links outside the target directory (GHSA-mp2f-45pm-3cg9, critical) - transitive via @swc/cli>@xhmikosr/bin-wrapper>@xhmikosr/downloader; @swc/cli 0.8.1 is already the latest release and still resolves the vulnerable range, so an override is the only fix"
-    },
-    "overrides": {
-      "axios@<1.16.0": "1.16.0",
-      "fast-uri@<3.1.2": "3.1.2",
-      "@babel/plugin-transform-modules-systemjs@>=7.12.0 <7.29.4": "7.29.4",
-      "minimatch@<3.1.5": "3.1.5",
-      "minimatch@>=9.0.0 <9.0.9": "9.0.9",
-      "minimatch@>=10.0.0 <10.2.5": "10.2.5",
-      "ajv@<6.14.0": "6.14.0",
-      "ajv@>=7.0.0-alpha.0 <8.18.0": "8.18.0",
-      "undici@>=7.0.0 <7.28.0": "7.28.0",
-      "piscina@<4.9.3": "4.9.3",
-      "@babel/core@<7.29.6": "7.29.6",
-      "handlebars@>=4.0.0 <4.7.9": "4.7.9",
-      "brace-expansion@<1.1.13": "1.1.13",
-      "brace-expansion@>=4.0.0 <5.0.6": "5.0.6",
-      "picomatch@<2.3.2": "2.3.2",
-      "picomatch@>=4.0.0 <4.0.4": "4.0.4",
-      "path-to-regexp@>=8.0.0 <8.4.2": "8.4.2",
-      "kysely@>=0.26.0 <0.28.17": "0.28.17",
-      "@protobufjs/utf8@<=1.1.0": "1.1.1",
-      "ws@>=8.0.0 <8.21.0": "8.21.0",
-      "ws@>=7.0.0 <7.5.11": "7.5.11",
-      "qs@>=6.11.1 <=6.15.1": "6.15.2",
-      "lodash@>=4.0.0 <4.18.0": "4.18.1",
-      "defu@<=6.1.6": "6.1.7",
-      "follow-redirects@<=1.15.11": "1.16.0",
-      "uuid@<14.0.0": "14.0.0",
-      "postcss@<8.5.10": "8.5.12",
-      "esbuild@>=0.17.0 <0.28.1": "0.28.1",
-      "form-data@<4.0.6": "4.0.6",
-      "vite@>=8.0.0 <8.0.16": "8.0.16",
-      "hono@<4.12.25": "4.12.25",
-      "nodemailer@<9.0.1": "9.0.1",
-      "multer@<2.2.0": "2.2.0",
-      "js-yaml@<4.2.0": "4.2.0",
-      "@xhmikosr/decompress@<11.1.3": "11.1.3"
-    },
-    "//peerDependencyRules": "allowedVersions: deps lag behind our newer majors (graphql-upload wants @types/express@^4, the deprecated apollo playground plugin wants @apollo/server@^4) — both work with our v5. ignoreMissing: browser-only vis-network peers pulled in transitively via yuml-diagram (server-side UML generation never renders, so these are not needed).",
-    "peerDependencyRules": {
-      "allowedVersions": {
-        "@apollo/server": "5",
-        "@types/express": "5"
-      },
-      "ignoreMissing": [
-        "@egjs/hammerjs",
-        "keycharm",
-        "vis-data",
-        "vis-util"
-      ]
-    },
-    "onlyBuiltDependencies": [
-      "bcrypt",
-      "@swc/core",
-      "esbuild",
-      "@nestjs/core",
-      "@compodoc/compodoc",
-      "@apollo/protobufjs"
-    ]
-  }
+  "packageManager": "pnpm@11.13.0"
 }

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

@@ -1,10 +1,35 @@
+/**
+ * NOTE ON `export function` VS `export const` (do not "modernize" these to arrow functions).
+ *
+ * `Restricted`, `getRestricted` and `checkRestricted` are declared as FUNCTION DECLARATIONS on
+ * purpose. This file sits on an import cycle:
+ *
+ *   restricted.decorator → helpers/db.helper → helpers/input.helper → restricted.decorator
+ *
+ * so when `input.helper`'s module body runs, THIS module is still mid-evaluation. A `const` arrow is
+ * a temporal-dead-zone binding: any evaluation-time read of it from `input.helper` (a top-level
+ * alias, an `@Restricted`-decorated class, `design:type` metadata) would throw under SWC → CommonJS:
+ *
+ *   ReferenceError: Cannot access 'checkRestricted' before initialization
+ *
+ * Function declarations are HOISTED and fully initialized before any module body runs, so they are
+ * immune. `input.helper` today only calls `checkRestricted` from inside a function body, which is
+ * why nothing has crashed — but that is one careless top-level line away, in the file that drives
+ * field-level access control. The hoisting removes the hazard rather than relying on vigilance.
+ *
+ * The proper fix is to break the cycle (extract the ID helpers out of `db.helper` into a leaf), and
+ * that is worth doing. Until then, `pnpm run check:swc-tdz` is the mechanical guard.
+ * See .claude/rules/architecture.md → "DI Token Placement (SWC-Safe)".
+ */
 import { UnauthorizedException } from '@nestjs/common';
 import 'reflect-metadata';
 import _ = require('lodash');
 
 import { ProcessType } from '../enums/process-type.enum';
 import { RoleEnum } from '../enums/role.enum';
-import { equalIds, getIncludedIds } from '../helpers/db.helper';
+// 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';
@@ -40,9 +65,9 @@ export type RestrictedType = (
  *    properties of the processed item, which is specified by the value of `memberOf`
  *    Via processType the restriction can be set for input or output only
  */
-export const Restricted = (...rolesOrMember: RestrictedType): ClassDecorator & PropertyDecorator => {
+export function Restricted(...rolesOrMember: RestrictedType): ClassDecorator & PropertyDecorator {
   return Reflect.metadata(restrictedMetaKey, rolesOrMember);
-};
+}
 
 /**
  * Cache for Restricted metadata — decorators are static, metadata never changes at runtime.
@@ -60,7 +85,7 @@ const restrictedMetadataCache = new WeakMap<object, Map<string, RestrictedType>>
 /**
  * Get restricted data for (property of) object
  */
-export const getRestricted = (object: unknown, propertyKey?: string): RestrictedType => {
+export function getRestricted(object: unknown, propertyKey?: string): RestrictedType {
   if (!object) {
     return null;
   }
@@ -94,13 +119,13 @@ export const getRestricted = (object: unknown, propertyKey?: string): Restricted
 
   classCache.set(cacheKey, metadata);
   return metadata;
-};
+}
 
 /**
  * Check data for restricted properties (properties with `Restricted` decorator)
  * For special Roles and member of group checking the dbObject must be set in options
  */
-export const checkRestricted = (
+export function checkRestricted(
   data: any,
   user: {
     emailVerified?: any;
@@ -125,7 +150,7 @@ export const checkRestricted = (
     throwError?: boolean;
   } = {},
   processedObjects: WeakSet<object> = new WeakSet(),
-) => {
+) {
   // Act like Roles handling: checkObjectItself = false & mergeRoles = true
   // For Input: throwError = true
   // For Output: throwError = false
@@ -394,4 +419,4 @@ export const checkRestricted = (
 
   // Return processed data
   return data;
-};
+}