Read the audit log

TOVIO keeps an append-only audit log of who accessed which protected files, which attempts were blocked, and when policies changed. It is content-addressed and signed, so it cannot be quietly rewritten — and you can verify that, offline, with one command. This guide shows how to read the log, get a human-friendly summary, and check its integrity.

Phase 1 — built today

The audit log is part of the Phase 1 permission layer, which is done. tovio audit verify, tovio audit log, tovio audit summary, and tovio audit show are built today, and the chain is tamper-evident: each entry is signed and links the previous one, so tovio audit verify catches any alteration offline.

flowchart LR
    EV["reads / denials / policy changes<br/>grants / revokes / rotations"] --> A["append signed entry<br/>(links prev hash)"] --> L[("audit log")]
    L --> V["tovio audit verify"] --> OK([✓ chain intact])

More diagrams for the full permission and review flow: Permission & review workflows.

Get a readable summary

Start with tovio audit summary — the rollup designed for humans. It answers "who touched the protected files lately?" without making you read raw entries:

$ tovio audit summary --last 7d
Audit summary — 49 entries, recent window:
  did:key:69923b5c…  47 read(s)  config/production/api-keys.env
  policy changes: 1
    PolicyChange           1
    PolicyObjectDecrypted  47
    ReadDenied             1

At a glance you see protected-read counts grouped by effective principal, the distinct paths they touched, and a count for every event class in the window — listed in alphabetical order by event name, not by frequency. --last <duration> accepts 7d, 24h, 30m and the like; omit it for all of history, and the header says "all history" instead of "recent window". A window with no protected reads in it prints no protected-object reads recorded in place of the per-principal lines — the event counts still follow. A per-principal zero-read/denial rollup is still a UX follow-on; inspect the raw records for the denied principal and token today.

Read the raw log

tovio audit log is the full, append-only access record, newest first:

$ tovio audit log
PolicyChange   2026-09-09 10:56:59 -04:00  did:key:69923b5c…
PolicyChange   2026-09-09 10:55:33 -04:00  config/production/**

$ tovio audit log --format json
$ tovio audit log --format csv

Option	Shows
--format human	The default — event, local timestamp, and the entry's subject (a DID or a path)
--format json	Machine-readable entries, including signer, effective principal, path, and token id
--format csv	Tabular export of the same current fields
--format template:<spec>	Repository-standard templated rows

--since, --path, --identity, and --agent filters are specified but not implemented on audit log yet. audit summary --last and audit show --object/--token provide the current narrowing surfaces.

To pull the records for a single object or token — the recovery path when you are investigating one file or one agent session — use tovio audit show:

$ tovio audit show --object blake3:5d20ab
$ tovio audit show --token cap_238545309b986bfda27a30da57bafafc

Exactly one of --object/--token is required. An object hash matches by prefix, with or without the blake3: prefix, so a short hash from tovio log is enough. A token id is the full cap_<32 hex> string tovio agent new printed. This is also the documented recovery path for TVO-STORE-002 and TVO-TOKEN-003.

Verify the log has not been tampered with

The audit log is a signed, chained structure: each entry links to the one before it. tovio audit verify walks that chain and confirms every signature and link, entirely offline:

$ tovio audit verify
✓ Audit chain verified — 1284 signed entries intact.

A clean result means no entry has been altered, removed, or inserted since it was written. If verification fails, the command errors rather than reporting success — a broken signature surfaces as TVO-CRYPTO-002. If some of the history has been moved behind a signed archive checkpoint by tovio audit archive, a second line says how many entries are live and how many the checkpoint authenticates; both are verified.

The chain survives key rotation

When an identity rotates its keys (see manage your keys), the audit chain is not orphaned. A signed key_rotate entry roots a new segment and records the previous segment's head, so tovio audit verify checks across the rotation — each segment under the key that signed it — without deleting or rewriting any earlier entry. Your history stays continuous and verifiable across rotations.

What gets logged

The audit log records the security-relevant events you would expect to answer "who did what":

• Reads of protected (policy) objects — PolicyObjectDecrypted.
• Token scope/operation/clearance and final decrypt denials at protected-read edges — ReadDenied. Denial append is best-effort because no plaintext is released; successful protected reads fail closed on audit append.
• PolicyChange — a new, modified, or removed policy in the manifest, and every tovio access grant and tovio access revoke, which carry the affected DID rather than a path. There is no separate grant or revoke event; filter on the DID to find them.
• TokenIssue / TokenRevoke for capability tokens, and KeyRotate / KeyRecover / KeyImport / IdentityInit / DeviceEnroll / DeviceRevoke across the key and device lifecycle.
• AgentCommit for every tovio commit --token, and PluginBlocked when an enforcing plugin gate refuses an operation.
• Obliterate, plus ref and transfer events (Push, Fetch, BranchCreate, BranchDelete), the federation events (FederationProvision, FederationDeprovision, FederationAttributeChange), and the Forge's own admin-mutation events such as LockBreak, WebhookDeactivate and HostedAdminChange.

The variant set is additive — new events are added over time without changing the encoding of the existing ones — so a consumer should tolerate an event name it does not recognize rather than reject the entry. An entry is encoded in snake_case (policy_object_decrypted, key_rotate) and rendered in the CLI as shown above.

Because the log is append-only and signed, it is a trustworthy record, not just a convenience — it is the evidence behind every "yes, that access really happened" question.

Next steps

• Check access — diagnose a denial that shows up as a blocked attempt here.
• Grant and revoke access — the grants and revocations recorded in this log.
• Security — how the audit log fits the broader security posture.

Last reviewed September 9, 2026

Suggest an improvement to this page  ·  Not for security reports — see disclosure