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

package/src/modules/audit/__tests__/agent-audit.service.test.ts

@@ -0,0 +1,370 @@
+/* eslint-disable @typescript-eslint/no-explicit-any -- the fake drizzle chain below is untyped by design, like its siblings */
+import { describe, expect, it, vi } from 'vitest';
+import type { SQL } from 'drizzle-orm';
+import { PgDialect } from 'drizzle-orm/pg-core';
+import { AgentAuditService, retentionDaysFrom } from '../agent-audit.service.js';
+import { AuditPrincipalNotFoundError, InvalidCursorError } from '../audit.contract.js';
+import type { Database } from '../../database/connection.js';
+import { agentConnections, oauthTokens } from '../../database/schema.js';
+import type { IExternalApiKeyService } from '../../tool-auth/external-api-key.interface.js';
+
+/**
+ * The fake drizzle chain the other service tests use: every chainable method
+ * returns the chain, the chain is thenable, and each `db.insert / select /
+ * update / delete` pops the next queued result. `transaction` runs its
+ * callback against the same fake, so queued results are consumed in order.
+ * Every `where` predicate and `update` target is captured, so a test can pin
+ * WHICH rows a statement addressed (see {@link render}), not just that it ran.
+ */
+function makeFakeDb(queue: unknown[]) {
+  const captured: { values: any[]; set: any[]; where: SQL[]; updateTargets: unknown[] } = {
+    values: [],
+    set: [],
+    where: [],
+    updateTargets: [],
+  };
+  const counts = { insert: 0, select: 0, update: 0, delete: 0 };
+
+  function nextChain() {
+    const result = queue.shift();
+    const chain: any = {};
+    const passthrough = (recorder?: (args: any[]) => void) =>
+      vi.fn((...args: any[]) => {
+        recorder?.(args);
+        return chain;
+      });
+    chain.values = passthrough((a) => captured.values.push(a[0]));
+    chain.set = passthrough((a) => captured.set.push(a[0]));
+    chain.where = passthrough((a) => captured.where.push(a[0]));
+    chain.limit = passthrough();
+    chain.innerJoin = passthrough();
+    chain.from = passthrough();
+    chain.orderBy = passthrough();
+    chain.groupBy = passthrough();
+    chain.returning = passthrough();
+    chain.then = (onF: any, onR: any) => Promise.resolve(result).then(onF, onR);
+    return chain;
+  }
+
+  const db: any = {
+    insert: vi.fn(() => (counts.insert++, nextChain())),
+    select: vi.fn(() => (counts.select++, nextChain())),
+    update: vi.fn((table: unknown) => (counts.update++, captured.updateTargets.push(table), nextChain())),
+    delete: vi.fn(() => (counts.delete++, nextChain())),
+    transaction: vi.fn((fn: (tx: any) => Promise<unknown>) => fn(db)),
+  };
+  return { db: db as Database, captured, counts };
+}
+
+/** A captured predicate as the SQL it would send, with its parameters. */
+function render(fragment: SQL | undefined): { sql: string; params: unknown[] } {
+  if (!fragment) return { sql: '', params: [] };
+  const q = new PgDialect().sqlToQuery(fragment);
+  return { sql: q.sql, params: q.params };
+}
+
+const ALICE = { id: 'u-alice', email: 'alice@example.com', name: 'Alice' };
+const BOB = { id: 'u-bob', email: 'bob@example.com', name: 'Bob' };
+const DAY = 24 * 60 * 60_000;
+const NOW = Date.UTC(2026, 8, 23, 12, 0, 0);
+
+const key = (over: object) => ({
+  id: 'k-1',
+  label: 'CI pipeline',
+  kind: 'key',
+  createdAt: NOW - 10 * DAY,
+  lastUsedAt: NOW - DAY,
+  revokedAt: null,
+  revokedBy: null,
+  ...over,
+});
+const connection = (over: object) => ({
+  id: 'c-1',
+  userId: ALICE.id,
+  clientId: 'client-claude',
+  clientName: 'Claude',
+  connectedAt: new Date(NOW - 5 * DAY),
+  lastUsedAt: new Date(NOW - 60_000),
+  revokedAt: null,
+  revokedBy: null,
+  ...over,
+});
+
+function makeService(queue: unknown[], keys: Partial<IExternalApiKeyService> = {}, retention: number | null = 90) {
+  const fake = makeFakeDb(queue);
+  const keyService = {
+    listForUser: vi.fn(async () => []),
+    listForDeployment: vi.fn(async () => []),
+    ownerOf: vi.fn(async () => null),
+    ...keys,
+  } as unknown as IExternalApiKeyService;
+  const service = new AgentAuditService(fake.db, keyService, () => retention, () => NOW);
+  return { service, ...fake, keyService };
+}
+
+/** Let the fire-and-forget insert (and whatever it schedules) settle. */
+const flush = () => new Promise((r) => setTimeout(r, 0));
+
+describe('AgentAuditService.record', () => {
+  it('inserts the event with exactly one principal column set and never throws to the caller', async () => {
+    const { service, captured } = makeService([undefined /* insert */]);
+    service.record({
+      userId: ALICE.id,
+      principal: { kind: 'key', id: 'k-1' },
+      kind: 'tool',
+      manual: 'notion',
+      name: 'search',
+      outcome: 'ok',
+      durationMs: 42,
+    });
+    await flush();
+    expect(captured.values[0]).toMatchObject({
+      userId: ALICE.id,
+      keyId: 'k-1',
+      connectionId: null,
+      kind: 'tool',
+      manual: 'notion',
+      name: 'search',
+      outcome: 'ok',
+      durationMs: 42,
+    });
+
+    const agent = makeService([undefined]);
+    agent.service.record({
+      userId: ALICE.id,
+      principal: { kind: 'agent', id: 'c-1' },
+      kind: 'skill',
+      manual: 'Plugins/Sales/rfi',
+      name: 'rfi',
+      outcome: 'ok',
+      durationMs: null,
+    });
+    await flush();
+    expect(agent.captured.values[0]).toMatchObject({ keyId: null, connectionId: 'c-1', kind: 'skill' });
+  });
+
+  it('prunes past the retention window once per hour, not on every insert', async () => {
+    const { service, counts } = makeService([undefined, undefined, undefined, undefined], {}, 30);
+    const event = {
+      userId: ALICE.id,
+      principal: { kind: 'key' as const, id: 'k-1' },
+      kind: 'capability' as const,
+      manual: null,
+      name: 'read_file',
+      outcome: 'ok' as const,
+      durationMs: 3,
+    };
+    service.record(event);
+    await flush();
+    expect(counts.delete).toBe(1); // the first insert sweeps
+    service.record(event);
+    await flush();
+    expect(counts.delete).toBe(1); // the second, a moment later, does not
+  });
+
+  it('sweeps nothing on a deployment that keeps events forever', async () => {
+    const { service, counts } = makeService([undefined], {}, null);
+    service.record({
+      userId: ALICE.id,
+      principal: { kind: 'key', id: 'k-1' },
+      kind: 'capability',
+      manual: null,
+      name: 'read_file',
+      outcome: 'ok',
+      durationMs: 3,
+    });
+    await flush();
+    expect(counts.delete).toBe(0);
+  });
+
+  it('swallows an insert failure (logged), so a tool result never fails over its bookkeeping', async () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const { service } = makeService([Promise.reject(new Error('db down'))]);
+    expect(() =>
+      service.record({
+        userId: ALICE.id,
+        principal: { kind: 'key', id: 'k-1' },
+        kind: 'capability',
+        manual: null,
+        name: 'ask',
+        outcome: 'ok',
+        durationMs: 1,
+      }),
+    ).not.toThrow();
+    await flush();
+    expect(warn).toHaveBeenCalled();
+    warn.mockRestore();
+  });
+});
+
+describe('AgentAuditService.listPrincipals', () => {
+  it("lists a person's keys and agents with event counts, live first, most recently used first", async () => {
+    const { service } = makeService(
+      [
+        // keysForUser: the user row
+        [ALICE],
+        // connections joined with users
+        [
+          { connection: connection({ id: 'c-old', revokedAt: new Date(NOW - DAY), revokedBy: 'owner', lastUsedAt: new Date(NOW) }), user: ALICE },
+          { connection: connection({ id: 'c-1' }), user: ALICE },
+        ],
+        // event counts
+        [
+          { keyId: 'k-1', connectionId: null, n: 7 },
+          { keyId: null, connectionId: 'c-1', n: 3 },
+        ],
+      ],
+      { listForUser: vi.fn(async () => [key({ lastUsedAt: NOW - 2 * DAY })]) },
+    );
+
+    const rows = await service.listPrincipals({ userId: ALICE.id });
+
+    expect(rows.map((r) => `${r.kind}:${r.id}`)).toEqual(['agent:c-1', 'key:k-1', 'agent:c-old']);
+    expect(rows[0]).toMatchObject({ label: 'Claude', eventCount: 3, user: ALICE, revokedAt: null });
+    expect(rows[1]).toMatchObject({ label: 'CI pipeline', keyKind: 'key', eventCount: 7, user: ALICE });
+    // The revoked one sinks, still carrying who ended it and its (zero) count.
+    expect(rows[2]).toMatchObject({ revokedBy: 'owner', eventCount: 0 });
+  });
+
+  it('lists every account for the deployment, grouped by owner email', async () => {
+    const { service, keyService } = makeService(
+      [
+        [{ connection: connection({ id: 'c-bob', userId: BOB.id }), user: BOB }],
+        [],
+      ],
+      { listForDeployment: vi.fn(async () => [{ ...key({}), user: ALICE }]) },
+    );
+
+    const rows = await service.listPrincipals('all');
+
+    expect(rows.map((r) => r.user.email)).toEqual(['alice@example.com', 'bob@example.com']);
+    expect((keyService.listForDeployment as any)).toHaveBeenCalled();
+    expect((keyService.listForUser as any)).not.toHaveBeenCalled();
+  });
+});
+
+describe('AgentAuditService.listEvents', () => {
+  const eventId = (i: number) => `00000000-0000-4000-8000-00000000000${i}`;
+  const eventRow = (i: number) => ({
+    id: eventId(i),
+    kind: 'capability',
+    manual: null,
+    name: `tool-${i}`,
+    outcome: 'ok',
+    at: new Date(NOW - i * 1000),
+  });
+
+  it('pages newest first with a keyset cursor and reports the total', async () => {
+    const { service, captured } = makeService([
+      [eventRow(1), eventRow(2), eventRow(3)] /* limit 2 → 3 rows means more */,
+      [{ total: 12 }],
+    ]);
+
+    const page = await service.listEvents({ kind: 'key', id: 'k-1' }, { limit: 2 });
+
+    expect(page.events.map((e) => e.id)).toEqual([eventId(1), eventId(2)]);
+    expect(page.events[0]).toMatchObject({ kind: 'capability', name: 'tool-1', outcome: 'ok', at: NOW - 1000 });
+    expect(page.total).toBe(12);
+    expect(page.nextCursor).toBe(`${NOW - 2000}.${eventId(2)}`);
+    // The page and the total both read THIS principal's rows and nobody else's.
+    expect(render(captured.where[0]).params).toEqual(['k-1']);
+    expect(render(captured.where[1]).params).toEqual(['k-1']);
+
+    // A cursor page counts nothing: the reader holds the first page's total.
+    const last = makeService([[eventRow(3)]]);
+    const tail = await last.service.listEvents({ kind: 'key', id: 'k-1' }, { before: page.nextCursor!, limit: 2 });
+    expect(tail.events.map((e) => e.id)).toEqual([eventId(3)]);
+    expect(tail.nextCursor).toBeNull();
+    expect(tail.total).toBeNull();
+    expect(last.counts.select).toBe(1);
+    // The cursor became the keyset predicate: strictly older, or the same
+    // instant and a smaller id.
+    const after = render(last.captured.where[0]);
+    expect(after.sql).toMatch(/"at" < \$2 or \("agent_events"."at" = \$3 and "agent_events"."id" < \$4\)/);
+    // The instant rides twice (strictly-older, and same-instant) as whatever
+    // the driver spells a timestamp as; the id is the cursor's own.
+    expect(after.params[0]).toBe('k-1');
+    expect(after.params[1]).toEqual(after.params[2]);
+    expect(new Date(after.params[1] as string | Date).getTime()).toBe(NOW - 2000);
+    expect(after.params[3]).toBe(eventId(2));
+  });
+
+  it('refuses a cursor it did not issue instead of sending it to the database', async () => {
+    const { service, counts } = makeService([]);
+    for (const before of ['123.bad', 'notanumber.' + eventId(1), '1e5.' + eventId(1), eventId(1)]) {
+      await expect(service.listEvents({ kind: 'key', id: 'k-1' }, { before, limit: 2 })).rejects.toBeInstanceOf(
+        InvalidCursorError,
+      );
+    }
+    expect(counts.select).toBe(0);
+  });
+});
+
+describe('AgentAuditService.ownerOf', () => {
+  it('answers for a key through the key service, and for an agent from its connection row', async () => {
+    const { service, keyService } = makeService([[{ userId: BOB.id }]], { ownerOf: vi.fn(async () => ALICE.id) });
+    await expect(service.ownerOf({ kind: 'key', id: 'k-1' })).resolves.toBe(ALICE.id);
+    expect(keyService.ownerOf).toHaveBeenCalledWith('k-1');
+    await expect(service.ownerOf({ kind: 'agent', id: 'c-1' })).resolves.toBe(BOB.id);
+  });
+});
+
+describe('AgentAuditService.revokeConnection', () => {
+  it('marks the connection revoked by whom, and revokes every live token it holds', async () => {
+    const { service, captured } = makeService([
+      [{ id: 'c-1' }] /* connection update.returning */,
+      undefined /* tokens update */,
+    ]);
+
+    await service.revokeConnection('c-1', 'admin');
+
+    expect(captured.updateTargets).toEqual([agentConnections, oauthTokens]);
+    expect(captured.set[0]).toMatchObject({ revokedBy: 'admin' });
+    expect(captured.set[0].revokedAt).toBeInstanceOf(Date);
+    expect(captured.set[1].revokedAt).toBeInstanceOf(Date);
+    // An admin's revoke is unscoped by owner, and touches only a LIVE connection…
+    const connection = render(captured.where[0]);
+    expect(connection.sql).toMatch(/"agent_connections"."id" = \$1 and "agent_connections"."revoked_at" is null/);
+    expect(connection.params).toEqual(['c-1']);
+    // …and exactly its own live tokens, never another connection's.
+    const tokens = render(captured.where[1]);
+    expect(tokens.sql).toMatch(/"oauth_tokens"."connection_id" = \$1 and "oauth_tokens"."revoked_at" is null/);
+    expect(tokens.params).toEqual(['c-1']);
+  });
+
+  it("scopes an owner's revoke to their own connections", async () => {
+    const { service, captured } = makeService([[{ id: 'c-1' }], undefined]);
+    await service.revokeConnection('c-1', 'owner', ALICE.id);
+    const connection = render(captured.where[0]);
+    expect(connection.sql).toMatch(/"agent_connections"."user_id" = \$2/);
+    expect(connection.params).toEqual(['c-1', ALICE.id]);
+    expect(captured.set[0]).toMatchObject({ revokedBy: 'owner' });
+  });
+
+  it('is idempotent on an already-revoked connection and throws for one out of scope', async () => {
+    const already = makeService([[] /* nothing live */, [{ id: 'c-1' }] /* but it exists */]);
+    await expect(already.service.revokeConnection('c-1', 'owner', ALICE.id)).resolves.toBeUndefined();
+    expect(already.counts.update).toBe(1); // no token revoke on a no-op
+    // The existence probe carries the SAME owner scope as the revoke itself.
+    expect(render(already.captured.where[1]).params).toEqual(['c-1', ALICE.id]);
+
+    const foreign = makeService([[], []]);
+    await expect(foreign.service.revokeConnection('c-1', 'owner', BOB.id)).rejects.toBeInstanceOf(
+      AuditPrincipalNotFoundError,
+    );
+  });
+});
+
+describe('retentionDaysFrom', () => {
+  it('reads a positive whole number of days, and blank, zero or negative as forever', () => {
+    expect(retentionDaysFrom('30')).toBe(30);
+    expect(retentionDaysFrom(' 3650 ')).toBe(3650);
+    expect(retentionDaysFrom('99999')).toBe(99999);
+    expect(retentionDaysFrom('')).toBeNull();
+    expect(retentionDaysFrom('0')).toBeNull();
+    expect(retentionDaysFrom('-5')).toBeNull();
+    // Not a window at all: kept forever too, and said once on the log.
+    expect(retentionDaysFrom('1.5')).toBeNull();
+    expect(retentionDaysFrom('lots')).toBeNull();
+  });
+});

