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

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

package/dist/modules/audit/event-classifier.js

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

package/dist/modules/audit/event-classifier.js.map

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

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/modules/audit/index.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAC;AACpC,OAAO,EAAE,iBAAiB,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAChG,OAAO,EAAE,8BAA8B,EAAE,MAAM,kCAAkC,CAAC;AAClF,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EACL,gBAAgB,EAChB,eAAe,EACf,aAAa,EACb,aAAa,EACb,KAAK,cAAc,EACnB,KAAK,iBAAiB,EACtB,KAAK,WAAW,GACjB,MAAM,uBAAuB,CAAC"}

package/dist/modules/audit/index.js

@@ -0,0 +1,7 @@
+export * from './audit.contract.js';
+export { AgentAuditService, MAX_EVENT_PAGE, retentionDaysFrom } from './agent-audit.service.js';
+export { createAgentRestAuditMiddleware } from './agent-rest-audit.middleware.js';
+export { createAuditRoutes } from './audit.routes.js';
+export { RequestAudit } from './request-audit.js';
+export { classifyToolCall, skillContaining, skillReadPath, splitUtcpName, } from './event-classifier.js';
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/modules/audit/index.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAC;AACpC,OAAO,EAAE,iBAAiB,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAChG,OAAO,EAAE,8BAA8B,EAAE,MAAM,kCAAkC,CAAC;AAClF,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EACL,gBAAgB,EAChB,eAAe,EACf,aAAa,EACb,aAAa,GAId,MAAM,uBAAuB,CAAC"}

package/dist/modules/audit/request-audit.d.ts

@@ -0,0 +1,57 @@
+import type { CodeModeUtcpClient } from '@utcp/code-mode';
+import type { AgentEventOutcome, AuditPrincipalRef, IAgentEventRecorder } from './audit.contract.js';
+import { type ClassifiedCall, type SkillFolder } from './event-classifier.js';
+/**
+ * The Audit log's view of ONE MCP request: who is calling (the user and the
+ * key or agent connection the request arrived through), and how to name what
+ * they call. The MCP proxy creates one per request that has a principal and
+ * routes every call through it; a request with none (a browser JWT, an
+ * internal token minted before connections existed) gets no instance and
+ * records nothing.
+ *
+ * Holds nothing that outlives the request. The skill catalog it may need to
+ * tell a skill read from a file read is fetched at most once, and only when
+ * a platform read names a path.
+ */
+export declare class RequestAudit {
+    private readonly recorder;
+    private readonly userId;
+    private readonly principal;
+    private readonly ctx;
+    private skills;
+    constructor(recorder: IAgentEventRecorder, userId: string, principal: AuditPrincipalRef, ctx: {
+        kbManualName: string;
+        /** Read at classification time — the surface (and its catalog names) is built lazily. */
+        catalogNames: () => ReadonlyMap<string, string>;
+        /** The caller's skill catalog, for telling a skill read from a file read. */
+        loadSkills: () => Promise<readonly SkillFolder[]>;
+    });
+    /** Record one already-classified call. Never throws. */
+    emit(call: ClassifiedCall, outcome: AgentEventOutcome, durationMs: number | null): void;
+    /** What a UTCP call is logged as — fetching the skill catalog first when the call might be a skill read. */
+    classify(utcpName: string, args: Record<string, unknown>): Promise<ClassifiedCall>;
+    /**
+     * Run a UTCP call and record it: `error` when it throws or `isError` says
+     * the result is one, `ok` otherwise. The result (or the throw) reaches the
+     * caller unchanged — recording is a side effect, never a filter.
+     *
+     * The call starts FIRST and is classified alongside: naming a read may cost
+     * a loopback fetch of the skill catalog, and that is the log's business,
+     * not the tool's — a tool result never waits on its own bookkeeping.
+     */
+    call<T>(utcpName: string, args: Record<string, unknown>, run: () => Promise<T>, isError: (result: T) => boolean): Promise<T>;
+    /** A call refused before it ran, because the caller's sign-in for its manual is missing. */
+    denied(utcpName: string, args: Record<string, unknown>): Promise<void>;
+    /**
+     * Record every tool call made from INSIDE `call_tool_chain`: the chain
+     * bridges each in-isolate tool function to `client.callTool`, so wrapping
+     * that one entry point catches them all. Installed after the downstream
+     * routing wrapper so the timing covers the pool lease and any retry too.
+     * The direct MCP path (`callToolStreaming`) is deliberately NOT wrapped —
+     * the proxy's tool handler records those itself, with the result's
+     * `isError` in hand.
+     */
+    instrumentChainCalls(client: CodeModeUtcpClient): void;
+    private skillCatalog;
+}
+//# sourceMappingURL=request-audit.d.ts.map

