Audit log

What gets logged

Every side-effect the brain performs:

• Auth - login, logout, password change, failed login, invitation accepted, password reset requested/completed.
• Users / memberships - invite, accept, role change, remove.
• Agents - token mint, token revoke, agent deleted.
• Actions - task retry, cancel, bulk retry, queue purge.
• Schedules - create, update, pause, resume, delete.
• Project - create, settings change, delete.

Events flowing through the queue are not in the audit log - those are in events. Audit is “who pressed what button,” not “what did the workers do.”

Chain structure

Each row contains:

id, ts, actor_user_id, project_id, action, target_type, target_id, details (jsonb),
row_hmac, prev_row_hmac

row_hmac = HMAC-SHA256(Z4J_AUDIT_SECRET, canonical(row_fields || prev_row_hmac))

• canonical(...) is a deterministic JSON serialization (sorted keys, no whitespace).
• prev_row_hmac refers to the immediately previous row in id order.
• Genesis row has prev_row_hmac = null.

Deleting or rewriting a row breaks the chain at that point; every subsequent row’s HMAC will fail to verify.

Verification

The brain exposes an internal verify_chain() that walks the full log and returns (ok, first_broken_row_id). It runs:

• On-demand from CLI: z4j-brain audit verify.
• As part of the pre-release security audit suite.
• Optionally on a schedule (set Z4J_AUDIT_VERIFY_INTERVAL=3600 to run hourly).

If verification fails, an alert-level log line is emitted and the /api/v1/health endpoint includes audit_chain_ok=false.

Retention

Unlimited. The audit log is never automatically deleted. Operators can export + truncate with z4j-brain audit export --older-than 1y but this is a deliberate action that writes a final audit entry.

Export

CSV export via /api/v1/audit/export?format=csv&from=...&to=.... Includes all fields; row_hmac and prev_row_hmac are included so external systems can verify the chain.

What it does not give you

• Not a SIEM - use it as a source for a SIEM (export + ship to Datadog / Splunk / Loki).
• Not a compliance certificate - tamper-evidence is a primitive; SOC 2 auditors want policies and training, not just tech.
• Not a replacement for Postgres audit triggers - the brain’s own writes are what we sign. Direct SQL access bypasses this.

See security § HMAC audit chain for the threat model.