package/src/modules/audit/__tests__/agent-rest-audit.middleware.test.ts

@@ -0,0 +1,113 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import express from 'express';
+import type { Server } from 'node:http';
+import { createAgentRestAuditMiddleware } from '../agent-rest-audit.middleware.js';
+import type { AgentEventInput } from '../audit.contract.js';
+import type { ToolAuth } from '../../tool-auth/tool-auth.middleware.js';
+
+const KB = 'KNOWLEDGE_BASE';
+
+/**
+ * The REST recorder, on a real router: a stand-in auth stamps whatever
+ * `toolAuth` a test wants (the way the real gate does, per route), a couple
+ * of routes answer as the platform tools do, and the recorder is watched.
+ */
+function makeApp(auth: ToolAuth | null, skills: { name: string; path: string }[] = []) {
+  const events: AgentEventInput[] = [];
+  const skillFolders = vi.fn(async () => skills);
+  const app = express();
+  app.use(express.json());
+  const router = express.Router();
+  router.use(
+    '/agent/tools/:name',
+    createAgentRestAuditMiddleware({ recorder: { record: (e) => void events.push(e) }, kbManualName: KB, skillFolders }),
+  );
+  const stampAuth: express.RequestHandler = (req, res, next) => {
+    if (!auth) {
+      res.status(401).json({ error: 'nope' });
+      return;
+    }
+    req.toolAuth = auth;
+    next();
+  };
+  router.post('/agent/tools/get_skill', stampAuth, (_req, res) => res.json({ ok: true }));
+  router.post('/agent/tools/read_file', stampAuth, (_req, res) => res.json({ content: 'x' }));
+  router.post('/agent/tools/list_skills', stampAuth, (_req, res) => res.json({ skills }));
+  router.post('/agent/tools/boom', stampAuth, (_req, res) => res.status(500).json({ error: 'kaboom' }));
+  app.use('/api', router);
+  return { app, events, skillFolders };
+}
+
+let server: Server;
+afterEach(() => server?.close());
+
+async function listen(app: express.Express): Promise<string> {
+  await new Promise<void>((resolve) => {
+    server = app.listen(0, resolve);
+  });
+  const address = server.address();
+  if (typeof address === 'string' || !address) throw new Error('no port');
+  return `http://127.0.0.1:${address.port}`;
+}
+
+const post = (base: string, name: string, body: unknown) =>
+  fetch(`${base}/api/agent/tools/${name}`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(body),
+  });
+
+/** Recording lands after the response; give it a turn. */
+const settle = () => new Promise((r) => setTimeout(r, 20));
+
+const EXCHANGED_GRANT: ToolAuth = { source: 'external', userId: 'u-1', connectionId: 'conn-1', scope: 'write' };
+
+describe('the REST recorder for the local server', () => {
+  it("records a skill read made with an exchanged grant as that agent's skill event, with the outcome", async () => {
+    const { app, events } = makeApp(EXCHANGED_GRANT, [{ name: 'rfi', path: 'Plugins/Sales/rfi' }]);
+    const base = await listen(app);
+    expect((await post(base, 'get_skill', { name: 'rfi' })).status).toBe(200);
+    expect((await post(base, 'boom', {})).status).toBe(500);
+    await settle();
+    expect(events).toEqual([
+      expect.objectContaining({
+        userId: 'u-1',
+        principal: { kind: 'agent', id: 'conn-1' },
+        kind: 'skill',
+        manual: 'Plugins/Sales/rfi',
+        name: 'rfi',
+        outcome: 'ok',
+      }),
+      expect.objectContaining({ kind: 'capability', name: 'boom', outcome: 'error' }),
+    ]);
+    expect(typeof events[0]!.durationMs).toBe('number');
+  });
+
+  it('fetches the skill catalog only for a read that names a path, and classifies the read by it', async () => {
+    const { app, events, skillFolders } = makeApp(EXCHANGED_GRANT, [{ name: 'rfi', path: 'Plugins/Sales/rfi' }]);
+    const base = await listen(app);
+    await post(base, 'list_skills', {});
+    await post(base, 'read_file', { path: 'Plugins/Sales/rfi/SKILL.md', branch: 'main' });
+    await settle();
+    expect(skillFolders).toHaveBeenCalledTimes(1);
+    expect(events.map((e) => `${e.kind}:${e.name}`)).toEqual(['capability:list_skills', 'skill:rfi']);
+  });
+
+  it('records nothing for a connection key, a loopback token, or a refused call — those are the proxy\'s to record, or nobody\'s', async () => {
+    const key = makeApp({ source: 'external', userId: 'u-1', tokenId: 'k-1', scope: 'write' });
+    let base = await listen(key.app);
+    await post(base, 'get_skill', { name: 'rfi' });
+    server.close();
+    const loopback = makeApp({ source: 'external', userId: 'u-1', scope: 'write' });
+    base = await listen(loopback.app);
+    await post(base, 'get_skill', { name: 'rfi' });
+    server.close();
+    const refused = makeApp(null);
+    base = await listen(refused.app);
+    expect((await post(base, 'get_skill', { name: 'rfi' })).status).toBe(401);
+    await settle();
+    expect(key.events).toEqual([]);
+    expect(loopback.events).toEqual([]);
+    expect(refused.events).toEqual([]);
+  });
+});

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

