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

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/mcp-server-edit.service.ts

@@ -368,7 +368,7 @@ export class McpServerEditService {
     // COMMIT must not — the pending-commit pipeline may already have created
     // a local commit before the push refused, and rewriting the working tree
     // to pre-edit bytes would leave it dirty AGAINST that commit, a state the
-    // workflow layer's own pull-rebase recovery then misreads. Commit-stage
+    // version-control layer's own pull-rebase recovery then misreads. Commit-stage
     // failures propagate as-is and the pipeline's recovery owns the cleanup.
     const [mcpBefore, manifestBefore] = await Promise.all([
       fs.readFile(mcpAbs, 'utf8').catch(() => null),

package/src/modules/tool-manuals/pending-tools.service.ts

@@ -3,7 +3,7 @@ import {
   PLUGIN_MCP_FILE,
   pluginOfPath,
   type ChangeRequest,
-  type IWorkflowService,
+  type IVersionControlService,
   type KbLayout,
 } from '@bevel-software/platform-shared';
 import { type WorkspaceService } from '../workspace/index.js';
@@ -54,7 +54,7 @@ export class PendingToolsService implements IPendingToolService {
     private readonly workspaceService: WorkspaceService,
     private readonly accessControl: IAccessControl,
     private readonly toolManuals: Pick<IToolManualService, 'listAllSummaries'>,
-    private readonly workflow: IWorkflowService,
+    private readonly versionControl: IVersionControlService,
     private readonly kb: KbContext,
   ) {}
 
@@ -77,7 +77,7 @@ export class PendingToolsService implements IPendingToolService {
       {
         workspaceService: this.workspaceService,
         accessControl: this.accessControl,
-        workflow: this.workflow,
+        versionControl: this.versionControl,
         kb: this.kb,
       },
       userEmail,

package/src/modules/tool-manuals/tool-delete.service.ts

@@ -331,7 +331,7 @@ export class ToolDeleteService {
       // THEN pushes, so a refused push leaves a commit that already removed
       // the file: renaming it back there would leave the working tree dirty
       // against HEAD — re-adding, on the next commit, the very tool this one
-      // deleted, which is the state the workflow layer's own recovery
+      // deleted, which is the state the version-control layer's own recovery
       // misreads (McpServerEditService refuses to touch the tree for the same
       // reason). A probe that itself fails counts as "a commit may exist": the
       // park survives, dot-prefixed and invisible to the scanner, for a person

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

@@ -52,7 +52,12 @@ export interface ToolVariableOAuth {
   /** Absent on an mcp.json server ⇒ discovered from the server's OAuth metadata. */
   authorizationUrl?: string;
   tokenUrl?: string;
-  clientId: string;
+  /**
+   * Required on an ordinary sign-in. Absent ONLY on a managed one (see
+   * `managed`), whose client is Bevel's and lives on the broker; an owner who
+   * brings their own app supplies it on the client-secret route instead.
+   */
+  clientId?: string;
   scopes?: string[];
   /**
    * Extra static query params appended to the authorization request — e.g.
@@ -77,6 +82,21 @@ export interface ToolVariableOAuth {
    * endpoints are declared by hand too.
    */
   resource?: string;
+  /**
+   * The sign-in goes through Bevel's managed OAuth app for a platform
+   * connector: the broker does the provider round-trip and hands the tokens
+   * to this deployment, and renews them on its behalf. Written by the
+   * connector template an admin enables; `clientId` is then absent. The
+   * broker decides the scopes it requests from its own copy of the
+   * connector's definition, so an edited file cannot widen them.
+   */
+  managed?: ManagedSignIn;
+}
+
+/** Which managed connector and scope set a sign-in belongs to. */
+export interface ManagedSignIn {
+  connectorId: string;
+  scopeSet: string;
 }
 
 /**
@@ -93,8 +113,11 @@ export interface ToolVariable {
   label?: string;
   /**
    * When present, this variable is OAuth-backed: the user signs in with the
-   * declared provider to obtain a token. Only valid with `scope:'user'` (each
-   * caller authorizes their own). The client secret is NOT declared here.
+   * declared provider to obtain a token. Valid with `scope:'user'` (each
+   * caller authorizes their own), or with `scope:'admin'` ONLY for a managed
+   * sign-in — one workspace connection an owner makes, read by every caller
+   * (the shared row then holds the tokens). The client secret is NOT
+   * declared here.
    */
   oauth?: ToolVariableOAuth;
 }
@@ -366,6 +389,11 @@ export interface ToolManualDetail extends Omit<ToolManualSummary, 'description'>
  */
 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[]>;
@@ -395,6 +423,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
@@ -503,6 +548,21 @@ export interface IToolManualService {
   ): Promise<
     { key: string; name: string; label: string | null; oauth: boolean; oauthScopes?: string[] }[]
   >;
+  /**
+   * The SHARED (`admin`-scoped) sign-ins a manual declares — a managed
+   * connector enabled as a workspace connection. The pre-call check reads
+   * these so a tool whose one connection nobody has made yet is reported as
+   * missing its sign-in, labelled "(a tool owner connects this for the
+   * workspace)", instead of failing opaquely at the provider.
+   *
+   * `key` is the vault key as UTCP derives it (`utcpNamespacedKey`): the
+   * manual's name with every non-word character made `_` and every `_` then
+   * doubled, an `_`, and the variable's name (`my-tool` + `ACCESS_TOKEN` →
+   * `my__tool_ACCESS_TOKEN`). Read it from here; never compose it by hand.
+   */
+  sharedSignInKeysForManual(
+    manualName: string,
+  ): Promise<{ key: string; name: string; label: string | null; oauthScopes?: string[] }[]>;
   /** Drop the cached catalog (call after a merge to the default branch). */
   invalidate(): void;
 }