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,219 @@
import { describe, expect, test, vi } from "vitest";
import {
createPluginCapabilityUseRecorder,
hashCapabilityPayload,
PluginCapabilityUseAuditTruncatedError,
type PluginCapabilityUseBatch,
type PluginCapabilityUseSink,
} from "./audit.js";
function makeSink(): {
sink: PluginCapabilityUseSink;
batches: PluginCapabilityUseBatch[];
} {
const batches: PluginCapabilityUseBatch[] = [];
return {
batches,
sink: {
async emit(batch) {
batches.push(batch);
},
},
};
}
describe("createPluginCapabilityUseRecorder", () => {
test("buffers records then flushes them as a single batch", async () => {
const { sink, batches } = makeSink();
const recorder = createPluginCapabilityUseRecorder({
tenantId: "t1",
pluginId: "de.acme.slack",
sink,
});
recorder.record({ capability: "log", outcome: "success", durationMs: 1 });
recorder.record({ capability: "http.outbound", outcome: "success", durationMs: 12 });
expect(recorder.snapshot()).toHaveLength(2);
await recorder.flush();
expect(batches).toHaveLength(1);
expect(batches[0]?.entries).toHaveLength(2);
expect(batches[0]?.pluginId).toBe("de.acme.slack");
expect(batches[0]?.tenantId).toBe("t1");
expect(recorder.snapshot()).toHaveLength(0);
});
test("flush is a no-op when no entries were recorded", async () => {
const { sink, batches } = makeSink();
const recorder = createPluginCapabilityUseRecorder({
tenantId: "t1",
pluginId: "p1",
sink,
});
await recorder.flush();
expect(batches).toHaveLength(0);
});
test("uses the supplied pluginInvocationId for every record + the batch", async () => {
const { sink, batches } = makeSink();
const recorder = createPluginCapabilityUseRecorder({
tenantId: "t1",
pluginId: "p1",
pluginInvocationId: "inv-fixed",
sink,
});
recorder.record({ capability: "log", outcome: "success" });
await recorder.flush();
expect(recorder.pluginInvocationId).toBe("inv-fixed");
expect(batches[0]?.pluginInvocationId).toBe("inv-fixed");
expect(batches[0]?.entries[0]?.pluginInvocationId).toBe("inv-fixed");
});
test("sink failure does not propagate — logs an error instead", async () => {
const errors: Record<string, unknown>[] = [];
const recorder = createPluginCapabilityUseRecorder({
tenantId: "t1",
pluginId: "p1",
sink: {
async emit() {
throw new Error("db down");
},
},
logger: {
error: (record) => {
errors.push(record);
},
},
});
recorder.record({ capability: "log", outcome: "success" });
await expect(recorder.flush()).resolves.toBeUndefined();
expect(errors).toHaveLength(1);
expect(errors[0]?.entryCount).toBe(1);
});
test("sink failure propagates when failClosed is enabled", async () => {
const errors: Record<string, unknown>[] = [];
const recorder = createPluginCapabilityUseRecorder({
tenantId: "t1",
pluginId: "p1",
failClosed: true,
sink: {
async emit() {
throw new Error("outbox down");
},
},
logger: {
error: (record) => {
errors.push(record);
},
},
});
recorder.record({ capability: "log", outcome: "success" });
await expect(recorder.flush()).rejects.toThrow("outbox down");
expect(errors).toHaveLength(1);
expect(errors[0]?.entryCount).toBe(1);
});
test("drops entries past maxEntries and warns once on flush", async () => {
const { sink } = makeSink();
const warns: Record<string, unknown>[] = [];
const recorder = createPluginCapabilityUseRecorder({
tenantId: "t1",
pluginId: "p1",
sink,
maxEntries: 2,
logger: {
warn: (record) => {
warns.push(record);
},
},
});
recorder.record({ capability: "log", outcome: "success" });
recorder.record({ capability: "log", outcome: "success" });
recorder.record({ capability: "log", outcome: "success" });
recorder.record({ capability: "log", outcome: "success" });
expect(recorder.snapshot()).toHaveLength(2);
await recorder.flush();
expect(warns).toHaveLength(1);
expect(warns[0]?.droppedCount).toBe(2);
});
test("fails closed on truncated capability-use audit while preserving retained entries", async () => {
const { sink, batches } = makeSink();
const warns: Record<string, unknown>[] = [];
const recorder = createPluginCapabilityUseRecorder({
tenantId: "t1",
pluginId: "p1",
sink,
failClosed: true,
maxEntries: 2,
logger: {
warn: (record) => {
warns.push(record);
},
},
});
recorder.record({ capability: "log", outcome: "success" });
recorder.record({ capability: "audit", outcome: "success" });
recorder.record({ capability: "http.outbound", outcome: "success" });
await expect(recorder.flush()).rejects.toThrow(PluginCapabilityUseAuditTruncatedError);
expect(batches).toHaveLength(1);
expect(batches[0]?.entries.map((entry) => entry.capability)).toEqual(["log", "audit"]);
expect(warns).toHaveLength(1);
expect(warns[0]).toMatchObject({ droppedCount: 1, maxEntries: 2 });
});
test("records error + denied outcomes alongside successes", async () => {
const { sink, batches } = makeSink();
const recorder = createPluginCapabilityUseRecorder({
tenantId: "t1",
pluginId: "p1",
sink,
});
recorder.record({ capability: "log", outcome: "success" });
recorder.record({
capability: "http.outbound",
outcome: "denied",
errorCode: "not_declared_in_manifest",
});
recorder.record({
capability: "http.outbound",
outcome: "error",
errorCode: "host_fn_threw",
durationMs: 7,
});
await recorder.flush();
const outcomes = batches[0]?.entries.map((e) => e.outcome);
expect(outcomes).toEqual(["success", "denied", "error"]);
});
});
describe("hashCapabilityPayload", () => {
test("produces a deterministic SHA-256 hex digest", () => {
const a = hashCapabilityPayload("GET https://example.com");
const b = hashCapabilityPayload("GET https://example.com");
const c = hashCapabilityPayload("POST https://example.com");
expect(a).toEqual(b);
expect(a).not.toEqual(c);
expect(a).toMatch(/^[0-9a-f]{64}$/);
});
});
describe("integration with capability gateway hook", () => {
test("records each invocation when wired as a gateway-onCall hook", async () => {
const { sink, batches } = makeSink();
const recorder = createPluginCapabilityUseRecorder({
tenantId: "t1",
pluginId: "p1",
sink,
});
const onCall = vi.fn((info: { capability: string; outcome: "success" | "denied" | "error"; durationMs?: number; errorCode?: string }) => {
recorder.record(info);
});
onCall({ capability: "log", outcome: "success", durationMs: 1 });
onCall({ capability: "audit", outcome: "success", durationMs: 1 });
await recorder.flush();
expect(onCall).toHaveBeenCalledTimes(2);
expect(batches[0]?.entries.map((e) => e.capability)).toEqual(["log", "audit"]);
});
});