Exchange

This content is for v1.0. Switch to the latest version for up-to-date documentation.

Every agent action starts with exchange — validate the inbound credential, apply policy, mint a short-lived WIMSE JWT scoped to one audience. That is Starfly’s core job on the fabric.

Why it matters

One front door — Kubernetes, SPIFFE, OIDC, and MCP agent creds all use the same RFC 8693 shape.
Scoped by default — audience at exchange time becomes aud on the JWT; blast radius is chosen up front.
Fast by design — lookup, policy, and sign stay on the hot path; everything else is async.

How it works

Workload credential  →  POST /v1/exchange/token  →  WIMSE JWT
     (inbound)              OPA + validators           (outbound, aud-scoped)

Client sends an RFC 8693 token exchange request.
Starfly identifies credential type (subject_token_type).
Validators check signature, expiry, and trust domain match.
OPA policy allows or denies — see policies/.
Starfly signs a WIMSE JWT with sub, aud, td, exp, and optional delegation claims.

Background work (graph, behavioral profiling, federation relay) runs on NATS consumers — never inside the exchange request.

The latency contract

The exchange path is optimized for sub-millisecond end-to-end latency in production fabrics. Do not add synchronous dependencies (remote calls, blocking I/O) to this pipeline.

Async integrator surfaces — dashboard, graph, UTC — sit beside exchange, not in it.

Dev vs production

Mode	Credential	Policy
`--dev`	Stub JWTs accepted	`policies/dev/` permissive
Production	Real platform credentials	Operator-authored Rego

Key endpoints

Path	Purpose
`POST /v1/exchange/token`	Exchange
`GET /v1/identity/jwks`	Verify issued tokens
`GET /metrics`	`starfly_exchange_*` histograms

Full reference: OpenAPI — exchange.

Try it

make build-dev && ./bin/starfly --dev
./sandbox/run.sh exchange

Integrator walkthrough: token exchange.

Code in this repo

Path	Role
`pkg/exchange/`	Exchange pipeline
`policies/`	OPA Rego bundles