@lenne.tech/nest-server 11.41.3 → 11.41.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nest-server",
-  "version": "11.41.3",
+  "version": "11.41.5",
   "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",
@@ -16,8 +16,8 @@
   "scripts": {
     "build": "rimraf dist && nest build && pnpm run build:copy-types && pnpm run build:copy-templates && pnpm run build:add-type-references && pnpm run build:framework-api",
     "build:add-type-references": "node scripts/add-type-references.js",
-    "build:copy-templates": "mkdir -p dist/core/modules/migrate/templates && cp src/core/modules/migrate/templates/migration-project.template.ts dist/core/modules/migrate/templates/",
-    "build:copy-types": "mkdir -p dist/types && cp src/types/*.d.ts dist/types/",
+    "build:copy-templates": "node scripts/copy-build-assets.mjs templates",
+    "build:copy-types": "node scripts/copy-build-assets.mjs types",
     "build:dev": "pnpm run build",
     "build:framework-api": "tsx scripts/generate-framework-api.ts",
     "build:pack": "pnpm pack && echo \"use file:/ROOT_PATH_TO_TGZ_FILE to integrate the package\"",
@@ -25,12 +25,13 @@
     "cf": "pnpm run check:fix",
     "check": "node scripts/check.mjs",
     "check:consumer": "node scripts/check-consumer.mjs",
-    "check:fix": "pnpm install && pnpm run spectaql:sync && pnpm audit --fix && pnpm run check:overrides && pnpm peers check && pnpm run format && pnpm run lint:fix && pnpm run typecheck:tests && 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 run spectaql:sync && pnpm audit --fix && pnpm run check:overrides && pnpm peers check && pnpm run format && pnpm run lint:fix && pnpm run typecheck:tests && pnpm run check:swc-tdz && pnpm test && pnpm run build && pnpm run check:manifest && pnpm run check:server-start",
     "check:manifest": "node scripts/check-package-manifest.mjs",
     "check:mutations": "node scripts/check-mutations.mjs",
-    "check:naf": "pnpm install && pnpm run spectaql:sync && pnpm run check:overrides && pnpm peers check && pnpm run format && pnpm run lint:fix && pnpm run typecheck:tests && 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 spectaql:sync && pnpm run check:overrides && pnpm peers check && pnpm run format && pnpm run lint:fix && pnpm run typecheck:tests && pnpm run check:swc-tdz && pnpm test && pnpm run build && pnpm run check:manifest && pnpm run check:server-start",
     "check:overrides": "node scripts/check-overrides.mjs",
-    "check:raw": "pnpm install --frozen-lockfile && pnpm run spectaql:sync && pnpm audit && pnpm run check:overrides && pnpm peers check && pnpm run format:check && pnpm run lint && pnpm run typecheck:tests && pnpm run check:swc-tdz && pnpm test && pnpm run build && pnpm run check:manifest && bash scripts/check-server-start.sh",
+    "check:raw": "pnpm install --frozen-lockfile && pnpm run spectaql:sync && pnpm audit && pnpm run check:overrides && pnpm peers check && pnpm run format:check && pnpm run lint && pnpm run typecheck:tests && pnpm run check:swc-tdz && pnpm test && pnpm run build && pnpm run check:manifest && pnpm run check:server-start",
+    "check:server-start": "cross-env NODE_ENV=local node scripts/check-server-start.mjs --entry=dist/main.js --port-env=NSC__PORT --ready=\"Server starte[dt] at\" --path=/",
     "check:swc-tdz": "nest build -b swc -p tsconfig.swc-tdz.json && node scripts/check-swc-tdz.mjs",
     "cnaf": "pnpm run check:naf",
     "docs": "pnpm run docs:ci && open http://127.0.0.1:8080/ && open ./public/index.html && compodoc -p tsconfig.json -s ",
@@ -92,50 +93,50 @@
     "@apollo/server": "5.5.1",
     "@as-integrations/express5": "1.1.2",
     "@getbrevo/brevo": "6.0.3",
-    "@modelcontextprotocol/sdk": "1.30.0",
+    "@modelcontextprotocol/sdk": "1.31.0",
     "@nestjs/apollo": "13.4.5",
-    "@nestjs/common": "11.2.1",
-    "@nestjs/core": "11.2.1",
+    "@nestjs/common": "11.2.6",
+    "@nestjs/core": "11.2.6",
     "@nestjs/graphql": "13.4.5",
     "@nestjs/jwt": "11.0.2",
     "@nestjs/mongoose": "11.0.4",
     "@nestjs/passport": "11.0.5",
-    "@nestjs/platform-express": "11.2.1",
+    "@nestjs/platform-express": "11.2.6",
     "@nestjs/schedule": "6.1.3",
     "@nestjs/swagger": "11.4.7",
     "@nestjs/terminus": "11.1.1",
     "@tus/file-store": "2.1.1",
-    "@tus/server": "2.4.4",
+    "@tus/server": "2.4.5",
     "@types/supertest": "7.2.1",
     "bcrypt": "6.0.0",
     "class-transformer": "0.5.1",
     "class-validator": "0.15.1",
-    "compression": "1.8.1",
+    "compression": "1.8.2",
     "cookie-parser": "1.4.7",
     "cron": "4.4.0",
     "dotenv": "17.4.2",
     "ejs": "6.0.1",
     "express": "5.2.1",
-    "graphql": "16.14.0",
+    "graphql": "16.14.2",
     "graphql-query-complexity": "2.0.0",
     "graphql-subscriptions": "3.0.0",
     "graphql-upload": "15.0.2",
     "graphql-ws": "6.2.1",
-    "jose": "6.2.9",
+    "jose": "6.2.12",
     "js-sha256": "1.0.0",
     "json-to-graphql-query": "2.3.0",
     "lodash": "4.18.1",
-    "mongodb": "7.5.0",
-    "mongoose": "9.9.3",
-    "multer": "2.3.0",
+    "mongodb": "7.6.0",
+    "mongoose": "9.10.3",
+    "multer": "2.4.0",
     "node-mailjet": "6.0.11",
-    "nodemailer": "9.1.1",
+    "nodemailer": "10.0.13",
     "passport": "0.7.0",
     "passport-jwt": "4.0.1",
     "reflect-metadata": "0.2.2",
     "rfdc": "1.4.1",
     "rxjs": "7.8.2",
-    "supertest": "7.2.2",
+    "supertest": "7.3.0",
     "ts-morph": "28.0.0",
     "ws": "8.21.3",
     "yuml-diagram": "1.2.0"
@@ -177,47 +178,47 @@
     }
   },
   "devDependencies": {
-    "@aws-sdk/client-s3": "3.1115.0",
-    "@aws-sdk/s3-request-presigner": "3.1115.0",
+    "@aws-sdk/client-s3": "3.1143.0",
+    "@aws-sdk/s3-request-presigner": "3.1143.0",
     "@better-auth/core": "1.7.1",
     "@better-auth/passkey": "1.7.1",
     "@compodoc/compodoc": "2.0.0",
     "@nestjs/cli": "11.0.24",
     "@nestjs/schematics": "11.1.0",
-    "@nestjs/testing": "11.2.1",
+    "@nestjs/testing": "11.2.6",
     "@swc/cli": "0.8.1",
-    "@swc/core": "1.16.1",
-    "@tus/s3-store": "2.0.6",
+    "@swc/core": "1.16.12",
+    "@tus/s3-store": "2.0.7",
     "@types/compression": "1.8.1",
     "@types/cookie-parser": "1.4.10",
     "@types/ejs": "3.1.5",
     "@types/express": "5.0.6",
     "@types/lodash": "4.17.25",
-    "@types/multer": "2.2.0",
-    "@types/node": "26.2.0",
-    "@types/nodemailer": "8.0.1",
+    "@types/multer": "2.3.0",
+    "@types/node": "26.6.3",
+    "@types/nodemailer": "8.0.2",
     "@types/passport": "1.0.17",
     "@vitest/coverage-v8": "4.1.11",
     "ansi-colors": "4.1.3",
     "better-auth": "1.7.1",
-    "bullmq": "6.2.0",
+    "bullmq": "6.3.10",
     "cross-env": "10.1.0",
     "find-file-up": "2.0.1",
     "husky": "9.1.7",
     "ioredis": "6.0.0",
     "nodemon": "3.1.14",
     "npm-watch": "0.13.0",
-    "otpauth": "9.5.1",
-    "oxfmt": "0.64.0",
-    "oxlint": "1.79.0",
+    "otpauth": "9.5.2",
+    "oxfmt": "0.71.0",
+    "oxlint": "1.86.0",
     "rimraf": "6.1.3",
     "ts-node": "10.9.2",
     "tsconfig-paths": "4.2.0",
-    "tsx": "4.23.12",
+    "tsx": "4.23.15",
     "tus-js-client": "4.3.1",
     "typescript": "5.9.3",
-    "unplugin-swc": "1.5.11",
-    "vite": "8.2.2",
+    "unplugin-swc": "2.0.0",
+    "vite": "8.3.1",
     "vite-plugin-node": "8.0.0",
     "vitest": "4.1.11"
   },

