How the hash-chain audit works

Audit must support accountability. Queryable logs alone are not enough: the process that writes logs can usually rewrite them. Agent Forge chains records per tenant with a hash chain and exposes recomputation verify; breakpoints resolve to a specific record.

Chain structure

Each record includes:

prev_hash: digest of the previous record; genesis is 64 0 characters
hash: sha256(prev_hash + "\n" + canon(body))

canon sorts body keys and drops undefined so the computed form matches the form after write-then-read, reducing false positives. Writes append to the chain in time order; verify recomputes in order and stops on the first failure.

flowchart LR
  G[Genesis prev_hash] --> R1[Record 1 hash]
  R1 --> R2[Record 2]
  R2 --> R3[Record 3]
  V[verify] --> R1
  V --> R2
  V --> R3

Verify API

GET /audit/verify (enterprise governance · trust capability) response examples:

{ "ok": true, "checked": 50, "broken_at": null }

{ "ok": false, "checked": 12, "broken_at": "aud_…" }

checked is the number of recomputed records; a non-null broken_at points at the breakpoint. Open-source can query the audit stream; full verify and rehash repair are gated by license. POST /audit/rehash is admin-only — for fixing serialization false positives, not for covering real tampering.

Coverage semantics

Paths with external side effects should land on the chain (permission/approval decisions, breaker, retention deletes, session deletes, collaboration escalation, and so on). Read-only operations do not require approval. checked counts chain records that can be recomputed; it is not the same as every business-side mutating count — keep the two numbers separate.

Capability boundary: the chain constrains rewrite of history after a write completes. If the write path itself is compromised, false content can still be written and then hashed to match. When the write path is trusted, later rewrite of old records is caught by verify.

Fuller metrics narrative: Reliability · metrics. Product claim: verifiable audit.

Related reading: