@bevel-software/platform-core-backend 0.32.0 → 0.34.0

package/src/modules/mcp/__tests__/read-only-hint.e2e.test.ts

@@ -0,0 +1,213 @@
+import type { Server as HttpServer } from 'node:http';
+import type { AddressInfo } from 'node:net';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import express, { type RequestHandler } from 'express';
+import { afterEach, describe, expect, it } from 'vitest';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import { createMcpRoutes } from '../mcp.routes.js';
+import { McpService } from '../mcp.service.js';
+import { SpillStore } from '../../workspace/index.js';
+import { TOOL_READ_ONLY_SETTING, ToolReadOnlyHints, ToolRegistry, createManualRoutes } from '../../tool-registry/index.js';
+import { toolDef } from '../../tool-helpers/index.js';
+import { createCatalogRevisionRoutes } from '../../../core/catalog-revision.js';
+import { startFakeDownstreamMcpServer, type FakeDownstreamMcpServer } from './fake-downstream-mcp-server.js';
+
+/**
+ * The read-only hint as the HOSTED MCP endpoint lists it, over the real
+ * Streamable-HTTP transport: the real `McpService` discovering the real agent
+ * manual over loopback, with the real hints applied to it. What a client such
+ * as Claude Cowork reads to decide whether a call needs approval.
+ */
+
+const KEY = 'bevel_key_interactive';
+const fakeAuth: RequestHandler = (req, res, next) => {
+  if ((req.headers.authorization ?? '') !== `Bearer ${KEY}`) {
+    res.status(401).json({ error: 'unauthorized' });
+    return;
+  }
+  // An interactive caller (no connection-key id): the full listing, no credential filter.
+  req.userId = 'user-A';
+  next();
+};
+const pass: RequestHandler = (_req, _res, next) => next();
+
+const stops: Array<() => Promise<void>> = [];
+afterEach(async () => {
+  for (const stop of stops.splice(0).reverse()) await stop().catch(() => {});
+});
+
+async function startPlatform(opts: { downstream?: FakeDownstreamMcpServer; catalogRevision?: boolean } = {}) {
+  const registry = new ToolRegistry();
+  registry.registerExternalTool(
+    toolDef({ name: 'read_file', description: 'Read a file.', path: '/api/agent/tools/read_file', inputs: { type: 'object', properties: {} } }),
+  );
+  registry.registerExternalTool(
+    toolDef({
+      name: 'write_file',
+      description: 'Write a file.',
+      path: '/api/agent/tools/write_file',
+      inputs: { type: 'object', properties: {} },
+      tags: ['write'],
+    }),
+  );
+  // One stored row, as the deployment-settings table would hold it.
+  const row = { value: '' };
+  const hints = new ToolReadOnlyHints(registry, {
+    reload: async (key) => (key === TOOL_READ_ONLY_SETTING ? row.value : ''),
+    recordIfAbsent: async (_key, value) => {
+      if (row.value) return false;
+      row.value = value;
+      return true;
+    },
+    swapIfValue: async (_key, expected, next) => {
+      if (row.value !== expected) return false;
+      row.value = next ?? '';
+      return true;
+    },
+  });
+
+  const app = express();
+  app.use(express.json());
+  app.get('/api/agent/all-tools', (_req, res) => {
+    res.json({
+      manuals: [
+        {
+          name: 'KNOWLEDGE_BASE',
+          call_template_type: 'http',
+          http_method: 'GET',
+          url: '${API_URL}/api/agent/utcp',
+          content_type: 'application/json',
+          headers: { Authorization: 'Bearer ${CONNECTION_KEY}' },
+        },
+        // A plugin's MCP server: a tool from the knowledge base, not the platform's.
+        ...(opts.downstream
+          ? [{ name: 'notion', call_template_type: 'mcp', config: { mcpServers: { srv: { transport: 'http', url: opts.downstream.url } } } }]
+          : []),
+      ],
+    });
+  });
+  const httpServer = await new Promise<HttpServer>((resolve) => {
+    const s = app.listen(0, '127.0.0.1', () => resolve(s));
+  });
+  const baseUrl = `http://127.0.0.1:${(httpServer.address() as AddressInfo).port}`;
+  const service = new McpService({
+    loopbackBaseUrl: baseUrl,
+    manualName: 'KNOWLEDGE_BASE',
+    spillStore: new SpillStore(join(tmpdir(), 'bevel-test-spills')),
+    publicFrontendUrl: 'http://localhost:5173',
+    readOnlyOverrides: () => hints.overrides(),
+  });
+  const stub = {} as never;
+  app.use('/api', createMcpRoutes(service, stub, fakeAuth, fakeAuth, stub, stub, stub, ''));
+  app.use('/api', createManualRoutes(registry, pass, undefined, hints));
+  // The route the endpoint keys its cached tool surface by. Served, a listing
+  // reuses the surface it built until the revision moves; absent (404), every
+  // request builds its own. An override does not move it: the hints are
+  // joined on per listing, so the cached surface never holds one.
+  if (opts.catalogRevision) {
+    const asCaller: RequestHandler = (req, _res, next) => {
+      req.toolAuth = { userId: 'user-A' } as never;
+      next();
+    };
+    app.use(
+      '/api',
+      createCatalogRevisionRoutes({
+        toolManuals: { catalogFingerprints: async () => [] },
+        skills: { listSkills: async () => [] },
+        manualAuth: asCaller,
+        resolveUserEmail: async () => 'a@example.test',
+      }),
+    );
+  }
+  stops.push(async () => {
+    service.onSecretsChanged(null);
+    httpServer.closeAllConnections();
+    await new Promise<void>((r) => httpServer.close(() => r()));
+  });
+  return { baseUrl, hints };
+}
+
+async function connect(baseUrl: string): Promise<Client> {
+  const transport = new StreamableHTTPClientTransport(new URL(`${baseUrl}/api/mcp`), {
+    requestInit: { headers: { Authorization: `Bearer ${KEY}` } },
+  });
+  const client = new Client({ name: 'hint-client', version: '0.0.0' }, { capabilities: {} });
+  await client.connect(transport);
+  stops.push(() => client.close());
+  return client;
+}
+
+const annotationsOf = async (client: Client) =>
+  Object.fromEntries((await client.listTools()).tools.map((t) => [t.name, t.annotations]));
+
+describe('the hosted MCP endpoint lists the read-only hint', () => {
+  it('on every platform tool and every meta-tool, and no other annotation', async () => {
+    const { baseUrl } = await startPlatform();
+    expect(await annotationsOf(await connect(baseUrl))).toEqual({
+      list_tools: { readOnlyHint: true },
+      tools_info: { readOnlyHint: true },
+      call_tool_chain: { readOnlyHint: false },
+      read_file: { readOnlyHint: true },
+      write_file: { readOnlyHint: false },
+    });
+  });
+
+  it("lists an admin's change on the client's NEXT tools/list, with no reconnect, and a reset undoes it", async () => {
+    const { baseUrl, hints } = await startPlatform();
+    const client = await connect(baseUrl);
+    expect((await annotationsOf(client)).read_file).toEqual({ readOnlyHint: true });
+
+    await hints.set('read_file', false, '00000000-0000-4000-8000-00000000000a');
+    await hints.set('write_file', true, '00000000-0000-4000-8000-00000000000a');
+    await hints.set('call_tool_chain', true, '00000000-0000-4000-8000-00000000000a');
+    let listed = await annotationsOf(client);
+    expect(listed.read_file).toEqual({ readOnlyHint: false });
+    expect(listed.write_file).toEqual({ readOnlyHint: true });
+    expect(listed.call_tool_chain).toEqual({ readOnlyHint: true });
+
+    for (const name of ['read_file', 'write_file', 'call_tool_chain']) await hints.set(name, null, '00000000-0000-4000-8000-00000000000a');
+    listed = await annotationsOf(client);
+    expect(listed.read_file).toEqual({ readOnlyHint: true });
+    expect(listed.write_file).toEqual({ readOnlyHint: false });
+    expect(listed.call_tool_chain).toEqual({ readOnlyHint: false });
+  });
+
+  it("lists an admin's change and its reset on the next tools/list when the tool surface is cached", async () => {
+    const { baseUrl, hints } = await startPlatform({ catalogRevision: true });
+    const client = await connect(baseUrl);
+    expect((await annotationsOf(client)).read_file).toEqual({ readOnlyHint: true });
+
+    await hints.set('read_file', false, '00000000-0000-4000-8000-00000000000a');
+    await hints.set('write_file', true, '00000000-0000-4000-8000-00000000000a');
+    let listed = await annotationsOf(client);
+    expect(listed.read_file).toEqual({ readOnlyHint: false });
+    expect(listed.write_file).toEqual({ readOnlyHint: true });
+
+    for (const name of ['read_file', 'write_file']) await hints.set(name, null, '00000000-0000-4000-8000-00000000000a');
+    listed = await annotationsOf(client);
+    expect(listed.read_file).toEqual({ readOnlyHint: true });
+    expect(listed.write_file).toEqual({ readOnlyHint: false });
+  });
+
+  it('does not keep an override in the cached surface: one set before the surface is built is undone by its reset', async () => {
+    const { baseUrl, hints } = await startPlatform({ catalogRevision: true });
+    await hints.set('read_file', false, '00000000-0000-4000-8000-00000000000a');
+    const client = await connect(baseUrl);
+    expect((await annotationsOf(client)).read_file).toEqual({ readOnlyHint: false });
+
+    await hints.set('read_file', null, '00000000-0000-4000-8000-00000000000a');
+    expect((await annotationsOf(client)).read_file).toEqual({ readOnlyHint: true });
+  });
+
+  it('leaves a tool from a plugin MCP server unannotated, as before', async () => {
+    const downstream = await startFakeDownstreamMcpServer();
+    stops.push(() => downstream.stop());
+    const { baseUrl } = await startPlatform({ downstream });
+    const tools = (await (await connect(baseUrl)).listTools()).tools;
+    const proxied = tools.find((t) => t.name.endsWith('echo'));
+    expect(proxied).toBeDefined();
+    expect(proxied).not.toHaveProperty('annotations');
+  });
+});

package/src/modules/mcp/index.ts

@@ -0,0 +1,7 @@
+/**
+ * What the mcp module offers the other modules. A consumer outside the
+ * module imports from here, never from the files: they are the module's own
+ * layout and free to move. Export what another module needs; nothing more.
+ */
+export { signAuthRequest } from './oauth/oauth-state.js';
+export type { McpAuthRequestState } from './oauth/oauth-state.js';

package/src/modules/mcp/mcp-auth.middleware.ts

@@ -3,14 +3,13 @@ import { logger } from '../../shared/logging.js';
 
 const log = logger('mcp-auth');
 import { InvalidTokenError } from '@modelcontextprotocol/sdk/server/auth/errors.js';
-import type { AuthService } from '../auth/auth.service.js';
-import { ACCOUNT_DEACTIVATED_MESSAGE, AccountDeactivatedError, AuthBackendError } from '../auth/account-admission.js';
-import type { IExternalApiKeyService } from '../tool-auth/external-api-key.interface.js';
-import type { InternalTokenService } from '../tool-auth/internal-token.service.js';
-import { rejectConnectionKey } from '../tool-auth/connection-key-rejection.js';
+import type { AuthService } from '../auth/index.js';
+import { ACCOUNT_DEACTIVATED_MESSAGE, AccountDeactivatedError, AuthBackendError } from '../auth/index.js';
+import type { IExternalApiKeyService, InternalTokenService } from '../tool-auth/index.js';
+import { rejectConnectionKey } from '../tool-auth/index.js';
 import type { BevelOAuthProvider } from './oauth/bevel-oauth-provider.js';