package/dist/modules/audit/request-audit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-audit.d.ts","sourceRoot":"","sources":["../../../src/modules/audit/request-audit.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAE1D,OAAO,KAAK,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AACrG,OAAO,EAGL,KAAK,cAAc,EAEnB,KAAK,WAAW,EACjB,MAAM,uBAAuB,CAAC;AAI/B;;;;;;;;;;;GAWG;AACH,qBAAa,YAAY;IAIrB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,GAAG;IANtB,OAAO,CAAC,MAAM,CAAqD;gBAGhD,QAAQ,EAAE,mBAAmB,EAC7B,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,iBAAiB,EAC5B,GAAG,EAAE;QACpB,YAAY,EAAE,MAAM,CAAC;QACrB,yFAAyF;QACzF,YAAY,EAAE,MAAM,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAChD,6EAA6E;QAC7E,UAAU,EAAE,MAAM,OAAO,CAAC,SAAS,WAAW,EAAE,CAAC,CAAC;KACnD;IAGH,wDAAwD;IACxD,IAAI,CAAC,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI;IAgBvF,4GAA4G;IACtG,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,cAAc,CAAC;IAOxF;;;;;;;;OAQG;IACG,IAAI,CAAC,CAAC,EACV,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,GAAG,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACrB,OAAO,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,OAAO,GAC9B,OAAO,CAAC,CAAC,CAAC;IAeb,4FAA4F;IACtF,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAI5E;;;;;;;;OAQG;IACH,oBAAoB,CAAC,MAAM,EAAE,kBAAkB,GAAG,IAAI;IAMtD,OAAO,CAAC,YAAY;CAUrB"}

package/dist/modules/audit/request-audit.js

