pipelock-verify 0.1.0

Verify Pipelock action receipts (Ed25519-signed, chain-linked).

pipelock-verify

Python verifier for Pipelock action receipts. Verifies the Ed25519 signature, chain linkage, and flight-recorder wrapping of receipts emitted by the Pipelock mediator.

The library mirrors the Go reference implementation byte-for-byte. The conformance golden files in tests/conformance/ are generated by Pipelock's Go code and verified identically by both sides.

Install

pip install pipelock-verify

Only one runtime dependency: cryptography for the Ed25519 primitives.

Usage

Single receipt

import pipelock_verify

with open("receipt.json", "rb") as f:
    result = pipelock_verify.verify(f.read())

if not result.valid:
    raise SystemExit(f"bad receipt: {result.error}")

print(f"OK: {result.action_id} {result.verdict} {result.target}")

Pin a specific signing key to reject receipts from any other signer:

PROD_KEY = "70b991eb77816fc4ef0ae6a54d8a4119ddc5a16c9711c332c39e743079f6c63e"
result = pipelock_verify.verify(receipt_bytes, public_key_hex=PROD_KEY)

Receipt chain

Pass a flight-recorder JSONL path:

chain = pipelock_verify.verify_chain("evidence-proxy-0.jsonl")

if not chain.valid:
    raise SystemExit(
        f"chain broken at seq {chain.broken_at_seq}: {chain.error}"
    )

print(f"CHAIN VALID: {chain.receipt_count} receipts, root {chain.root_hash}")

When no trust anchor is supplied, the first receipt's signer_key becomes the expected key for the rest of the chain. This matches the signer- consistency check in Go's receipt.VerifyChain.

CLI

python -m pipelock_verify receipt.json
python -m pipelock_verify evidence.jsonl
python -m pipelock_verify evidence.jsonl --key 70b991eb77816fc4...

Exit codes match pipelock verify-receipt: 0 on success, 1 on failure.

What gets verified

On a single receipt:

• Envelope version (rejects anything other than v1).
• Action record version (rejects anything other than v1).
• Required action record fields (action_id, action_type, timestamp, target, verdict, transport).
• Signature format (ed25519:<hex> prefix, 64-byte length).
• Signer key format (32-byte hex).
• Optional trust anchor match (public_key_hex argument).
• Ed25519 signature over SHA-256(canonical action record).

On a chain:

• Every individual receipt above.
• Signer consistency (every receipt uses the same signer_key, or the pinned trust anchor if one was supplied).
• Monotonic chain_seq starting at 0.
• chain_prev_hash linkage: each receipt's chain_prev_hash equals SHA-256 of the previous receipt's canonical envelope, in hex.
• First receipt's chain_prev_hash equals the literal string "genesis".

Failing receipts return the first break point (broken_at_seq) and a descriptive error, the same shape the Go CLI prints.

Input formats

verify_chain() accepts JSONL in two shapes:

1. Flight-recorder entries — the format Pipelock actually writes to disk. Each line is a recorder.Entry object with type == "action_receipt" and the receipt nested in detail. Non-receipt entries (checkpoints etc.) are skipped, not rejected.
2. Bare receipts — one receipt object per line, no wrapping. Used by the conformance suite and handy for ad-hoc testing.

verify() accepts:

• A JSON string or UTF-8 bytes.
• A pre-parsed dict (for callers that already have the receipt loaded).
• A flight-recorder entry dict (transparently unwrapped).

Canonicalization rules

The signing input is the SHA-256 of the Go json.Marshal output of the ActionRecord struct. "Canonical" means matching that exactly:

• Fields emitted in Go struct declaration order (not alphabetical).
• omitempty fields dropped when the value is the Go zero value ("", empty slice, 0, false, nil).
• Compact JSON (no whitespace between tokens).
• HTML-safe escapes: <, >, &, U+2028, U+2029 encoded as Unicode escapes, matching Go's default encoding/json behavior.
• Fields unknown to the v1 schema are dropped (matches Go json.Unmarshal round-trip behavior).

Any deviation produces different bytes, a different hash, and a failed signature. See pipelock_verify/_canonical.py for the full rule set.

Relationship to the Go reference

• Go reference: https://github.com/luckyPipewrench/pipelock/tree/main/internal/receipt
• Conformance suite: https://github.com/luckyPipewrench/pipelock/tree/main/sdk/conformance
• Spec page: https://pipelab.org/learn/action-receipt-spec/

Both implementations verify the same sdk/conformance/testdata/ golden files and compute identical root hashes.

Development

git clone https://github.com/luckyPipewrench/pipelock-verify-python
cd pipelock-verify-python
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
pytest

To refresh the conformance fixtures from a local Pipelock checkout:

cd /path/to/pipelock
go test ./sdk/conformance/ -run TestGenerateGoldenFiles -update
cp sdk/conformance/testdata/*.{json,jsonl} \
   /path/to/pipelock-verify-python/tests/conformance/
pytest

License

Apache 2.0. See LICENSE.