@voltro/plugin-audit 0.33.0 → 0.34.0

package/dist/index.d.ts

@@ -43,6 +43,68 @@ export declare const auditBySubject: (store: AuditQueryStore, subjectId: string,
  */
 export declare const auditByTrace: (store: AuditQueryStore, traceId: string) => Promise<ReadonlyArray<Record<string, unknown>>>;
 
+/** A writer's chain state. One per `dataStoreAuditSink`, i.e. one per process. */
+export declare interface AuditChain {
+    readonly chainId: string;
+    /**
+     * Allocate this row's link and stamp it onto the row. SYNCHRONOUS and
+     * `await`-free by construction — that is the whole concurrency argument (see
+     * the header). Do not make it async.
+     */
+    readonly link: (row: Record<string, unknown>) => Record<string, unknown>;
+}
+
+export declare interface AuditChainIssue {
+    readonly kind: AuditChainIssueKind;
+    readonly chainId: string;
+    readonly seq: number;
+    /** The offending row's id, when it has one (a `gap` names the MISSING seq,
+     *  so it has no row and no id). */
+    readonly rowId?: string;
+    readonly detail: string;
+}
+
+export declare type AuditChainIssueKind = 'tampered' | 'broken-link' | 'gap';
+
+/** The columns the chain adds to `_voltro_audit_log`. */
+export declare interface AuditChainLink {
+    /** Which writer's chain this row belongs to. Null for an unchained row. */
+    readonly chainId: string;
+    /** 1-based position within `chainId`. */
+    readonly seq: number;
+    /** The previous row's `hash`, or null for the first row of a chain. */
+    readonly prevHash: string | null;
+    /** `H(chainId, seq, prevHash, content)` — hex. */
+    readonly hash: string;
+}
+
+export declare interface AuditChainSummary {
+    readonly chainId: string;
+    /** Lowest `seq` present. `> 1` means the retention sweep pruned a prefix. */
+    readonly from: number;
+    /** Highest `seq` present. */
+    readonly to: number;
+    /** The tip hash — publish this somewhere append-only to defeat tail
+     *  truncation and to bind an unkeyed chain to a point in time. */
+    readonly tip: string;
+    /** Whether the chain starts above `seq` 1 (a pruned prefix, not an issue). */
+    readonly prunedPrefix: boolean;
+}
+
+export declare interface AuditChainVerification {
+    readonly ok: boolean;
+    readonly rowsChecked: number;
+    /** Rows carrying no `hash` — written before chaining shipped, or stripped.
+     *  Not an `issue` (a pre-chain deployment is not tampering) but never
+     *  silently dropped either. */
+    readonly unchainedRows: number;
+    readonly chains: ReadonlyArray<AuditChainSummary>;
+    readonly issues: ReadonlyArray<AuditChainIssue>;
+    /** Whether the digest was keyed. An `ok: true` from an UNKEYED run is a
+     *  weaker statement — surfaced so a report cannot quietly overstate it. */
+    readonly keyed: boolean;
+}
+
 /** Narrow slice of the framework DataStore the durable sink needs. */
 export declare interface AuditDataStore {
     insert: (table: string, row: Record<string, unknown>) => Promise<unknown>;
@@ -113,6 +175,35 @@ export declare const auditLogTables: ReadonlyArray<AuditLogTable>;
 export declare const auditPlugin: (options?: AuditPluginOptions) => VoltroPlugin;
 
 export declare interface AuditPluginOptions {
+    /**
+     * Namespace for this plugin's inspect surface + any rpc tags it contributes. Default `audit`.
+     *
+     * Set it when your app already publishes under that name — an exact tag
+     * collision is fatal at codegen, and this is the way out.
+     */
+    readonly alias?: string;
+    /**
+     * Contribute this plugin's tables via `extendSchema.tables`. Default `true`.
+     *
+     * Set `false` when your app ALREADY declares equivalent tables and you want to
+     * keep them — the seam this exists for. The plugin then contributes no DDL and
+     * the declarative differ never proposes its tables; everything else (routes,
+     * inspect, interceptors) is unchanged.
+     *
+     * **What you take over, exactly:** a table named `_voltro_audit_log` with the shape
+     * `auditLogTable` declares (exported from this package, so declare it with
+     * `.renamedFrom()` or copy its columns). The `datastore` sink writes to it BY
+     * NAME through the bound store; nothing validates that it exists, so a missing
+     * or mis-shaped table fails at the first audited mutation, not at boot.
+     *
+     * It is not offered on every plugin, and the omissions are deliberate rather
+     * than unfinished: a `tables: false` that quietly disables a table carrying an
+     * AUTHORIZATION or SAFETY decision — the SAML replay cache, SCIM provisioning
+     * state, billing's usage counters, cdc-out's outbox — is a security regression
+     * shipped as an ergonomics feature. Those plugins need a named store seam
+     * first, not a boolean.
+     */
+    readonly tables?: boolean;
     /**
      * Where to record audit events:
      *   - 'console' (default) — pretty-prints to stdout for local dev.
@@ -336,6 +427,15 @@ export declare interface AuditQueryStore {
     query: (descriptor: unknown) => Promise<ReadonlyArray<Record<string, unknown>>>;
 }
 
+/** `H(chainId, seq, prevHash, content)` for one row. Pure — the verifier and
+ *  the writer call the SAME function, which is what makes the check mean
+ *  anything. */
+export declare const auditRowHash: (row: Record<string, unknown>, link: {
+    readonly chainId: string;
+    readonly seq: number;
+    readonly prevHash: string | null;
+}) => string;
+
 export declare type AuditSink = (event: AuditEvent) => void | Promise<void> | Effect.Effect<void>;
 
 /** Drop everything in the in-process buffer. Useful between smoke phases. */
@@ -349,6 +449,10 @@ export declare const clearAuditBuffer: () => void;
  */
 export declare const dataStoreAuditSink: (store: AuditDataStore) => (event: AuditEvent) => Promise<void>;
 
+/** Mint a fresh chain. `chainId` is 96 bits of CSPRNG — collisions across
+ *  replicas would merge two chains into one apparent fork. */
+export declare const makeAuditChain: (chainId?: string) => AuditChain;
+
 /**
  * Read the in-process audit buffer. Returns a stable snapshot copy —
  * mutating it has no effect on the running buffer. Empty array when
@@ -356,6 +460,23 @@ export declare const dataStoreAuditSink: (store: AuditDataStore) => (event: Audi
  */
 export declare const readAuditBuffer: () => ReadonlyArray<AuditEvent>;
 
+/**
+ * Recompute every chain in `_voltro_audit_log` and report what does not add up.
+ *
+ * Reads through the same `AuditQueryStore` the other read entry points use, so
+ * it works against any dialect and inside a transaction. Ordered by
+ * `(chainId, seq)` — the `byAuditChain` index exists for exactly this scan.
+ */
+export declare const verifyAuditChain: (store: AuditQueryStore, options?: VerifyAuditChainOptions) => Promise<AuditChainVerification>;
+
+export declare interface VerifyAuditChainOptions {
+    /** Verify one writer's chain instead of all of them. */
+    readonly chainId?: string;
+    /** Cap the rows read. Unset = every row, which is the honest default for a
+     *  completeness check; pass one for a spot check on a very large table. */
+    readonly limit?: number;
+}
+
 export { VoltroPlugin }
 
 export { }

package/dist/index.js

@@ -1,25 +1,142 @@
 import { audit as e } from "./mixin.js";
 import { Effect as t } from "effect";
-import { definePlugin as n } from "@voltro/protocol";
-import { createLogger as r } from "@voltro/logger";
-import { and as i, eq as a, id as o, json as s, registerRetention as c, resolveActorSnapshot as l, retentionTtlMsFromEnv as u, table as d, text as f, timestamp as p } from "@voltro/database";
-//#region src/store.ts
-var m = "_voltro_audit_log", h = d(m, {
-	id: o({ prefix: "audit" }),
-	tag: f(),
-	at: p(),
-	subjectId: f().nullable(),
-	tenantId: f().nullable(),
-	traceId: f(),
-	status: f(),
-	durationMs: f(),
-	subject: s(),
-	actor: s().nullable(),
-	scope: s().nullable(),
-	metadata: s().nullable(),
-	input: s(),
-	outcome: s(),
-	errorTag: f().nullable()
+import { definePlugin as n, pluginInstanceName as r } from "@voltro/protocol";
+import { createLogger as i } from "@voltro/logger";
+import { and as a, eq as o, id as s, integer as c, json as l, registerRetention as u, resolveActorSnapshot as d, retentionTtlMsFromEnv as f, table as p, text as m, timestamp as h } from "@voltro/database";
+import { createHash as g, createHmac as _, randomBytes as v } from "node:crypto";
+//#region src/tableName.ts
+var y = "_voltro_audit_log", b = [
+	"tag",
+	"at",
+	"subjectId",
+	"tenantId",
+	"traceId",
+	"status",
+	"durationMs",
+	"subject",
+	"actor",
+	"scope",
+	"metadata",
+	"input",
+	"outcome",
+	"errorTag"
+], x = (e) => {
+	if (e == null) return "null";
+	if (e instanceof Date) return JSON.stringify(e.toISOString());
+	let t = typeof e;
+	return t === "number" || t === "boolean" || t === "string" ? JSON.stringify(e) : t === "bigint" ? JSON.stringify(String(e)) : Array.isArray(e) ? `[${e.map(x).join(",")}]` : t === "object" ? `{${Object.entries(e).filter(([, e]) => e !== void 0).sort(([e], [t]) => e < t ? -1 : +(e > t)).map(([e, t]) => `${JSON.stringify(e)}:${x(t)}`).join(",")}}` : JSON.stringify(String(e));
+}, S = (e) => e instanceof Date ? e.toISOString() : e, C = (e) => x(Object.fromEntries(b.map((t) => [t, S(e[t] ?? null)]))), w = (e) => {
+	let t = process.env.VOLTRO_AUDIT_CHAIN_SECRET;
+	return t ? _("sha256", t).update(e, "utf8").digest("hex") : g("sha256").update(e, "utf8").digest("hex");
+}, T = (e, t) => w(JSON.stringify([
+	t.chainId,
+	t.seq,
+	t.prevHash,
+	C(e)
+])), E = (e = v(12).toString("base64url")) => {
+	let t = 0, n = null;
+	return {
+		chainId: e,
+		link: (r) => {
+			t += 1;
+			let i = T(r, {
+				chainId: e,
+				seq: t,
+				prevHash: n
+			}), a = {
+				...r,
+				chainId: e,
+				seq: t,
+				prevHash: n,
+				hash: i
+			};
+			return n = i, a;
+		}
+	};
+}, D = async (e, t = {}) => {
+	let n = t.chainId === void 0 ? void 0 : o("chainId", t.chainId), r = await e.query({
+		table: y,
+		...n ? { predicate: n } : {},
+		order: [{
+			column: "chainId",
+			direction: "asc"
+		}, {
+			column: "seq",
+			direction: "asc"
+		}],
+		...t.limit === void 0 ? {} : { take: t.limit }
+	}), i = [], a = [], s = 0, c = 0, l = null, u = () => {
+		l &&= (a.push({
+			chainId: l.chainId,
+			from: l.from,
+			to: l.last,
+			tip: l.tip,
+			prunedPrefix: l.from > 1
+		}), null);
+	};
+	for (let e of r) {
+		let t = e.chainId, n = e.hash, r = e.seq;
+		if (typeof t != "string" || typeof n != "string" || r == null) {
+			s += 1;
+			continue;
+		}
+		let a = Number(r), o = typeof e.prevHash == "string" ? e.prevHash : null, d = typeof e.id == "string" ? e.id : void 0;
+		c += 1, !l || l.chainId !== t ? (u(), l = {
+			chainId: t,
+			from: a,
+			last: a,
+			tip: n
+		}) : (a === l.last + 1 ? o !== l.tip && i.push({
+			kind: "broken-link",
+			chainId: t,
+			seq: a,
+			...d ? { rowId: d } : {},
+			detail: `prevHash does not match the hash of seq ${l.last}`
+		}) : i.push({
+			kind: "gap",
+			chainId: t,
+			seq: l.last + 1,
+			detail: `chain jumps from seq ${l.last} to ${a} — ${a - l.last - 1} row(s) missing`
+		}), l.last = a, l.tip = n), T(e, {
+			chainId: t,
+			seq: a,
+			prevHash: o
+		}) !== n && i.push({
+			kind: "tampered",
+			chainId: t,
+			seq: a,
+			...d ? { rowId: d } : {},
+			detail: "the row content does not hash to its stored hash — a column was altered"
+		});
+	}
+	return u(), {
+		ok: i.length === 0,
+		rowsChecked: c,
+		unchainedRows: s,
+		chains: a,
+		issues: i,
+		keyed: !!process.env.VOLTRO_AUDIT_CHAIN_SECRET
+	};
+}, O = p(y, {
+	id: s({ prefix: "audit" }),
+	tag: m(),
+	at: h(),
+	subjectId: m().nullable(),
+	tenantId: m().nullable(),
+	traceId: m(),
+	status: m(),
+	durationMs: m(),
+	subject: l(),
+	actor: l().nullable(),
+	scope: l().nullable(),
+	metadata: l().nullable(),
+	input: l(),
+	outcome: l(),
+	errorTag: m().nullable(),
+	chainId: m().nullable(),
+	seq: c().nullable(),
+	prevHash: m().nullable(),
+	hash: m().nullable()
 }).index("byAuditTag", ["tag"]).index("byAuditTrace", ["traceId"]).index("byAuditSubjectStatus", [
 	"subjectId",
 	"status",
@@ -28,7 +145,7 @@ var m = "_voltro_audit_log", h = d(m, {
 	"tenantId",
 	"status",
 	"at"
-]), g = [h], _ = (e) => ({
+]).index("byAuditChain", ["chainId", "seq"]), k = [O], A = (e) => ({
 	tag: e.tag,
 	at: new Date(e.ts),
 	subjectId: e.subject.id ?? null,
@@ -42,40 +159,43 @@ var m = "_voltro_audit_log", h = d(m, {
 	metadata: e.metadata ?? null,
 	input: e.input,
 	outcome: e.outcome,
-	errorTag: e.outcome.kind === "error" ? v(e.outcome.error) : null
-}), v = (e) => {
+	errorTag: e.outcome.kind === "error" ? j(e.outcome.error) : null
+}), j = (e) => {
 	if (typeof e != "object" || !e) return null;
 	let t = e._tag;
 	return typeof t == "string" && t !== "" ? t : null;
-}, y = async (e, t) => e.query({
-	table: m,
-	predicate: a("traceId", t),
+}, M = async (e, t) => e.query({
+	table: y,
+	predicate: o("traceId", t),
 	order: [{
 		column: "at",
 		direction: "asc"
 	}]
-}), b = async (e, t, n = {}) => {
-	let r = a("subjectId", t);
+}), N = async (e, t, n = {}) => {
+	let r = o("subjectId", t);
 	return e.query({
-		table: m,
-		predicate: n.status === void 0 ? r : i(r, a("status", n.status)),
+		table: y,
+		predicate: n.status === void 0 ? r : a(r, o("status", n.status)),
 		order: [{
 			column: "at",
 			direction: "desc"
 		}],
 		take: n.limit ?? 100
 	});
-}, x = (e) => async (t) => {
-	let n = t.actor !== void 0 || typeof e.query != "function" ? t : {
-		...t,
-		actor: await l(e, t.subject.id ?? null, t.subject.type)
+}, P = (e) => {
+	let t = E();
+	return async (n) => {
+		let r = n.actor !== void 0 || typeof e.query != "function" ? n : {
+			...n,
+			actor: await d(e, n.subject.id ?? null, n.subject.type)
+		};
+		await e.insert(y, t.link(A(r)));
 	};
-	await e.insert(m, _(n));
-}, S = r({ scope: "@voltro/plugin-audit" }), C = 1e3, w = [], T = () => [...w], E = () => {
-	w.length = 0;
-}, D = (e) => {
-	w.push(e), w.length > C && w.splice(0, w.length - C);
-}, O = (e) => {
+}, F = i({ scope: "@voltro/plugin-audit" }), I = 1e3, L = [], R = () => [...L], z = () => {
+	L.length = 0;
+}, B = (e) => {
+	L.push(e), L.length > I && L.splice(0, L.length - I);
+}, V = (e) => {
 	let t = e.subject.id ? `${e.subject.type}:${e.subject.id}` : e.subject.type, n = e.outcome.kind === "ok" ? "ok" : "error", r = {
 		subject: t,
 		tenant: e.subject.tenantId ?? null,
@@ -83,8 +203,8 @@ var m = "_voltro_audit_log", h = d(m, {
 		durationMs: e.outcome.durationMs,
 		traceId: e.traceId
 	};
-	n === "error" ? S.warn(e.tag, r) : S.info(e.tag, r);
-}, k = (e, n) => typeof e == "function" ? (n) => t.suspend(() => {
+	n === "error" ? F.warn(e.tag, r) : F.info(e.tag, r);
+}, H = (e, n) => typeof e == "function" ? (n) => t.suspend(() => {
 	let r = e(n);
 	return r === void 0 ? t.void : t.isEffect(r) ? r : t.tryPromise({
 		try: () => Promise.resolve(r),
@@ -96,7 +216,7 @@ var m = "_voltro_audit_log", h = d(m, {
 		try: () => r(e),
 		catch: (e) => e
 	}) : t.void;
-}) : e === "memory" ? (e) => t.sync(() => D(e)) : (e) => t.sync(() => O(e)), A = (e) => {
+}) : e === "memory" ? (e) => t.sync(() => B(e)) : (e) => t.sync(() => V(e)), U = (e) => {
 	let t = [], n = [], r = (e) => {
 		if (e._tag !== "Empty") {
 			if (e._tag === "Fail") {
@@ -120,26 +240,27 @@ var m = "_voltro_audit_log", h = d(m, {
 		}
 	};
 	return r(e), t[0] ?? n[0] ?? e;
-}, j = (e = {}) => {
-	let r = e.sink === "datastore";
-	r && c({
-		table: m,
+}, W = "@voltro/plugin-audit", G = (e = {}) => {
+	let i = e.sink === "datastore";
+	i && u({
+		source: "plugin",
+		table: y,
 		timeColumn: "at",
-		ttlMs: u(process.env.VOLTRO_AUDIT_LOG_TTL_HOURS, 24 * 365)
+		ttlMs: f(process.env.VOLTRO_AUDIT_LOG_TTL_HOURS, 24 * 365)
 	});
-	let i, a = k(e.sink, () => i), o = (t) => !(e.exclude?.test(t) || e.include && !e.include.test(t)), s = (t) => {
+	let a, o = H(e.sink, () => a), s = (e) => e === void 0 || !e.global && !e.sticky ? e : new RegExp(e.source, e.flags.replace(/[gy]/g, "")), c = s(e.exclude), l = s(e.include), d = (e) => !(c?.test(e) || l && !l.test(e)), p = (t) => {
 		let n = e.record ?? "all";
 		return n === "all" ? !0 : n === "errors" ? t.outcome.kind === "error" : n(t);
-	}, l = { __redacted: "all" }, d = (t) => {
+	}, m = { __redacted: "all" }, h = (t) => {
 		let n = e.redactInput ?? "all";
 		return n === "none" ? t : {
 			...t,
-			input: n === "all" ? l : n(t)
+			input: n === "all" ? m : n(t)
 		};
-	}, f = (t) => {
+	}, g = (t) => {
 		let n = e.redactOutcome ?? "all";
 		if (n === "none") return t;
-		let r = n === "all" ? l : n(t), i = t.outcome;
+		let r = n === "all" ? m : n(t), i = t.outcome;
 		if (i.kind === "ok") return {
 			...t,
 			outcome: {
@@ -158,7 +279,7 @@ var m = "_voltro_audit_log", h = d(m, {
 				}
 			}
 		};
-	}, p = (t) => {
+	}, _ = (t) => {
 		let n = e.redactSubject ?? "metadata";
 		if (n === "none") return t;
 		if (typeof n == "function") return {
@@ -172,18 +293,18 @@ var m = "_voltro_audit_log", h = d(m, {
 			...t,
 			subject: {
 				...a,
-				metadata: l
+				metadata: m
 			}
 		};
-	}, h = (e) => s(e) ? a(f(p(d(e)))) : t.void, _ = (t) => {
+	}, v = (e) => p(e) ? o(g(_(h(e)))) : t.void, b = (t) => {
 		if (e.resolveScope !== void 0) try {
 			return e.resolveScope(t);
 		} catch {
 			return;
 		}
-	}, v = (e, n) => o(n.tag) ? t.suspend(() => {
-		let r = Date.now(), i = _(n);
-		return e.pipe(t.tap((e) => h({
+	}, x = (e, n) => d(n.tag) ? t.suspend(() => {
+		let r = Date.now(), i = b(n);
+		return e.pipe(t.tap((e) => v({
 			ts: r,
 			tag: n.tag,
 			subject: n.subject,
@@ -195,7 +316,7 @@ var m = "_voltro_audit_log", h = d(m, {
 				value: e,
 				durationMs: Date.now() - r
 			}
-		}).pipe(t.catchAllCause(() => t.void))), t.tapErrorCause((e) => h({
+		}).pipe(t.catchAllCause(() => t.void))), t.tapErrorCause((e) => v({
 			ts: r,
 			tag: n.tag,
 			subject: n.subject,
@@ -204,30 +325,34 @@ var m = "_voltro_audit_log", h = d(m, {
 			input: n.input,
 			outcome: {
 				kind: "error",
-				error: A(e),
+				error: U(e),
 				durationMs: Date.now() - r
 			}
 		}).pipe(t.catchAllCause(() => t.void))));
-	}) : e, y = v, b = v, S = v;
+	}) : e, S = x, C = x, w = x;
 	return n({
-		name: "@voltro/plugin-audit",
+		name: r({
+			base: W,
+			alias: e.alias
+		}),
+		baseName: W,
 		description: "Records every mutation invocation; ships an audit() schema mixin for row-level metadata.",
 		permissions: [
 			"rpc:intercept:mutation",
 			"rpc:intercept:action",
-			...r ? ["store:write"] : [],
+			...i ? ["store:write"] : [],
 			...e.recordQueries === !0 ? ["rpc:intercept:query"] : []
 		],
-		...r ? {
-			extendSchema: { tables: g },
+		...i ? {
+			...e.tables === !1 ? {} : { extendSchema: { tables: k } },
 			bindDataStore: (e) => {
-				i = x(e);
+				a = P(e);
 			}
 		} : {},
-		interceptMutation: y,
-		interceptAction: b,
-		...e.recordQueries === !0 ? { interceptQuery: S } : {}
+		interceptMutation: S,
+		interceptAction: C,
+		...e.recordQueries === !0 ? { interceptQuery: w } : {}
 	});
 };
 //#endregion
-export { m as AUDIT_LOG_TABLE, e as audit, b as auditBySubject, y as auditByTrace, _ as auditEventToRow, h as auditLogTable, g as auditLogTables, j as auditPlugin, E as clearAuditBuffer, x as dataStoreAuditSink, T as readAuditBuffer };
+export { y as AUDIT_LOG_TABLE, e as audit, N as auditBySubject, M as auditByTrace, A as auditEventToRow, O as auditLogTable, k as auditLogTables, G as auditPlugin, T as auditRowHash, z as clearAuditBuffer, P as dataStoreAuditSink, E as makeAuditChain, R as readAuditBuffer, D as verifyAuditChain };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/plugin-audit",
-  "version": "0.33.0",
+  "version": "0.34.0",
   "description": "Audit plugin — ships the `audit()` schema mixin (createdAt/updatedAt/createdBy/updatedBy → Actor) plus an optional mutation interceptor that records every call to a configurable sink (console / memory / custom function).",
   "keywords": [
     "voltro",
@@ -38,9 +38,9 @@
     "node": ">=24.0.0"
   },
   "dependencies": {
-    "@voltro/database": "0.33.0",
-    "@voltro/logger": "0.33.0",
-    "@voltro/protocol": "0.33.0"
+    "@voltro/database": "0.34.0",
+    "@voltro/logger": "0.34.0",
+    "@voltro/protocol": "0.34.0"
   },
   "peerDependencies": {
     "effect": "^3.22.0"