Protocol Reference

The repository-wide protocol profile for the shipped Chio release. Capability-scoped mediation, signed receipts, manifest discovery, and the trust-control HTTP service share one contract across native, hosted, and HTTP substrate surfaces.

When to use this page

Use this page when: you need the canonical contract that every Chio surface shares, capability and receipt field tables, decision and provenance enums, and the launch-candidate safety property inventory. Don't use this if: you want frame-level wire details (see Wire Protocol) or the HTTP substrate sidecar contract (see HTTP Substrate).

Source

This page normatively reflects spec/PROTOCOL.md in the chio repository. Status: Current bounded Chio release profile. Version 3.0. v3.0 is a backward-compatible extension of v2.0; all v2 artifacts, wire formats, and verification rules remain valid. v3 adds the HTTP substrate, OpenAPI integration pipeline, and supporting CLI surfaces without changing existing contract semantics.

Purpose

Chio is a capability-scoped mediation and evidence system for agent tool use. 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-manifest, negotiation, and qualification artifacts
portable trust artifacts for did:chio, schema issuance, presentation, evidence export, and certification

Compatibility

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

Components and Trust Boundaries

Component	Role
Agent	Untrusted caller that presents a capability or authenticates to a hosted edge
Kernel	Trusted enforcement layer that validates capabilities, runs guards, dispatches calls, and signs receipts
Tool server	Native or wrapped implementation of tools/resources/prompts
Trust-control	Operator-facing authority, receipt, revocation, budget, federation, and certification service
Hosted MCP edge	`chio mcp serve-http`, exposes an MCP-compatible HTTP surface with remote session lifecycle and admin APIs
Operator stores	SQLite stores and file-backed registries for authoritative local state

The security boundary that matters is constant across these surfaces:

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 seams and must still preserve local policy activation plus signed Chio truth
registry and artifact mismatches fail closed instead of degrading silently

Serialization and Identity

Canonical JSON

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

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 primitive. did:chio is the shipped self-certifying DID method:

text

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. Capability tokens do not carry a schema field today. The signed body is:

Field	Meaning
`id`	Stable capability identifier used for revocation
`issuer`	Ed25519 public key of the authority or delegating issuer
`subject`	Ed25519 public key bound to the caller
`scope`	Tool, resource, and prompt grants
`issued_at`	Unix timestamp seconds
`expires_at`	Unix timestamp seconds
`delegation_chain`	Ordered chain of delegation links

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 surface includes ordinary argument constraints plus governed-transaction controls such as governed_intent_required, require_approval_above, and seller_exact.

Governed Transaction Extensions

Tool-call requests may attach two optional governed artifacts:

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 artifact 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 artifacts such as chio.session_anchor.v1, chio.receipt_lineage_statement.v1, or chio.call_chain_continuation.v1

Verification Rules

The kernel and trust surfaces 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:

ID	Property
P1	Capability attenuation: supported delegated capability issuance can only narrow scope relative to the issuing parent
P2	Presented revocation coverage: a revoked capability or revoked presented delegation ancestor ID is denied
P3	Fail-closed evaluation: verification or policy failures deny or reject rather than widening access
P4	Receipt integrity: signed receipts and checkpoints remain verifiable as evidence artifacts
P5	Presented delegation-chain structural validity: depth, connectivity, and timestamp monotonicity
P6	Local parent-link soundness: an observed local parent edge implies the parent request existed in the same authenticated session
P7	Receipt-lineage soundness: a verified receipt edge implies both receipts verify and the linkage was signed by a trusted kernel
P8	Session continuity soundness: continued provenance can only claim session continuity through a valid session anchor and continuation artifact
P9	Delegation/provenance consistency: verified call-chain subjects and parent capability references remain consistent with capability lineage
P10	Report truthfulness: enterprise/report/export surfaces never label asserted lineage as verified

Receipt Contract

The shipped receipt envelope is ChioReceipt.

Field	Meaning
`id`	Stable receipt identifier
`timestamp`	Unix timestamp seconds
`capability_id`	Capability exercised or presented
`tool_server`	Target server id
`tool_name`	Target tool
`action`	Canonicalized tool parameters plus `parameter_hash`
`decision`	`allow`, `deny`, `cancelled`, or `incomplete`
`content_hash`	Hash of the evaluated content or outcome payload
`policy_hash`	Hash of the policy material used
`evidence`	Per-guard evidence
`metadata`	Optional structured metadata
`kernel_key`	Verifying public key
`signature`	Ed25519 signature

Decisions

The decision enum is part of the contract:

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 Artifacts

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 surfaces. Those proofs support audit and transparency_preview claims only.

HTTP Receipts

The HTTP substrate 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 surface from another protocol.

OpenAPI-Derived Manifests

Chio v3 adds 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
chio run
chio mcp serve
chio mcp serve-http
chio trust serve
chio api protect: reverse proxy that enforces Chio policy over an HTTP API using an OpenAPI spec
chio cert generate: generate TLS or signing certificates
chio cert verify: verify a certificate chain or signing material
chio cert inspect: display certificate metadata, expiry, and key bindings

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 surfaces 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 surface is documented in source.

Version Negotiation

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

Error Model

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

Explicit Gaps

The following are intentionally outside the shipped v3 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
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
performance claims beyond the qualification and documentation surfaces