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

package/src/modules/audit/audit.routes.ts

@@ -0,0 +1,168 @@
+import express from 'express';
+import { logger } from '../../shared/logging.js';
+import type { IAdminAccessService } from '../admin/admin.interface.js';
+import { TokenNotFoundError } from '../tool-auth/external-api-key.errors.js';
+import type { IExternalApiKeyService } from '../tool-auth/external-api-key.interface.js';
+import {
+  AuditPrincipalNotFoundError,
+  InvalidCursorError,
+  isUuid,
+  type AuditPrincipalRef,
+  type IAgentAuditService,
+} from './audit.contract.js';
+import { MAX_EVENT_PAGE } from './agent-audit.service.js';
+import '../auth/auth.middleware.js'; // Express Request augmentation (req.userId / req.userEmail)
+
+const log = logger('audit');
+
+const DEFAULT_EVENT_PAGE = 50;
+
+/**
+ * The Audit log's routes, JWT-only (mounted behind the session middleware):
+ *
+ *   GET    /api/audit/principals?scope=me|all           — agents + keys, with owners and event counts
+ *   GET    /api/audit/principals/:kind/:id/events        — one principal's events, newest first, cursor-paged
+ *   DELETE /api/audit/agents/:id                         — revoke an agent (owner or admin)
+ *   DELETE /api/audit/keys/:id                           — revoke a key (owner or admin)
+ *
+ * Everyone may read and revoke their OWN rows; `scope=all` and anyone else's
+ * rows are admins' (per request, through {@link IAdminAccessService}). Both
+ * revokes are recorded as the owner's or an admin's doing, so the owner's
+ * page can say which. Keys keep their existing per-user and admin routes;
+ * the one here exists so the page has a single client for both kinds.
+ */
+export function createAuditRoutes(
+  audit: IAgentAuditService,
+  keys: Pick<IExternalApiKeyService, 'revoke' | 'revokeAny'>,
+  adminAccess: IAdminAccessService,
+): express.Router {
+  const router = express.Router();
+
+  const isAdmin = (req: express.Request) => adminAccess.isAdmin(req.userEmail);
+
+  /** The principal named by the URL, or null when it names none (a malformed id is a not-found, not a 500). */
+  const principalOf = (req: express.Request): AuditPrincipalRef | null => {
+    const kind = String(req.params.kind);
+    const id = String(req.params.id);
+    if ((kind !== 'key' && kind !== 'agent') || !isUuid(id)) return null;
+    return { kind, id };
+  };
+
+  /** Whether the caller may read or revoke `principal`: its owner, or an admin. Null when there is no such principal. */
+  const mayAct = async (req: express.Request, principal: AuditPrincipalRef): Promise<boolean | null> => {
+    const owner = await audit.ownerOf(principal);
+    if (owner === null) return null;
+    if (owner === req.userId) return true;
+    return isAdmin(req);
+  };
+
+  router.get('/audit/principals', async (req, res) => {
+    try {
+      const all = req.query.scope === 'all';
+      if (all && !(await isAdmin(req))) {
+        res.status(403).json({ error: 'Admins only' });
+        return;
+      }
+      const principals = await audit.listPrincipals(all ? 'all' : { userId: req.userId! });
+      res.json({ principals });
+    } catch (err) {
+      log.error('list principals failed:', { err });
+      res.status(500).json({ error: 'Failed to load the audit log' });
+    }
+  });
+
+  router.get('/audit/principals/:kind/:id/events', async (req, res) => {
+    const principal = principalOf(req);
+    if (!principal) {
+      res.status(404).json({ error: 'No such agent or key' });
+      return;
+    }
+    try {
+      const allowed = await mayAct(req, principal);
+      if (allowed === null) {
+        res.status(404).json({ error: 'No such agent or key' });
+        return;
+      }
+      if (!allowed) {
+        res.status(403).json({ error: 'Not yours' });
+        return;
+      }
+      const rawLimit = Number(req.query.limit);
+      const limit = Number.isFinite(rawLimit) && rawLimit > 0 ? Math.min(rawLimit, MAX_EVENT_PAGE) : DEFAULT_EVENT_PAGE;
+      const before = typeof req.query.before === 'string' && req.query.before ? req.query.before : undefined;
+      res.json(await audit.listEvents(principal, { before, limit }));
+    } catch (err) {
+      if (err instanceof InvalidCursorError) {
+        res.status(400).json({ error: 'Invalid cursor — reload the events from the start' });
+        return;
+      }
+      log.error('list events failed:', { err });
+      res.status(500).json({ error: 'Failed to load events' });
+    }
+  });
+
+  router.delete('/audit/agents/:id', async (req, res) => {
+    const id = String(req.params.id);
+    if (!isUuid(id)) {
+      res.status(404).json({ error: 'No such agent' });
+      return;
+    }
+    try {
+      // Own connection: the owner's revoke, recorded as theirs — an admin
+      // cutting off their OWN agent disconnected it, and the row must not
+      // tell them an admin took it. Anyone else's: only an admin may, and it
+      // is recorded as an admin's so the owner is told. Same order as keys.
+      const owner = await audit.ownerOf({ kind: 'agent', id });
+      if (owner === req.userId) {
+        await audit.revokeConnection(id, 'owner', req.userId!);
+      } else if (await isAdmin(req)) {
+        await audit.revokeConnection(id, 'admin');
+        log.info('revoke audit:', { action: 'admin-revoke-agent', actorUserId: req.userId, connectionId: id });
+      } else {
+        res.status(owner === null ? 404 : 403).json({ error: owner === null ? 'No such agent' : 'Not yours' });
+        return;
+      }
+      res.json({ status: 'revoked' });
+    } catch (err) {
+      if (err instanceof AuditPrincipalNotFoundError) {
+        res.status(404).json({ error: err.message });
+        return;
+      }
+      log.error('revoke agent failed:', { err });
+      res.status(500).json({ error: 'Failed to revoke this agent' });
+    }
+  });
+
+  router.delete('/audit/keys/:id', async (req, res) => {
+    const id = String(req.params.id);
+    if (!isUuid(id)) {
+      res.status(404).json({ error: 'Token not found' });
+      return;
+    }
+    try {
+      const admin = await isAdmin(req);
+      // Own key: the owner's revoke (recorded as theirs). Anyone else's: only
+      // an admin may, and it is recorded as an admin's so the owner is told.
+      const owner = await audit.ownerOf({ kind: 'key', id });
+      if (owner === req.userId) {
+        await keys.revoke(id, req.userId!);
+      } else if (admin) {
+        await keys.revokeAny(id);
+        log.info('revoke audit:', { action: 'admin-revoke-key', actorUserId: req.userId, tokenId: id });
+      } else {
+        res.status(owner === null ? 404 : 403).json({ error: owner === null ? 'Token not found' : 'Not yours' });
+        return;
+      }
+      res.json({ status: 'revoked' });
+    } catch (err) {
+      if (err instanceof TokenNotFoundError) {
+        res.status(404).json({ error: err.message });
+        return;
+      }
+      log.error('revoke key failed:', { err });
+      res.status(500).json({ error: 'Failed to revoke this key' });
+    }
+  });
+
+  return router;
+}

