Evidence and Audit Commands¶
Commands that read, verify and archive a Network Authority’s evidence store, and that replace its NA key.
Commands are stable unless marked Beta; Public Contract lists the level of every command. A beta command may change in a minor release.
Note
The commands that talk to an NA here need it running with EVIDENCE_STORE=on
(off by default; genesis-mesh na start --evidence-store on locally, or
EVIDENCE_STORE=on in its settings file). Without it the NA records nothing
and answers 404 evidence_store_disabled. Anchors are made every
NA_ANCHOR_INTERVAL_SECONDS (default 3600; 0 only on request). The key
succession commands work with the store off.
Evidence Store¶
genesis-mesh evidence verify-export¶
v0.59: Evidence Store
Verify an evidence export offline: envelopes, the store hash chain, NA and executor signatures, per-decision and per-resource chains.
genesis-mesh evidence verify-export \
--file export.jsonl \
--na-public-key <base64> \
--executor-keys executor-keys.json
--executor-keys takes the response of GET /admin/evidence/executor-keys.
With --known-anchors <dir or file> (v1.2.0) the export is also checked
against store anchors held outside the NA: it must start at entry 1 or right
after a retention checkpoint it contains (an export after retention must hold
the checkpoint’s entry), and must not stop before the newest held anchor; a
removed or rewritten anchored record fails. --from-anchor (v1.3.1) accepts
an export since an anchored position, which starts right after a held anchor
whose digest its first entry names; before 1.3.1 every such export was
accepted. --partial accepts a deliberate slice and checks neither end.
The reason codes are listed in Evidence event schema (gm.evidence.event v1).
Exit code 0 when verified; 1 on any failure.
genesis-mesh evidence anchors fetch¶
Beta.
v1.2.0: Evidence Anchors
Copy the NA’s store anchors into a directory you control. Each run reads
every anchor the NA serves and compares it with the copy held: a different
anchor at a held position, or one the NA no longer serves, writes nothing and
fails. Otherwise the whole set is checked (NA signature, unbroken chain) and
missing positions are written atomically; existing files are never replaced.
--anchor-now first asks the NA to anchor its current head. A read-tier key
is enough for both.
genesis-mesh evidence anchors fetch \
--na https://na.example.org \
--na-public-key na.pub \
--out /audit/anchors \
--operator-key auditor.key --operator-key-id auditor
See Evidence Anchors. Exit code 0 on success; 1 on failure.
Across an NA key succession (v1.5.0), give --na-public-key once per key, or
verify exports with verify-export --key-history <file> --root-key <root public key>: the key history (GET /na/key-history) is checked from the root
key, and each NA signature with the key valid at the record’s time.
Audit Packs and Key Succession¶
Beta. Every command in this section is beta.
v1.5.0: Audit Packs and Independent Verification.
Command |
What it does |
|---|---|
|
Write an audit pack: one range of the store between two anchors ( |
|
Verify a pack offline from the root public key and the anchors you hold (without them: a warning, |
|
Write a pack from the end of the last archive to immutable storage, read it back, verify it ( |
|
Save the NA’s key history for the offline signing step |
|
Offline: verify the history from the root key, then sign the next NA key’s succession with it ( |
|
Where the new NA key lives: sign the succession with it, proving it is held ( |
|
Record the succession the root key and the new key signed; the NA countersigns it with its current key. Privileged key. See Key Succession and the Root Key |
|
After a succession, re-issue now the attestations and treaties the old key signed that outlive its vouching horizon, and sign the active policy manifest again; reports what is still due. The NA also does this on its own once the new key signs. Privileged key (v1.8.0) |
|
Check an NA host against its settings: the root private key absent from where the NA’s files live, the NA key valid now (and for how long), nothing left to re-issue after a succession (v1.8.0), archives required. |
genesis-mesh init warns that it writes the root private key next to the NA
key (v1.5.0): for anything but local use, move it offline.