Evidence Export

A directory, not a stream

chio evidence export writes a directory. The output path must not exist or must be empty; a non-directory path and a directory with any entry in it are both refused before a byte is written. What lands there is twelve files, up to three more when a policy or a federation policy is attached, and manifest.json, which lists the SHA-256 and byte length of every file except itself. The whole feature is shipped: export, verify, import, and federation-policy create are subcommands in chio-cli, and the remote path is POST /v1/evidence/export and POST /v1/evidence/import on the trust control plane.

The verifier is the point. chio evidence verify --input <dir> dispatches to a function handed the input directory and an output flag and nothing else: no store handle, no control-plane client, no key material. It re-reads the directory, re-derives every count the manifest asserts, checks every signature the package carries, and replays every inclusion proof against the Merkle root in the checkpoint that proof names. An outside party runs it on a copy with the network unplugged.

What is in the package

The manifest is a commitment, not an authority. Six of its fields are re-derived at verification time from the data next to them: counts, proof_coverage, receipt_semantics, child_receipt_scope, disclosure_notice, and claim_boundary. That is why a tampered receipt is caught even when the attacker refreshes the file digest to match:

struct EvidenceExportManifest {
    schema: String,
    exported_at: u64,
    query: EvidenceExportQuery,
    counts: EvidenceExportCounts,
    proof_coverage: EvidenceProofCoverage,
    receipt_semantics: EvidenceReceiptSemanticSummary,
    child_receipt_scope: EvidenceChildReceiptScope,
    claim_boundary: Option<EvidenceTransparencyClaims>,
    files: Vec<EvidenceExportFileHash>,
    policy: Option<PolicyAttachmentMetadata>,
    federation_policy: Option<FederationPolicyAttachmentMetadata>,
    disclosure_notice: Option<EvidenceDisclosureNotice>,
}

receipt_semantics counts receipt kinds, boundary classes, and an authorized total that increments only for a receipt whose id recomputes from its body, whose signature and action hash both verify, and which ChioReceipt::is_allowed accepts: trust level Mediated, kind MediatedDecision, boundary class Prevent, no observation outcome, decision Allow. Editing a receipt body moves that total, so the semantic-summary check trips before the raw signature pass. That is what evidence_verify_detects_tampered_receipt_even_if_manifest_hash_is_updated asserts, byte for byte, in the CLI integration suite.

How an export is assembled

The query is settled before the store is touched. prepare_evidence_export verifies an attached federation policy’s signature, merges its query with the requested one, and validates the result. The merge is intersection, not union: an exact scope field present in both must match or the export fails with falls outside the signed federation policy; since takes the maximum, until the minimum, and a window that does not overlap is an error. require_proofs is the logical OR of the flag and the policy. A read boundary is mandatory: a query with none is refused, and when a policy is attached the boundary must come from the policy, so a caller cannot pick its own.

Then the store builds the bundle. Tool receipts page through the ordinary receipt query with the boundary applied, and each receipt is paired with its claim_receipt_log_entries sequence; a receipt missing from the claim log fails the export rather than exporting unsequenced. Checkpoints are every checkpoint whose batch range overlaps the exported minimum and maximum sequence. Lineage is the combined delegation chain for each cited capability, and every snapshot must pass transport validation, which re-verifies the signed token against the projected fields and refuses a legacy projection outright. A snapshot whose provenance is a federation anchor has no token to verify: transport validation only checks that its id is fed-del- plus 64 hex characters and that it puts nothing in the signed lineage fields. Inclusion proofs are rebuilt, not stored: for each checkpoint the store re-reads the canonical bytes of the whole batch, rebuilds the Merkle tree, and emits a path for each exported receipt inside it. Receipts with no covering checkpoint go to uncheckpointedReceipts, and --require-proofs turns a non-empty list into a failed export naming the first five as receipt_id@seq. Only the count reaches the package; the ids live in the in-memory bundle and in that error string, not in a file.

Child receipts carry an honest scope flag

Child request receipts have no capability or agent attribution, so the export refuses to imply one. The scope is derived from the query alone and recorded in the manifest: full_query_window only for an admin-all export with no tenant, capability, or agent filter, since a time window on its own does not narrow it; time_window_context_only when a capability or agent filter is paired with a time window; and omitted_no_join_path for any tenant-scoped or tenant-filtered export and for a capability or agent filter with no time window. Verification recomputes the expected scope from the query and rejects both a mismatch and the presence of child receipts under an omitted scope.

The cross-tenant disclosure a signed checkpoint cannot avoid

