Developer smoke: local protected request

This optional developer exercise uses the checksum-verified v0.2.5 CLI archive and the versioned local fixture v0.1.3. It starts a software-signer broker, adapter, and synthetic upstream on disposable localhost ports. The CLI’s startup sample headers are captured in a mode-restricted temporary log; fresh request headers stay in the fixture process’s memory. The temporary directory is removed on exit. It creates no Control Auth Site or Control Audit record.

Two separate versions

v0.1.3 names only this tutorial’s downloadable run.py helper. The TrustPlane CLI used by the helper is v0.2.5; the Auth adapter, Helm chart, and SDKs have their own release numbers. The fixture’s manifest records its source tag, script hash, and tested CLI platform.

Before you run

1. Follow Install and verify for your macOS or Linux archive. Check SHA256SUMS before unpacking it; run ./trustplane --help. The fixture’s executed check was on the macOS arm64 archive. Other archive targets are listed, but were not executed here.

2. Have Python 3 available. The script uses only the standard library and needs permission to create localhost TCP and Unix sockets.

3. Download the exact fixture release and its SHA256SUMS, then check the script before running it. The versioned release manifest records the source tag and expected hash:

   Use the exact .txt checksum filename shown below.

curl -fsSLO https://docs.auth.trustplane.dev/examples/local-first-request/v0.1.3/run.py
curl -fsSLO https://docs.auth.trustplane.dev/examples/local-first-request/v0.1.3/SHA256SUMS.txt
shasum -a 256 -c SHA256SUMS.txt
python3 run.py --version

Run it with the verified CLI binary:

python3 run.py --cli ./trustplane

For a narrated terminal walkthrough, use python3 run.py --walkthrough --cli ./trustplane. That mode displays the safe trustplane up and broker issue command templates, each HTTP method/path and its purpose, and pauses between real calls. It does not display the JWT, proof, or private startup log. The default mode remains suitable for automated checks.

The script runs the same commands described here: trustplane up starts the local services, then trustplane broker issue makes short-lived headers for an exact GET /orders. It sends an unsigned request, the signed request, its exact replay, and a fresh signature sent to a changed path. The script checks status and denial reason without printing the bearer token or proof headers.

Expected result

unsigned: HTTP 401; reason=missing_bearer_token
signed: HTTP 200; upstream=local-demo
replay: HTTP 403; reason=jti_replay
changed path: HTTP 403; reason=request_binding_mismatch
PASS: local protected request, replay, and path binding

These lines came from a real run of the checked macOS arm64 v0.2.5 archive. A 403 alone is not evidence of a valid signature; the changed-path reason and fresh broker issue show which check rejected the request. The allowed 200 comes from the synthetic upstream through the adapter. Stop if the script reports a different status or reason rather than editing the expected output.

The local bundles are generated for the demo and do not model managed Control distribution, signed publication, durable replay, an offline lease, or Control Audit. Continue to the managed Auth Site guide when you have the account, capacity, trust root, and cluster inputs it lists.