Compliance Certificates

Certificate Assertions

A valid certificate asserts six things about the session it covers:

• Every receipt in the session has a valid Ed25519 signature.
• The receipt chain is continuous: no gaps, duplicates, or reordering across sequence numbers.
• Every tool invocation fell inside the capability's authorized scope.
• No budget limit (invocation count or monetary) was exceeded.
• Every required guard produced evidence in every receipt.
• Delegation chains maintained monotonic attenuation (no escalation).

The unsigned body records these checks as typed booleans plus an anomalies array. For the certificate to report all checks passing, each boolean must be true and anomalies must be empty.

Schema

pub const COMPLIANCE_CERTIFICATE_SCHEMA: &str = "chio.compliance.certificate.v1";

pub struct ComplianceCertificateBody {
    pub schema: String,                  // chio.compliance.certificate.v1
    pub session_id: String,
    pub issued_at: u64,                  // unix seconds
    pub receipt_count: u64,
    pub first_receipt_at: u64,
    pub last_receipt_at: u64,
    pub all_signatures_valid: bool,
    pub chain_continuous: bool,
    pub scope_compliant: bool,
    pub budget_compliant: bool,
    pub guards_compliant: bool,
    pub anomalies: Vec<String>,
    pub kernel_key: PublicKey,           // kernel that signed the session receipts
}

pub struct ComplianceCertificate {
    pub body: ComplianceCertificateBody,
    pub signer_key: PublicKey,
    pub signature: Signature,            // Ed25519 over canonical_json_bytes(body)
}

The signature is computed over RFC 8785 canonical JSON of the body. Verifiers must re-canonicalize the body before checking the signature; non-canonical serialization will fail verification.

Generation Algorithm

The kernel walks the complete receipt log for the session. Any anomaly raises a typed error and aborts. The kernel does not issue a partial certificate.

pub fn generate_compliance_certificate(
    session_id: &str,
    receipts: &[ComplianceReceiptEntry],
    config: &ComplianceConfig,
    keypair: &Keypair,
) -> Result<ComplianceCertificate, ComplianceCertificateError>;

The configuration controls scope, budget, and guard expectations:

pub struct ComplianceConfig {
    pub budget_limit: u64,           // 0 means unlimited
    pub required_guards: Vec<String>,
    pub authorized_scopes: Vec<String>,  // resource path prefixes
    pub expected_tenant_id: Option<String>,  // None disables the tenant check
    pub trusted_kernel_keys: BTreeSet<String>,
}

Step ordering inside the algorithm:

• Empty session check: if no receipts exist for the session, abort with EmptySession.
• Per-receipt Ed25519 signature verification. First failure aborts with InvalidReceiptSignature.
• Per-receipt integrity: the content-addressed receipt id, the action parameter hash, the signing kernel key's membership in trusted_kernel_keys, and the session (and, when configured, tenant) binding. These abort with InvalidReceiptId, InvalidActionHash, UntrustedKernelKey, SessionMismatch, and TenantMismatch respectively.
• Chain continuity. Consecutive receipts must satisfy receipts[i].seq + 1 == receipts[i+1].seq. Any gap aborts with ChainDiscontinuity.
• Scope check (when authorized_scopes is non-empty): tool name must match at least one authorized prefix.
• Budget check (when budget_limit > 0): total invocation count must not exceed the limit.
• Guard evidence: for each required guard, every receipt must list it in evidence.
• Construct the body and sign it with the operator keypair over canonical JSON.

Abort Errors

The shipped ComplianceCertificateError enum has fifteen variants. Thirteen are substantive compliance aborts: each means the session is non-compliant and no certificate is produced.

The two remaining variants, Serialization and Signing, are infrastructure errors during certificate construction rather than compliance findings.

Verification Modes

Lightweight

Lightweight verification trusts the kernel's assertions in the body. It checks the certificate signature, confirms every body boolean is true, and confirms the anomalies list is empty. It does not re-verify individual receipt signatures. Sufficient when the kernel is in the relying party's trusted computing base.

Full Bundle

Full bundle verification re-verifies receipt signatures independently of the kernel's assertions. It performs all lightweight checks plus a per-receipt Ed25519 verify against the receipt log bundle, then reports the count of successful and failed re-verifications. A third party can use this mode without trusting the issuing kernel.

pub enum VerificationMode {
    Lightweight,
    FullBundle,
}

