@lenne.tech/nest-server 11.41.8 → 11.42.0

package/docs/REQUEST-LIFECYCLE.md

@@ -107,10 +107,10 @@ JWT-based authentication for existing projects:
 | **Response Filter Interceptor** | Enforces `@Restricted()` field-level access |
 | **Translation Interceptor** | Applies `_translations` based on `Accept-Language` |
 | **Secret Fields Removal** | Configurable fallback removal of password, tokens, etc. |
-| **RequestContext** | `AsyncLocalStorage`-based context for current user in Mongoose hooks |
+| **RequestContext** | `AsyncLocalStorage`-based context for current user in Mongoose hooks. `fromRequest` (11.42.0) marks a context created for a CLIENT operation (HTTP middleware, GraphQL WebSocket), so service-level checks such as `assertTenantRole()` tell an anonymous request apart from system work |
 | **Query Complexity** | GraphQL query complexity analysis to prevent DoS |
 | **Tenant Isolation** | Header-based multi-tenant isolation with membership validation (opt-in) |
-| **Tenant Guard** | `CoreTenantGuard` validates tenant membership; system roles (`S_EVERYONE`, `S_USER`, `S_VERIFIED`) are checked as OR alternatives before real roles; hierarchy roles (`@Roles(DefaultHR.MEMBER)`), `@SkipTenantCheck()`, BetterAuth auto-skip (`betterAuth.skipTenantCheck`) |
+| **Tenant Guard** | `CoreTenantGuard` validates tenant membership — and, with `multiTenancy.isTenantActive` (11.42.0), that the tenant is not deactivated; system roles (`S_EVERYONE`, `S_USER`, `S_VERIFIED`) are checked as OR alternatives before real roles; hierarchy roles (`@Roles(DefaultHR.MEMBER)`), `@SkipTenantCheck()`, BetterAuth auto-skip (`betterAuth.skipTenantCheck`) |
 | **Tenant Plugin Safety Net** | Mongoose tenant plugin throws `ForbiddenException` when tenant-schema is accessed without valid tenant context |
 | **API Tokens** | `apiTokens` config (opt-in): USER tokens act as their user without global roles; TENANT tokens (multi-tenancy only) act with the lowest tenant role in their own tenant. `CoreApiTokenMiddleware` authenticates `Authorization: Bearer` / `x-api-key`; every guard denies a token unless the route declares `@ApiTokenScopes()`. Signed short-lived assertions for embedded pages. See `src/core/modules/api-token/README.md` |
 
@@ -165,7 +165,7 @@ JWT-based authentication for existing projects:
 | **REST Endpoints** | `GET /files/id/:id`, `GET /files/:filename` (core, gated by `file.downloadRoles`, default ADMIN); `POST /files/upload`, `DELETE /files/:id` (project-specific) |
 | **GraphQL Endpoints** | `getFileInfo` (`file.downloadRoles`), `uploadFile` / `uploadFiles` (`file.uploadRoles`), `deleteFile` (`file.deleteRoles`) — all default ADMIN |
 | **File access control** | Roles are the coarse filter; per-file rules go in `CoreFileService.checkRights()` using metadata written at upload time. Cover BOTH the `id` and the `filename` branch — the filename route authorizes on the by-name lookup alone when presigned S3 downloads are on, and `deleteFileByName()` always does. Working reference: `src/server/modules/file/file.service.ts` (with `file.downloadRoles: [S_USER]` in `src/config.env.ts`, so the rule is actually reached). Both file classes carry `@SkipTenantCheck()` — GridFS is not tenant-scoped |
-| **TUS Module** | Resumable uploads via tus.io protocol (creation, termination, expiration), gated by `tus.roles` (default `S_USER`); `OPTIONS` stays public for the CORS preflight |
+| **TUS Module** | Resumable uploads via tus.io protocol (creation, termination, expiration), gated by `tus.roles` (default `S_USER`); `OPTIONS` stays public for the CORS preflight. Records owner and, with `multiTenancy` only, the validated tenant at upload creation; a custom service plugs in via `TusModule.forRoot({ service })` |
 | **GridFS Migration** | Completed TUS uploads auto-migrate to GridFS |
 | **CORS Support** | Automatic CORS headers for browser uploads |
 
