Reorganize repo structure and standards references

This commit is contained in:
david committed 2026-06-29 05:03:42 +02:00
1 parent 3cb93a81be
commit be2054274d
5885 files changed
+2588 -195

No files matched your search

@@ -0,0 +1,202 @@
/**
* 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");
}