pipelock-verify 0.1.0__tar.gz

pipelock_verify-0.1.0/LICENSE

@@ -0,0 +1,17 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   Copyright 2026 PipeLab
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

pipelock_verify-0.1.0/PKG-INFO

@@ -0,0 +1,205 @@
+Metadata-Version: 2.4
+Name: pipelock-verify
+Version: 0.1.0
+Summary: Verify Pipelock action receipts (Ed25519-signed, chain-linked).
+Author-email: PipeLab <luckypipe@pipelab.org>
+License: Apache-2.0
+Project-URL: Homepage, https://pipelab.org
+Project-URL: Repository, https://github.com/luckyPipewrench/pipelock-verify-python
+Project-URL: Pipelock (Go reference), https://github.com/luckyPipewrench/pipelock
+Project-URL: Receipt Spec, https://pipelab.org/learn/action-receipt-spec/
+Keywords: pipelock,agent-security,receipt,ed25519,verifier,ai-safety
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Classifier: Topic :: Security :: Cryptography
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: cryptography>=41.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Requires-Dist: mypy>=1.8; extra == "dev"
+Dynamic: license-file
+
+# pipelock-verify
+
+[![PyPI version](https://img.shields.io/pypi/v/pipelock-verify.svg)](https://pypi.org/project/pipelock-verify/)
+[![Python versions](https://img.shields.io/pypi/pyversions/pipelock-verify.svg)](https://pypi.org/project/pipelock-verify/)
+[![CI](https://github.com/luckyPipewrench/pipelock-verify-python/actions/workflows/ci.yml/badge.svg)](https://github.com/luckyPipewrench/pipelock-verify-python/actions/workflows/ci.yml)
+[![License: Apache-2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
+
+Python verifier for [Pipelock](https://github.com/luckyPipewrench/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
+
+```bash
+pip install pipelock-verify
+```
+
+Only one runtime dependency: [`cryptography`](https://cryptography.io) for
+the Ed25519 primitives.
+
+## Usage
+
+### Single receipt
+
+```python
+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:
+
+```python
+PROD_KEY = "70b991eb77816fc4ef0ae6a54d8a4119ddc5a16c9711c332c39e743079f6c63e"
+result = pipelock_verify.verify(receipt_bytes, public_key_hex=PROD_KEY)
+```
+
+### Receipt chain
+
+Pass a flight-recorder JSONL path:
+
+```python
+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
+
+```bash
+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
+
+```bash
+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:
+
+```bash
+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](LICENSE).

pipelock_verify-0.1.0/README.md

@@ -0,0 +1,169 @@
+# pipelock-verify
+
+[![PyPI version](https://img.shields.io/pypi/v/pipelock-verify.svg)](https://pypi.org/project/pipelock-verify/)
+[![Python versions](https://img.shields.io/pypi/pyversions/pipelock-verify.svg)](https://pypi.org/project/pipelock-verify/)
+[![CI](https://github.com/luckyPipewrench/pipelock-verify-python/actions/workflows/ci.yml/badge.svg)](https://github.com/luckyPipewrench/pipelock-verify-python/actions/workflows/ci.yml)
+[![License: Apache-2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
+
+Python verifier for [Pipelock](https://github.com/luckyPipewrench/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
+
+```bash
+pip install pipelock-verify
+```
+
+Only one runtime dependency: [`cryptography`](https://cryptography.io) for
+the Ed25519 primitives.
+
+## Usage
+
+### Single receipt
+
+```python
+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:
+
+```python
+PROD_KEY = "70b991eb77816fc4ef0ae6a54d8a4119ddc5a16c9711c332c39e743079f6c63e"
+result = pipelock_verify.verify(receipt_bytes, public_key_hex=PROD_KEY)
+```
+
+### Receipt chain
+
+Pass a flight-recorder JSONL path:
+
+```python
+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
+
+```bash
+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
+
+```bash
+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:
+
+```bash
+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](LICENSE).

pipelock_verify-0.1.0/pipelock_verify/__init__.py

@@ -0,0 +1,49 @@
+"""Pipelock action receipt verifier.
+
+Verifies Ed25519-signed action receipts emitted by the Pipelock mediator.
+Matches the Go reference implementation in ``internal/receipt`` byte-for-byte
+so that receipts generated by the Pipelock binary verify identically in Go
+and Python.
+
+Typical usage::
+
+    import pipelock_verify
+
+    # Single receipt from a JSON string, bytes, or already-parsed dict.
+    result = pipelock_verify.verify(receipt_json)
+    if not result.valid:
+        raise SystemExit(f"bad receipt: {result.error}")
+
+    # Receipt chain from a flight recorder JSONL file.
+    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}")
+
+Trust anchors are opt-in. Pass ``public_key_hex`` to pin a specific signer,
+or leave it empty to trust the key embedded in the receipt (chain mode then
+enforces signer consistency across every receipt in the file).
+
+Wire format: see https://pipelab.org/learn/action-receipt-spec/ for field
+layout, canonicalization rules, and the exact signing input. The format is
+the Go ``json.Marshal`` output of the ``Receipt`` struct; this library
+mirrors it.
+"""
+
+from ._verify import (
+    ChainResult,
+    InvalidReceiptError,
+    VerifyResult,
+    verify,
+    verify_chain,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "ChainResult",
+    "InvalidReceiptError",
+    "VerifyResult",
+    "__version__",
+    "verify",
+    "verify_chain",
+]

pipelock_verify-0.1.0/pipelock_verify/__main__.py

@@ -0,0 +1,140 @@
+"""Command-line interface for ``python -m pipelock_verify``.
+
+Verifies a single receipt JSON file or a flight recorder JSONL chain.
+Exit code 0 on success, 1 on failure — same convention as the Go
+``pipelock verify-receipt`` command.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from collections.abc import Sequence
+from pathlib import Path
+
+from . import __version__
+from ._verify import ChainResult, VerifyResult, verify, verify_chain
+
+
+def _detect_mode(path: Path) -> str:
+    """Return ``"chain"`` for JSONL files, ``"single"`` otherwise."""
+    if path.suffix.lower() == ".jsonl":
+        return "chain"
+    return "single"
+
+
+def _print_single(result: VerifyResult, path: Path) -> None:
+    if not result.valid:
+        print(f"FAILED: {path}: {result.error}")
+        return
+    print(f"OK: {path}")
+    if result.action_id:
+        print(f"  Action ID:   {result.action_id}")
+    if result.action_type:
+        print(f"  Action Type: {result.action_type}")
+    if result.verdict:
+        print(f"  Verdict:     {result.verdict}")
+    if result.target:
+        print(f"  Target:      {result.target}")
+    if result.transport:
+        print(f"  Transport:   {result.transport}")
+    if result.timestamp:
+        print(f"  Timestamp:   {result.timestamp}")
+    if result.signer_key:
+        print(f"  Signer:      {result.signer_key}")
+    if result.chain_seq is not None:
+        print(f"  Chain seq:   {result.chain_seq}")
+    if result.chain_prev_hash:
+        print(f"  Chain prev:  {result.chain_prev_hash}")
+
+
+def _print_chain(result: ChainResult, path: Path) -> None:
+    if not result.valid:
+        print(f"CHAIN BROKEN: {path}")
+        if result.error:
+            print(f"  Error:    {result.error}")
+        if result.broken_at_seq is not None:
+            print(f"  Broke at: seq {result.broken_at_seq}")
+        return
+    print(f"CHAIN VALID: {path}")
+    print(f"  Receipts:  {result.receipt_count}")
+    if result.final_seq is not None:
+        print(f"  Final seq: {result.final_seq}")
+    if result.root_hash:
+        print(f"  Root hash: {result.root_hash}")
+    if result.start_time:
+        print(f"  Start:     {result.start_time}")
+    if result.end_time:
+        print(f"  End:       {result.end_time}")
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="pipelock_verify",
+        description=(
+            "Verify Pipelock action receipts. "
+            "Pass a single receipt JSON file or a JSONL flight recorder "
+            "chain. Exit 0 on success, 1 on failure."
+        ),
+    )
+    parser.add_argument(
+        "path",
+        type=Path,
+        help="receipt JSON file (single) or JSONL file (chain)",
+    )
+    parser.add_argument(
+        "--key",
+        dest="public_key_hex",
+        help=(
+            "expected signer public key, hex-encoded. When omitted, the "
+            "embedded signer_key is trusted; chain mode pins it to the "
+            "first receipt and enforces consistency across the chain."
+        ),
+    )
+    parser.add_argument(
+        "--mode",
+        choices=("single", "chain", "auto"),
+        default="auto",
+        help="force single or chain mode; default auto-detects from file suffix",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"pipelock-verify {__version__}",
+    )
+
+    args = parser.parse_args(argv)
+    path: Path = args.path
+
+    if not path.exists():
+        print(f"FAILED: {path}: file not found", file=sys.stderr)
+        return 1
+
+    mode = args.mode if args.mode != "auto" else _detect_mode(path)
+
+    if mode == "chain":
+        chain_result = verify_chain(path, args.public_key_hex)
+        # Empty files are rejected at the CLI layer to match the Go CLI's
+        # behavior (internal/cli/signing/receipt.go returns an error when
+        # the extracted receipt list is empty). The library function keeps
+        # the permissive "empty is vacuously valid" shape that mirrors
+        # Go's receipt.VerifyChain.
+        if chain_result.valid and chain_result.receipt_count == 0:
+            print(f"No receipts found in {path}")
+            return 1
+        _print_chain(chain_result, path)
+        return 0 if chain_result.valid else 1
+
+    try:
+        data = path.read_bytes()
+    except OSError as exc:
+        print(f"FAILED: {path}: {exc}", file=sys.stderr)
+        return 1
+
+    single_result = verify(data, args.public_key_hex)
+    _print_single(single_result, path)
+    return 0 if single_result.valid else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())