HTTP Transport

Source

This page normatively reflects spec/HTTP-SUBSTRATE.md in the chio repository. Status: Normative. Version 1.0. The keywords MUST, SHOULD, and MAY are normative per RFC 2119.

Where that document and the code differ, the page follows the crate crates/platform/chio-http-core (evaluation.rs, verdict.rs, receipt.rs) and the sidecar in crates/products/chio-api-protect/src/proxy, which are the normative source for wire behavior.

Synopsis

POST /chio/evaluate   body: ChioHttpRequest   ->  200  EvaluateResponse { verdict, receipt, evidence, execution_nonce? }
POST /chio/verify     body: HttpReceipt       ->  200  VerifyReceiptResponse
GET  /chio/live                               ->  200  HealthResponse { status, version, receipt_backend, revocation_backend }
GET  /chio/health                             ->  200 | 503  HealthResponse

The routes chio-api-protect mounts under /chio, with the request and response types chio-http-core defines.

Overview

A Chio kernel runs as a local process and exposes an HTTP API on localhost. Framework middleware or an SDK intercepts an incoming HTTP request, constructs a ChioHttpRequest, sends it to the sidecar, and enforces the returned verdict. The same types serve the chio api protect reverse proxy, which evaluates the request in-process and forwards it itself.

Sidecar evaluation protocol

Transport

The sidecar MUST listen on 127.0.0.1:9090 by default; that is the default of the --listen flag of chio api protect. Implementations MAY override the sidecar URL via:

• An explicit configuration value (sidecarUrl in SDK config, or equivalent)
• The CHIO_SIDECAR_URL environment variable

If both are set, the explicit configuration value takes precedence. If neither is set, the default http://127.0.0.1:9090 MUST be used. All request and response bodies MUST use Content-Type: application/json.

Endpoints

The sidecar also mounts the approval routes under /approvals and the SDK helper routes under /v1, behind the sidecar-control token where noted in crates/products/chio-api-protect/src/proxy/router.rs. Those routes are outside this protocol.

POST /chio/evaluate

Evaluates an HTTP request against the loaded policy and returns a signed receipt. The sidecar reads at most 10 MiB of request body, decodes it as a ChioHttpRequest, and records the receipt before answering.

Request body: ChioHttpRequest.

Response body: EvaluateResponse.

Status codes:

• 200 OK. Evaluation completed, for every verdict, including a deny for a revoked capability. The verdict field carries the outcome.
• 400 Bad Request, "error": "chio_bad_request". The body could not be read or does not decode as a ChioHttpRequest.
• 409 Conflict, "error": "chio_approval_required". The route is approval-gated and the decision is pending; the body carries kernel_receipt_id and, when the sidecar holds an approval handle, approval_id and resume_path.
• 500 Internal Server Error, "error": "chio_evaluation_failed" for any other evaluation error, or "error": "chio_receipt_persistence_failed" when the receipt could not be recorded.

POST /chio/verify

Verifies the signature, content-addressed id, and authority semantics of a previously issued HttpReceipt. The sidecar reads at most 1 MiB of body and answers 400 chio_bad_request when the body does not decode as an HttpReceipt.

Request body: HttpReceipt.

Response body: VerifyReceiptResponse. There is no single valid field; the response decomposes verification into these fields:

No field reads timestamp. A receipt with a valid signature but an expired timestamp still reports signature_valid: true; temporal validity is the caller's responsibility.

GET /chio/live and GET /chio/health

Both routes answer with a HealthResponse. Liveness is process-only: it reports healthy and empty backend fields while the process runs, so a dependency fault does not restart a container that is serving. Readiness consults the proxy state.

Status codes on /chio/health: 200 OK when healthy; 503 Service Unavailable when degraded or unhealthy. The sidecar reports unhealthy when its durable receipt store is no longer reachable, because every mediated call would then be denied fail closed.

Timeout and failure behavior