@@ -373,6 +373,8 @@ The following diagram shows the exact order of execution from HTTP request to re
   |     - Non-admin + header + no membership = always 403   |
   |     - Checks configurable roleHierarchy levels          |
   |     - Admin bypass: sets isAdminBypass (sees all data)  |
+  |     - multiTenancy.isTenantActive (11.42.0): deactivated |
+  |       tenant = 403 / dropped from tenantIds (not admin) |
   |     - Sets tenantId in RequestContext                    |
   |     - @SkipTenantCheck() opts out of tenant validation  |
   |     - BetterAuth auto-skip: IAM handlers skip tenant    |

package/migration-guides/11.41.8-to-11.41.9.md

@@ -0,0 +1,116 @@
+# Migration Guide: 11.41.8 → 11.41.9
+
+## Overview
+
+| Category              | Details                                                                                                                                                                  |
+| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **New Features**      | A custom TUS service via `TusModule.forRoot({ service })`, and an overridable `onUploadCreate()` (§1)                                                                    |
+| **Behaviour Changes** | Only with `multiTenancy` configured: TUS uploads record the validated tenant, and a tenant header naming a tenant the caller does not belong to is refused with 403 (§2) |
+| **Breaking Changes**  | None for projects without `multiTenancy`                                                                                                                                 |
+| **Migration Effort**  | None — `pnpm update`. Projects that want upload rules (quota, validation) adopt §1                                                                                       |
+
+## Quick Migration
+
+```bash
+pnpm update @lenne.tech/nest-server
+pnpm run build && pnpm test
+```
+
+Vendor-mode projects pick up the core update; nothing else to change.
+
+## What's New in 11.41.9
+
+### 1. A custom TUS service, and a hook before the first byte
+
+Until now `TusModule` constructed `CoreTusService` directly in both of its provider factories, so a
+project could not plug in a subclass at all — and `onUploadCreate` sat inline inside a private method,
+so even a subclass could not have changed it. Both are open now:
+
+```typescript
+import { CoreTusService } from '@lenne.tech/nest-server';
+import { Upload } from '@tus/server';
+
+export class TusService extends CoreTusService {
+  protected override async onUploadCreate(req: any, upload: Upload) {
+    const quota = this.options?.moduleRef?.get(QuotaService, { strict: false });
+    if (!(await quota?.hasRoomFor(req, upload.size))) {
+      const error = new Error('Storage quota exceeded');
+      (error as any).status_code = 413;
+      throw error;
+    }
+    return super.onUploadCreate(req, upload);
+  }
+}
+
+// server.module.ts
+TusModule.forRoot({ controller: TusController, service: TusService });
+```
+
+`onUploadCreate(req, upload)` runs once per upload, after the client declared `Upload-Length` and
+before anything is stored — the one point at which a quota can refuse an upload without the store
+having grown first.
+
+Three rules, all in the TUS [INTEGRATION-CHECKLIST](../src/core/modules/tus/INTEGRATION-CHECKLIST.md)
+Step 2:
+
+- **Keep the constructor signature `(connection, options?)`.** The module constructs the service
+  itself, with exactly those arguments. Project providers are reached at call time through
+  `this.options?.moduleRef`, which the module now passes in.
+- **Return `super.onUploadCreate()`.** It records the owner and the tenant and enforces
+  `allowedTypes`; skipping it produces owner-less uploads and accepts every file type.
+- **Throw an `Error` with `status_code`** to refuse — that is how `@tus/server` turns it into a
+  response.
+
+### 2. With multi-tenancy: TUS uploads carry their tenant
+
+**Projects without `multiTenancy` see no change** — no header is read, no field is written.
+
+With `multiTenancy` configured (and not `enabled: false`), TUS uploads used to carry no tenant at
+all: the routes carry `@SkipTenantCheck()`, the file stores sit outside Mongoose, and so every
+TUS-uploaded file bypassed tenant filtering and any per-tenant storage accounting. Now an upload that
+sends the tenant header is validated against the caller's active memberships — the same check
+GraphQL subscriptions use — and the finished file gets `metadata.tenantId`:
+
+| Request                                              | 11.41.8               | 11.41.9                 |
+| ---------------------------------------------------- | --------------------- | ----------------------- |
+| No tenant header                                     | tenant-less           | tenant-less (unchanged) |
+| Header naming a tenant the caller belongs to         | tenant-less           | `metadata.tenantId` set |
+| Header naming a tenant the caller does NOT belong to | accepted, tenant-less | **403**, nothing stored |
+
+**Send the header from the TUS client.** A tenant header added by an interceptor of the project's
+generated API client does not reach `tus-js-client`. Without it the upload silently stays tenant-less,
+outside tenant filtering and per-tenant quotas. Pass it explicitly, e.g.
+`useLtTusUpload({ headers: { 'X-Tenant-Id': currentTenantId } })`.
+
+The tenant is recorded under the framework-owned metadata key `TUS_TENANT_METADATA_KEY`
+(`ltTenantId`), next to the owner key. Like the owner key it is always overwritten, so a client
+cannot put a tenant into its own `Upload-Metadata`.
+
+**What this changes downstream:** the file module's `'tenant'` access preset and any
+`checkRights()` rule reading `metadata.tenantId` now see the tenant on TUS-uploaded files. Under the
+`'tenant'` preset such files used to be refused for every non-admin (no tenant on the file); new
+uploads are now readable within their tenant. Files uploaded before 11.41.9 keep no tenant.
+
+## Compatibility Notes
+
+| Pattern                                                               | Status                                                            |
+| --------------------------------------------------------------------- | ----------------------------------------------------------------- |
+| `TusModule.forRoot()` / `forRoot({ controller })`                     | Unchanged                                                         |
+| Project without `multiTenancy`                                        | Unchanged — nothing read, nothing written (§2)                    |
+| Multi-tenant client sending a tenant header it is a member of         | Works; files now carry `tenantId` (§2)                            |
+| Multi-tenant client sending a header for a foreign tenant             | Now 403 (§2)                                                      |
+| Own `TusModule` replacement that provides a `CoreTusService` subclass | Keeps working; `forRoot({ service })` is now the simpler way (§1) |
+
+## Troubleshooting
+
+| Symptom                                              | Cause                                                                  | Fix                                               |
+| ---------------------------------------------------- | ---------------------------------------------------------------------- | ------------------------------------------------- |
+| TUS `POST` answers 403 after the update              | The tenant header names a tenant the caller is not an active member of | Send the caller's own tenant, or no header (§2)   |
+| An `onUploadCreate` override never runs              | The subclass is not registered                                         | `TusModule.forRoot({ service: TusService })` (§1) |
+| Dependencies are `undefined` in the service subclass | Declared as constructor parameters                                     | Resolve via `this.options?.moduleRef` (§1)        |
+| Uploads have no `ownerId` after adding an override   | `onUploadCreate` override does not call `super`                        | `return super.onUploadCreate(req, upload)` (§1)   |
+
+## Module Documentation
+
+- [TUS README](../src/core/modules/tus/README.md) — Custom Service, Validate an Upload Before It Starts, Tenant Scoping
+- [TUS INTEGRATION-CHECKLIST](../src/core/modules/tus/INTEGRATION-CHECKLIST.md) — Step 2

