Add API Middleware

Chio's framework middleware asks the kernel about each request before your route handler runs. A refused request returns 403 from inside your service; an admitted one continues with its receipt id attached.

The middleware lives in your application and sends each request to a local Chio evaluator over HTTP. Larkfield's pricing service in FastAPI comes first: refuse a quote, authorize it, and read the three decisions. Then wire the same middleware into your own framework.

1. Start the governed FastAPI service

Starts from chio new pricing-python --example pricing-python, the project Python HTTP Frameworks walks through. Every terminal below starts in its directory.

chio new pricing-python --example pricing-python && cd pricing-python
uv sync
uv run uvicorn fastapi_app:app --host 127.0.0.1 --port 8091

The service listens on port 8091. Its ASGI middleware sends requests to the evaluator on port 9098 and excludes /healthz.

2. Start the evaluator beside it

In a second terminal, start chio api protect on port 9098. The middleware calls it for each decision.

chio --authority-seed-file .pricing/authority.hex api protect \
  --upstream http://127.0.0.1:8091 \
  --spec openapi.yaml --listen 127.0.0.1:9098 \
  --receipt-store .pricing/receipts.db

Chio creates the signing seed and receipt store and reuses them on restart. Send application requests to port 8091, where the middleware intercepts them; port 9098 hosts the evaluator and the local operator endpoints.

3. Read, then watch a quote stop

In a third terminal, check the service's health and read its quotes.

curl -sS -i http://127.0.0.1:8091/healthz

HTTP/1.1 200 OK
content-type: application/json

{"status":"ready","framework":"fastapi"}

curl -sS -i http://127.0.0.1:8091/v1/quotes

HTTP/1.1 200 OK
content-type: application/json
x-chio-receipt: 01a12ef0-d1a4-7c3e-9b7d-5f0c2a61e8b4

{"quotes":[]}

You should see the health check answer directly and the read carry an x-chio-receipt header. Now ask for a quote. POST /v1/quote has side effects, so the middleware refuses it before the quote handler runs.

curl -sS -i http://127.0.0.1:8091/v1/quote \
  -H 'Content-Type: application/json' -d '{"sku":"sku-301","percent":80}'

HTTP/1.1 403 Forbidden
content-type: application/json

{"error":"CapabilityGuard","message":"side-effect route requires a capability token","status":403}

4. Grant a capability and repeat the write

As the local operator, issue the five-minute grant http-grant.json describes for Basalt's buying agent, and keep the capability in this directory.

curl -sS http://127.0.0.1:9098/v1/capabilities/mint \
  -H 'Content-Type: application/json' --data-binary @http-grant.json \
  | jq .capability > capability.json

The grant covers the evaluator's HTTP operation on any route, with no count of quotes. Keep this operator endpoint on loopback; a shared deployment puts it behind its own authenticated control boundary. Send the quote again with the capability.

curl -sS -i http://127.0.0.1:8091/v1/quote \
  -H 'Content-Type: application/json' \
  -H "X-Chio-Capability: $(jq -c . capability.json)" \
  -d '{"sku":"sku-301","percent":80}'

HTTP/1.1 201 Created
content-type: application/json
x-chio-receipt: 01a12ef0-d2f7-7a10-8c44-0e93b5d17a62

{"id":1,"sku":"sku-301","percent":80.0,"price":"28.00","currency":"USD"}

You should see 201 with USD 28.00 and a new receipt id in x-chio-receipt.

5. Read the three decisions

Read the evaluator's store. On a fresh store these requests produce three receipts: the allowed read, the refused quote, and the authorized quote. The health check produces none.

python3 receipts.py

01a12ef0-d1a4-7c3e-9b7d-5f0c2a61e8b4  ALLOW      GET    /v1/quotes  HTTP 200
01a12ef0-d22b-7f06-a1c5-7e48d93b20aa  DENY       POST   /v1/quote  HTTP 403
01a12ef0-d2f7-7a10-8c44-0e93b5d17a62  ALLOW      POST   /v1/quote  HTTP 200

You should see each decision with its route. The authorized quote's row shows HTTP 200 although FastAPI answered 201: the evaluator signs before the handler runs, so the receipt records the admission decision. Pass a receipt id to receipts.py to print the complete signed record; HTTP receipt lookup explains how the HTTP receipt links to its kernel record.

Your state is .pricing/receipts.db, .pricing/authority.hex, and capability.json. Stop both services with Ctrl-C when you finish, and keep the signing seed private. python3 run.py check runs an isolated copy of this flow and shuts down its services.

6. Wire the middleware into your own service

The pricing service runs in five more frameworks against one contract: GET /healthz outside Chio, GET /v1/quotes allowed with a receipt, and POST /v1/quote refused without a capability. Each delegates evaluation to a local evaluator. Add the interception point for your framework.

const app = express();
app.use(chio({ sidecarUrl: process.env.CHIO_SIDECAR_URL ?? 'http://127.0.0.1:9099', skip: ['/healthz'] }));
app.use(express.json());
// ...routes...
app.use(chioErrorHandler);

app.add_middleware(
    ChioASGIMiddleware,
    config=ChioASGIConfig(
        sidecar_url=os.environ.get("CHIO_SIDECAR_URL", "http://127.0.0.1:9098"),
        max_body_bytes=8192,
        exclude_paths=frozenset({"/healthz"}),
        exclude_methods=frozenset(),
    ),
)

	protected := chio.Protect(router, chio.WithSidecarURL(sidecar))

    @Bean
    fun chioFilter() = FilterRegistrationBean<ChioFilter>().apply {
        filter = ChioFilter(ChioFilterConfig(
            sidecarUrl = System.getenv("CHIO_SIDECAR_URL") ?: "http://127.0.0.1:9102"
        ))
        addUrlPatterns("/v1/*")
        order = Ordered.HIGHEST_PRECEDENCE + 1
    }

builder.Services.AddChioProtection(options => {
    options.MaxRequestBodyBytes = 8192;
    options.SidecarUrl = Environment.GetEnvironmentVariable("CHIO_SIDECAR_URL")
        ?? "http://127.0.0.1:9102";
});
var app = builder.Build();
var store = new QuoteStore(".pricing/dotnet-quotes.json");
app.UseWhen(context => context.Request.Path.StartsWithSegments("/v1"), branch => {
    branch.UseChioProtection();
});

You should see your framework's health route answer directly and a quote without a capability return 403. Set the sidecar URL explicitly or supply CHIO_SIDECAR_URL, and give the evaluator your OpenAPI document when you start it. The complete services, with their dependencies and launchers, are on the Node, Python, Go and C++, and JVM and .NET pages.

from fastapi import FastAPI, Request
from chio_fastapi import chio_requires

app = FastAPI()


@app.post("/search")
@chio_requires(server_id="search-srv", tool_name="search_documents")
async def search(request: Request, query: str) -> dict:
    return {"results": run_search(query)}