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

package/dist/modules/audit/agent-rest-audit.middleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-rest-audit.middleware.d.ts","sourceRoot":"","sources":["../../../src/modules/audit/agent-rest-audit.middleware.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE9C,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC/D,OAAO,EAAmC,KAAK,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAC1F,OAAO,sCAAsC,CAAC;AAI9C,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,2EAA2E;IAC3E,YAAY,EAAE,MAAM,CAAC;IACrB,oHAAoH;IACpH,YAAY,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,WAAW,EAAE,CAAC,CAAC;CACnE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,8BAA8B,CAAC,IAAI,EAAE,kBAAkB,GAAG,cAAc,CAuCvF"}

package/dist/modules/audit/agent-rest-audit.middleware.js

@@ -0,0 +1,75 @@
+import { logger } from '../../shared/logging.js';
+import { classifyToolCall, skillReadPath } from './event-classifier.js';
+import '../tool-auth/tool-auth.middleware.js'; // Express Request augmentation (req.toolAuth)
+const log = logger('audit');
+/**
+ * Records the REST tool calls the LOCAL server makes directly — the ones that
+ * never pass through the hosted MCP endpoint, where every other call an agent
+ * makes is recorded.
+ *
+ * hexis-mcp reaches the deployment two ways. Tool calls go through the
+ * hosted `/api/mcp` as its remote manual, and the proxy records them there.
+ * But the skill catalog and a skill's body are read straight off the REST
+ * surface (`list_skills`, `get_skill`, `list_local_tools`, …) with the
+ * internal token the server exchanged its grant for — so a person loading a
+ * skill as a slash command in Claude Code through the local server left no
+ * `skill` event, while the same read through the hosted endpoint did.
+ *
+ * WHICH calls are recorded here is decided by the credential, not the route:
+ * only an `externalProxy` token that names an agent connection — the
+ * exchanged grant — is recorded. The hosted proxy's own loopback tokens name
+ * none, so a call the proxy has already recorded is never counted twice;
+ * and a connection key reaching REST directly is indistinguishable from the
+ * proxy passing that same key through, so keys stay recorded at the proxy
+ * alone. The rule is the credential's shape, which no caller chooses.
+ *
+ * Mounted in front of every `/agent/tools/:name` route and judging on
+ * `finish`, when the route's own auth has run and the status is known: a 2xx
+ * is `ok`, anything else `error`. Never on the tool's critical path — the
+ * classification (and the skill catalog it may need) runs after the answer
+ * has gone out.
+ */
+export function createAgentRestAuditMiddleware(deps) {
+    return (req, res, next) => {
+        const started = performance.now();
+        // Read NOW: `req.params` is rewritten for each layer Express matches, and
+        // by `finish` it is the route's own (empty) set, not this mount's.
+        const name = String(req.params.name ?? '');
+        res.on('finish', () => {
+            const auth = req.toolAuth;
+            if (!auth || auth.source !== 'external' || !auth.connectionId)
+                return;
+            if (!name)
+                return;
+            const durationMs = Math.max(0, Math.round(performance.now() - started));
+            const outcome = res.statusCode < 400 ? 'ok' : 'error';
+            const args = (req.body && typeof req.body === 'object' ? req.body : {});
+            const utcpName = `${deps.kbManualName}.${name}`;
+            const ctx = { kbManualName: deps.kbManualName, catalogNames: new Map() };
+            const record = (skills) => {
+                try {
+                    deps.recorder.record({
+                        userId: auth.userId,
+                        principal: { kind: 'agent', id: auth.connectionId },
+                        ...classifyToolCall(utcpName, args, ctx, skills),
+                        outcome,
+                        durationMs,
+                    });
+                }
+                catch (err) {
+                    log.warn('recording a REST agent event failed:', { err });
+                }
+            };
+            if (skillReadPath(utcpName, args, deps.kbManualName) === null) {
+                record(null);
+                return;
+            }
+            deps.skillFolders(auth.userId).then(record, (err) => {
+                log.warn('skill catalog unavailable for audit classification:', { err });
+                record(null);
+            });
+        });
+        next();
+    };
+}
+//# sourceMappingURL=agent-rest-audit.middleware.js.map

