@lenne.tech/nest-server 11.41.9 → 11.42.1

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` |
 
@@ -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

@@ -77,6 +77,11 @@ GraphQL subscriptions use — and the finished file gets `metadata.tenantId`:
 | 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`.

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.42.0-to-11.42.1.md

@@ -0,0 +1,66 @@
+# Migration Guide: 11.42.0 → 11.42.1
+
+## Overview
+
+| Category             | Details                                                                                       |
+| -------------------- | --------------------------------------------------------------------------------------------- |
+| **Bugfix**           | Browser uploads through TUS work with cookie authentication and separate app/API origins (§1) |
+| **New option**       | `tus.allowedOrigins` overrides the derived origins (§1)                                       |
+| **Migration Effort** | None — `pnpm update`                                                                          |
+
+## Quick Migration
+
+```bash
+pnpm update @lenne.tech/nest-server
+```
+
+Vendor-mode projects pick up the core update; nothing else to change.
+
+## 1. TUS answered a credentialed request with `Access-Control-Allow-Origin: *`
+
+The tus handler writes its responses itself, past the API's CORS layer, and `@tus/server` answers
+`Access-Control-Allow-Origin: *` unless it is given `allowedOrigins`. The core gave it none. With cookie
+authentication and separate app and API origins (`lt dev up`, or `app.example.com` /
+`api.example.com`), the request is credentialed and the API adds
+`Access-Control-Allow-Credentials: true` — a combination every browser refuses:
+
+> The value of the 'Access-Control-Allow-Origin' header in the response must not be the wildcard '*'
+> when the request's credentials mode is 'include'.
+
+So every browser upload failed, while the server answered `201`. Preflights and unauthenticated
+requests were fine, which is why no test noticed — only an **authenticated** request with an `Origin`
+reaches the header.
+
+Since 11.42.1 the tus server takes its origins from `buildCorsConfig()`, the decision REST, GraphQL and
+Better-Auth already share (`appUrl`, `baseUrl`, `cors.allowedOrigins`, `cors.allowAll`), and mirrors an
+allowed `Origin`. A foreign origin gets no `Access-Control-Allow-Origin` at all. To use different
+origins for uploads:
+
+```typescript
+tus: {
+  allowedOrigins: ['https://uploads.example.com'];
+}
+```
+
+Without credentialed CORS configured — cookies off, or no origin resolvable — nothing changes; the tus
+default `*` stays.
+
+## 2. Dependencies
+
+Updated within their majors: `@modelcontextprotocol/sdk` 1.32.0, `mongoose` 9.10.4, `supertest` 7.3.1, and
+the `@aws-sdk/*` S3 packages 3.1146.0 (dev). NestJS stays on 11.
+
+`@modelcontextprotocol/sdk` 1.32.0 lets its CLIENT transports follow redirects only within the same
+origin. The framework uses the server side only, so this matters only to a project that builds its own MCP
+client transport and relied on a cross-origin redirect.
+
+## Troubleshooting
+
+| Symptom                                                                                            | Cause                                          | Fix                                                          |
+| -------------------------------------------------------------------------------------------------- | ---------------------------------------------- | ------------------------------------------------------------ |
+| Browser: "must not be the wildcard '*' when the request's credentials mode is 'include'" on `/tus` | 11.42.0 or older                               | Update to 11.42.1                                            |
+| Upload from an origin that is not the app refused by CORS                                          | Origin not in `appUrl` / `cors.allowedOrigins` | Add it to `cors.allowedOrigins`, or set `tus.allowedOrigins` |
+
+## Module Documentation
+
+- [TUS README](../src/core/modules/tus/README.md) — CORS Headers

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.9",
+  "version": "11.42.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",
@@ -92,7 +92,7 @@
     "@apollo/server": "5.5.1",
     "@as-integrations/express5": "1.1.2",
     "@getbrevo/brevo": "6.0.3",
-    "@modelcontextprotocol/sdk": "1.31.0",
+    "@modelcontextprotocol/sdk": "1.32.0",
     "@nestjs/apollo": "13.4.5",
     "@nestjs/common": "11.2.7",
     "@nestjs/core": "11.2.7",
@@ -126,7 +126,7 @@
     "json-to-graphql-query": "2.3.0",
     "lodash": "4.18.1",
     "mongodb": "7.6.0",
-    "mongoose": "9.10.3",
+    "mongoose": "9.10.4",
     "multer": "2.4.0",
     "node-mailjet": "6.0.11",
     "nodemailer": "10.0.13",
@@ -135,8 +135,9 @@
     "reflect-metadata": "0.2.2",
     "rfdc": "1.4.1",
     "rxjs": "7.8.2",