-import '../tool-auth/external-api-key.interface.js'; // Express Request augmentation (req.externalApiKeyId)
-import '../audit/audit.contract.js'; // Express Request augmentation (req.agentConnectionId)
+import '../tool-auth/index.js'; // Express Request augmentation (req.externalApiKeyId)
+import '../audit/index.js'; // Express Request augmentation (req.agentConnectionId)
 
 /** Which of the four credentials below an MCP request was authenticated with. */
 export type McpCallerKind = 'key' | 'oauth' | 'internal' | 'session';
@@ -25,6 +24,13 @@ declare global {
        * the page its call comes from (`X-Bevel-Page`).
        */
       mcpCallerKind?: McpCallerKind;
+      /**
+       * The agent configuration the MCP caller's credential connects as — a key's
+       * `api_tokens.agent_path`, an agent connection's
+       * `agent_connections.agent_path`, or the one an exchanged grant
+       * carries. Unset is Everything.
+       */
+      mcpAgentPath?: string;
     }
   }
 }
@@ -111,6 +117,7 @@ export function createMcpAuthMiddleware(
         req.userId = resolved.user.id;
         req.userEmail = resolved.user.email;
         req.externalApiKeyId = resolved.tokenId;
+        if (resolved.agentPath) req.mcpAgentPath = resolved.agentPath;
         req.mcpCallerKind = 'key';
         next();
         return;
@@ -138,6 +145,9 @@ export function createMcpAuthMiddleware(
         if (typeof info.extra?.connectionId === 'string') {
           req.agentConnectionId = info.extra.connectionId;
         }
+        if (typeof info.extra?.agentPath === 'string' && info.extra.agentPath) {
+          req.mcpAgentPath = info.extra.agentPath;
+        }
         if (!req.userId) {
           unauthorized(res, 'Invalid access token');
           return;
@@ -218,10 +228,13 @@ export function createMcpAuthMiddleware(
       // stamped too (throttled, off the request's path), so the Audit log's
       // "last used" follows the local server's calls, not only its sign-ins.
       // Carried on the request so those calls are logged under the agent.
+      // The same read answers what the connection is made as NOW: a
+      // re-consent changes the row, not the token, so the row's choice is
+      // the one served, never the one the token was minted with.
       if (claim.connectionId) {
-        let live: boolean;
+        let live: { agentPath: string | null } | null;
         try {
-          live = await oauthProvider.isConnectionLive(claim.connectionId);
+          live = await oauthProvider.liveConnectionChoice(claim.connectionId);
         } catch (err) {
           log.error('agent-connection check failed:', { err });
           res.status(500).json({ error: 'Authentication backend unavailable' });
@@ -233,6 +246,9 @@ export function createMcpAuthMiddleware(
         }
         oauthProvider.noteConnectionUse(claim.connectionId);
         req.agentConnectionId = claim.connectionId;
+        if (live.agentPath) req.mcpAgentPath = live.agentPath;
+      } else if (claim.agentPath) {
+        req.mcpAgentPath = claim.agentPath;
       }
       req.mcpCallerKind = 'internal';
       next();

package/src/modules/mcp/mcp.routes.ts

@@ -9,15 +9,15 @@ import {
   InvalidTokenLabelError,
   TokenNotFoundError,
   TokenStillActiveError,
-} from '../tool-auth/external-api-key.errors.js';
-import type { IExternalApiKeyService } from '../tool-auth/external-api-key.interface.js';
-import type { InternalTokenService } from '../tool-auth/internal-token.service.js';
+} from '../tool-auth/index.js';
+import type { IExternalApiKeyService, InternalTokenService, ILlmUsageMeter } from '../tool-auth/index.js';
 import { MCP_LOOPBACK_TOKEN_TTL_MS, type McpService } from './mcp.service.js';
 import type { BevelOAuthProvider } from './oauth/bevel-oauth-provider.js';
-import type { ILlmUsageMeter } from '../tool-auth/llm-usage-meter.js';
-import '../tool-auth/external-api-key.interface.js'; // req.externalApiKeyId augmentation
+import '../tool-auth/index.js'; // req.externalApiKeyId augmentation
 import './mcp-auth.middleware.js'; // req.mcpCallerKind augmentation
 import { isPagePath } from '../audit/index.js';
+import type { IAgentScopeResolver } from '../agent-scope/index.js';
+import { NOT_AN_AGENT_CHOICE } from './oauth/oauth-consent.routes.js';
 
 /** Pull the raw bearer token off an already-authenticated request. */
 function extractBearer(req: Request): string {
@@ -106,6 +106,11 @@ export function createMcpRoutes(
   // RFC 9728 pointer carried on this router's own 401 challenges (the
   // local-token exchange), same value McpAuthMiddleware advertises.
   resourceMetadataUrl: string,
+  /**
+   * The "Connect as" choices a key may be minted as (`modules/agent-scope`).
+   * Absent: keys are minted as Everything only, and no choices are listed.
+   */
+  agents?: Pick<IAgentScopeResolver, 'listChoices' | 'choosable'>,
 ): express.Router {
   const router = express.Router();
 
@@ -155,6 +160,10 @@ export function createMcpRoutes(
           // exchanged grant; undefined for keys/JWTs) — the Audit log's other
           // principal, resolved per request like the key id.
           connectionId: req.agentConnectionId ?? null,
+          // The agent configuration the credential connects as (a key's, an agent
+          // connection's, or the one an exchanged grant carries); null is
+          // Everything. Resolved per request like the ids above.
+          ...(req.mcpAgentPath ? { agentPath: req.mcpAgentPath } : {}),
           // The proxy authenticates its loopback calls with the SAME bearer the
           // client used here, so it acts on the request exactly as the caller would.
           bearer: extractBearer(req),
@@ -235,6 +244,17 @@ export function createMcpRoutes(
 
   // ── Connection-key management (JWT-only) ───────────────────────────────
 
+  // The agents a key may be minted as — the same choices the OAuth consent
+  // step offers below Everything, for the key-mint dialog.
+  router.get('/mcp/agent-choices', jwtAuthMiddleware, async (req, res) => {
+    try {
+      res.json({ agents: agents && req.userEmail ? await agents.listChoices(req.userEmail) : [] });
+    } catch (err) {
+      log.error('listing the agents to connect as failed:', { err });
+      res.status(500).json({ error: 'Failed to list the agents' });
+    }
+  });
+
   router.get('/mcp/external-api-keys', jwtAuthMiddleware, async (req, res) => {
     try {
       const tokens = await externalApiKeyService.listForUser(req.userId!);
@@ -266,12 +286,23 @@ export function createMcpRoutes(
         res.status(400).json({ error: 'JSON body required' });
         return;
       }
-      const { label } = req.body as { label?: string };
+      const { label, agentPath: asked } = req.body as { label?: string; agentPath?: unknown };
       if (!label) {
         res.status(400).json({ error: 'label is required' });
         return;
       }
-      const minted = await externalApiKeyService.mint(req.userId!, label);
+      // "Connect as", exactly as on the consent step: absent, null or empty is
+      // Everything; anything else must be an agent the owner may choose now.
+      let agentPath: string | null = null;
+      if (asked !== undefined && asked !== null && asked !== '') {
+        agentPath =
+          typeof asked === 'string' && agents && req.userEmail ? await agents.choosable(req.userEmail, asked) : null;
+        if (agentPath === null) {
+          res.status(400).json({ error: NOT_AN_AGENT_CHOICE });
+          return;
+        }
+      }
+      const minted = await externalApiKeyService.mint(req.userId!, label, agentPath ? { agentPath } : {});
       // The plaintext field is the *only* read path for the raw key. The
       // frontend must store it nowhere — it shows the dialog once and then
       // discards. Subsequent fetches return only `summary`-shaped rows.
@@ -430,8 +461,11 @@ export function createMcpRoutes(
       // The grant's agent connection rides along, so the local server's
       // calls with this token stay attributed to the agent in the Audit log.
       const connectionId = typeof info.extra?.connectionId === 'string' ? info.extra.connectionId : undefined;
+      // So does the agent the connection was made as: the local server's
+      // calls see the same narrowed surface as the hosted endpoint's.
+      const agentPath = typeof info.extra?.agentPath === 'string' && info.extra.agentPath ? info.extra.agentPath : undefined;
       const minted = internalTokens.mint(
-        { userId, externalProxy: true, ...(connectionId ? { connectionId } : {}) },
+        { userId, externalProxy: true, ...(connectionId ? { connectionId } : {}), ...(agentPath ? { agentPath } : {}) },
         ttlMs,
       );
       // The ACTUAL lifetime, not the constant — the caller schedules its