package/dist/modules/audit/agent-rest-audit.middleware.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-rest-audit.middleware.js","sourceRoot":"","sources":["../../../src/modules/audit/agent-rest-audit.middleware.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAEjD,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAoB,MAAM,uBAAuB,CAAC;AAC1F,OAAO,sCAAsC,CAAC,CAAC,8CAA8C;AAE7F,MAAM,GAAG,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC;AAU5B;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,UAAU,8BAA8B,CAAC,IAAwB;IACrE,OAAO,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE;QACxB,MAAM,OAAO,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC;QAClC,0EAA0E;QAC1E,mEAAmE;QACnE,MAAM,IAAI,GAAG,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC;QAC3C,GAAG,CAAC,EAAE,CAAC,QAAQ,EAAE,GAAG,EAAE;YACpB,MAAM,IAAI,GAAG,GAAG,CAAC,QAAQ,CAAC;YAC1B,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,MAAM,KAAK,UAAU,IAAI,CAAC,IAAI,CAAC,YAAY;gBAAE,OAAO;YACtE,IAAI,CAAC,IAAI;gBAAE,OAAO;YAClB,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,GAAG,EAAE,GAAG,OAAO,CAAC,CAAC,CAAC;YACxE,MAAM,OAAO,GAAG,GAAG,CAAC,UAAU,GAAG,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC;YACtD,MAAM,IAAI,GAAG,CAAC,GAAG,CAAC,IAAI,IAAI,OAAO,GAAG,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAA4B,CAAC;YACnG,MAAM,QAAQ,GAAG,GAAG,IAAI,CAAC,YAAY,IAAI,IAAI,EAAE,CAAC;YAChD,MAAM,GAAG,GAAG,EAAE,YAAY,EAAE,IAAI,CAAC,YAAY,EAAE,YAAY,EAAE,IAAI,GAAG,EAAkB,EAAE,CAAC;YACzF,MAAM,MAAM,GAAG,CAAC,MAAqC,EAAE,EAAE;gBACvD,IAAI,CAAC;oBACH,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC;wBACnB,MAAM,EAAE,IAAI,CAAC,MAAM;wBACnB,SAAS,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE,IAAI,CAAC,YAAa,EAAE;wBACpD,GAAG,gBAAgB,CAAC,QAAQ,EAAE,IAAI,EAAE,GAAG,EAAE,MAAM,CAAC;wBAChD,OAAO;wBACP,UAAU;qBACX,CAAC,CAAC;gBACL,CAAC;gBAAC,OAAO,GAAG,EAAE,CAAC;oBACb,GAAG,CAAC,IAAI,CAAC,sCAAsC,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC;gBAC5D,CAAC;YACH,CAAC,CAAC;YACF,IAAI,aAAa,CAAC,QAAQ,EAAE,IAAI,EAAE,IAAI,CAAC,YAAY,CAAC,KAAK,IAAI,EAAE,CAAC;gBAC9D,MAAM,CAAC,IAAI,CAAC,CAAC;gBACb,OAAO;YACT,CAAC;YACD,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,EAAE;gBAClD,GAAG,CAAC,IAAI,CAAC,qDAAqD,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC;gBACzE,MAAM,CAAC,IAAI,CAAC,CAAC;YACf,CAAC,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;QACH,IAAI,EAAE,CAAC;IACT,CAAC,CAAC;AACJ,CAAC"}

package/dist/modules/audit/audit.contract.d.ts