@@ -0,0 +1,117 @@
+import { logger } from '../../shared/logging.js';
+import { classifyToolCall, skillReadPath, } from './event-classifier.js';
+const log = logger('audit');
+/**
+ * The Audit log's view of ONE MCP request: who is calling (the user and the
+ * key or agent connection the request arrived through), and how to name what
+ * they call. The MCP proxy creates one per request that has a principal and
+ * routes every call through it; a request with none (a browser JWT, an
+ * internal token minted before connections existed) gets no instance and
+ * records nothing.
+ *
+ * Holds nothing that outlives the request. The skill catalog it may need to
+ * tell a skill read from a file read is fetched at most once, and only when
+ * a platform read names a path.
+ */
+export class RequestAudit {
+    recorder;
+    userId;
+    principal;
+    ctx;
+    skills;
+    constructor(recorder, userId, principal, ctx) {
+        this.recorder = recorder;
+        this.userId = userId;
+        this.principal = principal;
+        this.ctx = ctx;
+    }
+    /** Record one already-classified call. Never throws. */
+    emit(call, outcome, durationMs) {
+        try {
+            this.recorder.record({
+                userId: this.userId,
+                principal: this.principal,
+                kind: call.kind,
+                manual: call.manual,
+                name: call.name,
+                outcome,
+                durationMs,
+            });
+        }
+        catch (err) {
+            log.warn('recording an agent event failed:', { err });
+        }
+    }
+    /** What a UTCP call is logged as — fetching the skill catalog first when the call might be a skill read. */
+    async classify(utcpName, args) {
+        const ctx = { kbManualName: this.ctx.kbManualName, catalogNames: this.ctx.catalogNames() };
+        const wantsSkills = skillReadPath(utcpName, args, ctx.kbManualName) !== null;
+        const skills = wantsSkills ? await this.skillCatalog() : null;
+        return classifyToolCall(utcpName, args, ctx, skills);
+    }
+    /**
+     * Run a UTCP call and record it: `error` when it throws or `isError` says
+     * the result is one, `ok` otherwise. The result (or the throw) reaches the
+     * caller unchanged — recording is a side effect, never a filter.
+     *
+     * The call starts FIRST and is classified alongside: naming a read may cost
+     * a loopback fetch of the skill catalog, and that is the log's business,
+     * not the tool's — a tool result never waits on its own bookkeeping.
+     */
+    async call(utcpName, args, run, isError) {
+        const started = performance.now();
+        const classified = this.classify(utcpName, args);
+        try {
+            const result = await run();
+            const duration = elapsed(started);
+            this.emit(await classified, isError(result) ? 'error' : 'ok', duration);
+            return result;
+        }
+        catch (err) {
+            const duration = elapsed(started);
+            this.emit(await classified, 'error', duration);
+            throw err;
+        }
+    }
+    /** A call refused before it ran, because the caller's sign-in for its manual is missing. */
+    async denied(utcpName, args) {
+        this.emit(await this.classify(utcpName, args), 'denied', null);
+    }
+    /**
+     * Record every tool call made from INSIDE `call_tool_chain`: the chain
+     * bridges each in-isolate tool function to `client.callTool`, so wrapping
+     * that one entry point catches them all. Installed after the downstream
+     * routing wrapper so the timing covers the pool lease and any retry too.
+     * The direct MCP path (`callToolStreaming`) is deliberately NOT wrapped —
+     * the proxy's tool handler records those itself, with the result's
+     * `isError` in hand.
+     */
+    instrumentChainCalls(client) {
+        const callTool = client.callTool.bind(client);
+        client.callTool = (toolName, toolArgs) => this.call(toolName, toolArgs, () => callTool(toolName, toolArgs), isErrorShaped);
+    }
+    skillCatalog() {
+        // A failed fetch is remembered as "no catalog" for the rest of the
+        // request: the read is then logged as a capability, and one hiccup does
+        // not cost a loopback round-trip per subsequent call.
+        this.skills ??= this.ctx.loadSkills().catch((err) => {
+            log.warn('skill catalog unavailable for audit classification:', { err });
+            return null;
+        });
+        return this.skills;
+    }
+}
+function elapsed(started) {
+    return Math.max(0, Math.round(performance.now() - started));
+}
+/**
+ * A chain-internal result that is the tool saying it failed. A downstream
+ * MCP server answers a failed call with `{ isError: true, content }` as a
+ * VALUE (the UTCP mcp protocol hands it through rather than throwing), and
+ * the direct path records that as an error — so must the chain path, or the
+ * same failure would read `ok` inside a chain and `error` outside one.
+ */
+function isErrorShaped(result) {
+    return typeof result === 'object' && result !== null && result.isError === true;
+}
+//# sourceMappingURL=request-audit.js.map

package/dist/modules/audit/request-audit.js.map

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

package/dist/modules/auth/account-erasure.service.d.ts

@@ -1,4 +1,9 @@
 import type { Database } from '../database/connection.js';
