203 lines
6.8 KiB
TypeScript
203 lines
6.8 KiB
TypeScript
/**
|
|
* 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<PluginCapabilityUseRecord>;
|
|
}
|
|
|
|
export interface PluginCapabilityUseSink {
|
|
/** Persist a batch. Resolves on success; rejects on transient failure. */
|
|
emit(batch: PluginCapabilityUseBatch): Promise<void>;
|
|
}
|
|
|
|
export interface PluginCapabilityUseLogger {
|
|
warn?: (record: Record<string, unknown>, message?: string) => void;
|
|
error?: (record: Record<string, unknown>, 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<PluginCapabilityUseRecord>;
|
|
/** Emits the batch + clears the buffer. Throws on sink failure when `failClosed` is enabled. */
|
|
flush(): Promise<void>;
|
|
}
|
|
|
|
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");
|
|
}
|