@lenne.tech/nest-server 11.27.7 → 11.28.0

package/docs/REQUEST-LIFECYCLE.md

@@ -949,6 +949,41 @@ The `process()` method in `ModuleService` is the **primary** way to handle CRUD
   +---------------------------------------------------------------+
 ```
 
+### Status Codes: 401 vs 403 (v11.28.0+)
+
+One policy across **all five** permission layers — the role guards, the tenant guard, `check()` /
+`checkRights`, `checkRestricted()` (object and field level), and a model's `securityCheck()`:
+
+| Situation | Status | Thrown by |
+|-----------|--------|-----------|
+| Requester is **not authenticated** | **401** `ErrorCode.UNAUTHORIZED` | guards, `accessDeniedException(undefined)` |
+| Requester **is authenticated** but lacks a right | **403** `ErrorCode.ACCESS_DENIED` | guards, `accessDeniedException(user)` |
+| Resource is locked via `S_NO_ONE` | **403**, always — even for anonymous requesters | guards, `check()` |
+
+`S_NO_ONE` is 403 for everyone because authenticating can never unlock it; a 401 would tell the
+client to retry after logging in, which is a lie.
+
+**Why this matters:** 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). A permission error answered with 401 therefore logs the user out of the whole app. With this
+policy a frontend may treat 401 as "session invalid" — with one exception:
+`ErrorCode.EMAIL_VERIFICATION_REQUIRED` is a legitimate 401 (no session exists yet at sign-in) that
+must **not** trigger a logout. Branch on the ErrorCode, not on the status alone.
+
+**Writing new denial code:** use the exported factory rather than hand-rolling the decision. It
+returns the **native** `ForbiddenException` / `UnauthorizedException`, so `instanceof` checks and
+`@Catch(...)` filters in consuming projects keep working:
+
+```typescript
+import { accessDeniedException } from '@lenne.tech/nest-server';
+
+// In a service, a custom guard, or a model's securityCheck():
+throw accessDeniedException(currentUser);
+```
+
+See `src/core/common/exceptions/access-denied.exception.ts` and
+`migration-guides/11.27.7-to-11.28.0.md`.
+
 ### Depth-Based Optimization (v11.23.0+)
 
 When `process()` is called from within another `process()` call (service cascades like A.create → B.create → C.create), steps 4–6 are **conditionally skipped** on inner calls to avoid redundant work:
@@ -1095,6 +1130,10 @@ Controls who can access a resolver/controller method. Evaluated by the RolesGuar
 
 Controls who can see or modify specific properties. Evaluated by `CheckResponseInterceptor` (output) and `checkRights()` (input).
 
+On **output** a denied field is silently removed (no exception). On **input** the request is
+rejected: **403** for an authenticated requester, **401** for an anonymous one, and **403 always**
+for `S_NO_ONE` — see [Status Codes: 401 vs 403](#status-codes-401-vs-403-v11280) above.
+
 ```typescript
 export class User extends CorePersistenceModel {
   // Only admins or the user themselves can see the email

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.7",
+  "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",

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

@@ -21,12 +21,12 @@
  * 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 { 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';
@@ -293,15 +293,32 @@ export function 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))
       ) {
@@ -365,9 +382,10 @@ export function 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;
     }
@@ -393,9 +411,14 @@ export function 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);
@@ -405,11 +428,10 @@ export function 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

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

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

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

@@ -1,4 +1,4 @@
-import { BadRequestException, UnauthorizedException } from '@nestjs/common';
+import { BadRequestException, ForbiddenException } from '@nestjs/common';
 import { plainToInstance } from 'class-transformer';
 import { validate } from 'class-validator';
 import { ValidatorOptions } from 'class-validator/types/validation/ValidatorOptions';
@@ -7,6 +7,8 @@ import { Kind } from 'graphql/index';
 import { checkRestricted } from '../decorators/restricted.decorator';
 import { ProcessType } from '../enums/process-type.enum';
 import { RoleEnum } from '../enums/role.enum';
+import { accessDeniedException } from '../exceptions/access-denied.exception';
+import { ErrorCode } from '../../modules/error-code/error-codes';
 import { clone } from './clone.helper';
 import { merge } from './config.helper';
 import { equalIds } from './id.helper';
