@lenne.tech/nest-server 11.25.6 → 11.26.0

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

@@ -0,0 +1,169 @@
+import { Injectable, Logger } from '@nestjs/common';
+
+import { RoleEnum } from '../../../common/enums/role.enum';
+import { AiToolContext, AiToolResult, IAiTool } from '../interfaces/ai-tool.interface';
+import { AiToolRegistry } from '../tools/ai-tool.registry';
+
+/**
+ * The MCP-client side of `@modelcontextprotocol/sdk` that we need to talk to. Kept
+ * structurally compatible so projects can pass either the real SDK `Client` or a
+ * test double / lightweight wrapper.
+ */
+export interface McpLikeClient {
+  callTool(req: {
+    arguments?: Record<string, any>;
+    name: string;
+  }): Promise<{ content?: { text?: string; type?: string }[]; isError?: boolean }>;
+  close?(): Promise<void> | void;
+  listTools(): Promise<{ tools: { description?: string; inputSchema?: any; name: string }[] }>;
+}
+
+/**
+ * Configuration of an external MCP server we connect to as a client.
+ */
+export interface AiMcpClientConfig {
+  /** Connected MCP client instance. Use `client` to pass a ready-made client (recommended). */
+  client?: McpLikeClient;
+  /** Roles required to see the imported tools. @default [S_USER] */
+  defaultRoles?: (RoleEnum | string)[];
+  /** Logical name; becomes the namespace prefix `<name>_<tool>` for imported tools. */
+  name: string;
+}
+
+/**
+ * Wires an external MCP server into our {@link AiToolRegistry}: lists the server's
+ * tools and registers each one as a wrapper tool that calls back to the MCP
+ * client's `callTool`. Imported tools are namespaced as `<clientName>_<toolName>`
+ * (avoids collisions across clients and with locally registered tools).
+ *
+ * The wrapper passes the original AiToolContext to the registry filter so role
+ * gating still applies — but the underlying CALL goes to the external server,
+ * whose own security model also applies. By default we mark imported tools as
+ * `mutating: true` (conservative) — they require confirmation. A project can
+ * override `defaultRoles` / mutating flag via the config.
+ *
+ * Override this class for project-specific connection logic (stdio spawn /
+ * StreamableHTTP / SSE / OAuth) via `CoreModule.forRoot(env, { ai: { mcpClientService } })`.
+ */
+@Injectable()
+export class CoreAiMcpClientService {
+  protected readonly logger = new Logger(CoreAiMcpClientService.name);
+  protected readonly registered = new Map<string, { client: McpLikeClient; toolNames: string[] }>();
+
+  constructor(protected readonly registry: AiToolRegistry) {}
+
+  /**
+   * Discover the external server's tools and register each one as a namespaced
+   * wrapper in the global tool registry. Idempotent on `name` — re-registers if
+   * called again with the same name (drops the previous tools first).
+   */
+  async registerExternalClient(config: AiMcpClientConfig): Promise<string[]> {
+    if (!config?.name || !config?.client) {
+      throw new Error('McpClientService.registerExternalClient requires { name, client }');
+    }
+    // Drop previous registration under this name.
+    await this.unregisterExternalClient(config.name);
+
+    let discovered: { tools: { description?: string; inputSchema?: any; name: string }[] };
+    try {
+      discovered = await config.client.listTools();
+    } catch (err) {
+      this.logger.warn(`MCP listTools for "${config.name}" failed: ${(err as Error).message}`);
+      return [];
+    }
+
+    const registered: string[] = [];
+    for (const t of discovered?.tools || []) {
+      if (!t?.name) {
+        continue;
+      }
+      const ns = `${config.name}_${t.name}`;
+      const wrapper: IAiTool = this.buildWrapperTool(ns, t, config);
+      this.registry.register(wrapper);
+      registered.push(ns);
+    }
+    this.registered.set(config.name, { client: config.client, toolNames: registered });
+    if (registered.length) {
+      this.logger.log(
+        `Registered ${registered.length} tool(s) from MCP client "${config.name}": ${registered.join(', ')}`,
+      );
+    }
+    return registered;
+  }
+
+  /** Tear down a previously registered MCP client and remove its tools. */
+  async unregisterExternalClient(name: string): Promise<void> {
+    const entry = this.registered.get(name);
+    if (!entry) {
+      return;
+    }
+    for (const toolName of entry.toolNames) {
+      try {
+        this.registry.unregister(toolName);
+      } catch {
+        // best-effort
+      }
+    }
+    try {
+      await entry.client.close?.();
+    } catch {
+      // best-effort
+    }
+    this.registered.delete(name);
+  }
+
+  /** Build the IAiTool wrapper for one imported MCP tool. */
+  protected buildWrapperTool(
+    namespacedName: string,
+    descriptor: { description?: string; inputSchema?: any; name: string },
+    config: AiMcpClientConfig,
+  ): IAiTool {
+    const client = config.client!;
+    const tool: IAiTool = {
+      description: descriptor.description || `(External MCP tool from "${config.name}")`,
+      // Conservative default for external tools — they require confirmation until
+      // the project explicitly opts out via a hook or scoped policy.
+      mutating: true,
+      name: namespacedName,
+      parameters: descriptor.inputSchema || { properties: {}, type: 'object' },
+      roles: config.defaultRoles || [RoleEnum.S_USER],
+      // eslint-disable-next-line @typescript-eslint/no-unused-vars
+      execute: async (args: Record<string, any>, _context: AiToolContext): Promise<AiToolResult> => {
+        try {
+          const res = await client.callTool({ arguments: args ?? {}, name: descriptor.name });
+          if (res?.isError) {
+            return {
+              message: this.extractText(res) || `MCP tool "${descriptor.name}" reported an error.`,
+              success: false,
+            };
+          }
+          const text = this.extractText(res);
+          let data: unknown = text;
+          if (text) {
+            try {
+              data = JSON.parse(text);
+            } catch {
+              // keep raw text
+            }
+          }
+          return { data, success: true };
+        } catch (err) {
+          return { message: (err as Error).message, success: false };
+        }
+      },
+    };
+    return tool;
+  }
+
+  /** Concatenate text parts of an MCP tool result. */
+  protected extractText(res: { content?: { text?: string; type?: string }[] } | undefined): string {
+    if (!res?.content?.length) {
+      return '';
+    }
+    return res.content
+      .filter((p) => p?.text)
+      .map((p) => p.text!)
+      .join('\n')
+      .trim();
+  }
+}

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