package/migration-guides/11.41.x-to-11.42.x.md

@@ -0,0 +1,161 @@
+# Migration Guide: 11.41.x → 11.42.x
+
+## Why this is a MINOR
+
+Per `.claude/rules/versioning.md` the MAJOR mirrors NestJS, so **MINOR is where breaking changes
+live**. Two behaviour changes hit multi-tenant projects only: with `multiTenancy.adminBypass: false`
+a platform administrator can no longer set a tenant account's e-mail address or password (§4), and
+the AI tool registry resolves tool roles by the membership role of the request's tenant (§3). A call
+that used to succeed can now be refused, so this is `11.42.0` rather than a patch.
+
+**Projects without `multiTenancy` see no behaviour change.** Everything else in this release is
+opt-in.
+
+## Overview
+
+| Category                                    | Details                                                                                                    |
+| ------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| **New (opt-in)**                            | `outboundFetch()` and friends — an SSRF guard for URLs a user entered (§1)                                 |
+| **New (opt-in)**                            | `multiTenancy.isTenantActive` — a deactivated tenant stops working (§2)                                    |
+| **New**                                     | `assertTenantRole()` / `hasTenantRole()` — tenant roles enforced in services, on every entry point (§3)    |
+| **Behaviour change** (multi-tenancy)        | AI tool roles (chat and MCP) resolve like `@Roles()` in the tenant guard (§3)                              |
+| **Behaviour change** (`adminBypass: false`) | No credential changes of other accounts through `updateUser`; no ADMIN bypass in the AI tool registry (§4) |
+| **Dependency**                              | `undici` 7.30.0 is a runtime dependency (§1) — nothing to do                                               |
+| **Migration Effort**                        | None without multi-tenancy. With it: check §3 and §4; adopt §1–§3 where they apply                         |
+
+## Quick Migration
+
+```bash
+pnpm update @lenne.tech/nest-server
+pnpm run build && pnpm test
+```
+
+Vendor-mode projects pick up the core update; `undici` reaches them through `dependencies`.
+
+## What's New in 11.42.0
+
+### 1. SSRF guard for user-entered URLs
+
+When the server calls a URL a USER entered — a webhook, an export target, an ERP address — it calls it
+from inside its own network. Without a check, a user points it at the database, other containers or
+the cloud metadata service (`169.254.169.254`) and reads the answer back.
+
+```typescript
+import { outboundFetch, OutboundUrlBlockedError } from '@lenne.tech/nest-server';
+
+const response = await outboundFetch(webhook.url, { body, headers, method: 'POST' });
+// an ERP in the same network, freed explicitly:
+await outboundFetch(target.url, init, { allowedHosts: ['erp.internal:8443'] });
+```
+
+- **Only for user-entered URLs.** Configured targets (AI providers, SMTP, S3, Redis, Brevo) do not use
+  it; nothing is applied globally.
+- Checked twice: on the URL before sending (`OutboundUrlBlockedError`, readable) and on every
+  connection — the only place that sees a redirect's next hop and DNS rebinding. A refusal on a later
+  hop surfaces as undici's `TypeError: fetch failed` with the `OutboundUrlBlockedError` as `cause`.
+- Internal targets are allowed in `local`, `e2e` and `ci`, refused elsewhere — including the deployed `test` stage.
+  `security.allowPrivateOutboundTargets` (`NSC__SECURITY__ALLOW_PRIVATE_OUTBOUND_TARGETS=true|false`)
+  decides explicitly.
+- `assertOutboundUrlAllowed(url)` checks without sending; `createOutboundDispatcher()` returns the
+  guarded undici `Agent` for code that uses undici directly. `outboundFetch()` uses undici's own
+  `fetch`: Node 22's built-in `fetch` bundles a different undici major than the agent.
+
+### 2. Deactivated tenants stop working
+
+`CoreTenantGuard` validated the membership only, so a tenant a project switched off kept working for
+its members, its API tokens and every request without a tenant header. Tell the guard:
+
+```typescript
+// config.env.ts
+multiTenancy: {
+  isTenantActive: async (tenantId, { connection }) =>
+    (await connection.collection('tenants').findOne({ _id: new Types.ObjectId(tenantId) }))?.active !== false,
+}
+```
+
+Then call `tenantGuard.invalidateTenant(tenantId)` right after switching a tenant on or off (answers are
+cached for `cacheTtlMs`; the call broadcasts to every replica with Redis). Effects: 403 on header paths
+and for tenant tokens, no tenant context on public routes, the tenant dropped from the header-less
+tenant list, no tenant for a new WebSocket subscription (one already open keeps its tenant until the client reconnects — the same holds today for a removed membership). A platform administrator under `adminBypass` still gets in.
+Asked after the membership check, so a non-member learns nothing. A function cannot come through
+`NSC__*` — set it in `config.env.ts`.
+
+**If your project already has its own "tenant active" guard**, it can stay; the hook additionally
+covers the header-less tenant list, which such a guard usually misses.
+
+### 3. Tenant roles on every entry point — services, MCP and AI chat
+
+`@Roles()` protects a route. MCP tools, AI tools, queue processors and other services call a service
+directly and never pass it. Enforce a tenant role in the service:
+
+```typescript
+import { assertTenantRole, DefaultHR } from '@lenne.tech/nest-server';
+
+async updateSettings(input: SettingsInput, serviceOptions?: ServiceOptions) {
+  assertTenantRole(DefaultHR.OWNER, 'Only owners may change the settings');
+  // …
+}
+```
+
+Signed in without the role → 403; anonymous client request → 401; system work (cron, migration, seed —
+no client request) → passes. The last two are told apart by the new `RequestContext.fromRequest`,
+which `RequestContextMiddleware` and the GraphQL WebSocket context set. **If you build a
+`RequestContext` yourself for a client operation** (a custom transport), set `fromRequest: true`.
+
+**Behaviour change, multi-tenancy only:** the AI tool registry (chat and `/ai/mcp`) now resolves a
+tool's `roles` like the tenant guard resolves `@Roles()` — a global role against `user.roles`, a tenant
+role against the membership role in the request's tenant (by hierarchy), and no ADMIN bypass where
+`adminBypass: false`. Before, every role was compared with the global `user.roles`. If a tool lists a
+TENANT role and a user relied on holding that name globally, the tool now follows the membership
+instead. An AI client acts within the signed-in user's rights and tenant scope — never beyond.
+
+**MCP sessions follow the current user.** A session used to keep the user object from its `initialize`
+request for its whole life, so a role revoked mid-session kept working over MCP until the client
+reconnected. The controller now refreshes the session's user on every request, and
+`CoreAiMcpService.createServer()` receives a **getter** (`() => AiToolUser`) instead of the user object.
+A project that overrides `createServer(user)` must accept the getter (a plain object is still accepted
+when you call it yourself) and read it per request, not once.
+
+### 4. `adminBypass: false` holds for credentials
+
+With multi-tenancy and `adminBypass: false`, `PATCH /users/:id` / `updateUser` now refuse (403) a change
+of another account's e-mail address or password — whoever asks, including the account's creator
+(`S_CREATOR` may update, and the e-mail field is open to every updater). Changing the address and
+requesting a reset was a way to take over a tenant account that `adminBypass: false` exists to rule
+out.
+
+Unaffected: the account itself, profile fields, an unchanged address sent along, deletion, and
+system work without a current user (invitation, password reset). Administrator accounts are NOT
+exempt as targets — an administrator may write `roles`, so "promote to ADMIN, then change the address"
+would otherwise open every account in two requests. Support for a
+tenant user goes through the password-reset flow. A project that needs a different rule overrides
+`CoreUserService.assertCredentialChangeAllowed()`.
+
+## Compatibility Notes
+
+| Pattern                                             | Status                                                                |
+| --------------------------------------------------- | --------------------------------------------------------------------- |
+| Project without `multiTenancy`                      | Unchanged                                                             |
+| `multiTenancy` with `adminBypass` on (default)      | Unchanged except §3 (AI tool roles follow the membership)             |
+| `multiTenancy` with `adminBypass: false`            | §3 and §4 apply                                                       |
+| Project-own tenant-active guard                     | Keeps working; the hook adds the header-less path                     |
+| Project-own SSRF check                              | Keeps working; consider `outboundFetch()` for redirects and rebinding |
+| Custom `RequestContext.run()` for client operations | Set `fromRequest: true` (§3)                                          |
+| Override of `CoreAiMcpService.createServer(user)`   | Receives a getter now — call it per request (§3)                      |
+
+## Troubleshooting
+
+| Symptom                                                        | Cause                                                                   | Fix                                                                 |
+| -------------------------------------------------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------- |
+| `403` when an admin changes a tenant user's e-mail or password | `adminBypass: false` (§4)                                               | Let the user change it, or use the reset flow                       |
+| An AI tool disappeared for some users                          | Tool roles follow the membership under multi-tenancy (§3)               | List the tenant role the users hold in the tenant, or a global role |
+| `Tenant is inactive` (403)                                     | `isTenantActive` returned `false`                                       | Reactivate, then `invalidateTenant(tenantId)`                       |
+| A reactivated tenant is still refused                          | Cached answer                                                           | `tenantGuard.invalidateTenant(tenantId)`                            |
+| `OutboundUrlBlockedError` locally                              | `security.allowPrivateOutboundTargets: false` set, or a non-local `env` | Unset it, or list the host in `allowedHosts`                        |
+| `TypeError: fetch failed` from `outboundFetch()`               | A redirect or DNS answer pointed inside                                 | Inspect `error.cause`                                               |
+
+## Module Documentation
+
+- [Tenant README](../src/core/modules/tenant/README.md) — Admin Bypass, Deactivated Tenants, Service-Level Role Checks
+- [Tenant INTEGRATION-CHECKLIST](../src/core/modules/tenant/INTEGRATION-CHECKLIST.md) — step 11
+- [AI README](../src/core/modules/ai/README.md) — Tool access is the user's access