pub struct CertificateVerificationResult {
    pub certificate_signature_valid: bool,
    pub body_consistent: bool,
    pub receipts_reverified: u64,
    pub receipt_failures: u64,
    pub passed: bool,
    pub summary: String,
}

Auditor Workflow

A certificate lets an auditor determine session compliance without replaying each guard evaluation:

• The kernel emits a certificate at session end. The session operator publishes it alongside the receipt log bundle.
• The auditor pulls the certificate and (for full bundle verification) the corresponding receipt bundle.
• The auditor confirms cert.signer_key is in the configured trust set.
• The auditor runs lightweight verification first. If that passes and the auditor needs cryptographic non-repudiation, they run full bundle verification using the receipt bundle.
• If any check fails, the certificate is rejected.

What a Certificate Does Not Prove

A compliance certificate is an attestation by the operator running the kernel. It is evidence, not a regulatory finding:

• Not a regulatory attestation by itself. A regulator may use the certificate as input, but the legal attestation is something a regulator or accredited auditor produces, not something the certificate replaces.
• Not a statement of policy quality. The certificate proves that the policies the operator declared were honored. It does not certify that the policies were sufficient for any particular regulatory regime.
• Not a statement about absent evidence. If a guard was never required by the config, its absence from receipts is not a compliance violation. Configuration is the operator's responsibility.
• Not transferable across sessions. Certificates are session-scoped. A clean certificate for session N says nothing about session N+1.

Difference from Regulatory APIs

Regulatory integrations, such as GDPR data-subject requests, SEC recordkeeping, and healthcare audit endpoints, consume signed receipts and certificates as evidence. A certificate is a signed set of compliance booleans for one session. A regulatory API projects certificates, receipts, and attestations for a specific regime across multiple sessions.

A regulatory API can:

• Pull the relevant compliance certificates plus underlying receipts.
• Re-canonicalize and re-verify signatures.
• Project the underlying evidence into the format the regulator accepts (XBRL filings, audit logs, schema-specific exports).

The regulatory layer can verify one Ed25519 signature per session instead of replaying each guard.

CLI

Implementations should expose three commands. Exit codes: 0 verification passed, 1 verification failed, 2 input error.

# Generate a certificate for a session (--receipt-db is required)
chio cert generate --session-id <session-id> --receipt-db <path> \
    [--budget-limit <n>] [--output <path>]

# Verify a certificate (add --full plus --receipt-db for full-bundle mode)
chio cert verify --certificate <path> --trusted-kernel-pubkey <path> \
    [--full] [--receipt-db <path>]

# Inspect a certificate without cryptographic verification
chio cert inspect --certificate <path>

A successful verify run prints:

certificate signature: valid
body consistent:       yes
receipts reverified:   2134
receipt failures:      0
result:                passed

Worked Example

Session sess_2026-04-28T14:00:00Z_abcd ran for 38 minutes, produced 2 134 receipts, and finished without any guard or budget violation. The operator's config required two guards (jailbreak and network) and capped invocations at 5 000. At session end the kernel emits:

{
  "body": {
    "schema": "chio.compliance.certificate.v1",
    "session_id": "sess_2026-04-28T14:00:00Z_abcd",
    "issued_at": 1714316280,
    "receipt_count": 2134,
    "first_receipt_at": 1714314000,
    "last_receipt_at": 1714316280,
    "all_signatures_valid": true,
    "chain_continuous": true,
    "scope_compliant": true,
    "budget_compliant": true,
    "guards_compliant": true,
    "anomalies": [],
    "kernel_key": "ed25519:c0fee1234..."
  },
  "signer_key": "ed25519:0a11ce5678...",
  "signature": "9b2f...c4d1"
}

An auditor running offline verification:

• Re-canonicalizes body with RFC 8785 JCS.
• Confirms signer_key.verify(canonical_body, signature) succeeds.
• Confirms every body boolean is true and the anomalies list is empty.
• Optionally pulls the receipt bundle and re-verifies each of the 2 134 Ed25519 signatures, expecting receipts_reverified = 2134 and receipt_failures = 0.

The process is offline. The auditor does not evaluate a guard.

Related Reading

• Kernel · Receipts · the per-invocation evidence the certificate aggregates
• Reputation Scoring · the longitudinal signal compiled from receipts across many sessions
• Agent Passports · portable proof of identity and reputation using Ed25519