@voltro/plugin-audit 0.85.0 → 0.87.0

package/dist/chain.js

@@ -0,0 +1,205 @@
+import { AUDIT_LOG_TABLE as e } from "./tableName.js";
+import { auditInvocationIdOf as t, hasConsistentAuditInvocationId as n } from "./invocationIdentity.js";
+import { and as r, column as i, eq as a, generateId as o, gt as s, isNotNull as c, isNull as l, lte as u, or as d } from "@voltro/database";
+import { createHash as f, createHmac as p, randomBytes as m } from "node:crypto";
+//#region src/chain.ts
+var h = [
+	"tag",
+	"at",
+	"subjectId",
+	"tenantId",
+	"traceId",
+	"status",
+	"durationMs",
+	"subject",
+	"actor",
+	"scope",
+	"metadata",
+	"input",
+	"outcome",
+	"errorTag"
+], g = [
+	...h,
+	"hashVersion",
+	"id",
+	"impersonation",
+	"scopeKey"
+], _ = (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(_).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)}:${_(t)}`).join(",")}}` : JSON.stringify(String(e));
+}, v = (e) => e instanceof Date ? e.toISOString() : e, y = (e, t) => _(Object.fromEntries((t === 2 ? g : h).map((t) => [t, v(e[t] ?? null)]))), b = (e) => {
+	let t = process.env.VOLTRO_AUDIT_CHAIN_SECRET;
+	return t ? p("sha256", t).update(e, "utf8").digest("hex") : f("sha256").update(e, "utf8").digest("hex");
+}, x = (e, t) => {
+	let n = e.hashVersion ?? 1;
+	if (n !== 1 && n !== 2) throw TypeError("Unsupported audit hash version");
+	return b(JSON.stringify([
+		t.chainId,
+		t.seq,
+		t.prevHash,
+		y(e, n)
+	]));
+}, S = (e = m(12).toString("base64url")) => {
+	let n = 0, r = null;
+	return {
+		chainId: e,
+		link: (i) => {
+			n += 1;
+			let a = {
+				...i,
+				invocationId: t(i.outcome),
+				id: i.id ?? o({
+					kind: "typeid",
+					prefix: "audit"
+				}, "_voltro_audit_log"),
+				hashVersion: 2
+			}, s = x(a, {
+				chainId: e,
+				seq: n,
+				prevHash: r
+			}), c = {
+				...a,
+				chainId: e,
+				seq: n,
+				prevHash: r,
+				hash: s
+			};
+			return r = s, c;
+		}
+	};
+};
+async function* C(t, n) {
+	let o = n.chainId === void 0 ? void 0 : a("chainId", n.chainId), f = (t, n, r) => ({
+		table: e,
+		predicate: t,
+		order: r,
+		take: n,
+		skip: void 0,
+		projection: void 0
+	});
+	if (n.limit !== void 0) {
+		yield* await t.query(f(o, n.limit, [{
+			column: "chainId",
+			direction: "asc"
+		}, {
+			column: "seq",
+			direction: "asc"
+		}]));
+		return;
+	}
+	let p = [...await t.query({
+		...f(o, void 0, [{
+			column: "chainId",
+			direction: "asc"
+		}]),
+		groupBy: ["chainId"],
+		aggregations: [
+			i("chainId"),
+			{
+				op: "max",
+				column: "seq",
+				alias: "lastSeq"
+			},
+			{
+				op: "max",
+				column: "id",
+				alias: "lastId"
+			}
+		]
+	})].sort((e, t) => String(e.chainId) < String(t.chainId) ? -1 : +(String(e.chainId) > String(t.chainId)));
+	for (let e of p) {
+		let n = e.chainId, i = n == null ? l("chainId") : a("chainId", n), o = n == null ? [!1] : [!1, !0];
+		for (let p of o) {
+			if (p && e.lastSeq == null) continue;
+			let o = [i, u("id", e.lastId)];
+			n != null && o.push(p ? r(c("seq"), u("seq", e.lastSeq)) : l("seq"));
+			let m;
+			for (;;) {
+				let e = m === void 0 ? void 0 : p ? d(s("seq", m.seq), r(a("seq", m.seq), s("id", m.id))) : s("id", m.id), n = await t.query(f(r(...o, ...e ? [e] : []), 1e3, [...p ? [{
+					column: "seq",
+					direction: "asc"
+				}] : [], {
+					column: "id",
+					direction: "asc"
+				}]));
+				if (yield* n, n.length < 1e3) break;
+				let i = n[n.length - 1];
+				if (i.id === void 0 || i.id === m?.id) throw Error("audit verification cursor did not advance");
+				m = i;
+			}
+		}
+	}
+}
+var w = async (e, t = {}) => {
+	let r = [], i = [], a = 0, o = 0, s = 0, c = null, l = () => {
+		c &&= (i.push({
+			chainId: c.chainId,
+			from: c.from,
+			to: c.last,
+			tip: c.tip,
+			prunedPrefix: c.from > 1
+		}), null);
+	};
+	for await (let i of C(e, t)) {
+		let e = i.chainId, t = i.hash, u = i.seq;
+		if (typeof e != "string" || typeof t != "string" || u == null) {
+			a += 1;
+			continue;
+		}
+		let d = Number(u), f = typeof i.prevHash == "string" ? i.prevHash : null, p = typeof i.id == "string" ? i.id : void 0;
+		s += 1, !c || c.chainId !== e ? (l(), c = {
+			chainId: e,
+			from: d,
+			last: d,
+			tip: t
+		}) : (d === c.last + 1 ? f !== c.tip && r.push({
+			kind: "broken-link",
+			chainId: e,
+			seq: d,
+			...p ? { rowId: p } : {},
+			detail: `prevHash does not match the hash of seq ${c.last}`
+		}) : r.push({
+			kind: "gap",
+			chainId: e,
+			seq: c.last + 1,
+			detail: `chain jumps from seq ${c.last} to ${d} — ${d - c.last - 1} row(s) missing`
+		}), c.last = d, c.tip = t);
+		let m = i.hashVersion ?? 1;
+		m !== 1 && m !== 2 ? r.push({
+			kind: "tampered",
+			chainId: e,
+			seq: d,
+			...p ? { rowId: p } : {},
+			detail: "unsupported audit hash version; the row cannot be verified"
+		}) : (m === 1 && (o += 1), n(i) ? x(i, {
+			chainId: e,
+			seq: d,
+			prevHash: f
+		}) !== t && r.push({
+			kind: "tampered",
+			chainId: e,
+			seq: d,
+			...p ? { rowId: p } : {},
+			detail: "the row content does not hash to its stored hash — a column was altered"
+		}) : r.push({
+			kind: "tampered",
+			chainId: e,
+			seq: d,
+			...p ? { rowId: p } : {},
+			detail: "the invocation lookup does not match its protected outcome"
+		}));
+	}
+	return l(), {
+		ok: r.length === 0,
+		rowsChecked: s,
+		unchainedRows: a,
+		legacyHashRows: o,
+		chains: i,
+		issues: r,
+		keyed: !!process.env.VOLTRO_AUDIT_CHAIN_SECRET
+	};
+};
+//#endregion
+export { x as auditRowHash, S as makeAuditChain, w as verifyAuditChain };