package/src/modules/audit/event-classifier.ts

@@ -0,0 +1,155 @@
+import type { AgentEventKind } from './audit.contract.js';
+
+/**
+ * Pure classification of one UTCP tool call into what the Audit log records:
+ * a hexis capability, a manual's tool, or a skill read. No I/O — the one
+ * catalog it may need (the skill folders) is handed in by the caller, which
+ * asks {@link skillReadPath} first whether that catalog is worth fetching.
+ */
+
+/** What a call is logged as: the kind, the manual (or skill folder), and the bare name. */
+export interface ClassifiedCall {
+  kind: AgentEventKind;
+  manual: string | null;
+  name: string;
+}
+
+/** A skill as the classifier needs it: its name and its repo-relative folder. */
+export interface SkillFolder {
+  name: string;
+  path: string;
+}
+
+export interface ClassifierContext {
+  /** The registered name of the platform's own manual (`KNOWLEDGE_BASE`). */
+  kbManualName: string;
+  /** Registered (rewritten) manual name → catalog name, for pooled MCP manuals. */
+  catalogNames: ReadonlyMap<string, string>;
+}
+
+/**
+ * The platform tools whose `path` argument may point INTO a skill folder — a
+ * read of `Plugins/Sales/rfi/SKILL.md` or of a file bundled beside it is the
+ * agent reading that skill, and is logged as such rather than as a file read.
+ */
+const SKILL_FOLDER_READ_TOOLS: ReadonlySet<string> = new Set(['read_file', 'grep', 'list_files']);
+
+/** The platform tool that loads a skill by name. */
+const GET_SKILL = 'get_skill';
+
+/** `<manual>.<tool>` → its two halves; a bare name has no manual. */
+export function splitUtcpName(utcpName: string): { manual: string; tool: string } {
+  const dot = utcpName.indexOf('.');
+  return dot < 0
+    ? { manual: '', tool: utcpName }
+    : { manual: utcpName.slice(0, dot), tool: utcpName.slice(dot + 1) };
+}
+
+/**
+ * The `path` a platform tool was called with, wherever the caller put it.
+ * Bevel-hosted http tools take their arguments inside a `body` envelope
+ * (`{ body: { path } }`); a caller that flattened it (`{ path }`) is read too.
+ */
+function pathArgument(args: Record<string, unknown>): string | null {
+  const body = args.body;
+  const inner = body && typeof body === 'object' ? (body as Record<string, unknown>).path : undefined;
+  const candidate = typeof inner === 'string' ? inner : args.path;
+  return typeof candidate === 'string' && candidate.length > 0 ? candidate : null;
+}
+
+/** The `name` a `get_skill` call asked for, from the envelope or flattened. */
+function skillNameArgument(args: Record<string, unknown>): string | null {
+  const body = args.body;
+  const inner = body && typeof body === 'object' ? (body as Record<string, unknown>).name : undefined;
+  const candidate = typeof inner === 'string' ? inner : args.name;
+  return typeof candidate === 'string' && candidate.length > 0 ? candidate : null;
+}
+
+/**
+ * When a platform read names a path, the path — the signal that the caller
+ * should fetch the skill catalog before classifying (a folder match turns
+ * the read into a skill event). Null for every other call, so the catalog is
+ * never fetched for a `notion.search` or a `write_file`.
+ */
+export function skillReadPath(utcpName: string, args: Record<string, unknown>, kbManualName: string): string | null {
+  const { manual, tool } = splitUtcpName(utcpName);
+  if (manual !== kbManualName) return null;
+  if (tool === GET_SKILL) return skillNameArgument(args) === null ? null : '';
+  if (!SKILL_FOLDER_READ_TOOLS.has(tool)) return null;
+  return pathArgument(args);
+}
+
+/**
+ * The path as segments, resolved: forward slashes, `.` dropped, `..` taken
+ * back a segment, no empty segments — so two spellings of one place compare
+ * equal, and a path that climbs OUT of a folder is never matched to it. A
+ * path that climbs above its own start has no place at all and resolves to
+ * the empty string, which matches nothing. (The file tools refuse `..`
+ * outright; the log must still not credit a refused read to a skill.)
+ */
+function normalizePath(p: string): string {
+  const out: string[] = [];
+  for (const segment of p.replace(/\\/g, '/').split('/')) {
+    if (segment === '' || segment === '.') continue;
+    if (segment === '..') {
+      if (out.length === 0) return '';
+      out.pop();
+      continue;
+    }
+    out.push(segment);
+  }
+  return out.join('/');
+}
+
+/**
+ * The skill whose folder contains `path`, if any. Matched on a segment
+ * boundary anywhere in the path — a caller may spell the path from the
+ * repository root (`Plugins/Sales/rfi/SKILL.md`) or from one level above it
+ * (`knowledge-base/Plugins/Sales/rfi/SKILL.md`), and both are that skill.
+ * The longest folder wins, so a skill nested under another's folder is not
+ * mistaken for its parent.
+ */
+export function skillContaining(path: string, skills: readonly SkillFolder[]): SkillFolder | null {
+  const normalized = normalizePath(path);
+  if (!normalized) return null;
+  const haystack = `/${normalized}/`;
+  let best: SkillFolder | null = null;
+  for (const skill of skills) {
+    const folder = normalizePath(skill.path);
+    if (!folder) continue;
+    if (haystack.includes(`/${folder}/`) && (!best || folder.length > normalizePath(best.path).length)) {
+      best = skill;
+    }
+  }
+  return best;
+}
+
+/**
+ * Classify one call. `skills` is the catalog when {@link skillReadPath} asked
+ * for it and the caller could fetch it; null otherwise (the read is then
+ * logged as the capability it is, which is the honest fallback).
+ */
+export function classifyToolCall(
+  utcpName: string,
+  args: Record<string, unknown>,
+  ctx: ClassifierContext,
+  skills: readonly SkillFolder[] | null,
+): ClassifiedCall {
+  const { manual, tool } = splitUtcpName(utcpName);
+  // A meta-tool (`call_tool_chain`, `list_tools`, …) has no manual: the platform's own.
+  if (manual === '' || manual === ctx.kbManualName) {
+    if (tool === GET_SKILL) {
+      const name = skillNameArgument(args);
+      if (name) {
+        const folder = skills?.find((s) => s.name === name)?.path ?? null;
+        return { kind: 'skill', manual: folder, name };
+      }
+    } else if (SKILL_FOLDER_READ_TOOLS.has(tool) && skills) {
+      const path = pathArgument(args);
+      const skill = path ? skillContaining(path, skills) : null;
+      if (skill) return { kind: 'skill', manual: skill.path, name: skill.name };
+    }
+    return { kind: 'capability', manual: null, name: tool };
+  }
+  return { kind: 'tool', manual: ctx.catalogNames.get(manual) ?? manual, name: tool };
+}

