Verify a Pipelock Receipt: Copy-Paste Demo

Pipelock writes a signed receipt every time it adjudicates an outbound agent action. Receipts compose into a hash-chained file an auditor or CI runner can read without trusting any vendor dashboard. This page is the shortest path from zero to “I ran the verifier, it passed, I tampered one byte, it failed.”

The fixtures here come from the public conformance corpus that verifier authors and Audit Packet producers can test against. There is no vendor-only verification path: every command below runs on public fixtures with a public test key.

The verifier commands

The Pipelock verifier is available as the built-in CLI, a standalone Go binary, and TypeScript, Rust, and Python ports. They expose the same receipt and chain verification surface, with matching exit-code semantics (0 valid, 1 invalid, 2 runtime error, 64 usage error).

Core Go invocations:

# Verify a single receipt with the main Pipelock binary
pipelock verify-receipt receipt.json

# Verify a single receipt with the standalone Go verifier
pipelock-verifier receipt receipt.json

# Verify a full receipt chain (one jsonl file or a session directory)
pipelock-verifier chain evidence.jsonl

# Verify a complete Audit Packet bundle
pipelock-verifier audit-packet ./audit-packet/

The receipt and chain commands accept --key HEX_OR_FILE to pin a signer key for trusted verification. The Go, TypeScript, and Rust CLIs also accept --json for machine-readable output. The standalone Go verifier additionally accepts --offline, --allow-self-consistent-only, --no-trust-required, and --expect-sha256 on audit-packet for stricter or more permissive policies depending on the relying party.

Walk the seven-case quick path

The full public conformance corpus ships 28 fixtures (8 golden, 8 edge, 12 malicious) covering every reject_reason in the closed enum. A verifier author runs the whole corpus. A first-time reader can grasp the format in seven hand-picked cases:

Each .json fixture has a sibling .expect.json describing the verdict any correct verifier MUST emit, the reject_reason enum value, the expected signer key, and notes for verifier authors. Drop your verifier in, run it across the corpus, compare line by line.

Try it locally

Clone the bench, pin the test key, run the verifier on a golden receipt:

git clone https://github.com/luckyPipewrench/agent-egress-bench.git
cd agent-egress-bench/receipts/v0/conformance

# Public test key (committed for reproducibility; production deployments pin their own)
TEST_KEY=$(jq -r .public_key_hex _generator/test-key.json)

# Golden case: accept
pipelock-verifier receipt golden/01-allow-clean-get.json --key "$TEST_KEY"
echo "exit: $?"     # 0 (valid)

# Malicious case: reject with signature_invalid
pipelock-verifier receipt malicious/m01-forged-signature-wrong-key.json --key "$TEST_KEY"
echo "exit: $?"     # 1 (invalid)

# Chain case: reject with chain_break
pipelock-verifier chain malicious/m08-tampered-chain-prev-hash.jsonl --key "$TEST_KEY"
echo "exit: $?"     # 1 (invalid)

A correct verifier emits the reject reason on stderr or in the --json output. The exit code is the relying party’s contract: CI runners gate on 0; auditors investigate any 1; 2 and 64 indicate the verifier itself is misconfigured.

Same corpus, three other languages

Each language port exposes the same receipt and chain verification surface. Use the public corpus to confirm whether a verifier agrees with the expected verdicts before trusting it on production receipts.

# TypeScript
cd sdk/verifiers/ts && npm install && npm run build
node dist/src/cli.js receipt path/to/golden/01-allow-clean-get.json --key "$TEST_KEY"

# Rust
cd sdk/verifiers/rust && cargo build --release
./target/release/pipelock-verifier-rs receipt path/to/golden/01-allow-clean-get.json --key "$TEST_KEY"

# Python (separate repo)
pip install pipelock-verify
pipelock-verify path/to/golden/01-allow-clean-get.json

If a verifier disagrees with the others on any fixture, the disagreement itself is the bug report. The corpus is the contract.

What a passing verification actually proves

Three things, in order, every time:

1. Signature math. The signature is a well-formed Ed25519 signature over SHA-256(canonical-JSON(action_record)), and it verifies against the embedded signer_key. A wrong-key forgery fails here.
2. Body integrity. The verifier recomputes the canonical-JSON hash from the current bytes of action_record. If a single byte changed after signing, the recomputed hash disagrees with the one the signature was produced over. A post-sign edit fails here.
3. Chain linkage. When verifying a chain, each receipt’s chain_prev_hash is checked against the SHA-256 of the previous receipt’s bytes. Cutting one receipt out, reordering, or splicing in a foreign receipt breaks the chain.

Add the verifier-side policy checks on top: pinned signer key, max age, replay window, schema version, strict JSON parsing. The conformance README documents the exact policy assumptions every conformance run uses.

Where to go next

• Agent action receipts: the primitive these commands verify, framed for procurement and audit.
• Verifiable egress control: the umbrella category combining binary-enforced mediation with signed evidence.
• Agent security control layers: where signed receipts fit in the four-lane agent-security map.
• Pipelock action receipt format spec: the exact bytes on the wire.
• AARP v0.1 spec: the assurance profile layered over a frozen receipt.
• Audit Packet v0 schema: the JSON Schema the bundle producers and verifiers both honor.
• pipelock-agent-egress-action: the GitHub Action that produces complete Audit Packets in CI.
• Conformance corpus README: the closed reject-reason enum, policy assumptions, and the generator that produces the fixtures.

Receipts or it didn’t happen. The corpus is public, the verifiers are public, the test key is public. The only thing that varies between a trustworthy run and an untrustworthy one is which public key the relying party chose to pin.