Protocol Reference

Source

This page normatively reflects spec/PROTOCOL.md in the Chio repository. Status: Current bounded Chio release profile. Version 1.0. Chio is pre-release and supports v1 only. Earlier internal draft versions are incorporated into this contract without runtime compatibility layers. The HTTP sidecar protocol, OpenAPI integration pipeline, and supporting CLI interfaces are part of that v1 contract, not a later major version.

Purpose

Chio mediates agent tool calls under capabilities and records signed receipts. In this repository it ships as:

• a native agent-to-kernel protocol for signed capability evaluation
• a kernel that emits signed receipts for allow, deny, cancelled, and incomplete outcomes
• trust-control services for authority, revocation, receipt, budget, and federation state
• hosted MCP-compatible edges and adapters that keep the same trust contract
• machine-readable extension manifests, negotiation records, and qualification records
• portable trust records for did:chio, schema issuance, challenge/response presentation, evidence export, and certification
• web3 trust, anchoring, oracle, and settlement records backed by bounded chio-link, chio-anchor, and chio-settle runtimes; they are evidence records unless a kernel-mediated dispatch path is present
• a static, read-only Proof Room page (chio proof serve) that renders verified evidence without authorizing actions
• records for one bounded autonomous insurance-automation workflow
• public identity-profile, wallet-directory, and routing records for one bounded public identity network

Compatibility

• Additive fields may appear in JSON responses and signed records.
• Unknown schema identifiers for schema-tagged records must be rejected.
• Fail-closed behavior is part of the protocol contract, not an implementation detail.

Not Yet Claimed

The shipped v1 contract does not claim the following. These are distinct from the boundary items in Explicit Gaps and are listed to prevent inferences from adjacent interfaces:

• OpenAI hosted-tool mediation, OpenAI remote MCP execution, Bedrock Lambda mediation, voice execution, or broad live-directory import, before receipt semantics, durable commit, semantic authority, and tenant read-boundary gates are merged and tested
• OAuth authorization-server product status, until an accepted ADR defines scope, RAR grammar, telemetry, and feature gates
• manifest event publish/consume actions, before the current v1 manifest planning work is accepted and implemented
• multi-region consensus or Byzantine replication
• automatic SCIM provisioning lifecycle
• synthetic cross-issuer passport scoring
• a replacement of MCP or A2A at the wire-protocol ecosystem level

Components and Trust Boundaries

The following security boundary applies to each interface:

• the agent never receives ambient authority
• every mediated action is bound to explicit capability or authenticated hosted session state
• denials are explicit, signed, and auditable
• extensions may replace only named integration points and must preserve local policy activation and signed Chio records
• registry and record mismatches fail closed

Serialization and Identity

Canonical JSON

Signed Chio records use canonical JSON serialization (RFC 8785) before Ed25519 signing. This includes capability tokens, receipts, manifests, checkpoints, verifier policies, passport presentations, and certification records.

Native Wire Format

The native agent-to-kernel protocol uses length-prefixed JSON messages with a type discriminator. The normative wire definition lives in the Wire Protocol page.

• Request examples: tool_call_request, list_capabilities, heartbeat.
• Response examples: tool_call_chunk, tool_call_response, capability_list, capability_revoked, heartbeat.

Hosted Wire Format

The hosted edge uses MCP-compatible HTTP semantics rather than the native length-prefixed transport:

• JSON-RPC over HTTP POST
• standalone GET/SSE streams where supported by the hosted edge
• bearer-token or JWT-backed session admission
• remote admin APIs under /admin/...

Shipped hosted contract:

• initialize is a POST /mcp request, not a GET bootstrap.
• Successful initialize returns an SSE response plus MCP-Session-Id.
• Clients send notifications/initialized before relying on ready-state methods such as tools/list or tools/call.
• GET /mcp is the live-and-replay notification stream, with Last-Event-ID as the replay cursor.
• Caller-supplied model metadata is preserved on the request path, but its provenance enters Chio as asserted until a trusted subsystem upgrades it.

Identity

Chio uses Ed25519 keys as the primary cryptographic identity mechanism. did:chio is the shipped self-certifying DID method:

did:chio:{64-hex-ed25519-public-key}

Resolution is local and self-certifying. Optional service endpoints, such as a receipt-log URL, may be attached by the resolving environment. Broader public identity profiles may also name did:web, did:key, and did:jwk as compatibility inputs, but those methods do not replace did:chio as Chio's canonical provenance anchor in this release.

Capability Contract

The shipped capability token is CapabilityToken from chio-core-types. Capability tokens are schema-tagged signed records: newly issued tokens carry schema: "chio.capability.v1" in the schema-aware signing input, and load-time and verify-time paths reject any unknown capability schema. The v1 signed body is:

Scope

The shipped scope model includes:

• grants: Vec<ToolGrant>
• resource_grants: Vec<ResourceGrant>
• prompt_grants: Vec<PromptGrant>

ToolGrant includes:

• server_id, tool_name, operations, constraints
• max_invocations, max_cost_per_invocation, max_total_cost
• optional dpop_required

The shipped constraints type includes ordinary argument constraints plus governed-transaction controls such as governed_intent_required, require_approval_above, and seller_exact.

Capability Attenuation

chio.capability.v1 carries delegation and attenuation directly in the signed token body:

• typed first-party caveats with { kind, predicate, sig? }
• scope_attenuations carrying the narrowing operations
• attenuation_proof with parentScopeHash, childScopeHash, and a normalizedSubsetProof
• optional budget_share_bps, a fixed-point child budget share capped at 10000; values above that fail closed because they would re-amplify parent authority

Minting and verification use the witness API:

compute_attenuation_witness(parent: &ChioScope, child: &ChioScope)
verify_attenuation_witness(parent_hash, child_hash, witness)

Both paths check that the child scope hash in the proof matches the token scope, that the witness hashes match the normalized scopes, and that every recorded grant relation is a subset.

A chain-binding rule (W1.1) binds the proof to the upstream lineage. Every delegation hop carries a signed DelegationLink.scope_hash. A direct-issue token (empty delegation_chain) MUST have attenuation_proof.parent_scope_hash equal to the verifier's trust-root scope hash for the issuing authority; a delegated token MUST have it equal to delegation_chain.last().scope_hash, and a chain whose hops omit scope_hash is rejected fail-closed. This binding is what enforces safety property P1: without it an issuer could claim a larger parent scope and supply an internally consistent witness.

Capability Negotiation

Federated peers exchange chio.capabilities.v1 during trust establishment. The envelope carries a string-keyed feature bitset, and peers proceed only with the intersection of features both sides advertise. Malformed feature names and unsupported schema IDs fail closed before a peer can use a negotiated feature. The initial feature names are:

• accepts_anchor_batch_v1
• accepts_hybrid_signatures
• delegation_chain_binding

Peers that do not advertise the bitset stay on the v1 default. Capability schema selection itself is not negotiated before public release: chio.capability.v1 is the only Chio-owned token schema accepted by runtime verifiers.

Governed Transaction Extensions

Tool-call requests may attach two optional governed objects:

• governed_intent: a canonical request intent carrying id, server_id, tool_name, purpose, optional max_amount, optional seller-scoped commerce, optional metered_billing, optional asserted call_chain, and optional structured context.
• approval_token: a signed approval token bound to one subject, one request id, and one governed intent hash.

When a matched grant includes governed_intent_required, the kernel requires governed_intent. When a matched grant includes require_approval_above, the kernel requires a valid approval_token whenever the provisional charged amount meets or exceeds that threshold. When a matched grant includes seller_exact, the kernel requires seller-scoped commerce approval context and denies if the governed seller does not match the grant seller scope.

Approval tokens are verified against trusted authority keys and are bound to:

• the request request_id
• the capability subject
• the canonical hash of the attached governed intent
• approval-token issued_at and expires_at time bounds

Provenance Evidence Classes

Chio's normative provenance model distinguishes three evidence classes:

• asserted: caller-supplied context that Chio preserves but has not independently authenticated
• observed: local lineage facts Chio directly observed inside one authenticated session
• verified: lineage Chio checked against signed records such as chio.session_anchor.v1, chio.receipt_lineage_statement.v1, or chio.call_chain_continuation.v1

Verification Rules

The kernel and trust-control service verify at minimum:

• Ed25519 signature validity
• current time is within issued_at <= now < expires_at
• the requested target is contained by the grant set
• the presented capability and any preserved delegation structure are syntactically valid for the bounded shipped profile
• revocation state is clear for the presented capability and any presented delegation ancestor IDs
• DPoP proof is valid when the selected grant requires it
• policy guards pass

Any failure denies or rejects the action instead of widening access.

Safety Properties

The current launch-candidate safety inventory:

Receipt Contract

The current v1 receipt envelope is ChioReceipt from chio-core-types. The v1 shape makes authority structural: a receipt's receipt_kind, boundary_class, and trust_level together determine whether it is an authorization or only evidence.

Receipt Kinds and Decisions

The receipt_kind tri-state binds each receipt's boundary class, trust level, and decision presence:

• mediated_decision receipts use boundary_class = prevent, trust_level = mediated, and MUST carry a decision.
• trace_observation receipts use boundary_class = detect_only, trust_level = verified, and MUST omit decision.
• advisory_evaluation receipts use boundary_class = advisory_only, trust_level = advisory, and MUST omit decision.

Only mediated_decision + prevent + Allow may be displayed or exported as authorization. Trace and advisory records can be evidence, but they are never authorization receipts.

When present, the decision enum is:

• Allow
• Deny { reason, guard }
• Cancelled { reason }
• Incomplete { reason }

The protocol guarantee is that cancelled and incomplete outcomes are preserved explicitly rather than collapsed into an undifferentiated error state.

Child Receipts

Nested flows such as sampling, elicitation, and resource reads use ChildRequestReceipt, which records: session_id, parent_request_id, request_id, operation_kind, terminal_state, outcome_hash, policy_hash, optional metadata.

Provenance Graph Records

• session anchors capture authenticated session continuity
• request-lineage records capture request nodes and local parent edges
• receipt-lineage statements capture authenticated receipt-to-receipt edges
• continuation tokens capture authenticated cross-kernel or cross-session provenance transfer

Checkpoints

Receipt batches can be committed to a Merkle checkpoint with primary schema chio.checkpoint_statement.v1. Checkpoint verification is part of exported evidence and compliance-oriented operator reporting. The current bounded release treats checkpoints as local audit evidence with derived log_id, log_tree_size, predecessor-witness and consistency-proof fields. Those proofs support audit and transparency_preview claims only.

HTTP Receipts

The HTTP sidecar protocol introduces HttpReceipt, a domain-specific receipt type for HTTP-layer policy evaluations. HttpReceipt is the receipt format returned by the sidecar evaluation endpoint. ChioReceipt remains the unified storage and verification format for all Chio receipt workflows, including checkpoints, evidence export, and federation. The deterministic mapping is defined in the HTTP Substrate page.

Manifest Contract

Tool discovery currently uses the frozen manifest schema chio.manifest.v1. The manifest defines:

• server identity
• one or more tool definitions
• per-tool input and optional output schemas
• operator-facing descriptions and metadata

This manifest is the authoritative discovery contract for native tool servers and for mediated adapters that synthesize a Chio tool tool interface from another protocol.

OpenAPI-Derived Manifests

