@bevel-software/platform-core-backend 0.33.0 → 0.35.0

package/src/modules/tool-manuals/mcp-json-discovery.ts

@@ -90,39 +90,62 @@ const SERVER_NAME_RE = /^[a-z0-9][a-z0-9_-]*$/;
  * silently vanishes from the catalog the moment its edit lands.
  */
 export function validatedVariables(raw: unknown): ToolVariable[] | null {
-  if (raw === undefined) return [];
-  if (!Array.isArray(raw)) return null;
+  const verdict = judgeVariables(raw);
+  return verdict.ok ? verdict.variables : null;
+}
+
+/**
+ * {@link validatedVariables} with the reason a declaration was refused. The
+ * reason locates the entry by its position (`` `variables[2] ``), never by
+ * the name it declared or any other value the author wrote — the `.tool`
+ * parser's discipline (`describeManualFault`): passing `[A-Za-z0-9_]+` makes
+ * a string a legal identifier, not one this process may repeat. The reason
+ * reaches logs and, for a sign-in start on the server, the person signing in.
+ */
+function judgeVariables(
+  raw: unknown,
+): { ok: true; variables: ToolVariable[] } | { ok: false; reason: string } {
+  const no = (reason: string) => ({ ok: false as const, reason });
+  if (raw === undefined) return { ok: true, variables: [] };
+  if (!Array.isArray(raw)) return no('`variables` must be a list');
   const out: ToolVariable[] = [];
   const declared = new Set<string>();
-  for (const entry of raw) {
-    if (!isRecord(entry)) return null;
-    if (typeof entry.name !== 'string' || !/^[A-Za-z0-9_]+$/.test(entry.name)) return null;
+  for (const [i, entry] of raw.entries()) {
+    const at = `\`variables[${i}]`;
+    if (!isRecord(entry)) return no(`${at}\` must be an object`);
+    if (typeof entry.name !== 'string' || !/^[A-Za-z0-9_]+$/.test(entry.name)) {
+      return no(`${at}.name\` must match [A-Za-z0-9_]+`);
+    }
     // The `.tool` parser's declaration rules, at this file's grain: a
     // platform-seeded name may not be re-declared (it would shadow the
     // seeding), and a duplicate would make later scope resolution depend on
     // declaration order.
-    if (RESERVED_VARIABLE_NAMES.includes(entry.name) || declared.has(entry.name)) return null;
+    if (RESERVED_VARIABLE_NAMES.includes(entry.name)) return no(`${at}.name\` is reserved for platform seeding`);
+    if (declared.has(entry.name)) return no(`${at}.name\` duplicates an earlier entry's`);
     declared.add(entry.name);
     const scope = entry.scope ?? 'admin';
-    if (scope !== 'admin' && scope !== 'user') return null;
+    if (scope !== 'admin' && scope !== 'user') return no(`${at}.scope\` must be \`admin\` or \`user\``);
     let oauth: ToolVariable['oauth'];
     if (entry.oauth !== undefined) {
       // OAuth is inherently per-caller (same rule the `.tool` parser
       // enforces): an admin-shared OAuth token would leak one user's token
       // to all callers.
-      if (!isRecord(entry.oauth) || scope !== 'user') return null;
+      if (!isRecord(entry.oauth)) return no(`${at}.oauth\` must be an object`);
+      if (scope !== 'user') return no(`${at}\` has \`oauth\`, so its \`scope\` must be \`user\``);
       const o = entry.oauth;
       // Confidential material never loads from a file, on either declaration
       // surface: the `.tool` parser throws on these keys, and silently
       // dropping one here would leave a plugin.json carrying a secret that
       // "worked" — the file is portable package data, readable by every
       // client that loads the plugin.
-      if (o.clientSecret !== undefined || o.client_secret !== undefined || o.secret !== undefined) return null;
+      if (o.clientSecret !== undefined || o.client_secret !== undefined || o.secret !== undefined) {
+        return no(`${at}.oauth\` may not carry a client secret — it is set through the protected client-secret route`);
+      }
       // `clientId` is trimmed and must be non-empty, exactly as the `.tool`
       // parser requires: a whitespace-only value would pass discovery and
       // then fail the owner's client-secret setup with "clientId is
       // required" — an error at the wrong surface, long after the save.
-      if (typeof o.clientId !== 'string' || !o.clientId.trim()) return null;
+      if (typeof o.clientId !== 'string' || !o.clientId.trim()) return no(`${at}.oauth.clientId\` is required`);
       // The endpoints are OPTIONAL here, unlike in a `.tool`: an MCP server
       // publishes its authorization-server metadata, so a declaration that
       // names only the client id is completed at scan time. Both or neither
@@ -137,33 +160,38 @@ export function validatedVariables(raw: unknown): ToolVariable[] | null {
       const authorizationUrl = optionalUrl(o.authorizationUrl);
       const tokenUrl = optionalUrl(o.tokenUrl);
       const resource = optionalUrl(o.resource);
-      if (authorizationUrl === null || tokenUrl === null || resource === null) return null;
-      if ((authorizationUrl === undefined) !== (tokenUrl === undefined)) return null;
+      if (authorizationUrl === null || tokenUrl === null || resource === null) {
+        return no(`${at}.oauth\` URLs must be strings`);
+      }
+      if ((authorizationUrl === undefined) !== (tokenUrl === undefined)) {
+        return no(`${at}.oauth\` must declare both \`authorizationUrl\` and \`tokenUrl\`, or neither`);
+      }
       // The same https + SSRF gate the `.tool` parser runs on these URLs: a
       // sign-in or token exchange aimed at an internal host is a declaration
       // this surface must refuse exactly like the other one does. `resource`
       // is never fetched, but it names the remote server — same bar.
       try {
         if (authorizationUrl !== undefined) {
-          assertSafeFetchUrl(authorizationUrl, { requireHttps: true, label: `${entry.name} oauth.authorizationUrl` });
-          assertSafeFetchUrl(tokenUrl!, { requireHttps: true, label: `${entry.name} oauth.tokenUrl` });
+          assertSafeFetchUrl(authorizationUrl, { requireHttps: true, label: `${at}.oauth.authorizationUrl\`` });
+          assertSafeFetchUrl(tokenUrl!, { requireHttps: true, label: `${at}.oauth.tokenUrl\`` });
         }
         if (resource !== undefined) {
-          assertSafeFetchUrl(resource, { requireHttps: true, label: `${entry.name} oauth.resource` });
+          assertSafeFetchUrl(resource, { requireHttps: true, label: `${at}.oauth.resource\`` });
         }
-      } catch {
-        return null;
+      } catch (err) {
+        // `assertSafeFetchUrl` names the field and the rule, never the URL.
+        return no(err instanceof Error ? err.message : `${at}.oauth\` has an invalid URL`);
       }
       // Forwarded verbatim as query params later — a non-string value here is
       // a malformed declaration, not something to coerce.
       if (o.authParams !== undefined) {
         if (!isRecord(o.authParams) || !Object.values(o.authParams).every((v) => typeof v === 'string')) {
-          return null;
+          return no(`${at}.oauth.authParams\` must be an object of string values`);
         }
       }
       // PKCE is on unless the declaration says `false`; anything else there is
       // a malformed flag, not a preference.
-      if (o.pkce !== undefined && typeof o.pkce !== 'boolean') return null;
+      if (o.pkce !== undefined && typeof o.pkce !== 'boolean') return no(`${at}.oauth.pkce\` must be a boolean`);
       oauth = {
         ...(authorizationUrl !== undefined ? { authorizationUrl, tokenUrl: tokenUrl! } : {}),
         clientId: o.clientId.trim(),
@@ -182,7 +210,7 @@ export function validatedVariables(raw: unknown): ToolVariable[] | null {
       ...(oauth ? { oauth } : {}),
     });
   }
-  return out;
+  return { ok: true, variables: out };
 }
 
 /**
@@ -318,6 +346,12 @@ export function descriptorsFromMcpJson(
   mcpJsonText: string,
   pluginJsonText: string | null,
   layout: KbLayout,
+  /**
+   * Told of every server this file declares and the parse refuses, with the
+   * reason the log line gives. The scan keeps them so a sign-in started on a
+   * refused server answers why, instead of finding nothing by that name.
+   */
+  onRefused?: (server: string, reason: string, path: string) => void,
 ): ToolManualDescriptor[] {
   const { pluginsDir } = layout;
   let mcp: unknown;
@@ -347,10 +381,14 @@ export function descriptorsFromMcpJson(
   const mcpJsonPath = `${pluginsDir}/${pluginFolder}/${PLUGIN_MCP_FILE}`;
 
   const out: ToolManualDescriptor[] = [];
+  const skip = (name: string, reason: string) => {
+    log.warn(`skipping mcp server "${name}" in ${mcpJsonPath}: ${reason}`);
+    onRefused?.(name, reason, mcpJsonPath);
+  };
   for (const [name, rawEntry] of Object.entries(mcp.mcpServers)) {
     const verdict = judgeMcpServerEntry(name, rawEntry);
     if (!verdict.ok) {
-      log.warn(`skipping mcp server "${name}" in ${mcpJsonPath}: ${verdict.reason}.`);
+      skip(name, `${verdict.reason}.`);
       continue;
     }
     // Narrowed by the verdict: an entry that passed is a record.
@@ -365,22 +403,23 @@ export function descriptorsFromMcpJson(
     // into outbound requests exactly the same way.
     const reserved = referencesReservedVariable({ raw, ext });
     if (reserved !== null) {
-      log.warn(
-        `skipping mcp server "${name}" in ${mcpJsonPath}: its declaration (mcp.json ` +
-          `entry or plugin.json extension) references the reserved variable "${reserved}" — API_URL and ` +
-          'CONNECTION_KEY are platform-seeded and may not appear in server declarations.',
+      skip(
+        name,
+        `its declaration (mcp.json entry or plugin.json extension) references the reserved variable "${reserved}" — ` +
+          'API_URL and CONNECTION_KEY are platform-seeded and may not appear in server declarations.',
       );
       continue;
     }
-    const variables = validatedVariables(ext.variables);
-    if (variables === null) {
-      log.warn(
-        `skipping mcp server "${name}" in ${mcpJsonPath}: its plugin.json \`variables\` ` +
-          'declaration is malformed — a dropped declaration would silently re-scope a credential, so ' +
-          'the server stays offline until the manifest is fixed.',
+    const judged = judgeVariables(ext.variables);
+    if (!judged.ok) {
+      skip(
+        name,
+        `its plugin.json \`variables\` declaration is malformed (${judged.reason}) — a dropped declaration ` +
+          'would silently re-scope a credential, so the server stays offline until the manifest is fixed.',
       );
       continue;
     }
+    const variables = judged.variables;
     const shared = {
       slug: name,
       name,
@@ -408,9 +447,9 @@ export function descriptorsFromMcpJson(
       try {
         assertSafeFetchUrl(url, { label: `mcp server "${name}" url` });
       } catch (err) {
-        log.warn(
-          `skipping mcp server "${name}" in ${mcpJsonPath}: ` +
-            `${err instanceof Error ? err.message : String(err)} (declare it \`local: true\` if it is deliberately private).`,
+        skip(
+          name,
+          `${err instanceof Error ? err.message : String(err)} (declare it \`local: true\` if it is deliberately private).`,
         );
         continue;
       }

package/src/modules/tool-manuals/tool-manuals.contract.ts

@@ -356,6 +356,21 @@ export interface ToolManualDetail extends Omit<ToolManualSummary, 'description'>
   hiddenTools: HiddenTool[];
 }
 
+/**
+ * A connection's narrowing of the catalog: whether the connector defined at
+ * `definitionPath` (a `.tool` file, or the MCP server definition a server
+ * entry came from) is one the connection loads. Applied AFTER the caller's
+ * read gate, so it can only take manuals away. The agent surfaces pass the
+ * connection scope's `allowsConnector` (`modules/agent-scope`); absent is the
+ * whole readable catalog.
+ */
+export type ConnectorScope = (definitionPath: string) => boolean;
+
+/** A manual as its file reads now — see {@link IToolManualService.liveDeclaration}. */
+export type LiveDeclaration =
+  | { manual: ToolManualSummary; variable?: ToolVariable; refused?: undefined }
+  | { refused: string; manual?: undefined; variable?: undefined };
+
 export interface IToolManualService {
   /** The `.tool` manuals the user can read, as summaries. */
   listAccessible(userEmail: string): Promise<ToolManualSummary[]>;
@@ -377,7 +392,7 @@ export interface IToolManualService {
    * unparseable by definition, so the verdict comes from its folder's
    * `access.md` chain — default-deny, as everywhere else.
    */
-  listAccessibleCatalog(userEmail: string): Promise<AccessibleCatalog>;
+  listAccessibleCatalog(userEmail: string, within?: ConnectorScope): Promise<AccessibleCatalog>;
   /**
    * One readable `.tool` by slug, with its description + capabilities, for the
    * browser tool page. `null` when no such slug exists OR the caller can't read
@@ -385,6 +400,23 @@ export interface IToolManualService {
    * confirm that a tool the caller can't see exists).
    */
   getDetail(userEmail: string, slug: string): Promise<ToolManualDetail | null>;
+  /**
+   * One manual's declaration as its file reads on the default branch NOW, for a
+   * sign-in about to start: the files are parsed afresh, never served from the
+   * catalog's cached scan, so an edit made seconds ago is already what this
+   * answers. A sign-in variable that names only its `clientId` is completed from
+   * the server's OAuth metadata by the same walk the catalog completes it with;
+   * when that fails, the endpoints stay absent and `manual.setup.reason` says why.
+   *
+   * `refused` when the file declaring this slug is one the parse refuses as it
+   * reads now (an endpoint failing the https/SSRF check, say): the parser's
+   * reason, so the sign-in can say why instead of finding nothing. `null` when
+   * no readable manual has this slug (fail-closed, like {@link getDetail});
+   * `variable` absent when the file declares no variable of that name. Nothing
+   * the platform synthesises from discovery (the zero-config sign-in variable)
+   * is in the answer: it is not in any file.
+   */
+  liveDeclaration(userEmail: string, slug: string, varName: string): Promise<LiveDeclaration | null>;
 
   /**
    * Wire where a hidden tool's schema finding comes from (the MCP proxy, which
@@ -406,7 +438,7 @@ export interface IToolManualService {
    * manual's embedded tools breaks without touching anything a summary shows.
    * Opaque to callers: only equality is ever asked of these lines.
    */
-  catalogFingerprints(userEmail: string): Promise<string[]>;
+  catalogFingerprints(userEmail: string, within?: ConnectorScope): Promise<string[]>;
   /**
    * Every manual in the catalog, UNFILTERED by access — the mirror of
    * `skillService.listSkills(undefined)`. For caller-INDEPENDENT counting only
@@ -422,7 +454,7 @@ export interface IToolManualService {
    * NOT include the KB manual (the route prepends that). With `{ remoteOnly: true }`
    * (the remote MCP proxy), LOCAL-ONLY manuals (`remote: false`) are excluded.
    */
-  toManualCallTemplates(userEmail: string, opts?: { remoteOnly?: boolean }): Promise<CallTemplate[]>;
+  toManualCallTemplates(userEmail: string, opts?: { remoteOnly?: boolean; within?: ConnectorScope }): Promise<CallTemplate[]>;
   /**
    * The caller's accessible LOCAL-ONLY (`remote: false`) manuals.
    *
@@ -430,21 +462,23 @@ export interface IToolManualService {
    * both: `name` is the UTCP namespace its `${VAR}` refs are keyed by, and
    * `slug` is what addresses the manual on the variable-resolution route.
    */
-  listLocalOnly(userEmail: string): Promise<{ slug: string; name: string; path: string }[]>;
+  listLocalOnly(userEmail: string, within?: ConnectorScope): Promise<{ slug: string; name: string; path: string }[]>;
   /**
    * Tools declared on `branch` whose namespace the default-branch catalog does
    * not serve yet, filtered to what the caller can read there. The catalog is
    * built from the default branch only, so a server an agent declares on its
    * draft is invisible to every tool surface until the draft is merged — this
    * is how the agent is told where its declaration lives. `[]` for the default
-   * branch itself, or a branch with no workspace.
+   * branch itself, or a branch with no workspace. `within` narrows the answer
+   * to a connection's connectors, after the read gate, as the catalog's does.
    */
   listDeclaredOnlyOnBranch(
     userEmail: string,
     branch: string,
+    within?: ConnectorScope,
   ): Promise<{ name: string; path: string; type: ToolManualType }[]>;
   /** The embedded UTCP manual for an inline `.tool` (served at `/api/tools/:slug/manual`). */
-  resolveInlineManual(userEmail: string, slug: string): Promise<UtcpManualDict | null>;
+  resolveInlineManual(userEmail: string, slug: string, opts?: { within?: ConnectorScope }): Promise<UtcpManualDict | null>;
   /** Validate a draft `.tool` file's content for the renderer preview. */
   preview(content: string): Promise<ToolManualPreview>;
   /**

package/src/modules/tool-manuals/tool-manuals.routes.ts

@@ -19,6 +19,7 @@ import type { AuthUser } from '@bevel-software/platform-shared';
 import '../auth/index.js'; // Express Request augmentation (req.userId / req.userEmail)
 import '../tool-auth/index.js'; // Express Request augmentation (req.toolAuth)
 import { hasGitInternalsSegment } from '../../shared/git-internals.js';
+import { NOT_AVAILABLE_TO_CONNECTION, resolveConnectionScope, type IAgentScopeResolver } from '../agent-scope/index.js';
 
 /** Resolve a connection-key/internal-token user id to its email (per-caller ACL). */
 export type ResolveUserEmail = (userId: string) => Promise<string | undefined>;
@@ -64,6 +65,11 @@ export function createToolManualsAgentRoutes(
      */
     pluginIndex?: Pick<IPluginIndexService, 'catalog'>;
   },
+  /**
+   * Resolves the scope of a connection made as an agent configuration, so
+   * `all-tools` lists only the connectors it loads (`modules/agent-scope`).
+   */
+  agentScope?: Pick<IAgentScopeResolver, 'resolve'>,
 ): express.Router {
   const router = express.Router();
 
@@ -83,9 +89,18 @@ export function createToolManualsAgentRoutes(
       // Default remote-safe: exclude local-only manuals unless the caller (a locally
       // installed MCP server) explicitly opts in with `?remote=false`.
       const remoteOnly = req.query.remote !== 'false';
-      const userManuals = email ? await toolManualService.toManualCallTemplates(email, { remoteOnly }) : [];
+      // A connection made as an agent configuration lists only the connectors that
+      // file loads, and says which agent it is — the MCP proxy words its
+      // refusals and its handshake from that. Everything lists as it always
+      // did, with no `connection` at all.
+      const scope = await resolveConnectionScope(agentScope, email, req.toolAuth?.agentPath);
+      const within = scope.connectorFilter();
+      const userManuals = email
+        ? await toolManualService.toManualCallTemplates(email, within ? { remoteOnly, within } : { remoteOnly })
+        : [];
       const manuals: CallTemplate[] = [kbManualTemplate(), ...userManuals];
-      res.json({ manuals });
+      const connection = scope.toWire();
+      res.json(connection ? { manuals, connection } : { manuals });
     } catch (err) {
       log.error('all-tools failed:', { err });
       res.status(500).json({ error: 'Failed to list tools' });
@@ -171,6 +186,24 @@ export function createToolManualsAgentRoutes(
         email,
         rels.map((r) => `${pluginRel}/${r}`),
       );
+      // A folder with nothing the person may read is absent to them, whatever
+      // the connection — so that 404 comes first, and the connection's own
+      // refusal below never confirms a folder the person could not see.
+      if (![...verdicts.values()].some((v) => v === true)) {
+        return void res.status(404).json({ error: 'Not found' });
+      }
+      // A connection made as an agent configuration materializes only a plugin
+      // that defines a connector the file loads — the archive is how the
+      // local MCP server runs one, and nothing else asks for it. Checked
+      // before any file is opened.
+      const scope = await resolveConnectionScope(agentScope, email, req.toolAuth?.agentPath);
+      if (!scope.loadsConnectorIn(pluginRel)) {
+        const why = scope.describe();
+        return void res.status(403).json({
+          error: `The plugin "${folder}" is not available to this connection.${why ? ` ${why}` : ''}`,
+          code: NOT_AVAILABLE_TO_CONNECTION,
+        });
+      }
       const zip = new AdmZip();
       let included = 0;
       let bytes = 0;
@@ -269,7 +302,11 @@ export function createToolManualsAgentRoutes(
       const email = await callerEmail(req);
       if (!email) return void res.status(403).json({ error: 'Forbidden' });
       const slug = Array.isArray(req.params.slug) ? req.params.slug[0] : req.params.slug;
-      const manual = await toolManualService.resolveInlineManual(email, String(slug));
+      // A connection made as an agent configuration reads only the manuals of the
+      // connectors it loads; another is as absent as one the person cannot read.
+      const scope = await resolveConnectionScope(agentScope, email, req.toolAuth?.agentPath);
+      const within = scope.connectorFilter();
+      const manual = await toolManualService.resolveInlineManual(email, String(slug), within ? { within } : undefined);
       if (!manual) return void res.status(404).json({ error: 'Not found' });
       res.json(manual);
     } catch (err) {