@@ -0,0 +1,145 @@
+/**
+ * The Audit log's contracts: what an external agent's activity is recorded
+ * as, who a recorded call is attributed to, and the two services around
+ * them — the recorder the MCP proxy writes through, and the read/revoke
+ * service the Audit log page is built on.
+ */
+declare global {
+    namespace Express {
+        interface Request {
+            /**
+             * The agent connection (`agent_connections.id`) an OAuth-authenticated
+             * MCP request arrived through — bound by the MCP auth middleware from
+             * the access token, or from the `connectionId` claim of the internal
+             * token the local server exchanged its grant for. Unset for connection
+             * keys (those carry `externalApiKeyId`) and for browser sessions.
+             */
+            agentConnectionId?: string;
+        }
+    }
+}
+/** What was called: the platform's own tool, a manual's tool, or a skill read. */
+export type AgentEventKind = 'capability' | 'tool' | 'skill';
+/** How the call ended. `denied`: the caller's sign-in for the tool was missing, so nothing ran. */
+export type AgentEventOutcome = 'ok' | 'error' | 'denied';
+/**
+ * Who a call is attributed to: the connection key it was authenticated with,
+ * or the agent connection behind its OAuth grant. Exactly one.
+ */
+export type AuditPrincipalRef = {
+    kind: 'key';
+    id: string;
+} | {
+    kind: 'agent';
+    id: string;
+};
+/** One recorded call, as the recorder takes it. */
+export interface AgentEventInput {
+    userId: string;
+    principal: AuditPrincipalRef;
+    kind: AgentEventKind;
+    /** The MCP server / `.tool` manual for a tool, the skill folder for a skill; null for a capability. */
+    manual: string | null;
+    name: string;
+    outcome: AgentEventOutcome;
+    durationMs: number | null;
+}
+/**
+ * The write half. `record` never throws and never blocks the call it
+ * describes: a recording failure is logged and the tool result still goes
+ * back to the agent.
+ */
+export interface IAgentEventRecorder {
+    record(event: AgentEventInput): void;
+}
+/** One row of the Audit log: an agent connection or a connection key, with its owner. */
+export interface AuditPrincipal {
+    kind: 'key' | 'agent';
+    id: string;
+    /** The key's label, or the agent's registered client name. */
+    label: string;
+    /**
+     * For a key: what it was minted as (`key` by hand, `github-link` for a
+     * Claude link). Absent for an agent.
+     */
+    keyKind?: string;
+    /** When the key was created / the agent connected. Epoch ms. */
+    createdAt: number;
+    lastUsedAt: number | null;
+    revokedAt: number | null;
+    /** Who ended it, once revoked: the owner, or an admin. */
+    revokedBy: 'owner' | 'admin' | null;
+    /** For a key: when its owner deleted it for good. Such rows reach admins only. */
+    deletedAt?: number | null;
+    /** Events currently on record for it (within the retention window). */
+    eventCount: number;
+    user: {
+        id: string;
+        email: string;
+        name: string;
+    };
+}
+/** One event as the page reads it. */
+export interface AgentEventView {
+    id: string;
+    kind: AgentEventKind;
+    manual: string | null;
+    name: string;
+    outcome: AgentEventOutcome;
+    at: number;
+}
+export interface AgentEventPage {
+    events: AgentEventView[];
+    /**
+     * Every event on record for the principal, not just this page — counted
+     * on the first page only; null on a page reached through a cursor, since
+     * the reader already holds the figure.
+     */
+    total: number | null;
+    /** Pass back as `before` to load the next (older) page; null when this was the last. */
+    nextCursor: string | null;
+}
+/** Whose rows: one person's, or the whole deployment's (admins). */
+export type AuditScope = {
+    userId: string;
+} | 'all';
+export interface IAgentAuditService {
+    listPrincipals(scope: AuditScope): Promise<AuditPrincipal[]>;
+    /** The account a principal belongs to, or null when there is no such principal. The routes' ownership check. */
+    ownerOf(principal: AuditPrincipalRef): Promise<string | null>;
+    listEvents(principal: AuditPrincipalRef, page: {
+        before?: string;
+        limit: number;
+    }): Promise<AgentEventPage>;
+    /**
+     * Cut an agent off: mark its connection revoked and revoke every live
+     * token it holds, so its next request fails and its refresh fails with it.
+     * `ownerUserId` scopes the revoke to the person's own connections; an admin
+     * passes none. Idempotent on an already-revoked connection; throws
+     * {@link AuditPrincipalNotFoundError} when nothing matches.
+     */
+    revokeConnection(id: string, by: 'owner' | 'admin', ownerUserId?: string): Promise<void>;
+}
+export declare class AuditPrincipalNotFoundError extends Error {
+    constructor();
+}
+/** A `before` cursor that is not one this service issued — the caller's mistake, answered as such. */
+export declare class InvalidCursorError extends Error {
+    constructor();
+}
+export declare function isUuid(value: string): boolean;
+/**
+ * The retention window's one rule, shared by the setting's validator and the
+ * runtime reader. A positive whole number of days is the window; blank,
+ * zero or a negative number is "keep forever" — the deployment's choice,
+ * made the same way whether typed on the Deployment page or set through
+ * `AUDIT_RETENTION_DAYS`. Anything else is not a window at all: the
+ * validator refuses the save, and the reader, which cannot refuse, keeps
+ * everything and says so.
+ */
+export type RetentionWindow = {
+    days: number;
+} | 'forever';
+/** The window a retention setting names, or null when it names none this rule accepts. */
+export declare function parseRetentionWindow(raw: string): RetentionWindow | null;
+//# sourceMappingURL=audit.contract.d.ts.map

