Skip to main content

Brownfield adapter (the wedge)

Concept​

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

This is "the wedge": you slide a verifier in front of an unmodified service. It is the same shape used for the deployment shape in Deployment overview.

Implementation​

  • 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).

Example​

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

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:

make demo-provider-gateway

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

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:

MethodPathRoute ID
GET/ordersacme.demo.orders.read
POST/ordersacme.demo.orders.create
GET/invoicesacme.demo.invoices.read
GET/customersacme.demo.customers.read

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 wedge.

→ Next: Broker & attested_workload.