@lenne.tech/nest-server 11.27.7 → 11.28.1

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/migration-guides/11.28.0-to-11.28.1.md

@@ -0,0 +1,155 @@
+# Migration Guide: 11.28.0 → 11.28.1
+
+## Overview
+
+| Category | Details |
+|----------|---------|
+| **Breaking Changes** | None |
+| **Bugfixes** | Internal only — the `ejs` import in the BetterAuth email-verification service was normalized to the CommonJS style (`import ejs = require('ejs')`), silencing a static-analysis warning. No runtime behavior change. |
+| **New Features** | None |
+| **Maintenance** | Dependency housekeeping: 17 within-major package updates, 4 previously-undeclared runtime dependencies now declared explicitly, security overrides pruned 9 → 6. `pnpm audit` remains at **0 vulnerabilities**. |
+| **Migration Effort** | **0 minutes for npm-mode consumers** (`pnpm update`). **~2 minutes for vendor-mode consumers** — ensure 4 runtime dependencies are present (see below). |
+
+This is a **pure maintenance patch**. There is no API change, no configuration change, and no
+behavioral change. Every one of the framework's 1381 tests passes unchanged.
+
+---
+
+## Quick Migration (npm mode)
+
+No code changes required.
+
+```bash
+# Update the package
+pnpm add @lenne.tech/nest-server@11.28.1
+
+# Verify
+pnpm run build
+pnpm test
+```
+
+All transitive dependency changes resolve automatically. Nothing in your project needs to change.
+
+---
+
+## What Changed
+
+### 1. Framework dependency updates (all within NestJS 11)
+
+The MAJOR version still mirrors NestJS 11 — no NestJS major boundary was crossed. Notable updates:
+
+| Package | 11.28.0 | 11.28.1 | Note |
+|---------|---------|---------|------|
+| `@nestjs/common` / `core` / `platform-express` / `websockets` | 11.1.23 | 11.1.28 | NestJS 11 patch |
+| `mongoose` | 9.6.2 | 9.7.4 | Minor (mongodb stays 7.2.0 — coupled) |
+| `nodemailer` | 8.0.8 | 9.0.3 | **Major bump** — internal email transport (see Compatibility Notes) |
+| `multer` | 2.1.1 | 2.2.0 | Security (unhandled multipart DoS) |
+| `graphql-query-complexity` | 1.1.0 | 1.1.1 | Patch |
+
+Dev-only tooling was also refreshed (`vitest`/`@vitest/*` 4.1.7 → 4.1.10, `vite` 8.0.14 → 8.1.4,
+`oxlint` 1.66.0 → 1.74.0, `@swc/core` 1.15.40 → 1.15.43, `tsx` 4.22.3 → 4.23.1, plus `@types/*`).
+Dev-tooling changes have **zero** effect on consuming projects.
+
+### 2. Newly declared runtime dependencies (relevant for vendor mode)
+
+Four packages that the framework's shipped code **imports directly** were previously only resolved
+**transitively** (phantom dependencies), relying on pnpm hoisting. They are now declared explicitly
+and pinned to the exact versions that were already resolving — **this is a declaration change, not a
+version bump, so nothing new is installed for npm-mode consumers.**
+
+| Package | Version | Imported by | Reached transitively before via |
+|---------|---------|-------------|----------------------------------|
+| `cron` | 4.4.0 | `src/core/common/services/core-cron-jobs.service.ts` (`new CronJob`) | `@nestjs/schedule` |
+| `jose` | 6.2.1 | `src/core/modules/better-auth/core-better-auth.service.ts` (`importJWK`/`jwtVerify`) | `better-auth`, `@modelcontextprotocol/sdk` |
+| `ws` | 8.21.0 | `src/test/test.helper.ts` (`require('ws')`) | `@nestjs/graphql`, `@nestjs/apollo` |
+| `graphql-ws` | 6.0.8 | `src/test/test.helper.ts` (`createClient`) | `@nestjs/graphql`, `@nestjs/apollo` |
+
+Why this matters: relying on a transitive package means its presence and **version** are controlled
+by someone else's dependency tree. `ws` already resolved to two versions in the tree (`8.21.0` and
+a nested `7.5.11`); an explicit declaration removes the hoisting lottery.
+
+### 3. Security override cleanup (9 → 6)
+
+Three overrides in `pnpm-workspace.yaml` became genuine no-ops after the direct-dependency updates
+above and were removed (verified with `pnpm audit`, which stays at 0 vulnerabilities):
+
+| Removed override | Now resolved by |
+|------------------|-----------------|
+| `nodemailer@<9.0.1` | direct dependency is now `nodemailer@9.0.3` (the old override was silently patching a vulnerable `8.0.8` direct pin) |
+| `multer@<2.2.0` | `@nestjs/platform-express@11.1.28` now pins `multer@2.2.0` exactly |
+| `vite@>=8.0.0 <8.0.16` | all `vite` now resolves to `8.1.4` |
+
+Six overrides remain, each proven still load-bearing (removing them reintroduces a vulnerability):
+`ajv`, `picomatch`, `ws`, `uuid`, `@babel/core`, `js-yaml`. Each carries its CVE/GHSA rationale as
+an inline comment.
+
+---
+
+## Compatibility Notes
+
+- **npm-mode consumers:** Nothing to do. `pnpm update @lenne.tech/nest-server` is sufficient.
+- **`nodemailer` 8 → 9 (internal):** `nodemailer` is used internally by the framework's
+  `EmailService`/SMTP transport. Projects configure it declaratively through
+  `email.smtp` in `config.env.ts`, and those options are unchanged across the 8 → 9 boundary — all
+  email tests pass unmodified. If (and only if) your project constructs a **custom `nodemailer`
+  transport object directly** and passes it in, review the
+  [nodemailer 9 release notes](https://github.com/nodemailer/nodemailer/releases) for the transport
+  API. The declarative `email.smtp` path needs no changes.
+- **Projects without BetterAuth / cron / GraphQL subscriptions:** Unaffected — the newly declared
+  packages were already in your tree transitively.
+
+### Vendor-mode consumers (`src/core/` copied into your project)
+
+Vendor-mode projects do **not** install `@lenne.tech/nest-server` as an npm dependency, so they do
+not inherit its `dependencies`. After syncing this release into your vendored `src/core/`, make sure
+these four runtime packages exist in **your** `package.json` (pinned, per the fixed-version rule):
+
+```jsonc
+{
+  "dependencies": {
+    "cron": "4.4.0",          // required — imported by core-cron-jobs.service.ts
+    "jose": "6.2.1"           // required — imported by core-better-auth.service.ts
+    // ws / graphql-ws: required only if you use the exported TestHelper (src/test/test.helper.ts)
+    // in your own tests — most projects do:
+    // "graphql-ws": "6.0.8",
+    // "ws": "8.21.0"
+  }
+}
+```
+
+In practice these are almost always already present transitively (via `@nestjs/schedule`,
+`better-auth`, `@nestjs/graphql`). Declaring them explicitly protects you from a future transitive
+change silently removing them. The `lt-dev:nest-server-core-updater` agent surfaces this during a
+core sync.
+
+---
+
+## Troubleshooting
+
+### `Cannot find module 'jose'` / `'cron'` after a vendor-mode sync
+
+You copied the updated `src/core/` but did not add the runtime dependency. Add the package to your
+project's `package.json` (see the vendor-mode block above) and run `pnpm install`.
+
+### `pnpm audit` reports a vulnerability I thought an override covered
+
+The `nodemailer`, `multer`, and `vite` overrides were removed because the direct/transitive
+resolutions now land on fixed versions on their own. If your project maintains its **own**
+`pnpm-workspace.yaml` overrides (vendor mode or a monorepo root), re-verify with a with/without
+lockfile diff — do not blindly copy this repo's removals; your tree may still resolve a vulnerable
+version back into range.
+
+### Build tool (`nest build`) fails with a permission error after `pnpm install`
+
+Unrelated to your code — a known pnpm 11 hoisted-linker store-dedup artifact can drop the executable
+bit on `node_modules/.bin/nest`. This release deliberately keeps `@nestjs/cli` at `11.0.21` to avoid
+re-linking it. If you still hit it, `chmod +x node_modules/@nestjs/cli/bin/nest.js` restores it and
+survives subsequent installs.
+
+---
+
+## References
+
+- [Package Management Rules](../.claude/rules/package-management.md) — fixed-version policy, override target rules
+- [Migration Guide 11.27.7 → 11.28.0](./11.27.7-to-11.28.0.md) — previous release (the 401/403 policy + S_SELF/S_CREATOR ownership fixes)
+- [nest-server-starter](https://github.com/lenneTech/nest-server-starter) (reference implementation)