+import type { IReviewWorkflowService } from '../workflow/review-workflow/review-workflow.interface.js';
+/** The anonymised id of one erasure — how a commit or log may name the account. */
+export declare function erasedAccountId(erasureId: string): string;
+/** The placeholder email anonymised audit rows carry for one erasure. */
+export declare function erasedEmailFor(erasureId: string): string;
 /** A user row as the admin surface needs it (no avatar, no timestamps churn). */
 export interface AdminUserView {
     id: string;
@@ -67,14 +72,35 @@ export interface IErasureParticipant {
  */
 export interface IAccountErasureService {
     listUsers(): Promise<AdminUserView[]>;
-    /** Erase `userId`. Returns false when no such user exists. */
-    eraseUser(userId: string): Promise<boolean>;
+    /**
+     * Erase `userId`. Returns false when no such user exists. `erasureId` fixes
+     * the anonymised identity (`deleted-<erasureId>@erased.invalid`) so a caller
+     * can name the erased account elsewhere — e.g. a commit message — without
+     * the email; random when omitted.
+     */
+    eraseUser(userId: string, opts?: {
+        erasureId?: string;
+    }): Promise<boolean>;
 }
 export declare class AccountErasureService implements IAccountErasureService {
     private readonly db;
+    /**
+     * The review workflow owns the approvals and the lock their writers take,
+     * so it does the rewrite (see `IReviewWorkflowService.eraseApprover`);
+     * this module only decides WHEN, inside its own transaction.
+     */
+    private readonly reviewWorkflow;
     private readonly participants;
-    constructor(db: Database, participants?: IErasureParticipant[]);
+    constructor(db: Database, 
+    /**
+     * The review workflow owns the approvals and the lock their writers take,
+     * so it does the rewrite (see `IReviewWorkflowService.eraseApprover`);
+     * this module only decides WHEN, inside its own transaction.
+     */
+    reviewWorkflow: Pick<IReviewWorkflowService, 'eraseApprover'>, participants?: IErasureParticipant[]);
     listUsers(): Promise<AdminUserView[]>;
-    eraseUser(userId: string): Promise<boolean>;
+    eraseUser(userId: string, opts?: {
+        erasureId?: string;
+    }): Promise<boolean>;
 }
 //# sourceMappingURL=account-erasure.service.d.ts.map

package/dist/modules/auth/account-erasure.service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"account-erasure.service.d.ts","sourceRoot":"","sources":["../../../src/modules/auth/account-erasure.service.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAc1D,iFAAiF;AACjF,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,8EAA8E;AAC9E,MAAM,MAAM,SAAS,GAAG,UAAU,CAAC,UAAU,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAE9E,4CAA4C;AAC5C,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,4EAA4E;IAC5E,KAAK,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,mBAAmB;IAClC,MAAM,CAAC,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9C,aAAa,CAAC,CAAC,EAAE,EAAE,SAAS,EAAE,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,GAAG,CAAC,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;CAC7F;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,WAAW,sBAAsB;IACrC,SAAS,IAAI,OAAO,CAAC,aAAa,EAAE,CAAC,CAAC;IACtC,8DAA8D;IAC9D,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC7C;AAED,qBAAa,qBAAsB,YAAW,sBAAsB;IAEhE,OAAO,CAAC,QAAQ,CAAC,EAAE;IACnB,OAAO,CAAC,QAAQ,CAAC,YAAY;gBADZ,EAAE,EAAE,QAAQ,EACZ,YAAY,GAAE,mBAAmB,EAAO;IAGrD,SAAS,IAAI,OAAO,CAAC,aAAa,EAAE,CAAC;IAQrC,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;CA4ElD"}
+{"version":3,"file":"account-erasure.service.d.ts","sourceRoot":"","sources":["../../../src/modules/auth/account-erasure.service.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAC1D,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,0DAA0D,CAAC;AAevG,mFAAmF;AACnF,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAEzD;AAED,yEAAyE;AACzE,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAExD;AAED,iFAAiF;AACjF,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,8EAA8E;AAC9E,MAAM,MAAM,SAAS,GAAG,UAAU,CAAC,UAAU,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAE9E,4CAA4C;AAC5C,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,4EAA4E;IAC5E,KAAK,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,mBAAmB;IAClC,MAAM,CAAC,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9C,aAAa,CAAC,CAAC,EAAE,EAAE,SAAS,EAAE,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,GAAG,CAAC,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;CAC7F;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,WAAW,sBAAsB;IACrC,SAAS,IAAI,OAAO,CAAC,aAAa,EAAE,CAAC,CAAC;IACtC;;;;;OAKG;IACH,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC5E;AAED,qBAAa,qBAAsB,YAAW,sBAAsB;IAEhE,OAAO,CAAC,QAAQ,CAAC,EAAE;IACnB;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,cAAc;IAC/B,OAAO,CAAC,QAAQ,CAAC,YAAY;gBAPZ,EAAE,EAAE,QAAQ;IAC7B;;;;OAIG;IACc,cAAc,EAAE,IAAI,CAAC,sBAAsB,EAAE,eAAe,CAAC,EAC7D,YAAY,GAAE,mBAAmB,EAAO;IAGrD,SAAS,IAAI,OAAO,CAAC,aAAa,EAAE,CAAC;IAQrC,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,GAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAO,GAAG,OAAO,CAAC,OAAO,CAAC;CA6JrF"}