SDK Overview

Source

This page reflects the SDK manifests in the Chio source. The layout and the two-cores-per-language rule come from sdks/README.md. Every package name, distribution name, version, and runtime floor below renders from the sdks dataset, which reads the package.json, pyproject.toml, go.mod, settings.gradle.kts, Package.swift, CMakeLists.txt, Cargo.toml, and .csproj files under sdks/ at the pinned commit. The worked wiring comes from the applications under examples/, and the Node floor from sdks/typescript/chio-ts/package.json (engines.node). None of these files carry MUST, SHOULD, or MAY: a manifest states what it states, and the normative protocol text lives in the Protocol Reference.

Synopsis

One install line and one entry-point import per language.

Distributions and imports

The distribution name and the import name differ in most ecosystems. These are the exact strings, with the version each manifest declares and the runtime floor it requires.

The Go, JVM, .NET, and Rust rows name a path rather than a registry, so a consuming build resolves them from a clone of the tree. Each declaration below is lifted from the worked example that uses it. Go points the module path at a sibling directory, Gradle substitutes the coordinate from a composite build, and MSBuild references the project file.

module hello-chi

go 1.21

require (
	github.com/backbay-labs/chio/sdks/go/chio-go-http v0.0.0
	github.com/go-chi/chi/v5 v5.2.3
)

require (
	github.com/apapsch/go-jsonmerge/v2 v2.0.0 // indirect
	github.com/google/uuid v1.6.0 // indirect
	github.com/oapi-codegen/runtime v1.2.0 // indirect
)

replace github.com/backbay-labs/chio/sdks/go/chio-go-http => ../../sdks/go/chio-go-http

includeBuild("../../sdks/jvm")

  <ItemGroup>
    <ProjectReference Include="../../sdks/dotnet/ChioMiddleware/src/ChioMiddleware.csproj" />
  </ItemGroup>

One route in every language

The example matrix carries 9 HTTP framework applications, one per framework. Each serves the same three routes behind the same sidecar: GET /healthz excluded from evaluation, GET /hello allowed, and POST /echo refused until the caller presents a capability. The wiring is one call in every language.

from chio_asgi import ChioASGIMiddleware, ChioASGIConfig

# Starlette / FastAPI
app.add_middleware(
    ChioASGIMiddleware,
    config=ChioASGIConfig(sidecar_url="http://127.0.0.1:9090"),
)

  if (enableChio) {
    app.use(
      chio({
        sidecarUrl,
        skip: ["/healthz"],
      }),
    );
  }

func protectedHandler(sidecarURL string) http.Handler {
	return chio.Protect(
		newRouter(),
		chio.WithSidecarURL(sidecarURL),
	)
}

    @Bean
    fun chioFilterRegistration(): FilterRegistrationBean<ChioFilter> {
        val filter = ChioFilter(
            ChioFilterConfig(
                sidecarUrl = System.getenv("CHIO_SIDECAR_URL") ?: "http://127.0.0.1:9090",
            ),
        )

        return FilterRegistrationBean<ChioFilter>().apply {
            setFilter(filter)
            addUrlPatterns("/hello", "/echo")
            order = Ordered.HIGHEST_PRECEDENCE
        }
    }

using Backbay.Chio;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddChioProtection();

var app = builder.Build();
app.UseChioProtection();

app.MapGet("/pets", () => new { pets = Array.Empty<object>() });

app.Run();

What a refusal returns

A refusal is a record. The two middlewares that front an application, the Python ASGI one and the Node interception layer every JavaScript adapter shares, both answer a denied request with a JSON body and a receipt id on a response header.

The ASGI status is the receipt verdict's own HTTP status when it carries one and 403 otherwise. The Node layer sends chio_access_denied on a deny and chio_invalid_receipt with status 502 when the sidecar answers with a receipt that fails verification. Both paths fail closed. Run any of the applications with examples/run-hello-smokes.sh, which starts a trust control plane, the application, and a sidecar, then walks the three routes.

Choose an SDK

Every SDK implements the same invariants. The differences are in the higher layers: framework adapters, orchestrator operators, agent framework integrations, and native server middleware.

