Architecture overview
TrustPlane Auth is a standalone auth plane for proof-bound machine authorization. It protects APIs without long-lived bearer tokens by issuing short-lived passports and verifying them locally at services, adapters, gateways, or middleware.
Design goals
- Make API requests verifiable without long-lived shared secrets.
- Keep verification local-first and provider-neutral.
- Support Kubernetes and non-Kubernetes runtimes.
- Compose with SPIFFE/SPIRE, OIDC/JWT, TrustPlane-native issuers, gateways, and middleware.
- Keep the core minimal while allowing external proof kinds and integrations.
The components
These are the public runtime components documented by TrustPlane Auth:
| Component | Path | Purpose |
|---|---|---|
| authcore | pkg/authcore | Passport verification primitives, replay interfaces, key resolution, signer taxonomy, trust-bundle parsing |
| proof | pkg/proof | The transcript-v1 request-binding builder/verifier |
| bundle | pkg/bundle | Build (trustplane-bundle-v1) and non-destructive merge of trust material + policy |
| audit | pkg/audit | The trustplane-auth-audit-event-v0.1 decision event schema |
| http middleware | pkg/middleware/http | Verifier-forwarding HTTP adapter primitives |
| CLI | cmd/trustplane-cli → trustplane | The only OSS CLI: issue, verify, bundle, broker, up, demo |
| Adapter | cmd/trustplane-adapter | Brownfield reverse-proxy verifier (the "wedge") |
| Broker | cmd/trustplane-broker + internal/broker | Issues request-bound passports; software signer + SPIFFE/SPIRE source |
| Issuer / Verifier | cmd/trustplane-issuer, cmd/trustplane-verifier | Local issuer/verifier binaries |
High-level flow
The enforcement point can be application middleware, the brownfield adapter, an API gateway, a service gateway, a sidecar, or a local verifier. They all use the same passport, proof, proof-kind, and trust-material contracts.
Tokenless, secretless protection (the sequence)
No long-lived bearer token ever crosses the wire. The verifier checks a short-lived, audience-bound, proof-bound artifact.
Kubernetes deployment shape
Kubernetes is a first-class target, not a requirement. SPIFFE/SPIRE is the recommended
production identity integration for CNCF-native environments, supplying the X.509-SVID the broker
verifies for attested_workload.
Non-Kubernetes deployment shape
Non-Kubernetes callers (for example an EC2/JWKS-style software source) sign requests with a software key; the adapter accepts them when local trust material and route policy match. See the Security model for what that does and does not prove.
Scope: what TrustPlane Auth does (and doesn't)
TrustPlane Auth is the runtime: it issues passports, verifies proof-bound requests, and
enforces route policy from local trust material and policy bundles. Those bundles are local
files you produce by hand or with trustplane bundle build and merge-source.
Out of scope for this runtime, so the claims stay honest:
- Persistent principal records — Auth makes a per-request decision and remembers no caller state.
- Managed signing, bundle distribution, or revocation feeds — bundles are mounted local files.
- Approval workflows and lifecycle management.
Design rules (the invariants)
coremust work independently.- Verification must be possible from local trust material.
- SPIFFE-compatible must not mean SPIFFE-required.
- Kubernetes-compatible must not mean Kubernetes-required.
- External proof kinds must plug in without changing the core passport contract.
- Private keys stay with issuers/brokers/key managers; verifiers consume only public trust material.
- API protection must not require long-lived shared tokens.
Next: the exact data contracts → Contracts.