Skip to main content

Quickstart

This gets you from local TrustPlane Auth binaries to a verified, proof-bound request in a few minutes — all local, no Docker, no cloud, no hosted services.

Private preview artifact posture

v0.1.0-rc.1 is available as a private preview pre-release. CLI archives are publicly downloadable from downloads.auth.trustplane.dev and require checksum verification. Container images are digest-pinned, and the Helm OCI chart version is 0.1.0-rc.1. See Install & artifacts.

Prerequisites​

  • Go 1.22+ (the runtime is written in Go).
  • A POSIX shell (macOS/Linux). The demos use Unix domain sockets.
  • Either a verified trustplane private preview CLI archive or local access to the pre-release TrustPlane Auth source tree.

1. Prepare the CLI and binaries​

Use the publicly downloadable private-preview CLI archive from Install & artifacts, or build from a pre-release TrustPlane Auth source tree:

make build

This produces three binaries in bin/:

BinaryWhat it is
bin/trustplaneThe CLI (issue, verify, bundle, broker, up, demo)
bin/trustplane-adapterThe brownfield reverse-proxy verifier
bin/trustplane-brokerThe local broker (issues request-bound passports)

2. Run the demos (fastest way to see it work)​

Each make target is a self-contained, local demonstration:

make demo                 # issue + verify a passport, run the protected-service example
make demo-bundle          # resolve issuer keys from a local TrustPlane bundle
make demo-adapter         # brownfield adapter: valid allows, missing=401, wrong-aud=403
make demo-provider-gateway  # the full story: broker + transcript-v1 + replay + deny reasons

The demo-provider-gateway target is the one to watch — it starts a local software-signer broker, writes a local trust bundle and a trustplane-bundle-v1 policy bundle, starts the transcript-v1 adapter, and then proves: a valid call allows, a duplicate is denied (jti_replay), a wrong path/nonce/route is denied (request_binding_mismatch), a missing route policy is denied, and a stale bundle fails closed.

3. Issue and verify a passport by hand​

Issue a short-lived passport (this also writes a trust bundle with the public key):

./bin/trustplane issue \
  --subject spiffe://example.local/ns/default/sa/demo \
  --audience example-api \
  --trust-domain example.local \
  --bundle-out trustplane-bundle.json

Verify it using the bundle (no online lookup needed):

./bin/trustplane verify \
  --token "$TOKEN" \
  --bundle trustplane-bundle.json \
  --kid "$KEY_ID" \
  --issuer "$ISSUER" \
  --audience example-api \
  --trust-domain example.local

You just did secretless verification: the verifier only used a public bundle, never a shared secret.

4. Run the local broker + adapter together (trustplane up)​

trustplane up is the one-command local orchestrator. It starts a software-signer broker over a Unix socket, writes local bundle files, and starts a transcript-v1 adapter with in-memory replay and bundle-policy enforcement. It is the easiest way to experiment with the full pipeline.

./bin/trustplane up

trustplane up is developer/demo orchestration only. It does not deploy to Kubernetes, use a hardware/KMS signer, or deploy to a cluster. For a live deployment, see Deployment overview.

5. Run the v0.1 acceptance gate​

This is the canonical "is the local Auth Plane behaving correctly?" check. It is deterministic and local-only:

make v01-acceptance

It exercises broker-issued headers through the adapter, no-broker trustplane sign headers, wrong-route denial, duplicate-replay denial, stale-bundle fail-closed, insufficient-key-binding denial, request-binding tamper denial, and transcript conformance. See the Acceptance gate tutorial for a walkthrough.

Where to go next​