-    "supertest": "7.3.0",
+    "supertest": "7.3.1",
     "ts-morph": "28.0.0",
+    "undici": "7.30.0",
     "ws": "8.21.3",
     "yuml-diagram": "1.2.0"
   },
@@ -181,9 +182,9 @@
     }
   },
   "devDependencies": {
-    "@aws-sdk/client-s3": "3.1145.0",
-    "@aws-sdk/lib-storage": "3.1145.0",
-    "@aws-sdk/s3-request-presigner": "3.1145.0",
+    "@aws-sdk/client-s3": "3.1146.0",
+    "@aws-sdk/lib-storage": "3.1146.0",
+    "@aws-sdk/s3-request-presigner": "3.1146.0",
     "@better-auth/core": "1.7.7",
     "@better-auth/passkey": "1.7.7",
     "@compodoc/compodoc": "2.0.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 =

package/src/core/common/helpers/outbound-url.helper.ts

@@ -0,0 +1,310 @@
+import { lookup as dnsLookup, type LookupAddress } from 'node:dns';
+import { BlockList, isIP } from 'node:net';
+import { Agent, buildConnector, fetch as undiciFetch } from 'undici';
+
+import { ConfigService } from '../services/config.service';
+
+/**
+ * Requests to a URL a USER entered — a webhook, an export target, an ERP address.
+ *
+ * The server calls such a URL from inside its own network. Without a check, a user points it at the
+ * neighbourhood — the database, other containers, the cloud metadata service at 169.254.169.254 — and,
+ * wherever the response is stored or shown, reads the answer back (SSRF).
+ *
+ * **Only for user-entered URLs.** Targets the operator configured (AI providers, SMTP, S3, Redis,
+ * Brevo) do not go through this; nothing here is applied globally.
+ *
+ * The check runs twice on purpose:
+ * 1. {@link assertOutboundUrlAllowed} on the URL before anything is sent — a readable error, and
+ * 2. on every connection through {@link createOutboundDispatcher} — the only place that sees a
+ *    redirect's next hop and the address a DNS name resolves to at connect time (rebinding).
+ *
+ * {@link outboundFetch} does both.
+ *
+ * Internal targets are refused on deployed stages (including `test`) and allowed locally, in e2e and CI,
+ * where the counterpart often runs in the same network. `security.allowPrivateOutboundTargets`
+ * (`NSC__SECURITY__ALLOW_PRIVATE_OUTBOUND_TARGETS=true|false`) decides it explicitly either way;
+ * `allowedHosts` frees individual internal hosts without opening all of them.
+ */
+
+const blocked = new BlockList();
+for (const [network, prefix] of [
+  ['0.0.0.0', 8], // "this network"
+  ['10.0.0.0', 8], // RFC 1918
+  ['100.64.0.0', 10], // carrier-grade NAT
+  ['127.0.0.0', 8], // loopback
+  ['169.254.0.0', 16], // link-local, incl. the cloud metadata service
+  ['172.16.0.0', 12], // RFC 1918
+  ['192.0.0.0', 24], // IETF protocol assignments
+  ['192.168.0.0', 16], // RFC 1918
+  ['198.18.0.0', 15], // benchmarking
+  ['224.0.0.0', 4], // multicast
+  ['240.0.0.0', 4], // reserved, incl. broadcast
+] as const) {
+  blocked.addSubnet(network, prefix, 'ipv4');
+}
+for (const [network, prefix] of [
+  ['::', 96], // unspecified, loopback and IPv4-compatible (::a.b.c.d)
+  ['64:ff9b::', 96], // NAT64 — embeds an IPv4 address
+  ['fc00::', 7], // unique local
+  ['fe80::', 10], // link-local
+  ['ff00::', 8], // multicast
+] as const) {
+  blocked.addSubnet(network, prefix, 'ipv6');
+}
+
+/**
+ * Environments in which internal targets are allowed unless configured otherwise. Deliberately NOT
+ * `test`: in projects built from nest-server-starter that is a DEPLOYED stage.
+ */
+const LOCAL_ENVIRONMENTS = new Set(['ci', 'e2e', 'local']);
+
+/** Thrown for a target that is, or resolves to, an internal address. */
+export class OutboundUrlBlockedError extends Error {
+  constructor(
+    readonly host: string,
+    readonly address: string,
+  ) {
+    super(
+      `Outbound target not allowed: "${host}" points to the internal address ${address}. ` +
+        'Use a public address, list the host in allowedHosts, or set security.allowPrivateOutboundTargets.',
+    );
+    this.name = 'OutboundUrlBlockedError';
+  }
+}
+
+export interface IOutboundUrlOptions {
+  /**
+   * Internal hosts that may be reached anyway, e.g. an ERP in the same network. `'erp.local:8443'`
+   * matches that port only, `'erp.local'` and `'10.0.0.5'` any port. Matched against the host as
+   * written in the URL — and on every connection, so a redirect does not inherit the exemption.
+   */
+  allowedHosts?: string[];
+}
+
+/** Whether internal targets are allowed at all — explicit config first, then the environment. */
+export function privateOutboundTargetsAllowed(): boolean {
+  const config = ConfigService.configFastButReadOnly;
+  // Read loosely: a value from NSC__* or NEST_SERVER_CONFIG may arrive as a string.
+  const flag = config?.security?.allowPrivateOutboundTargets as unknown;
+  if (flag === true || flag === 'true') {
+    return true;
+  }
+  if (flag === false || flag === 'false') {
+    return false;
+  }
+  const env = String(config?.env ?? process.env.NODE_ENV ?? '')
+    .trim()
+    .toLowerCase();
+  return LOCAL_ENVIRONMENTS.has(env);
+}
+
+/** Whether an IP address is internal. A hostname (not an IP) answers false — resolve it first. */
+export function isBlockedOutboundAddress(address: string): boolean {
+  const plain = stripBrackets(address);
+  const family = isIP(plain);
+  if (family === 4) {
+    return blocked.check(plain, 'ipv4');
+  }
+  if (family === 6) {
+    const mapped = mappedIpv4(plain);
+    return mapped ? blocked.check(mapped, 'ipv4') : blocked.check(plain, 'ipv6');
+  }
+  return false;
+}
+
+/**
+ * Refuses a URL whose scheme is not http(s) or whose host is, or resolves to, an internal address.
+ * Returns the parsed URL. A redirect is NOT covered here — send the request through
+ * {@link outboundFetch} or {@link createOutboundDispatcher}.
+ */
+export async function assertOutboundUrlAllowed(url: string, options: IOutboundUrlOptions = {}): Promise<URL> {
+  let parsed: URL;
+  try {
+    parsed = new URL(url);
+  } catch {
+    throw new Error(`Invalid outbound URL: "${url}"`);
+  }
+  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+    throw new Error(`Outbound URL must use http:// or https://: "${url}"`);
+  }
+  const host = stripBrackets(parsed.hostname);
+  if (privateOutboundTargetsAllowed() || isAllowedHost(host, effectivePort(parsed.port, parsed.protocol), options)) {
+    return parsed;
+  }
+  const addresses = isIP(host) ? [host] : await resolveAll(host);
+  const internal = addresses.find(isBlockedOutboundAddress);
+  if (internal) {
+    throw new OutboundUrlBlockedError(host, internal);
+  }
+  return parsed;
+}
+
+const plainConnect = buildConnector({});
+const guardedConnect = buildConnector({ lookup: guardedLookup as never });
+
+/**
+ * An undici dispatcher that refuses every connection to an internal address — whether the host came
+ * as a name or as a literal, and whether it is the first URL or a redirect's next hop. Use it with
+ * undici's own `fetch`/`request`; {@link outboundFetch} does that for you.
+ */
+export function createOutboundDispatcher(options: IOutboundUrlOptions = {}): Agent {
+  return new Agent({
+    connect: (connectOptions, callback) => {
+      const host = stripBrackets(String(connectOptions.hostname ?? ''));
+      const port = effectivePort(connectOptions.port, connectOptions.protocol);
+      if (privateOutboundTargetsAllowed() || isAllowedHost(host, port, options)) {
+        plainConnect(connectOptions, callback);
+        return;
+      }
+      if (isIP(host) && isBlockedOutboundAddress(host)) {
+        callback(new OutboundUrlBlockedError(host, host), null);
+        return;
+      }
+      guardedConnect(connectOptions, callback);
+    },
+  });
+}
+
+let defaultDispatcher: Agent | undefined;
+const allowListDispatchers = new Map<string, Agent>();
+const MAX_ALLOW_LIST_DISPATCHERS = 50;
+
+/**
+ * `fetch` for a user-entered URL: the URL check first (a readable {@link OutboundUrlBlockedError}),
+ * then the request through a guarded dispatcher. Uses undici's own `fetch`, so the dispatcher always
+ * matches the client — Node's built-in `fetch` bundles a different undici major on Node 22.
+ *
+ * A refusal on a later hop (redirect, rebinding) surfaces as undici's `TypeError: fetch failed` with
+ * the {@link OutboundUrlBlockedError} as its `cause`.
+ */
+export async function outboundFetch(
+  url: string,
+  init: Parameters<typeof undiciFetch>[1] = {},
+  options: IOutboundUrlOptions = {},
+): ReturnType<typeof undiciFetch> {
+  await assertOutboundUrlAllowed(url, options);
+  return undiciFetch(url, { ...init, dispatcher: dispatcherFor(options) });
+}
+
+function dispatcherFor(options: IOutboundUrlOptions): Agent {
+  const hosts = (options.allowedHosts ?? []).map(normalizeHost).filter(Boolean).sort();
+  if (!hosts.length) {
+    defaultDispatcher ??= createOutboundDispatcher();
+    return defaultDispatcher;
+  }
+  const key = hosts.join(',');
+  let dispatcher = allowListDispatchers.get(key);
+  if (!dispatcher) {
+    if (allowListDispatchers.size >= MAX_ALLOW_LIST_DISPATCHERS) {
+      const [oldestKey, oldest] = allowListDispatchers.entries().next().value as [string, Agent];
+      allowListDispatchers.delete(oldestKey);
+      void oldest.close().catch(() => undefined);
+    }
+    dispatcher = createOutboundDispatcher({ allowedHosts: hosts });
+    allowListDispatchers.set(key, dispatcher);
+  }
+  return dispatcher;
+}
+
+function guardedLookup(
+  hostname: string,
+  options: { all?: boolean; family?: number },
+  callback: (err: Error | null, address?: LookupAddress[] | string, family?: number) => void,
+): void {
+  dnsLookup(hostname, { ...options, all: true }, (err, addresses) => {
+    if (err) {
+      callback(err);
+      return;
+    }
+    const list = addresses as LookupAddress[];
+    const internal = list.find((entry) => isBlockedOutboundAddress(entry.address));
+    if (internal) {
+      callback(new OutboundUrlBlockedError(hostname, internal.address));
+      return;
+    }
+    if (options.all) {
+      callback(null, list);
+      return;
+    }
+    callback(null, list[0]?.address, list[0]?.family);
+  });
+}
+
+function resolveAll(host: string): Promise<string[]> {
+  return new Promise((resolve, reject) => {
+    dnsLookup(host, { all: true }, (err, addresses) => {
+      if (err) {
+        reject(new Error(`Outbound target cannot be resolved: "${host}" (${err.message})`));
+        return;
+      }
+      resolve(addresses.map((entry) => entry.address));
+    });
+  });
+}
+
+function isAllowedHost(host: string, port: string, options: IOutboundUrlOptions): boolean {
+  const wanted = host.toLowerCase();
+  return (options.allowedHosts ?? []).some((entry) => {
+    const normalized = normalizeHost(entry);
+    if (!normalized) {
+      return false;
+    }
+    const [entryHost, entryPort] = splitHostPort(normalized);
+    return entryHost === wanted && (!entryPort || entryPort === port);
+  });
+}
+
+/** `Host`, `host:port`, `[v6]` and `[v6]:port`, lowercased, IPv6 canonicalised; '' when unusable. */
+function normalizeHost(entry: string): string {
+  if (typeof entry !== 'string' || !entry.trim()) {
+    return '';
+  }
+  try {
+    const url = new URL(`http://${entry.trim()}`);
+    const host = stripBrackets(url.hostname).toLowerCase();
+    return url.port ? `${host.includes(':') ? `[${host}]` : host}:${url.port}` : host;
+  } catch {
+    return '';
+  }
+}
+
+function splitHostPort(normalized: string): [string, string] {
+  const v6 = /^\[(.+)\]:(\d+)$/.exec(normalized);
+  if (v6) {
+    return [v6[1], v6[2]];
+  }
+  if (isIP(normalized) === 6) {
+    return [normalized, ''];
+  }
+  const index = normalized.lastIndexOf(':');
+  return index === -1 ? [normalized, ''] : [normalized.slice(0, index), normalized.slice(index + 1)];
+}
+
+function effectivePort(port: number | string | null | undefined, protocol: string | null | undefined): string {
+  if (port !== undefined && port !== null && String(port) !== '') {
+    return String(port);
+  }
+  return protocol === 'https:' ? '443' : '80';
+}
+
+function stripBrackets(value: string): string {
+  return value.replace(/^\[|\]$/g, '');
+}
+
+/** The IPv4 address inside an IPv4-mapped IPv6 address, in any notation. */
+function mappedIpv4(address: string): string | undefined {
+  let canonical: string;
+  try {
+    canonical = stripBrackets(new URL(`http://[${address}]`).hostname);
+  } catch {
+    return undefined;
+  }
+  const match = /^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/i.exec(canonical);
+  if (!match) {
+    return undefined;
+  }
+  const high = parseInt(match[1], 16);
+  const low = parseInt(match[2], 16);
+  return `${high >> 8}.${high & 255}.${low >> 8}.${low & 255}`;
+}