SDKs MUST implement a configurable timeout for sidecar calls. The default timeout SHOULD be 5000 milliseconds; the TypeScript node-http package defaults timeoutMs to 5000.

Sequence

ChioHttpRequest

The protocol-agnostic HTTP request that Chio evaluates. It is the shared input type for every HTTP adapter: reverse proxy, framework middleware, and sidecar alike. The fields in this table are the ones the specification defines.

Sidecar-only fields

The crate carries further optional fields that the schema file does not list. Each is omitted from the wire when absent.

Content hash computation

The content hash that binds a request to its receipt is computed as the SHA-256 hex digest of the canonical JSON (RFC 8785) of the following binding object, which ChioHttpRequest::content_hash serializes from the RequestContentBinding struct:

{
  "body_hash": "<body_hash or null>",
  "method": "<HTTP method>",
  "path": "<actual path>",
  "query": { "<sorted query params>" },
  "route_pattern": "<route pattern>"
}

CallerIdentity

The identity of the caller as extracted from the HTTP request.

Identity hash: the caller_identity_hash in receipts is the SHA-256 hex digest of the canonical JSON representation of the full CallerIdentity object (CallerIdentity::identity_hash). The same identity MUST always produce the same hash.

AuthMethod

A tagged union representing how the caller authenticated. The discriminator field is method. Variant names use snake_case.

The specification's Bearer example, with a placeholder hash:

{
  "method": "bearer",
  "token_hash": "a1b2c3d4e5f6..."
}

The Anonymous example:

{
  "method": "anonymous"
}

SessionContext

Per-session context carried through the Chio HTTP guard pipeline. A session groups related requests from the same caller over a bounded time window.

Verdict

Internally tagged with "verdict" as the tag key and snake_case variant names.

When deserializing a deny verdict without an explicit http_status field, implementations MUST default to 403; the crate does this through a serde default. The specification's examples:

{ "verdict": "allow" }

{
  "verdict": "deny",
  "reason": "side-effect route requires a capability token",
  "guard": "CapabilityGuard",
  "http_status": 403
}

That deny is the one the HTTP authority emits for a deny-by-default route with no capability presented; an invalid capability yields a deny from the same guard with the validation failure as reason.

DenyDetails

A deny verdict carries an optional boxed DenyDetails block so a sidecar can tell an SDK what scope was required and what scope was granted. Every field is optional; the whole details key is omitted from the wire when all fields are empty.

HttpMethod

Serialized as uppercase strings. HttpMethod::is_safe names the first column and requires_capability is its negation.

Safe methods (GET, HEAD, OPTIONS) are treated as side-effect-free by default and receive session-scoped allow verdicts. Unsafe methods (POST, PUT, PATCH, DELETE) require an explicit capability grant.

GuardEvidence

The same GuardEvidence type the core receipt carries. The HTTP authority emits entries named DefaultPolicyGuard for a session-scoped allow and CapabilityGuard for a capability decision.

HttpReceipt

A signed receipt proving that an HTTP request was evaluated by the Chio kernel. The receipt binds the request identity, route, method, verdict, semantic classification, and guard evidence under a signature from the kernel (Ed25519 by default; P-256 and P-384 also supported). The Required column reads the serde attributes: a field with a skip rule is omitted from the wire at its default.

Signing

HttpReceipt::sign(body, keypair) produces a signed receipt in this order:

1. Construct an HttpReceiptBody containing every field in the table except signature.
2. Compute the content-addressed id (compute_http_receipt_id) and overwrite the body's id with it.
3. Validate the authority semantics: mediated_decision, prevent, no observation_outcome, mediated. Any other shape is an error.
4. Serialize the body to canonical JSON (RFC 8785) and sign the canonical bytes with the kernel's private key (Ed25519 by default; P-256 or P-384 when configured).
5. Attach the resulting signature to the receipt.

Verification

HttpReceipt::verify_signature returns false at the first failing step:

