Skip to content
TrustPlane

Run the local flow

The fastest way to understand TrustPlane Auth is to watch it deny the right things. Start with the first local protected request: its released-CLI fixture executes the request flow and checks each result. The source-build commands below are additional development exercises for passport issuance, transcript-v1 binding, adapter verification, replay denial, and route policy.

New here? Read What is TrustPlane Auth? first for the short product story, then come back to run the local flow.

Prerequisites

Section titled “Prerequisites”

Using a verified CLI archive for the first local protected request:

  • A POSIX shell (macOS/Linux). The demos use Unix domain sockets.
  • A verified trustplane CLI archive and Python 3 — start with Install and verify if you have not downloaded and verified it yet.
  • No Go toolchain is required for the archive path.

Building from a source checkout instead:

  • Go 1.22+ (the runtime is written in Go).
  • A local TrustPlane Auth source checkout (make build produces the binaries).

Prepare the CLI and binaries

Section titled “Prepare the CLI and binaries”

Use a verified CLI archive from Install and verify, or build from a TrustPlane Auth source checkout:

Terminal window
make build

This produces three binaries in bin/:

Binary What it is
bin/trustplane The CLI (issue, verify, bundle, broker, up, demo)
bin/trustplane-adapter The brownfield reverse-proxy verifier
bin/trustplane-broker The local broker (issues request-bound passports)

If you installed from an archive, the first check is:

Terminal window
trustplane --help

Run the demos (fastest way to see it work)

Section titled “Run the demos (fastest way to see it work)”

From a source checkout, each make target is a self-contained, local demonstration:

Terminal window
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.

Issue and verify a passport by hand

Section titled “Issue and verify a passport by hand”

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

Terminal window
./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):

Terminal window
./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.

Run the local broker and adapter together (trustplane up)

Section titled “Run the local broker and 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.

Terminal window
./bin/trustplane up

Run the v0.1 acceptance gate

Section titled “Run the v0.1 acceptance gate”

This is the canonical “is the local TrustPlane Auth runtime behaving correctly?” check. It is deterministic and local-only:

Terminal window
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 guide for a walkthrough.

Next steps

Section titled “Next steps”