Under all six sits the Bindings API, the low-level contract every binding implements: canonical JSON, hashing, signing, receipt and capability and manifest verification, delegation chains, Merkle proofs, and the stable error taxonomy. Read it if you are porting to a new language or writing an offline verifier.

Shared functionality

The four SDKs that carry a client and a session are compared below. Rust provides invariants only. The JVM and .NET SDKs are sidecar clients: they evaluate, verify, and filter HTTP requests, and they open no MCP session.

• Invariants. Pure functions for canonical JSON, SHA-256, Ed25519, and verification of receipts, capabilities, and signed manifests. They make no network call.
• Transport. Streamable HTTP MCP transport with an explicit session lifecycle.
• Client and session. Opening a session against a chio edge and calling tools over it.
• Receipt query. A typed client over GET /v1/receipts/query with pagination. From Go or Rust, call the endpoint directly.
• DPoP proof signing. signDpopProof builds and signs a proof bound to a capability, a tool, and an action-argument hash. The Python sidecar client accepts a caller-supplied dpop_proof on mediated evaluation but constructs none.
• Cognition market. Buyer, seller, and hosted clients for the Finding market, plus the buyer-local bid ceiling.

Platform SDKs

Two integrations govern infrastructure rather than application code. Neither calls the sidecar over POST /chio/evaluate.

• chio-tower. A Rust tower::Layer that wraps any Tower or Axum HTTP service and runs the kernel in process. It exports ChioLayer, ChioService, ChioEvaluator, EvaluationResult, ChioTowerError, extract_identity, IdentityExtractor, DEFAULT_MAX_BODY_BYTES, and the KernelService stack (build_layered, KernelTraceLayer, TenantConcurrencyLimitLayer, TenantId). It fails closed.
• Kubernetes controller and webhooks. The controller watches Jobs labeled chio.world/governed: "true", reads the requested scopes off chio.world/scopes, mints a capability grant at creation, writes chio.world/capability-id, chio.world/capability-token, and chio.world/capability-expires-at onto the pod template, holds the Job with the chio.world/capability-finalizer finalizer, and harvests the chio.world/receipt annotations the sidecar posted. The validating webhook admits a pod only when the token on chio.world/capability-token verifies against the operator's configured trust set, and it denies any pod that carries chio.world/required-scopes or chio.world/exempt, because a workload must not set its own policy. The mutating webhook runs the same verification and emits no patch. A namespaced ChioPolicy custom resource in the chio.world group carries the operator's policy.

Everything under sdks/

Most directories under sdks/ hold one language. Three do not: guard/ holds the WASM guard guest SDKs, which are built out of tree and loaded as components rather than linked as host clients; k8s/ holds the Kubernetes controller, its custom resource, and the admission webhooks; and lambda/ holds the AWS Lambda pair. Every package, module, and project the manifests declare appears below.

C++ and Swift have no reference page of their own. The C++ projects are worked in examples/hello-drogon.

Cross-language conformance

TypeScript, Python, Go, and Rust run the same conformance vectors: canonical JSON, hashing, signature verification, receipt parsing, capability parsing, and manifest parsing. Rust is the reference, and the other three produce byte-identical output against its vectors. The JVM SDK asserts the same byte-equality under a parity JUnit tag on canonical JSON, the DLQ router, and synthetic deny receipts.

Cross-language verification fails when canonical JSON is nonconformant, so every SDK implements the RFC 8785 requirements for key sorting, whitespace, and number formatting. The Bindings API carries that contract in full.

# Run conformance per SDK
$ cd sdks/typescript/chio-ts && npm test
$ cd sdks/python/chio-py && pytest
$ cd sdks/go/chio-go && go test ./...
$ cargo test -p chio-binding-helpers
$ cd sdks/jvm && ./gradlew build --no-daemon

Related

• Python SDK, TypeScript SDK, Go SDK, JVM SDK, .NET SDK, Rust SDK: the per-language references.
• Bindings API: the invariants contract every SDK conforms to.
• CLI Reference: standalone governance of an MCP server without embedding an SDK.
• Receipt Format and Receipt Query API: the data shapes each SDK wraps.
• Python, Node, Go and C++, and JVM and .NET worked applications.