Skip to content
TrustPlane

Brownfield adapter

The fastest way to adopt TrustPlane Auth is to not change your API at all. The brownfield adapter is a reverse proxy that verifies the passport + proof and only forwards verified requests to your existing upstream:

client  ->  trustplane-adapter  ->  existing upstream

You slide a verifier in front of an unmodified service. It is the same shape used for the deployment shape in the deployment guide.

How it works

Section titled “How it works”
  • Binary: cmd/trustplane-adapter, built on pkg/middleware/http and pkg/authcore.
  • On each request it extracts the passport from the Authorization header, verifies it (signature, issuer key resolution, audience, expiry, trust domain, cnf, replay/jti), and enforces route policy from the mounted bundle.
  • On success it forwards to the configured upstream and adds context headers:
    • X-TrustPlane-Subject
    • X-TrustPlane-Issuer
    • X-TrustPlane-Trust-Domain
    • X-TrustPlane-JTI
  • On failure the upstream is never called: 401 for missing passport, 403 for wrong audience, and JSON deny bodies like { "allowed": false, "reason": "..." } for policy/binding failures.
  • Route modes: --route-id (single route) or --route-policy-mode request (derive route_id from the bundle’s method + path_template, enabling one adapter to protect many routes).
sequenceDiagram
  participant C as Client
  participant A as trustplane-adapter
  participant V as authcore verifier
  participant T as Trust bundle + policy
  participant U as Existing upstream

  C->>A: GET /orders + Authorization: Bearer <passport> + proof
  A->>V: Verify passport + transcript-v1 + policy
  V->>T: Resolve issuer key + route source rule
  T-->>V: key + allowed_sources + freshness
  V-->>A: allow
  A->>U: Forward + X-TrustPlane-* headers
  U-->>C: 200 business JSON
  Note over A,U: If verify fails: 401 / 403 / JSON deny — upstream NOT called

Run the adapter demo

Section titled “Run the adapter demo”

Run the local adapter demo — it starts a simple upstream, puts the adapter in front, and proves three outcomes:

Terminal window
make demo-adapter
  1. A valid passport reaches the upstream.
  2. A missing passport returns 401.
  3. A passport with the wrong audience returns 403.

For the richer flow (broker-issued passports, transcript-v1 binding, route_id policy, replay denial, stable deny reasons), use:

Terminal window
make demo-provider-gateway

Protect many routes with one adapter

Section titled “Protect many routes with one adapter”

A multi-route adapter (one adapter, many business routes) uses request mode with a mounted policy bundle:

Terminal window
trustplane-adapter \
  --upstream http://mock-api.acme-demo.svc.cluster.local \
  --policy-bundle /etc/trustplane/trustplane.policy.bundle.json \
  --route-policy-mode request \
  --proof-mode transcript-v1

With the multi-route example bundle, that single adapter protects:

Method Path Route ID
GET /orders acme.demo.orders.read
POST /orders acme.demo.orders.create
GET /invoices acme.demo.invoices.read
GET /customers acme.demo.customers.read

What to notice

Section titled “What to notice”
  • Zero upstream changes. Your service keeps speaking plain HTTP; the adapter handles all verification.
  • The adapter is stable infrastructure: adding clients is a bundle change, not an adapter rebuild or redeploy (see Trust anchors).
  • The same binary that runs in make demo-adapter is the image deployed in the live adapter deployment.

Next steps

Section titled “Next steps”