@@ -248,9 +250,11 @@ export async function check(
     }
     let valid = false;
 
-    // Prevent access for everyone, including administrators
+    // Prevent access for everyone, including administrators. Always 403, never 401: the resource is
+    // locked permanently, so authenticating can never grant access and telling an anonymous
+    // requester to "authenticate and retry" (401) would be a lie. Both role guards do the same.
     if (roles.includes(RoleEnum.S_NO_ONE)) {
-      throw new UnauthorizedException('No access');
+      throw new ForbiddenException(ErrorCode.ACCESS_DENIED);
     }
 
     // Check access
@@ -276,7 +280,8 @@ export async function check(
       valid = true;
     }
     if (!valid) {
-      throw new UnauthorizedException('Missing rights');
+      // 403 when authenticated, 401 otherwise — policy documented in accessDeniedException
+      throw accessDeniedException(user);
     }
   }
 

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

@@ -1,10 +1,10 @@
-import { UnauthorizedException } from '@nestjs/common';
 import bcrypt = require('bcrypt');
 import { sha256 } from 'js-sha256';
 import _ = require('lodash');
 import { Types } from 'mongoose';
 
 import { RoleEnum } from '../enums/role.enum';
+import { accessDeniedException } from '../exceptions/access-denied.exception';
 import { PrepareInputOptions } from '../interfaces/prepare-input-options.interface';
 import { PrepareOutputOptions } from '../interfaces/prepare-output-options.interface';
 import { ResolveSelector } from '../interfaces/resolve-selector.interface';
@@ -151,15 +151,17 @@ export async function prepareInput<T = any>(
     value === undefined && delete input[key];
   }
 
-  // Process roles
+  // Process roles — 403 when authenticated, 401 otherwise (see accessDeniedException). The rejected
+  // roles are logged rather than returned: the client gets the translatable ErrorCode the guards use.
   if (config.checkRoles && (input as Record<string, any>).roles && !currentUser?.hasRole?.(RoleEnum.ADMIN)) {
     if (!(currentUser as any)?.roles) {
-      throw new UnauthorizedException('Missing roles of current user');
+      throw accessDeniedException(currentUser);
     } else {
       const allowedRoles = _.intersection((input as Record<string, any>).roles, (currentUser as any).roles);
       if (allowedRoles.length !== (input as Record<string, any>).roles.length) {
         const missingRoles = _.difference((input as Record<string, any>).roles, (currentUser as any).roles);
-        throw new UnauthorizedException(`Current user not allowed setting roles: ${missingRoles}`);
+        console.debug(`Current user not allowed setting roles: ${missingRoles}`);
+        throw accessDeniedException(currentUser);
       }
       (input as Record<string, any>).roles = allowedRoles;
     }

package/src/core/modules/auth/guards/roles.guard.ts

@@ -137,9 +137,10 @@ export class RolesGuard extends AuthGuard(AuthGuardStrategy.JWT) {
     ]);
     const roles = mergeRolesMetadata(reflectorRoles);
 
-    // Check if locked - always deny
+    // Check if locked - always deny. 403, never 401: the endpoint is locked permanently, so
+    // authenticating can never grant access and a 401 ("authenticate and retry") would be a lie.
     if (roles && roles.includes(RoleEnum.S_NO_ONE)) {
-      throw new UnauthorizedException(ErrorCode.UNAUTHORIZED);
+      throw new ForbiddenException(ErrorCode.ACCESS_DENIED);
     }
 
     // If no roles required, or S_EVERYONE is set, allow access without authentication
@@ -293,9 +294,9 @@ export class RolesGuard extends AuthGuard(AuthGuardStrategy.JWT) {
     ]);
     const roles = mergeRolesMetadata(reflectorRoles);
 
-    // Check if locked
+    // Check if locked — 403, never 401 (see canActivate: authenticating can never unlock it)
     if (roles && roles.includes(RoleEnum.S_NO_ONE)) {
-      throw new UnauthorizedException(ErrorCode.UNAUTHORIZED);
+      throw new ForbiddenException(ErrorCode.ACCESS_DENIED);
     }
 
     // Check roles