@@ -0,0 +1,445 @@
+import { Injectable, Logger, OnModuleInit } from '@nestjs/common';
+import { InjectConnection } from '@nestjs/mongoose';
+import { createHash, createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
+import { Connection } from 'mongoose';
+
+import { isProductionLikeEnv } from '../../../common/helpers/cookies.helper';
+import { ConfigService } from '../../../common/services/config.service';
+
+/**
+ * Stored OAuth client (dynamically registered).
+ *
+ * For confidential clients (i.e. clients that registered with a
+ * `token_endpoint_auth_method` other than `'none'`), `client_secret` is
+ * persisted and returned here so the SDK's `clientAuth` middleware can verify
+ * it. Dropping the secret from the returned shape would silently downgrade
+ * confidential clients to public clients (the SDK's secret-verification branch
+ * is gated by `if (client.client_secret)`).
+ */
+export interface AiMcpOAuthClient {
+  client_id: string;
+  client_name?: string;
+  client_secret?: string;
+  client_secret_expires_at?: number;
+  redirect_uris: string[];
+  token_endpoint_auth_method?: string;
+}
+
+/**
+ * Decoded MCP access-token payload.
+ */
+export interface AiMcpAccessTokenPayload {
+  cid: string;
+  exp: number;
+  sub: string;
+  type: 'mcp_access';
+}
+
+/**
+ * Security core for the MCP OAuth 2.1 flow.
+ *
+ * Implements the security-critical primitives — HMAC-signed access tokens
+ * (constant-time verification), PKCE (S256) verification — and MongoDB-backed
+ * stores for dynamically registered clients, authorization codes (TTL) and
+ * refresh tokens. These power the SDK `OAuthServerProvider` returned by
+ * {@link buildOAuthProvider}, which `mcpAuthRouter` mounts (see
+ * `mountAiMcpOAuth`). The interactive consent/authorize flow is a thin layer on
+ * top of these primitives and is documented in the integration checklist.
+ *
+ * Token format: `base64url(JSON payload).base64url(HMAC-SHA256)`.
+ */
+@Injectable()
+export class CoreAiMcpOAuthService implements OnModuleInit {
+  protected readonly logger = new Logger(CoreAiMcpOAuthService.name);
+
+  /** Native MongoDB collections (no Mongoose schema needed for OAuth artifacts). */
+  protected readonly clientsCollection = 'aiMcpOAuthClients';
+  protected readonly codesCollection = 'aiMcpOAuthCodes';
+  protected readonly refreshCollection = 'aiMcpOAuthRefreshTokens';
+
+  private indexesEnsured = false;
+  private warnedSecret = false;
+
+  constructor(@InjectConnection() protected readonly connection: Connection) {}
+
+  /**
+   * Fail loud at boot in production/staging when the OAuth 2.1 layer is enabled
+   * (`ai.mcp.oauth`) but no signing secret is configured — otherwise tokens would be
+   * signed with a public, insecure development default.
+   */
+  onModuleInit(): void {
+    this.assertProductionSafe();
+  }
+
+  /** Throw in production/staging when OAuth is enabled but no secret is configured. */
+  assertProductionSafe(): void {
+    if (this.oauthEnabled() && isProductionLikeEnv(ConfigService.get<string>('env')) && !this.resolveSecret()) {
+      throw new Error(
+        'AI MCP OAuth signing secret is required in production/staging when ai.mcp.oauth is enabled, ' +
+          'but none is set (ai.mcp.oauthSecret / ai.encryptionSecret / NSC__AI__ENCRYPTION_SECRET / ' +
+          'SECRETS_ENCRYPTION_KEY). Set a random 32+ char value.',
+      );
+    }
+  }
+
+  /** Whether the OAuth 2.1 layer is enabled via `ai.mcp.oauth`. */
+  protected oauthEnabled(): boolean {
+    const mcp = ConfigService.get<{ oauth?: boolean }>('ai.mcp');
+    return typeof mcp === 'object' && mcp?.oauth === true;
+  }
+
+  /** Resolve the HMAC signing secret from config/env (no dev fallback). */
+  protected resolveSecret(): string | undefined {
+    return (
+      ConfigService.get<string>('ai.mcp.oauthSecret') ||
+      ConfigService.get<string>('ai.encryptionSecret') ||
+      process.env.NSC__AI__ENCRYPTION_SECRET ||
+      process.env.SECRETS_ENCRYPTION_KEY
+    );
+  }
+
+  // ===================================================================================================================
+  // Security primitives (unit-tested)
+  // ===================================================================================================================
+
+  /**
+   * Sign an access token for a user + client with a TTL (seconds).
+   */
+  signAccessToken(userId: string, clientId: string, ttlSeconds = 3600): string {
+    const payload: AiMcpAccessTokenPayload = {
+      cid: clientId,
+      exp: Math.floor(Date.now() / 1000) + ttlSeconds,
+      sub: userId,
+      type: 'mcp_access',
+    };
+    const payloadStr = Buffer.from(JSON.stringify(payload)).toString('base64url');
+    return `${payloadStr}.${this.hmac(payloadStr)}`;
+  }
+
+  /**
+   * Verify an access token's signature and expiry; returns the payload or null.
+   */
+  verifyAccessToken(token: string): AiMcpAccessTokenPayload | null {
+    if (!token || !token.includes('.')) {
+      return null;
+    }
+    const [payloadStr, signature] = token.split('.');
+    if (!payloadStr || !signature) {
+      return null;
+    }
+    const expected = this.hmac(payloadStr);
+    if (!this.safeEqual(signature, expected)) {
+      return null;
+    }
+    try {
+      const payload = JSON.parse(Buffer.from(payloadStr, 'base64url').toString('utf8')) as AiMcpAccessTokenPayload;
+      if (payload.type !== 'mcp_access' || payload.exp <= Math.floor(Date.now() / 1000)) {
+        return null;
+      }
+      return payload;
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Verify a PKCE code verifier against a stored S256 challenge.
+   */
+  verifyPkce(verifier: string, challenge: string, method = 'S256'): boolean {
+    if (!verifier || !challenge) {
+      return false;
+    }
+    if (method !== 'S256') {
+      // Only S256 is accepted (plain is insecure).
+      return false;
+    }
+    const computed = createHash('sha256').update(verifier).digest('base64url');
+    return this.safeEqual(computed, challenge);
+  }
+
+  /**
+   * Generate a cryptographically secure random id/token.
+   */
+  generateId(bytes = 32): string {
+    return randomBytes(bytes).toString('base64url');
+  }
+
+  // ===================================================================================================================
+  // Stores (MongoDB)
+  // ===================================================================================================================
+
+  /**
+   * Register a dynamic OAuth client.
+   */
+  async registerClient(client: AiMcpOAuthClient): Promise<AiMcpOAuthClient> {
+    await this.ensureIndexes();
+    await this.db()
+      .collection(this.clientsCollection)
+      .insertOne({ ...client, createdAt: new Date() });
+    return client;
+  }
+
+  /**
+   * Look up a registered client.
+   *
+   * Returns `client_secret` and `client_secret_expires_at` when present so the
+   * SDK's `clientAuth` middleware can verify the secret on token-endpoint
+   * requests (`if (client.client_secret) { …verify… }`). Public clients
+   * (registered with `token_endpoint_auth_method: 'none'`) have no secret and
+   * the verification branch is skipped — PKCE protects the auth-code flow.
+   */
+  async getClient(clientId: string): Promise<AiMcpOAuthClient | null> {
+    const doc = await this.db().collection(this.clientsCollection).findOne({ client_id: clientId });
+    if (!doc) {
+      return null;
+    }
+    return {
+      client_id: doc.client_id,
+      client_name: doc.client_name,
+      client_secret: doc.client_secret,
+      client_secret_expires_at: doc.client_secret_expires_at,
+      redirect_uris: doc.redirect_uris,
+      token_endpoint_auth_method: doc.token_endpoint_auth_method,
+    };
+  }
+
+  /**
+   * Persist an authorization code with its PKCE challenge (TTL 10 minutes).
+   */
+  async saveAuthorizationCode(
+    code: string,
+    data: { clientId: string; codeChallenge: string; userId: string },
+  ): Promise<void> {
+    await this.ensureIndexes();
+    await this.db().collection(this.codesCollection).insertOne({
+      clientId: data.clientId,
+      code,
+      codeChallenge: data.codeChallenge,
+      createdAt: new Date(),
+      userId: data.userId,
+    });
+  }
+
+  /**
+   * Read an authorization code WITHOUT deleting it (for PKCE challenge lookup).
+   */
+  async getAuthorizationCode(
+    code: string,
+  ): Promise<{ clientId: string; codeChallenge: string; userId: string } | null> {
+    const doc = await this.db().collection(this.codesCollection).findOne({ code });
+    return doc ? { clientId: doc.clientId, codeChallenge: doc.codeChallenge, userId: doc.userId } : null;
+  }
+
+  /**
+   * Consume (read + delete) an authorization code. One-time use.
+   */
+  async consumeAuthorizationCode(
+    code: string,
+  ): Promise<{ clientId: string; codeChallenge: string; userId: string } | null> {
+    const doc = await this.db().collection(this.codesCollection).findOneAndDelete({ code });
+    const value = (doc as any)?.value ?? doc; // driver version compatibility
+    if (!value) {
+      return null;
+    }
+    return { clientId: value.clientId, codeChallenge: value.codeChallenge, userId: value.userId };
+  }
+
+  /**
+   * Issue a refresh token for a user + client.
+   */
+  async issueRefreshToken(userId: string, clientId: string): Promise<string> {
+    await this.ensureIndexes();
+    const token = this.generateId();
+    await this.db().collection(this.refreshCollection).insertOne({ clientId, createdAt: new Date(), token, userId });
+    return token;
+  }
+
+  /**
+   * Rotate a refresh token: validate, delete, issue a new one. Returns the user/client.
+   *
+   * The `clientId` parameter is REQUIRED — refresh tokens are bound to the
+   * issuing client per OAuth 2.1 §4.13.2 / §7.4. Looking up the token alone
+   * would let a different client present a stolen refresh token and obtain an
+   * access token for the original user's subject (impersonation). The
+   * `findOneAndDelete({ token, clientId })` query enforces the binding atomically.
+   */
+  async rotateRefreshToken(
+    token: string,
+    clientId: string,
+  ): Promise<{ clientId: string; newToken: string; userId: string } | null> {
+    if (!token || !clientId) {
+      return null;
+    }
+    const doc = await this.db().collection(this.refreshCollection).findOneAndDelete({ clientId, token });
+    const value = (doc as any)?.value ?? doc;
+    if (!value) {
+      return null;
+    }
+    const newToken = await this.issueRefreshToken(value.userId, value.clientId);
+    return { clientId: value.clientId, newToken, userId: value.userId };
+  }
+
+  /**
+   * Load the minimal user shape ({ id, roles }) for a verified OAuth subject from
+   * the `users` collection (read-only). Enough for tool role-filtering + ownership.
+   */
+  async loadUser(userId: string): Promise<{ id: string; roles: string[] } | null> {
+    try {
+      const { ObjectId } = await import('mongodb');
+      const query = ObjectId.isValid(userId) ? { _id: new ObjectId(userId) } : { _id: userId as any };
+      const doc = await this.db()
+        .collection('users')
+        .findOne(query, { projection: { roles: 1 } });
+      if (!doc) {
+        return null;
+      }
+      return { id: userId, roles: Array.isArray(doc.roles) ? doc.roles : [] };
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Build an SDK-compatible `OAuthServerProvider` from the primitives + stores.
+   *
+   * The machine-to-machine methods (clients store, PKCE challenge lookup, code +
+   * refresh exchange, access-token verification) are fully implemented. The
+   * interactive {@link authorizeConsent} (browser login/consent) is overridable —
+   * a consumer wires it to its own login + consent UI (see INTEGRATION-CHECKLIST).
+   */
+  buildOAuthProvider(accessTtlSeconds = 3600): Record<string, any> {
+    return {
+      authorize: (client: any, params: any, res: any) => this.authorizeConsent(client, params, res),
+      challengeForAuthorizationCode: async (_client: any, authorizationCode: string) => {
+        const stored = await this.getAuthorizationCode(authorizationCode);
+        return stored?.codeChallenge ?? '';
+      },
+      clientsStore: {
+        getClient: (clientId: string) => this.getClient(clientId),
+        registerClient: (client: AiMcpOAuthClient) => this.registerClient(client),
+      },
+      exchangeAuthorizationCode: async (client: any, authorizationCode: string) => {
+        const stored = await this.consumeAuthorizationCode(authorizationCode);
+        if (!stored || stored.clientId !== client.client_id) {
+          throw new Error('invalid_grant');
+        }
+        return {
+          access_token: this.signAccessToken(stored.userId, stored.clientId, accessTtlSeconds),
+          expires_in: accessTtlSeconds,
+          refresh_token: await this.issueRefreshToken(stored.userId, stored.clientId),
+          token_type: 'Bearer',
+        };
+      },
+      exchangeRefreshToken: async (client: any, refreshToken: string) => {
+        // Bind the rotating refresh token to the calling client (OAuth 2.1
+        // §4.13.2 / §7.4). Without this check, a different client could present
+        // a stolen refresh token and obtain an access token for the original
+        // user's subject. `rotateRefreshToken` enforces the binding atomically
+        // via `findOneAndDelete({ token, clientId })`.
+        const callerClientId = client?.client_id;
+        if (!callerClientId) {
+          throw new Error('invalid_client');
+        }
+        const rotated = await this.rotateRefreshToken(refreshToken, callerClientId);
+        if (!rotated) {
+          throw new Error('invalid_grant');
+        }
+        return {
+          access_token: this.signAccessToken(rotated.userId, rotated.clientId, accessTtlSeconds),
+          expires_in: accessTtlSeconds,
+          refresh_token: rotated.newToken,
+          token_type: 'Bearer',
+        };
+      },
+      verifyAccessToken: async (token: string) => {
+        const payload = this.verifyAccessToken(token);
+        if (!payload) {
+          throw new Error('invalid_token');
+        }
+        return { clientId: payload.cid, extra: { userId: payload.sub }, scopes: [], token };
+      },
+    };
+  }
+
+  /**
+   * Interactive authorize/consent step. Override to integrate your login + consent
+   * UI: authenticate the user, then call {@link saveAuthorizationCode} and redirect
+   * to `redirect_uri?code=...&state=...`. Default: not implemented.
+   */
+  protected async authorizeConsent(_client: any, _params: any, _res: any): Promise<void> {
+    throw new Error(
+      'authorizeConsent is not implemented — override CoreAiMcpOAuthService.authorizeConsent to wire your login/consent UI.',
+    );
+  }
+
+  // ===================================================================================================================
+  // Helpers
+  // ===================================================================================================================
+
+  /**
+   * Compute the HMAC-SHA256 of a payload string (base64url).
+   */
+  protected hmac(payloadStr: string): string {
+    return createHmac('sha256', this.getSecret()).update(payloadStr).digest('base64url');
+  }
+
+  /**
+   * Constant-time string comparison (avoids timing attacks on token/PKCE checks).
+   */
+  protected safeEqual(a: string, b: string): boolean {
+    const bufA = Buffer.from(a);
+    const bufB = Buffer.from(b);
+    if (bufA.length !== bufB.length) {
+      return false;
+    }
+    return timingSafeEqual(bufA, bufB);
+  }
+
+  /**
+   * Resolve the HMAC secret (same sources as AiCryptoService; dedicated override
+   * via `ai.mcp.oauthSecret`).
+   */
+  protected getSecret(): string {
+    const raw = this.resolveSecret();
+    if (!raw) {
+      if (!this.warnedSecret) {
+        this.logger.warn(
+          'No AI MCP OAuth secret set — using an insecure development default. Set ai.mcp.oauthSecret ' +
+            '(or ai.encryptionSecret / NSC__AI__ENCRYPTION_SECRET) to a random 32+ char value in production.',
+        );
+        this.warnedSecret = true;
+      }
+      return 'lt-nest-server-ai-mcp-oauth-dev-only-insecure-default';
+    }
+    return raw;
+  }
+
+  /**
+   * Native MongoDB database handle.
+   */
+  protected db() {
+    if (!this.connection.db) {
+      throw new Error('MongoDB connection not available for MCP OAuth');
+    }
+    return this.connection.db;
+  }
+
+  /**
+   * Ensure TTL + unique indexes on the OAuth collections (once).
+   */
+  protected async ensureIndexes(): Promise<void> {
+    if (this.indexesEnsured) {
+      return;
+    }
+    this.indexesEnsured = true;
+    try {
+      await this.db().collection(this.clientsCollection).createIndex({ client_id: 1 }, { unique: true });
+      // Authorization codes expire after 10 minutes.
+      await this.db().collection(this.codesCollection).createIndex({ createdAt: 1 }, { expireAfterSeconds: 600 });
+      await this.db().collection(this.codesCollection).createIndex({ code: 1 }, { unique: true });
+      await this.db().collection(this.refreshCollection).createIndex({ token: 1 }, { unique: true });
+    } catch (err) {
+      this.logger.warn(`Could not ensure MCP OAuth indexes: ${(err as Error).message}`);
+    }
+  }
+}