Compliance Certificates

Three commands generate, inspect, and verify a session certificate

Generation checks the session and signs the result, inspection renders its fields, and verification decides whether the certificate and the evidence you supply pass.

chio --authority-seed-file ./session-authority.seed cert generate \
  --session-id session-001 --receipt-db ./receipts.db \
  --output ./session-certificate.json

chio cert inspect --certificate ./session-certificate.json

chio cert verify --certificate ./session-certificate.json \
  --trusted-kernel-pubkey ./session-kernel.pub \
  --full --receipt-db ./receipts.db

The CLI uses the generation key's public key as its receipt trust set, so that key matches the one that signed the retained session receipts. It supplies empty authorized-scope and required-guard lists and no expected tenant id, and takes its invocation budget from --budget-limit, where zero disables the budget check. An application that needs a scope, guard, or tenant requirement calls the library with an explicit ComplianceConfig.

Keep the database and the trusted key with the certificate when a reviewer will recheck the bundle, and read three things before interpreting the verdict:

1. Session and range. Match session_id, receipt_count, first_receipt_at, and last_receipt_at to the material you meant to review.
2. Configured checks. Read the five compliance booleans and anomalies beside the scopes, budget, required guards, and trusted keys that were supplied.
3. Verification result. Read passed, summary, receipts_reverified, and receipt_failures. Rendering the signed body is inspection, and verification is a separate step.

A passing certificate asserts six facts about one session

• Every receipt carries a signature its own signing key verifies.
• The receipt chain is continuous: receipts[i].seq + 1 == receipts[i+1].seq across the session.
• Every invocation named a tool inside the authorized scope set.
• The session stayed inside its invocation budget.
• Every required guard left evidence in every receipt.
• One kernel key, the one the body names, signed every receipt.

The body records the first five as typed booleans beside an anomalies array. Generation is all or nothing: the first failed check raises a typed error, so generate_compliance_certificate never produces a false boolean or a non-empty anomalies. Verification still treats either as a failure, which matters for a certificate that arrived from elsewhere.

The certificate is the operator's attestation over the configuration it supplied, for one session, and no legal, regulatory, or third-party certification: a regulator or accredited auditor takes it as input and makes its own finding. It shows that declared policies were honored, and says nothing about whether they suffice for a regime. A check that was never configured is skipped and still reports true: a guard absent from required_guards, scope with an empty authorized_scopes, and budget with budget_limit at zero. A clean certificate covers its session only.

The recipient chooses how much evidence to recheck

Lightweight verification takes the certificate and an independently trusted kernel key. It checks the signature over the canonical body, that the signer is in trusted_kernel_keys, that signer_key equals body.kernel_key, and that the body is consistent: the certificate schema, all five booleans true, and anomalies empty. It reads no receipts, and an untrusted signer fails whatever else holds.

Full-bundle verification adds the session's receipt database and repeats the per-receipt integrity walk from generation: it re-derives each content-addressed id, rechecks the action hash and the kernel key against the trust set, and rechecks session and tenant bindings. It passes only with zero receipt failures, so a third party reaches a verdict without trusting the issuing kernel. A FullBundle call with no receipt slice returns the lightweight result, and the CLI closes that gap by refusing --full without --receipt-db.

A pass reads lightweight verification passed or full-bundle verification passed (N receipts re-verified). A failure reads verification failed: followed by every reason that applied, comma separated, as listed in Verification result.

Verification refuses an unsigned certificate and missing inputs

The captures use a body assembled by hand with a signature that does not verify. inspect renders every field and reaches no verdict, because it verifies nothing:

$ chio cert inspect --certificate ./cert.json

Session ID:     demo-session
Schema:         chio.compliance.certificate.v1
Issued at:      1756944000
Receipt count:  3
First receipt:  1756943000
Last receipt:   1756944000
Signatures:     valid
Chain:          continuous
Scope:          compliant
Budget:         compliant
Guards:         compliant
Signer key:     31debe55d37c722768b137131caa6087080b2e0b60b94bd785d14575cfa498bc
Kernel key:     31debe55d37c722768b137131caa6087080b2e0b60b94bd785d14575cfa498bc

verify reaches the verdict. The hand-written signature fails, so the run reports one reason and exits 1; the signer is trusted here because the same key was passed in --trusted-kernel-pubkey.

$ chio cert verify \
    --certificate ./cert.json \
    --trusted-kernel-pubkey ./kernel.pub

FAIL: verification failed: certificate signature invalid

Full-bundle mode refuses before reading anything when it has no receipt database, and generation refuses a session with no receipts, which is what a store without Agent Client Protocol history returns for every session id.

$ chio cert verify \
    --certificate ./cert.json \
    --trusted-kernel-pubkey ./kernel.pub \
    --full

error[CHIO-CLI-RECEIPT-STORE-REQUIRED]: full-bundle verification re-verifies every receipt signature and needs the receipt store
  help: pass --receipt-db <path>, or drop --full to check the certificate signature alone
  code: urn:chio:error:cli:receipt-store-required
  docs: https://chio.computer/docs/reference/errors#error-cli-receipt-store-required

$ chio cert generate \
    --session-id demo-session \
    --receipt-db ./receipts.db \
    --authority-seed-file ./authority.seed

error[CHIO-CLI-SESSION-EMPTY]: no receipts found for session demo-session
  help: pass the --session-id of a session with receipts in the store
  code: urn:chio:error:cli:session-empty
  docs: https://chio.computer/docs/reference/errors#error-cli-session-empty

Each refusal names its input. An unsigned sample needs a generated certificate; a full-bundle request needs the retained session receipts; an empty session means the database holds no matching session, so check the session id and the Agent Client Protocol receipt binding. Configure an untrusted signer through your own channel, never because its key arrived in the certificate.

Each audit question has its own signed record

A certificate answers whether one session's configured checks held. The audit APIs answer which receipts matched a query, and a risk report answers whether the financial evidence behind a Transaction Passport holds together.

The certificate carries booleans and no receipts. The regulatory receipt export is the other direction: a read-only projection of the receipt store, filtered by agent and time window, capped at MAX_REGULATORY_EXPORT_LIMIT rows, and wrapped in a SignedExportEnvelope signed by the kernel's receipt-signing keypair. A reviewer holding both checks one certificate signature instead of replaying a guard, and returns to the receipts when the answer matters.

Next: export the receipts behind a certificate