@lenne.tech/nest-server 11.43.2 → 11.43.3

package/docs/REQUEST-LIFECYCLE.md

@@ -179,7 +179,7 @@ JWT-based authentication for existing projects:
 | **AI Module** | Prompt orchestrator (auto + plan mode), DB-backed LLM connections, tool registry |
 | **REST Endpoints** | `POST /ai/prompt`, `POST /ai/stream` (SSE); `GET/POST/PUT/DELETE /ai/connections*`, `/ai/connections/available`, `/ai/connections/select`, `/ai/connections/preferences*`, `/ai/conversations*`, `/ai/interactions*`, `/ai/budget-limits*`, `GET /ai/usage` |
 | **GraphQL Endpoints** | `aiPrompt`, `aiAvailableConnections`, `aiSetUserConnection`, connection/preference/conversation/interaction/budget queries + mutations, `aiUsage` |
-| **MCP Server** | Streamable HTTP at `POST/GET/DELETE /ai/mcp` (Bearer auth); with `ai.mcp.oauth` an OAuth 2.1 router (`/.well-known/*`, `/authorize`, `/token`, `/register`) that `CoreAiMcpOAuthInitializer` mounts during `app.init()` — an Express router behind the Nest middleware and routes, ahead of Nest's not-found handler, so guards and interceptors do not run for it; `/authorize` answers with a built-in consent page (the Better-Auth session from the middleware is the user; Allow is a CSRF-bound POST) |
+| **MCP Server** | Streamable HTTP at `POST/GET/DELETE /ai/mcp` (Bearer auth); a user the controller resolves itself (the OAuth access token, which only this controller accepts, after the guards ran without a user) gets `req.user` and the tenant the header names from an active membership only, through `CoreTenantGuard.resolveMembershipContext()` (11.43.3); with `ai.mcp.oauth` an OAuth 2.1 router (`/.well-known/*`, `/authorize`, `/token`, `/register`) that `CoreAiMcpOAuthInitializer` mounts during `app.init()` — an Express router behind the Nest middleware and routes, ahead of Nest's not-found handler, so guards and interceptors do not run for it; `/authorize` answers with a built-in consent page (the Better-Auth session from the middleware is the user; Allow is a CSRF-bound POST) |
 | **Permission Model** | `S_USER` for prompt/conversations/available/usage; `ADMIN` for connections/preferences/interactions/budgets; encrypted API keys never leave the server (`securityCheck` + `secretFields`) |
 
 ### Email & Templates

package/migration-guides/11.43.2-to-11.43.3.md