1. Extract the body (all fields except signature) and validate the authority semantics.
2. Recompute the content-addressed id and compare it with id.
3. Serialize the body to canonical JSON (RFC 8785) and verify the signature against the canonical bytes using the kernel_key embedded in the receipt.

Implementations SHOULD verify the receipt signature before treating receipt content as authoritative.

Cryptographic representations

kernel_key and signature reuse the algorithm-aware chio_core_types::crypto types of the core ChioReceipt, so they are not restricted to bare Ed25519 hex:

• kernel_key: bare 64-character lowercase hex for Ed25519, p256:<130-hex> (uncompressed SEC1), or p384:<194-hex>.
• signature: bare 128-character lowercase hex for Ed25519, or a p256: or p384: prefixed DER hex form. Verification dispatches on the prefix.

HttpReceipt to ChioReceipt mapping

An HttpReceipt maps into the core ChioReceipt type for unified storage and querying. There are two methods, and the no-argument one fails closed:

• to_chio_receipt() (no argument) always returns an error ("cannot convert HttpReceipt into signed ChioReceipt without the kernel keypair"), because a copied HTTP signature would not verify over the ChioReceiptBody.
• to_chio_receipt_with_keypair(keypair) builds the ChioReceiptBody, recomputes content_hash over that canonical body, and re-signs through ChioReceipt::sign(...) with the supplied kernel keypair. The HTTP signature is never copied.

Field mapping

Verdict to Decision mapping

The reverse mapping, Verdict::from(Decision), restores a deny with http_status 403 and empty details.

Conversion re-signs or fails closed

Use to_chio_receipt_with_keypair(keypair) for conversion. It recomputes content_hash over the canonical ChioReceiptBody and re-signs with the kernel keypair, producing a ChioReceipt whose signature and action.parameter_hash verify, so a durable receipt store accepts it.

Default policy semantics

The HTTP sidecar protocol defines default policy behavior based on HTTP method safety:

• Safe methods (GET, HEAD, OPTIONS): session-scoped allow, recorded as a passing DefaultPolicyGuard evidence entry.
• Unsafe methods (POST, PUT, PATCH, DELETE): deny by default. These methods require a capability token presented in the X-Chio-Capability request header, the chio_capability query parameter, or capability_id in the ChioHttpRequest.

When a route is not matched in the loaded policy, the evaluator MUST fall back to method-based default policy. The reverse proxy then records the raw path as route_pattern.

Error handling

Sidecar error codes

SDKs MUST use the following error codes when communicating sidecar failures to callers. The TypeScript node-http package exports these five and one more, chio_sidecar_unavailable, as ChioErrorCode; it classifies a verify response of 408, 404, 429, or 5xx under that code.

The sidecar itself answers with these codes in its own JSON error bodies:

Structured error response

When middleware denies a request, the response body SHOULD be a structured JSON object. The reverse proxy's 403 body carries all four fields and repeats the receipt id in an X-Chio-Receipt-Id header.

Schemas and conformance

Versioned HTTP sidecar schemas live under spec/schemas/chio-http/v1/. Schema files in that directory are the machine-readable contract for the HTTP sidecar types. Implementations MUST serialize all HTTP sidecar types in a form accepted by those schemas. Schema validation SHOULD be exercised against live Rust serialization and never against handwritten examples alone.

The directory holds 15 schema files; the schema registry lists 0 of them. The table names every file with the title it declares.

evaluate-request.schema.json is a reference to chio-http-request.schema.json. The session, stream, error-envelope, and hosted-finding schemas describe the chio-http edge and the hosted finding API, which this page does not cover.

Related

• Wire Protocol: the agent-to-kernel wire format and the hosted MCP session transport.
• Protocol Reference: the capability and receipt contract the HTTP types build on.
• OpenAPI Integration: the chio api protect flags, the OpenAPI conversion, and the proxy's status mapping.
• Protect an API: running the proxy in front of an upstream.
• Schemas and Errors: the schema registry and the error registry.