build-audit-logs

Build or Review an Audit System with evlog

For application developers who either need to add an audit trail to their product, or who already have one and want it reviewed. Walks through the design calls, the end-to-end implementation, and a review checklist for an existing setup.

This skill assumes the audit lives in your app. To extend the evlog package itself (new audit helper, new drain wrapper), see the contributor skills under .agents/skills/.

Quick reference: call-site cheat sheet

When you already know the system is wired and just need to remember the API:

Situation	Helper
Inside a request handler, action succeeded	log.audit({ action, actor, target, outcome: 'success' })
Inside a request handler, AuthZ denial	log.audit.deny('reason', { action, actor, target })
Standalone job / script / CLI (no request)	audit({ action, actor, target, outcome })
Auto-record success / failure / denied for a function	withAudit({ action, target }, fn)
Recording a state change	add changes: auditDiff(before, after)
Centralised typed action vocabulary	defineAuditCatalog('billing', { INVOICE_REFUND: { target: 'invoice' } }) — or defineAuditAction('invoice.refund', { target: 'invoice' }) for one-offs
Asserting audits in tests	mockAudit() — assertAudit() or toIncludeAuditOf()

AuditFields schema (always provide action, actor, outcome; target strongly recommended; the rest is filled in for you):

interface AuditFields {
  action: string                                  // 'invoice.refund'
  actor: { type: 'user' | 'system' | 'api' | 'agent', id: string, email?, displayName?, model?, tools?, reason?, promptId? }
  outcome: 'success' | 'failure' | 'denied'
  target?: { type: string, id: string, [k: string]: unknown }
  reason?: string
  changes?: { before?: unknown, after?: unknown, patch?: AuditPatchOp[] }
  causationId?: string
  correlationId?: string
  version?: number                                // defaults to AUDIT_SCHEMA_VERSION
  idempotencyKey?: string                         // auto-derived from action+actor+target+timestamp
  context?: { requestId?, traceId?, ip?, userAgent?, tenantId?, ... }   // filled by auditEnricher
  signature?: string                              // added by signed(drain, { strategy: 'hmac' })
  prevHash?: string                               // added by signed(drain, { strategy: 'hash-chain' })
  hash?: string                                   // added by signed(drain, { strategy: 'hash-chain' })
}