The v1 contract includes an automated pipeline for deriving chio.manifest.v1 tool definitions from OpenAPI 3.0.x and 3.1.x specifications. Each HTTP operation (method + path pair) becomes one ToolDefinition. Full pipeline: OpenAPI Integration.

When no x-chio-* extensions are present, the pipeline applies a default deny-by-method policy, ensuring fail-closed behavior for undecorated specs. Downstream consumers (the kernel, trust-control, and receipt pipeline) do not distinguish between hand-authored and OpenAPI-derived manifests.

Runtime Surfaces

Local CLI and Kernel

The repository ships these primary runtime entrypoints:

• chio check: single-call policy evaluation in preflight mode, or full mode with an output fixture for post-output guards
• chio run
• chio mcp serve
• chio mcp serve-http
• chio trust serve
• chio receipt explain: reconstruct and explain a stored receipt and its lineage
• chio proof serve: static, read-only Proof Room server over a collected and verified proof bundle
• chio api protect: reverse proxy that enforces Chio policy over an HTTP API using an OpenAPI spec
• chio cert generate: generate a compliance certificate for an ACP session
• chio cert verify: verify a compliance certificate against a trusted kernel key
• chio cert inspect: display a compliance certificate's contents

MCP Compatibility

Chio does not claim to replace MCP. It ships an MCP-compatible mediation layer that currently covers tools, resources, prompts, completions, logging, tasks, progress notifications, nested sampling, elicitation, and roots callbacks, plus remote HTTP auth discovery and hosted authorization-server flows.

Hosted Remote Admin

chio mcp serve-http ships operator-facing admin APIs:

• /admin/health
• /admin/authority
• /admin/sessions
• /admin/sessions/{session_id}/trust
• /admin/receipts/...
• /admin/revocations
• /admin/budgets

Trust-Control Contract

chio trust serve is the shipped trust-control HTTP service. Core operator and cluster endpoints include:

• /health
• /v1/authority
• /v1/capabilities/issue
• /v1/internal/cluster/status
• /v1/receipts/query
• /v1/reports/operator
• /v1/reports/behavioral-feed
• /v1/reports/economic-receipts
• /v1/reports/authorization-context
• /v1/reports/authorization-profile-metadata
• /v1/reports/authorization-review-pack
• /v1/settlements/reconcile
• /v1/federation/evidence-shares
• /v1/reputation/compare/{subject_key}

Federation and certification administration includes endpoints under /v1/federation/providers and /v1/certifications with discovery, transparency, dispute, and revocation paths. The full endpoint list is documented in source.

Version Negotiation

The machine-readable negotiation file is spec/versions/chio-protocol-negotiation.v1.json. See the Wire Protocol page for the full negotiation rules across native, hosted, and trust-control endpoints.

Error Model

The error registry lives at spec/errors/chio-error-registry.v1.json. The eight categories are protocol, auth, capability, guard, budget, tool, internal, and transaction. See the Schemas and Errors page for the complete code table.

Explicit Gaps

The following are intentionally outside the shipped v1 contract and documented explicitly so operators and integrators do not have to infer them from source code:

• permissionless or auto-trusting public federation or certification marketplace semantics
• permissionless mirror/indexer publication as automatic trust, sanction, or market-penalty authority
• public federation beyond Chio's documented bounded federation-activation exchange, quorum, open-admission, reputation-clearing, and qualification surfaces
• portable reputation as a universal trust oracle or automatic cross-issuer score
• automatic enterprise identity propagation into every portable artifact
• custom A2A auth schemes beyond the shipped matrix
• full automatic wallet/distribution semantics for passports
• permissionless or arbitrary external capital dispatch beyond the documented official web3 lane, or autonomous insurer-rate setting beyond the documented autonomous-pricing, capital-pool, rollback, live-capital, reserve-control, payout, and settlement surfaces
• performance claims beyond the qualification and documentation surfaces

Related

• Wire Protocol
• HTTP Substrate
• Bindings API
• Receipt Format
• Schemas and Errors