A tenant-scoped export contains only that tenant’s receipts. The signed checkpoint bodies it inherits cover the full per-batch Merkle tree, which spans tenants by construction, so the package necessarily reveals seven checkpoint body fields (batch_start_seq, batch_end_seq, tree_size, merkle_root, checkpoint_seq, issued_at, previous_checkpoint_sha256) and three derived publication fields (entry_start_seq, entry_end_seq, log_tree_size). Rather than hide that, a tenant-scoped export attaches a fixed notice (chio.evidence_export_disclosure_notice.v1) listing those ten fields, the metadata narrowed relative to an admin-all export, and a protocol reference. The notice is canonical text: verification rebuilds it from the query and rejects a package that strips it, tampers with it, or attaches it to an admin-all export. Eliminating the disclosure needs per-tenant subtree proofs, which the protocol does not have.

Where it runs, and what the cluster does with it

Export reads one store. Against --receipt-db it opens the file directly; against --control-url it posts the query and receives the bundle. Passing both is refused, passing neither is refused. On the service side the handler resolves a read principal first: a tenant read token cannot request an admin-all export, cannot name another tenant, and has an omitted boundary filled in with its own tenant. That check runs twice, once on the request and again on the query that came out of the federation-policy merge, so a signed policy cannot widen a tenant token.

Import is the write, and it is the one clustered operation here. POST /v1/evidence/import authenticates against the full service token rather than a read principal, so a tenant read token can export and cannot import at all. It then goes through forward_post_to_leader like any other trust-control write, so it inherits the quorum check, the lease check, and the 503 vocabulary described in Leader & Failover. Export forwards nothing; it is a read, answered by whichever node received it, from that node’s own disk.

Every import needs an attached signed federation policy. build_federated_share_import refuses a package without one, with the reason stated in the code ("so remote receipt sharing stays bilateral and explicit"), and names the share share-<sha256> over a canonical descriptor holding the manifest and that policy. The mechanism is Cluster. The authorization it insists on is Federation.

What verification actually checks

load_verified_evidence_package is one pipeline used by all three verbs: verify runs it and prints, import runs it and then builds the share, and chio-mercury runs its summary form to obtain a manifest digest. Every step below is a hard failure, and the order is the order in the function: a package that fails an early structural check never reaches the proof replay.

Export, verify, then break it

Both verbs run against a local receipt database with no cluster and no network. The package below comes from a node that had answered exactly two governed calls, one allow and one deny.

$ chio --receipt-db .chio/receipts.db evidence export --admin-all --output ./evidence
$ ls evidence

README.txt
capability-lineage.ndjson
checkpoint-consistency-proofs.ndjson
checkpoint-equivocations.ndjson
checkpoint-publications.ndjson
checkpoint-witnesses.ndjson
checkpoints.ndjson
child-receipts.ndjson
inclusion-proofs.ndjson
manifest.json
query.json
receipts.ndjson
retention.json

$ chio evidence verify --input ./evidence

evidence package verified
tool_receipts:          2
child_receipts:         0
checkpoints:            0
checkpoint_publications: 0
checkpoint_witnesses:   0
checkpoint_consistency_proofs: 0
checkpoint_equivocations: 0
capability_lineage:     2
inclusion_proofs:       0
uncheckpointed_receipts: 2
authorized_receipts:     1
trace_observations:      0
advisory_evaluations:    0
verified_files:         12
child_receipt_scope:    FullQueryWindow
transparency_preview_logs: 0
publication_state:      transparency_preview

verified_files: 12 is the first pass in the table: every file the manifest lists was re-hashed and re-measured. authorized_receipts: 1 counts the allow, and the deny is the other row. Rewrite that deny in a copy of the exported receipts.ndjson so it reads as an allow, which is the edit an exporter would most want to get away with, and the manifest digest catches it before any signature is checked.

$ cp -R ./evidence ./evidence-flipped
$ python3 - <<'PY'
$ import json, pathlib
$ p = pathlib.Path('./evidence-flipped/receipts.ndjson')
$ lines = p.read_text().splitlines()
$ obj = json.loads(lines[1])
$ obj["receipt"]["decision"] = {"verdict": "allow"}
$ lines[1] = json.dumps(obj, separators=(",", ":"))
$ p.write_text("\n".join(lines) + "\n")
$ PY
$ chio evidence verify --input ./evidence-flipped

error [urn:chio:error:attest:provenance-missing]: evidence package file hash mismatch for receipts.ndjson
context: {"domain":"attest","severity":"error","stability":"unstable","string_code":"CHIO-ATTEST-PROVENANCE-MISSING"}
suggested fix: Regenerate the evidence bundle and include provenance before submitting the operation.

