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

package/src/modules/audit/request-audit.ts

@@ -1,6 +1,6 @@
 import type { CodeModeUtcpClient } from '@utcp/code-mode';
 import { logger } from '../../shared/logging.js';
-import type { AgentEventOutcome, AuditPrincipalRef, IAgentEventRecorder } from './audit.contract.js';
+import type { AgentEventOutcome, IAgentEventRecorder, RecordedPrincipal } from './audit.contract.js';
 import {
   classifyToolCall,
   skillReadPath,
@@ -13,11 +13,11 @@ const log = logger('audit');
 
 /**
  * The Audit log's view of ONE MCP request: who is calling (the user and the
- * key or agent connection the request arrived through), and how to name what
- * they call. The MCP proxy creates one per request that has a principal and
- * routes every call through it; a request with none (a browser JWT, an
- * internal token minted before connections existed) gets no instance and
- * records nothing.
+ * key, agent connection or page the request arrived through), and how to name
+ * what they call. The MCP proxy creates one per request that has a principal
+ * and routes every call through it; a request with none (a browser JWT that
+ * names no page, an internal token minted before connections existed) gets no
+ * instance and records nothing.
  *
  * Holds nothing that outlives the request. The skill catalog it may need to
  * tell a skill read from a file read is fetched at most once, and only when
@@ -29,7 +29,7 @@ export class RequestAudit {
   constructor(
     private readonly recorder: IAgentEventRecorder,
     private readonly userId: string,
-    private readonly principal: AuditPrincipalRef,
+    private readonly principal: RecordedPrincipal,
     private readonly ctx: {
       kbManualName: string;
       /** Read at classification time — the surface (and its catalog names) is built lazily. */
@@ -93,9 +93,13 @@ export class RequestAudit {
     }
   }
 
