@lenne.tech/nest-server 11.27.6 → 11.28.0

package/docs/REQUEST-LIFECYCLE.md

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

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

@@ -0,0 +1,374 @@
+# Migration Guide: 11.27.6 → 11.27.7
+
+## Overview
+
+| Category | Details |
+|----------|---------|
+| **Breaking Changes** | None |
+| **New Features** | None. Four new leaf modules (`core-better-auth.constants.ts`, `core-better-auth.registry.ts`, `id.helper.ts`, `clone.helper.ts`) — the tokens and helpers they hold were already public and stay reachable from their old locations. The registry is module-internal and deliberately **not** exported. |
+| **Public API** | Unchanged. Verified by diffing the full export surface of `src/index.ts` on both versions: **nothing removed, nothing renamed**. |
+| **Bugfixes** | **(1)** Applications compiled with **SWC** (`nest start -b swc`, `nest build -b swc`) no longer crash at startup with `ReferenceError: Cannot access 'BETTER_AUTH_INSTANCE' before initialization` when BetterAuth is enabled. **(2)** A direct import of `core/common/inputs/combined-filter.input` no longer crashes under SWC with `ReferenceError: Cannot access 'CombinedFilterInput' before initialization`. **(3)** A consumer setting `betterAuth.options.advanced.defaultCookieAttributes` no longer silently strips the `Secure` flag from session cookies on an `https://` deployment. |
+| **Security** | See bugfix (3). If your project sets `advanced.defaultCookieAttributes` for any reason (cookie partitioning, a custom domain) **and** runs on an `https://` baseURL, your session cookies were being sent without `Secure`. Updating fixes this with no action required. |
+| **Deprecations** | The BetterAuth DI tokens re-exported from `core-better-auth.module` / `core-better-auth.service` are now marked deprecated in their docblocks. Import them from `core-better-auth.constants` (or the package root) instead. Both paths keep working. |
+| **Toolchain** | The framework repo moved to **pnpm 11** (see the note below). **npm consumers are unaffected** — you do not inherit the framework's `packageManager` or `pnpm-workspace.yaml`. Relevant only if you contribute to the framework or mirror its toolchain. |
+| **Migration Effort** | **npm mode:** 0 minutes (automatic) — `pnpm update` is enough. **Vendor mode:** see the note below — the BetterAuth change is an atomic file set. |
+
+This is a **startup-crash + cookie-security bugfix release**. No source-code or
+config changes are required in consuming projects.
+
+---
+
+## Toolchain: pnpm 11 (framework contributors only)
+
+**npm consumers of `@lenne.tech/nest-server` can ignore this section** — installing the
+package does not import our package manager or its config.
+
+The framework repo itself upgraded from pnpm 10 to **pnpm 11**, for one concrete reason:
+**`pnpm audit` is broken on every pnpm 10.x** — npm retired the legacy audit endpoint
+(HTTP 410) and only pnpm 11 uses the working bulk-advisory endpoint. The upgrade also
+required migrating pnpm's config, because pnpm 11 has breaking changes:
+
+- **The `pnpm` field in `package.json` is gone.** All pnpm settings moved to
+  `pnpm-workspace.yaml`: `overrides`, `allowBuilds`, `nodeLinker`, `autoInstallPeers`,
+  `strictPeerDependencies`, `peerDependencyRules`. `.npmrc` is now auth/registry only.
+- **`allowBuilds` replaced `onlyBuiltDependencies`** — a map that must classify *every*
+  package with an install script as `true` (build it, e.g. `bcrypt`) or `false` (don't,
+  e.g. the `@scarf/scarf` telemetry). An unclassified build-script package makes
+  `pnpm install` exit non-zero.
+- **Security overrides pruned 36 → 9.** Only entries still load-bearing (removing them
+  lets the package resolve back into its vulnerable range) were kept; `pnpm audit` on
+  pnpm 11 confirms the pruned set is still clean.
+
+CI (`pnpm/action-setup`) and Docker (`corepack`) follow the `packageManager` field, so no
+workflow or Dockerfile edits were needed — they use pnpm 11 automatically.
+
+**If you develop against or vendor the framework's toolchain:** switch to pnpm 11
+(`corepack use pnpm@11` or let corepack follow `packageManager`), and move any
+`package.json#pnpm` settings you have into `pnpm-workspace.yaml`. See
+`.claude/rules/package-management.md` for the full pattern.
+
+---
+
+## Quick Migration
+
+No code changes required.
+
+```bash
+# Update package
+pnpm add @lenne.tech/nest-server@11.27.7
+
+# Verify build
+pnpm run build
+
+# Run tests
+pnpm test
+```
+
+---
+
+## What's Fixed in 11.27.7
+
+### Startup crash under the SWC compiler
+
+**The symptom.** With BetterAuth enabled and the app started or built via SWC:
+
+```
+ReferenceError: Cannot access 'BETTER_AUTH_INSTANCE' before initialization
+    at core-better-auth.module.ts
+    at core-better-auth.service.ts
+```
+
+This affected anyone using `nest start -b swc` / `nest build -b swc` — including
+the `start:dev:swc` and `start:local:swc` scripts shipped in the starter. Projects
+building with the default `tsc` builder were **not** affected.
+
+**The bug.** The three BetterAuth dependency-injection tokens were split across two
+files that imported each other:
+
+- `BETTER_AUTH_INSTANCE` was declared in `core-better-auth.module.ts`
+- `BETTER_AUTH_CONFIG` and `BETTER_AUTH_COOKIE_DOMAIN` were declared in `core-better-auth.service.ts`
+
+The service imported the first token from the module, and the module imported the
+other two — plus the service class itself — back from the service. A genuine import
+cycle.
+
+The cycle alone would have been survivable. What made it fatal is *when* the token
+is read: `@Inject(BETTER_AUTH_INSTANCE)` is a **constructor-parameter decorator**,
+and decorator arguments are evaluated when the class is *defined* — that is, while
+the module is still initializing. On a cycle, the importing side reads a `const`
+that is still in its temporal dead zone.
+
+Under `tsc`/CommonJS the evaluation order happened to work out. Under SWC it did
+not, and the app died at startup.
+
+**The fix.** All three tokens moved into a new **import-free leaf module**,
+`core-better-auth.constants.ts`. A file with zero imports can never be
+mid-evaluation when someone imports it — in any module system, under any compiler —
+so the initialization order is now deterministic everywhere.
+
+A second leaf, `core-better-auth.registry.ts`, does the same for the
+`BetterAuthTokenService` reference that `BetterAuthRolesGuard` looks up statically,
+removing the last import cycle inside the module. As a side effect this also fixes a
+test-isolation leak: `CoreBetterAuthModule.reset()` previously did not clear that
+reference, so a token service could survive into the next testing module.
+
+---
+
+## Deprecations
+
+The tokens are still re-exported from their old locations, so **every existing import
+keeps working**:
+
+```typescript
+// Still works (now @deprecated)
+import { BETTER_AUTH_INSTANCE } from '@lenne.tech/nest-server/dist/core/modules/better-auth/core-better-auth.module';
+import { BETTER_AUTH_CONFIG } from '@lenne.tech/nest-server/dist/core/modules/better-auth/core-better-auth.service';
+
+// Preferred
+import { BETTER_AUTH_CONFIG, BETTER_AUTH_INSTANCE } from '@lenne.tech/nest-server';
+```
+
+Importing from the package root (`@lenne.tech/nest-server`) was already the
+recommended path and is unaffected — **most projects need to change nothing.**
+
+The deprecated re-exports will be removed in a future MINOR.
+
+> **The token string values are unchanged** (`'BETTER_AUTH_INSTANCE'`,
+> `'BETTER_AUTH_CONFIG'`, `'BETTER_AUTH_COOKIE_DOMAIN'`), so `@Inject('BETTER_AUTH_INSTANCE')`
+> written as a string literal keeps resolving. A new unit test pins these values
+> precisely because they are part of the public contract.
+
+---
+
+## Vendor Mode: five atomic file sets
+
+Projects that vendor the framework core (`projects/api/src/core/`) sync via the
+`/lt-dev:backend:update-nest-server-core` agent rather than `pnpm update`.
+
+Every change in this release works the same way: a symbol moved into a new **leaf**
+file, and its old home now re-exports it. That makes each one an **atomic set** —
+adopt the edits without the new file and you get an unresolvable import and a broken
+build.
+
+**Seven files are new.** If a sync is interrupted, verify all seven exist before
+building:
+
+```
+core/modules/better-auth/core-better-auth.constants.ts
+core/modules/better-auth/core-better-auth.registry.ts
+core/modules/ai/core-ai.constants.ts
+core/modules/ai/interfaces/ai-interaction-record.interface.ts
+core/modules/tus/tus.constants.ts
+core/common/helpers/id.helper.ts
+core/common/helpers/clone.helper.ts
+```
+
+> **Expect merge conflicts on locally-patched files.** If your project has local edits
+> in `db.helper.ts`, `input.helper.ts`, `filter.input.ts`, `restricted.decorator.ts`
+> or any `ai/services/*.service.ts`, this release moves code *out* of them — the sync
+> will conflict there. The resolution is always the same: keep your local logic, keep
+> the new `import` + `export … from` lines pointing at the leaf, and do not restore the
+> declarations that moved out.
+
+**Set 1 — BetterAuth DI tokens**
+
+| File | Change |
+|------|--------|
+| `core/modules/better-auth/core-better-auth.constants.ts` | 🆕 the token leaf |
+| `core/modules/better-auth/core-better-auth.registry.ts` | 🆕 the token-service leaf |
+| `core/modules/better-auth/core-better-auth.module.ts` | takes tokens from the constants leaf; delegates the token-service lookup to the registry |
+| `core/modules/better-auth/core-better-auth.service.ts` | takes tokens from the constants leaf |
+| `core/modules/better-auth/better-auth-roles.guard.ts` | reads the registry instead of importing the module |
+| `core/modules/better-auth/index.ts` | exports the constants leaf (the registry is deliberately **not** exported — it is module-internal) |
+
+**Set 2 — core helpers** (this is what takes `restricted.decorator` off its cycles)
+
+| File | Change |
+|------|--------|
+| `core/common/helpers/id.helper.ts` | 🆕 the ID cluster (`equalIds`, `getIncludedIds`, `getStringIds`, `getObjectIds`) |
+| `core/common/helpers/clone.helper.ts` | 🆕 `clone`, `deepFreeze` |
+| `core/common/helpers/db.helper.ts` | ID cluster removed; **re-exports it** from `id.helper` |
+| `core/common/helpers/input.helper.ts` | `clone`/`deepFreeze` removed; **re-exports them** from `clone.helper`; takes `equalIds` from `id.helper` |
+| `core/common/services/config.service.ts` | takes `clone`/`deepFreeze` from `clone.helper` |
+| `core/common/decorators/restricted.decorator.ts` | takes the ID helpers from `id.helper`; its three exports become hoisted `function` declarations |
+
+**Set 3 — filter inputs**
+
+| File | Change |
+|------|--------|
+| `core/common/inputs/filter.input.ts` | now declares **both** `CombinedFilterInput` (first) and `FilterInput` — the order is load-bearing |
+| `core/common/inputs/combined-filter.input.ts` | reduced to a re-export shim |
+
+**Set 4 — AI module** (22 DI tokens + the type that closed the last AI cycle)
+
+| File | Change |
+|------|--------|
+| `core/modules/ai/core-ai.constants.ts` | 🆕 all 22 `AI_*_MODEL` / `AI_*_CLASS` tokens |
+| `core/modules/ai/interfaces/ai-interaction-record.interface.ts` | 🆕 `AiInteractionRecord` |
+| `core/modules/ai/services/*.service.ts` (11 files) | tokens removed; each **re-exports its own** from the constants leaf |
+| `core/modules/ai/services/core-ai.service.ts` | `AiInteractionRecord` removed; **re-exports it** from the interface leaf |
+| `core/modules/ai/services/core-ai-interaction.service.ts` | takes the type from the interface leaf — no longer imports `core-ai.service` at all |
+| `core/modules/ai/index.ts` | exports the interface leaf |
+
+> If your project registered custom AI models via these tokens, nothing changes —
+> the values are unchanged and every old import path still resolves.
+
+**Set 5 — TUS module**
+
+| File | Change |
+|------|--------|
+| `core/modules/tus/tus.constants.ts` | 🆕 `TUS_CONFIG` |
+| `core/modules/tus/tus.module.ts` | token removed; **re-exports it** from the leaf |
+
+---
+
+> ### Do not "clean up" the re-export lines
+>
+> `db.helper.ts`, `input.helper.ts`, `combined-filter.input.ts`, `core-better-auth.module.ts`,
+> `core-better-auth.service.ts`, `tus.module.ts`, `core-ai.service.ts` and all eleven
+> `ai/services/*.service.ts` files now carry `export { … } from './…'` lines that look
+> exactly like dead code.
+>
+> They are not. They are the *entire* backward-compatibility layer: this package has no
+> `exports` map, so consumers deep-import these files directly, and deleting one line
+> breaks every one of them — **with nothing turning red**, because the symbol is still
+> exported from the package root.
+>
+> The framework pins them with a test (`tests/unit/import-cycle-invariants.spec.ts`) for
+> exactly this reason. Keep the equivalent lines in your vendored copy.
+
+---
+
+## Also fixed: `CombinedFilterInput` crashed on a direct import
+
+Same bug class, different module. `FilterInput` and `CombinedFilterInput` lived in
+two files that imported each other, and `FilterInput` referenced
+`CombinedFilterInput` **eagerly** — in a decorator argument and in the `design:type`
+metadata `emitDecoratorMetadata` emits. Under SWC:
+
+```
+require('.../core/common/inputs/combined-filter.input.js')
+→ ReferenceError: Cannot access 'CombinedFilterInput' before initialization
+```
+
+This only stayed hidden because importing from the package root pulls `filter.input`
+in first. A **deep import** of `combined-filter.input` — plausible in vendor mode or
+in a unit test — hit the crash.
+
+Both classes now live in `filter.input.ts` (declaration order matters), and
+`combined-filter.input.ts` re-exports `CombinedFilterInput`. **Every existing import
+path still resolves**, including deep imports of either file.
+
+---
+
+## Also fixed (security): `Secure` could be stripped from session cookies
+
+If a project sets `betterAuth.options.advanced.defaultCookieAttributes` — for cookie
+partitioning, a custom domain, anything — that object **wholesale-replaced** the
+framework's own `{ secure: true }`, because the merge was shallow. On an `https://`
+baseURL the result was session cookies without the `Secure` attribute, forwarded
+verbatim by BetterAuth's native handlers (2FA verify, social callback, magic link).
+No error, no warning.
+
+```ts
+// Before 11.27.7 — on an https baseURL:
+betterAuth: { options: { advanced: { defaultCookieAttributes: { partitioned: true } } } }
+// → Set-Cookie: iam.session_token=…; HttpOnly; SameSite=Lax        ← Secure GONE
+```
+
+The merge is now deep for that one key: `secure: true` is the base and your keys
+spread over it. An **explicit** `{ secure: false }` still wins — this guards against
+silent clobbering, not against a deliberate choice.
+
+**No action required.** If you set `defaultCookieAttributes` and run on HTTPS, the
+fix applies automatically on update.
+
+---
+
+## New: SWC regression guard
+
+The bug had the worst possible failure profile — **it passed a fully green CI and
+crashed only for consumers.** `nest build` uses `tsc`, and vitest runs SWC through
+Vite's module runner, whose getter-based live bindings tolerate import cycles. So
+neither the build nor 2000+ tests could see it.
+
+A new check step closes that hole:
+
+```bash
+pnpm run check:swc-tdz
+# = nest build -b swc -p tsconfig.swc-tdz.json && node scripts/check-swc-tdz.mjs
+```
+
+It compiles with SWC to CommonJS and loads **every compiled module as its own entry
+point** under Node's CJS loader — the exact path that fails.
+
+Loading only the package barrel is *not* sufficient, and that is not a theoretical
+point: whether such a cycle throws depends on which module the graph is entered
+through. The `CombinedFilterInput` crash above was invisible to a barrel-only load,
+because the barrel happens to pull `filter.input` in first. Requiring each file
+separately is what surfaces it.
+
+It builds into its own throwaway directory (`dist-swc-tdz/`, removed on success,
+kept on failure so you can inspect the emit), so it never touches your real `dist/`.
+It is wired into `check:raw` — ahead of the test step, so a cycle fails in seconds
+rather than after the full suite — and into the CI workflow.
+
+### Copying it into your own project
+
+**Worth doing if you build or run with SWC** (`nest start -b swc`, `start:dev:swc`):
+it costs a few seconds, needs no database, and is the only thing that catches this
+bug class.
+
+Note that `scripts/` is **not** part of the published npm package, so you cannot
+copy it out of `node_modules`. Take the three pieces from the repository:
+
+- [`scripts/check-swc-tdz.mjs`](https://github.com/lenneTech/nest-server/blob/develop/scripts/check-swc-tdz.mjs)
+- [`tsconfig.swc-tdz.json`](https://github.com/lenneTech/nest-server/blob/develop/tsconfig.swc-tdz.json)
+- the `check:swc-tdz` script entry in `package.json`, plus `dist-swc-tdz` in `.gitignore`
+
+Then add `pnpm run check:swc-tdz` to your own `check` chain (before the tests, so it
+fails fast) and to CI.
+
+> **Vendor-mode projects should treat this as required, not optional.** You copy
+> `src/core/` into your own tree, where a local edit can re-introduce exactly this
+> kind of cycle — and your `tsc` build and your test suite will both stay green while
+> it does.
+
+---
+
+## Compatibility Notes
+
+| Pattern | Status |
+|---------|--------|
+| Importing tokens from `@lenne.tech/nest-server` (package root) | ✅ Unchanged |
+| Deep-importing tokens from `core-better-auth.module` / `.service` | ✅ Works, now `@deprecated` |
+| `@Inject('BETTER_AUTH_INSTANCE')` as a string literal | ✅ Unchanged (values pinned by test) |
+| Custom `{ provide: BETTER_AUTH_INSTANCE, useValue: ... }` overrides | ✅ Unchanged |
+| Extending `BetterAuthRolesGuard` | ✅ Unchanged public behavior |
+| `CoreBetterAuthModule.getTokenServiceInstance()` | ✅ Unchanged (now delegates to the registry) |
+| Building with `tsc` (default) | ✅ Was never affected |
+| Building with SWC | ✅ **Fixed** |
+
+---
+
+## Troubleshooting
+
+**`ReferenceError: Cannot access 'BETTER_AUTH_INSTANCE' before initialization`**
+You are still on ≤ 11.27.6 with an SWC build. Update to 11.27.7.
+
+**Vendor mode: `Cannot find module './core-better-auth.constants'`**
+The sync did not create the new leaf file(s). Re-run the core update and confirm
+both `core-better-auth.constants.ts` and `core-better-auth.registry.ts` exist in
+`src/core/modules/better-auth/`.
+
+**Deprecation warnings on the token imports**
+Expected. Switch the import to the package root (`@lenne.tech/nest-server`) or to
+`core-better-auth.constants`. No behavior change either way.
+
+---
+
+## Module Documentation
+
+- [BetterAuth README](../src/core/modules/better-auth/README.md)
+- [BetterAuth Integration Checklist](../src/core/modules/better-auth/INTEGRATION-CHECKLIST.md)
+- [BetterAuth Customization](../src/core/modules/better-auth/CUSTOMIZATION.md)