Audit log

Hash-chained, append-only record of every admin action on the Vault API. Verifiable in your browser with no API call required.

🟡 In progress · public write-through expected v0.2

What the log records

Every admin-side action on Vault that could materially affect a customer's ability to use the service, or that touches an issued API key, gets appended to the log with a cryptographic chain. Entries include:

app_register — a new customer app is provisioned (direct-register or via application approval)
app_rotate — a customer's keypair + API key is rotated (self-serve or admin-initiated)
app_revoke — a customer's app is deactivated
application_submit — a B2B apply-for-key form submission lands in the queue
application_approve — a pending application is approved, a new Vault App is issued
application_reject — a pending application is rejected, with reason
admin_token_use — any call to an /admin/* endpoint (records actor + action, never payload)

Hash-chain format

Each entry includes the SHA-256 of the previous entry concatenated with its own content. Flipping any byte of any past entry breaks every entry after it. A daily Ed25519 signature over the current head hash is the canonical proof of state — embedded in our warrant canary.

entry_n = {
  "seq":        n,
  "ts":         "2026-04-17T10:22:15Z",
  "actor":      "admin:sajid" | "customer:app_abc" | "public",
  "action":     "application_approve",
  "target":     "apl_abc123",            // or app_ / other resource id
  "detail":     { "app_id": "app_xyz", "plan": "pro" },  // never plaintext
  "prev_hash":  "sha256(entry_n-1)",
  "self_hash":  "sha256(this entry without self_hash field)"
}

head_signature = Ed25519(root_key, self_hash_of_most_recent_entry)

The root Ed25519 key fingerprint is pinned in products/zoza-vault/OPS.md and echoed into the warrant canary — three separate sources. An attacker who silently replaces the key on one surface can't replace it everywhere at once without tripping a canary.

How to verify (when v0.2 ships)

Call GET /v1/audit/head for the current head hash and signature. Then call GET /v1/audit/entries?from=0 (paginated) to pull the full chain. Our in-browser verifier at this page will:

Fetch every entry in the chain.
Recompute each entry's self_hash from its content.
Confirm each entry's prev_hash matches the previous entry's self_hash.
Verify the head signature against the pinned Ed25519 public key.
Show green if all four hold. One byte different anywhere — red.

All of this runs in your browser. No API call returns "yes this is valid" — only the raw entries. You do the checking. That's the whole point.

⚠ Current status (v0.1)

As of 2026-04-17, Vault logs admin actions to stderr and to the activity_logs table of the admin DB. The public write-through to an append-only hash-chained log, with Ed25519 head signatures and an in-browser verifier, is implemented for Shield and planned for Vault v0.2. Until then, the log is not tamper-evident — the code path exists and logs to a local file, but the public API and the chain-verification UI ship with v0.2.

What the log does not record

Plaintext field values. The server never sees plaintext; nothing to log.
Ciphertext content. Recording ciphertext in the audit log doubles the data footprint without helping anyone audit anything. Audit entries reference app_ids only.
Customer end-user identities. Vault has no concept of end users — that's the customer's domain.
High-volume decrypt calls. Rate-limited endpoints log status in the access log (30-day rolling retention), not the audit chain. Audit entries would explode under real traffic; they're reserved for actions with operational or compliance weight.