Audit Trail

HMAC-SHA256 hash-chained audit trail for tamper-evident AI agent logging. EU AI Act Article 12 compliant.

HMAC-SHA256 hash-chained audit logging. Every event's hash includes the previous event's hash, creating an immutable chain where any tampering is immediately detectable. Satisfies EU AI Act Article 12 record-keeping requirements.

Setup

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

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

// Wrap governance with tamper-evident hash chaining
const audit = createIntegrityAudit(gov, {
  signingKey: process.env.AUDIT_SIGNING_KEY!,  // Keep this secret
  algorithm: 'hmac-sha256',                     // Default
});

Warning: The signing key is used to compute HMAC hashes. If it is compromised, an attacker could forge valid hashes. Store it as an environment variable and rotate it periodically.

Automatic Audit Logging

Every gov.enforce() call automatically writes an audit event. You don't need to log enforcement decisions manually.

// 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

Verify the entire audit chain at any time. The verifier recomputes every hash from scratch and checks chain continuity. If any event has been modified, inserted, deleted, or reordered, it reports the exact location.

// Verify the entire chain — detects any tampering
const verification = await audit.verify();

// 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 has been modified",
//   verifiedAt: "2026-03-10T15:00:00Z"
// }

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 audit.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 audit.export({
  agentId: 'sales-agent',
  since: '2026-03-01T00:00:00Z',
  until: '2026-03-10T23:59:59Z',
});

// Get chain statistics
const stats = await audit.stats();
// {
//   totalEvents: 142,
//   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.