-  /** A call refused before it ran, because the caller's sign-in for its manual is missing. */
-  async denied(utcpName: string, args: Record<string, unknown>): Promise<void> {
-    this.emit(await this.classify(utcpName, args), 'denied', null);
+  /**
+   * A call refused before it ran: `denied` when the caller's sign-in for its
+   * manual is missing, `refused` when the person viewing a page answered its
+   * request to write with Deny.
+   */
+  async denied(utcpName: string, args: Record<string, unknown>, outcome: 'denied' | 'refused' = 'denied'): Promise<void> {
+    this.emit(await this.classify(utcpName, args), outcome, null);
   }
 
   /**
@@ -106,11 +110,22 @@ export class RequestAudit {
    * The direct MCP path (`callToolStreaming`) is deliberately NOT wrapped —
    * the proxy's tool handler records those itself, with the result's
    * `isError` in hand.
+   *
+   * Installed ONCE, when the client is built, because the client is shared by
+   * every request of its person: `current` names the request a call belongs
+   * to, at call time, and a call outside any request (or in one attributed to
+   * nothing) is recorded nowhere. Rebinding the client per request instead
+   * would hand one request's calls to another's audit, and stack a wrapper
+   * per request.
    */
-  instrumentChainCalls(client: CodeModeUtcpClient): void {
+  static instrumentChainCalls(client: CodeModeUtcpClient, current: () => RequestAudit | null | undefined): void {
     const callTool = client.callTool.bind(client);
-    client.callTool = (toolName: string, toolArgs: Record<string, unknown>) =>
-      this.call(toolName, toolArgs, () => callTool(toolName, toolArgs), isErrorShaped);
+    client.callTool = (toolName: string, toolArgs: Record<string, unknown>) => {
+      const audit = current();
+      return audit
+        ? audit.call(toolName, toolArgs, () => callTool(toolName, toolArgs), isErrorShaped)
+        : callTool(toolName, toolArgs);
+    };
   }
 
   private skillCatalog(): Promise<readonly SkillFolder[] | null> {

package/src/modules/database/core-schema.ts

@@ -589,22 +589,30 @@ export const oauthTokens = pgTable('oauth_tokens', {
  * which agent, when" — not "what was said".
  *
  * Exactly one principal per row (the CHECK): the connection key or the agent
- * connection the call arrived through. Both cascade, so deleting a key for
- * good, revoking-then-erasing a person, or dropping a connection takes its
- * events along — the same contract the LLM-usage rows already keep.
+ * connection the call arrived through, or the knowledge-base page whose
+ * script made the call as the person viewing it (`page_path`). Key and
+ * connection cascade, so deleting a key for good, revoking-then-erasing a
+ * person, or dropping a connection takes its events along — the same contract
+ * the LLM-usage rows already keep; a page's events go with the person.
  */
 export const agentEvents = pgTable('agent_events', {
   id: uuid('id').defaultRandom().primaryKey(),
   userId: uuid('user_id').notNull().references(() => users.id, { onDelete: 'cascade' }),
   keyId: uuid('key_id').references(() => externalApiKeys.id, { onDelete: 'cascade' }),
   connectionId: uuid('connection_id').references(() => agentConnections.id, { onDelete: 'cascade' }),
+  /** The knowledge-base path of the HTML page that made the call, for a page's calls; null otherwise. */
+  pagePath: text('page_path'),
   /** `capability` | `tool` | `skill`. */
   kind: text('kind').notNull(),
   /** The MCP server / `.tool` manual (catalog name) for a tool, the skill folder for a skill; null for a capability. */
   manual: text('manual'),
   /** The tool's bare name, or the skill's name. */
   name: text('name').notNull(),
-  /** `ok` | `error` | `denied` (denied: the caller's sign-in for the tool was missing, so nothing ran). */
+  /**
+   * `ok` | `error` | `denied` | `refused`. Denied: the caller's sign-in for the
+   * tool was missing, so nothing ran. Refused: the viewer answered a page's
+   * request to write with Deny, so nothing ran.
+   */
   outcome: text('outcome').notNull(),
   durationMs: integer('duration_ms'),
   at: timestamp('at').defaultNow().notNull(),
@@ -612,14 +620,15 @@ export const agentEvents = pgTable('agent_events', {
   // The two read paths: one principal's events, newest first.
   byKey: index('agent_events_by_key').on(t.keyId, t.at),
   byConnection: index('agent_events_by_connection').on(t.connectionId, t.at),
+  byPage: index('agent_events_by_page').on(t.userId, t.pagePath, t.at),
   // The retention prune, and per-user counts.
   byAt: index('agent_events_by_at').on(t.at),
   byUser: index('agent_events_by_user').on(t.userId),
   kindCheck: check('agent_events_kind', sql`${t.kind} IN ('capability', 'tool', 'skill')`),
-  outcomeCheck: check('agent_events_outcome', sql`${t.outcome} IN ('ok', 'error', 'denied')`),
+  outcomeCheck: check('agent_events_outcome', sql`${t.outcome} IN ('ok', 'error', 'denied', 'refused')`),
   principalCheck: check(
     'agent_events_principal',
-    sql`(${t.keyId} IS NULL) <> (${t.connectionId} IS NULL)`,
+    sql`num_nonnulls(${t.keyId}, ${t.connectionId}, ${t.pagePath}) = 1`,
   ),
 }));
 

package/src/modules/kb-fs/__tests__/mutex.canonical.test.ts

@@ -0,0 +1,57 @@
+import { describe, it, expect } from 'vitest';
+import { WorkspaceIdMutex, WorkspaceMutex } from '../mutex.js';
+
+/**
+ * `WorkspaceIdMutex`: a workspace id in either spelling — a route's decoded
+ * `alice/feature`, a tool's `alice%2Ffeature` — takes the one key.
+ */
+describe('WorkspaceIdMutex', () => {
+  /** A task that signals when it starts and ends only when released. */
+  const held = () => {
+    let release: () => void = () => {};
+    let started: () => void = () => {};
+    const begun = new Promise<void>((r) => { started = r; });
+    const task = () =>
+      new Promise<void>((resolve) => {
+        release = resolve;
+        started();
+      });
+    return { task, begun, release: () => release() };
+  };
+  const settled = () => new Promise<void>((r) => setImmediate(r));
+
+  it('queues the decoded and the encoded spelling of one workspace on the same key', async () => {
+    const mutex = new WorkspaceIdMutex();
+    const first = held();
+    const order: string[] = [];
+    const a = mutex.run('alice/feature', first.task).then(() => { order.push('decoded'); });
+    await first.begun;
+    const b = mutex.run('alice%2Ffeature', async () => { order.push('encoded'); });
+    await settled();
+    // The encoded spelling waits on the decoded one's reservation: nothing
+    // has run until the first is released; then both do.
+    expect(order).toEqual([]);
+    first.release();
+    await Promise.all([a, b]);
+    expect([...order].sort()).toEqual(['decoded', 'encoded']);
+  });
+
+  it('is what the plain mutex is not: two spellings, two keys, no wait', async () => {
+    const mutex = new WorkspaceMutex();
+    const first = held();
+    const order: string[] = [];
+    const a = mutex.run('alice/feature', first.task).then(() => { order.push('decoded'); });
+    await first.begun;
+    await mutex.run('alice%2Ffeature', async () => { order.push('encoded'); });
+    expect(order).toEqual(['encoded']);
+    first.release();
+    await a;
+  });
+
+  it('leaves a protected branch (no slash, one spelling) and a malformed id as they are', async () => {
+    const mutex = new WorkspaceIdMutex();
+    const seen: string[] = [];
+    await mutex.runAll(['main', 'bad%'], async () => { seen.push('ran'); });
+    expect(seen).toEqual(['ran']);
+  });
+});

package/src/modules/kb-fs/index.ts

@@ -4,5 +4,6 @@
  * workspace needs only the shape of the gate every write passes first.
  */
 export type { WriteValidator } from './locking-filesystem.js';
+export { WorkspaceMutex, WorkspaceIdMutex } from './mutex.js';
 export { readRefSha, readRevSha, type RefFileAnswer } from './ref-files.js';
 export { gitDirOf, readGitfile } from './git-dir.js';

package/src/modules/kb-fs/locking-filesystem.ts

@@ -52,6 +52,7 @@ import { PushNeedsAgentResolutionError } from '../../shared/domain-errors.js';
 import type { FileChangeNotifier } from './file-change-notifier.js';
 import { isAbsence } from '../../shared/fs.contract.js';
 import { DestinationTakenError, lstatOrNull, renameNoReplace, takenError } from '../../shared/rename-no-replace.js';
+import { linkedAncestor } from '../../shared/no-link-below.js';
 import { assertInsideRepo } from './repo-path.js';
 import { GitGuardedFilesystem } from './git-guarded-filesystem.js';
 import type { CreationGrantPlan, ICreatorAccess } from '../access-model/creator.js';
@@ -644,18 +645,8 @@ export class LockingFilesystem extends GitGuardedFilesystem {
   private async assertNoLinkBelowBase(inputPath: string): Promise<void> {
     const absolute = this.resolveAbsolutePath(inputPath);
     if (!absolute) return;
-    const base = path.resolve(this.basePath);
-    let current = path.resolve(absolute);
-    const ancestors: string[] = [];
-    while (current.startsWith(base) && current !== base) {
-      ancestors.push(current);
-      current = path.dirname(current);
-    }
-    for (const ancestor of ancestors) {
-      const stat = await lstatOrNull(ancestor);
-      if (stat?.isSymbolicLink()) {
-        throw new Error(`"${inputPath}" is reached through a link, so nothing was moved.`);
-      }
+    if ((await linkedAncestor(this.basePath, absolute)) !== null) {
+      throw new Error(`"${inputPath}" is reached through a link, so nothing was moved.`);
     }
   }
 

package/src/modules/kb-fs/mutex.ts

@@ -1,3 +1,5 @@
+import { canonicalWorkspaceId } from '../../shared/workspace-id.js';
+
 /**
  * Serializes async operations by key. Two `run(k, ...)` calls with the same key
  * execute sequentially in call order; different keys run independently.
@@ -65,3 +67,17 @@ export class WorkspaceMutex {
     }
   }
 }
+
+/**
+ * A `WorkspaceMutex` whose keys are WORKSPACE IDS, taken in their canonical
+ * spelling: a route's Express-decoded `:id` (`alice/feature`) and a tool's
+ * `alice%2Ffeature` name the same clone and must queue on the same key — two
+ * spellings would let a route's read run beside a tool's merge of the same
+ * checkout. `canonicalWorkspaceId` collapses both to the encoded form every
+ * other keyed store (the file locks, the pending commits) already uses.
+ */
+export class WorkspaceIdMutex extends WorkspaceMutex {
+  override async runAll<T>(keys: string[], fn: () => Promise<T>): Promise<T> {
+    return super.runAll(keys.map(canonicalWorkspaceId), fn);
+  }
+}

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();
+  });
+});