Architecture overview

Long-lived bearer tokens are the weak point of most machine-to-machine auth: steal one and you can replay it anywhere. TrustPlane Auth is a standalone auth plane for proof-bound machine authorization — it protects APIs by issuing short-lived passports and verifying them locally at services, adapters, gateways, or middleware, so no long-lived shared secret ever crosses the wire.

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 TrustPlane Auth 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

How a request flows

flowchart LR
  W["Workload or agent"] -->|"request + passport + proof"| E["Enforcement point"]
  E --> V["Verifier (authcore + proof)"]
  V --> TM["Trust material"]
  TM --> B["TrustPlane bundle"]
  TM --> J["JWKS endpoint (planned)"]
  TM --> S["SPIFFE-compatible bundle"]
  V -->|"allow / deny"| E
  E -->|"verified request"| API["Protected API"]
  IDP["Identity provider"] --> I["Issuer / Broker"]
  I -->|"short-lived passport"| W

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

sequenceDiagram
  participant C as Caller
  participant I as Issuer / Broker
  participant A as Adapter / Gateway
  participant T as Trust material
  participant U as Upstream API

  C->>I: Request short-lived passport from workload identity
  I-->>C: TrustPlane Passport (+ transcript-v1 proof)
  C->>A: API request + passport + proof
  A->>T: Resolve issuer public key + route policy
  T-->>A: Public key / bundle entry
  A->>A: Verify signature, audience, expiry, trust domain, cnf, binding, replay
  A->>U: Forward verified request
  U-->>C: API response

No long-lived bearer token ever crosses the wire. The verifier checks a short-lived, audience-bound, proof-bound artifact.

Deploy on Kubernetes

flowchart TB
  subgraph K["Kubernetes cluster"]
    W["Workload pod (+ broker sidecar)"] --> GW["Adapter / Gateway"]
    GW --> API["Protected service"]
    SPIRE["SPIRE agent/server"] --> W
    GW --> B["Bundle / JWKS cache"]
  end

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.

Deploy outside Kubernetes

flowchart LR
  P["Local process / VM / edge / EC2"] --> A["trustplane-adapter"]
  A --> API["Existing upstream API"]
  I["Local or OIDC issuer"] --> P
  A --> T["Local bundle / JWKS cache"]

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.

For a caller-by-caller map across local software, EC2-style software, same-cluster SPIFFE/SPIRE, and external automation, see the Use cases overview.

What TrustPlane Auth does (and doesn’t)

flowchart LR
  subgraph Auth["TrustPlane Auth"]
    direction TB
    RT["Runtime: issue / verify / enforce"]
    LB["Local trust material + policy bundles"]
  end
  RT --> LB

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)

• core must 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 steps

• Contracts — the exact data contracts behind every component.
• Security model — the threat model and trust tiers.
• Adoption path — growing from one adapter to fleet management.