@lenne.tech/nest-server 11.28.1 → 11.29.1

package/docs/REQUEST-LIFECYCLE.md

@@ -528,6 +528,18 @@ Authenticates the request using three strategies in priority order:
 
 If authentication succeeds, `req.user` is set with the authenticated user (including `hasRole()` method).
 
+> **Native `/iam/*` routes bypass the `@Roles()`/`checkRoles` layer.** Better-Auth's own endpoints
+> (e.g. `POST /iam/update-user`, `POST /iam/sign-up/email`) that are **not** in
+> `CONTROLLER_HANDLED_PATHS` are forwarded raw by `CoreBetterAuthApiMiddleware` to Better-Auth's
+> native handler under its `sessionMiddleware` — i.e. reachable by **any authenticated user**,
+> independent of the controller's class-level `@Roles(ADMIN)` and nest-server's `checkRoles`. This is
+> why server-managed user fields (`roles`, `verified`, `verifiedAt`, `twoFactorEnabled`, `iamId`) are
+> locked at the Better-Auth schema layer with `input: false` (see `betterAuth.additionalUserFields[].input`
+> in `.claude/rules/configurable-features.md` and `.claude/rules/better-auth.md` §2): field-level
+> input rejection is the correct control here because the guard layer does not run on these
+> raw-forwarded routes. A forged `POST /iam/update-user {"roles":["admin"]}` is rejected with
+> `FIELD_NOT_ALLOWED` (HTTP 400) at the input-parse stage, before any persistence.
+
 #### 3. graphqlUploadExpress
 
 Only for GraphQL routes. Handles multipart file upload requests according to the [GraphQL multipart request specification](https://github.com/jaydenseric/graphql-multipart-request-spec).

package/migration-guides/11.28.1-to-11.29.0.md

@@ -0,0 +1,231 @@
+# Migration Guide: 11.28.1 → 11.29.0
+
+## Overview
+
+| Category | Details |
+|----------|---------|
+| **Breaking Changes** | Server-managed Better-Auth user fields (`roles`, `verified`, `verifiedAt`, `twoFactorEnabled`, `iamId`, and by default `termsAndPrivacyAcceptedAt`) are now registered with `input: false`, so Better-Auth's **native** input parsing rejects client-supplied values. Behavioral change on `POST /iam/update-user` and `POST /iam/sign-up/email`. |
+| **Security Fix** | Closes a confirmed **vertical privilege-escalation** vulnerability (OWASP A01): any authenticated user could self-grant `admin` via `POST /iam/update-user {"roles":["admin"]}`. |
+| **New Features** | New per-field `input?: boolean` option on `IBetterAuthUserField` (`betterAuth.additionalUserFields`) so projects can mark their own fields as server-managed. New parallel-safe e2e test infrastructure (machine-wide run governor, startup sweep, `retry: 2`) — optional adoption, see below. |
+| **Bugfix** | `CoreUserService.create()` now checks email uniqueness at application level (the unique index alone misses duplicates on a fresh database while autoIndex is still building — same window on freshly deployed production DBs). **Behavioral note:** a duplicate email via `userService.create()` now always yields **400 "Email address already in use"** — previously, callers other than `signUp` could see a raw **422 Unprocessable Entity** when the error surfaced as a Mongo duplicate-key error. Adjust tests that asserted the 422. |
+| **Migration Effort** | **~0 minutes for most projects** (`pnpm update`). **Audit required** only if your project relied on client-setting one of the locked fields via the Better-Auth input path — see below. |
+
+MINOR was incremented because this repo's scheme treats behavioral/breaking changes as MINOR (MAJOR mirrors the NestJS version, still 11).
+
+---
+
+## Why this change
+
+Better-Auth registers `betterAuth.additionalUserFields` as native `additionalFields`, and Better-Auth
+defaults each field to `input: true` — i.e. **client-settable** via `POST /iam/sign-up/email` and
+`POST /iam/update-user`. Critically, `/iam/update-user` is **not** in `CONTROLLER_HANDLED_PATHS`, so
+`CoreBetterAuthApiMiddleware` forwards it raw to Better-Auth's native handler under its
+`sessionMiddleware` — reachable by **any authenticated user**, bypassing the controller's class-level
+`@Roles(ADMIN)` and nest-server's `checkRoles`.
+
+Before 11.29.0 the server-managed `roles` field was registered **without** `input: false`. The result:
+
+```http
+POST /iam/update-user
+Authorization: Bearer <any authenticated user's token>
+
+{ "roles": ["admin"] }
+```
+
+…wrote `roles: ["admin"]` onto the caller's own user row, which then became authoritative for
+`@Restricted(RoleEnum.ADMIN)`. A freshly self-registered user could make themselves admin.
+
+## What changed
+
+Server-managed core fields are now registered with `input: false` and **re-asserted after** any
+project `additionalUserFields` are merged, so a project override cannot silently re-open them. The
+security-critical, hard-locked set (`PROTECTED_INPUT_FALSE_KEYS`) is:
+
+| Field | Prevented attack |
+|-------|------------------|
+| `roles` | vertical privilege escalation (self-granting `admin`) |
+| `verified` / `verifiedAt` | email-verification bypass |
+| `twoFactorEnabled` | self-toggling the 2FA state |
+| `iamId` | identity / account-linking hijack |
+
+The lock is **column-scoped**: a shadow field whose `fieldName` maps to one of these columns
+(e.g. `{ customRoles: { fieldName: 'roles', input: true } }`) is also forced to `input: false`.
+
+Runtime behavior after the change:
+
+- `POST /iam/update-user {"roles":[...]}` (or `verified`, etc.) → **`FIELD_NOT_ALLOWED` (HTTP 400)**.
+- `POST /iam/sign-up/email {"roles":[...]}` → account created with the **server default** (`roles: []`);
+  the forged value is silently dropped, not persisted.
+- `termsAndPrivacyAcceptedAt` is `input: false` by **default** but is intentionally **not** in the
+  hard-lock set (it is a consent timestamp, not a privilege boundary) — a project may re-open it with
+  `additionalUserFields: { termsAndPrivacyAcceptedAt: { type: 'date', input: true } }`.
+
+**Unaffected:** nest-server's own role-assignment path — `UserService.setRoles`,
+`CrudService.update` (via `checkRoles`), and the Better-Auth user mapper's native `$set` writes — does
+**not** use Better-Auth input parsing and keeps working exactly as before. `input: false` only gates
+the Better-Auth native sign-up/update-user routes.
+
+---
+
+## Quick Migration (npm mode)
+
+For the overwhelming majority of projects, **no code change is required**:
+
+```bash
+pnpm add @lenne.tech/nest-server@11.29.0
+pnpm run build
+pnpm test
+```
+
+Your existing role assignment (admin panels calling `updateUser`/`setRoles`, sign-up flows,
+verification flows) continues to work — those go through nest-server's service layer, not the
+Better-Auth native input path.
+
+---
+
+## New: Parallel-Safe e2e Test Infrastructure (Optional Adoption)
+
+This release also overhauls the e2e test infrastructure so that MANY parallel sessions
+(`lt ticket` worktrees, several projects, agent sessions) can run test suites on one machine
+without starving each other or leaving database garbage behind. **These are repository files, not
+npm-package code** — `pnpm update` does NOT bring them into your project. Adopt them by syncing the
+test files from [nest-server-starter](https://github.com/lenneTech/nest-server-starter) (or via the
+lt-dev fullstack update agent):
+
+| File | What it adds |
+|------|--------------|
+| `tests/e2e-run-slots.ts` (new) | **Machine-wide run governor**: at most N concurrent e2e runs across ALL lt projects (slot files in the OS temp dir, PID-liveness crash recovery, fail-open). Knobs: `LT_E2E_MAX_RUNS` (0 disables), `LT_E2E_SLOT_DIR`, `LT_E2E_SLOT_TIMEOUT`. |
+| `tests/global-setup.ts` | **Startup sweep** — stale test DBs of this project AND leftover upload-test artifacts (`tests/*.txt` / `*.bin` from aborted file-upload specs) are removed when the next run STARTS, so cleanup survives SIGKILL (watchdog) and `--reporter` CLI overrides; then acquires a governor slot. |
+| `tests/db-lifecycle.reporter.ts` | Exports the shared `isStaleTestDb()` predicate used by the sweep; failure message now points to the startup-sweep semantics. |
+| `vitest-e2e.config.ts` | Auto low-resource mode when **another e2e run is active** (deterministic slot signal — the 1-minute load average structurally lags short runs) or load is high; **`retry: 2`** (a higher retry turns one broken spec file into an hour-long 0%-CPU grind that looks like a deadlock). |
+| `tests/unit/e2e-run-slots.spec.ts` (new) | Unit tests for the governor. |
+
+Measured effect (12-core machine): two overlapping full-speed runs previously drove load to 30 with
+spurious 401 failures; with the governor, 6 parallel project checks all pass in 109–125s. A run
+printing `[e2e-governor] waiting for a free e2e slot` every 15s is **queued, not hung**.
+
+Rule carried over from the reporter docs: specs that need an extra database must derive it via
+`deriveTestDbUri('<suffix>')` — never a hardcoded or `Date.now()`-based name — and drop their DB
+**after** `app.close()` (async module init can re-create a database dropped while the app is alive).
+
+**Related: `scripts/check.mjs` (canonical version distributed by the lt CLI).** The report-driven
+check wrapper gained the same robustness set across all lt base repos: an **idle-watchdog** that
+kills a test step after 300s of silence and diagnoses it as a hang (`CHECK_IDLE_TIMEOUT` /
+`--idle-timeout=<s>`, 0 disables), whole-process-tree kills (no orphaned fork workers), a
+SIGTERM/SIGKILL exit hint (a killed step is not an assertion failure), summed vitest metrics
+(unit + e2e runs are no longer under-reported), and the audit rendered like every other step.
+Consumer projects receive it via `lt fullstack update` (self-heal; skips a `scripts/check.mjs`
+with uncommitted local edits) — `lt dev doctor` warns when the local copy drifts from the
+canonical version.
+
+---
+
+## Audit Before Upgrading
+
+> **Mirrors the v11.28.x precedent in [`.claude/rules/role-system.md`](../.claude/rules/role-system.md)
+> ("Audit every `S_SELF`/`S_CREATOR` on an input type before upgrading").**
+
+You only need to act if **both** are true for your project:
+
+1. You send `roles`, `verified`, `verifiedAt`, `twoFactorEnabled`, `iamId` (or
+   `termsAndPrivacyAcceptedAt`) in the **body of `POST /iam/update-user` or `POST /iam/sign-up/email`**
+   (i.e. through Better-Auth's native input path), **and**
+2. You expected that value to be persisted.
+
+If so, those requests will now receive `400 FIELD_NOT_ALLOWED` (update-user) or silently get the
+server default (sign-up). **Move the assignment to the correct server-side path:**
+
+```typescript
+// BEFORE (relied on Better-Auth native input — now rejected):
+// POST /iam/update-user { "roles": ["admin"] }
+
+// AFTER — assign roles through nest-server's service layer (authorized + audited):
+await this.userService.setRoles(userId, [RoleEnum.ADMIN]);
+// or, from an admin-driven update that runs checkRoles:
+await this.userService.update(userId, { roles: [RoleEnum.ADMIN] }, { currentUser: adminUser });
+```
+
+If you deliberately need one of your **own** `additionalUserFields` to be server-managed, set
+`input: false` on it:
+
+```typescript
+betterAuth: {
+  additionalUserFields: {
+    internalScore: { type: 'number', defaultValue: 0, input: false }, // rejects client input
+  },
+}
+```
+
+**Note:** You cannot re-open a hard-locked key (`roles`, `verified`, `verifiedAt`, `twoFactorEnabled`,
+`iamId`) via `additionalUserFields` — the re-assertion re-locks it by design. This is intentional and
+is the security guarantee of this release.
+
+---
+
+## Compatibility Notes
+
+| Pattern | Status |
+|---------|--------|
+| Admin panel updating roles via `UserService`/`CrudService`/GraphQL `updateUser` | ✅ Unaffected — service layer, not Better-Auth input |
+| Sign-up / email verification / 2FA enable-disable flows | ✅ Unaffected — server-managed |
+| Reading `roles`/`verified` in responses | ✅ Unaffected — `input: false` only gates writes |
+| Client sending `roles`/`verified` in `/iam/update-user` or `/iam/sign-up/email` body | ⚠️ Now rejected/dropped — this was the vulnerability |
+| Custom `additionalUserFields` (non-protected keys) | ✅ Unaffected — still client-settable unless you set `input: false` |
+
+### Toolchain: `engines.pnpm` now advertised
+
+`package.json` now declares `engines.pnpm: "^11.0.0"` (and drops the repo-internal `packageManager`
+pin). Impact on consumers is **low and pnpm-only**:
+
+- **npm / yarn consumers:** unaffected — they ignore `engines.pnpm`.
+- **pnpm consumers on pnpm ≥ 11:** unaffected.
+- **pnpm consumers on pnpm < 11:** you may see an `EBADENGINE` / `ERR_PNPM_UNSUPPORTED_ENGINE`
+  **warning** on install (a hard error only if you run with `engine-strict=true`). Upgrade to pnpm 11
+  (`corepack use pnpm@11` or `npm i -g pnpm@11`) to silence it. The framework's runtime does not
+  depend on pnpm — this only concerns the install step for pnpm-based projects.
+
+No `engines.node` change (still `>= 22`).
+
+### Vendor-mode consumers (`src/core/` copied into your project)
+
+This release touches only `src/core/modules/better-auth/better-auth.config.ts`,
+`src/core/common/interfaces/server-options.interface.ts` and
+`src/core/modules/user/core-user.service.ts` (bugfix: application-level email-uniqueness check in
+`create()` — the unique index alone misses duplicates on a fresh database while autoIndex is still
+building; raw Mongo duplicate-key errors now also map to the correct "Email address already in use"
+message) — no new files, no new imports, no new runtime dependencies. After syncing `src/core/` (via `/lt-dev:backend:update-nest-server-core` /
+`lt-dev:nest-server-core-updater`), no additional package or config work is required. Run your
+Better-Auth tests to confirm.
+
+---
+
+## Troubleshooting
+
+### A client integration started getting `400 FIELD_NOT_ALLOWED` on `/iam/update-user`
+
+Working as intended. The client was setting a server-managed field (`roles`/`verified`/…) through the
+Better-Auth native input path. Move that assignment to the server (`UserService.setRoles` /
+`CrudService.update` with an authorized `currentUser`), or — for your own field — decide whether it
+should really be `input: false`.
+
+### A user's `roles` no longer update after sign-up
+
+If you relied on passing `roles` in the sign-up body, that value is now dropped (server default
+applied). Assign roles explicitly after account creation via `UserService.setRoles`, or through your
+admin-provisioning flow.
+
+### I need one of my own additional fields to reject client input
+
+Add `input: false` to it in `betterAuth.additionalUserFields`. See the "Audit" section above.
+
+---
+
+## References
+
+- [Role System — S_ roles, 401/403 policy, S_SELF/S_CREATOR ownership](../.claude/rules/role-system.md)
+- [Better-Auth Module Rules — §2 server-managed fields must be `input: false`](../.claude/rules/better-auth.md)
+- [Configurable Features — BetterAuth Server-Managed User Fields](../.claude/rules/configurable-features.md)
+- [Request Lifecycle — native `/iam/*` routes bypass the guard layer](../docs/REQUEST-LIFECYCLE.md)
+- Regression test: `tests/stories/better-auth-privilege-escalation.e2e-spec.ts`
+- [Migration Guide 11.28.0 → 11.28.1](./11.28.0-to-11.28.1.md) — previous release
+- [nest-server-starter](https://github.com/lenneTech/nest-server-starter) (reference implementation)

package/migration-guides/11.29.0-to-11.29.1.md

@@ -0,0 +1,311 @@
+# Migration Guide: 11.29.0 → 11.29.1
+
+## Overview
+
+| Category | Details |
+|----------|---------|
+| **Breaking Changes** | None |
+| **Bugfixes** | None — no runtime code changed. `src/core/` is byte-identical to 11.29.0. |
+| **New Features** | None |
+| **Maintenance** | **Toolchain only.** `package.json#packageManager` is restored as the *single* place the pnpm version is pinned. `corepack` is gone from the `Dockerfile` (Node >= 25 no longer ships it); every pnpm-running build stage now provisions the pinned pnpm itself. `pnpm/action-setup` reads the pin instead of carrying its own `version` input. A contract test (`tests/unit/pnpm-pin-contract.spec.ts`) guards the whole chain. |
+| **Migration Effort** | **0 minutes for npm-mode and vendor-mode consumers** — nothing in your project changes. **~10 minutes if you adopt the pattern**, which you should do *before* moving any build to Node >= 25. |
+
+This release changes **how the framework repo builds itself**. It ships no API change, no
+configuration change, and no behavioral change. Update with `pnpm add @lenne.tech/nest-server@11.29.1`
+and you are done.
+
+The reason to read further: **the `Dockerfile` is not part of the npm package** (it is not in
+`package.json#files`). Your project's own `Dockerfile` and CI came from the starter template, so you
+do **not** inherit this fix automatically. If they still run `corepack enable`, they will break the
+day you move to Node >= 25 — see [Adopting the pattern](#adopting-the-pattern-in-your-project-recommended).
+
+---
+
+## Quick Migration (npm mode)
+
+No code changes required.
+
+```bash
+# Update the package
+pnpm add @lenne.tech/nest-server@11.29.1
+
+# Verify
+pnpm run build
+pnpm test
+```
+
+---
+
+## Why this release exists: corepack is going away
+
+`corepack` was the mechanism that read `package.json#packageManager` and materialized the right
+package-manager binary. It shipped with Node for years, which is why the framework's `Dockerfile`
+could simply say `corepack enable` and trust that pnpm appeared.
+
+**Node >= 25 no longer ships corepack.** A build stage that runs `corepack enable` on such an image
+fails outright:
+
+```
+/bin/sh: corepack: not found
+```
+
+So the framework needed a way to provision an exact pnpm version that does not depend on corepack
+existing — without giving up the single-source-of-truth pin.
+
+### What 11.29.0 did, and why it is reverted here
+
+11.29.0 removed the `packageManager` field and introduced `engines.pnpm: "^11.0.0"`. That left the
+repo with **no exact pin at all**, so the version had to be restated wherever pnpm was needed — the
+workflows grew a hardcoded `with: version: 11`, and Docker's `corepack enable` (with no
+`packageManager` field to follow) would resolve to whatever it considered current.
+
+Two sources of truth, neither exact. 11.29.1 collapses them back into one:
+
+| | 11.29.0 | 11.29.1 |
+|---|---|---|
+| `package.json#packageManager` | *(removed)* | `pnpm@11.13.1+sha512.…` — **the** pin |
+| `package.json#engines.pnpm` | `^11.0.0` | `^11.0.0` — unchanged, a soft major gate |
+| `.github/workflows/*` | `with: version: 11` | *(no `version` input — reads the pin)* |
+| `Dockerfile` | `corepack enable` | derive-line (below) |
+
+`engines.pnpm` stays, but understand what it is: a **soft major-range guard**, not a pin. It warns a
+pnpm 10 user; it does not tell CI which version to install. Only `packageManager` does that.
+
+---
+
+## What Changed
+
+### 1. `packageManager` is back — exact, with an integrity hash
+
+```jsonc
+// package.json
+{
+  "packageManager": "pnpm@11.13.1+sha512.b2fc7683b8a6525414e7d13e1ba28caaddde96bf66ec540bfaeb7e702b81f3e0be4d1f295edf7f9fe0396740a8dce4509c582ddf79891f4543fea32d37645f25",
+  "engines": {
+    "node": ">= 22",
+    "pnpm": "^11.0.0"
+  }
+}
+```
+
+**This field has no effect on your project.** `packageManager` is only ever read from the *root*
+`package.json` of the project being built — never from a dependency's. You inherit nothing from the
+framework's pin.
+
+Note that pnpm itself honours the field, with no corepack involved: run any `pnpm` command in a
+directory whose `package.json` pins a different pnpm, and pnpm switches to it
+(`managePackageManagerVersions`, on by default since pnpm 10). Corepack was never the only thing
+reading this field — which is exactly why dropping it costs nothing.
+
+### 2. The Dockerfile provisions pnpm without corepack
+
+Every stage that runs `pnpm` now provisions the pinned version itself, from the pin:
+
+```dockerfile
+# Provision the exact pnpm declared in package.json (single source of truth).
+# No corepack: Node >= 25 no longer ships it. The +sha512 suffix is stripped;
+# npm enforces registry integrity for the tarball itself.
+RUN npm install -g "$(node -p "require('./package.json').packageManager.split('+')[0]")"
+```
+
+The `.split('+')[0]` turns `pnpm@11.13.1+sha512.b2fc…` into `pnpm@11.13.1`, because `npm install -g`
+takes a plain spec. The dropped hash is not a loss of integrity: npm verifies the tarball against the
+registry's own integrity metadata on install.
+
+The line appears **once per pnpm-running stage** (`deps` and `builder`) — Docker stages do not inherit
+each other's globally installed binaries, only what is explicitly `COPY --from=`'d.
+
+### 3. `pnpm/action-setup` no longer carries a `version` input
+
+```yaml
+- name: Install pnpm
+  # No version input: the exact version is read from package.json's packageManager field.
+  uses: pnpm/action-setup@v6
+```
+
+The action reads `packageManager` on its own. Specifying **both** is not redundant-but-harmless — the
+action treats a mismatch as a hard error, so the two sources cannot silently drift.
+
+### 4. A contract test guards the chain
+
+`tests/unit/pnpm-pin-contract.spec.ts` (11 assertions, unit suite, no MongoDB) fails the build if
+anyone re-introduces the drift this release removes:
+
+- the pin is exact (`x.y.z` + `sha512` hash — never a range),
+- `engines.pnpm` tracks the pin's major,
+- `devEngines.packageManager` never (re)appears — npm/npx abort with `EBADDEVENGINES` on it,
+- the `Dockerfile` contains no `corepack` in any `RUN`,
+- **every** pnpm-running stage runs the derive-line *before* its first `pnpm` command, and only after
+  a `COPY` has put `package.json` in place,
+- no workflow passes a `version:` to `pnpm/action-setup` or hardcodes `npm install -g pnpm@…`.
+
+A twelfth test proves the chain end-to-end — it derives the spec exactly as the Dockerfile does,
+installs it into a throwaway prefix, and asserts the provisioned binary reports the pinned version.
+It needs network and ~10 MB, so it is gated to `CI` / `PIN_PROVISION_TEST=1` and stays out of your way
+locally.
+
+---
+
+## Breaking Changes
+
+**None.** No public API, config key, decorator, or exported symbol changed.
+
+---
+
+## Adopting the pattern in your project (recommended)
+
+Do this **before** you move any build to Node >= 25 — not after it breaks. If your project was
+generated from a recent `nest-server-starter` / `lt fullstack init`, check whether it is already done.
+
+### Step 1: Pin pnpm in your root `package.json`
+
+```bash
+# Writes packageManager with the integrity hash for the version you actually use
+pnpm self-update
+```
+
+Or set it by hand — the exact form matters (`pnpm@x.y.z+sha512.<hash>`):
+
+```jsonc
+{
+  "packageManager": "pnpm@11.13.1+sha512.b2fc7683…",
+  "engines": { "node": ">= 22", "pnpm": "^11.0.0" }
+}
+```
+
+> **Monorepo:** this belongs in the **workspace root** `package.json`, not only in `projects/api/`.
+> The Dockerfile's derive-line reads `/app/package.json`, which in monorepo mode
+> (`--build-arg API_DIR=projects/api`) is the root manifest. See
+> [Troubleshooting](#docker-build-fails-with-typeerror-cannot-read-properties-of-undefined-reading-split).
+
+### Step 2: Replace corepack in your Dockerfile
+
+**Before:**
+```dockerfile
+RUN apk add --no-cache python3 make g++ && corepack enable
+```
+
+**After:**
+```dockerfile
+RUN apk add --no-cache python3 make g++
+
+# … COPY the manifests first — the derive-line reads package.json …
+
+# Provision the exact pnpm declared in package.json (single source of truth).
+# No corepack: Node >= 25 no longer ships it. The +sha512 suffix is stripped;
+# npm enforces registry integrity for the tarball itself.
+RUN npm install -g "$(node -p "require('./package.json').packageManager.split('+')[0]")"
+```
+
+Two ordering rules, both easy to get wrong:
+
+1. The derive-line must come **after** the `COPY` that puts `package.json` into the WORKDIR — it
+   reads that file.
+2. It must be repeated in **each** stage that runs `pnpm`. A global install in `deps` does not reach
+   `builder`.
+
+### Step 3: Drop the hardcoded version in CI
+
+**GitHub Actions** — remove the `version` input:
+
+```yaml
+- name: Install pnpm
+  uses: pnpm/action-setup@v6      # reads packageManager; no `with: version:`
+```
+
+**GitLab CI** (or any runner without the action) — use the same derive-line:
+
+```yaml
+before_script:
+  # Provision the exact pnpm pinned in package.json (single source of truth).
+  - npm install -g "$(node -p "require('./package.json').packageManager.split('+')[0]")"
+  - pnpm install --frozen-lockfile
+```
+
+### Step 4 (optional): Guard it with a test
+
+Copy `tests/unit/pnpm-pin-contract.spec.ts` from this repo and trim it to the files your project has.
+The value is not the assertions — it is that the next person who "helpfully" re-adds
+`with: version: 11` or a second `npm install -g pnpm@…` gets a red build instead of a silent drift
+that surfaces months later as an unreproducible container.
+
+---
+
+## Compatibility Notes
+
+| Pattern | Status |
+|---------|--------|
+| Any application code, decorator, service, or config using the framework | ✅ Unaffected — no runtime code changed |
+| **npm-mode** consumers (`@lenne.tech/nest-server` as a dependency) | ✅ Unaffected — `pnpm add …@11.29.1` and done |
+| **Vendor-mode** consumers (`src/core/` copied in) | ✅ Unaffected — `src/core/` is byte-identical to 11.29.0; a sync produces no delta |
+| The framework's `packageManager` pin leaking into your project | ✅ Impossible — the field is read only from the root manifest, never from a dependency |
+| Your project's `Dockerfile` still using `corepack enable` | ⚠️ Works on Node <= 24, **breaks on Node >= 25** — apply Step 2 |
+| Your CI passing both `with: version:` **and** having a `packageManager` field | ⚠️ Hard error on version mismatch — apply Step 3 |
+| Node version | ✅ Unchanged (`engines.node: ">= 22"`); the framework's own images stay on Node 24 LTS |
+| pnpm 10 or older as your project's package manager | ⚠️ `engines.pnpm: "^11.0.0"` warns (`EBADENGINE`); a hard failure only with `engine-strict=true` |
+
+---
+
+## Troubleshooting
+
+### `corepack: not found` in a Docker build or CI job
+
+You moved to a Node >= 25 image while your build still calls `corepack enable`. This is exactly the
+failure this release prevents — apply [Step 2](#step-2-replace-corepack-in-your-dockerfile). Do not
+"fix" it with `npm install -g corepack`: that reintroduces the indirection the derive-line removes.
+
+### Docker build fails with `TypeError: Cannot read properties of undefined (reading 'split')`
+
+The derive-line found a `package.json` **without** a `packageManager` field. Almost always a
+monorepo: in monorepo mode the build context is the workspace root, so `/app/package.json` is the
+**root** manifest — and the pin was only added to `projects/api/package.json`.
+
+Fix: add `packageManager` to the workspace **root** manifest (Step 1). Keeping the root and the API
+package on the same pin is the point — one pnpm builds the whole workspace.
+
+### `ERR_PNPM_BAD_PM_VERSION`, or the action reports multiple pnpm versions
+
+Two sources disagree about the version. Either your workflow still passes `with: version:` alongside
+a `packageManager` field (remove the input — [Step 3](#step-3-drop-the-hardcoded-version-in-ci)), or a
+stray `npm install -g pnpm@<other>` runs before the derive-line.
+
+### `EBADENGINE` / `ERR_PNPM_UNSUPPORTED_ENGINE` warning mentioning pnpm
+
+Unchanged from 11.29.0 — `engines.pnpm: "^11.0.0"` warns when installing with pnpm 10 or older.
+Upgrade with `npm i -g pnpm@11`, or pin your project via `packageManager` and let pnpm switch itself.
+The framework's *runtime* does not depend on pnpm; this concerns the install step only.
+
+### `EBADDEVENGINES` from npm or npx
+
+Something added a `devEngines.packageManager` block. npm and npx abort on it, and corepack rejects
+ranges inside it. Use `packageManager` (exact pin) plus `engines.pnpm` (soft range) instead — the
+contract test asserts `devEngines.packageManager` stays absent.
+
+---
+
+## Affected Files
+
+No core module changed in this release, so there is no module documentation to revisit. For
+completeness, the full change surface:
+
+| File | Change |
+|------|--------|
+| `package.json` | `packageManager` restored (exact pin + `sha512`); version → 11.29.1 |
+| `Dockerfile` | `corepack enable` removed; derive-line added to the `deps` and `builder` stages |
+| `.github/workflows/build.yml`, `publish.yml` | `with: version: 11` removed from `pnpm/action-setup` |
+| `tests/unit/pnpm-pin-contract.spec.ts` | **New** — 11 structural assertions + 1 CI-gated provisioning proof |
+| `spectaql.yml`, `FRAMEWORK-API.md` | Version bump only (kept in sync per the release process) |
+| `.claude/rules/package-management.md` | Documents the corepack-free pin contract |
+
+---
+
+## References
+
+- [Package Management Rules — fixed versions, overrides, the pnpm pin contract](../.claude/rules/package-management.md)
+- [Versioning Strategy — release process, `package.json` / `spectaql.yml` version sync](../.claude/rules/versioning.md)
+- Contract test: `tests/unit/pnpm-pin-contract.spec.ts`
+- [Migration Guide 11.28.1 → 11.29.0](./11.28.1-to-11.29.0.md) — previous release (introduced the `engines.pnpm` gate this guide keeps)
+- [Migration Guide 11.27.6 → 11.27.7](./11.27.6-to-11.27.7.md) — the pnpm 11 move, when corepack was still the mechanism
+- [nest-server-starter](https://github.com/lenneTech/nest-server-starter) (reference implementation)
+</content>
+</invoke>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nest-server",
-  "version": "11.28.1",
+  "version": "11.29.1",
   "description": "Modern, fast, powerful Node.js web framework in TypeScript based on Nest with a GraphQL API and a connection to MongoDB (or other databases).",
   "keywords": [
     "node",
@@ -23,9 +23,10 @@
     "build:dev": "pnpm run build",
     "c": "pnpm run check",
     "check": "node scripts/check.mjs",
-    "check:raw": "pnpm audit && pnpm run format:check && pnpm run lint && pnpm run check:swc-tdz && pnpm test && pnpm run build && bash scripts/check-server-start.sh",
-    "check:fix": "pnpm install && pnpm audit --fix && pnpm run format && pnpm run lint:fix && pnpm run check:swc-tdz && pnpm test && pnpm run build && bash scripts/check-server-start.sh",
-    "check:naf": "pnpm install && pnpm run format && pnpm run lint:fix && pnpm run check:swc-tdz && pnpm test && pnpm run build && bash scripts/check-server-start.sh",
+    "check:raw": "pnpm install --frozen-lockfile && pnpm audit && pnpm run format:check && pnpm run lint && pnpm run check:swc-tdz && pnpm test && pnpm run build && pnpm run check:manifest && bash scripts/check-server-start.sh",
+    "check:fix": "pnpm install && pnpm audit --fix && pnpm run format && pnpm run lint:fix && pnpm run check:swc-tdz && pnpm test && pnpm run build && pnpm run check:manifest && bash scripts/check-server-start.sh",
+    "check:naf": "pnpm install && pnpm run format && pnpm run lint:fix && pnpm run check:swc-tdz && pnpm test && pnpm run build && pnpm run check:manifest && bash scripts/check-server-start.sh",
+    "check:manifest": "node scripts/check-package-manifest.mjs",
     "check:swc-tdz": "nest build -b swc -p tsconfig.swc-tdz.json && node scripts/check-swc-tdz.mjs",
     "cf": "pnpm run check:fix",
     "cnaf": "pnpm run check:naf",
@@ -75,8 +76,10 @@
     "url": "https://github.com/lenneTech/nest-server/issues"
   },
   "engines": {
-    "node": ">= 22"
+    "node": ">= 22",
+    "pnpm": "^11.0.0"
   },
+  "packageManager": "pnpm@11.13.1+sha512.b2fc7683b8a6525414e7d13e1ba28caaddde96bf66ec540bfaeb7e702b81f3e0be4d1f295edf7f9fe0396740a8dce4509c582ddf79891f4543fea32d37645f25",
   "dependencies": {
     "@apollo/server": "5.5.1",
     "@as-integrations/express5": "1.1.2",
@@ -187,6 +190,5 @@
   ],
   "watch": {
     "build:dev": "src"
-  },
-  "packageManager": "pnpm@11.13.0"
+  }
 }

package/src/core/common/interfaces/server-options.interface.ts

@@ -727,6 +727,18 @@ export interface IBetterAuthUserField {
    */
   fieldName?: string;
 
+  /**
+   * Whether a client may supply this field's value via Better-Auth's native input parsing
+   * (sign-up create / update-user).
+   *
+   * When `false`, Better-Auth rejects client-supplied values: it throws `FIELD_NOT_ALLOWED`
+   * on the update-user route and silently substitutes the server-side default on sign-up.
+   * Use this to mark server-managed fields that must never be set from client input.
+   *
+   * @default true (Better-Auth default when omitted)
+   */
+  input?: boolean;
+
   /**
    * Whether this field is required
    */

package/src/core/modules/better-auth/README.md

@@ -641,6 +641,8 @@ const config = {
       department: { type: 'string', required: true },
       preferences: { type: 'string', defaultValue: '{}' },
       isActive: { type: 'boolean', defaultValue: true },
+      // Server-managed field: reject any client-supplied value (sign-up / update-user)
+      internalScore: { type: 'number', defaultValue: 0, input: false },
     },
   },
 };
@@ -648,6 +650,26 @@ const config = {
 
 **Available field types:** `'string'`, `'number'`, `'boolean'`, `'date'`, `'json'`, `'string[]'`, `'number[]'`
 
+**Field options:**
+
+| Option         | Type       | Default                      | Description                                                                                                                                                                                                                                                     |
+| -------------- | ---------- | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `type`         | field type | —                            | Required. One of the field types above.                                                                                                                                                                                                                         |
+| `defaultValue` | any        | —                            | Value used when the client does not (or may not) supply one.                                                                                                                                                                                                    |
+| `required`     | boolean    | `false`                      | Whether the field is required.                                                                                                                                                                                                                                  |
+| `input`        | boolean    | `true` (Better-Auth default) | When `false`, Better-Auth rejects client-supplied values: it throws `FIELD_NOT_ALLOWED` (HTTP 400) on `POST /iam/update-user` and substitutes the server default on sign-up. Use it to mark **server-managed** fields that must never be set from client input. |
+
+> **⚠️ Security — server-managed core fields are hard-locked.** The core fields `roles`, `verified`,
+> `verifiedAt`, `twoFactorEnabled` and `iamId` are registered with `input: false` and **re-asserted
+> after** your `additionalUserFields` are merged, so a project override **cannot** re-open them for
+> client input. This closes a vertical privilege-escalation path (a client can no longer self-grant
+> `roles: ['admin']`, self-verify, or toggle 2FA via `POST /iam/update-user`). The lock also applies
+> to any shadow field whose `fieldName` maps to one of those columns. `roles`/`verified` etc. are
+> still assigned server-side through nest-server's own service layer (`UserService.setRoles`,
+> `CrudService.update` with `checkRoles`) — that path does not use Better-Auth input parsing and is
+> unaffected. (`termsAndPrivacyAcceptedAt` is `input: false` by default but is intentionally NOT
+> hard-locked — it is a consent timestamp, not a privilege boundary, so a project may re-open it.)
+
 ### Module Integration (Recommended Pattern)
 
 By default (`autoRegister: false`), projects integrate BetterAuth via an **extended module** in their project. This follows the same pattern as Legacy Auth and allows for custom resolvers, controllers, and project-specific authentication logic.