Reorganize repo structure and standards references
This commit is contained in:
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");
|
||||
}
|
||||
Reference in new issue
Block a user