HTTP Substrate

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 sidecar protocol uses a local 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 sidecar protocol 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 signature, content-addressed id, and authority semantics of a previously issued HttpReceipt.

Request body: HttpReceipt.

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

A receipt with a valid signature but an expired timestamp still reports signature_valid: true. 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 sidecar 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.

DenyDetails

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

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, semantic classification, and guard evidence under a signature from the kernel (Ed25519 by default; P-256 and P-384 also supported).

Signing

To produce a signed receipt:

• Construct an HttpReceiptBody containing all fields from the table above except signature.
• Compute the content-addressed id (compute_http_receipt_id) and validate the authority semantics (mediated_decision + prevent + mediated, no observation_outcome).
• Serialize the body to canonical JSON (RFC 8785).
• Sign the canonical bytes with the kernel's private key (Ed25519 by default; P-256 or P-384 when configured).
• 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 and signature reuse the same algorithm-aware chio_core_types::crypto types as the core ChioReceipt (imported directly), so they are not restricted to bare Ed25519 hex:

• kernel_key: bare 64-character lowercase hex for Ed25519, or a p256:<130-hex> / p384:<194-hex> prefixed form.
• signature: bare 128-character lowercase hex for Ed25519, or a p256: / p384: prefixed DER-hex form. Verification dispatches off the self-describing encoding.

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 by design:

• 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 via ChioReceipt::sign(...) with the supplied kernel keypair. The old HTTP signature is never copied.

Field Mapping

Verdict to Decision Mapping

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.
• 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 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, not handwritten examples alone.

Related

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