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

package/src/modules/tool-manuals/mcp-server-edit.service.ts

@@ -174,10 +174,19 @@ export class McpServerEditService {
     const servers = mcp.mcpServers as Record<string, unknown>;
     if (!(name in servers)) throw new McpServerEditError('No such server.', 404);
 
-    if (write.transport !== 'streamable-http' && write.transport !== 'sse' && write.transport !== 'stdio') {
-      // Persisting an unknown transport would save an entry discovery then
-      // refuses — an unusable server with no error at the moment it was made.
-      throw new McpServerEditError(`Unknown transport "${String(write.transport)}".`, 422);
+    if (write.transport !== 'streamable-http' && write.transport !== 'stdio') {
+      // Persisting a transport discovery refuses would save an entry that
+      // vanishes from the catalog the moment it is written — an unusable
+      // server with no error at the moment it was made. `sse` is refused BY
+      // NAME with the fix spelled out, because the pinned MCP client has no
+      // sse transport; an EXISTING sse entry stays readable here, so it can
+      // be edited to `streamable-http` rather than being stranded.
+      throw new McpServerEditError(
+        write.transport === 'sse'
+          ? 'The MCP client has no `sse` transport — declare the server as `streamable-http` if it supports it.'
+          : `Unknown transport "${String(write.transport)}".`,
+        422,
+      );
     }
     // The EFFECTIVE value of every field, PATCH-over-stored (see
     // McpServerWrite): `undefined` keeps what the files already say, a

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

@@ -88,6 +88,57 @@ export interface ToolVariable {
   oauth?: ToolVariableOAuth;
 }
 
+/**
+ * An optional cheap, read-only call that proves a credential actually WORKS.
+ *
+ * A `type: mcp` manual needs none — its handshake is authenticated, so merely
+ * connecting already tests the token. `http` and `inline` manuals have no such
+ * moment: registering an `http` manual fetches its DESCRIPTION, which providers
+ * usually serve publicly, so a wrong key sails through; an `inline` manual's
+ * discovery template points at Bevel's own API and never touches the provider
+ * at all. Without a declaration there is genuinely nothing to call, and the
+ * platform reports the connection as unverified rather than guessing.
+ *
+ * NOT inferred from the manual's own tools. Picking one automatically would
+ * mean calling an arbitrary tool with invented arguments — a probe that could
+ * send a message or create a record is worse than no probe. The author names a
+ * safe endpoint or the tool stays unverified.
+ *
+ * `${VAR}` refs resolve from the caller's vault exactly as they do in `url` and
+ * `headers`, which is the whole point: the probe must carry the same credential
+ * the real calls carry. Any 2xx is a pass; 401/403 is a rejection; anything
+ * else is treated as the provider being unwell rather than the key being wrong.
+ */
+export interface ToolHealthCheck {
+  /** Absolute URL to call. May contain `${VAR}` refs; SSRF-checked like `url`. */
+  url: string;
+  /** Default `GET`. A health check may not mutate, so nothing else is allowed. */
+  method?: 'GET';
+  /** Defaults to the manual's own `headers` — usually where the credential is. */
+  headers?: Record<string, string>;
+}
+
+/**
+ * One manual, reduced to exactly what testing its credential requires.
+ *
+ * Server-internal, like {@link ToolHealthCheck} and for the same reason: both
+ * `healthCheck.headers` and `callTemplate` can carry a literal token.
+ */
+export interface ToolProbeTarget {
+  name: string;
+  type: ToolManualType;
+  /** `false` for a local-only tool this server is not the one that can reach it. */
+  remote?: boolean;
+  /** The probe the `.tool` declares, if any. */
+  healthCheck?: ToolHealthCheck;
+  /**
+   * The validated UTCP call template, or `null` when the manual doesn't produce
+   * a valid one. Only the `mcp` probe uses it — its handshake IS the test — but
+   * it is built here so the probe never has to walk the catalog again.
+   */
+  callTemplate: CallTemplate | null;
+}
+
 /**
  * For a `type: mcp` tool, what an admin must do to make the remote server
  * reachable — derived from OAuth auto-discovery, which a non-mcp tool has no
@@ -140,6 +191,15 @@ export interface ToolManualDescriptorBase {
   variables?: ToolVariable[];
   /** For `type: mcp`: the admin-facing setup requirement from auto-discovery. */
   setup?: ToolManualSetup;
+  /**
+   * Optional credential probe — see {@link ToolHealthCheck}. Declared on
+   * `http`/`inline` manuals, and honoured on `type: mcp` too, where it
+   * OVERRIDES the default handshake probe (a server whose health endpoint is
+   * cheaper or more truthful than a full MCP handshake says so here).
+   * INTERNAL: lives on the descriptor, never on {@link ToolManualSummary},
+   * because it carries `headers`.
+   */
+  healthCheck?: ToolHealthCheck;
 }
 
 /** The spawn spec of a stdio-declared MCP server (a plugin `mcp.json` entry). */
@@ -197,6 +257,10 @@ export interface ToolManualSummary {
   remote?: boolean;
   /** For `type: mcp`: the admin-facing setup requirement from auto-discovery. */
   setup?: ToolManualSetup;
+  // NOTE: no `healthCheck` here, deliberately. This type is serialized straight
+  // to the browser by the tool endpoints, and a probe carries `headers` — which
+  // a `.tool` author may write as a literal token rather than a `${VAR}` ref.
+  // The server reads probe config through `IToolManualService.probeTargetFor`.
 }
 
 /** One thing an `inline` manual's embedded tool list says the assistant can do. */
@@ -269,6 +333,31 @@ export interface IToolManualService {
    * a `resolve` reads the shared row or the caller's row.
    */
   scopeOfVariable(effectiveKey: string): Promise<ToolVariableScope>;
+  /**
+   * Everything the credential probe needs about one readable manual, resolved
+   * in a SINGLE catalog + ACL pass.
+   *
+   * One accessor rather than three because the probe needs three facts that all
+   * come from the same file — is it local-only, does it declare a health check,
+   * and what call template would reach it — and asking for them separately made
+   * one probe walk the catalog four times, building call templates for every
+   * manual in the workspace to use exactly one of them.
+   *
+   * Deliberately NOT reachable through {@link ToolManualSummary}: that type is
+   * serialized straight to the browser by the tool endpoints, and a probe
+   * carries `headers` — which a `.tool` author may write as a literal token
+   * rather than a `${VAR}` ref. Probe config is internal to the server, so it
+   * travels by its own accessor and never rides a public DTO.
+   *
+   * Addressed by SLUG, which is what the route has: resolving the slug here
+   * rather than making the caller map it to a name first is what reduces a
+   * probe to one pass. `ToolProbeTarget.name` carries the UTCP namespace back
+   * out, since that is what the probe's `${VAR}` lookups are keyed by.
+   *
+   * `null` when no such manual exists OR the caller can't read it — the two are
+   * indistinguishable on purpose, as everywhere else in this contract.
+   */
+  probeTargetFor(userEmail: string, slug: string): Promise<ToolProbeTarget | null>;
   /**
    * The per-user (`user`-scoped) variables a manual declares, each with the vault
    * key (`<manual>_<VAR>`) the caller's value is stored under, its bare name, and

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

@@ -45,6 +45,8 @@ import {
   type ToolManualPreview,
   type ToolManualType,
   type ToolVariable,
+  type ToolHealthCheck,
+  type ToolProbeTarget,
   type ToolVariableScope,
   type ToolVariableOAuth,
 } from './tool-manuals.contract.js';
@@ -235,6 +237,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[] = [];
@@ -415,6 +452,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 +532,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 ?? []),
             {
@@ -848,20 +912,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 +923,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__/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();
+  });
+});