Audit Trail

Opt-in HMAC-SHA256 hash-chained audit trail for tamper-evident AI agent logging. Maps to EU AI Act Article 12 record-keeping.

gov.enforce() always writes audit events to your storage adapter. Hash-chaining is opt-in — when enabled, every event's hash includes the previous event's hash, creating a chain where any tampering is immediately detectable. The chain maps to EU AI Act Article 12 record-keeping.

Setup

The simplest way to enable tamper-evident audit is the integrityAudit config option on createGovernance — every event the SDK writes (registrations, enforcement decisions, audit.log() calls, kill-switch events) is intercepted and appended to the signed chain.

import { createGovernance } from 'governance-sdk';

const gov = createGovernance({
  rules: [...],
  integrityAudit: {
    signingKey: process.env.AUDIT_SIGNING_KEY!,  // Keep this secret
    onFailure: 'allow',                           // or 'block' for no-gap guarantee
  },
});

If you need finer control (e.g. only chaining a subset of events), use the lower-level createIntegrityAudit() wrapper from governance-sdk/audit-integrity.

Warning: The signing key is used to compute HMAC hashes. If it leaks, history is rewritable by the attacker. Store it as an environment variable, rotate it regularly, and pair with an external anchor (object-storage immutability, blockchain anchoring) for defence in depth.

Honesty note: Only events routed through this governance instance get chained. Host-level logging your application does independently (pino, winston, etc.) is not covered.

What gets chained (with `integrityAudit`)

When integrityAudit is set, every audit write the SDK makes is HMAC-chained — no separate wrapper, no ceremony.

Event type	Written by	Captures
`agent_registered`	`gov.register()`	name, framework, owner, initial score
`policy_evaluation`	`gov.enforce()`	agent, action, tool, rule matched, outcome, reason
`policy_evaluation_preprocess` / `_postprocess`	`gov.enforcePreprocess()` / `Postprocess()`	stage-scoped enforcement result
`action_outcome`	`gov.recordOutcome()` or `runWithOutcome()`	success / failure, duration, tokens, output summary, error
`agent_killed`	`killSwitch.kill()`	agent, reason, killedBy
(caller-supplied)	`gov.audit.log()`	any `eventType` you pass — custom LLM calls, approvals, etc.

What is NOT chained: anything you log directly via storage.createAuditEvent() (bypasses the chain), anything your host app does outside governance (raw fetch(), filesystem I/O outside governed tools), and anything the agent did between enforce() calls without invoking enforce() or recordOutcome() itself.

Recording post-execution outcomes

gov.enforce() records the decision ("is the agent allowed to call search?"). To also record what happened AFTER the action ran, use recordOutcome() or its one-line wrapper runWithOutcome(). When integrityAudit is on, the outcome event joins the chain alongside every other SDK write.

import { runWithOutcome } from 'governance-sdk';

const result = await runWithOutcome(
  gov,
  { agentId: 'sales-bot', tool: 'search' },
  async () => await searchApi.query(q),
);
// Success → action_outcome event (duration, output summary) auto-recorded.
// Failure → action_outcome event (error message) auto-recorded, then error re-thrown.

Or call recordOutcome() directly when you need finer control (token counts, custom detail):

await gov.recordOutcome({
  agentId: 'sales-bot',
  tool: 'search',
  success: true,
  durationMs: 142,
  tokensUsed: 485,
  output: { hits: 3 }, // redact sensitive fields before passing
  policyRuleId: decision.ruleId,
});

Tip: Pass a summarize function to runWithOutcome({ summarize }) to redact output before it hits the audit log.

Audit Logging

Every gov.enforce() call automatically writes an audit event to your storage adapter. You don't need to log enforcement decisions manually. When integrityAudit is configured, those events are also hash-chained.

// You don't need to call audit.log() manually for enforcement.
// Every gov.enforce() call automatically writes to the audit trail.
const decision = await gov.enforce({
  agentId: 'sales-agent',
  action: 'tool_call',
  tool: 'payment_send',
});

// Audit event written automatically:
// {
//   agentId: "sales-agent",
//   eventType: "enforcement",
//   outcome: "blocked",        // or "allowed"
//   severity: "warning",
//   policyRuleId: "block-dangerous-tools",
//   detail: { tool: "payment_send", action: "tool_call" }
// }

Custom Events

Log additional events for business logic, tool execution results, or any other auditable action.

// Log a custom event — returns the event with integrity metadata
const event = await audit.log({
  agentId: 'sales-agent',
  eventType: 'tool_call',
  outcome: 'allowed',
  severity: 'info',
  detail: {
    tool: 'crm_update',
    params: { contactId: 'c_123', field: 'status', value: 'qualified' },
  },
});

// event.integrity:
// {
//   hash: "a3f8c1d2e4b5...",       // HMAC-SHA256 of this event
//   previousHash: "7b9e0f1a2c3d...", // Hash of the previous event
//   sequence: 42,                    // Position in the chain
//   signedAt: "2026-03-10T14:30:00Z"
// }

Note: Events are serialized deterministically (all keys recursively sorted) before hashing. This ensures the same event always produces the same hash regardless of property insertion order.

Chain Verification

Export the chain from the governance instance, then re-verify it anywhere — even on a separate auditor machine — using the standalone verifyAuditIntegrity function.

import { verifyAuditIntegrity } from 'governance-sdk/audit-integrity-verify';

// From the process that wrote the chain:
const chain = await gov.integrityChain!.export();

// Anywhere else, with the shared secret:
const verification = await verifyAuditIntegrity(chain, process.env.AUDIT_SIGNING_KEY!);

// If valid:
// {
//   valid: true,
//   eventsVerified: 142,
//   totalEvents: 142,
//   brokenAt: null,
//   breakDetail: null,
//   verifiedAt: "2026-03-10T15:00:00Z"
// }

// If tampered:
// {
//   valid: false,
//   eventsVerified: 87,
//   totalEvents: 142,
//   brokenAt: 87,
//   breakDetail: "Hash mismatch at sequence 88: event evt_abc123 content has been modified",
//   verifiedAt: "2026-03-10T15:00:00Z"
// }

Note: gov.integrityChain is only populated when integrityAudit is configured on createGovernance. For the lower-level createIntegrityAudit() wrapper (which has an in-instance .verify() method), see governance-sdk/audit-integrity.

Tamper Detection

Attack	How It's Detected
Event modification	Hash mismatch — recomputed hash differs from stored hash
Event insertion	Missing integrity record for the inserted event
Event deletion	Chain break — previousHash of event N+1 doesn't match hash of event N
Event reordering	Chain continuity break at the reordered position

Export & Statistics

Export the full chain for compliance review, external auditors, or archival. Filter by agent, time range, or event type.

// Export the chain for external auditors or compliance review
const chain = await gov.integrityChain!.export();

// Each event includes full integrity metadata
// chain[0].integrity.hash           → "a1b2c3d4..."
// chain[0].integrity.previousHash   → "0000000000..." (genesis)
// chain[0].integrity.sequence       → 1

// Filter by agent or time range
const agentChain = await gov.integrityChain!.export({
  agentId: 'sales-agent',
  since: '2026-03-01T00:00:00Z',
  until: '2026-03-10T23:59:59Z',
});

// Get chain statistics
const stats = gov.integrityChain!.stats();
// {
//   latestSequence: 142,
//   latestHash: "f8e7d6c5b4a3...",
//   algorithm: "hmac-sha256"
// }

Known Limitations

Warning: In-memory chain: The hash chain state is held in process memory. It does not survive process restarts without re-hydrating from persistent storage. Use the PostgreSQL storage adapter for durable audit.

Warning: Concurrent writes: The chain uses an internal serialization queue to prevent hash forks from concurrent log() calls. This means writes are serialized within a single process.