package/dist/modules/audit/audit.contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit.contract.d.ts","sourceRoot":"","sources":["../../../src/modules/audit/audit.contract.ts"],"names":[],"mappings":"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"}

package/dist/modules/audit/audit.contract.js

@@ -0,0 +1,35 @@
+/**
+ * The Audit log's contracts: what an external agent's activity is recorded
+ * as, who a recorded call is attributed to, and the two services around
+ * them — the recorder the MCP proxy writes through, and the read/revoke
+ * service the Audit log page is built on.
+ */
+export class AuditPrincipalNotFoundError extends Error {
+    constructor() {
+        super('No such agent or key');
+        this.name = 'AuditPrincipalNotFoundError';
+    }
+}
+/** A `before` cursor that is not one this service issued — the caller's mistake, answered as such. */
+export class InvalidCursorError extends Error {
+    constructor() {
+        super('Invalid cursor');
+        this.name = 'InvalidCursorError';
+    }
+}
+/** Shape of the id columns (any uuid version; case-insensitive). */
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+export function isUuid(value) {
+    return UUID_RE.test(value);
+}
+/** The window a retention setting names, or null when it names none this rule accepts. */
+export function parseRetentionWindow(raw) {
+    const trimmed = raw.trim();
+    if (trimmed === '')
+        return 'forever';
+    if (!/^-?\d+$/.test(trimmed))
+        return null;
+    const n = Number(trimmed);
+    return n > 0 ? { days: n } : 'forever';
+}
+//# sourceMappingURL=audit.contract.js.map

package/dist/modules/audit/audit.contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit.contract.js","sourceRoot":"","sources":["../../../src/modules/audit/audit.contract.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAsHH,MAAM,OAAO,2BAA4B,SAAQ,KAAK;IACpD;QACE,KAAK,CAAC,sBAAsB,CAAC,CAAC;QAC9B,IAAI,CAAC,IAAI,GAAG,6BAA6B,CAAC;IAC5C,CAAC;CACF;AAED,sGAAsG;AACtG,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAC3C;QACE,KAAK,CAAC,gBAAgB,CAAC,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;IACnC,CAAC;CACF;AAED,oEAAoE;AACpE,MAAM,OAAO,GAAG,iEAAiE,CAAC;AAElF,MAAM,UAAU,MAAM,CAAC,KAAa;IAClC,OAAO,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AAC7B,CAAC;AAaD,0FAA0F;AAC1F,MAAM,UAAU,oBAAoB,CAAC,GAAW;IAC9C,MAAM,OAAO,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;IAC3B,IAAI,OAAO,KAAK,EAAE;QAAE,OAAO,SAAS,CAAC;IACrC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC;QAAE,OAAO,IAAI,CAAC;IAC1C,MAAM,CAAC,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC;IAC1B,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;AACzC,CAAC"}

