@lenne.tech/nest-server 11.27.6 → 11.28.0

package/.claude/rules/architecture.md

@@ -60,6 +60,72 @@ Key areas: JWT, MongoDB, GraphQL, email, security, static assets
 - `CheckResponseInterceptor` - Filters restricted fields
 - `CheckSecurityInterceptor` - Processes `securityCheck()` methods
 
+## DI Token Placement (SWC-Safe)
+
+**Rule: DI tokens belong in an import-free leaf file (`*.constants.ts` / `*.enums.ts`) — never in `*.module.ts` or `*.service.ts`.**
+
+A token declared in a module that the service imports (or vice versa) makes the two files import each other. That cycle compiles fine under tsc, but `@Inject(TOKEN)` is a constructor-parameter decorator evaluated at **class-definition time** — so on the cycle it reads a `const` that is still in its temporal dead zone. Under SWC → CommonJS (`nest start -b swc`) the app dies at startup:
+
+```
+ReferenceError: Cannot access 'BETTER_AUTH_INSTANCE' before initialization
+```
+
+**This is invisible to `tsc`, to `pnpm test` (vitest runs SWC through Vite's cycle-tolerant module runner) and to `oxlint` (which has no `import/no-cycle` rule).** It is caught only by `pnpm run check:swc-tdz`.
+
+### The general rule: a cycle is fatal only when dereferenced at evaluation time
+
+The cycle alone is survivable. What kills it is **reading a TDZ-subject binding (`const` / `class` / `let`) while the module is still initializing**:
+
+| Deref location | Evaluated | Danger |
+|----------------|-----------|--------|
+| Decorator argument (`@UnifiedField({ type: X })`, `@Inject(TOKEN)`) | class-definition time | ☠️ **fatal on a cycle** |
+| `design:type` / `design:paramtypes` metadata (from `emitDecoratorMetadata`) | class-definition time | ☠️ **fatal on a cycle** — and userland cannot make it lazy |
+| Static / class field initializer | class-definition time | ☠️ **fatal on a cycle** |
+| Top-level `const alias = X` | module-evaluation time | ☠️ **fatal on a cycle** |
+| Inside a function or method body | call time | ✅ safe (both modules are done by then) |
+| `export function` declaration | hoisted | ✅ TDZ-immune — prefer over `const` arrows on cycle-adjacent files |
+| `import type` | erased | ✅ not a runtime edge at all |
+
+**A lazy thunk is often NOT enough.** `type: () => X` defers the decorator argument, but `emitDecoratorMetadata` still emits an eager `design:type` for the property, and SWC's `typeof` guard does not protect the member expression it compiles to. To be safe you must remove the **import edge** — merge the modules, or extract the shared binding into a leaf.
+
+### `check:swc-tdz` loads every module as its own entry point
+
+Whether such a cycle throws depends on **which module the graph is entered through**. A barrel-only check is not enough: `filter.input` ↔ `combined-filter.input` crashed on a direct `require()` of `combined-filter.input` while the barrel loaded green, because the barrel happened to pull `filter.input` in first. So the guard requires each compiled file separately (`scripts/check-swc-tdz.mjs`).
+
+### Status per module
+
+Repo-wide cycles went from **10 → 5**, and **every DI token in `src/core/` now lives in an import-free leaf**. The five that remain are, per an SWC-emit audit, **not runtime cycles at all** — type-only imports that madge reports but both compilers erase (their emits are empty).
+
+Both invariants are enforced by `tests/unit/import-cycle-invariants.spec.ts`, which fails if a token reappears in a `*.module.ts` / `*.service.ts` or if a leaf grows an import. That matters, because the guard below catches the *crash*, not the *disarming* of a safety property — those are different things, and only the second one is silent.
+
+| Module | Token / type leaf |
+|--------|-------------------|
+| `better-auth` | `core-better-auth.constants.ts` (tokens) + `core-better-auth.registry.ts` (static service refs, `import type` only, deliberately **not** barrel-exported) |
+| `ai` | `core-ai.constants.ts` (all 22 `AI_*` tokens) + `interfaces/ai-interaction-record.interface.ts` |
+| `tus` | `tus.constants.ts` (`TUS_CONFIG`) |
+| `tenant` | `core-tenant.enums.ts` |
+| `auth` | `interfaces/auth-provider.interface.ts` |
+| `common/helpers` | `id.helper.ts` (ID cluster, out of `db.helper`) + `clone.helper.ts` (`clone`/`deepFreeze`, out of `input.helper`) |
+| `common/inputs` | `FilterInput` + `CombinedFilterInput` merged into `filter.input.ts` — declaration order is load-bearing |
+| `common/decorators` | `restricted.decorator` is on **zero** cycles; its exports are hoisted `function` declarations (TDZ-immune) as defense in depth |
+
+Every old location re-exports what it lost, so no import path broke — the public API is byte-identical (472 exports, verified by diffing both versions).
+
+### What each of these actually was
+
+Worth knowing, because the pattern repeats:
+
+- **`CombinedFilterInput` was already crashing.** `require('.../combined-filter.input.js')` threw. It stayed hidden because the barrel happens to pull `filter.input` in first — a deep import or a reordering of `src/index.ts` would have surfaced it. A lazy thunk does **not** fix that shape: `emitDecoratorMetadata` still emits an eager `design:type`.
+- **`restricted.decorator` sat on two cycles at once**, in the file that drives field-level access control. Removing the `db.helper` edge felt like the fix and left the `config.service` one fully intact. **Removing one edge is not removing the cycle** — re-run madge and confirm the file appears in *zero* cycles.
+- **The AI interaction record was held apart by one keyword.** `import type` erases the edge; an IDE "organize imports" widening it to a value import would have armed a `design:paramtypes` deref, silently.
+- **`TUS_CONFIG` and the 22 `AI_*` tokens** never crashed — their graphs happened to be acyclic. Each was one back-import away, with nothing watching.
+
+### The lesson that cost the most time
+
+Removing one edge is not the same as removing the cycle. `restricted.decorator` was on **two** cycles through different paths; extracting the ID helpers out of `db.helper` felt like the fix and left the second one (via `config.service`) fully intact — with `madge` happily reporting the file as still cyclic. Always re-run `npx madge --circular --extensions ts src/` after an extraction and check the file appears in **zero** cycles, rather than assuming the edge you removed was the only one.
+
+Full background, failure analysis and the mistakes table: `.claude/rules/better-auth.md` §6.
+
 ## Model Inheritance
 
 - `CorePersistenceModel` - Base for database entities

package/.claude/rules/better-auth.md

@@ -199,6 +199,8 @@ The BetterAuth module provides two RolesGuard implementations:
 **Solution:** `BetterAuthRolesGuard` with NO constructor dependencies:
 
 ```typescript
+import { getBetterAuthTokenService } from './core-better-auth.registry';
+
 @Injectable()
 export class BetterAuthRolesGuard implements CanActivate {
   // NO constructor dependencies - avoids mixin DI conflict
@@ -207,14 +209,19 @@ export class BetterAuthRolesGuard implements CanActivate {
     // Use Reflect.getMetadata directly (not NestJS Reflector)
     const roles = Reflect.getMetadata('roles', context.getHandler());
 
-    // Access services via static module reference
-    const tokenService = CoreBetterAuthModule.getTokenServiceInstance();
+    // Read the token service from the registry LEAF — never from CoreBetterAuthModule.
+    // Importing the module here re-creates the guard <-> module import cycle (see §6).
+    const tokenService = getBetterAuthTokenService();
 
     // ... role checking logic identical to RolesGuard
   }
 }
 ```
 
+> The guard must NOT do `CoreBetterAuthModule.getTokenServiceInstance()`. That static accessor is
+> still public API and still works — but calling it *from the guard* means importing the module,
+> which is exactly the cycle §6 exists to prevent. Everywhere else, the static accessor is fine.
+
 ### Guard Selection Logic
 
 In `CoreBetterAuthModule.createDeferredModule()`:
@@ -250,6 +257,84 @@ Both guards implement identical security logic:
 2. **New system roles** → Add to BOTH guards
 3. **Token verification changes** → Update `BetterAuthTokenService` (shared by both)
 4. **Testing** → Test both Legacy Mode and IAM-Only Mode
+5. **Reaching services from `BetterAuthRolesGuard`** → go through `core-better-auth.registry.ts`,
+   **never** through `CoreBetterAuthModule` (see §6 — importing the module from the guard
+   re-creates an import cycle)
+
+## 6. DI Token Placement (SWC-Safe)
+
+### The rule
+
+**DI tokens and static service references belong in an import-free leaf file — never in
+`*.module.ts` or `*.service.ts`.**
+
+| File | Contents | Imports |
+|------|----------|---------|
+| `core-better-auth.constants.ts` | `BETTER_AUTH_INSTANCE`, `BETTER_AUTH_CONFIG`, `BETTER_AUTH_COOKIE_DOMAIN` | **none** |
+| `core-better-auth.registry.ts` | `BetterAuthTokenService` reference for `BetterAuthRolesGuard` | **`import type` only** (erased by tsc and SWC) |
+
+### The problem
+
+The tokens used to live in the module (`BETTER_AUTH_INSTANCE`) and the service (`BETTER_AUTH_CONFIG`,
+`BETTER_AUTH_COOKIE_DOMAIN`), so module and service imported each other.
+
+**Error (only under `nest start -b swc` / `nest build -b swc`):**
+
+```
+ReferenceError: Cannot access 'BETTER_AUTH_INSTANCE' before initialization
+```
+
+The lethal ingredient is **not the cycle by itself** — it is a cycle **plus a read of the cyclic
+binding at module-evaluation time**. `@Inject(BETTER_AUTH_INSTANCE)` is a constructor-parameter
+decorator, and decorator arguments are evaluated when the class is *defined*, i.e. while the module
+is still initializing. On a cycle, the importing side then reads a `const` that is still in its
+temporal dead zone.
+
+This is why the same cycle is harmless when both sides only dereference each other **inside method
+bodies** (deferred to call time) — and why such a cycle is nonetheless a loaded gun: hoisting a
+lazy lookup into a static field, or adding a typed constructor parameter (which emits
+`design:paramtypes` at top level), weaponizes it instantly.
+
+### The solution
+
+```typescript
+// core-better-auth.constants.ts — imports NOTHING
+export const BETTER_AUTH_INSTANCE = 'BETTER_AUTH_INSTANCE';
+
+// core-better-auth.module.ts AND core-better-auth.service.ts
+import { BETTER_AUTH_INSTANCE } from './core-better-auth.constants';
+```
+
+A file with zero imports can never be mid-evaluation when someone imports it — in any module
+system, under any compiler.
+
+### Why you cannot rely on the test suite here
+
+This bug class is **invisible** to everything except one specific step:
+
+| Tool | Sees it? | Why |
+|------|:--------:|-----|
+| `tsc` / `pnpm run build` | ❌ | Compiles the cycle without complaint |
+| `pnpm test` (vitest) | ❌ | vitest runs SWC through **Vite's module runner**, whose getter-based live bindings tolerate cycles |
+| `oxlint` | ❌ | oxlint does **not** implement `import/no-cycle` |
+| `pnpm run check:swc-tdz` | ✅ | SWC → CommonJS → `require()`: the exact path consumers hit |
+| `tests/unit/better-auth-di-tokens.spec.ts` | ✅ | Asserts the leaf invariant structurally |
+
+The bug shipped to `develop` with a fully green CI. Treat a green `pnpm test` as **no evidence** on
+this question.
+
+### Common mistakes
+
+| Mistake | Symptom | Fix |
+|---------|---------|-----|
+| Importing a token from `./core-better-auth.module` or `./core-better-auth.service` inside the better-auth module | Green tsc + green tests; `ReferenceError` for consumers on SWC | Import from `./core-better-auth.constants` |
+| Adding any runtime `import` to `core-better-auth.constants.ts` | `better-auth-di-tokens.spec.ts` fails | Keep it a leaf; move whatever you needed elsewhere |
+| Importing `CoreBetterAuthModule` into `better-auth-roles.guard.ts` | Re-creates the guard ↔ module cycle | Use `getBetterAuthTokenService()` from `./core-better-auth.registry` |
+| Hoisting `getBetterAuthTokenService()` into a static field / class property initializer | Evaluation-time deref → TDZ crash returns | Keep the lookup inside the method body |
+
+> The backward-compat re-exports in `core-better-auth.module.ts` / `core-better-auth.service.ts` are
+> marked `@deprecated` and exist **only** for external deep importers. Never use them from inside
+> the module — that is precisely the path that re-creates the cycle.
 
 ## Summary
 
@@ -260,3 +345,4 @@ Both guards implement identical security logic:
 | Testing | Full coverage, all tests pass, security tests included |
 | Customization | Use correct registration pattern, re-declare Resolver decorators |
 | Guards | Maintain both RolesGuard and BetterAuthRolesGuard in sync |
+| DI Tokens | Import-free leaf file only — never in `*.module.ts` / `*.service.ts` (§6) |

package/.claude/rules/package-management.md

@@ -97,9 +97,23 @@ peerDependencies may use ranges when necessary for compatibility with consuming
 
 The `pnpm-lock.yaml` file must always be committed. It provides additional reproducibility even if someone accidentally introduces a version range.
 
+## Package Manager: pnpm 11
+
+This repo is pinned to **pnpm 11** via the `packageManager` field (corepack/`pnpm/action-setup` follow it, so CI and Docker use it automatically — no version is hardcoded anywhere else).
+
+pnpm 11 **no longer reads the `pnpm` field in `package.json`**, and `.npmrc` is auth/registry only. All pnpm-specific settings live in **`pnpm-workspace.yaml`**:
+
+- `overrides:` — the security overrides (see below)
+- `allowBuilds:` — a **map** of `pkg: true|false` classifying every package that has an install script (canonical v11 form; replaces `onlyBuiltDependencies`). Native builds we need are `true` (`bcrypt`, `@swc/core`, …); telemetry like `@scarf/scarf` is `false`. **Every build-script package must be classified**, or `pnpm install` exits non-zero with `ERR_PNPM_IGNORED_BUILDS` and appends a broken stub.
+- `nodeLinker`, `autoInstallPeers`, `strictPeerDependencies`, `peerDependencyRules` — moved here from `.npmrc` (camelCase).
+
+`pnpm audit`: pnpm 10.x is broken (npm retired the legacy audit endpoint → HTTP 410); pnpm 11 uses the working bulk-advisory endpoint. `scripts/check.mjs` degrades the retired-endpoint failure to a non-blocking warning as a safety net, so `check` stays green + honest even if a future endpoint change lands.
+
 ## Overrides
 
-Package overrides are configured in the `pnpm.overrides` section of `package.json` and are typically used to force transitive dependencies to a security-patched version.
+Package overrides live in the `overrides:` section of **`pnpm-workspace.yaml`** (they moved out of `package.json`'s `pnpm.overrides` in the pnpm 11 upgrade). They force transitive dependencies to a security-patched version.
+
+**Keep the set minimal.** On the pnpm 11 upgrade the list was pruned from 36 to the 9 still load-bearing — an override is only necessary if removing it lets the package resolve back INTO its vulnerable range (verify with a with/without lockfile diff; `pnpm audit` is the arbiter). Each surviving entry carries its CVE rationale as a comment. Remove an entry once its parent dependency ships a fixed version.
 
 ### Rule: Override Targets MUST Be Fixed Versions
 
@@ -115,19 +129,14 @@ The **target** of an override (the value on the right-hand side) MUST be a fixed
 
 The **key** (left-hand side) of an override entry selects which installed versions the override applies to. Both forms are valid:
 
-```json
-{
-  "pnpm": {
-    "overrides": {
-      // Form 1: Replace ALL versions of a package with a fixed one
-      "lodash": "4.17.23",
-
-      // Form 2: Replace only vulnerable versions with a fixed patched one
-      "minimatch@<3.1.4": "3.1.4",
-      "path-to-regexp@>=8.0.0 <8.4.0": "8.4.2"
-    }
-  }
-}
+```yaml
+# pnpm-workspace.yaml
+overrides:
+  # Form 1: Replace ALL versions of a package with a fixed one
+  'lodash': '4.17.23'
+  # Form 2: Replace only vulnerable versions with a fixed patched one
+  'minimatch@<3.1.4': '3.1.4'
+  'path-to-regexp@>=8.0.0 <8.4.0': '8.4.2'
 ```
 
 Form 2 is preferred for security-driven overrides because it leaves non-vulnerable versions untouched, which reduces the blast radius of the override.

package/.claude/rules/role-system.md

@@ -21,6 +21,57 @@ System roles are used for **runtime checks only** and must **NEVER** be stored i
 | `S_EVERYONE` | Public access | Always true |
 | `S_NO_ONE` | Locked access | Always false |
 
+### `object` means the PERSISTED object — never the request payload
+
+For `S_SELF` and `S_CREATOR`, "object" is the record loaded from the database
+(`serviceOptions.dbObject`), **not** the input DTO. This distinction is security-critical.
+
+On the **input** path the DTO is fully attacker-controlled. Deciding `S_SELF` from it would let an
+authenticated attacker unlock an owner-restricted field on someone else's record just by putting
+their own id in the body — the service writes to the target it was called with, not to the id in the
+payload:
+
+```
+PATCH /users/<victim-id>   { "id": "<attacker-id>", "iban": "DE...attacker" }
+```
+
+On the **output** path there is no attacker-controlled input: the object being checked *is* the
+persisted record (and a list is checked per item), so it is the correct comparison target there.
+
+Both `check()` (`input.helper.ts`) and `checkRestricted()` (`restricted.decorator.ts`) implement this.
+If you write your own rights check, compare against `dbObject` on input — never against the DTO.
+
+### ⚠️ `S_CREATOR` is the CREATOR of the record — which is often an admin, not the user
+
+`createdBy` is set by the audit plugin to whoever **created the record**. On a self-signup that is the
+user themselves. But in an **invite or admin-provisioning flow it is the inviting admin** — and it
+stays that way forever.
+
+So `@Restricted(S_CREATOR)` on a **User input field** does not mean "the user may edit their own
+field". It means **"whoever created this account may edit it"** — granting the inviter permanent
+write access to the invited user's record.
+
+That is almost never the intent, and it is dangerous on exactly the fields people reach for it on:
+
+```typescript
+// DANGEROUS on an invite-based system: the inviting workspace admin IS the creator, so this
+// lets them rewrite the invited member's email — and then trigger a password reset.
+@UnifiedField({ roles: [RoleEnum.ADMIN, RoleEnum.S_CREATOR] })
+email?: string;
+
+// SAFE: only a system admin, and the user changes their own email through the verification-gated
+// BetterAuth changeEmail flow, never through a generic update DTO.
+@UnifiedField({ roles: [RoleEnum.ADMIN] })
+email?: string;
+```
+
+**Upgrade note:** before v11.28.x, `S_SELF`/`S_CREATOR` on an *input* field never actually fired —
+the check read the claim off the DTO, and `MapAndValidatePipe` strips `id`/`createdBy` from payloads
+(they are not `@UnifiedField`s). Such fields were therefore effectively **admin-only-or-denied**.
+Now that the check reads the persisted object, they start working — and a field that looked
+owner-restricted may suddenly become writable by an admin who provisioned the record. **Audit every
+`S_SELF`/`S_CREATOR` on an input type before upgrading.**
+
 ## Critical Rule
 
 ```typescript
@@ -79,6 +130,45 @@ The role system is evaluated in:
 - `CheckResponseInterceptor` - Filters fields based on `@Restricted()` decorators
 - `CheckSecurityInterceptor` - Processes `securityCheck()` methods
 
+## Status Codes: 401 vs 403 (v11.28.0+)
+
+**All five permission layers answer with the same policy.** Getting this wrong has a concrete
+consequence: SPA auth layers treat 401 as "session expired" and log the user out — so a mere
+permission error returned as 401 kicks a logged-in user out of the whole app.
+
+| Situation | Status | Message |
+|-----------|--------|---------|
+| Requester is **not authenticated** | **401** | `ErrorCode.UNAUTHORIZED` |
+| Requester **is authenticated** but lacks a right | **403** | `ErrorCode.ACCESS_DENIED` |
+| `S_NO_ONE` (locked for everyone) | **403 always**, even for anonymous requesters | `ErrorCode.ACCESS_DENIED` |
+
+`S_NO_ONE` is 403 even without a session because authenticating can *never* unlock it — a 401 would
+tell the client to log in and retry, which is a lie.
+
+Exception: `ErrorCode.EMAIL_VERIFICATION_REQUIRED` is a legitimate **401** (thrown at sign-in, where
+no session exists yet). Frontends must branch on the ErrorCode, not on the status alone, so this one
+does not trigger the logout flow.
+
+### Never hand-roll the decision
+
+```typescript
+import { accessDeniedException } from '@lenne.tech/nest-server';
+
+// CORRECT — one policy, native exceptions (instanceof / @Catch keep working)
+throw accessDeniedException(currentUser);
+throw accessDeniedException(currentUser, 'Custom message');
+
+// WRONG — drifts from the framework policy and mishandles falsy-but-present ids (0, '')
+throw currentUser?.id ? new ForbiddenException() : new UnauthorizedException();
+
+// WRONG — a permission error must never be a 401 for an authenticated user
+throw new UnauthorizedException('Missing rights');
+```
+
+**This applies to `securityCheck()` in your models too.** `CoreTenantMemberModel` is the reference
+implementation. A model that throws `UnauthorizedException` from `securityCheck()` reintroduces the
+auto-logout bug in your own project.
+
 ## @Roles vs @UseGuards
 
 **IMPORTANT: `@Roles()` already handles JWT authentication internally.**

package/.claude/rules/versioning.md

@@ -23,12 +23,27 @@
 ## Release Process
 
 1. Make changes and ensure all tests pass (`pnpm test`)
-2. Update version in `package.json`
-3. Build the package (`pnpm run build`)
+2. **Bump the version in BOTH version-carrying files — they must never drift:**
+   - `package.json` → `version`
+   - `spectaql.yml` → `info.version` (feeds the published GraphQL API docs)
+
+   `spectaql.yml` is derived from `package.json` by `extras/update-spectaql-version.mjs`, but that
+   script only runs via `pnpm run docs` — it is **not** part of `pnpm run build`. A release commit
+   that bumps only `package.json` therefore ships API docs advertising the previous version. Run
+   `node extras/update-spectaql-version.mjs` (or edit the file) and commit both together.
+3. Build the package (`pnpm run build`) — this also regenerates `FRAMEWORK-API.md` with the new version
 4. Publish to npm
 5. Update and test in [nest-server-starter](https://github.com/lenneTech/nest-server-starter)
 6. Commit changes to starter with migration notes
 
+### Version Consistency Check
+
+```bash
+# Both must print the same version
+grep -m1 '"version"' package.json
+grep -m1 '^  version:' spectaql.yml
+```
+
 ## Package Distribution
 
 - **NPM Package**: `@lenne.tech/nest-server`

package/CLAUDE.md

@@ -114,9 +114,15 @@ npx vitest run --config vitest-e2e.config.ts --reporter=hanging-process   # Debu
 pnpm run test:cleanup   # Remove leftover test artifacts (.txt, .bin)
 
 # Linting & Formatting
-pnpm run lint           # ESLint check
+pnpm run lint           # oxlint check
 pnpm run lint:fix       # Auto-fix
-pnpm run format         # Prettier format
+pnpm run format         # oxfmt format
+
+# Import-cycle / SWC safety (part of `check`)
+pnpm run check:swc-tdz  # SWC→CJS build, loads EVERY module as its own entry point.
+                        # The only step that catches a temporal-dead-zone crash from an
+                        # import cycle — tsc, vitest and oxlint are all blind to it.
+                        # See .claude/rules/architecture.md → "DI Token Placement (SWC-Safe)"
 
 # Package Development
 pnpm run build:dev      # Build for local development (use with pnpm link)

package/FRAMEWORK-API.md

@@ -1,6 +1,6 @@
 # @lenne.tech/nest-server — Framework API Reference
 
-> Auto-generated from source code on 2026-07-11 (v11.27.6)
+> Auto-generated from source code on 2026-07-15 (v11.28.0)
 > File: `FRAMEWORK-API.md` — compact, machine-readable API surface for Claude Code
 
 ## CoreModule.forRoot()
@@ -283,6 +283,31 @@ Generic: `CrudService<Model, CreateInput, UpdateInput>`
 | `tus` | README, CHECKLIST | `src/core/modules/tus/` |
 | `user` | — | `src/core/modules/user/` |
 
+## Errors & Status Codes
+
+One 401/403 policy across all permission layers (role guards, tenant guard, `check()`,
+`checkRestricted()`, model `securityCheck()`):
+
+| Situation | Status | Message |
+|-----------|--------|---------|
+| Requester is **not authenticated** | **401** | `ErrorCode.UNAUTHORIZED` |
+| Requester **is authenticated** but lacks a right | **403** | `ErrorCode.ACCESS_DENIED` |
+| `S_NO_ONE` (locked for everyone, even admins) | **403 always** | `ErrorCode.ACCESS_DENIED` |
+
+Never hand-roll the decision — use `accessDeniedException(user)`. It returns the **native**
+`ForbiddenException` / `UnauthorizedException`, so `instanceof` checks and `@Catch(...)` filters
+in consuming projects keep working.
+
+### Exported error helpers
+
+| Export | Purpose | Path |
+|--------|---------|------|
+| `ExpiredRefreshTokenException` | Exception for expired refresh token | `src/core/modules/auth/exceptions/expired-refresh-token.exception.ts` |
+| `ExpiredTokenException` | Exception for expired token | `src/core/modules/auth/exceptions/expired-token.exception.ts` |
+| `InvalidTokenException` | Exception for invalid token | `src/core/modules/auth/exceptions/invalid-token.exception.ts` |
+| `LegacyAuthDisabledException` | Exception thrown when Legacy Auth endpoints are accessed but disabled | `src/core/modules/auth/exceptions/legacy-auth-disabled.exception.ts` |
+| `accessDeniedException()` | Creates the access error that matches the requester's auth state (RFC 9110, mirrors RolesGuard): | `src/core/common/exceptions/access-denied.exception.ts` |
+
 ## Key Source Files
 
 | File | Purpose |
@@ -293,6 +318,7 @@ Generic: `CrudService<Model, CreateInput, UpdateInput>`
 | `src/core/common/services/crud.service.ts` | CrudService base class |
 | `src/core/common/services/config.service.ts` | ConfigService (global) |
 | `src/core/common/decorators/` | @Restricted, @Roles, @CurrentUser, @UnifiedField |
+| `src/core/common/exceptions/` | accessDeniedException — the 401/403 policy |
 | `src/core/common/interceptors/` | CheckResponse, CheckSecurity, ResponseModel |
 | `docs/REQUEST-LIFECYCLE.md` | Complete request lifecycle |
 | `.claude/rules/` | Detailed rules for architecture, security, testing |

package/dist/core/common/decorators/restricted.decorator.d.ts

@@ -6,9 +6,9 @@ export type RestrictedType = (RequireAtLeastOne<{
     processType?: ProcessType;
     roles?: string | string[];
 }, 'memberOf' | 'roles'> | string | string[])[];
-export declare const Restricted: (...rolesOrMember: RestrictedType) => ClassDecorator & PropertyDecorator;
-export declare const getRestricted: (object: unknown, propertyKey?: string) => RestrictedType;
-export declare const checkRestricted: (data: any, user: {
+export declare function Restricted(...rolesOrMember: RestrictedType): ClassDecorator & PropertyDecorator;
+export declare function getRestricted(object: unknown, propertyKey?: string): RestrictedType;
+export declare function checkRestricted(data: any, user: {
     emailVerified?: any;
     hasRole: (roles: string[]) => boolean;
     id: any;
@@ -28,4 +28,4 @@ export declare const checkRestricted: (data: any, user: {
     processType?: ProcessType;
     removeUndefinedFromResultArray?: boolean;
     throwError?: boolean;
-}, processedObjects?: WeakSet<object>) => any;
+}, processedObjects?: WeakSet<object>): any;

package/dist/core/common/decorators/restricted.decorator.js

@@ -1,20 +1,22 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.checkRestricted = exports.getRestricted = exports.Restricted = void 0;
-const common_1 = require("@nestjs/common");
+exports.Restricted = Restricted;
+exports.getRestricted = getRestricted;
+exports.checkRestricted = checkRestricted;
 require("reflect-metadata");
 const _ = require("lodash");
+const process_type_enum_1 = require("../enums/process-type.enum");
 const role_enum_1 = require("../enums/role.enum");
-const db_helper_1 = require("../helpers/db.helper");
+const access_denied_exception_1 = require("../exceptions/access-denied.exception");
+const id_helper_1 = require("../helpers/id.helper");
 const request_context_service_1 = require("../services/request-context.service");
 const core_tenant_helpers_1 = require("../../modules/tenant/core-tenant.helpers");
 const restrictedMetaKey = Symbol('restricted');
-const Restricted = (...rolesOrMember) => {
+function Restricted(...rolesOrMember) {
     return Reflect.metadata(restrictedMetaKey, rolesOrMember);
-};
-exports.Restricted = Restricted;
+}
 const restrictedMetadataCache = new WeakMap();
-const getRestricted = (object, propertyKey) => {
+function getRestricted(object, propertyKey) {
     if (!object) {
         return null;
     }
@@ -38,9 +40,8 @@ const getRestricted = (object, propertyKey) => {
         : Reflect.getMetadata(restrictedMetaKey, object);
     classCache.set(cacheKey, metadata);
     return metadata;
-};
-exports.getRestricted = getRestricted;
-const checkRestricted = (data, user, options = {}, processedObjects = new WeakSet()) => {
+}
+function checkRestricted(data, user, options = {}, processedObjects = new WeakSet()) {
     const config = {
         allowCreatorOfParent: true,
         checkObjectItself: false,
@@ -70,7 +71,7 @@ const checkRestricted = (data, user, options = {}, processedObjects = new WeakSe
             !Array.isArray(sample) &&
             sample.constructor &&
             sample.constructor !== Object) {
-            const classRestrictions = (0, exports.getRestricted)(sample.constructor) || [];
+            const classRestrictions = getRestricted(sample.constructor) || [];
             if (classRestrictions.length) {
                 const hasCreatorOrSelf = classRestrictions.some((r) => r === role_enum_1.RoleEnum.S_CREATOR ||
                     r === role_enum_1.RoleEnum.S_SELF ||
@@ -84,7 +85,7 @@ const checkRestricted = (data, user, options = {}, processedObjects = new WeakSe
                             r.roles === role_enum_1.RoleEnum.S_CREATOR ||
                             r.roles === role_enum_1.RoleEnum.S_SELF)));
                 if (!hasCreatorOrSelf) {
-                    const sampleResult = (0, exports.checkRestricted)(sample, user, config, processedObjects);
+                    const sampleResult = checkRestricted(sample, user, config, processedObjects);
                     if (sampleResult === undefined || sampleResult === null) {
                         if (config.throwError) {
                             return data;
@@ -93,7 +94,7 @@ const checkRestricted = (data, user, options = {}, processedObjects = new WeakSe
                     }
                     const result = [sampleResult];
                     for (let i = 1; i < data.length; i++) {
-                        result.push((0, exports.checkRestricted)(data[i], user, config, processedObjects));
+                        result.push(checkRestricted(data[i], user, config, processedObjects));
                     }
                     if (!config.throwError && config.removeUndefinedFromResultArray) {
                         return result.filter((item) => item !== undefined);
@@ -102,7 +103,7 @@ const checkRestricted = (data, user, options = {}, processedObjects = new WeakSe
                 }
             }
         }
-        let result = data.map((item) => (0, exports.checkRestricted)(item, user, config, processedObjects));
+        let result = data.map((item) => checkRestricted(item, user, config, processedObjects));
         if (!config.throwError && config.removeUndefinedFromResultArray) {
             result = result.filter((item) => item !== undefined);
         }
@@ -138,13 +139,14 @@ const checkRestricted = (data, user, options = {}, processedObjects = new WeakSe
             if (roles.includes(role_enum_1.RoleEnum.S_NO_ONE)) {
                 return false;
             }
+            const owner = config.processType === process_type_enum_1.ProcessType.INPUT ? config.dbObject : data;
             if (roles.includes(role_enum_1.RoleEnum.S_EVERYONE) ||
                 user?.hasRole?.(roles) ||
                 (user?.id && roles.includes(role_enum_1.RoleEnum.S_USER)) ||
-                (roles.includes(role_enum_1.RoleEnum.S_SELF) && (0, db_helper_1.equalIds)(data, user)) ||
+                (roles.includes(role_enum_1.RoleEnum.S_SELF) && (0, id_helper_1.equalIds)(owner, user)) ||
                 (roles.includes(role_enum_1.RoleEnum.S_CREATOR) &&
-                    (('createdBy' in data && (0, db_helper_1.equalIds)(data.createdBy, user)) ||
-                        (config.allowCreatorOfParent && !('createdBy' in data) && config.isCreatorOfParent))) ||
+                    ((owner && 'createdBy' in owner && (0, id_helper_1.equalIds)(owner.createdBy, user)) ||
+                        (config.allowCreatorOfParent && owner && !('createdBy' in owner) && config.isCreatorOfParent))) ||
                 (roles.includes(role_enum_1.RoleEnum.S_VERIFIED) && (user?.verified || user?.verifiedAt || user?.emailVerified)) ||
                 (user?.id && (0, core_tenant_helpers_1.checkRoleAccess)(roles, user?.roles, request_context_service_1.RequestContext.get()?.tenantRole))) {
                 valid = true;
@@ -175,7 +177,7 @@ const checkRestricted = (data, user, options = {}, processedObjects = new WeakSe
                         }
                     }
                 }
-                if ((0, db_helper_1.getIncludedIds)(members, user)) {
+                if ((0, id_helper_1.getIncludedIds)(members, user)) {
                     valid = true;
                 }
             }
@@ -185,7 +187,7 @@ const checkRestricted = (data, user, options = {}, processedObjects = new WeakSe
         }
         return valid;
     };
-    const objectRestrictions = (0, exports.getRestricted)(data.constructor) || [];
+    const objectRestrictions = getRestricted(data.constructor) || [];
     if (config.checkObjectItself) {
         const objectIsValid = validateRestricted(objectRestrictions);
         if (!objectIsValid) {
@@ -193,7 +195,7 @@ const checkRestricted = (data, user, options = {}, processedObjects = new WeakSe
                 console.debug(`The current user has no access rights for ${data.constructor?.name}`);
             }
             if (config.throwError) {
-                throw new common_1.UnauthorizedException(`The current user has no access rights for ${data.constructor?.name}`);
+                throw (0, access_denied_exception_1.accessDeniedException)(user);
             }
             return null;
         }
@@ -205,25 +207,26 @@ const checkRestricted = (data, user, options = {}, processedObjects = new WeakSe
         if (data[propertyKey] === undefined && config.ignoreUndefined) {
             continue;
         }
-        const restricted = (0, exports.getRestricted)(data, propertyKey) || [];
+        const restricted = getRestricted(data, propertyKey) || [];
         const concatenatedRestrictions = config.mergeRoles && objectRestrictions.length ? _.uniq(objectRestrictions.concat(restricted)) : restricted;
         const valid = validateRestricted(concatenatedRestrictions);
         if (valid) {
+            const parent = config.processType === process_type_enum_1.ProcessType.INPUT ? config.dbObject : data;
             config.isCreatorOfParent =
-                (0, db_helper_1.equalIds)(data, user) || ('createdBy' in data ? (0, db_helper_1.equalIds)(data.createdBy, user) : config.isCreatorOfParent);
-            data[propertyKey] = (0, exports.checkRestricted)(data[propertyKey], user, config, processedObjects);
+                (0, id_helper_1.equalIds)(parent, user) ||
+                    (parent && 'createdBy' in parent ? (0, id_helper_1.equalIds)(parent.createdBy, user) : config.isCreatorOfParent);
+            data[propertyKey] = checkRestricted(data[propertyKey], user, config, processedObjects);
         }
         else {
             if (config.debug) {
                 console.debug(`The current user has no access rights for ${propertyKey}${data.constructor?.name ? ` of ${data.constructor.name}` : ''}`);
             }
             if (config.throwError) {
-                throw new common_1.UnauthorizedException(`The current user has no access rights for ${propertyKey}${data.constructor?.name ? ` of ${data.constructor.name}` : ''}`);
+                throw (0, access_denied_exception_1.accessDeniedException)(user);
             }
             delete data[propertyKey];
         }
     }
     return data;
-};
-exports.checkRestricted = checkRestricted;
+}
 //# sourceMappingURL=restricted.decorator.js.map