package/migration-guides/11.9.x-to-11.10.x.md

@@ -124,7 +124,8 @@ New `CoreBetterAuthChallengeService` enables Passkey authentication in **cookiel
 **Client-side usage (JWT mode):**
 ```typescript
 // Use composable methods which handle challengeId automatically
-const { authenticateWithPasskey, registerPasskey } = useBetterAuth();
+// useLtAuth() from @lenne.tech/nuxt-extensions; starters before nuxt-extensions called it useBetterAuth()
+const { authenticateWithPasskey, registerPasskey } = useLtAuth();
 
 // Authentication
 const result = await authenticateWithPasskey();
@@ -495,7 +496,7 @@ betterAuth: {
 **Solution:** Ensure you're using the composable methods that handle `challengeId`:
 ```typescript
 // CORRECT: Use composable methods
-const { authenticateWithPasskey } = useBetterAuth();
+const { authenticateWithPasskey } = useLtAuth(); // formerly useBetterAuth() in the starter
 await authenticateWithPasskey();
 
 // WRONG: Direct client call (doesn't handle challengeId in JWT mode)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nest-server",
-  "version": "11.41.8",
+  "version": "11.42.0",
   "description": "Modern, fast, powerful Node.js web framework in TypeScript based on Nest with a GraphQL API and a connection to MongoDB (or other databases).",
   "keywords": [
     "node",
@@ -137,6 +137,7 @@
     "rxjs": "7.8.2",
     "supertest": "7.3.0",
     "ts-morph": "28.0.0",
+    "undici": "7.30.0",
     "ws": "8.21.3",
     "yuml-diagram": "1.2.0"
   },

package/src/core/common/helpers/graphql-ws-context.helper.ts

@@ -93,7 +93,7 @@ export async function buildWsRequestContext(contextValue: any): Promise<IRequest
   }
 
   const user = readUser(contextValue);
-  const context: IRequestContext = { currentUser: user };
+  const context: IRequestContext = { currentUser: user, fromRequest: true };
 
   // Language: same source as the HTTP path, when the transport carried it.
   const acceptLanguage =