@@ -0,0 +1,80 @@
+# Migration Guide: 11.43.2 → 11.43.3
+
+## Overview
+
+| Category             | Details                                                                                                                                                                                                                                                                              |
+| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **Bugfixes**         | An MCP OAuth access token reaches the tenant context: tenant-scoped AI tools answered "Tenant context required" to every OAuth client, members included (§1). The OAuth user is the current user of the request, so audit fields and the role guard plugin apply to tool writes (§2) |
+| **New Features**     | None                                                                                                                                                                                                                                                                                 |
+| **Framework API**    | `CoreTenantGuard.resolveMembershipContext()` (new, public), the optional `resolveMembership()` on the exported `TenantContextResolver` interface, `CoreAiMcpController.resolveScopedUser()` / `scopeLateResolvedUser()` (new, protected)                                             |
+| **Dependencies**     | Unchanged                                                                                                                                                                                                                                                                            |
+| **Breaking Changes** | None                                                                                                                                                                                                                                                                                 |
+| **Migration Effort** | None. Check §2 if MCP tools of your project write data                                                                                                                                                                                                                               |
+
+## Quick Migration
+
+```bash
+pnpm update @lenne.tech/nest-server
+```
+
+Vendor-mode projects pick it up with the core update. No code or configuration change is required.
+
+## 1. MCP OAuth clients got no tenant context
+
+`CoreTenantGuard` turns the tenant header (`X-Tenant-Id`) into a tenant context only for a user it sees on the
+request. A session cookie and a Better-Auth JWT are resolved by the middleware before the guards. An MCP OAuth
+access token is not: nothing but `CoreAiMcpController` accepts it, so it is resolved after the guards. The request
+therefore never got a tenant, and `mongooseTenantPlugin` refused every tenant-scoped read — a generic MCP client
+could discover, register, pass the consent page, open a session and list its tools, and then every tenant-scoped
+tool answered `Tenant context required`, even with a header naming a tenant the user is an active member of.
+
+The controller now asks the guard's own membership check (`CoreTenantGuard.resolveMembershipContext()`, the same
+decision as its `@Roles(S_EVERYONE)` branch) for a user it resolved itself. The result does not depend on the
+credential:
+
+| Request                                               | Session cookie / JWT | MCP OAuth token (11.43.2) | MCP OAuth token (11.43.3) |
+| ----------------------------------------------------- | -------------------- | ------------------------- | ------------------------- |
+| Header names a tenant the user is an active member of | that tenant          | none — refused            | that tenant               |
+| Header names a tenant the user is not a member of     | none — refused       | none — refused            | none — refused            |
+| No header                                             | none — refused       | none — refused            | none — refused            |
+
+The header alone never establishes a tenant, which is what keeps a freely chosen `X-Tenant-Id` harmless.
+
+## 2. The OAuth user is the current user of the request
+
+For the same reason `req.user` stayed unset for an OAuth request, and `RequestContext.currentUser` is read from
+it. The Mongoose plugins read an empty current user as work the server does on its own:
+
+- `createdBy` / `updatedBy` were not written for data an MCP tool created or changed,
+- `mongooseRoleGuardPlugin` let a tool's write change `roles` without checking the caller,
+- `assertTenantRole()` refused the call as anonymous.
+
+Since 11.43.3 the controller sets `req.user` for a user it resolved itself, so all three behave as for a cookie or
+JWT request.
+
+**What to check:**
+
+- **An MCP tool of your project writes `roles` and relied on the role guard plugin letting it through:** under an
+  OAuth token that write is now checked against the user, as it always was under a cookie or a JWT. Run such a
+  write inside `RequestContext.runWithBypassRoleGuard()` when the tool is meant to assign roles.
+- **A test in your project pins the old refusal** ("Tenant context required" for an OAuth member): flip it to
+  assert the data, and keep the cases for a non-member and for a missing header refused.
+- **You override `CoreAiMcpController.handlePost()` or `handleGet()` / `handleDelete()`** without calling
+  `super`: resolve the user through `resolveScopedUser(req)` instead of `resolveUser(req)`, or the fix does not
+  reach your controller.
+
+## Compatibility Notes
+
+| Pattern                                                                      | Status                                                                                                        |
+| ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| MCP over a session cookie or a Better-Auth JWT                               | Unchanged — the guards saw the user before                                                                    |
+| MCP OAuth without `multiTenancy`                                             | Unchanged apart from §2                                                                                       |
+| Your own `TenantContextResolver` registered via `setTenantContextResolver()` | Compiles unchanged — `resolveMembership()` is optional; without it an OAuth request gets no tenant, as before |
+| An override of `resolveUser()`                                               | Still used — `resolveScopedUser()` calls it                                                                   |
+
+## Module Documentation
+
+- [AI module → Tool access is the user's access](../src/core/modules/ai/README.md#tool-access-is-the-users-access)
+- [Tenant module](../src/core/modules/tenant/README.md)
+- Implementation: `src/core/modules/ai/core-ai-mcp.controller.ts` → `scopeLateResolvedUser()`,
+  `src/core/modules/tenant/core-tenant.guard.ts` → `resolveMembershipContext()`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nest-server",
-  "version": "11.43.2",
+  "version": "11.43.3",
   "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",

package/src/core/common/services/core-tenant-context.registry.ts

@@ -28,6 +28,18 @@ export interface TenantContextResolver {
    *   validated against an active membership before it is returned
    */
   resolve(user: { id: string; roles?: string[] } | undefined, headerTenantId?: string): Promise<ResolvedTenantContext>;
+
+  /**
+   * The narrower answer `CoreTenantGuard` gives an `@Roles(S_EVERYONE)` route: a tenant only from an
+   * ACTIVE membership in the tenant the header names (in an active tenant) — no admin bypass, and no
+   * fallback to every membership when no tenant is named. For an HTTP route that authenticates its
+   * caller itself, after the guards ran without a user (the MCP endpoint and its OAuth access token),
+   * so that route scopes the request exactly as the guard would have.
+   *
+   * Optional because the interface is public. A caller finding it absent establishes no tenant, which
+   * leaves the plugin's safety net to refuse tenant-scoped reads.
+   */
+  resolveMembership?(user: { id: string; roles?: string[] }, headerTenantId?: string): Promise<ResolvedTenantContext>;
 }
 
 let resolver: TenantContextResolver | undefined;

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

@@ -619,6 +619,12 @@ them:
   so `mongooseTenantPlugin` filters by the tenant the guard validated. Without a tenant header there
   is no tenant scope on these routes and tenant-scoped reads are refused (403) — an AI client is
   never broader than its user, at worst narrower.
+  An **MCP OAuth access token** is accepted only by the MCP controller, after the guards ran without a
+  user. Since 11.43.3 the controller gives such a request what the guard gives a user it saw: the user
+  on the request (so `RequestContext.currentUser`, the audit fields and `mongooseRoleGuardPlugin` see
+  it), and the tenant the header names — only when the user is an ACTIVE member of it, through the
+  guard's own check (`CoreTenantGuard.resolveMembershipContext()`). Before, every tenant-scoped tool
+  answered "Tenant context required" to an OAuth client, even for a member.
 - **Service-level rules** apply on every entry point when the service enforces them itself —
   `assertTenantRole()` (see the tenant module README) — instead of relying on a controller's
   `@Roles()`, which a tool calling the service never passes through.

package/src/core/modules/ai/core-ai-mcp.controller.ts

@@ -7,6 +7,7 @@ import { Roles } from '../../common/decorators/roles.decorator';
 import { RoleEnum } from '../../common/enums/role.enum';
 import { ConfigService } from '../../common/services/config.service';
 import { CoreRedisService } from '../../common/services/core-redis.service';
+import { getTenantContextResolver } from '../../common/services/core-tenant-context.registry';
 import { CoreBetterAuthModule } from '../better-auth/core-better-auth.module';
 import { ErrorCode } from '../error-code/error-codes';
 import { getMountedMcpOAuth } from './helpers/ai-mcp-oauth.registry';
@@ -36,7 +37,9 @@ import { AiToolUser } from './tools/ai-tool.registry';
  *
  * When `ai.mcp.oauth` is enabled, the handler additionally accepts OAuth 2.1 access
  * tokens (endpoints mounted by `CoreAiMcpOAuthInitializer`); otherwise it authenticates via
- * Bearer/session token.
+ * Bearer/session token. A user resolved here rather than by the guards — the OAuth token always —
+ * gets the request scope the guards would have given it (`req.user`, and a tenant from an active
+ * membership in the tenant the header names): see {@link CoreAiMcpController.scopeLateResolvedUser}.
  *
  * ## Multi-replica
  *
@@ -121,7 +124,7 @@ export class CoreAiMcpController implements OnModuleDestroy {
   })
   @Post()
   async handlePost(@Req() req: Request, @Res() res: Response): Promise<void> {
-    const user = await this.resolveUser(req);
+    const user = await this.resolveScopedUser(req);
     if (!user?.id) {
       this.unauthorized(res);
       return;
@@ -274,6 +277,59 @@ export class CoreAiMcpController implements OnModuleDestroy {
     return null;
   }
 
+  /**
+   * {@link resolveUser}, plus — for a user resolved HERE rather than seen by the guards — the request
+   * scope the guards give a user they saw (see {@link scopeLateResolvedUser}).
+   *
+   * Whether the guards saw the user is read BEFORE `resolveUser()` runs, so an override of it that sets
+   * `req.user` itself still counts as resolved late.
+   */
+  protected async resolveScopedUser(req: Request): Promise<any | null> {
+    const seenByGuards = !!(req as any).user?.id;
+    const user = await this.resolveUser(req);
+    if (user?.id && !seenByGuards) {
+      await this.scopeLateResolvedUser(req, user);
+    }
+    return user;
+  }
+
+  /**
+   * Give a request whose user this controller resolved itself what the guards give a request whose
+   * user they saw: the user on the request, and a tenant from an active membership only.
+   *
+   * The guards run before this controller, and an MCP OAuth access token is accepted by nothing else
+   * — so `CoreTenantGuard` found no `request.user` and never turned the tenant header into a context.
+   * In 11.43.2 and earlier that left two things behind:
+   * - **No tenant scope.** Every tenant-scoped tool answered "Tenant context required", even with a
+   *   tenant header naming a tenant the user is an active member of. Fail-closed, but unusable.
+   * - **No current user in `RequestContext`**, which reads `req.user` lazily. The Mongoose plugins read
+   *   that as SYSTEM work: no `createdBy` / `updatedBy`, `mongooseRoleGuardPlugin` let a tool's write
+   *   change roles, and `assertTenantRole()` refused the call as anonymous.
+   *
+   * The tenant comes from `CoreTenantGuard.resolveMembershipContext()`, the same decision its
+   * `@Roles(S_EVERYONE)` branch makes for a user it saw — so an OAuth token, a session cookie and a
+   * Better-Auth JWT reach the same scope. The header alone never establishes one: a tenant the user is
+   * not an active member of yields none, and the plugin's safety net refuses the read.
+   */
+  protected async scopeLateResolvedUser(req: Request, user: { id: string; roles?: string[] }): Promise<void> {
+    (req as any).user = user;
+
+    const config = ConfigService.configFastButReadOnly?.multiTenancy;
+    if (!config || config.enabled === false || (req as any).tenantId) {
+      return;
+    }
+    const headerName = (config.headerName ?? 'x-tenant-id').toLowerCase();
+    const header = req.headers?.[headerName];
+    const resolved = await getTenantContextResolver()?.resolveMembership?.(
+      user,
+      typeof header === 'string' ? header : undefined,
+    );
+    if (resolved?.tenantId) {
+      (req as any).tenantId = resolved.tenantId;
+      (req as any).tenantRole = resolved.tenantRole;
+    }
+  }
+
   /**
    * Whether the body is an `initialize` — the one request that legitimately starts a session.
    *
@@ -298,7 +354,7 @@ export class CoreAiMcpController implements OnModuleDestroy {
    * Forward a GET (SSE stream) or DELETE (close) to the session's transport.
    */
   private async handleSessionRequest(req: Request, res: Response): Promise<void> {
-    const user = await this.resolveUser(req);
+    const user = await this.resolveScopedUser(req);
     if (!user?.id) {
       this.unauthorized(res);
       return;

package/src/core/modules/tenant/core-tenant.guard.ts

@@ -181,6 +181,7 @@ export class CoreTenantGuard implements CanActivate, OnApplicationBootstrap, OnM
     // GraphQL WebSocket. See core-tenant-context.registry.ts for why this is a registry and not DI.
     setTenantContextResolver({
       resolve: (user, headerTenantId) => this.resolveTenantContext(user, headerTenantId),
+      resolveMembership: (user, headerTenantId) => this.resolveMembershipContext(user, headerTenantId),
     });
 
     // Lets the role guards delegate non-system roles to this guard — only while it exists.
@@ -248,6 +249,39 @@ export class CoreTenantGuard implements CanActivate, OnApplicationBootstrap, OnM
     return { tenantIds: carrier.tenantIds ?? [] };
   }
 
+  /**
+   * The tenant context `canActivate()` gives an `@Roles(S_EVERYONE)` route, for a caller it could not
+   * see: a route that authenticates its caller ITSELF, after the guards ran without a user.
+   *
+   * That is the MCP endpoint with an MCP OAuth access token — a credential nothing but its controller
+   * accepts, so the guard found no `request.user`, never checked the tenant header against a
+   * membership, and every tenant-scoped tool answered "Tenant context required" to a member of that
+   * very tenant. Answering through the same {@link memberTenantContext} as the guard's own branch is
+   * what keeps the result independent of which credential the caller used.
+   *
+   * Narrower than {@link resolveTenantContext} on purpose: that one answers for a transport whose every
+   * operation needs a scope (no admin bypass here, no list of all memberships without a header).
+   */
+  async resolveMembershipContext(
+    user: { id: string; roles?: string[] } | undefined,
+    headerTenantId?: string,
+  ): Promise<ResolvedTenantContext> {
+    const config = ConfigService.configFastButReadOnly?.multiTenancy;
+    if (!config || config.enabled === false) {
+      return {};
+    }
+    this.syncConfig(config);
+
+    const tenantId =
+      headerTenantId && typeof headerTenantId === 'string' && headerTenantId.length <= 128
+        ? headerTenantId.trim()
+        : undefined;
+    if (!tenantId || !user?.id) {
+      return {};
+    }
+    return (await this.memberTenantContext(user, tenantId)) ?? {};
+  }
+
   /**
    * Subscribe to the cross-replica cache invalidation channel.
    *
@@ -414,10 +448,10 @@ export class CoreTenantGuard implements CanActivate, OnApplicationBootstrap, OnM
       // Optionally enrich with tenant context when header is present and user is an active member.
       // Never block access — S_EVERYONE endpoints are always public.
       if (headerTenantId && request.user?.id) {
-        const membership = await this.findMembershipCached(request.user.id, headerTenantId);
-        if (membership && (await this.isTenantActive(headerTenantId))) {
-          request.tenantId = headerTenantId;
-          request.tenantRole = capApiTokenTenantRole(request.user, membership.role as string) ?? undefined;
+        const member = await this.memberTenantContext(request.user, headerTenantId);
+        if (member) {
+          request.tenantId = member.tenantId;
+          request.tenantRole = member.tenantRole;
         }
       }
       return true;
@@ -901,6 +935,22 @@ export class CoreTenantGuard implements CanActivate, OnApplicationBootstrap, OnM
     return active;
   }
 
+  /**
+   * The context an ACTIVE membership in an active tenant establishes, or undefined. Never the header
+   * alone: a freely chosen tenant id only becomes a scope once it names one of the caller's own tenants.
+   * Shared by the `S_EVERYONE` branch of `canActivate()` and {@link resolveMembershipContext}.
+   */
+  private async memberTenantContext(
+    user: { id: string; roles?: string[] },
+    tenantId: string,
+  ): Promise<{ tenantId: string; tenantRole?: string } | undefined> {
+    const membership = await this.findMembershipCached(user.id, tenantId);
+    if (!membership || !(await this.isTenantActive(tenantId))) {
+      return undefined;
+    }
+    return { tenantId, tenantRole: capApiTokenTenantRole(user, membership.role as string) ?? undefined };
+  }
+
   /** 403 for a deactivated tenant. */
   private async assertTenantActive(tenantId: string): Promise<void> {
     if (!(await this.isTenantActive(tenantId))) {