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.

v3.7 completeness checks

Replace trusted-signing.pub in these examples with the public key you independently trust for the recorder signer.

An intact chain without an end proof reports VALID PREFIX, END UNPROVEN. For recorder directories, use pipelock verify-receipt --chain ./recorder --whole-recorder --key trusted-signing.pub to check the transcript seal. Receipt-chain mode can exit 3 even after a clean shutdown if EvidenceReceipt v2 receipts have no chain end marker. Other verifiers support independently retained expected heads or sequences where documented.

For parallel receipt chains, keep the complete directory and use a group-capable verifier. The published TypeScript and Rust packages at 0.6.5 check whole groups; Python pipelock-verify 0.4.1 checks individual shards and chains, including their signed group binding, but doesn’t verify the group. Signed recovery seals attest a discontinuity and preserve the damaged history’s failure. Read the v3.7 upgrade guide.

The verifier commands

The Pipelock verifier is available as the built-in CLI, a standalone Go binary, and TypeScript, Rust, and Python ports. Choose the exit contract for the command you run:

• Built-in pipelock verify-receipt v3.7.1: 0 valid, 1 invalid, malformed or refused, and 2 for a configuration error or a usage error the command checks itself. A missing argument or unknown flag is rejected before the command runs and exits 1. Chain mode also exits 3 for an intact prefix whose end isn’t proven.
• Standalone Go v3.7.1, TypeScript 0.6.5 and Rust 0.6.5: 0 valid, 1 invalid, 2 runtime error, 64 usage error, and 3 for an intact chain prefix whose end isn’t proven. --allow-prefix accepts that prefix with exit 0 while retaining its incomplete-end label.
• Python pipelock-verify 0.4.1: 0 for valid receipts or chain linkage, 1 for verification failure, and 2 for argument errors. It has no end-proof state and can exit 0 when a chain’s tail is missing. Its success doesn’t establish run completeness or whole-group validity.

Core Go invocations:

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

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

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

# Verify a complete Audit Packet bundle, pinning the signer key
pipelock-verifier audit-packet ./audit-packet/ --key signer.pub

To check more than the receipts, pass --whole-recorder to pipelock verify-receipt. It verifies every recorder entry present, its taxonomy, and the transcript_root seal written at clean shutdown, and the output says Mode: whole-recorder so you can tell which check ran. Add --require-seal to fail when any run lacks that seal. It works on a recorder JSONL file or a --chain directory, and it can’t be combined with --clean-report or --fleet-report.

A single-chain Pipelock process writes a receipt chain named <base>.run.<id>. Parallel mode uses signed group lifecycle records to bind multiple chains. A restart isn’t a gap: it’s recorded as a signed link file that names the tail of the run it continues. pipelock verify-receipt --chain ./recorder --key trusted-signing.pub verifies every run chain of the base, then checks that each link names the exact tail of the run it continues. pipelock evidence doctor follows the same links. Runs that no link continues are listed as unlinked. That’s normal for a first run or concurrent runs, and it’s also what a deleted link file looks like, so a passing result doesn’t prove no run’s evidence is missing.

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.

audit-packet --offline no longer reports a packet as trusted. Since v3.6.0 the Go, Rust, and TypeScript verifiers return verdict: schema_checked_trust_unverified with trusted and valid both false and exit non-zero, because offline mode checks only the packet schema and never re-reads the receipt chain. Clean reports also carry a verification_mode of pinned_provenance or unpinned_structural. A CI job that read the old success must run a full chain check instead.

You can also check a chain without installing anything. The browser verifier runs locally, uploads nothing, and lets you pin the operator public key you trust.

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/pipelab-org/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 verifies individual receipts and chain linkage. Their end-proof and group checks differ, as described above. 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

• Why this evidence matters: the public corpus, signed rules, and assessment evidence behind Pipelock’s claims.
• 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. A trustworthy run still depends on the boundary, binary, workflow, key custody, and the public key the relying party chose to pin.