package/dist/index.d.ts

@@ -2,9 +2,11 @@ import { AuditActor } from '@voltro/database';
 import { ColumnDefinition } from '@voltro/database';
 import { Effect } from 'effect';
 import { MixinDefinition } from '@voltro/database';
+import { Query } from '@voltro/database';
+import { Row } from '@voltro/database';
+import { SchemaTable } from '@voltro/database';
 import { Subject } from '@voltro/protocol';
 import { TableIndex } from '@voltro/database';
-import { TableLike } from '@voltro/database';
 import { VoltroPlugin } from '@voltro/protocol';
 
 export declare const audit: () => MixinDefinition<{
@@ -72,6 +74,8 @@ export declare type AuditChainIssueKind = 'tampered' | 'broken-link' | 'gap';
 
 /** The columns the chain adds to `_voltro_audit_log`. */
 export declare interface AuditChainLink {
+    /** NULL/1 is historical coverage; new writers use format 2. */
+    readonly hashVersion?: number | null;
     /** Which writer's chain this row belongs to. Null for an unchained row. */
     readonly chainId: string;
     /** 1-based position within `chainId`. */
@@ -102,6 +106,9 @@ export declare interface AuditChainVerification {
      *  Not an `issue` (a pre-chain deployment is not tampering) but never
      *  silently dropped either. */
     readonly unchainedRows: number;
+    /** Rows using the historical digest, which did not cover impersonation or
+     * the derived scope key. Optional for compatibility with older result DTOs. */
+    readonly legacyHashRows?: number;
     readonly chains: ReadonlyArray<AuditChainSummary>;
     readonly issues: ReadonlyArray<AuditChainIssue>;
     /** Whether the digest was keyed. An `ok: true` from an UNKEYED run is a
@@ -125,7 +132,7 @@ export declare interface AuditEvent {
      * (anonymous, system). Absent is honest; a fabricated placeholder would be
      * the thing this field exists to prevent.
      */
-    readonly actor?: AuditActor | undefined;
+    readonly actor?: AuditActor | null | undefined;
     /** The app's own scoping dimension — opaque, stored verbatim, filterable.
      *  `.with(tenant())` is one level too coarse for a per-team trail. */
     readonly scope?: unknown;
@@ -158,22 +165,38 @@ export declare interface AuditEvent {
         readonly kind: 'ok';
         readonly value: unknown;
         readonly durationMs: number;
+        readonly invocationId?: string;
     } | {
         readonly kind: 'error';
         readonly error: unknown;
         readonly durationMs: number;
+        readonly invocationId?: string;
+    } | {
+        readonly kind: 'unknown';
+        readonly invocationId: string;
+        readonly durationMs: number;
     };
 }
 
 /** Map an {@link AuditEvent} to an audit-log row. */
 export declare const auditEventToRow: (event: AuditEvent) => Record<string, unknown>;
 
+/** Stable display identity when an unknown admission acquires a terminal row.
+ * A pagination cursor still uses the selected raw row's actual ordering key. */
+export declare const auditInvocationIdentity: (row: Readonly<Record<string, unknown>>) => string;
+
+/** One logical invocation per result, before filtering/order/pagination. Raw
+ * admissions remain immutable. Qualify caller predicates/order with audit. */
+export declare const auditInvocationQuery: () => Query<Row, string, {
+    completed: Row;
+}>;
+
 /**
  * The slice of a built `Table` this package exposes — annotated explicitly so
  * @voltro/database's private column-builder class doesn't leak across the
  * package boundary (TS4094). Only name + columns + indexes are needed.
  */
-export declare interface AuditLogTable extends TableLike {
+export declare interface AuditLogTable extends SchemaTable {
     readonly fields: Record<string, ColumnDefinition<unknown>>;
     readonly appliedIndexes: ReadonlyArray<TableIndex>;
 }
@@ -200,6 +223,32 @@ export declare const auditLogTables: ReadonlyArray<AuditLogTable>;
 export declare const auditPlugin: (options?: AuditPluginOptions) => VoltroPlugin;
 
 export declare interface AuditPluginOptions {
+    /** Successful registered mutations may capture a required redacted intent on
+     * the current transaction outbox. Requires the literal datastore sink and the
+     * supported Runtime/CLI hook. Default best-effort recording is unchanged.
+     * Required scope/metadata/redaction/encoding failures roll back the mutation.
+     * Callbacks must remain free of external side effects: replay may repeat them.
+     * Refusals, actions, workflows and HTTP remain best effort in this mode. */
+    readonly mutationCapture?: 'best-effort' | 'transactional-outbox';
+    /** Registered mutation/action/workflow failures enqueue a redacted outcome
+     * after the business transaction has rolled back. Requires datastore sink
+     * and the current host's root outcome capability. Capture failures preserve
+     * the original operation error and report only bounded diagnostics. Query,
+     * HTTP and successful non-mutation capture are unchanged. */
+    readonly failureCapture?: 'best-effort' | 'outbox';
+    /** Successful registered actions and workflow-start calls enqueue a frozen
+     * redacted outcome through the host's root outbox. Requires datastore sink.
+     * This is durable delivery after completion, not a transaction around external
+     * side effects: admission failures preserve the successful business result and
+     * emit a bounded diagnostic. Queries, HTTP and mutation capture are unchanged. */
+    readonly successCapture?: 'best-effort' | 'outbox';
+    /** Required admission for selected action/workflow-start calls. Persist an
+     * immutable privacy-safe unknown outcome before executing their effect, then
+     * correlate the terminal outcome by invocationId. Requires datastore sink,
+     * success/failure outbox capture and record: all. Admission failure prevents
+     * execution; interruption leaves unknown evidence without claiming rollback.
+     * Mutations, queries and HTTP are unchanged. */
+    readonly invocationCapture?: 'best-effort' | 'required';
     /**
      * Namespace for this plugin's inspect surface + any rpc tags it contributes. Default `audit`.
      *
@@ -306,7 +355,7 @@ export declare interface AuditPluginOptions {
      * between an indexed read path and stuffing `teamId` into `metadata` and
      * scanning — a column documented as a free-form note is not a read path.
      *
-     * Throwing here never fails the mutation being recorded: a scope that cannot
+     * In default best-effort mode, throwing never fails the mutation: a scope that cannot
      * be derived is null, the same answer as not configuring one.
      */
     readonly resolveScope?: (ctx: {
@@ -323,10 +372,10 @@ export declare interface AuditPluginOptions {
      *
      * Resolved AFTER the call, so it sees the result (`outcome.kind === 'ok'`
      * with `value`, or `'error'` with the error) — the note for a failed removal
-     * is a different note. May be async. Throwing, rejecting, or returning
-     * `undefined` records no note; it never fails the call being recorded, and
-     * never delays it: the note is resolved on the same fire-and-forget path
-     * the sink write takes.
+     * is a different note. May be async. In default best-effort mode, throwing, rejecting, or returning
+     * `undefined` records no note. Resolution is awaited on the interceptor's
+     * recording path, but failure does not replace the call's original outcome.
+     * Transactional capture requires successful callback resolution.
      *
      * ```ts
      * auditPlugin({
@@ -470,6 +519,13 @@ export declare interface AuditPluginOptions {
      * "who really did this" is not app-controlled metadata, it is the event.
      */
     readonly redactSubject?: 'metadata' | 'metadata-shape' | 'none' | ((subject: Subject) => unknown);
+    /** Project resolved actor displayName/email before capture or sink delivery.
+     * The framework retains id/type even if JavaScript returns extra fields.
+     * Return both labels as strings or null. The synchronous callback must be
+     * pure: required capture failure aborts its transaction; refusal admission
+     * keeps the original error. Decisions are frozen before enqueue, not rerun
+     * during delivery. Absent preserves the existing policy; no actor stays null. */
+    readonly redactActor?: (actor: Readonly<AuditActor>) => Pick<AuditActor, 'displayName' | 'email'>;
     /**
      * What happens to `AuditEvent.outcome`'s payload before it is handed to the
      * sink.
@@ -555,12 +611,17 @@ export declare type AuditSink = (event: AuditEvent) => void | Promise<void> | Ef
 export declare const clearAuditBuffer: () => void;
 
 /**
- * A DataStore-backed audit sink — appends each event to `_voltro_audit_log`.
- * Returns a `(event) => Promise<void>` so it plugs straight into the plugin's
- * function-sink path (which lifts it into an Effect + swallows failures, so a
- * write hiccup never masks the mutation).
+ * A DataStore-backed sink. Optional receiptId identifies one logical append
+ * across delivery retries and sink/process reconstruction. Stable receipts
+ * require a query-capable store and are refused if their content differs.
+ *
+ * A per-writer semaphore serializes append attempts. Read-capable stores derive
+ * the next link from persisted state, so rejected inserts and lost write
+ * acknowledgements cannot advance or fork the writer's chain. Insert-only
+ * substitutes retain the old surface, with in-memory state advanced on success.
+ * This is append recovery, not durable event capture before business commit.
  */
-export declare const dataStoreAuditSink: (store: AuditDataStore) => (event: AuditEvent) => Promise<void>;
+export declare const dataStoreAuditSink: (store: AuditDataStore) => (event: AuditEvent, receiptId?: string) => Promise<void>;
 
 /** Mint a fresh chain. `chainId` is 96 bits of CSPRNG — collisions across
  *  replicas would merge two chains into one apparent fork. */