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

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

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

@@ -0,0 +1,121 @@
+import { describe, expect, it } from 'vitest';
+import { classifyToolCall, skillContaining, skillReadPath, splitUtcpName } from '../event-classifier.js';
+
+const KB = 'KNOWLEDGE_BASE';
+const ctx = { kbManualName: KB, catalogNames: new Map([['my_server', 'my-server']]) };
+const skills = [
+  { name: 'rfi', path: 'Plugins/Sales/rfi' },
+  { name: 'deploy-checklist', path: 'Skills/Engineering/deploy-checklist' },
+  // Nested under another skill's folder: the longer match must win.
+  { name: 'rfi-followup', path: 'Plugins/Sales/rfi/followup' },
+];
+
+describe('splitUtcpName', () => {
+  it('splits on the first dot and leaves a bare name without a manual', () => {
+    expect(splitUtcpName('KNOWLEDGE_BASE.read_file')).toEqual({ manual: 'KNOWLEDGE_BASE', tool: 'read_file' });
+    expect(splitUtcpName('notion.notion-search')).toEqual({ manual: 'notion', tool: 'notion-search' });
+    expect(splitUtcpName('call_tool_chain')).toEqual({ manual: '', tool: 'call_tool_chain' });
+  });
+});
+
+describe('skillReadPath', () => {
+  it('asks for the skill catalog only for a platform read that names a path, or a get_skill with a name', () => {
+    expect(skillReadPath(`${KB}.read_file`, { body: { path: 'Plugins/Sales/rfi/SKILL.md' } }, KB)).toBe(
+      'Plugins/Sales/rfi/SKILL.md',
+    );
+    expect(skillReadPath(`${KB}.grep`, { path: 'Skills' }, KB)).toBe('Skills');
+    expect(skillReadPath(`${KB}.get_skill`, { body: { name: 'rfi' } }, KB)).toBe('');
+    // Not worth a catalog fetch: a write, a read with no path, another manual's tool, a meta-tool.
+    expect(skillReadPath(`${KB}.write_file`, { body: { path: 'Plugins/x' } }, KB)).toBeNull();
+    expect(skillReadPath(`${KB}.read_file`, { body: {} }, KB)).toBeNull();
+    expect(skillReadPath('notion.search', { body: { path: 'Plugins/x' } }, KB)).toBeNull();
+    expect(skillReadPath('call_tool_chain', { code: 'x' }, KB)).toBeNull();
+  });
+});
+
+describe('skillContaining', () => {
+  it('matches a path inside a skill folder on a segment boundary, from either root, longest folder first', () => {
+    expect(skillContaining('Plugins/Sales/rfi/SKILL.md', skills)?.name).toBe('rfi');
+    expect(skillContaining('knowledge-base/Plugins/Sales/rfi/scripts/build.py', skills)?.name).toBe('rfi');
+    expect(skillContaining('./Skills\\Engineering\\deploy-checklist\\SKILL.md', skills)?.name).toBe('deploy-checklist');
+    expect(skillContaining('Plugins/Sales/rfi/followup/SKILL.md', skills)?.name).toBe('rfi-followup');
+    // The file tools accept a doubled separator as the same path; so does this.
+    expect(skillContaining('Plugins//Sales/rfi/SKILL.md', skills)?.name).toBe('rfi');
+    // `.` and `..` are resolved before matching: a path that climbs out of a
+    // skill folder is not a read of that skill, and one that climbs above its
+    // own start is no place at all.
+    expect(skillContaining('Plugins/Sales/rfi/./SKILL.md', skills)?.name).toBe('rfi');
+    expect(skillContaining('Plugins/Sales/other/../rfi/SKILL.md', skills)?.name).toBe('rfi');
+    expect(skillContaining('Plugins/Sales/rfi/../../../KnowledgeBase/Secrets.md', skills)).toBeNull();
+    expect(skillContaining('../Plugins/Sales/rfi/SKILL.md', skills)).toBeNull();
+    // A folder that merely shares a prefix is not the skill's folder.
+    expect(skillContaining('Plugins/Sales/rfi-old/notes.md', skills)).toBeNull();
+    expect(skillContaining('KnowledgeBase/Product/roadmap.md', skills)).toBeNull();
+  });
+});
+
+describe('classifyToolCall', () => {
+  it('logs the platform manual and the meta-tools as hexis capabilities, by bare name', () => {
+    expect(classifyToolCall(`${KB}.write_file`, { body: { path: 'x' } }, ctx, null)).toEqual({
+      kind: 'capability',
+      manual: null,
+      name: 'write_file',
+    });
+    expect(classifyToolCall('call_tool_chain', { code: 'x' }, ctx, null)).toEqual({
+      kind: 'capability',
+      manual: null,
+      name: 'call_tool_chain',
+    });
+  });
+
+  it("logs another manual's tool as a tool under its catalog name", () => {
+    expect(classifyToolCall('my_server.search', { q: 'x' }, ctx, null)).toEqual({
+      kind: 'tool',
+      manual: 'my-server',
+      name: 'search',
+    });
+    // An http `.tool` manual has no rewrite, so its registered name is the catalog name.
+    expect(classifyToolCall('hubspot.search_contacts', {}, ctx, null)).toEqual({
+      kind: 'tool',
+      manual: 'hubspot',
+      name: 'search_contacts',
+    });
+  });
+
+  it('logs get_skill as a skill read, with the folder when the catalog knows it', () => {
+    expect(classifyToolCall(`${KB}.get_skill`, { body: { name: 'rfi' } }, ctx, skills)).toEqual({
+      kind: 'skill',
+      manual: 'Plugins/Sales/rfi',
+      name: 'rfi',
+    });
+    expect(classifyToolCall(`${KB}.get_skill`, { name: 'unknown' }, ctx, skills)).toEqual({
+      kind: 'skill',
+      manual: null,
+      name: 'unknown',
+    });
+  });
+
+  it('logs a platform read inside a skill folder as that skill, and elsewhere as the read', () => {
+    expect(classifyToolCall(`${KB}.read_file`, { body: { path: 'Plugins/Sales/rfi/SKILL.md' } }, ctx, skills)).toEqual({
+      kind: 'skill',
+      manual: 'Plugins/Sales/rfi',
+      name: 'rfi',
+    });
+    expect(classifyToolCall(`${KB}.list_files`, { body: { path: 'Skills/Engineering/deploy-checklist' } }, ctx, skills)).toEqual({
+      kind: 'skill',
+      manual: 'Skills/Engineering/deploy-checklist',
+      name: 'deploy-checklist',
+    });
+    expect(classifyToolCall(`${KB}.read_file`, { body: { path: 'KnowledgeBase/Product/roadmap.md' } }, ctx, skills)).toEqual({
+      kind: 'capability',
+      manual: null,
+      name: 'read_file',
+    });
+    // No catalog (the fetch failed): the honest fallback is the read itself.
+    expect(classifyToolCall(`${KB}.read_file`, { body: { path: 'Plugins/Sales/rfi/SKILL.md' } }, ctx, null)).toEqual({
+      kind: 'capability',
+      manual: null,
+      name: 'read_file',
+    });
+  });
+});

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

