@bevel-software/platform-core-backend 0.13.6 → 0.15.1

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

@@ -15,10 +15,10 @@ import {
 import {
   DEFAULT_BRANCH,
   PLUGINS_DIR,
-  PLUGIN_MANIFEST_FILE,
-  PLUGIN_MCP_FILE,
 } from '@bevel-software/platform-shared';
 import { descriptorsFromMcpJson } from './mcp-json-discovery.js';
+import type { PluginSource } from '../plugins/discovery/plugin-source.js';
+import { KbPluginSource } from '../plugins/discovery/kb-plugin-source.js';
 import type { WorkspaceService } from '../workspace/workspace.service.js';
 import { workspaceIdForBranch } from '../../shared/workspace-id.js';
 import type { IAccessControl } from '../access/access-control.interface.js';
@@ -45,6 +45,8 @@ import {
   type ToolManualPreview,
   type ToolManualType,
   type ToolVariable,
+  type ToolHealthCheck,
+  type ToolProbeTarget,
   type ToolVariableScope,
   type ToolVariableOAuth,
 } from './tool-manuals.contract.js';
@@ -148,6 +150,8 @@ export class ToolManualService implements IToolManualService {
     private readonly accessControl: IAccessControl,
     private readonly kbDirName: string,
     now: () => number = Date.now,
+    /** Where plugins (and their MCP servers) come from — native manifests unless a dialect is configured. */
+    private readonly source: PluginSource = new KbPluginSource(),
   ) {
     this.cache = new TtlCache(CACHE_TTL_MS, now);
   }
@@ -235,6 +239,41 @@ export class ToolManualService implements IToolManualService {
     return declared?.scope ?? 'admin';
   }
 
+  /**
+   * The probe config for a manual this caller can read — the internal
+   * counterpart to everything on `ToolManualSummary`.
+   *
+   * Access-gated through `accessibleManuals` like every other read, so this
+   * cannot become a way to learn what a `.tool` you can't see declares.
+   */
+  async probeTargetFor(userEmail: string, slug: string): Promise<ToolProbeTarget | null> {
+    const manuals = await this.accessibleManuals(userEmail);
+    const m = manuals.find((x) => x.slug === slug);
+    if (!m) return null;
+    // Built here, from the manual already in hand. `toManualCallTemplates`
+    // would validate every manual in the workspace to hand back the one we
+    // want; an invalid template for THIS manual is not an error, just a probe
+    // that has nothing to dial (the caller reports it as unverifiable).
+    //
+    // Only for the ONE path that dials it — an `mcp` manual, reachable from
+    // this process, that declared no health check of its own. Everywhere else
+    // the template is built, validated and thrown away, and an http tool with
+    // an unvalidatable template warn-logs on every probe about a value nothing
+    // was ever going to use.
+    const dialsTheTemplate = m.type === 'mcp' && !m.healthCheck && m.remote !== false;
+    let callTemplate: CallTemplate | null = null;
+    if (dialsTheTemplate) {
+      try {
+        callTemplate = callTemplateSerializer.validateDict(this.buildCallTemplateDict(m));
+      } catch (err) {
+        console.warn(
+          `[tool-manuals] no valid call template for "${m.path}": ${err instanceof Error ? err.message : String(err)}`,
+        );
+      }
+    }
+    return { name: m.name, type: m.type, remote: m.remote, healthCheck: m.healthCheck, callTemplate };
+  }
+
   async toManualCallTemplates(userEmail: string, opts?: { remoteOnly?: boolean }): Promise<CallTemplate[]> {
     const manuals = await this.accessibleManuals(userEmail);
     const out: CallTemplate[] = [];
@@ -388,12 +427,15 @@ export class ToolManualService implements IToolManualService {
   private async scan(): Promise<ToolManualDescriptor[]> {
     const cached = this.cache.get();
     if (cached) return cached;
+    // See `TtlCache.begin`: taken before the read so an `invalidate()` that
+    // lands mid-scan discards this result instead of being overwritten by it.
+    const token = this.cache.begin();
     const manuals = await this.scanDisk();
     await this.decorateMcpOAuth(manuals);
     // AFTER the oauth decoration, so an injected `${MCP_OAUTH}` header ref is
     // already declared and isn't re-surfaced as a bare admin key.
     for (const m of manuals) this.surfaceReferencedVariables(m);
-    this.cache.set(manuals);
+    this.cache.set(manuals, token);
     return manuals;
   }
 
@@ -415,6 +457,19 @@ export class ToolManualService implements IToolManualService {
       if (m.type === 'inline' && m.tools) {
         refs.push(...variableSubstitutor.findRequiredVariables(m.tools, m.name));
       }
+      // A probe-only credential still has to reach the secrets UI. The call
+      // template is built from `url`/`headers` and never carries `healthCheck`,
+      // so a `${VAR}` used solely by the probe would never be surfaced for
+      // provisioning — and `probeDeclared` would then report `unverifiable`
+      // forever on a variable no screen ever offered anyone to fill in.
+      if (m.healthCheck) {
+        refs.push(
+          ...variableSubstitutor.findRequiredVariables(
+            { url: m.healthCheck.url, headers: m.healthCheck.headers ?? {} },
+            m.name,
+          ),
+        );
+      }
     } catch {
       return; // a malformed template is reported elsewhere; never break the scan
     }
@@ -482,6 +537,20 @@ export class ToolManualService implements IToolManualService {
           }
           m.setup = { kind: 'oauth-auto' };
           m.headers = { ...(m.headers ?? {}), Authorization: `Bearer \${${MCP_OAUTH_VAR}}` };
+          // A declared healthCheck froze its headers during normalize —
+          // BEFORE this decoration — so it would dial without the bearer
+          // every real call now carries and read its own 401 as a rejected
+          // credential. The injected sign-in reaches the check too, unless
+          // the check declares its own Authorization.
+          if (
+            m.healthCheck &&
+            !Object.keys(m.healthCheck.headers ?? {}).some((h) => h.toLowerCase() === 'authorization')
+          ) {
+            m.healthCheck = {
+              ...m.healthCheck,
+              headers: { ...(m.healthCheck.headers ?? {}), Authorization: `Bearer \${${MCP_OAUTH_VAR}}` },
+            };
+          }
           m.variables = [
             ...(m.variables ?? []),
             {
@@ -590,27 +659,13 @@ export class ToolManualService implements IToolManualService {
     // shape. Listed BEFORE the `.tool` files: on a name collision (a legacy
     // mcp `.tool` the migration has not converted yet), the shared dedup keeps
     // the first occurrence, and the authoritative source must be the one kept.
+    // The plugins (and their mcp.json text) come from the configured source, so
+    // a dialect that expands servers from a registry lands here unchanged.
     const parsed: ToolManualDescriptor[] = [];
-    let pluginFolders: string[] = [];
-    try {
-      pluginFolders = (await fs.readdir(root, { withFileTypes: true }))
-        .filter((e) => e.isDirectory() && !e.name.startsWith('.'))
-        .map((e) => e.name)
-        .sort();
-    } catch {
-      /* no Plugins/ root — nothing to scan */
-    }
-    for (const folder of pluginFolders) {
-      let mcpJson: string;
-      try {
-        mcpJson = await fs.readFile(path.join(root, folder, PLUGIN_MCP_FILE), 'utf-8');
-      } catch {
-        continue; // no mcp.json is the common case, not an error
-      }
-      const pluginJson = await fs
-        .readFile(path.join(root, folder, PLUGIN_MANIFEST_FILE), 'utf-8')
-        .catch(() => null);
-      parsed.push(...descriptorsFromMcpJson(folder, mcpJson, pluginJson));
+    const discovered = await this.source.discover(kbRoot);
+    for (const plugin of discovered.plugins) {
+      if (plugin.mcpJsonText === null) continue; // no servers is the common case, not an error
+      parsed.push(...descriptorsFromMcpJson(plugin.relFolder, plugin.mcpJsonText, plugin.manifestText));
     }
 
     for (const f of files) {
@@ -848,20 +903,8 @@ export function normalizeToolManual(
     // literal internal host slips past as a templated scheme or userinfo.
     // Local-only (`remote: false`) `.tool`s are never fetched server-side, so
     // are exempt.
-    const literalScheme = /^([a-zA-Z][a-zA-Z0-9+.-]*:)[\\/]{2}/.exec(url)?.[1];
-    const sepMatch = /:[\\/]{2}/.exec(url);
-    const sepIdx = sepMatch ? sepMatch.index : -1;
-    const authority = sepIdx >= 0 ? url.slice(sepIdx + 3).split(/[/\\?#]/, 1)[0] : url;
-    const hostPort = authority.slice(authority.lastIndexOf('@') + 1);
-    const host = hostPort.startsWith('[') ? hostPort.slice(0, hostPort.indexOf(']') + 1) : hostPort.split(':')[0];
-    if (descriptor.remote !== false && !host.includes('${')) {
-      const checkUrl =
-        literalScheme && !authority.includes('${')
-          ? url // fully literal scheme + authority → validate the URL as-is
-          : sepIdx >= 0
-            ? `${literalScheme ?? 'http:'}//${host}` // templated scheme/userinfo/port, literal host
-            : url; // no authority shape at all → parse raw (refuses malformed)
-      assertSafeFetchUrl(checkUrl, { label: `\`.tool\` "${name}" url` });
+    if (descriptor.remote !== false) {
+      assertSafeManualFetchUrl(url, `\`.tool\` "${name}" url`);
     }
     if (obj.headers && typeof obj.headers === 'object' && !Array.isArray(obj.headers)) {
       descriptor.headers = obj.headers as Record<string, string>;
@@ -871,9 +914,139 @@ export function normalizeToolManual(
       descriptor.httpMethod = m === 'POST' ? 'POST' : 'GET';
     }
   }
+
+  // LAST, because it inherits the manual's own `headers` when it declares none
+  // — which is the common case, and the reason a one-line `healthCheck: {url}`
+  // authenticates exactly like a real call. Resolving that default here, where
+  // the whole descriptor is in hand, keeps the probe self-contained: nothing
+  // downstream has to re-derive which headers a manual would have sent.
+  //
+  // For `http`/`mcp` only. An `inline` manual's execution never sends its
+  // top-level `headers` — each embedded tool carries its own call template —
+  // so inheriting them would have the probe prove a request no real call
+  // makes. An inline probe declares its own headers on the healthCheck, or
+  // sends none.
+  const declaredHeaders =
+    type !== 'inline' && obj.headers && typeof obj.headers === 'object' && !Array.isArray(obj.headers)
+      ? (obj.headers as Record<string, string>)
+      : undefined;
+  const healthCheck = normalizeHealthCheck(obj.healthCheck, name, descriptor.remote, declaredHeaders);
+  if (healthCheck) descriptor.healthCheck = healthCheck;
+
   return descriptor;
 }
 
+/**
+ * SSRF guard for a URL a `.tool` will make the SERVER fetch — its manual `url`
+ * and its declared `healthCheck.url` alike, which is why this is a function
+ * rather than an inline block: two fetch targets policed by one rule cannot
+ * drift apart.
+ *
+ * A remote-capable `.tool` triggers a server-side fetch (the MCP proxy, the
+ * in-process agent, headless routines, and now the credential probe), so a
+ * literal private/loopback/metadata host is refused at the producing boundary.
+ * Only a TEMPLATED HOSTNAME (resolved at call time) is uncheckable here — a
+ * `${...}` in the scheme, userinfo, port, path, or query still leaves a
+ * concrete network target (`${S}://169.254.169.254/x` and
+ * `http://${U}@169.254.169.254/x` target the metadata IP no matter what
+ * resolves), so the guard must still run against the literal host. The
+ * authority is therefore taken from `://` INDEPENDENT of the scheme being
+ * literal, and when the raw url can't parse (templated scheme or port) the
+ * check runs on a synthetic `<scheme-or-http>//host`. A BACKSLASH behaves as a
+ * slash for http(s) in WHATWG `new URL` — BOTH as the scheme separator
+ * (`${S}:\\169.254.169.254\\p` → the IP is the host) and inside the authority
+ * (`http://169.254.169.254\\@${HOST}/x` fetches the IP, the `\\@…` becoming
+ * path). So the authority separator is `:` + two `[\/]` (not just `://`), and
+ * `\` also terminates the authority alongside `/?#`; otherwise a literal
+ * internal host slips past as a templated scheme or userinfo.
+ *
+ * Callers gate on `remote !== false`: a local-only `.tool` is never fetched
+ * server-side, so it is exempt.
+ */
+function assertSafeManualFetchUrl(url: string, label: string): void {
+  const literalScheme = /^([a-zA-Z][a-zA-Z0-9+.-]*:)[\\/]{2}/.exec(url)?.[1];
+  const sepMatch = /:[\\/]{2}/.exec(url);
+  const sepIdx = sepMatch ? sepMatch.index : -1;
+  const authority = sepIdx >= 0 ? url.slice(sepIdx + 3).split(/[/\\?#]/, 1)[0] : url;
+  const hostPort = authority.slice(authority.lastIndexOf('@') + 1);
+  const host = hostPort.startsWith('[') ? hostPort.slice(0, hostPort.indexOf(']') + 1) : hostPort.split(':')[0];
+  // A templated host resolves to something we can't know yet — nothing to check.
+  if (host.includes('${')) return;
+  const checkUrl =
+    literalScheme && !authority.includes('${')
+      ? url // fully literal scheme + authority → validate the URL as-is
+      : sepIdx >= 0
+        ? `${literalScheme ?? 'http:'}//${host}` // templated scheme/userinfo/port, literal host
+        : url; // no authority shape at all → parse raw (refuses malformed)
+  assertSafeFetchUrl(checkUrl, { label });
+}
+
+/**
+ * Parse the optional `healthCheck:` block — the read-only call that proves this
+ * tool's credential works (see {@link ToolHealthCheck}).
+ *
+ * Throws on a malformed block rather than dropping it, matching `variables`
+ * and for the same reason inverted: a silently-ignored probe would leave the
+ * tool reporting "can't verify" forever while its author believes they wired
+ * one up, and the whole point of the field is to stop the UI overclaiming.
+ *
+ * `method` accepts only `GET`. A probe that can mutate is not a probe — it runs
+ * unattended on every save and re-check, so `POST` is refused outright instead
+ * of being quietly downgraded.
+ */
+function normalizeHealthCheck(
+  raw: unknown,
+  manualName: string,
+  remote: boolean | undefined,
+  manualHeaders: Record<string, string> | undefined,
+): ToolHealthCheck | undefined {
+  if (raw === undefined || raw === null) return undefined;
+  if (typeof raw !== 'object' || Array.isArray(raw)) throw new Error('`healthCheck` must be an object');
+  const e = raw as Record<string, unknown>;
+  const url = typeof e.url === 'string' ? e.url.trim() : '';
+  if (!url) throw new Error('`healthCheck` must have a `url`');
+  if (remote !== false) {
+    assertSafeManualFetchUrl(url, `\`.tool\` "${manualName}" healthCheck.url`);
+  }
+  const check: ToolHealthCheck = { url };
+  if (e.method !== undefined) {
+    const m = typeof e.method === 'string' ? e.method.toUpperCase() : '';
+    if (m !== 'GET') throw new Error('`healthCheck.method` must be `GET` — a health check may not mutate');
+    check.method = 'GET';
+  }
+  // Whichever headers the probe ends up carrying get checked — declared OR
+  // inherited. Validating only the declared branch left the common case
+  // unguarded: `healthCheck: { url }` alone inherits the manual's headers, so a
+  // YAML `Authorization: 1234` there still reached the probe untouched.
+  if (e.headers !== undefined) {
+    if (!e.headers || typeof e.headers !== 'object' || Array.isArray(e.headers)) {
+      throw new Error('`healthCheck.headers` must be an object');
+    }
+    check.headers = assertStringHeaders(e.headers as Record<string, unknown>, 'healthCheck.headers');
+  } else if (manualHeaders) {
+    check.headers = assertStringHeaders(manualHeaders as Record<string, unknown>, 'headers');
+  }
+  return check;
+}
+
+/**
+ * The VALUES of a header map, not just its container.
+ *
+ * YAML types `Authorization: 1234` as a number, and a cast alone let it through
+ * to the probe, where substitution calls `.matchAll` on it — surfacing
+ * `text.matchAll is not a function` to the user as the reason their credential
+ * is unhealthy. Caught at parse time, next to `url` and `method`, it reads as
+ * what it is: a mistake in the `.tool` file.
+ */
+function assertStringHeaders(headers: Record<string, unknown>, label: string): Record<string, string> {
+  for (const [k, v] of Object.entries(headers)) {
+    if (typeof v !== 'string') {
+      throw new Error(`\`${label}.${k}\` must be a string (quote it if it looks like a number)`);
+    }
+  }
+  return headers as Record<string, string>;
+}
+
 /**
  * Parse the optional `variables:` block of a `.tool` file. Each entry names a
  * `${VAR}` and who provisions it (`admin` default | `user`). Throws on a

package/src/modules/workflow/__tests__/preserve-roles-yaml.test.ts

@@ -80,7 +80,7 @@ describe('mergeChangeRequest — roles.yaml preservation guard', () => {
 
     const git = {
       fetch: vi.fn().mockResolvedValue(undefined),
-      pull: vi.fn().mockResolvedValue(undefined),
+      pull: vi.fn().mockResolvedValue({ treeChanged: true }),
       // Resolve roles.yaml at origin/<ref> from the per-test content.
       readFileAtRef: vi.fn(async (_ws: string, ref: string) =>
         ref === `origin/${BASE}` ? opts.baseRoles : ref === `origin/${HEAD}` ? opts.headRoles : null,

package/src/modules/workflow/__tests__/workflow.routes.history-read-gate.test.ts

@@ -0,0 +1,139 @@
+import type { Server } from 'node:http';
+import type { AddressInfo } from 'node:net';
+import express from 'express';
+import { describe, it, expect, afterEach, vi } from 'vitest';
+import type { IWorkflowService } from '@bevel-software/platform-shared';
+import type { IAccessControl } from '../../access/access-control.interface.js';
+import type { AuthService } from '../../auth/auth.service.js';
+import type { WorkspaceService } from '../../workspace/workspace.service.js';
+import type { WorkflowEventBus } from '../event-bus.js';
+import { createWorkflowRoutes } from '../workflow.routes.js';
+
+// A file's history is its content with a time axis: the same default-deny
+// read model that hides a file must hide its commit list, its diffs, and its
+// content at any commit. These routes used to require only "is authenticated".
+
+const USER = { id: 'u1', email: 'alice@example.com', name: 'Alice' };
+const WS = 'main';
+const KB = 'knowledge-base';
+const allow = (p: string) => !p.includes('Secret');
+
+interface Harness {
+  server: Server;
+  canRead: ReturnType<typeof vi.fn>;
+  canReadAtRef: ReturnType<typeof vi.fn>;
+  workflow: {
+    listChangesForFile: ReturnType<typeof vi.fn>;
+    compareFile: ReturnType<typeof vi.fn>;
+    showFileAtChange: ReturnType<typeof vi.fn>;
+    fileAtChange: ReturnType<typeof vi.fn>;
+  };
+  baseUrl: string;
+}
+
+async function makeHarness(): Promise<Harness> {
+  const canRead = vi.fn(async (_w: string, _e: string, p: string) => allow(p));
+  const canReadAtRef = vi.fn(async (_w: string, _r: string, _e: string, p: string) => allow(p));
+  const accessControl = { canRead, canReadAtRef } as unknown as IAccessControl;
+  const workflow = {
+    listChangesForFile: vi.fn(async () => []),
+    compareFile: vi.fn(async () => ''),
+    showFileAtChange: vi.fn(async () => ''),
+    fileAtChange: vi.fn(async () => ({ baseline: null, current: 'x' })),
+  };
+  const authService = { getUserById: vi.fn(async () => USER) } as unknown as AuthService;
+
+  const app = express();
+  app.use(express.json());
+  app.use('/api', (req, _res, next) => {
+    (req as unknown as { userId: string }).userId = USER.id;
+    next();
+  });
+  app.use(
+    '/api',
+    createWorkflowRoutes(
+      workflow as unknown as IWorkflowService,
+      {} as unknown as WorkspaceService,
+      authService,
+      { subscribe: vi.fn(), publish: vi.fn() } as unknown as WorkflowEventBus,
+      accessControl,
+      KB,
+    ),
+  );
+  const server = await new Promise<Server>((resolve) => {
+    const s = app.listen(0, () => resolve(s));
+  });
+  const addr = server.address() as AddressInfo;
+  return { server, canRead, canReadAtRef, workflow, baseUrl: `http://127.0.0.1:${addr.port}` };
+}
+
+function close(s: Server): Promise<void> {
+  return new Promise((resolve, reject) => s.close((e) => (e ? reject(e) : resolve())));
+}
+
+const OPEN = encodeURIComponent(`${KB}/Open/a.md`);
+const SECRET = encodeURIComponent(`${KB}/Secret/x.md`);
+
+describe('history routes enforce the read model', () => {
+  let h: Harness | null = null;
+  afterEach(async () => {
+    if (h) await close(h.server);
+    h = null;
+  });
+  const get = (p: string) => fetch(`${h!.baseUrl}/api/workspace/${WS}/workflow${p}`);
+
+  it.each([
+    ['/changes?path=%s', 'listChangesForFile'],
+    ['/show-file?sha=abc&path=%s', 'showFileAtChange'],
+    ['/file-at-change?sha=abc&path=%s', 'fileAtChange'],
+    ['/compare-file?from=a&to=b&path=%s', 'compareFile'],
+  ] as const)('%s: readable → 200, denied → 403 and git is never consulted', async (route, method) => {
+    h = await makeHarness();
+    expect((await get(route.replace('%s', OPEN))).status).toBe(200);
+    expect((await get(route.replace('%s', SECRET))).status).toBe(403);
+    // The denial happened BEFORE the service — nothing read the repository.
+    const calls = h.workflow[method].mock.calls as unknown[][];
+    expect(calls.length).toBe(1);
+    expect(String(calls[0][1])).toContain('Open');
+  });
+
+  it('a path without the repo prefix is refused outright — the git layer would read it as repo-relative', async () => {
+    // `stripRepoPrefix` makes `Secret/x.md` and `knowledge-base/Secret/x.md`
+    // name the same object, so an ungated "non-KB" branch would be a gate
+    // bypass by spelling. History is for tracked files only; no prefix, 400.
+    h = await makeHarness();
+    for (const p of ['Secret/x.md', 'scratch/notes.txt']) {
+      const res = await get(`/changes?path=${encodeURIComponent(p)}`);
+      expect(res.status).toBe(400);
+    }
+    expect(h.workflow.listChangesForFile).not.toHaveBeenCalled();
+  });
+
+  it('compare-file authorizes at every ref the comparison could serve', async () => {
+    // The comparison prefers a local ref (and the working tree) over
+    // `origin/<branch>`, so BOTH candidates are authorized per branch.
+    h = await makeHarness();
+    const res = await get(`/compare-file?from=a&to=b&path=${OPEN}`);
+    expect(res.status).toBe(200);
+    const refs = h.canReadAtRef.mock.calls.map((c) => c[1]).sort();
+    expect(refs).toEqual(['a', 'b', 'origin/a', 'origin/b']);
+
+    // Any RESOLVABLE ref denying the read refuses the diff.
+    h.canReadAtRef.mockImplementation(async (_w: string, ref: string) => (ref === 'b' ? false : true));
+    expect((await get(`/compare-file?from=a&to=b&path=${OPEN}`)).status).toBe(403);
+
+    // A branch none of whose refs resolve cannot be authorized: refused.
+    h.canReadAtRef.mockImplementation(async (_w: string, ref: string) =>
+      ref.endsWith('b') ? null : true,
+    );
+    expect((await get(`/compare-file?from=a&to=b&path=${OPEN}`)).status).toBe(403);
+  });
+
+  it('an access-model error fails closed, not open', async () => {
+    h = await makeHarness();
+    h.canRead.mockRejectedValueOnce(new Error('access tree unreadable'));
+    const res = await get(`/changes?path=${OPEN}`);
+    expect(res.status).toBeGreaterThanOrEqual(500);
+    expect(h.workflow.listChangesForFile).not.toHaveBeenCalled();
+  });
+});