HTTP Substrate

The HTTP substrate enables Chio to protect arbitrary HTTP APIs by evaluating requests against policy, signing receipts, and returning structured verdicts. It is the foundation that all HTTP-layer SDKs, middleware crates, and sidecar deployments consume.

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.

Overview

The HTTP substrate uses a sidecar evaluation model: a Chio kernel runs as a local process and exposes an HTTP API on localhost. Language-specific middleware (Express, Actix, Axum, etc.) intercepts incoming HTTP requests, constructs a ChioHttpRequest, sends it to the sidecar, and enforces the returned verdict.

The substrate defines:

• A sidecar evaluation protocol (three HTTP endpoints)
• A typed request model (ChioHttpRequest) for policy evaluation
• A typed receipt model (HttpReceipt) for signed proof of evaluation
• Supporting types for caller identity, authentication, sessions, and verdicts
• A deterministic mapping from HttpReceipt to the core ChioReceipt type

Sidecar Evaluation Protocol

Transport

The sidecar MUST listen on 127.0.0.1:9090 by default. 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

POST /chio/evaluate

Evaluates an HTTP request against the loaded policy and returns a signed receipt.

Request body: ChioHttpRequest.

Response body: EvaluateResponse.

Status codes:

• 200 OK. Evaluation completed (regardless of verdict). The verdict field indicates whether the request was allowed or denied.
• 400 Bad Request. The request body is malformed or missing required fields.
• 500 Internal Server Error. The sidecar encountered an internal error during evaluation.

POST /chio/verify

Verifies the Ed25519 signature on a previously issued HttpReceipt.

Request body: HttpReceipt.

Response body:

A receipt with a valid signature but an expired timestamp is still valid: true from the verification endpoint's perspective. Temporal validity is the caller's responsibility.

GET /chio/health

Status codes: 200 OK if healthy or degraded; 503 Service Unavailable if unhealthy.

Timeout and Failure Behavior

SDKs MUST implement a configurable timeout for sidecar calls. The default timeout SHOULD be 5000 milliseconds.

ChioHttpRequest

The protocol-agnostic HTTP request that Chio evaluates. This is the shared input type for all HTTP substrate adapters (reverse proxy, framework middleware, and sidecar alike).

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:

{
  "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. 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.

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

SessionContext

Per-session context carried through the Chio HTTP 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.

HttpMethod

Serialized as uppercase strings.

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

GuardEvidence

HttpReceipt

A signed receipt proving that an HTTP request was evaluated by the Chio kernel. The receipt binds the request identity, route, method, verdict, and guard evidence under an Ed25519 signature from the kernel.

Signing

To produce a signed receipt:

• Construct an HttpReceiptBody containing all fields from the table above except signature.
• Serialize the body to canonical JSON (RFC 8785).
• Sign the canonical bytes with the kernel's Ed25519 private key.
• Attach the resulting signature to the receipt.

Verification

• Extract the body (all fields except signature).
• Serialize the body to canonical JSON (RFC 8785).
• 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: Ed25519 public key as 64-character lowercase hex (32 bytes). Pattern: ^[0-9a-f]{64}$.
• signature: Ed25519 signature as 128-character lowercase hex (64 bytes). Pattern: ^[0-9a-f]{128}$.

HttpReceipt to ChioReceipt Mapping

The to_chio_receipt() conversion maps an HTTP-layer receipt into the core ChioReceipt type for unified storage and cross-surface querying.

Field Mapping

Verdict to Decision Mapping

Signature Limitation

In production deployments, the kernel SHOULD sign both HttpReceipt and ChioReceipt independently from the same evaluation, rather than relying on the conversion method.

Default Policy Semantics

The HTTP substrate defines default policy behavior based on HTTP method safety:

• Safe methods (GET, HEAD, OPTIONS): Session-scoped allow.
• Unsafe methods (POST, PUT, PATCH, DELETE): Deny by default. These methods require an explicit capability token presented in the X-Chio-Capability request header or via 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.

Error Handling

Sidecar Error Codes

SDKs MUST use the following error codes when communicating sidecar failures to callers:

Structured Error Response

When middleware denies a request, the response body SHOULD be a structured JSON object:

Schemas and Conformance

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

Related

• Wire Protocol
• Protocol Reference
• Protect an API
• OpenAPI Integration