@@ -0,0 +1,316 @@
+import { and, asc, count, desc, eq, isNull, lt, or, type SQL } from 'drizzle-orm';
+import { logger } from '../../shared/logging.js';
+import type { Database } from '../database/connection.js';
+import { agentConnections, agentEvents, oauthTokens, users } from '../database/schema.js';
+import type { IExternalApiKeyService } from '../tool-auth/external-api-key.interface.js';
+import {
+  AuditPrincipalNotFoundError,
+  InvalidCursorError,
+  isUuid,
+  parseRetentionWindow,
+  type AgentEventInput,
+  type AgentEventPage,
+  type AgentEventView,
+  type AuditPrincipal,
+  type AuditPrincipalRef,
+  type AuditScope,
+  type IAgentAuditService,
+  type IAgentEventRecorder,
+} from './audit.contract.js';
+
+const log = logger('audit');
+
+/** The most events one page may carry; the routes clamp to it. */
+export const MAX_EVENT_PAGE = 200;
+
+/** How often, at most, one process sweeps events past the retention window. */
+const PRUNE_INTERVAL_MS = 60 * 60_000;
+
+/**
+ * The Audit log: the write half the MCP proxy records through, and the read
+ * and revoke half its page is built on.
+ *
+ * Writes are fire-and-forget by contract — a tool result must never wait on,
+ * or fail over, its own bookkeeping. Retention is enforced opportunistically
+ * on the write path (one sweep per process per hour, piggybacked on an
+ * insert), the same way the OAuth tables prune themselves on mint: no
+ * scheduler, and a deployment that records nothing has nothing to sweep.
+ *
+ * Connection keys are read through the key service rather than joined here,
+ * so their summary shape (kind, revoked-by, …) has exactly one definition.
+ */
+export class AgentAuditService implements IAgentAuditService, IAgentEventRecorder {
+  private lastPruneAt = 0;
+
+  constructor(
+    private readonly db: Database,
+    private readonly keys: Pick<IExternalApiKeyService, 'listForUser' | 'listForDeployment' | 'ownerOf'>,
+    /** Read per sweep, so a changed setting applies without a restart; null = keep forever. */
+    private readonly retentionDays: () => number | null,
+    private readonly now: () => number = Date.now,
+  ) {}
+
+  record(event: AgentEventInput): void {
+    this.db
+      .insert(agentEvents)
+      .values({
+        userId: event.userId,
+        keyId: event.principal.kind === 'key' ? event.principal.id : null,
+        connectionId: event.principal.kind === 'agent' ? event.principal.id : null,
+        kind: event.kind,
+        manual: event.manual,
+        name: event.name,
+        outcome: event.outcome,
+        durationMs: event.durationMs,
+        at: new Date(this.now()),
+      })
+      .then(
+        () => this.maybePrune(),
+        (err) => log.warn('recording an agent event failed:', { err }),
+      );
+  }
+
+  /**
+   * Sweep events older than the retention window — at most once per hour per
+   * process, best-effort, never awaited by a caller. A deployment that keeps
+   * events forever sweeps nothing.
+   */
+  private async maybePrune(): Promise<void> {
+    const now = this.now();
+    if (now - this.lastPruneAt < PRUNE_INTERVAL_MS) return;
+    this.lastPruneAt = now;
+    const days = this.retentionDays();
+    if (days === null) return;
+    const cutoff = new Date(now - days * 24 * 60 * 60_000);
+    try {
+      await this.db.delete(agentEvents).where(lt(agentEvents.at, cutoff));
+    } catch (err) {
+      log.warn('agent-event prune failed (non-fatal):', { err });
+    }
+  }
+
+  async listPrincipals(scope: AuditScope): Promise<AuditPrincipal[]> {
+    const mine = scope === 'all' ? null : scope.userId;
+    const [keyRows, connectionRows, countRows] = await Promise.all([
+      mine === null ? this.keys.listForDeployment() : this.keysForUser(mine),
+      this.db
+        .select({
+          connection: agentConnections,
+          user: { id: users.id, email: users.email, name: users.name },
+        })
+        .from(agentConnections)
+        .innerJoin(users, eq(agentConnections.userId, users.id))
+        .where(mine === null ? undefined : eq(agentConnections.userId, mine))
+        .orderBy(asc(users.email), desc(agentConnections.connectedAt)),
+      this.db
+        .select({ keyId: agentEvents.keyId, connectionId: agentEvents.connectionId, n: count() })
+        .from(agentEvents)
+        .where(mine === null ? undefined : eq(agentEvents.userId, mine))
+        .groupBy(agentEvents.keyId, agentEvents.connectionId),
+    ]);
+
+    const counts = new Map<string, number>();
+    for (const row of countRows) {
+      const id = row.keyId ?? row.connectionId;
+      if (id) counts.set(id, Number(row.n));
+    }
+
+    const principals: AuditPrincipal[] = [
+      ...keyRows.map((k) => ({
+        kind: 'key' as const,
+        id: k.id,
+        label: k.label,
+        keyKind: k.kind,
+        createdAt: k.createdAt,
+        lastUsedAt: k.lastUsedAt,
+        revokedAt: k.revokedAt,
+        revokedBy: k.revokedBy,
+        deletedAt: k.deletedAt,
+        eventCount: counts.get(k.id) ?? 0,
+        user: k.user,
+      })),
+      ...connectionRows.map(({ connection: c, user }) => ({
+        kind: 'agent' as const,
+        id: c.id,
+        label: c.clientName ?? 'Unnamed agent',
+        createdAt: c.connectedAt.getTime(),
+        lastUsedAt: c.lastUsedAt ? c.lastUsedAt.getTime() : null,
+        revokedAt: c.revokedAt ? c.revokedAt.getTime() : null,
+        revokedBy: (c.revokedBy as 'owner' | 'admin' | null) ?? null,
+        eventCount: counts.get(c.id) ?? 0,
+        user,
+      })),
+    ];
+    // Per account (by email), live before revoked, most recently used first,
+    // newest first among the never-used — the order the page shows without
+    // re-sorting, and the one the Connection keys overview had.
+    principals.sort((a, b) => {
+      const byEmail = a.user.email.localeCompare(b.user.email);
+      if (byEmail !== 0) return byEmail;
+      const aRevoked = a.revokedAt !== null;
+      const bRevoked = b.revokedAt !== null;
+      if (aRevoked !== bRevoked) return aRevoked ? 1 : -1;
+      const byUse = (b.lastUsedAt ?? 0) - (a.lastUsedAt ?? 0);
+      return byUse !== 0 ? byUse : b.createdAt - a.createdAt;
+    });
+    return principals;
+  }
+
+  /** One person's keys, with the owner attached the way the deployment listing attaches it. */
+  private async keysForUser(userId: string) {
+    const [keys, [user]] = await Promise.all([
+      this.keys.listForUser(userId),
+      this.db
+        .select({ id: users.id, email: users.email, name: users.name })
+        .from(users)
+        .where(eq(users.id, userId))
+        .limit(1),
+    ]);
+    if (!user) return [];
+    return keys.map((k) => ({ ...k, user }));
+  }
+
+  async ownerOf(principal: AuditPrincipalRef): Promise<string | null> {
+    if (principal.kind === 'agent') {
+      const [row] = await this.db
+        .select({ userId: agentConnections.userId })
+        .from(agentConnections)
+        .where(eq(agentConnections.id, principal.id))
+        .limit(1);
+      return row?.userId ?? null;
+    }
+    // A key is the key service's to answer for, like every other read of one.
+    return this.keys.ownerOf(principal.id);
+  }
+
+  async listEvents(
+    principal: AuditPrincipalRef,
+    page: { before?: string; limit: number },
+  ): Promise<AgentEventPage> {
+    const limit = Math.max(1, Math.min(MAX_EVENT_PAGE, Math.floor(page.limit)));
+    const byPrincipal =
+      principal.kind === 'key'
+        ? eq(agentEvents.keyId, principal.id)
+        : eq(agentEvents.connectionId, principal.id);
+    // Keyset on (at, id): a page boundary between two events at the same
+    // instant is still a boundary, and a row inserted while the reader pages
+    // never shifts what the next page returns.
+    const cursor = page.before ? parseCursor(page.before) : null;
+    if (page.before && !cursor) throw new InvalidCursorError();
+    const after: SQL | undefined = cursor
+      ? or(
+          lt(agentEvents.at, cursor.at),
+          and(eq(agentEvents.at, cursor.at), lt(agentEvents.id, cursor.id)),
+        )
+      : undefined;
+    // The total is counted on the FIRST page only: a reader paging back
+    // through a busy principal's history would otherwise pay a full count of
+    // the same number on every step, for a figure the page already holds.
+    const [rows, totals] = await Promise.all([
+      this.db
+        .select({
+          id: agentEvents.id,
+          kind: agentEvents.kind,
+          manual: agentEvents.manual,
+          name: agentEvents.name,
+          outcome: agentEvents.outcome,
+          at: agentEvents.at,
+        })
+        .from(agentEvents)
+        .where(and(byPrincipal, after))
+        .orderBy(desc(agentEvents.at), desc(agentEvents.id))
+        .limit(limit + 1),
+      cursor ? null : this.db.select({ total: count() }).from(agentEvents).where(byPrincipal),
+    ]);
+    const hasMore = rows.length > limit;
+    const pageRows = hasMore ? rows.slice(0, limit) : rows;
+    const events: AgentEventView[] = pageRows.map((r) => ({
+      id: r.id,
+      kind: r.kind as AgentEventView['kind'],
+      manual: r.manual,
+      name: r.name,
+      outcome: r.outcome as AgentEventView['outcome'],
+      at: r.at.getTime(),
+    }));
+    const last = pageRows[pageRows.length - 1];
+    return {
+      events,
+      total: totals ? Number(totals[0]?.total ?? 0) : null,
+      nextCursor: hasMore && last ? formatCursor(last.at, last.id) : null,
+    };
+  }
+
+  async revokeConnection(id: string, by: 'owner' | 'admin', ownerUserId?: string): Promise<void> {
+    const scope = ownerUserId
+      ? and(eq(agentConnections.id, id), eq(agentConnections.userId, ownerUserId))!
+      : eq(agentConnections.id, id);
+    await this.db.transaction(async (tx) => {
+      const revoked = await tx
+        .update(agentConnections)
+        .set({ revokedAt: new Date(this.now()), revokedBy: by })
+        .where(and(scope, isNull(agentConnections.revokedAt)))
+        .returning({ id: agentConnections.id });
+      if (revoked.length === 0) {
+        // Already revoked stays idempotent; out of scope or unknown throws —
+        // the same split `ExternalApiKeyService.markRevoked` makes.
+        const [existing] = await tx
+          .select({ id: agentConnections.id })
+          .from(agentConnections)
+          .where(scope)
+          .limit(1);
+        if (!existing) throw new AuditPrincipalNotFoundError();
+        return;
+      }
+      // Every live token of the connection, access and refresh alike: the
+      // agent's next request 401s, its refresh fails, and re-authorizing —
+      // through the browser, as a person — is the only way back in.
+      await tx
+        .update(oauthTokens)
+        .set({ revokedAt: new Date(this.now()) })
+        .where(and(eq(oauthTokens.connectionId, id), isNull(oauthTokens.revokedAt)));
+    });
+  }
+}
+
+/** `<epoch ms>.<uuid>` — the page's opaque-enough cursor. */
+function formatCursor(at: Date, id: string): string {
+  return `${at.getTime()}.${id}`;
+}
+
+/**
+ * The cursor back into its parts, or null for anything this service did not
+ * issue: the id must be a uuid (the column is one, and Postgres refuses to
+ * compare it with anything else) and the instant a whole number of epoch
+ * milliseconds a `timestamp` can hold.
+ */
+function parseCursor(raw: string): { at: Date; id: string } | null {
+  const dot = raw.indexOf('.');
+  if (dot < 0) return null;
+  const msText = raw.slice(0, dot);
+  const id = raw.slice(dot + 1);
+  if (!/^\d{1,15}$/.test(msText) || !isUuid(id)) return null;
+  return { at: new Date(Number(msText)), id };
+}
+
+/** The last invalid setting value warned about, so a standing misconfiguration is said once, not once per prune. */
+let warnedInvalidRetention: string | null = null;
+
+/**
+ * The retention window the service runs on, in days — or null to keep
+ * events forever, which is what a blank, zero or negative setting means. A
+ * value that is not a window at all is kept-forever too, said out loud once:
+ * the Deployment page shows an environment value as the one in effect and
+ * would otherwise be the only place claiming a window nobody is keeping.
+ */
+export function retentionDaysFrom(raw: string): number | null {
+  const window = parseRetentionWindow(raw);
+  if (window === 'forever') return null;
+  if (window !== null) return window.days;
+  if (raw !== warnedInvalidRetention) {
+    warnedInvalidRetention = raw;
+    log.warn(
+      `auditRetentionDays is "${raw}", which is not a whole number of days — keeping events forever until it is fixed.`,
+    );
+  }
+  return null;
+}