package/src/core/common/helpers/graceful-shutdown.helper.ts

@@ -47,6 +47,15 @@ const SHUTDOWN_DELAY_ADVISORY_MS = 10_000;
  * Without a configured delay this is exactly `app.enableShutdownHooks()`, which is what the
  * framework did before.
  *
+ * **Windows: a termination from outside runs none of this.** Windows has no SIGTERM to deliver.
+ * Ending a process from outside, whether by `child.kill()`, `taskkill /F` (what `lt dev down` and
+ * the `check` watchdog use) or the Task Manager, terminates it at once. Measured on the Windows CI
+ * runner (`tests/unit/process-diagnostics-signal.spec.ts`): the process exits and the handler
+ * never runs. So on Windows neither `shutdownDelayMs` nor any `onModuleDestroy` /
+ * `onApplicationShutdown` hook runs on such a termination. Ctrl+C in a console window reaches Node
+ * as SIGINT and SHOULD reach this handler — that path is **unmeasured**. Do not rely on a graceful
+ * drain there; production targets Linux containers, where all of the above holds.
+ *
  * @param app the Nest application to shut down
  * @returns the same app, so it can be chained
  */

package/src/core/common/helpers/logging.helper.ts

@@ -171,6 +171,13 @@ export function redactSensitiveText(text: string): string {
         /(\/(?:request-password-reset|reset-password|forget-password|forgot-password|set-password|change-email|magic-?link|verify|reset|confirm|activate|invite)\/)([A-Za-z0-9._~-]{16,})/gi,
         (_m, prefix, token) => `${prefix}${maskToken(token)}`,
       )
