@bevel-software/platform-core-backend 0.29.0 → 0.31.0

package/src/modules/kb-fs/ref-files.ts

@@ -0,0 +1,279 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { isAbsence } from '../../shared/fs.contract.js';
+import { gitDirOf } from './git-dir.js';
+
+/**
+ * Where a ref points, read from the repository's own files instead of a
+ * `git rev-parse` process.
+ *
+ * A branch tip is a small file git maintains: `refs/remotes/origin/<branch>`
+ * as a loose file, or one line of `packed-refs`. Reading it costs a file read
+ * and no fork, and it is exactly as current as the last fetch — the same
+ * freshness a `rev-parse` has. A change-request listing resolves two tips per
+ * open request and the access gates resolve every ref they decide at; with a
+ * hundred open requests that was hundreds of forks per listing, each costing
+ * tens of milliseconds of the main thread on a server holding a large heap.
+ *
+ * What is read, in git's own order: a loose file under the common directory
+ * (a worktree shares `refs/` with the repository it belongs to), then
+ * `packed-refs`. `HEAD` and the per-worktree namespaces (`refs/worktree/`,
+ * `refs/bisect/`, `refs/rewritten/`) are a worktree's own: read loose from
+ * its git directory, never from the common directory, and never packed. A
+ * symbolic ref (`ref: refs/heads/main`) is followed. A tag is never decided
+ * here: its file may hold a tag object, and what that peels to is git's to
+ * say.
+ *
+ * The answer is one of three things, and the caller treats them differently:
+ * `{ sha }` is what git would answer too; `'missing'` means every file git
+ * would consult says there is no such ref, which is as authoritative as
+ * `rev-parse` answering nothing; `'unreadable'` means this reader could not
+ * decide — a repository it does not understand (one whose refs live in a
+ * reftable, say), a tag, a corrupt file, a name it refuses — and the caller
+ * asks git, which is authoritative. Never a guess: a read error is
+ * `'unreadable'`, not `'missing'`, so a flaky disk sends the caller to git
+ * rather than making a branch disappear.
+ *
+ * What the files guarantee about the object: git itself refuses to write a
+ * non-commit under `refs/heads/`, and `refs/remotes/origin/` mirrors the
+ * remote's `refs/heads/`, so a branch tip read here is a commit as surely
+ * as `rev-parse <branch>^{commit}` would make it one. A caller that holds
+ * an object id rather than a name, or a `<rev>^{...}` form, asks git.
+ */
+export type RefFileAnswer = { sha: string } | 'missing' | 'unreadable';
+
+const SHA = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;
+const MAX_SYMREF_DEPTH = 5;
+const PER_WORKTREE = /^refs\/(?:worktree|bisect|rewritten)\//;
+
+/** A ref name this reader is willing to turn into a path under `.git`. */
+function isSafeRefName(ref: string): boolean {
+  if (ref === 'HEAD') return true;
+  if (!ref.startsWith('refs/')) return false;
+  if (!/^[A-Za-z0-9._\-/@+]+$/.test(ref)) return false;
+  return !ref.split('/').some((segment) => segment === '' || segment === '.' || segment === '..');
+}
+
+/**
+ * One resolution's view of the repository: the two directories, and the
+ * `packed-refs` table read at most once however many candidates a name
+ * tries — the table can grow with the history, and a name that is missing
+ * as itself consults it for every prefix.
+ */
+interface GitDirs {
+  /** The worktree's own git directory: `HEAD` lives here. */
+  gitDir: string;
+  /** Where `refs/` and `packed-refs` live: the repository, shared by every worktree. */
+  commonDir: string;
+  /** The `packed-refs` table, read on first need; null when it could not be read. */
+  packed?: Promise<Map<string, string> | null>;
+}
+
+async function gitDirsOf(repoDir: string): Promise<GitDirs | null> {
+  let gitDir: string | null;
+  try {
+    gitDir = await gitDirOf(repoDir);
+  } catch {
+    return null;
+  }
+  if (gitDir === null) return null;
+  let commonDir = gitDir;
+  try {
+    const pointer = (await fs.readFile(path.join(gitDir, 'commondir'), 'utf-8')).trim();
+    if (pointer) commonDir = path.resolve(gitDir, pointer);
+  } catch (err) {
+    if (!isAbsence(err)) return null;
+  }
+  // A repository whose refs live in a reftable (`extensions.refStorage`)
+  // keeps nothing this reader understands under `refs/` or in `packed-refs`:
+  // every name would read as missing. Not a repository for this reader.
+  try {
+    await fs.stat(path.join(commonDir, 'reftable'));
+    return null;
+  } catch (err) {
+    if (!isAbsence(err)) return null;
+  }
+  try {
+    if (/^\s*refstorage\s*=\s*reftable\s*$/im.test(await fs.readFile(path.join(commonDir, 'config'), 'utf-8'))) {
+      return null;
+    }
+  } catch (err) {
+    if (!isAbsence(err)) return null;
+  }
+  return { gitDir, commonDir };
+}
+
+/**
+ * `packed-refs`: `<sha> <name>` lines, `^<sha>` peel lines, `#` comments.
+ * Absent file → an empty table. A line that is none of those is a file this
+ * reader does not understand, and the whole table is null (unreadable): a
+ * record it skipped could be the one that was asked for.
+ */
+async function readPackedRefs(commonDir: string): Promise<Map<string, string> | null> {
+  let text: string;
+  try {
+    text = await fs.readFile(path.join(commonDir, 'packed-refs'), 'utf-8');
+  } catch (err) {
+    return isAbsence(err) ? new Map() : null;
+  }
+  const table = new Map<string, string>();
+  for (const raw of text.split('\n')) {
+    const line = raw.trim();
+    if (!line || line.startsWith('#')) continue;
+    if (line.startsWith('^')) {
+      if (!SHA.test(line.slice(1))) return null;
+      continue;
+    }
+    const space = line.indexOf(' ');
+    const sha = space < 0 ? '' : line.slice(0, space);
+    const name = space < 0 ? '' : line.slice(space + 1).trim();
+    if (!SHA.test(sha) || !name) return null;
+    table.set(name, sha);
+  }
+  return table;
+}
+
+/**
+ * The file at `<dir>/<relative>`, read as git reads a loose ref: a symbolic
+ * ref is followed, an object id is the answer, anything else is not decided.
+ */
+async function readLooseRef(dirs: GitDirs, dir: string, relative: string, depth: number): Promise<RefFileAnswer> {
+  let text: string;
+  try {
+    text = (await fs.readFile(path.join(dir, ...relative.split('/')), 'utf-8')).trim();
+  } catch (err) {
+    return isAbsence(err) ? 'missing' : 'unreadable';
+  }
+  if (text.startsWith('ref:')) {
+    const answer = await resolveIn(dirs, text.slice('ref:'.length).trim(), depth + 1);
+    // A symbolic ref whose target is gone is dangling, and git reports it
+    // as such; a packed entry under the symbolic ref's own name does not
+    // stand in for it. Git's to report, then.
+    return answer === 'missing' ? 'unreadable' : answer;
+  }
+  return SHA.test(text) ? { sha: text } : 'unreadable';
+}
+
+async function resolveIn(dirs: GitDirs, ref: string, depth: number): Promise<RefFileAnswer> {
+  if (depth > MAX_SYMREF_DEPTH) return 'unreadable';
+  if (!isSafeRefName(ref)) return 'unreadable';
+  // `HEAD` and the per-worktree namespaces (`refs/worktree/`, `refs/bisect/`,
+  // `refs/rewritten/`) are a worktree's own, kept loose in its git directory
+  // and never packed; everything else is the repository's.
+  const own = ref === 'HEAD' || PER_WORKTREE.test(ref);
+  const loose = await readLooseRef(dirs, own ? dirs.gitDir : dirs.commonDir, ref, depth);
+  if (loose !== 'missing') return decidedHere(ref, loose);
+  if (own) return 'missing';
+  const packed = await (dirs.packed ??= readPackedRefs(dirs.commonDir));
+  if (!packed) return 'unreadable';
+  const sha = packed.get(ref);
+  return sha ? decidedHere(ref, { sha }) : 'missing';
+}
+
+/**
+ * The files decide only where git itself guarantees the object is a commit:
+ * `HEAD` and `refs/heads/*`, which git refuses to point at anything else,
+ * and `refs/remotes/*`, fetched from a remote's `refs/heads/*` under the
+ * same refusal. Anything else that exists — a tag, a ref directly under
+ * `refs/` — may name a tree or a blob, which only git's `^{commit}` refuses,
+ * so it is git's to resolve. Anything that does not exist is as missing as
+ * any other ref, so a short name can move on to the branch git would find
+ * next.
+ */
+function decidedHere(ref: string, answer: RefFileAnswer): RefFileAnswer {
+  if (answer !== 'missing' && answer !== 'unreadable' && !commitGuaranteed(ref)) return 'unreadable';
+  return answer;
+}
+
+function commitGuaranteed(ref: string): boolean {
+  return ref === 'HEAD' || ref.startsWith('refs/heads/') || ref.startsWith('refs/remotes/');
+}
+
+/**
+ * The commit a full ref name (`refs/...`) or `HEAD` points at in the
+ * repository behind `repoDir` (a clone, or a worktree of one). See the module
+ * doc for the three answers and what each means to the caller.
+ *
+ * "Missing" is what `rev-parse` answers nothing for, and `rev-parse` tries
+ * the same prefixes for a full name as for a short one (`refs/heads/x` is
+ * also looked for as `refs/heads/refs/heads/x`), so a name that is missing
+ * as itself but present under a prefix is git's to resolve.
+ */
+export async function readRefSha(repoDir: string, ref: string): Promise<RefFileAnswer> {
+  const dirs = await gitDirsOf(repoDir);
+  if (!dirs) return 'unreadable';
+  const exact = await resolveIn(dirs, ref, 0);
+  if (exact !== 'missing') return exact;
+  for (const name of prefixedCandidates(ref)) {
+    if ((await resolveIn(dirs, name, 0)) !== 'missing') return 'unreadable';
+  }
+  return 'missing';
+}
+
+/**
+ * The names `git rev-parse` tries for `<name>` after `$GIT_DIR/<name>`
+ * itself, in git's order (gitrevisions(7)): `refs/<name>`,
+ * `refs/tags/<name>`, `refs/heads/<name>`, `refs/remotes/<name>`,
+ * `refs/remotes/<name>/HEAD`. The same for every spelling, a full `refs/...`
+ * name included.
+ */
+function prefixedCandidates(name: string): string[] {
+  return [`refs/${name}`, `refs/tags/${name}`, `refs/heads/${name}`, `refs/remotes/${name}`, `refs/remotes/${name}/HEAD`];
+}
+
+/**
+ * Every name `git rev-parse` tries for a spelling, in git's order: the
+ * spelling itself at `$GIT_DIR/<name>` (which for `HEAD` and a full
+ * `refs/...` name is the ref file), then the prefixed forms. Null for a
+ * spelling this reader does not resolve — an object id or its abbreviation,
+ * a `<rev>^{...}` or `@{...}` form, an empty or option-looking name — which
+ * the caller sends to git.
+ */
+function refNameCandidates(ref: string): string[] | null {
+  if (!ref || ref.startsWith('-')) return null;
+  if (/[\^~:@{}\\\s]/.test(ref)) return null;
+  if (/^[0-9a-f]{4,64}$/i.test(ref)) return null;
+  // `main-worktree/<ref>` and `worktrees/<name>/<ref>` reach another
+  // worktree's own refs (gitrevisions(7)): git's to resolve.
+  if (/^(?:main-worktree|worktrees)\//.test(ref)) return null;
+  return [ref, ...prefixedCandidates(ref)];
+}
+
+/**
+ * {@link readRefSha} for a name as a caller holds it (`main`, `origin/main`,
+ * `HEAD`, `refs/heads/main`): the first of git's candidates that resolves,
+ * starting where git starts, at `$GIT_DIR/<name>` itself. Whatever is found
+ * there (`MERGE_HEAD`, `FETCH_HEAD`, `AUTO_MERGE`, which may name a tree) is
+ * git's to resolve; only its absence lets the `refs/` candidates be read.
+ * `'missing'` only when every candidate is missing; `'unreadable'` as soon
+ * as one cannot be decided, because the undecided one might be the one git
+ * would pick.
+ */
+export async function readRevSha(repoDir: string, rev: string): Promise<RefFileAnswer> {
+  const candidates = refNameCandidates(rev);
+  if (!candidates) return 'unreadable';
+  const dirs = await gitDirsOf(repoDir);
+  if (!dirs) return 'unreadable';
+  for (const name of candidates) {
+    const answer = name === rev ? await resolveAsItself(dirs, rev) : await resolveIn(dirs, name, 0);
+    if (answer !== 'missing') return answer;
+  }
+  return 'missing';
+}
+
+/**
+ * Git's first step for any spelling: `$GIT_DIR/<name>`. For `HEAD` and a
+ * full `refs/...` name that is the ref itself, read as such. For anything
+ * else it is a pseudoref (`MERGE_HEAD`, `AUTO_MERGE`, which may name a
+ * tree), and whatever exists there is git's to resolve.
+ */
+async function resolveAsItself(dirs: GitDirs, rev: string): Promise<RefFileAnswer> {
+  if (rev === 'HEAD' || rev.startsWith('refs/')) return resolveIn(dirs, rev, 0);
+  if (!isSafeRefName(`refs/${rev}`)) return 'unreadable';
+  try {
+    await fs.stat(path.join(dirs.gitDir, ...rev.split('/')));
+    return 'unreadable';
+  } catch (err) {
+    return isAbsence(err) ? 'missing' : 'unreadable';
+  }
+}

package/src/modules/mcp/__tests__/mcp-routes-harness.ts

@@ -2,6 +2,7 @@ import type { Server as HttpServer } from 'node:http';
 import type { RequestHandler } from 'express';
 import express from 'express';
 import { createMcpRoutes } from '../mcp.routes.js';
+import type { McpCallerKind } from '../mcp-auth.middleware.js';
 
 /**
  * The shared mount for every `createMcpRoutes` suite.
@@ -19,7 +20,8 @@ import { createMcpRoutes } from '../mcp.routes.js';
  */
 
 /**
- * Auth stand-in binding the user named by `x-test-user`, defaulting to user-A.
+ * Auth stand-in binding the user named by `x-test-user`, defaulting to user-A,
+ * and the credential kind named by `x-test-kind`, when one is.
  *
  * The header lets a suite act as a second user (the cross-user checks need
  * one); suites that never send it see the single fixed user their assertions
@@ -27,6 +29,10 @@ import { createMcpRoutes } from '../mcp.routes.js';
  */
 export const fakeAuth: RequestHandler = (req, _res, next) => {
   req.userId = (req.headers['x-test-user'] as string | undefined) ?? 'user-A';
+  // The credential kind the real middleware would have recognised, when a
+  // suite needs one (the page header is a session's alone).
+  const kind = req.headers['x-test-kind'] as McpCallerKind | undefined;
+  if (kind) req.mcpCallerKind = kind;
   next();
 };
 

package/src/modules/mcp/__tests__/mcp.routes.page.test.ts

@@ -0,0 +1,115 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import type { McpCaller } from '../mcp.service.js';
+import { closeMountedRoutes, mountMcpRoutes } from './mcp-routes-harness.js';
+
+/**
+ * The page a call comes from: an HTML page of the knowledge base whose script
+ * calls the viewer's tools through the app. The app names it in
+ * `X-Bevel-Page`, and only the app — a session — may: a key, an OAuth token or
+ * an internal token belongs to an agent with an Audit log row of its own.
+ */
+
+afterEach(async () => {
+  await closeMountedRoutes();
+  vi.restoreAllMocks();
+});
+
+function makeMcpService() {
+  const callers: McpCaller[] = [];
+  return {
+    callers,
+    createRequestServer: vi.fn(async (caller: McpCaller) => {
+      callers.push(caller);
+      const server = new Server({ name: 'stub', version: '0' }, { capabilities: { tools: {} } });
+      server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: [] }));
+      return server;
+    }),
+    recordPageRefusal: vi.fn(async () => {}),
+  };
+}
+
+const TOOLS_LIST = { jsonrpc: '2.0', id: 1, method: 'tools/list', params: {} };
+const PAGE = 'Dashboards/Road map — Q4.html';
+
+function post(baseUrl: string, path: string, body: unknown, headers: Record<string, string>) {
+  return fetch(`${baseUrl}/api${path}`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json', Accept: 'application/json, text/event-stream', ...headers },
+    body: JSON.stringify(body),
+  });
+}
+
+describe('POST /mcp with X-Bevel-Page', () => {
+  it("hands a session's page to the service, decoded", async () => {
+    const mcpService = makeMcpService();
+    const baseUrl = await mountMcpRoutes({ mcpService });
+    const res = await post(baseUrl, '/mcp', TOOLS_LIST, { 'x-test-kind': 'session', 'x-bevel-page': encodeURIComponent(PAGE) });
+    expect(res.status).toBe(200);
+    expect(mcpService.callers[0]).toMatchObject({ userId: 'user-A', page: PAGE });
+  });
+
+  it.each(['key', 'oauth', 'internal'])('refuses the header from a %s caller, building nothing', async (kind) => {
+    const mcpService = makeMcpService();
+    const baseUrl = await mountMcpRoutes({ mcpService });
+    const res = await post(baseUrl, '/mcp', TOOLS_LIST, { 'x-test-kind': kind, 'x-bevel-page': encodeURIComponent(PAGE) });
+    expect(res.status).toBe(400);
+    expect(((await res.json()) as { error: { message: string } }).error.message).toContain('X-Bevel-Page');
+    expect(mcpService.createRequestServer).not.toHaveBeenCalled();
+  });
+
+  it('refuses a page that is not a path', async () => {
+    const mcpService = makeMcpService();
+    const baseUrl = await mountMcpRoutes({ mcpService });
+    const res = await post(baseUrl, '/mcp', TOOLS_LIST, { 'x-test-kind': 'session', 'x-bevel-page': encodeURIComponent('a\nb') });
+    expect(res.status).toBe(400);
+  });
+
+  it('names no page when the header is absent, as before', async () => {
+    const mcpService = makeMcpService();
+    const baseUrl = await mountMcpRoutes({ mcpService });
+    await post(baseUrl, '/mcp', TOOLS_LIST, { 'x-test-kind': 'session' });
+    expect(mcpService.callers[0]).not.toHaveProperty('page');
+  });
+});
+
+describe('POST /mcp/page-refusals', () => {
+  it("records a session's refused call under its page", async () => {
+    const mcpService = makeMcpService();
+    const baseUrl = await mountMcpRoutes({ mcpService });
+    const res = await post(
+      baseUrl,
+      '/mcp/page-refusals',
+      { page: PAGE, tool: 'edit_file', args: { body: { path: 'a.md' } } },
+      { 'x-test-kind': 'session', Authorization: 'Bearer eyJ.session' },
+    );
+    expect(res.status).toBe(204);
+    expect(mcpService.recordPageRefusal).toHaveBeenCalledWith(
+      { userId: 'user-A', bearer: 'eyJ.session' },
+      PAGE,
+      'edit_file',
+      { body: { path: 'a.md' } },
+    );
+  });
+
+  it('is the app\'s alone: an agent credential is refused', async () => {
+    const mcpService = makeMcpService();
+    const baseUrl = await mountMcpRoutes({ mcpService });
+    const res = await post(baseUrl, '/mcp/page-refusals', { page: PAGE, tool: 'edit_file' }, { 'x-test-kind': 'key' });
+    expect(res.status).toBe(403);
+    expect(mcpService.recordPageRefusal).not.toHaveBeenCalled();
+  });
+
+  it('wants a page and a tool', async () => {
+    const mcpService = makeMcpService();
+    const baseUrl = await mountMcpRoutes({ mcpService });
+    const res = await post(baseUrl, '/mcp/page-refusals', { tool: 'edit_file' }, { 'x-test-kind': 'session' });
+    expect(res.status).toBe(400);
+    for (const tool of [undefined, '']) {
+      const noTool = await post(baseUrl, '/mcp/page-refusals', { page: PAGE, tool }, { 'x-test-kind': 'session' });
+      expect(noTool.status).toBe(400);
+    }
+    expect(mcpService.recordPageRefusal).not.toHaveBeenCalled();
+  });
+});