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

package/dist/modules/audit/agent-audit.service.js

@@ -0,0 +1,290 @@
+import { and, asc, count, desc, eq, isNull, lt, or } from 'drizzle-orm';
+import { logger } from '../../shared/logging.js';
+import { agentConnections, agentEvents, oauthTokens, users } from '../database/schema.js';
+import { AuditPrincipalNotFoundError, InvalidCursorError, isUuid, parseRetentionWindow, } 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 {
+    db;
+    keys;
+    retentionDays;
+    now;
+    lastPruneAt = 0;
+    constructor(db, keys, 
+    /** Read per sweep, so a changed setting applies without a restart; null = keep forever. */
+    retentionDays, now = Date.now) {
+        this.db = db;
+        this.keys = keys;
+        this.retentionDays = retentionDays;
+        this.now = now;
+    }
+    record(event) {
+        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.
+     */
+    async maybePrune() {
+        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) {
+        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();
+        for (const row of countRows) {
+            const id = row.keyId ?? row.connectionId;
+            if (id)
+                counts.set(id, Number(row.n));
+        }
+        const principals = [
+            ...keyRows.map((k) => ({
+                kind: 'key',
+                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',
+                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 ?? 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. */
+    async keysForUser(userId) {
+        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) {
+        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, page) {
+        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 = 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 = pageRows.map((r) => ({
+            id: r.id,
+            kind: r.kind,
+            manual: r.manual,
+            name: r.name,
+            outcome: r.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, by, ownerUserId) {
+        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, id) {
+    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) {
+    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 = 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) {
+    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;
+}
+//# sourceMappingURL=agent-audit.service.js.map

package/dist/modules/audit/agent-audit.service.js.map

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

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

@@ -0,0 +1,40 @@
+import type { RequestHandler } from 'express';
+import type { IAgentEventRecorder } from './audit.contract.js';
+import { type SkillFolder } from './event-classifier.js';
+import '../tool-auth/tool-auth.middleware.js';
+export interface AgentRestAuditDeps {
+    recorder: IAgentEventRecorder;
+    /** The registered name of the platform's own manual (`KNOWLEDGE_BASE`). */
+    kbManualName: string;
+    /** The caller's skill catalog, for telling a skill read from a file read; fetched only when a read names a path. */
+    skillFolders: (userId: string) => Promise<readonly SkillFolder[]>;
+}
+/**
+ * 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 declare function createAgentRestAuditMiddleware(deps: AgentRestAuditDeps): RequestHandler;
+//# sourceMappingURL=agent-rest-audit.middleware.d.ts.map

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"}