pipelock-verify 0.1.0__py3-none-any.whl

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/__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())

pipelock_verify/_canonical.py

@@ -0,0 +1,176 @@
+"""Go-compatible JSON canonicalization for action records and receipts.
+
+The signing input for a Pipelock receipt is the SHA-256 of the canonical
+JSON encoding of the inner ``ActionRecord``. "Canonical" here means
+"byte-identical to what Go's ``encoding/json`` produces when marshalling
+the ``receipt.ActionRecord`` struct." That contract is what this module
+reproduces. The same rules apply when hashing the full ``Receipt`` envelope
+for chain linkage.
+
+What Go does that matters:
+
+* Fields are emitted in **struct declaration order**, not alphabetical.
+* Fields tagged ``omitempty`` are dropped when the value is the Go zero value
+  (``""`` for strings, empty slice, ``0``, ``false``, nil).
+* Compact output: no whitespace between tokens.
+* HTML-safe escaping: ``<``, ``>``, ``&``, U+2028, U+2029 are escaped as
+  ``\\u003c``, ``\\u003e``, ``\\u0026``, ``\\u2028``, ``\\u2029`` even inside
+  strings that would otherwise be valid JSON.
+
+Any deviation from these rules produces different bytes, which produces a
+different SHA-256, which fails signature verification. There is no slack.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+# ActionRecord fields in Go struct-tag order. Each tuple is
+# (json_name, has_omitempty). Source of truth:
+# https://github.com/luckyPipewrench/pipelock/blob/main/internal/receipt/action.go
+_ACTION_RECORD_FIELDS: list[tuple[str, bool]] = [
+    ("version", False),
+    ("action_id", False),
+    ("action_type", False),
+    ("timestamp", False),
+    ("principal", False),
+    ("actor", False),
+    ("delegation_chain", False),
+    ("target", False),
+    ("intent", True),
+    ("data_classes_in", True),
+    ("data_classes_out", True),
+    ("side_effect_class", False),
+    ("reversibility", False),
+    ("policy_hash", False),
+    ("verdict", False),
+    ("transport", False),
+    ("method", True),
+    ("layer", True),
+    ("pattern", True),
+    ("request_id", True),
+    ("chain_prev_hash", False),
+    ("chain_seq", False),
+    ("venue", True),
+    ("jurisdiction", True),
+    ("rulebook_id", True),
+    ("remedy_class", True),
+    ("contestation_window", True),
+    ("precedent_refs", True),
+]
+
+# Receipt envelope fields in Go struct-tag order. Source of truth:
+# https://github.com/luckyPipewrench/pipelock/blob/main/internal/receipt/receipt.go
+_RECEIPT_FIELDS: list[tuple[str, bool]] = [
+    ("version", False),
+    ("action_record", False),
+    ("signature", False),
+    ("signer_key", False),
+]
+
+
+def _is_go_zero(value: Any) -> bool:
+    """Return True if ``value`` matches Go's ``omitempty`` zero value.
+
+    Go drops a field tagged ``omitempty`` when the value is the zero value
+    for its type: ``""``, empty/nil slice, empty/nil map, ``0``, ``false``,
+    or ``nil``. Python equivalents:
+
+    * ``None`` (nil)
+    * ``""`` (string zero)
+    * ``[]`` (nil or empty slice)
+    * ``{}`` (nil or empty map)
+    * ``False``
+    * ``0`` / ``0.0``
+    """
+    if value is None:
+        return True
+    if isinstance(value, bool):
+        return not value
+    if isinstance(value, (int, float)):
+        return value == 0
+    if isinstance(value, str):
+        return value == ""
+    if isinstance(value, (list, tuple, dict)):
+        return len(value) == 0
+    return False
+
+
+def _order_action_record(ar: dict[str, Any]) -> dict[str, Any]:
+    """Return a new dict with ActionRecord fields in Go's canonical order.
+
+    Missing fields are skipped. ``omitempty`` fields with zero values are
+    dropped. Unknown fields are ignored: Go's ``json.Unmarshal`` would drop
+    them, and the re-serialized canonical form should not include them.
+    """
+    ordered: dict[str, Any] = {}
+    for name, omitempty in _ACTION_RECORD_FIELDS:
+        if name not in ar:
+            continue
+        value = ar[name]
+        if omitempty and _is_go_zero(value):
+            continue
+        ordered[name] = value
+    return ordered
+
+
+def _order_receipt(receipt: dict[str, Any]) -> dict[str, Any]:
+    """Return a new dict with Receipt fields in Go's canonical order.
+
+    The nested ``action_record`` is also reordered, so this function alone
+    is enough to produce canonical bytes for the full envelope (used when
+    computing chain prev_hash linkage).
+    """
+    ordered: dict[str, Any] = {}
+    for name, omitempty in _RECEIPT_FIELDS:
+        if name not in receipt:
+            continue
+        value = receipt[name]
+        if omitempty and _is_go_zero(value):
+            continue
+        if name == "action_record" and isinstance(value, dict):
+            value = _order_action_record(value)
+        ordered[name] = value
+    return ordered
+
+
+def _go_html_escape(serialized: str) -> str:
+    """Apply Go's default HTML-safe escaping to a JSON string.
+
+    Go's ``encoding/json`` escapes ``<``, ``>``, ``&`` and the Unicode line
+    separators U+2028, U+2029 even inside string values. Python's
+    ``json.dumps`` does not. This post-processes the Python output so it
+    matches Go byte-for-byte.
+    """
+    return (
+        serialized.replace("<", "\\u003c")
+        .replace(">", "\\u003e")
+        .replace("&", "\\u0026")
+        .replace("\u2028", "\\u2028")
+        .replace("\u2029", "\\u2029")
+    )
+
+
+def _to_canonical_bytes(obj: Any) -> bytes:
+    """Serialize an ordered dict to canonical UTF-8 bytes."""
+    raw = json.dumps(obj, separators=(",", ":"), ensure_ascii=False)
+    return _go_html_escape(raw).encode("utf-8")
+
+
+def canonicalize_action_record(ar: dict[str, Any]) -> bytes:
+    """Return the signing input bytes for an action record.
+
+    The returned bytes are what Go's ``ActionRecord.Canonical()`` produces
+    and what gets SHA-256-hashed before Ed25519 signing.
+    """
+    return _to_canonical_bytes(_order_action_record(ar))
+
+
+def canonicalize_receipt(receipt: dict[str, Any]) -> bytes:
+    """Return the chain-linking bytes for a full receipt envelope.
+
+    The returned bytes are what Go's ``json.Marshal(receipt)`` produces
+    and what gets SHA-256-hashed to form the next receipt's ``chain_prev_hash``.
+    """
+    return _to_canonical_bytes(_order_receipt(receipt))

pipelock_verify/_verify.py

@@ -0,0 +1,471 @@
+"""Core receipt and chain verification."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+from dataclasses import dataclass
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+from cryptography.exceptions import InvalidSignature
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
+
+from ._canonical import canonicalize_action_record, canonicalize_receipt
+
+# Wire format constants — keep in sync with internal/receipt/receipt.go.
+_RECEIPT_VERSION = 1
+_ACTION_RECORD_VERSION = 1
+_SIGNATURE_PREFIX = "ed25519:"
+_GENESIS_HASH = "genesis"
+
+# Ed25519 sizes (RFC 8032): 32-byte public key, 64-byte signature.
+_PUBLIC_KEY_LEN = 32
+_SIGNATURE_LEN = 64
+
+# Flight-recorder entry type for receipts. Matches
+# internal/receipt/emitter.go recorderEntryType.
+_RECORDER_ENTRY_TYPE = "action_receipt"
+
+# Valid action_type enum values. Matches the allActionTypes map in
+# internal/receipt/action.go. A verifier that does not enforce this set
+# will accept Go-rejected receipts (e.g. action_type: "bogus"), which
+# breaks cross-implementation agreement. Order mirrors the Go source.
+_VALID_ACTION_TYPES = frozenset(
+    {
+        "read",
+        "derive",
+        "write",
+        "delegate",
+        "authorize",
+        "spend",
+        "commit",
+        "actuate",
+        "unclassified",
+    }
+)
+
+# RFC 3339 / time.RFC3339Nano shape check. Go's time.Time.UnmarshalJSON
+# accepts:
+#
+#   2006-01-02T15:04:05Z                        (no fractional seconds)
+#   2006-01-02T15:04:05.999999999Z              (up to 9 fractional digits)
+#   2006-01-02T15:04:05.999999999+07:00         (numeric offset)
+#
+# It rejects anything else, including lower-case "t"/"z", missing timezone,
+# or non-numeric content. The regex below enforces the shape; a follow-up
+# datetime.fromisoformat() call catches semantic errors like month 13 or
+# day 32. Both checks must pass or the timestamp is invalid.
+_RFC3339_RE = re.compile(r"^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,9})?(Z|[+-]\d{2}:\d{2})$")
+
+
+def _is_valid_rfc3339(value: Any) -> bool:
+    """Return True if value parses as an RFC 3339 timestamp Go would accept.
+
+    Python's datetime.fromisoformat accepts the ``Z`` suffix natively only
+    on 3.11+, so we substitute it with ``+00:00`` before parsing to support
+    3.9 and 3.10 as well.
+    """
+    if not isinstance(value, str):
+        return False
+    if not _RFC3339_RE.match(value):
+        return False
+    candidate = value[:-1] + "+00:00" if value.endswith("Z") else value
+    try:
+        datetime.fromisoformat(candidate)
+    except ValueError:
+        return False
+    return True
+
+
+class InvalidReceiptError(Exception):
+    """Raised when a receipt cannot be parsed as JSON at all."""
+
+
+@dataclass
+class VerifyResult:
+    """Outcome of verifying a single receipt.
+
+    ``valid`` is the only field guaranteed to be set. Descriptive fields
+    are populated on success (and may be populated on some failures) for
+    diagnostic output. ``error`` holds a short reason string on failure.
+    """
+
+    valid: bool
+    error: str | None = None
+    action_id: str | None = None
+    action_type: str | None = None
+    verdict: str | None = None
+    target: str | None = None
+    transport: str | None = None
+    signer_key: str | None = None
+    chain_seq: int | None = None
+    chain_prev_hash: str | None = None
+    timestamp: str | None = None
+
+
+@dataclass
+class ChainResult:
+    """Outcome of verifying a receipt chain.
+
+    Mirrors ``receipt.ChainResult`` in the Go implementation: on break,
+    ``broken_at_seq`` identifies where the chain failed, and ``error``
+    describes why. On success, ``root_hash`` is the hash of the final
+    receipt, suitable for publishing as a transcript root.
+    """
+
+    valid: bool
+    error: str | None = None
+    broken_at_seq: int | None = None
+    receipt_count: int = 0
+    final_seq: int | None = None
+    root_hash: str | None = None
+    start_time: str | None = None
+    end_time: str | None = None
+
+
+def verify(
+    source: str | bytes | dict[str, Any],
+    public_key_hex: str | None = None,
+) -> VerifyResult:
+    """Verify a single action receipt.
+
+    Args:
+        source: Receipt as a JSON string, UTF-8 bytes, or a pre-parsed dict.
+        public_key_hex: Optional trust anchor. When supplied, the receipt's
+            ``signer_key`` field must match this value (hex-encoded 32-byte
+            Ed25519 public key). When omitted, the embedded ``signer_key``
+            is trusted.
+
+    Returns:
+        A :class:`VerifyResult`. ``result.valid`` is ``True`` only when the
+        signature verifies and every structural check passes.
+    """
+    try:
+        parsed = _parse_receipt(source)
+    except json.JSONDecodeError as exc:
+        return VerifyResult(valid=False, error=f"parsing receipt: {exc}")
+    except InvalidReceiptError as exc:
+        return VerifyResult(valid=False, error=str(exc))
+
+    # Transparently unwrap a flight-recorder entry wrapper if present so
+    # callers can feed either bare receipt JSON or an entry dump.
+    try:
+        receipt = _extract_receipt(parsed)
+    except InvalidReceiptError as exc:
+        return VerifyResult(valid=False, error=str(exc))
+    if receipt is None:
+        return VerifyResult(
+            valid=False, error="flight-recorder entry does not carry an action receipt"
+        )
+
+    return _verify_receipt_dict(receipt, public_key_hex)
+
+
+def verify_chain(
+    jsonl_path: str | Path,
+    public_key_hex: str | None = None,
+) -> ChainResult:
+    """Verify a receipt chain from a flight recorder JSONL file.
+
+    Args:
+        jsonl_path: Path to a JSONL file with one receipt per line. Empty
+            lines are ignored.
+        public_key_hex: Optional trust anchor. When omitted, the
+            ``signer_key`` of the first receipt is taken as the expected
+            key and every subsequent receipt must share it. This matches
+            the Go ``VerifyChain`` signer-consistency check.
+
+    Returns:
+        A :class:`ChainResult`. On failure, ``broken_at_seq`` and ``error``
+        locate the first receipt that failed.
+    """
+    try:
+        receipts = _read_jsonl(Path(jsonl_path))
+    except FileNotFoundError as exc:
+        return ChainResult(valid=False, error=f"reading file: {exc}")
+    except json.JSONDecodeError as exc:
+        return ChainResult(valid=False, error=f"parsing JSONL: {exc}")
+    except InvalidReceiptError as exc:
+        # _read_jsonl raises this when a line parses as JSON but doesn't
+        # look like a receipt or a flight-recorder entry. Surface it as a
+        # normal failure result instead of propagating a raw exception.
+        return ChainResult(valid=False, error=f"parsing JSONL: {exc}")
+
+    return _verify_chain_list(receipts, public_key_hex)
+
+
+# ---- internals ----
+
+
+def _parse_receipt(source: str | bytes | dict[str, Any]) -> dict[str, Any]:
+    if isinstance(source, dict):
+        return source
+    if isinstance(source, bytes):
+        source = source.decode("utf-8")
+    if not isinstance(source, str):
+        raise InvalidReceiptError(
+            f"unsupported source type {type(source).__name__}; expected str, bytes, or dict"
+        )
+    parsed = json.loads(source)
+    if not isinstance(parsed, dict):
+        raise InvalidReceiptError("receipt must be a JSON object")
+    return parsed
+
+
+def _extract_receipt(parsed: dict[str, Any]) -> dict[str, Any] | None:
+    """Pull a receipt dict out of a parsed JSONL line.
+
+    Accepts two formats:
+
+    1. **Bare receipt** — the top-level object already has ``action_record``
+       and ``signature``. Returned as-is.
+    2. **Flight-recorder entry** — a wrapper with ``type == "action_receipt"``
+       and the receipt sitting in ``detail`` (either as an object or as a
+       JSON-encoded string, since Go emits it via ``json.RawMessage``).
+
+    Returns ``None`` for flight-recorder entries whose type is not a
+    receipt (checkpoints, other event types) so ``_read_jsonl`` can skip
+    them without aborting the chain.
+    """
+    # Flight-recorder entry.
+    if "type" in parsed and "detail" in parsed:
+        if parsed.get("type") != _RECORDER_ENTRY_TYPE:
+            return None
+        detail = parsed["detail"]
+        if isinstance(detail, dict):
+            return detail
+        if isinstance(detail, (str, bytes)):
+            decoded = json.loads(detail)
+            if not isinstance(decoded, dict):
+                raise InvalidReceiptError("flight-recorder detail JSON did not decode to an object")
+            return decoded
+        raise InvalidReceiptError(
+            f"flight-recorder detail has unexpected type {type(detail).__name__}"
+        )
+
+    # Bare receipt.
+    if "action_record" in parsed and "signature" in parsed:
+        return parsed
+
+    raise InvalidReceiptError("unrecognized JSONL line: not a receipt or flight-recorder entry")
+
+
+def _read_jsonl(path: Path) -> list[dict[str, Any]]:
+    text = path.read_text(encoding="utf-8")
+    receipts: list[dict[str, Any]] = []
+    for lineno, raw in enumerate(text.splitlines(), start=1):
+        line = raw.strip()
+        if not line:
+            continue
+        try:
+            parsed = json.loads(line)
+        except json.JSONDecodeError as exc:
+            raise json.JSONDecodeError(f"line {lineno}: {exc.msg}", exc.doc, exc.pos) from exc
+        if not isinstance(parsed, dict):
+            raise json.JSONDecodeError(f"line {lineno}: JSONL entry must be a JSON object", line, 0)
+        receipt = _extract_receipt(parsed)
+        if receipt is None:
+            # Non-receipt recorder entry (checkpoint, other event). Skip
+            # instead of failing the whole chain — matches Go ExtractReceipts.
+            continue
+        receipts.append(receipt)
+    return receipts
+
+
+def _verify_receipt_dict(
+    receipt: dict[str, Any],
+    expected_key_hex: str | None,
+) -> VerifyResult:
+    version = receipt.get("version")
+    if version != _RECEIPT_VERSION:
+        return VerifyResult(
+            valid=False,
+            error=(f"unsupported receipt version {version} (expected {_RECEIPT_VERSION})"),
+        )
+
+    action_record = receipt.get("action_record")
+    if not isinstance(action_record, dict):
+        return VerifyResult(valid=False, error="missing or invalid action_record")
+
+    ar_version = action_record.get("version")
+    if ar_version != _ACTION_RECORD_VERSION:
+        return VerifyResult(
+            valid=False,
+            error=(
+                f"unsupported action_record version {ar_version} "
+                f"(expected {_ACTION_RECORD_VERSION})"
+            ),
+        )
+
+    # Match internal/receipt/action.go Validate() exactly. Go's error order
+    # and messages are part of the cross-implementation contract:
+    #
+    #   1. action_id presence          -> "action_id is required"
+    #   2. action_type enum membership -> 'invalid action_type "<value>"'
+    #      (rejects both empty "" and any non-enum value with the same
+    #      wording; the required-field sweep does NOT cover action_type)
+    #   3. timestamp presence          -> "timestamp is required"
+    #   4. target presence             -> "target is required"
+    #   5. verdict presence            -> "verdict is required"
+    #   6. transport presence          -> "transport is required"
+    #
+    # Timestamp validity is enforced BEFORE the signature check because Go
+    # parses the receipt into a typed struct first; a malformed timestamp
+    # there fails json.Unmarshal and never reaches signature verification.
+    # Python parses into a dict, so we have to replay the same check
+    # manually or an attacker can ship "timestamp": "not-a-time" with a
+    # valid signature over the canonical garbage and Python will accept it.
+    if not action_record.get("action_id"):
+        return VerifyResult(valid=False, error="invalid action record: action_id is required")
+
+    action_type = action_record.get("action_type", "")
+    if action_type not in _VALID_ACTION_TYPES:
+        return VerifyResult(
+            valid=False,
+            error=f'invalid action record: invalid action_type "{action_type}"',
+        )
+
+    timestamp = action_record.get("timestamp")
+    if not timestamp:
+        return VerifyResult(valid=False, error="invalid action record: timestamp is required")
+    if not _is_valid_rfc3339(timestamp):
+        # Go surfaces this as a json.Unmarshal error; Python surfaces it as
+        # its own diagnostic so the fix point is obvious. The net effect —
+        # "signed receipt with a bogus timestamp is rejected" — matches.
+        return VerifyResult(
+            valid=False,
+            error=(f'unmarshal receipt: invalid RFC 3339 timestamp "{timestamp}"'),
+        )
+
+    for required in ("target", "verdict", "transport"):
+        if not action_record.get(required):
+            return VerifyResult(
+                valid=False,
+                error=f"invalid action record: {required} is required",
+            )
+
+    signature_str = receipt.get("signature", "")
+    if not signature_str:
+        return VerifyResult(valid=False, error="receipt has no signature")
+    if not isinstance(signature_str, str) or not signature_str.startswith(_SIGNATURE_PREFIX):
+        return VerifyResult(
+            valid=False,
+            error=f"invalid signature format: missing {_SIGNATURE_PREFIX} prefix",
+        )
+
+    signer_key_hex = receipt.get("signer_key", "")
+    if not signer_key_hex:
+        return VerifyResult(valid=False, error="receipt has no signer_key")
+
+    if expected_key_hex and signer_key_hex != expected_key_hex:
+        return VerifyResult(
+            valid=False,
+            error=(f"signer_key {signer_key_hex} does not match expected key {expected_key_hex}"),
+        )
+
+    sig_hex = signature_str[len(_SIGNATURE_PREFIX) :]
+    try:
+        sig_bytes = bytes.fromhex(sig_hex)
+    except ValueError as exc:
+        return VerifyResult(valid=False, error=f"decoding signature: {exc}")
+    if len(sig_bytes) != _SIGNATURE_LEN:
+        return VerifyResult(
+            valid=False,
+            error=(f"invalid signature length: got {len(sig_bytes)}, want {_SIGNATURE_LEN}"),
+        )
+
+    try:
+        pub_key_bytes = bytes.fromhex(signer_key_hex)
+    except ValueError as exc:
+        return VerifyResult(valid=False, error=f"decoding signer_key: {exc}")
+    if len(pub_key_bytes) != _PUBLIC_KEY_LEN:
+        return VerifyResult(
+            valid=False,
+            error=(f"invalid signer_key length: got {len(pub_key_bytes)}, want {_PUBLIC_KEY_LEN}"),
+        )
+
+    canonical = canonicalize_action_record(action_record)
+    signing_hash = hashlib.sha256(canonical).digest()
+
+    try:
+        Ed25519PublicKey.from_public_bytes(pub_key_bytes).verify(sig_bytes, signing_hash)
+    except InvalidSignature:
+        return VerifyResult(valid=False, error="signature verification failed")
+
+    return VerifyResult(
+        valid=True,
+        action_id=action_record.get("action_id"),
+        action_type=action_record.get("action_type"),
+        verdict=action_record.get("verdict"),
+        target=action_record.get("target"),
+        transport=action_record.get("transport"),
+        signer_key=signer_key_hex,
+        chain_seq=action_record.get("chain_seq"),
+        chain_prev_hash=action_record.get("chain_prev_hash"),
+        timestamp=action_record.get("timestamp"),
+    )
+
+
+def _compute_receipt_hash(receipt: dict[str, Any]) -> str:
+    """Chain linkage hash: SHA-256 hex of canonical receipt envelope.
+
+    Matches ``receipt.ReceiptHash`` in ``internal/receipt/chain.go``.
+    """
+    canonical = canonicalize_receipt(receipt)
+    return hashlib.sha256(canonical).hexdigest()
+
+
+def _verify_chain_list(
+    receipts: list[dict[str, Any]],
+    public_key_hex: str | None,
+) -> ChainResult:
+    if not receipts:
+        return ChainResult(valid=True, receipt_count=0)
+
+    # When no key is pinned, lock to the first receipt's signer_key so an
+    # attacker can't splice receipts from a second signer into the chain.
+    expected_key = public_key_hex or receipts[0].get("signer_key", "")
+
+    prev_hash = _GENESIS_HASH
+    for i, receipt in enumerate(receipts):
+        ar = receipt.get("action_record") or {}
+        seq = ar.get("chain_seq", i)
+
+        result = _verify_receipt_dict(receipt, expected_key)
+        if not result.valid:
+            return ChainResult(
+                valid=False,
+                broken_at_seq=seq,
+                error=f"seq {seq}: signature: {result.error}",
+            )
+
+        if seq != i:
+            return ChainResult(
+                valid=False,
+                broken_at_seq=seq,
+                error=f"seq gap: expected {i}, got {seq}",
+            )
+
+        actual_prev = ar.get("chain_prev_hash", "")
+        if actual_prev != prev_hash:
+            return ChainResult(
+                valid=False,
+                broken_at_seq=seq,
+                error=f"seq {seq}: chain_prev_hash mismatch",
+            )
+
+        prev_hash = _compute_receipt_hash(receipt)
+
+    first_ar = receipts[0].get("action_record") or {}
+    last_ar = receipts[-1].get("action_record") or {}
+    return ChainResult(
+        valid=True,
+        receipt_count=len(receipts),
+        final_seq=last_ar.get("chain_seq"),
+        root_hash=prev_hash,
+        start_time=first_ar.get("timestamp"),
+        end_time=last_ar.get("timestamp"),
+    )

