/** * Plugin capability-use audit recorder — Phase 06 #23. * * Buffers one entry per host-fn call inside a plugin invocation, then * emits them as a single `plugin.capability-use.batch` outbox event at * sandbox close. The worker handler (apps/worker/src/jobs/plugin- * capability-use.ts) is what eventually writes the rows into the * `PluginCapabilityUse` table — keeping the plugin hot-path off the DB. * * Body content is NEVER stored. Callers pass an optional `payloadHash` * (SHA-256 of a stable arg-shape descriptor) so forensics can match a * suspected payload without retaining tenant data. DSGVO-minimisation * applies to every field exposed here. * * Failure mode defaults to soft for local/dev callers. Production * worker bootstraps should set `failClosed: true` so the invocation * fails instead of acknowledging execution without durable capability * telemetry. */ import { createHash, randomUUID } from "node:crypto"; export type PluginCapabilityUseOutcome = "success" | "denied" | "error"; export interface PluginCapabilityUseEntry { /** Capability name (e.g. "http.outbound", "log"). */ readonly capability: string; /** Outcome of the host-fn call. */ readonly outcome: PluginCapabilityUseOutcome; /** Optional SHA-256 hex of a stable arg-shape descriptor. */ readonly payloadHash?: string; /** Optional short error-code (e.g. "not_declared_in_manifest"). */ readonly errorCode?: string; /** Optional duration in milliseconds. */ readonly durationMs?: number; } export interface PluginCapabilityUseRecord extends PluginCapabilityUseEntry { /** Per-call uuid — primary key in the PluginCapabilityUse table. */ readonly id: string; /** Sandbox-generated invocation id (groups every host-fn call of one run). */ readonly pluginInvocationId: string; readonly tenantId: string; readonly pluginId: string; /** ISO-8601 string — the worker parses this back to a Date. */ readonly timestamp: string; } export interface PluginCapabilityUseBatch { readonly pluginInvocationId: string; readonly tenantId: string; readonly pluginId: string; readonly entries: ReadonlyArray; } export interface PluginCapabilityUseSink { /** Persist a batch. Resolves on success; rejects on transient failure. */ emit(batch: PluginCapabilityUseBatch): Promise; } export interface PluginCapabilityUseLogger { warn?: (record: Record, message?: string) => void; error?: (record: Record, message?: string) => void; } export interface PluginCapabilityUseRecorderOptions { readonly tenantId: string; readonly pluginId: string; /** * Optional pre-assigned invocation id. Defaults to a fresh uuid * when omitted (lets the sandbox use the same id as elsewhere). */ readonly pluginInvocationId?: string; readonly sink: PluginCapabilityUseSink; readonly logger?: PluginCapabilityUseLogger; /** * Propagate sink failures after logging them. Production plugin workers * should enable this so capability-use audit loss fails closed. */ readonly failClosed?: boolean; /** * Hard cap on retained entries per invocation. Prevents runaway * plugins from exhausting heap by spamming capability calls. * Defaults to 1024. */ readonly maxEntries?: number; } export interface PluginCapabilityUseRecorder { readonly pluginInvocationId: string; record(entry: PluginCapabilityUseEntry): void; /** Snapshot of currently buffered records — mostly useful in tests. */ snapshot(): ReadonlyArray; /** Emits the batch + clears the buffer. Throws on sink failure when `failClosed` is enabled. */ flush(): Promise; } const DEFAULT_MAX_ENTRIES = 1024; export class PluginCapabilityUseAuditTruncatedError extends Error { override readonly name = "PluginCapabilityUseAuditTruncatedError"; constructor( readonly pluginInvocationId: string, readonly droppedCount: number, readonly maxEntries: number ) { super(`Plugin capability-use audit dropped ${droppedCount} entries after maxEntries=${maxEntries}.`); } } /** * Build an invocation-scoped recorder. Callers create one per plugin * invocation, hand the `record()` callback to the capability gateway, * and call `flush()` once the plugin returns (or traps). */ export function createPluginCapabilityUseRecorder( options: PluginCapabilityUseRecorderOptions ): PluginCapabilityUseRecorder { const pluginInvocationId = options.pluginInvocationId ?? randomUUID(); const maxEntries = options.maxEntries ?? DEFAULT_MAX_ENTRIES; const buffer: PluginCapabilityUseRecord[] = []; let droppedCount = 0; return { pluginInvocationId, record(entry) { if (buffer.length >= maxEntries) { droppedCount += 1; return; } buffer.push({ ...entry, id: randomUUID(), pluginInvocationId, tenantId: options.tenantId, pluginId: options.pluginId, timestamp: new Date().toISOString(), }); }, snapshot() { return [...buffer]; }, async flush() { if (buffer.length === 0) { return; } const batch: PluginCapabilityUseBatch = { pluginInvocationId, tenantId: options.tenantId, pluginId: options.pluginId, entries: [...buffer], }; buffer.length = 0; try { await options.sink.emit(batch); buffer.length = 0; } catch (err) { options.logger?.error?.( { err: err instanceof Error ? { name: err.name, message: err.message } : err, pluginInvocationId, tenantId: options.tenantId, pluginId: options.pluginId, entryCount: batch.entries.length, }, "plugin capability-use audit flush failed" ); if (options.failClosed) { throw err; } buffer.length = 0; } if (droppedCount > 0) { const error = new PluginCapabilityUseAuditTruncatedError(pluginInvocationId, droppedCount, maxEntries); options.logger?.warn?.( { pluginInvocationId, tenantId: options.tenantId, pluginId: options.pluginId, droppedCount, maxEntries, }, "plugin capability-use audit dropped entries past max" ); droppedCount = 0; if (options.failClosed) { throw error; } } }, }; } /** * Hash a stable description of host-fn args. Plugin runtimes call this * with the smallest sensible descriptor (e.g. for `http.outbound` * "GET https://hooks.slack.com/services/X") and store the resulting * hex digest in `payloadHash` — never the original body. */ export function hashCapabilityPayload(descriptor: string): string { return createHash("sha256").update(descriptor, "utf8").digest("hex"); }