@lenne.tech/nest-server 11.27.6 → 11.28.0

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

@@ -0,0 +1,350 @@
+# Migration Guide: 11.27.7 → 11.28.0
+
+> Coming from 11.27.6 or earlier? Read [11.27.6 → 11.27.7](./11.27.6-to-11.27.7.md) first — it is a
+> separate startup-crash + cookie-security bugfix release with no overlap with the changes here.
+
+## Overview
+
+| Category | Details |
+|----------|---------|
+| **Breaking Changes** | **(1)** Permission errors for **authenticated** users now return **403 Forbidden** instead of 401 Unauthorized. **(2)** `@Roles(S_NO_ONE)` / `@Restricted(S_NO_ONE)` now return **403 for every requester**, including unauthenticated ones (was 401). **(3)** The **error messages** of these denials changed from raw English strings to the translatable `ErrorCode.ACCESS_DENIED` / `ErrorCode.UNAUTHORIZED`. **(4)** `CoreTenantGuard` now returns **401** (was 403) when a request has no authenticated user. **(5)** `@Restricted(S_SELF)` / `@Restricted(S_CREATOR)` on **input** fields now actually enforce ownership (they were silently inert before) — a field that looked owner-restricted may become writable, so **audit them before upgrading**. |
+| **New Features** | `accessDeniedException(user, message?)` — an exported factory that derives 401 or 403 from the requester's auth state. Use it in your own services, models and guards instead of hand-rolling the decision. |
+| **Bugfixes** | **(a)** Status-code semantics per RFC 9110 across **all five** permission layers (role guards, tenant guard, `check()`, `checkRestricted()`, model `securityCheck()`), which previously contradicted each other. **(b)** `checkRestricted()` decided `S_SELF`/`S_CREATOR` ownership from the request **payload** instead of the persisted object — an authenticated attacker could unlock an owner-restricted input field on someone else's record. Now aligned with `check()`, which always read the persisted object. |
+| **Migration Effort** | ~5–20 minutes. `pnpm update`, then **(a)** update any assertion or handler that matches on **status 401** for an authenticated permission error or on the **exact wording** of a permission-error message, and **(b)** audit every `@Restricted(S_SELF)` / `@Restricted(S_CREATOR)` on an **input** type (Breaking Change 5). |
+
+### Why
+
+- **RFC 9110:** 401 means "authenticate yourself", 403 means "you are authenticated, but not
+  allowed". A permission error answered with 401 tells clients to re-authenticate, which cannot fix
+  the problem.
+- **Frontend auto-logout:** SPA auth layers commonly treat 401 as "session expired" and clear the
+  session — the `@lenne.tech/nuxt-extensions` auth interceptor patches `$fetch`/`fetch` globally and
+  does exactly this. With the old behavior, an authenticated user who merely lacked a right was
+  logged out of the whole app.
+- **Debuggability:** 401 logs no longer mix real authentication failures with permission failures.
+
+---
+
+## Quick Migration
+
+```bash
+pnpm add @lenne.tech/nest-server@11.28.0
+pnpm run build && pnpm test
+```
+
+Then work through the five breaking changes below. If your project never asserts 401 on an
+authenticated request, never matches on permission-error message text, and uses no
+`@Restricted(S_SELF)` / `@Restricted(S_CREATOR)` on an input type, there is nothing to do — but
+**verify that last point** (Breaking Change 5), it is the one with security impact.
+
+---
+
+## Breaking Change 1: 403 instead of 401 for authenticated permission errors
+
+| Path | Before | After (authenticated) | After (unauthenticated) |
+|------|--------|-----------------------|-------------------------|
+| `check()` / `checkRights` (`input.helper.ts`) | 401 | **403** | 401 |
+| `checkRestricted()`, object level (`restricted.decorator.ts`) | 401 | **403** | 401 |
+| `checkRestricted()`, field level (`restricted.decorator.ts`) | 401 | **403** | 401 |
+| Roles processing in `prepareInput` (`service.helper.ts`) | 401 | **403** | 401 |
+| `CoreTenantMemberModel.securityCheck()` (`core-tenant-member.model.ts`) | 401 | **403** | 401 |
+
+The decision key is `user.id`: a requester whose user object carries an id is authenticated and gets
+403; everyone else gets 401. A **falsy but present** id (`0`, `''`) counts as authenticated — relevant
+if your project uses numeric user ids.
+
+**Before:**
+```typescript
+// e2e: an authenticated customer patches an admin-only field
+await testHelper.rest(`/users/${customer.id}`, {
+  cookies: customer.token,
+  method: 'PATCH',
+  payload: { customerNumber: 'B-HACKED' },
+  statusCode: 401, // ← old: permission error surfaced as 401
+});
+```
+
+**After:**
+```typescript
+await testHelper.rest(`/users/${customer.id}`, {
+  cookies: customer.token,
+  method: 'PATCH',
+  payload: { customerNumber: 'B-HACKED' },
+  statusCode: 403, // ← new: authenticated, but lacking rights
+});
+```
+
+## Breaking Change 2: `S_NO_ONE` is now 403 for everyone
+
+`S_NO_ONE` marks a resource as locked for **all** requesters, administrators included.
+Authenticating can therefore never grant access, which makes 401 ("authenticate and retry") a lie
+even for an anonymous requester. All four paths now agree on **403**:
+
+| Path | Before | After |
+|------|--------|-------|
+| `RolesGuard` (`@Roles(S_NO_ONE)`) | 401 always | **403 always** |
+| `BetterAuthRolesGuard` (`@Roles(S_NO_ONE)`) | 401 always | **403 always** |
+| `CoreTenantGuard` (`@Roles(S_NO_ONE)`) | 403 always | 403 always (unchanged) |
+| `check()` (`@Restricted(S_NO_ONE)`, e.g. on `password`) | 401 always | **403 always** |
+
+Update any test asserting `statusCode: 401` on a locked endpoint or a `S_NO_ONE`-restricted field.
+
+## Breaking Change 3: error messages are now translatable `ErrorCode`s
+
+The paths above previously returned raw English strings (`'Missing rights'`, `'No access'`,
+`'The current user has no access rights for <field> of <Class>'`,
+`'Current user not allowed setting roles: <roles>'`). They now return the same `ErrorCode`s the role
+guards have always thrown:
+
+| Requester | Message |
+|-----------|---------|
+| authenticated | `ErrorCode.ACCESS_DENIED` → `#LTNS_0101: Access denied - Insufficient permissions` |
+| unauthenticated | `ErrorCode.UNAUTHORIZED` → `#LTNS_0100: Unauthorized - User is not logged in` |
+
+Two reasons:
+
+1. **They are translatable now.** The frontend error-translation layer keys off the `#LTNS_xxxx:`
+   marker. The old raw strings carried no marker, so users saw untranslated English — while the
+   *same* 403 coming from a role guard was translated. The framework no longer emits two
+   incompatible 403 formats.
+2. **They no longer leak internals.** The old field-level message embedded the Input/Model class name
+   and the property name in the HTTP response. That detail is still available — it goes to the debug
+   log (`config.debug`) instead of to the client.
+
+**Migration:** replace message assertions with `ErrorCode` comparisons.
+
+```typescript
+// Before
+expect(res.errors[0].message).toEqual('The current user has no access rights for roles of UserInput');
+
+// After
+import { ErrorCode } from '@lenne.tech/nest-server';
+expect(res.errors[0].message).toEqual(ErrorCode.ACCESS_DENIED);
+```
+
+If you relied on the class/field detail while debugging, enable `config.debug` and read the server log.
+
+## Breaking Change 4: `CoreTenantGuard` returns 401 when unauthenticated
+
+`CoreTenantGuard` previously threw `ForbiddenException('Authentication required')` — a **403** for a
+request with **no user at all**. That inverts the policy above: re-authenticating *is* the remedy
+here, so the client must be told. All five sites now throw **401** (`ErrorCode.UNAUTHORIZED`).
+
+This only surfaces when `CoreTenantGuard` runs without a role guard ahead of it; in the standard
+chain `RolesGuard` / `BetterAuthRolesGuard` already answered `!user` with 401.
+
+## Breaking Change 5: `S_SELF` / `S_CREATOR` on input fields now actually enforce ownership
+
+This is the one that needs a real audit before you upgrade.
+
+`checkRestricted()` used to decide `S_SELF` / `S_CREATOR` from the **request payload** (`data`) rather
+than from the persisted object. On the input path `data` is the caller-supplied DTO, so an
+authenticated attacker could unlock an owner-restricted field on **someone else's** record just by
+asserting ownership in the body — the service applies the input to the target it was called with, not
+to the ids in the payload:
+
+```
+PATCH /users/<victim>  { "id": "<attacker>", "createdBy": "<attacker>", "<restricted field>": ... }
+```
+
+Because `MapAndValidatePipe` strips `id`/`createdBy` from payloads (they are not `@UnifiedField`s),
+the branch usually could not fire, and such fields were **effectively admin-only-or-denied**. The fix
+reads ownership from `serviceOptions.dbObject` (as `check()` always did) — so `S_SELF`/`S_CREATOR` on
+an input field **start working**. A field that *looked* owner-restricted may suddenly become writable.
+
+### The audit
+
+Search for ownership roles on input types:
+
+```bash
+grep -rn "S_SELF\|S_CREATOR" src/server/**/inputs/
+```
+
+For each hit, decide what the field really means:
+
+| You want… | Use |
+|-----------|-----|
+| "the user may edit their own record's field" | `S_SELF` — correct, and now enforced |
+| "only an admin" (the common real case for `email`, `status`, `roles`) | `RoleEnum.ADMIN` — remove `S_CREATOR` |
+| "the field is open to any logged-in user" | `S_USER` |
+
+**Two traps:**
+
+1. **`S_CREATOR` is not "the user themselves".** `createdBy` is stamped by the audit plugin onto
+   whoever **created the record**. On a self-signup that is the user; in an **invite / admin-provisioning
+   flow it is the inviting admin, permanently**. `@Restricted(S_CREATOR)` on a user input therefore
+   grants the *inviter* write access to the invited user's fields — rarely the intent, and dangerous
+   on `email` (→ password reset).
+2. **A broader class-level role hides the field-level one.** `@Restricted(S_USER)` on the class
+   OR-merges with a field-level `S_SELF` (`mergeRoles` defaults to true), so `S_USER` alone already
+   grants the field — it was never owner-gated, and this change does not alter it. Such fields are
+   safe but misleading; consider dropping the redundant `S_SELF`.
+
+### Not affected
+
+- `check()` (`input.helper.ts`) already read from `dbObject` — no behavior change there.
+- **Output** filtering is unchanged: the object being checked *is* the persisted record.
+- `create()` has no `dbObject`, so ownership cannot be established there — `S_SELF`/`S_CREATOR` deny,
+  exactly as `check()` already did. (A normal create DTO carries neither `id` nor `createdBy`, so this
+  matches the old behavior for honest callers.)
+
+---
+
+## What is NOT affected
+
+- **All "requires auth" cases** (no token/session) — still 401. Only the `S_NO_ONE` case changed
+  (Breaking Change 2), because there authentication can never help.
+- **Token errors** (`Invalid token`, `Token expired`, refresh-token flows) — still 401.
+- **Sign-in with wrong credentials** — still 401.
+- **Email verification at sign-in** (`ErrorCode.EMAIL_VERIFICATION_REQUIRED`) — still **401**, and
+  correctly so: the requester has no session yet, so they are not authenticated. Note for frontends:
+  this is a 401 that must **not** trigger the auto-logout flow — branch on the ErrorCode, not on the
+  status alone.
+- **`instanceof` checks and `@Catch(...)` filters** — see below. This is deliberate.
+
+## `instanceof` and exception filters keep working
+
+The framework throws the **native** `ForbiddenException` / `UnauthorizedException`, never a custom
+subclass. Existing filters keep firing, and the REST error body (including the `name` field that
+`HttpExceptionLogFilter` emits) is unchanged:
+
+```typescript
+@Catch(ForbiddenException)    // fires for authenticated permission errors
+@Catch(UnauthorizedException) // fires for unauthenticated ones
+```
+
+A `@Catch(UnauthorizedException)` filter that used to catch an authenticated permission error will no
+longer see it — it is a `ForbiddenException` now. That is Breaking Change 1, and the fix is to handle
+`ForbiddenException` as well. No filter silently stops matching because of a changed exception class.
+
+### Use the factory in your own code
+
+```typescript
+import { accessDeniedException } from '@lenne.tech/nest-server';
+
+// In a service, a model's securityCheck(), or a custom guard:
+throw accessDeniedException(currentUser);                   // 403 if authenticated, else 401
+throw accessDeniedException(currentUser, 'Custom message'); // same decision, custom message
+```
+
+Prefer this over hand-rolling `user?.id ? new ForbiddenException() : new UnauthorizedException()` —
+it keeps the codebase on one policy and handles falsy-but-present ids correctly.
+
+---
+
+## Detailed Migration Steps
+
+### Step 1: Update the package
+
+```bash
+pnpm add @lenne.tech/nest-server@11.28.0
+```
+
+### Step 2: Find status-code expectations to update
+
+The candidates are assertions that send a token/cookie **and** expect 401:
+
+```bash
+# Backend tests
+grep -rn "statusCode: 401" tests/
+grep -rn "toEqual(401)\|toBe(401)" tests/
+
+# Locked endpoints / fields (S_NO_ONE) — every one of these is 403 now
+grep -rn "S_NO_ONE" src/ tests/
+```
+
+### Step 3: Find message assertions to update
+
+```bash
+grep -rn "Missing rights\|No access\|no access rights for\|not allowed setting roles" src/ tests/
+```
+
+Replace them with `ErrorCode.ACCESS_DENIED` / `ErrorCode.UNAUTHORIZED`.
+
+### Step 4: Find frontend 401 handlers
+
+The auto-logout interceptor usually does **not** live in your own `src/`/`app/` — in lt projects it
+ships with `@lenne.tech/nuxt-extensions` (`node_modules/`). Check your own branches too:
+
+```bash
+grep -rn "=== 401\|status === 401\|statusCode === 401\|case 401\|\[401" src/ app/
+grep -rn "onResponseError\|onError" app/plugins/ app/composables/
+```
+
+A 403 must show an error message; only a 401 may clear the session. Remember that
+`EMAIL_VERIFICATION_REQUIRED` is a 401 that must **not** log the user out — branch on the ErrorCode.
+
+For GraphQL clients the status sits at `errors[0].extensions.originalError.statusCode`, and
+`originalError.error` is `"Forbidden"` instead of `"Unauthorized"` for these cases.
+
+### Step 5: Audit `S_SELF` / `S_CREATOR` on input types (security)
+
+This is the step with security impact — do not skip it. See Breaking Change 5 for the full reasoning.
+
+```bash
+grep -rn "S_SELF\|S_CREATOR" src/server/**/inputs/
+```
+
+For each hit, confirm the intent still holds now that the role is actually enforced:
+
+- **`S_CREATOR` on a user-editable field** (e.g. `email`, `status`) — almost always wrong: in an
+  invite/admin-provisioning flow the *creator* is the inviting admin, not the user. Change to
+  `RoleEnum.ADMIN`.
+- **`S_SELF` under a broader class-level role** (`@Restricted(S_USER)` on the class) — never gated
+  anything (OR-merge); safe, but drop the redundant role to avoid the next reader's confusion.
+- **`S_SELF` as the only role** — now correctly enforces "owner only". Confirm that is what you want.
+
+### Step 6: Verify
+
+```bash
+pnpm run build && pnpm test
+```
+
+---
+
+## Compatibility Notes
+
+- Consumers of `@lenne.tech/nuxt-extensions`: version ≥ 1.8.4 additionally hardens the client auth
+  interceptor to verify the session before logging out on 401, so even backends still returning 401
+  for permission errors no longer cause wrongful logouts. Both changes are independent and
+  complementary.
+- Projects with a **vendored core** adopt this change via the regular core sync
+  (`/lt-dev:backend:update-nest-server-core`).
+- **Custom models that throw from `securityCheck()`** should switch to `accessDeniedException(user)`.
+  Otherwise they keep returning 401 to authenticated users and reintroduce the auto-logout bug in
+  your own code. `CoreTenantMemberModel` is the reference implementation.
+
+---
+
+## Troubleshooting
+
+### A test now fails with "expected 401, received 403"
+
+The request is authenticated and the user lacks rights — or the resource is `S_NO_ONE`-locked. 403 is
+the new, correct status. Update the assertion (Step 2).
+
+### A test now fails on the error message
+
+Permission errors return `ErrorCode.ACCESS_DENIED` / `ErrorCode.UNAUTHORIZED` instead of raw English
+(Breaking Change 3). Compare against the `ErrorCode` constant (Step 3).
+
+### My frontend no longer logs users out on permission errors
+
+That is the intended behavior: a permission error does not invalidate the session. Show an error
+message instead — the new messages carry the `#LTNS_xxxx:` marker, so `useLtErrorTranslation()`
+resolves them. Real session expiry still yields 401 and still triggers the logout flow.
+
+### I lost the "no access rights for `<field>` of `<Class>`" detail
+
+It is written to the debug log now rather than returned to the client (it exposed internal class and
+property names in the HTTP response). Enable `config.debug` to see it server-side.
+
+---
+
+## References
+
+- [RFC 9110 §15.5.2 (401 Unauthorized) / §15.5.4 (403 Forbidden)](https://www.rfc-editor.org/rfc/rfc9110)
+- `src/core/common/exceptions/access-denied.exception.ts` — the factory and the policy it encodes
+- `src/core/modules/auth/guards/roles.guard.ts` — the 401/403 pattern the service layer now mirrors
+- `.claude/rules/role-system.md` — role system and status-code rules
+- [nest-server-starter](https://github.com/lenneTech/nest-server-starter) — reference implementation

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nest-server",
-  "version": "11.27.6",
+  "version": "11.28.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",
@@ -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 ",
@@ -183,104 +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",
-      "esbuild@>=0.17.0 <0.28.1": "Security: esbuild dev-server responds to any request origin, letting any website the developer visits read files it serves (GHSA-67mh-4wv8-2f99, moderate); pinned to the latest patched release to keep esbuild aligned across the toolchain - dev-only, transitive via vite>vitest and @nestjs build tooling. Remove when all consumers resolve esbuild>=0.28.1",
-      "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",
-      "morgan@<1.11.0": "Security: Log Forging via unneutralized control characters in :remote-user (GHSA-4vj7-5mj6-jm8m, moderate, patched in 1.11.0) - dev-only, transitive via @compodoc/compodoc>@compodoc/live-server>morgan"
-    },
-    "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",
-      "morgan@<1.11.0": "1.11.0"
-    },
-    "//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 @@
-import { UnauthorizedException } from '@nestjs/common';
+/**
+ * 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 '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 { accessDeniedException } from '../exceptions/access-denied.exception';
+// 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
@@ -268,15 +293,32 @@ export const checkRestricted = (
         return false;
       }
 
+      // Ownership (S_SELF, S_CREATOR) must be decided from the PERSISTED object, never from `data`.
+      //
+      // On the INPUT path `data` is the caller-supplied DTO, so every ownership claim in it is
+      // attacker-controlled. An authenticated attacker could otherwise unlock an owner-restricted
+      // field on someone ELSE's record just by asserting ownership in the payload — the service
+      // applies the input to the target it was called with, not to the ids in the body:
+      //
+      //   PATCH /users/<victim>  { "id": "<own-id>", "createdBy": "<own-id>", "<restricted>": ... }
+      //
+      // `check()` (input.helper.ts) already reads both from `config.dbObject`; this is the same
+      // check and must agree with it. Where no dbObject exists (e.g. create), ownership cannot be
+      // established — exactly what check() does too.
+      //
+      // On the OUTPUT path there is no attacker-controlled input: `data` IS the persisted object
+      // (and a list yields one `data` per item), so it stays the source of truth there.
+      const owner = config.processType === ProcessType.INPUT ? config.dbObject : data;
+
       // Check access rights
       if (
         roles.includes(RoleEnum.S_EVERYONE) ||
         user?.hasRole?.(roles) ||
         (user?.id && roles.includes(RoleEnum.S_USER)) ||
-        (roles.includes(RoleEnum.S_SELF) && equalIds(data, user)) ||
+        (roles.includes(RoleEnum.S_SELF) && equalIds(owner, user)) ||
         (roles.includes(RoleEnum.S_CREATOR) &&
-          (('createdBy' in data && equalIds(data.createdBy, user)) ||
-            (config.allowCreatorOfParent && !('createdBy' in data) && config.isCreatorOfParent))) ||
+          ((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))
       ) {
@@ -340,9 +382,10 @@ export const checkRestricted = (
       if (config.debug) {
         console.debug(`The current user has no access rights for ${data.constructor?.name}`);
       }
-      // Throw error
+      // 403 when authenticated, 401 otherwise (see accessDeniedException). The class name stays in
+      // the debug log above — the client gets the translatable ErrorCode the role guards also use.
       if (config.throwError) {
-        throw new UnauthorizedException(`The current user has no access rights for ${data.constructor?.name}`);
+        throw accessDeniedException(user);
       }
       return null;
     }
@@ -368,9 +411,14 @@ export const checkRestricted = (
 
     // Check rights
     if (valid) {
-      // Check if data is user or user is creator of data (for nested plain objects)
+      // Check if the parent is the user, or the user created it (for nested plain objects).
+      // Same rule as above: on INPUT the ownership claim must come from the persisted object, not
+      // from the DTO — otherwise a forged `id`/`createdBy` in the payload would propagate a faked
+      // "creator of parent" trust down into every nested object.
+      const parent = config.processType === ProcessType.INPUT ? config.dbObject : data;
       config.isCreatorOfParent =
-        equalIds(data, user) || ('createdBy' in data ? equalIds(data.createdBy, user) : config.isCreatorOfParent);
+        equalIds(parent, user) ||
+        (parent && 'createdBy' in parent ? equalIds(parent.createdBy, user) : config.isCreatorOfParent);
 
       // Check deep
       data[propertyKey] = checkRestricted(data[propertyKey], user, config, processedObjects);
@@ -380,11 +428,10 @@ export const checkRestricted = (
           `The current user has no access rights for ${propertyKey}${data.constructor?.name ? ` of ${data.constructor.name}` : ''}`,
         );
       }
-      // Throw error
+      // 403 when authenticated, 401 otherwise (see accessDeniedException). The field and class name
+      // stay in the debug log above — the client gets the translatable ErrorCode the guards also use.
       if (config.throwError) {
-        throw new UnauthorizedException(
-          `The current user has no access rights for ${propertyKey}${data.constructor?.name ? ` of ${data.constructor.name}` : ''}`,
-        );
+        throw accessDeniedException(user);
       }
 
       // Remove property
@@ -394,4 +441,4 @@ export const checkRestricted = (
 
   // Return processed data
   return data;
-};
+}