package/dist/modules/audit/audit.routes.d.ts

@@ -0,0 +1,21 @@
+import express from 'express';
+import type { IAdminAccessService } from '../admin/admin.interface.js';
+import type { IExternalApiKeyService } from '../tool-auth/external-api-key.interface.js';
+import { type IAgentAuditService } from './audit.contract.js';
+import '../auth/auth.middleware.js';
+/**
+ * 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 declare function createAuditRoutes(audit: IAgentAuditService, keys: Pick<IExternalApiKeyService, 'revoke' | 'revokeAny'>, adminAccess: IAdminAccessService): express.Router;
+//# sourceMappingURL=audit.routes.d.ts.map

package/dist/modules/audit/audit.routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit.routes.d.ts","sourceRoot":"","sources":["../../../src/modules/audit/audit.routes.ts"],"names":[],"mappings":"AAAA,OAAO,OAAO,MAAM,SAAS,CAAC;AAE9B,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAEvE,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,4CAA4C,CAAC;AACzF,OAAO,EAKL,KAAK,kBAAkB,EACxB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,4BAA4B,CAAC;AAMpC;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,kBAAkB,EACzB,IAAI,EAAE,IAAI,CAAC,sBAAsB,EAAE,QAAQ,GAAG,WAAW,CAAC,EAC1D,WAAW,EAAE,mBAAmB,GAC/B,OAAO,CAAC,MAAM,CAkIhB"}

package/dist/modules/audit/audit.routes.js

@@ -0,0 +1,157 @@
+import express from 'express';
+import { logger } from '../../shared/logging.js';
+import { TokenNotFoundError } from '../tool-auth/external-api-key.errors.js';
+import { AuditPrincipalNotFoundError, InvalidCursorError, isUuid, } 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, keys, adminAccess) {
+    const router = express.Router();
+    const isAdmin = (req) => 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) => {
+        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, principal) => {
+        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;
+}
+//# sourceMappingURL=audit.routes.js.map

package/dist/modules/audit/audit.routes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit.routes.js","sourceRoot":"","sources":["../../../src/modules/audit/audit.routes.ts"],"names":[],"mappings":"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"}

package/dist/modules/audit/event-classifier.d.ts

@@ -0,0 +1,52 @@
+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>;
+}
+/** `<manual>.<tool>` → its two halves; a bare name has no manual. */
+export declare function splitUtcpName(utcpName: string): {
+    manual: string;
+    tool: string;
+};
+/**
+ * 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 declare function skillReadPath(utcpName: string, args: Record<string, unknown>, kbManualName: string): string | null;
+/**
+ * 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 declare function skillContaining(path: string, skills: readonly SkillFolder[]): SkillFolder | null;
+/**
+ * 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 declare function classifyToolCall(utcpName: string, args: Record<string, unknown>, ctx: ClassifierContext, skills: readonly SkillFolder[] | null): ClassifiedCall;
+//# sourceMappingURL=event-classifier.d.ts.map

package/dist/modules/audit/event-classifier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-classifier.d.ts","sourceRoot":"","sources":["../../../src/modules/audit/event-classifier.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAE1D;;;;;GAKG;AAEH,2FAA2F;AAC3F,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,cAAc,CAAC;IACrB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,iFAAiF;AACjF,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,iBAAiB;IAChC,2EAA2E;IAC3E,YAAY,EAAE,MAAM,CAAC;IACrB,iFAAiF;IACjF,YAAY,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC3C;AAYD,qEAAqE;AACrE,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAKhF;AAsBD;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAMlH;AAwBD;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,WAAW,EAAE,GAAG,WAAW,GAAG,IAAI,CAahG;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,GAAG,EAAE,iBAAiB,EACtB,MAAM,EAAE,SAAS,WAAW,EAAE,GAAG,IAAI,GACpC,cAAc,CAkBhB"}