The refusal names the file, not the receipt, because the manifest digest pass runs before the signature pass and a package that fails an early structural check never reaches the later ones. Repairing the manifest to match would move the refusal down to the signature pass, where the receipt’s own kernel signature no longer covers the edited body.

The require_proofs row in the table is the same shape and refuses at export rather than at verify, since these two receipts predate any checkpoint:

$ chio --receipt-db ./.chio/receipts.db evidence export \
  --output ./evidence-proofs --admin-all --require-proofs

error [urn:chio:error:attest:provenance-missing]: evidence export requires checkpoint coverage, but 2 receipt(s) are uncheckpointed: f8128d2289c69d835348f229edfdd2714a8b3c6f064f4f7324b652a299e9a4b3@1, e7a4fc95979cc9b31d8b740c27cd58f1fde209aac323aaeac115544d82be2ee7@2
context: {"domain":"attest","severity":"error","stability":"unstable","string_code":"CHIO-ATTEST-PROVENANCE-MISSING"}
suggested fix: Regenerate the evidence bundle and include provenance before submitting the operation.

Both receipt ids are printed with their entry sequence, so the operator knows which rows to checkpoint rather than which flag to drop.

One deliberate looseness is documented in place. Package verification has no policy input, so it cannot enforce an operator’s configured crypto floor and says so rather than guessing:

// Evidence package verification has no policy.crypto_floor input.
// Keep the compatibility floor explicit here: accept classical and hybrid receipts, while policy-bearing callers enforce
// their configured floor before export.
if !record
    .receipt
    .verify_signature_with_floor(ReceiptCryptoFloor::AllowHybrid)

Scoped disclosure: a subgraph of a signed root

The enterprise path solves a different problem. A transaction passport signs one evidence graph, and a recipient should see only the nodes their verifier family needs. Rather than re-sign a smaller graph, chio proof verify slices it: it keeps nodes whose role belongs to the family, keeps only edges whose endpoints both survived, and hands the verifier the scoped bytes plus the untouched root bytes. The passport it passes carries the scoped digest.

let mut signed_passport = passport.clone();
signed_passport.evidence_graph_sha256 = super::sha256_hex(signed_evidence_graph_bytes);
verify_transaction_passport_signature(&signed_passport, trusted_root_signer_keys)?;
if signed_evidence_graph_bytes != scoped_evidence_graph_bytes {
    validate_scoped_evidence_graph_subset(
        signed_evidence_graph_bytes,
        scoped_evidence_graph_bytes,
    )?;
}

The signature is checked against a clone carrying the root digest, so the issuer still signed the whole graph. The subset check then requires every scoped node and every scoped edge to appear in the signed root. Downstream, artifact binding runs against the scoped bytes and the passport’s own scoped digest. Omission is allowed, addition is not, and the recipient never receives the roles they were not given.

Entry identity in the subset test is serde_json::to_string of the parsed entry. The workspace does not enable preserve_order, so object keys are already sorted on both sides and neither key order nor whitespace matters; numeric re-formatting does, since 1.0 where the root wrote 1 is a different key. The signed root bytes themselves have to stay byte-exact regardless, because the passport signature is checked over their SHA-256.

The enterprise artifacts it validates

chio-enterprise-export verifies a scoped graph whose nodes are typed artifacts, each keyed to the passport and to one risk comptroller report that all five must cite identically. Every artifact struct in that crate is deny_unknown_fields, so an unexpected key is a parse failure rather than an ignored one.

The trust model here is the opposite of the offline verifier’s. Passport signers, approval signers, risk comptroller signers, and telemetry receipt kernel keys are all supplied by the operator, and the CLI reads them from pinned environment variables such as CHIO_ENTERPRISE_TRUSTED_APPROVAL_KEYS with no default: an unset variable fails the run with CHIO_ENTERPRISE_TRUSTED_APPROVAL_KEYS must pin trusted enterprise approval signer keys rather than accepting anyone.

Guarantees and limits

Next Steps

• Receipt Aggregation · the log this reads, the streams that replicate, and the checkpoint chain that does not
• Federation Overview · the counterpart half: the signed bilateral policy, its scope fields, and what a partner may ask for
• Leader & Failover · why import forwards and export does not, and what a forwarded write returns when it cannot proceed
• Node State on Disk · the single-writer store the bundle is read out of
• Proof Room · the verifier that recomputes a bundle report from source inputs, including the enterprise family above