Audit Chain

HMAC-SHA256 tamper-evident, append-only audit chain. Verify integrity, export logs, inspect stats.

Tamper-evident, append-only audit log. Every governance decision is HMAC-SHA256 linked to the previous entry, forming a verifiable chain. Import from governance-sdk/audit-integrity.

Functions

Function	Signature	Description
`createIntegrityAudit`	`createIntegrityAudit(governance, { signingKey, algorithm? }) => IntegrityAudit`	Create an integrity audit instance. Requires a signing key for HMAC-SHA256.
`chain.log`	`chain.log(event) => void`	Append an entry to the chain with HMAC signature.
`chain.verify`	`chain.verify() => { valid: boolean; brokenAt?: number }`	Walk the full chain, checking every HMAC link.
`chain.export`	`chain.export() => AuditEntry[]`	Return the full chain as a serializable array.
`chain.stats`	`chain.stats() => AuditStats`	Return summary statistics: chain length, timestamps, chain tip hash.

Setup

import { createGovernance } from 'governance-sdk';
import { createIntegrityAudit } from 'governance-sdk/audit-integrity';

const gov = createGovernance({ rules: [...] });

const chain = createIntegrityAudit(gov, { signingKey: process.env.AUDIT_SECRET! });

Note: The audit chain is built automatically. Every call to enforce() appends an entry. No manual instrumentation needed.

Verify Integrity

const chain = createIntegrityAudit(gov, { signingKey: process.env.AUDIT_SECRET! });

const result = chain.verify();

// result:
// {
//   valid: true,        // false if any entry was tampered with
//   brokenAt?: number,  // index of first broken link (only if valid=false)
// }

if (!result.valid) {
  throw new Error(`Audit chain tampered at entry ${result.brokenAt}`);
}

Export

const entries = chain.export();

// Each entry:
// {
//   index: 0,
//   timestamp: '2026-03-10T08:12:00.000Z',
//   agentId: 'research-agent',
//   action: 'tool_call',
//   tool: 'web.search',
//   decision: 'allowed',
//   reason: null,
//   hash: 'a1b2c3d4...',
//   previousHash: '00000000...',
// }

await writeAuditLog(entries);

Stats

const stats = chain.stats();

// stats:
// {
//   length: 1247,
//   firstTimestamp: '2026-03-10T00:00:00Z',
//   lastTimestamp: '2026-03-10T08:12:00Z',
//   lastHash: 'f9e8d7c6...',
// }