Skip to content
TrustPlane

Local development

The fastest way to see TrustPlane Auth work is with a software signing key on your own machine. This is also the smallest cross-organization shape: Acme protects the Orders API, and a caller — a local integration script, a test harness, a partner service — signs each request with a private key. Acme publishes the caller’s public key into trust material and allows that source on the route.

No API key or static bearer token is shared with the caller. The verifier checks a short-lived passport, the transcript-v1 proof, replay state, and route policy.

Install the CLI

Section titled “Install the CLI”

Use the current v0.2.4 CLI archive from Install and artifacts. Download the archive for your platform and verify SHA256SUMS before running trustplane.

Source builds are useful for local development, but start from the released CLI archive when you want the flow below to match these docs.

Step 1 — The caller creates a signing key

Section titled “Step 1 — The caller creates a signing key”
Terminal window
trustplane gen-key

The caller keeps the private key. Acme receives only the public key and a planned subject, such as external:jwks:acme-partner-orders.

Step 2 — Acme adds the source to the Orders route

Section titled “Step 2 — Acme adds the source to the Orders route”
Terminal window
trustplane bundle merge-source \
  --trust-material trust-material.json \
  --policy-bundle trustplane.bundle.json \
  --out-trust-material trust-material.partner.json \
  --out-policy-bundle trustplane.bundle.partner.json \
  --issuer https://issuer.acme.example/external-jwks \
  --trust-domain acme.example.external \
  --kid partner-orders-1 \
  --public-key "$PARTNER_PUBLIC_KEY_B64URL" \
  --route-id acme.orders.read \
  --subject-exact external:jwks:acme-partner-orders \
  --required-key-binding software

The reviewed output is then signed and mounted through the normal bundle process. Existing keys and source rules are preserved unless replacement is explicitly requested.

Step 3 — The caller signs the request

Section titled “Step 3 — The caller signs the request”
Terminal window
trustplane sign \
  --private-key "$PARTNER_PRIVATE_KEY_B64URL" \
  --subject external:jwks:acme-partner-orders \
  --issuer https://issuer.acme.example/external-jwks \
  --trust-domain acme.example.external \
  --method GET \
  --path /orders \
  --audience acme.orders \
  --route-id acme.orders.read \
  --curl

The emitted curl includes the passport and proof headers. The adapter accepts the request only when the signature, audience, route, subject, key binding, freshness, and replay checks pass.

What this proves

Section titled “What this proves”
Result Meaning
Valid signed request allows A configured software/JWKS-style source can call the route without an API key
Wrong audience denies The proof is scoped to the intended API
Wrong method/path denies The proof is bound to the request
Duplicate request denies Replay protection consumed the first presentation
Unknown key or subject denies Route allowed_sources controls which public keys and subjects are accepted

Know the boundary

Section titled “Know the boundary”

This is a software signer. It does not claim hardware-backed signing, cloud-native attestation, or managed enterprise enrollment. It is still useful because the verifier is not accepting a shared bearer secret; it is accepting a request-bound proof from a configured source.

Next steps

Section titled “Next steps”