pipelock_verify-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,11 @@
+pipelock_verify/__init__.py,sha256=Pn184SXU-bJsBo662X3VoZGvWS5GLz22NdBsguif7Rs,1486
+pipelock_verify/__main__.py,sha256=Zz-Qa5geo05zFb7_R3kKWp7wsci-eRX9BjoILXRAPpA,4605
+pipelock_verify/_canonical.py,sha256=Rbeua9GdUWu4P5pXhAWz_DYSgHOUU7Z_aA2VJ-tSteM,6066
+pipelock_verify/_verify.py,sha256=87cZUyfYSQDdcsmEuo91GVkyrpKBpgWhbFO1fCUh2-M,17345
+pipelock_verify/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pipelock_verify-0.1.0.dist-info/licenses/LICENSE,sha256=PO99Z4PhxPnBmYkVqYiQkSva2Gl6ssNCWErSAjABpUk,736
+pipelock_verify-0.1.0.dist-info/METADATA,sha256=CKt7s8GTO2YC14jvJ0jdymCN0bcbQDSjizei8LJcVHI,7319
+pipelock_verify-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+pipelock_verify-0.1.0.dist-info/entry_points.txt,sha256=gfvMGUzm26-g2k4hqoZndoCfJpuZhE83L2UWKd7g_Xw,66
+pipelock_verify-0.1.0.dist-info/top_level.txt,sha256=BCQ_f-JXtPiaHiyXK5UXMRRz6NEsW_PWLuEbTOcIhqg,16
+pipelock_verify-0.1.0.dist-info/RECORD,,

pipelock_verify-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

pipelock_verify-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pipelock-verify = pipelock_verify.__main__:main

pipelock_verify-0.1.0.dist-info/licenses/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.dist-info/top_level.txt

@@ -0,0 +1 @@
+pipelock_verify