Gateway integration patterns

You already have a gateway — Gateway API, Envoy, NGINX, or Kong — and you don’t want to replace it to adopt proof-bound verification. You don’t have to. The current v0.1 gateway pattern keeps TrustPlane Auth simple: your gateway keeps placing traffic, and the adapter does the verifying.

flowchart LR
  C["Client or agent"] --> G["Existing gateway or ingress"]
  G --> A["trustplane-adapter"]
  A --> U["Upstream API"]

TrustPlane Auth can protect an API directly through the adapter. Existing gateways can route protected traffic through that adapter, but the adapter remains the verifier and enforcement component. The upstream API remains unchanged and still owns business authorization and RBAC.

One adapter can protect many routes using --route-policy-mode=request. Route policy decides which sources may call which routes; replay state decides whether the proof has already been consumed; signed trust and policy bundles decide which issuers, keys, sources, and freshness rules are trusted.

The protected upstream must not be reachable directly by untrusted callers. If callers can bypass the adapter and hit the upstream, the gateway pattern is not enforcing the boundary. In every pattern below the flow is the same: caller → gateway/ingress → Auth adapter → upstream API, backed at the network layer by Network hardening.

Kubernetes Gateway API / HTTPRoute

Use Gateway API or ingress routing to send protected paths to the adapter Service. The adapter’s upstream points to the internal upstream Service.

Typical shape:

• Protected HTTPRoute paths route to the trustplane-adapter Service.
• The adapter verifies TrustPlane headers, route policy, replay, and source policy.
• The adapter forwards verified requests to the internal upstream Service.
• NetworkPolicy prevents untrusted callers from reaching the upstream Service directly.
• Signed trust and policy bundles are mounted into the adapter, and replay storage matches the adapter replica topology.

This keeps Kubernetes routing responsible for traffic placement while TrustPlane Auth remains responsible for proof-bound request enforcement.

Envoy

For Envoy-fronted APIs, route the protected virtual host or path cluster to the adapter. The adapter forwards to the upstream after local verification.

Typical shape:

• Envoy receives external traffic and matches the protected host or path.
• Envoy routes that traffic to a cluster that points at the adapter.
• The adapter verifies the request and proxies only verified traffic to the upstream cluster or service.
• Direct network access to the upstream is restricted so callers cannot skip the adapter.

Envoy must route protected traffic only to the adapter cluster — never define a route or cluster that reaches the upstream directly; enforce that with Network hardening.

Native Envoy ext_authz verify mode is not currently supported; the v0.1 model routes protected traffic through the adapter.

NGINX

For NGINX-fronted APIs, configure the protected location blocks to proxy to the adapter. The adapter proxies to the upstream after verification.

Typical shape:

• NGINX matches protected locations.
• NGINX proxies those locations to the adapter endpoint.
• The adapter verifies TrustPlane proof, route policy, replay, and source policy.
• The adapter forwards verified requests to the upstream.

NGINX must proxy protected locations only to the adapter — no location or upstream block may reach the protected upstream directly; enforce that with Network hardening.

NGINX auth_request verify endpoint mode is not currently supported; the v0.1 model routes protected traffic through the adapter.

Kong

For Kong-fronted APIs, route the protected Service or Route path to the adapter. The adapter then forwards verified requests to the upstream.

Typical shape:

• Kong matches protected routes.
• The route or service target sends protected traffic to the adapter.
• The adapter verifies locally and forwards to the upstream after enforcement.
• The upstream is not exposed as a separate direct route for untrusted callers.

Kong must send protected routes only to the adapter — never register a Kong Service or Route that targets the upstream directly; enforce that with Network hardening.

A native Kong plugin or serverless pre-function verify mode is not currently supported; the v0.1 model routes protected traffic through the adapter.

Use the current adapter contract

Whatever gateway you use, keep these properties:

• Protected traffic routes through trustplane-adapter.
• The adapter verifies proof-bound requests locally.
• Signed trust and policy bundles define trusted issuers, sources, routes, and freshness.
• Replay protection prevents the same proof from being accepted twice.
• The upstream is reachable only through the protected boundary.
• The upstream keeps business authorization and RBAC.

If a gateway pattern preserves those properties, it fits the TrustPlane Auth v0.1 deployment model.

Advanced integration options

Some teams may eventually want the gateway itself to call a TrustPlane verification service or run a gateway-native extension. Examples include Envoy ext_authz, NGINX auth_request, Kong plugins, backend token exchange, or Control-managed provider onboarding.

Those are useful future integration options, especially for large gateway fleets. The current release keeps the path simpler: route protected traffic through the adapter and keep the adapter as the verifier.

Next steps

• Helm chart — deploy the adapter with signed bundles and replay-safe topology.
• Network hardening — NetworkPolicies and verification checks that make the adapter the only path to the upstream.
• Gateway, certificates, and DNS — stand up the public Auth hostname, certificate, and DNS in front of the gateway.
• Route policy maps — one adapter protecting many routes.