package/src/modules/audit/index.ts

@@ -0,0 +1,14 @@
+export * from './audit.contract.js';
+export { AgentAuditService, MAX_EVENT_PAGE, retentionDaysFrom } from './agent-audit.service.js';
+export { createAgentRestAuditMiddleware } from './agent-rest-audit.middleware.js';
+export { createAuditRoutes } from './audit.routes.js';
+export { RequestAudit } from './request-audit.js';
+export {
+  classifyToolCall,
+  skillContaining,
+  skillReadPath,
+  splitUtcpName,
+  type ClassifiedCall,
+  type ClassifierContext,
+  type SkillFolder,
+} from './event-classifier.js';

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

@@ -0,0 +1,141 @@
+import type { CodeModeUtcpClient } from '@utcp/code-mode';
+import { logger } from '../../shared/logging.js';
+import type { AgentEventOutcome, AuditPrincipalRef, IAgentEventRecorder } from './audit.contract.js';
+import {
+  classifyToolCall,
+  skillReadPath,
+  type ClassifiedCall,
+  type ClassifierContext,
+  type SkillFolder,
+} from './event-classifier.js';
+
+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.
+ *
+ * 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
+ * a platform read names a path.
+ */
+export class RequestAudit {
+  private skills: Promise<readonly SkillFolder[] | null> | undefined;
+
+  constructor(
+    private readonly recorder: IAgentEventRecorder,
+    private readonly userId: string,
+    private readonly principal: AuditPrincipalRef,
+    private readonly ctx: {
+      kbManualName: string;
+      /** Read at classification time — the surface (and its catalog names) is built lazily. */
+      catalogNames: () => ReadonlyMap<string, string>;
+      /** The caller's skill catalog, for telling a skill read from a file read. */
+      loadSkills: () => Promise<readonly SkillFolder[]>;
+    },
+  ) {}
+
+  /** Record one already-classified call. Never throws. */
+  emit(call: ClassifiedCall, outcome: AgentEventOutcome, durationMs: number | null): void {
+    try {
+      this.recorder.record({
+        userId: this.userId,
+        principal: this.principal,
+        kind: call.kind,
+        manual: call.manual,
+        name: call.name,
+        outcome,
+        durationMs,
+      });
+    } catch (err) {
+      log.warn('recording an agent event failed:', { err });
+    }
+  }
+
+  /** What a UTCP call is logged as — fetching the skill catalog first when the call might be a skill read. */
+  async classify(utcpName: string, args: Record<string, unknown>): Promise<ClassifiedCall> {
+    const ctx: ClassifierContext = { kbManualName: this.ctx.kbManualName, catalogNames: this.ctx.catalogNames() };
+    const wantsSkills = skillReadPath(utcpName, args, ctx.kbManualName) !== null;
+    const skills = wantsSkills ? await this.skillCatalog() : null;
+    return classifyToolCall(utcpName, args, ctx, skills);
+  }
+
+  /**
+   * Run a UTCP call and record it: `error` when it throws or `isError` says
+   * the result is one, `ok` otherwise. The result (or the throw) reaches the
+   * caller unchanged — recording is a side effect, never a filter.
+   *
+   * The call starts FIRST and is classified alongside: naming a read may cost
+   * a loopback fetch of the skill catalog, and that is the log's business,
+   * not the tool's — a tool result never waits on its own bookkeeping.
+   */
+  async call<T>(
+    utcpName: string,
+    args: Record<string, unknown>,
+    run: () => Promise<T>,
+    isError: (result: T) => boolean,
+  ): Promise<T> {
+    const started = performance.now();
+    const classified = this.classify(utcpName, args);
+    try {
+      const result = await run();
+      const duration = elapsed(started);
+      this.emit(await classified, isError(result) ? 'error' : 'ok', duration);
+      return result;
+    } catch (err) {
+      const duration = elapsed(started);
+      this.emit(await classified, 'error', duration);
+      throw err;
+    }
+  }
+
+  /** 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);
+  }
+
+  /**
+   * Record every tool call made from INSIDE `call_tool_chain`: the chain
+   * bridges each in-isolate tool function to `client.callTool`, so wrapping
+   * that one entry point catches them all. Installed after the downstream
+   * routing wrapper so the timing covers the pool lease and any retry too.
+   * The direct MCP path (`callToolStreaming`) is deliberately NOT wrapped —
+   * the proxy's tool handler records those itself, with the result's
+   * `isError` in hand.
+   */
+  instrumentChainCalls(client: CodeModeUtcpClient): void {
+    const callTool = client.callTool.bind(client);
+    client.callTool = (toolName: string, toolArgs: Record<string, unknown>) =>
+      this.call(toolName, toolArgs, () => callTool(toolName, toolArgs), isErrorShaped);
+  }
+
+  private skillCatalog(): Promise<readonly SkillFolder[] | null> {
+    // A failed fetch is remembered as "no catalog" for the rest of the
+    // request: the read is then logged as a capability, and one hiccup does
+    // not cost a loopback round-trip per subsequent call.
+    this.skills ??= this.ctx.loadSkills().catch((err) => {
+      log.warn('skill catalog unavailable for audit classification:', { err });
+      return null;
+    });
+    return this.skills;
+  }
+}
+
+function elapsed(started: number): number {
+  return Math.max(0, Math.round(performance.now() - started));
+}
+
+/**
+ * A chain-internal result that is the tool saying it failed. A downstream
+ * MCP server answers a failed call with `{ isError: true, content }` as a
+ * VALUE (the UTCP mcp protocol hands it through rather than throwing), and
+ * the direct path records that as an error — so must the chain path, or the
+ * same failure would read `ok` inside a chain and `error` outside one.
+ */
+function isErrorShaped(result: unknown): boolean {
+  return typeof result === 'object' && result !== null && (result as { isError?: unknown }).isError === true;
+}