+      // tenant API tokens (`<prefix>_<24 hex>_<64 hex>`) and their signed assertions
+      // (`<prefix>s_<payload>.<43-char HMAC>`) anywhere in the line — they are long-lived bearer
+      // credentials, and a line that quotes one outside an Authorization header would pass the rule below
+      .replace(/\b[a-z][a-z0-9]{1,15}_[0-9a-f]{24}_[0-9a-f]{64}\b/g, (match) => maskToken(match))
+      .replace(/\b[a-z][a-z0-9]{1,15}s_[A-Za-z0-9_-]{16,}\.[A-Za-z0-9_-]{43}(?![A-Za-z0-9_-])/g, (match) =>
+        maskToken(match),
+      )
       // authorization: Bearer xyz / Authorization=xyz
       .replace(
         /(authorization["']?\s*[:=]\s*["']?)(?:Bearer\s+)?([^\s"',;]+)/gi,

package/src/core/common/helpers/process-diagnostics.helper.ts

@@ -208,6 +208,10 @@ function describeError(value: unknown): string {
  * Call this as the first statement of `bootstrap()`, before `NestFactory.create()`. See the module
  * docblock for why it must not live inside `CoreModule.forRoot()`.
  *
+ * On Windows the signal labels are not written when the process is ended from outside: there is
+ * no signal to deliver, the process is terminated at once and no handler runs (measured on the
+ * Windows CI runner, see `installGracefulShutdown()`). Ctrl+C in a console is unmeasured.
+ *
  * @param options - Injectable dependencies; defaults target the real `process`
  *
  * @example

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

@@ -37,19 +37,25 @@ export type BetterAuthFieldType = 'boolean' | 'date' | 'json' | 'number' | 'numb
  * particularly useful in CI / e2e tests: `{ jsonTransport: true }` serializes
  * outgoing mail to a JSON string and returns a valid response without any
  * network I/O — no SMTP server, no credentials, no flakiness.
+ *
+ * The `X.default` members are the transport INSTANCE types. nodemailer >= 10 ships its own
+ * declarations, where each `nodemailer/lib/<transport>` module is `export default class` plus a
+ * module-level `Options` alias, so `import type * as X` yields a module namespace — the class is
+ * `X.default`. (`@types/nodemailer` used `export =` with a merged namespace, where `X` itself
+ * was the class.)
  */
 export type MailTransportOptions =
-  | JSONTransport
+  | JSONTransport.default
   | JSONTransport.Options
-  | SendmailTransport
+  | SendmailTransport.default
   | SendmailTransport.Options
-  | SESTransport
+  | SESTransport.default
   | SESTransport.Options
-  | SMTPPool
+  | SMTPPool.default
   | SMTPPool.Options
-  | SMTPTransport
+  | SMTPTransport.default
   | SMTPTransport.Options
-  | StreamTransport
+  | StreamTransport.default
   | StreamTransport.Options
   | string;
 
@@ -1473,6 +1479,86 @@ export interface IMultiTenancy {
   cacheTtlMs?: number;
 }
 
+/**
+ * Configuration of API tokens (`apiTokens`).
+ *
+ * Two kinds share one model and one policy:
+ * - USER tokens act as their user with the user's CURRENT rights (never global roles), optionally
+ *   narrowed to scopes, one tenant and a maximum tenant role. Work with and without multi-tenancy.
+ * - TENANT tokens belong to a tenant, are managed by its administrators and act with the lowest tenant
+ *   role inside that tenant only. Available while multi-tenancy is active.
+ *
+ * Both are denied on every route that does not declare `@ApiTokenScopes(...)`.
+ *
+ * @since 11.41.4
+ */
+export interface IApiTokens {
+  /**
+   * Pre-configure without enabling.
+   * @default true (when the object is present)
+   */
+  enabled?: boolean;
+
+  /**
+   * Pass-phrase for the AES-256-GCM encryption of each token's signing key (used for signed
+   * assertions). Falls back to the `SECRETS_ENCRYPTION_KEY` environment variable. REQUIRED in
+   * `production` / `staging` — the boot fails without it; elsewhere an insecure development default
+   * is used with a warning. Rotating it invalidates the signing keys of all existing tokens.
+   */
+  encryptionKey?: string;
+
+  /**
+   * Tenant role required to create, list, change, revoke and delete TENANT tokens. Hierarchy roles
+   * compare by level, so higher roles qualify too. Must be a declared tenant role that the lowest
+   * hierarchy role (the role a tenant token acts with) does not reach. Platform admins qualify while
+   * `multiTenancy.adminBypass` is on.
+   * @default the highest role of `multiTenancy.roleHierarchy`
+   */
+  manageRole?: string;
+
+  /**
+   * Maximum lifetime of a signed assertion, measured from the moment it is presented. A longer-lived
+   * assertion is refused (401). An invalid value falls back to the default — never to "unbounded".
+   * @default 900 (15 minutes)
+   */
+  maxAssertionLifetimeSeconds?: number;
+
+  /**
+   * Recognisable token prefix: 2-16 characters, lowercase letters and digits, starting with a letter.
+   * Tokens read `<prefix>_<publicId>_<secret>`, assertions `<prefix>s_<payload>.<signature>`.
+   * @default 'ltt'
+   */
+  prefix?: string;
+
+  /**
+   * Per-token request limit (fixed window, shared across replicas when `redis` is configured).
+   * An exceeded limit answers 429 with `Retry-After`. `false` switches it off.
+   * @default { max: 600, windowSeconds: 60 }
+   */
+  rateLimit?: boolean | { enabled?: boolean; max?: number; windowSeconds?: number };
+
+  /**
+   * Vocabulary of scopes a token may carry (e.g. `['upload', 'read', 'export']`). Creating or updating
+   * a token with any other scope fails with 400; with an empty vocabulary no token can be created.
+   * A user token created without scopes receives the whole vocabulary.
+   * Scopes: 1-64 characters of letters, digits, `:`, `.`, `_`, `-`.
+   * @default []
+   */
+  scopes?: string[];
+
+  /**
+   * Allow tenant tokens. Only takes effect while multi-tenancy is active.
+   * @default true
+   */
+  tenantTokens?: boolean;
+
+  /**
+   * Allow user tokens.
+   * @default true
+   */
+  userTokens?: boolean;
+}
+
 /**
  * Cookie configuration for authentication handling.
  *
@@ -2020,6 +2106,20 @@ export interface IServerOptions {
    */
   appUrl?: string;
 
+  /**
+   * API tokens: bearer credentials for machine clients and embedded pages that cannot carry a session
+   * cookie. USER tokens act as their user (without global roles); TENANT tokens belong to a tenant
+   * (multi-tenancy only). Both are denied on every route that does not declare `@ApiTokenScopes(...)`,
+   * and both respect tenant boundaries whenever multi-tenancy is active.
+   *
+   * Boolean shorthand: `true` / `{}` enable with defaults, `{ enabled: false }` pre-configures,
+   * absent = off (no behaviour change). See `src/core/modules/api-token/README.md`.
+   *
+   * @default undefined (disabled)
+   * @since 11.41.4
+   */
+  apiTokens?: boolean | IApiTokens;
+
   /**
    * Authentication system configuration
    *
@@ -4322,6 +4422,22 @@ interface IBetterAuthWithPasskey extends IBetterAuthBase {
  * @since 11.22.0
  */
 export interface ICoreModuleOverrides {
+  /**
+   * Override API token collaborators with project-specific subclasses (`apiTokens` config).
+   *
+   * - `model` must extend `CoreApiTokenModel` (e.g. to bind a token to project data)
+   * - `service` must extend `CoreApiTokenService`
+   *
+   * @example
+   * ```typescript
+   * { apiToken: { model: ApiToken, service: ApiTokenService } }
+   * ```
+   */
+  apiToken?: {
+    model?: Type<any>;
+    service?: Type<any>;
+  };
+
   /**
    * Override AI module collaborators with project-specific subclasses.
    *

package/src/core/modules/ai/INTEGRATION-CHECKLIST.md

@@ -209,9 +209,15 @@ The response body carries the stable `#LTNS_0901` code, never the raw error.
 
 ```typescript
 import { mountAiMcpOAuth } from '@lenne.tech/nest-server';
-await mountAiMcpOAuth(app, { baseUrl: process.env.BASE_URL });
+await mountAiMcpOAuth(app);
 ```
 
+**WHY no `baseUrl` argument:** the issuer is every URL in the discovery metadata, and MCP clients
+follow them. The helper takes it from the server's `baseUrl` (`NSC__BASE_URL` when deployed) and
+fails the boot in a deployed environment that has none, rather than advertising `localhost` —
+which sends clients to the user's own machine. Pass `{ baseUrl }` only for an issuer that must
+differ from the server's `baseUrl`; never add a `localhost` fallback of your own.
+
 Override `CoreAiMcpOAuthService.authorizeConsent()` with your login/consent UI (the only
 browser-interactive step). All other OAuth pieces (tokens, PKCE, stores) are built in.
 
@@ -231,12 +237,13 @@ browser-interactive step). All other OAuth pieces (tokens, PKCE, stores) are bui
 
 ## Common Mistakes
 
-| Mistake                                       | Symptom                                                       | Fix                                                       |
-| --------------------------------------------- | ------------------------------------------------------------- | --------------------------------------------------------- |
-| No `ai` config block                          | Module not loaded, `aiPrompt` missing from schema             | Add an `ai` block (presence implies enabled)              |
-| No encryption secret in prod                  | **App refuses to boot** (throws); dev/local only warns        | Set `NSC__AI__ENCRYPTION_SECRET` (32+ chars)              |
-| Encryption secret changed after keys stored   | Boot logs "key(s) could not be decrypted"; those prompts fail | Re-enter the API key for the listed connections           |
-| Tool returns `.lean()`/aggregate data         | `@Restricted` fields leak into the LLM context                | Route through `CrudService` with `context.serviceOptions` |
-| Tool not registered                           | Tool never offered to the LLM                                 | Declare it as a provider in a module (extends `AiTool`)   |
-| Overridden resolver method missing decorators | Method absent from GraphQL schema                             | Re-declare `@Mutation`/`@Query`/`@Roles` in the override  |
-| Storing a real API key in `config.env.ts`     | Secret committed to the repo                                  | Use `apiKeyEnv` or the runtime connection CRUD            |
+| Mistake                                          | Symptom                                                                                | Fix                                                                |
+| ------------------------------------------------ | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
+| No `ai` config block                             | Module not loaded, `aiPrompt` missing from schema                                      | Add an `ai` block (presence implies enabled)                       |
+| No encryption secret in prod                     | **App refuses to boot** (throws); dev/local only warns                                 | Set `NSC__AI__ENCRYPTION_SECRET` (32+ chars)                       |
+| Encryption secret changed after keys stored      | Boot logs "key(s) could not be decrypted"; those prompts fail                          | Re-enter the API key for the listed connections                    |
+| Tool returns `.lean()`/aggregate data            | `@Restricted` fields leak into the LLM context                                         | Route through `CrudService` with `context.serviceOptions`          |
+| Tool not registered                              | Tool never offered to the LLM                                                          | Declare it as a provider in a module (extends `AiTool`)            |
+| Overridden resolver method missing decorators    | Method absent from GraphQL schema                                                      | Re-declare `@Mutation`/`@Query`/`@Roles` in the override           |
+| Storing a real API key in `config.env.ts`        | Secret committed to the repo                                                           | Use `apiKeyEnv` or the runtime connection CRUD                     |
+| `localhost` fallback for the MCP OAuth `baseUrl` | MCP client fails to register with `ECONNREFUSED`; discovery metadata names `localhost` | Call `mountAiMcpOAuth(app)` without `baseUrl`, set `NSC__BASE_URL` |

package/src/core/modules/ai/README.md

@@ -657,9 +657,17 @@ also accepts OAuth access tokens. Mount the discovery/token endpoints in `main.t
 ```typescript
 // main.ts, after app.init()
 import { mountAiMcpOAuth } from '@lenne.tech/nest-server';
-await mountAiMcpOAuth(app, { baseUrl: process.env.BASE_URL });
+await mountAiMcpOAuth(app);
 ```
 
+The issuer — and with it every endpoint URL in the discovery metadata, which MCP clients follow —
+is the server's `baseUrl` (`NSC__BASE_URL` when deployed), resolved the same way BetterAuth and
+CORS resolve it. `local` / `ci` / `e2e` fall back to `http://localhost:3000`; any other environment
+without a `baseUrl` fails the call instead of guessing, because a deployed API that advertised
+`http://localhost:3000` sent Claude Code off to register the client on the user's own machine.
+Pass `{ baseUrl }` only when the issuer must differ from the server's `baseUrl`, and do not add a
+`localhost` fallback of your own. The resolved issuer is logged once at boot.
+
 Override `CoreAiMcpOAuthService.authorizeConsent()` to wire your login/consent UI.
 Set `ai.mcp.oauthSecret` (or reuse `ai.encryptionSecret`) to a random 32+ char value.
 

package/src/core/modules/ai/helpers/ai-mcp-oauth.helper.ts

@@ -1,3 +1,7 @@
+import { Logger } from '@nestjs/common';
+
+import { resolveServerUrls } from '../../../common/helpers/cookies.helper';
+import { ConfigService } from '../../../common/services/config.service';
 import { CoreAiMcpOAuthService } from '../services/core-ai-mcp-oauth.service';
 
 /**
@@ -11,25 +15,88 @@ import { CoreAiMcpOAuthService } from '../services/core-ai-mcp-oauth.service';
  * The interactive consent step requires `CoreAiMcpOAuthService.authorizeConsent`
  * to be overridden with your login/consent UI (see INTEGRATION-CHECKLIST).
  *
+ * The base URL must be the server's public URL: it becomes the OAuth issuer and
+ * every endpoint in the discovery metadata, and MCP clients follow those URLs.
+ * Resolution order:
+ *
+ * 1. `options.baseUrl`, when non-blank — for an issuer that differs from `baseUrl`
+ * 2. `baseUrl` from the server config (`NSC__BASE_URL` in deployed environments)
+ * 3. `http://localhost:3000` in `local` / `ci` / `e2e` only
+ * 4. otherwise the call throws — it never guesses
+ *
+ * Steps 2 and 3 are `resolveServerUrls()`, the resolver BetterAuth and CORS use, so
+ * the issuer agrees with the URL the rest of the server believes it has. Step 4 is
+ * the point: a deployed API that advertised `http://localhost:3000` made Claude Code
+ * try to register the client on the user's own machine (`ECONNREFUSED`).
+ *
  * @example
  * ```typescript
  * // main.ts, after app.init()
- * await mountAiMcpOAuth(app, { baseUrl: process.env.BASE_URL });
+ * await mountAiMcpOAuth(app);
  * ```
  */
 export async function mountAiMcpOAuth(
   app: { get: (token: any) => any; use: (...args: any[]) => any },
-  options: { baseUrl: string; mcpPath?: string },
+  options: { baseUrl?: string; mcpPath?: string } = {},
 ): Promise<void> {
+  const { baseUrl, source } = resolveMcpOAuthBaseUrl(options.baseUrl);
+  const issuerUrl = parseAbsoluteUrl(baseUrl, source);
   const { mcpAuthRouter } = await import('@modelcontextprotocol/sdk/server/auth/router.js');
   const oauthService: CoreAiMcpOAuthService = app.get(CoreAiMcpOAuthService);
   const mcpPath = options.mcpPath ?? '/ai/mcp';
 
-  const router = mcpAuthRouter({
-    issuerUrl: new URL(options.baseUrl),
-    provider: oauthService.buildOAuthProvider() as any,
-    resourceServerUrl: new URL(`${options.baseUrl.replace(/\/$/, '')}${mcpPath}`),
-  });
+  let router: unknown;
+  try {
+    router = mcpAuthRouter({
+      issuerUrl,
+      provider: oauthService.buildOAuthProvider() as any,
+      resourceServerUrl: new URL(`${baseUrl.replace(/\/$/, '')}${mcpPath}`),
+    });
+  } catch (error) {
+    // The SDK's refusals ("Issuer URL must be HTTPS") do not say which URL they refused. Now
+    // that the URL can come from config rather than from the call site, that is the one thing
+    // an operator needs to know.
+    const reason = (error as Error).message;
+    throw new Error(`mountAiMcpOAuth: OAuth issuer "${baseUrl}" (from ${source}) rejected: ${reason}`, {
+      cause: error,
+    });
+  }
 
   app.use(router);
+  new Logger('mountAiMcpOAuth').log(`MCP OAuth issuer: ${issuerUrl.href} (from ${source})`);
+}
+
+/**
+ * Resolves the issuer base URL. A blank `explicit` value counts as absent, because
+ * `BASE_URL=` in an env file yields `''`, not `undefined`.
+ */
+function resolveMcpOAuthBaseUrl(explicit: string | undefined): { baseUrl: string; source: string } {
+  const given = explicit?.trim();
+  if (given) {
+    return { baseUrl: given, source: 'options.baseUrl' };
+  }
+
+  const config = ConfigService.configFastButReadOnly;
+  const resolved = resolveServerUrls({ baseUrl: config?.baseUrl, env: config?.env });
+  if (resolved.baseUrl) {
+    return {
+      baseUrl: resolved.baseUrl,
+      source:
+        resolved.baseUrlSource === 'localhost-default' ? `localhost default (env: ${config?.env})` : 'config.baseUrl',
+    };
+  }
+
+  throw new Error(
+    `mountAiMcpOAuth: no public server URL for the OAuth issuer (env: ${config?.env ?? 'unset'}). ` +
+      'Set `baseUrl` in the server config (NSC__BASE_URL) or pass `options.baseUrl`. ' +
+      'A guessed localhost URL would send MCP clients to their own machine.',
+  );
+}
+
+function parseAbsoluteUrl(value: string, source: string): URL {
+  try {
+    return new URL(value);
+  } catch {
+    throw new Error(`mountAiMcpOAuth: "${value}" (from ${source}) is not an absolute URL`);
+  }
 }

package/src/core/modules/ai/services/core-ai-mcp-oauth.service.ts

@@ -5,6 +5,7 @@ import { Connection } from 'mongoose';
 
 import { isProductionLikeEnv } from '../../../common/helpers/cookies.helper';
 import { ConfigService } from '../../../common/services/config.service';
+import { getApiTokenContext } from '../../api-token/core-api-token.helpers';
 
 /**
  * Stored OAuth client (dynamically registered).
@@ -309,7 +310,18 @@ export class CoreAiMcpOAuthService implements OnModuleInit {
    */
   buildOAuthProvider(accessTtlSeconds = 3600): Record<string, any> {
     return {
-      authorize: (client: any, params: any, res: any) => this.authorizeConsent(client, params, res),
+      authorize: async (client: any, params: any, res: any) => {
+        // An API token (or its signed assertion) must never approve an OAuth consent. The consent mints
+        // an MCP access token with the FULL rights of its user, which would lift a scope-limited user
+        // token out of every restriction it carries — and a tenant token has no user to consent for at
+        // all. This route is an Express router outside the Nest guards, so the deny-by-default of
+        // @ApiTokenScopes() does not reach it; the check sits here rather than in authorizeConsent()
+        // so an override of that method cannot drop it.
+        if (getApiTokenContext(res?.req?.user)) {
+          throw new Error('access_denied: an API token cannot authorize an OAuth client');
+        }
+        return this.authorizeConsent(client, params, res);
+      },
       challengeForAuthorizationCode: async (_client: any, authorizationCode: string) => {
         const stored = await this.getAuthorizationCode(authorizationCode);
         return stored?.codeChallenge ?? '';