@@ -0,0 +1,201 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import express from 'express';
+import type { Server } from 'node:http';
+import { createAuditRoutes } from '../audit.routes.js';
+import {
+  AuditPrincipalNotFoundError,
+  InvalidCursorError,
+  type AuditPrincipal,
+  type IAgentAuditService,
+} from '../audit.contract.js';
+import { TokenNotFoundError } from '../../tool-auth/external-api-key.errors.js';
+import type { IAdminAccessService } from '../../admin/admin.interface.js';
+
+const ALICE = { id: 'u-alice', email: 'alice@example.com', name: 'Alice' };
+const BOB = { id: 'u-bob', email: 'bob@example.com', name: 'Bob' };
+const KEY_ID = '0f1e2d3c-4b5a-4697-8877-665544332211';
+const AGENT_ID = '11111111-2222-4333-8444-555555555555';
+const ALICE_AGENT_ID = '22222222-3333-4444-8555-666666666666';
+
+const ALICE_KEY: AuditPrincipal = {
+  kind: 'key',
+  id: KEY_ID,
+  label: 'CI pipeline',
+  keyKind: 'key',
+  createdAt: Date.UTC(2026, 0, 1),
+  lastUsedAt: null,
+  revokedAt: null,
+  revokedBy: null,
+  eventCount: 2,
+  user: ALICE,
+};
+
+/** Who owns what, as the fake service answers `ownerOf`. */
+const OWNERS: Record<string, string> = { [KEY_ID]: ALICE.id, [AGENT_ID]: BOB.id, [ALICE_AGENT_ID]: ALICE.id };
+
+const audit = {
+  listPrincipals: vi.fn(async () => [ALICE_KEY]),
+  ownerOf: vi.fn(async (p: { id: string }) => OWNERS[p.id] ?? null),
+  listEvents: vi.fn(async () => ({ events: [], total: 0, nextCursor: null })),
+  revokeConnection: vi.fn(async () => {}),
+} satisfies IAgentAuditService;
+
+const keys = {
+  revoke: vi.fn(async () => {}),
+  revokeAny: vi.fn(async () => {}),
+};
+
+function makeApp(opts: { admin: boolean; as?: { id: string; email: string } }) {
+  const adminAccess: IAdminAccessService = { isAdmin: vi.fn(async () => opts.admin) };
+  const app = express();
+  app.use(express.json());
+  // Stand-in auth middleware: stamps the caller identity the way the real JWT middleware does.
+  app.use((req, _res, next) => {
+    req.userId = opts.as?.id ?? ALICE.id;
+    req.userEmail = opts.as?.email ?? ALICE.email;
+    next();
+  });
+  app.use('/api', createAuditRoutes(audit, keys, adminAccess));
+  return app;
+}
+
+let server: Server;
+afterEach(() => {
+  server?.close();
+  vi.clearAllMocks();
+});
+
+async function listen(app: express.Express): Promise<string> {
+  await new Promise<void>((resolve) => {
+    server = app.listen(0, resolve);
+  });
+  const address = server.address();
+  if (typeof address === 'string' || !address) throw new Error('no port');
+  return `http://127.0.0.1:${address.port}`;
+}
+
+describe('audit routes — principals', () => {
+  it("lists the caller's own rows by default, and refuses scope=all to a member", async () => {
+    const base = await listen(makeApp({ admin: false }));
+    const mine = await fetch(`${base}/api/audit/principals`);
+    expect(mine.status).toBe(200);
+    expect(await mine.json()).toEqual({ principals: [ALICE_KEY] });
+    expect(audit.listPrincipals).toHaveBeenCalledWith({ userId: ALICE.id });
+
+    expect((await fetch(`${base}/api/audit/principals?scope=all`)).status).toBe(403);
+    expect(audit.listPrincipals).toHaveBeenCalledTimes(1);
+  });
+
+  it('lists every account for an admin asking for scope=all', async () => {
+    const base = await listen(makeApp({ admin: true }));
+    const res = await fetch(`${base}/api/audit/principals?scope=all`);
+    expect(res.status).toBe(200);
+    expect(audit.listPrincipals).toHaveBeenCalledWith('all');
+  });
+});
+
+describe('audit routes — events', () => {
+  it('serves the owner their events, with the page parameters passed through and clamped', async () => {
+    const base = await listen(makeApp({ admin: false }));
+    const res = await fetch(`${base}/api/audit/principals/key/${KEY_ID}/events?before=123.e-9&limit=5000`);
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({ events: [], total: 0, nextCursor: null });
+    expect(audit.listEvents).toHaveBeenCalledWith({ kind: 'key', id: KEY_ID }, { before: '123.e-9', limit: 200 });
+  });
+
+  it('answers a cursor the service does not recognise with 400, not 500', async () => {
+    const base = await listen(makeApp({ admin: false }));
+    audit.listEvents.mockRejectedValueOnce(new InvalidCursorError());
+    const res = await fetch(`${base}/api/audit/principals/key/${KEY_ID}/events?before=123.bad`);
+    expect(res.status).toBe(400);
+  });
+
+  it("refuses another person's principal to a member, and serves it to an admin", async () => {
+    const asAlice = await listen(makeApp({ admin: false }));
+    expect((await fetch(`${asAlice}/api/audit/principals/agent/${AGENT_ID}/events`)).status).toBe(403);
+    expect(audit.listEvents).not.toHaveBeenCalled();
+    server.close();
+
+    const asAdmin = await listen(makeApp({ admin: true }));
+    expect((await fetch(`${asAdmin}/api/audit/principals/agent/${AGENT_ID}/events`)).status).toBe(200);
+  });
+
+  it('404s an unknown kind, a malformed id, and a principal nobody owns', async () => {
+    const base = await listen(makeApp({ admin: true }));
+    expect((await fetch(`${base}/api/audit/principals/robot/${KEY_ID}/events`)).status).toBe(404);
+    expect((await fetch(`${base}/api/audit/principals/key/not-a-uuid/events`)).status).toBe(404);
+    expect(
+      (await fetch(`${base}/api/audit/principals/key/00000000-0000-4000-8000-000000000000/events`)).status,
+    ).toBe(404);
+    expect(audit.listEvents).not.toHaveBeenCalled();
+  });
+});
+
+describe('audit routes — revoke an agent', () => {
+  it("scopes a member's revoke to their own connections and records it as the owner's", async () => {
+    const base = await listen(makeApp({ admin: false, as: BOB }));
+    const res = await fetch(`${base}/api/audit/agents/${AGENT_ID}`, { method: 'DELETE' });
+    expect(res.status).toBe(200);
+    expect(audit.revokeConnection).toHaveBeenCalledWith(AGENT_ID, 'owner', BOB.id);
+  });
+
+  it("revokes anyone else's connection for an admin, recorded as an admin's doing", async () => {
+    const base = await listen(makeApp({ admin: true }));
+    const res = await fetch(`${base}/api/audit/agents/${AGENT_ID}`, { method: 'DELETE' });
+    expect(res.status).toBe(200);
+    expect(audit.revokeConnection).toHaveBeenCalledWith(AGENT_ID, 'admin');
+  });
+
+  it("records an admin revoking their OWN agent as the owner's doing, like anyone else's", async () => {
+    const base = await listen(makeApp({ admin: true }));
+    const res = await fetch(`${base}/api/audit/agents/${ALICE_AGENT_ID}`, { method: 'DELETE' });
+    expect(res.status).toBe(200);
+    expect(audit.revokeConnection).toHaveBeenCalledWith(ALICE_AGENT_ID, 'owner', ALICE.id);
+  });
+
+  it("refuses another person's agent to a member, and 404s a malformed or unknown id, all without revoking", async () => {
+    const base = await listen(makeApp({ admin: false }));
+    expect((await fetch(`${base}/api/audit/agents/nope`, { method: 'DELETE' })).status).toBe(404);
+    expect((await fetch(`${base}/api/audit/agents/${AGENT_ID}`, { method: 'DELETE' })).status).toBe(403);
+    expect(
+      (await fetch(`${base}/api/audit/agents/00000000-0000-4000-8000-000000000000`, { method: 'DELETE' })).status,
+    ).toBe(404);
+    expect(audit.revokeConnection).not.toHaveBeenCalled();
+  });
+
+  it('404s when the connection vanished between the ownership check and the revoke', async () => {
+    const base = await listen(makeApp({ admin: false, as: BOB }));
+    audit.revokeConnection.mockRejectedValueOnce(new AuditPrincipalNotFoundError());
+    expect((await fetch(`${base}/api/audit/agents/${AGENT_ID}`, { method: 'DELETE' })).status).toBe(404);
+  });
+});
+
+describe('audit routes — revoke a key', () => {
+  it("revokes the caller's own key through the owner path", async () => {
+    const base = await listen(makeApp({ admin: false }));
+    const res = await fetch(`${base}/api/audit/keys/${KEY_ID}`, { method: 'DELETE' });
+    expect(res.status).toBe(200);
+    expect(keys.revoke).toHaveBeenCalledWith(KEY_ID, ALICE.id);
+    expect(keys.revokeAny).not.toHaveBeenCalled();
+  });
+
+  it("revokes someone else's key only for an admin, through the admin path", async () => {
+    const asBob = await listen(makeApp({ admin: false, as: BOB }));
+    expect((await fetch(`${asBob}/api/audit/keys/${KEY_ID}`, { method: 'DELETE' })).status).toBe(403);
+    expect(keys.revoke).not.toHaveBeenCalled();
+    expect(keys.revokeAny).not.toHaveBeenCalled();
+    server.close();
+
+    const asAdmin = await listen(makeApp({ admin: true, as: BOB }));
+    expect((await fetch(`${asAdmin}/api/audit/keys/${KEY_ID}`, { method: 'DELETE' })).status).toBe(200);
+    expect(keys.revokeAny).toHaveBeenCalledWith(KEY_ID);
+  });
+
+  it('404s an unknown key, for members and admins alike', async () => {
+    const base = await listen(makeApp({ admin: true }));
+    const ghost = '00000000-0000-4000-8000-000000000000';
+    keys.revokeAny.mockRejectedValueOnce(new TokenNotFoundError());
+    expect((await fetch(`${base}/api/audit/keys/${ghost}`, { method: 'DELETE' })).status).toBe(404);
+    expect((await fetch(`${base}/api/audit/keys/garbage`, { method: 'DELETE' })).status).toBe(404);
+  });
+});