aer1-haystack 0.1.0__py3-none-any.whl

aer1_haystack/__init__.py

@@ -0,0 +1,39 @@
+"""aer1-haystack: AER-1 verifiable workflow receipts for Haystack."""
+
+from .anchor import (
+    AnchorError,
+    NostrBackend,
+    OTSBackend,
+    anchor_chain_head,
+    bip340_verify,
+    proof_from_json,
+    proof_to_json,
+    verify_anchor,
+)
+from .collector import (
+    AER1ReceiptCollector,
+    DEFAULT_VERIFY_URL,
+    WORKFLOW_TYPE,
+    WORKFLOW_VERSION,
+    merkle_root,
+    verify_workflow_receipt,
+)
+
+__all__ = [
+    "AER1ReceiptCollector",
+    "DEFAULT_VERIFY_URL",
+    "WORKFLOW_TYPE",
+    "WORKFLOW_VERSION",
+    "AnchorError",
+    "NostrBackend",
+    "OTSBackend",
+    "anchor_chain_head",
+    "bip340_verify",
+    "merkle_root",
+    "proof_from_json",
+    "proof_to_json",
+    "verify_anchor",
+    "verify_workflow_receipt",
+]
+
+__version__ = "0.1.0"

aer1_haystack/anchor.py

@@ -0,0 +1,660 @@
+"""AER-1 chain-head anchoring: closing the truncation gap.
+
+The truncation attack
+---------------------
+A hash chain catches tampering (a modified step) and reordering (a moved
+step), because every step hash commits to its predecessor. But a hash
+chain CANNOT catch truncation on its own: delete the last k steps and the
+remaining chain still verifies cleanly. A dropped tail looks exactly like
+a run that ended earlier. If a buyer pays on receipts, the operator can
+silently drop the expensive tail of a run and present a clean, shorter
+receipt.
+
+The fix: anchor the chain head (the Merkle root over all step
+receipt_ids, AER-1 Section 8.1) somewhere external that the operator
+cannot rewrite. Verification then has three parts:
+
+  1. Recompute the Merkle root from the receipt's own steps.
+  2. Check the recomputed root matches the anchored root. This catches
+     truncation AND fake-root anchoring: an operator who anchors a root
+     for fewer steps fails here, because the receipt's own steps
+     recompute to the full root.
+  3. Check the anchor exists on the external backend(s) and commits to
+     the same root. This catches anchor forgery.
+
+Privacy by design: only the Merkle root (64 hex chars) and the receipt
+UUID ever touch a public backend. No step content, no inputs, no
+outputs, no tool names. A root is a commitment, not a leak.
+
+Censorship resistance
+---------------------
+Backend               Resists                              Notes
+nostr (multi-relay)   single-relay censorship,             published to N
+                      relay rewrites history               relays; the event
+                                                           is signed and public
+opentimestamps        relay/calendar censorship,           calendar attestation
+(Bitcoin)             operator timestamp lies              matures into a
+                                                           Bitcoin commitment
+                                                           (~1h via ots upgrade)
+
+No single backend is a single point of failure: if Nostr relays censor,
+the Bitcoin anchor still stands.
+
+Failure semantics
+-----------------
+Anchoring NEVER blocks receipt creation. If every backend is down, the
+receipt is still valid locally (hash chain intact) but marked
+"unanchored". Explicit anchoring (anchor_now) fails LOUDLY with
+AnchorError listing every backend failure. anchor_status() always
+reports per-backend state: pending / confirmed / failed. There are no
+silent drops.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+import os
+import re
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from datetime import datetime, timezone
+
+from .collector import _canonical, _rfc3339, merkle_root
+
+PROOF_FORMAT = "aer1-anchor-proof/1"
+
+DEFAULT_NOSTR_RELAYS = [
+    "wss://nos.lol",
+    "wss://relay.primal.net",
+    "wss://relay.ditto.pub",
+]
+DEFAULT_OTS_CALENDARS = [
+    "https://alice.btc.calendar.opentimestamps.org",
+    "https://bob.btc.calendar.opentimestamps.org",
+    "https://ots.btc.catallaxy.com",
+]
+
+OTS_MAGIC = b"\x00OpenTimestamps\x00\x00Proof\x00\xbf\x89\xe2\xe8\x84\xe8\x92\x94"
+OTS_VERSION = 1
+# OTS crypto-op tag -> digest length in bytes (v1 supports these four).
+_OTS_OP_LEN = {0x08: 32, 0x09: 20, 0x0A: 20, 0x0B: 32}
+
+_NOSTR_KIND = 1
+_URI_RE = re.compile(rb"https?://[A-Za-z0-9._~:/?#\[\]@!$&'()*+,;=%-]{8,120}")
+
+
+class AnchorError(Exception):
+    """Raised when explicit anchoring fails. Never raised by finalize()."""
+
+
+# ---------------------------------------------------------------------------
+# small helpers
+# ---------------------------------------------------------------------------
+
+def _now_rfc3339() -> str:
+    return datetime.fromtimestamp(time.time(), tz=timezone.utc).strftime(
+        "%Y-%m-%dT%H:%M:%SZ"
+    )
+
+
+def _read_varuint(data: bytes, pos: int):
+    """Read an OTS-style LEB128 varuint. Returns (value, new_pos)."""
+    value = 0
+    shift = 0
+    while True:
+        if pos >= len(data):
+            raise AnchorError("truncated varuint in OTS data")
+        b = data[pos]
+        pos += 1
+        value |= (b & 0x7F) << shift
+        if not (b & 0x80):
+            return value, pos
+        shift += 7
+        if shift > 63:
+            raise AnchorError("varuint overflow in OTS data")
+
+
+def _http_post_bytes(url: str, payload: bytes, timeout: int) -> bytes:
+    req = urllib.request.Request(
+        url, data=payload, headers={"Content-Type": "application/octet-stream"}
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            return resp.read()
+    except urllib.error.HTTPError as e:
+        raise AnchorError(f"HTTP {e.code} from {url}")
+    except urllib.error.URLError as e:
+        raise AnchorError(f"unreachable {url}: {e.reason}")
+    except TimeoutError:
+        raise AnchorError(f"timeout posting to {url}")
+
+
+def _proxy_from_env():
+    """(host, port, (user, password)) for websocket-client, or None."""
+    for var in ("https_proxy", "HTTPS_PROXY", "http_proxy", "HTTP_PROXY"):
+        val = os.environ.get(var)
+        if val:
+            u = urllib.parse.urlparse(val)
+            if u.hostname:
+                auth = (u.username, u.password) if u.username else None
+                return u.hostname, u.port or 8080, auth
+    return None
+
+
+# ---------------------------------------------------------------------------
+# BIP-340 Schnorr verification (pure python; no extra dependency)
+# ---------------------------------------------------------------------------
+
+_BIP340_P = 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFEFFFFFC2F
+_BIP340_N = 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFEBAAEDCE6AF48A03BBFD25E8CD0364141
+_BIP340_G = (
+    0x79BE667EF9DCBBAC55A06295CE870B07029BFCDB2DCE28D959F2815B16F81798,
+    0x483ADA7726A3C4655DA4FBFC0E1108A8FD17B448A68554199C47D08FFB10D4B8,
+)
+
+
+def _bip340_tagged_hash(tag: bytes, msg: bytes) -> bytes:
+    th = hashlib.sha256(tag).digest()
+    return hashlib.sha256(th + th + msg).digest()
+
+
+def _bip340_lift_x(x: int):
+    p = _BIP340_P
+    y_sq = (pow(x, 3, p) + 7) % p
+    y = pow(y_sq, (p + 1) // 4, p)
+    if pow(y, 2, p) != y_sq:
+        return None
+    return (x, y if y % 2 == 0 else p - y)
+
+
+def _bip340_add(p1, p2):
+    if p1 is None:
+        return p2
+    if p2 is None:
+        return p1
+    p = _BIP340_P
+    x1, y1 = p1
+    x2, y2 = p2
+    if x1 == x2:
+        if y1 != y2:
+            return None
+        lam = (3 * x1 * x1 * pow(2 * y1, p - 2, p)) % p
+    else:
+        lam = ((y2 - y1) * pow(x2 - x1, p - 2, p)) % p
+    x3 = (lam * lam - x1 - x2) % p
+    return (x3, (lam * (x1 - x3) - y1) % p)
+
+
+def _bip340_mul(point, n: int):
+    r = None
+    addend = point
+    while n:
+        if n & 1:
+            r = _bip340_add(r, addend)
+        addend = _bip340_add(addend, addend)
+        n >>= 1
+    return r
+
+
+def bip340_verify(pubkey: bytes, msg: bytes, sig: bytes) -> bool:
+    """BIP-340 Schnorr verification. pubkey: 32B x-only; msg: 32B; sig: 64B."""
+    p, n = _BIP340_P, _BIP340_N
+    if len(pubkey) != 32 or len(msg) != 32 or len(sig) != 64:
+        return False
+    r = int.from_bytes(sig[:32], "big")
+    s = int.from_bytes(sig[32:], "big")
+    if r >= p or s >= n:
+        return False
+    P = _bip340_lift_x(int.from_bytes(pubkey, "big"))
+    if P is None:
+        return False
+    e = int.from_bytes(
+        _bip340_tagged_hash(b"BIP0340/challenge", sig[:32] + pubkey + msg), "big"
+    ) % n
+    R = _bip340_add(_bip340_mul(_BIP340_G, s), _bip340_mul(P, n - e))
+    if R is None or R[1] % 2 != 0 or R[0] != r:
+        return False
+    return True
+
+
+# ---------------------------------------------------------------------------
+# Nostr backend
+# ---------------------------------------------------------------------------
+
+def _require_nostr_deps():
+    try:
+        import coincurve  # noqa: F401
+        import websocket  # noqa: F401
+    except ImportError:
+        raise AnchorError(
+            "nostr anchoring needs the 'anchor' extra: "
+            "pip install aer1-haystack[anchor]"
+        )
+
+
+class NostrBackend:
+    """Anchor a Merkle root as a signed Nostr kind-1 event.
+
+    The event content is canonical JSON carrying ONLY the receipt_id,
+    the merkle_root, and the anchor timestamp. Signing uses an ephemeral
+    keypair by default (pass private_key_hex to use your own); the
+    security property is the public, multi-relay log, not key identity.
+    Verification is fully offline: recompute the event id and check the
+    BIP-340 signature with pure-python code (no coincurve needed).
+    """
+
+    name = "nostr"
+
+    def __init__(self, relays=None, private_key_hex=None, timeout=25,
+                 min_relays_ok=1):
+        self.relays = list(relays) if relays else list(DEFAULT_NOSTR_RELAYS)
+        self.private_key_hex = private_key_hex
+        self.timeout = timeout
+        self.min_relays_ok = min_relays_ok
+
+    # -- signing (needs coincurve) ------------------------------------------
+    def _keypair(self):
+        _require_nostr_deps()
+        from coincurve import PrivateKey
+
+        if self.private_key_hex:
+            sk = PrivateKey(bytes.fromhex(self.private_key_hex))
+            priv_hex = self.private_key_hex.lower()
+        else:
+            sk = PrivateKey(os.urandom(32))
+            priv_hex = sk.to_hex()
+        pubkey_hex = sk.public_key.format(compressed=True)[1:].hex()
+        return sk, priv_hex, pubkey_hex
+
+    def _build_event(self, merkle_root_hex, receipt_id, pubkey_hex):
+        content = _canonical(
+            {
+                "aer1_anchor": 1,
+                "receipt_id": receipt_id,
+                "merkle_root": merkle_root_hex,
+                "anchored_at": _now_rfc3339(),
+            }
+        ).decode("utf-8")
+        return {
+            "kind": _NOSTR_KIND,
+            "content": content,
+            "tags": [["t", "aer1-anchor"]],
+            "created_at": int(time.time()),
+            "pubkey": pubkey_hex,
+        }
+
+    @staticmethod
+    def event_id(event) -> str:
+        # NIP-01: sha256 of ["0", pubkey, created_at, kind, tags, content]
+        # with integer 0, no whitespace.
+        preimage = json.dumps(
+            [
+                0,
+                event["pubkey"],
+                event["created_at"],
+                event["kind"],
+                event["tags"],
+                event["content"],
+            ],
+            separators=(",", ":"),
+            ensure_ascii=False,
+        ).encode("utf-8")
+        return hashlib.sha256(preimage).hexdigest()
+
+    def _sign_event(self, event, sk) -> dict:
+        eid = self.event_id(event)
+        sig = sk.sign_schnorr(bytes.fromhex(eid)).hex()
+        return {**event, "id": eid, "sig": sig}
+
+    @staticmethod
+    def verify_event_signature(event) -> bool:
+        """Offline check: event id recomputes and the Schnorr sig is valid."""
+        try:
+            eid = NostrBackend.event_id(event)
+            if eid != event.get("id"):
+                return False
+            return bip340_verify(
+                bytes.fromhex(event["pubkey"]),
+                bytes.fromhex(eid),
+                bytes.fromhex(event["sig"]),
+            )
+        except (KeyError, ValueError, TypeError):
+            return False
+
+    # -- publish --------------------------------------------------------------
+    def _publish_one(self, relay, event) -> None:
+        import websocket
+
+        kwargs = {"timeout": self.timeout}
+        proxy = _proxy_from_env()
+        if proxy:
+            host, port, auth = proxy
+            kwargs["http_proxy_host"] = host
+            kwargs["http_proxy_port"] = port
+            if auth:
+                kwargs["http_proxy_auth"] = auth
+        ws = websocket.create_connection(relay, **kwargs)
+        try:
+            ws.send(json.dumps(["EVENT", event]))
+            raw = ws.recv()
+            msg = json.loads(raw)
+            if (
+                not isinstance(msg, list)
+                or len(msg) < 3
+                or msg[0] != "OK"
+                or msg[1] != event["id"]
+                or msg[2] is not True
+            ):
+                raise AnchorError(f"relay {relay} rejected event: {raw[:160]}")
+        finally:
+            try:
+                ws.close()
+            except Exception:
+                pass
+
+    def anchor(self, merkle_root_hex, receipt_id) -> dict:
+        _require_nostr_deps()
+        sk, _priv_hex, pubkey_hex = self._keypair()
+        event = self._sign_event(
+            self._build_event(merkle_root_hex, receipt_id, pubkey_hex), sk
+        )
+        ok_relays = []
+        errors = []
+        for relay in self.relays:
+            try:
+                self._publish_one(relay, event)
+                ok_relays.append(relay)
+            except Exception as e:  # noqa: BLE001 - collected, reported loudly
+                errors.append(f"{relay}: {e}")
+        if len(ok_relays) < self.min_relays_ok:
+            raise AnchorError(
+                f"nostr publish failed ({len(ok_relays)}/{self.min_relays_ok} "
+                f"relays ok): " + "; ".join(errors)
+            )
+        return {
+            "event_id": event["id"],
+            "pubkey": pubkey_hex,
+            "relays_ok": ok_relays,
+            "relays_tried": list(self.relays),
+            "event": event,
+            "anchored_at": _now_rfc3339(),
+        }
+
+    def verify(self, proof, merkle_root_hex, receipt_id) -> list:
+        failures = []
+        event = proof.get("event")
+        if not isinstance(event, dict):
+            return ["nostr proof has no event"]
+        if not self.verify_event_signature(event):
+            failures.append("nostr event signature invalid (or event id mismatch)")
+        try:
+            content = json.loads(event.get("content", ""))
+        except (ValueError, TypeError):
+            content = {}
+        if content.get("aer1_anchor") != 1:
+            failures.append("nostr event is not an aer1 anchor event")
+        if content.get("receipt_id") != receipt_id:
+            failures.append("nostr event receipt_id does not match")
+        if content.get("merkle_root") != merkle_root_hex:
+            failures.append("nostr event merkle_root does not match anchored root")
+        if proof.get("event_id") != event.get("id"):
+            failures.append("nostr proof event_id does not match event")
+        return failures
+
+
+# ---------------------------------------------------------------------------
+# OpenTimestamps backend (Bitcoin)
+# ---------------------------------------------------------------------------
+
+class OTSBackend:
+    """Anchor a Merkle root digest with OpenTimestamps calendar servers.
+
+    The 32-byte root is POSTed to each calendar's /digest endpoint; the
+    calendar returns a timestamp token attesting it saw the digest. The
+    tokens are assembled into standard .ots files (openable and
+    upgradeable with the reference opentimestamps-client). After roughly
+    an hour the pending calendar attestation can be upgraded to a
+    Bitcoin block attestation, which is what makes the "when" provable,
+    not just the "what".
+
+    v1 verification is offline: the .ots container must be well-formed,
+    its message must equal our digest (binds the proof to OUR root and
+    defeats proof substitution), and the attestation URI recorded at
+    anchor time must be present (binds the proof to the calendar that
+    attested). Full Bitcoin attestation verification is the documented
+    job of the reference client after `ots upgrade`.
+    """
+
+    name = "opentimestamps"
+
+    def __init__(self, calendars=None, timeout=30, min_calendars_ok=1):
+        self.calendars = list(calendars) if calendars else list(DEFAULT_OTS_CALENDARS)
+        self.timeout = timeout
+        self.min_calendars_ok = min_calendars_ok
+
+    @staticmethod
+    def build_ots_file(digest: bytes, timestamp: bytes) -> bytes:
+        out = bytearray(OTS_MAGIC)
+        out += b"\x01"  # version varuint
+        out += b"\x08"  # OpSHA256
+        out += digest
+        out += timestamp
+        return bytes(out)
+
+    @staticmethod
+    def parse_ots_file(data: bytes):
+        """Returns (digest, timestamp_bytes). Raises AnchorError if malformed."""
+        if not data.startswith(OTS_MAGIC):
+            raise AnchorError("ots file has bad magic")
+        pos = len(OTS_MAGIC)
+        version, pos = _read_varuint(data, pos)
+        if version != OTS_VERSION:
+            raise AnchorError(f"unsupported ots version {version}")
+        if pos >= len(data):
+            raise AnchorError("ots file truncated after version")
+        op = data[pos]
+        pos += 1
+        if op not in _OTS_OP_LEN:
+            raise AnchorError(f"unsupported ots digest op 0x{op:02x}")
+        digest_len = _OTS_OP_LEN[op]
+        digest = data[pos:pos + digest_len]
+        if len(digest) != digest_len:
+            raise AnchorError("ots file truncated in digest")
+        timestamp = data[pos + digest_len:]
+        if not timestamp:
+            raise AnchorError("ots file has empty timestamp")
+        return digest, timestamp
+
+    @staticmethod
+    def attestation_uris(timestamp: bytes) -> list:
+        return sorted({m.group().decode("utf-8") for m in _URI_RE.finditer(timestamp)})
+
+    def _submit(self, calendar: str, digest: bytes):
+        raw = _http_post_bytes(calendar.rstrip("/") + "/digest", digest, self.timeout)
+        if not raw:
+            raise AnchorError(f"empty timestamp from {calendar}")
+        return raw
+
+    def anchor(self, merkle_root_hex, receipt_id) -> dict:
+        digest = bytes.fromhex(merkle_root_hex)
+        files = []
+        errors = []
+        for calendar in self.calendars:
+            try:
+                ts = self._submit(calendar, digest)
+                ots = self.build_ots_file(digest, ts)
+                files.append(
+                    {
+                        "calendar": calendar,
+                        "ots_b64": base64.b64encode(ots).decode("ascii"),
+                        "attestation_uris": self.attestation_uris(ts),
+                    }
+                )
+            except Exception as e:  # noqa: BLE001 - collected, reported loudly
+                errors.append(f"{calendar}: {e}")
+        if len(files) < self.min_calendars_ok:
+            raise AnchorError(
+                f"opentimestamps failed ({len(files)}/{self.min_calendars_ok} "
+                f"calendars ok): " + "; ".join(errors)
+            )
+        return {
+            "digest_hex": merkle_root_hex,
+            "ots_files": files,
+            "calendars_tried": list(self.calendars),
+            "note": "pending calendar attestation; run `ots upgrade` after ~1h "
+                    "for the Bitcoin block attestation",
+            "anchored_at": _now_rfc3339(),
+        }
+
+    def verify(self, proof, merkle_root_hex, receipt_id) -> list:
+        failures = []
+        want = bytes.fromhex(merkle_root_hex)
+        files = proof.get("ots_files")
+        if not isinstance(files, list) or not files:
+            return ["opentimestamps proof has no ots files"]
+        for i, f in enumerate(files):
+            try:
+                raw = base64.b64decode(f["ots_b64"])
+                digest, ts = self.parse_ots_file(raw)
+            except Exception as e:  # noqa: BLE001
+                failures.append(f"ots file {i} malformed: {e}")
+                continue
+            if digest != want:
+                failures.append(
+                    f"ots file {i} commits to a different digest "
+                    "(proof substitution or forgery)"
+                )
+            recorded = f.get("attestation_uris") or []
+            found = self.attestation_uris(ts)
+            if recorded and not any(u in found for u in recorded):
+                failures.append(
+                    f"ots file {i} attestation uri mismatch "
+                    f"(recorded {recorded}, found {found})"
+                )
+        return failures
+
+
+_BACKENDS = {
+    NostrBackend.name: NostrBackend,
+    OTSBackend.name: OTSBackend,
+}
+
+
+# ---------------------------------------------------------------------------
+# one-line anchoring + verification
+# ---------------------------------------------------------------------------
+
+def _resolve_backends(backends, backend_kwargs):
+    """backends: tuple of names or dict name -> instance."""
+    if isinstance(backends, dict):
+        return list(backends.items())
+    resolved = []
+    for name in backends:
+        cls = _BACKENDS.get(name)
+        if cls is None:
+            raise ValueError(
+                f"unknown anchor backend {name!r}; known: {sorted(_BACKENDS)}"
+            )
+        resolved.append((name, cls(**backend_kwargs.get(name, {}))))
+    return resolved
+
+
+def anchor_chain_head(workflow, backends=("nostr", "opentimestamps"),
+                      backend_kwargs=None) -> dict:
+    """Anchor a workflow receipt's chain head. Returns the anchor proof.
+
+    The Merkle root is RECOMPUTED from the workflow's steps (never taken
+    from workflow["merkle_root"]), so an operator cannot anchor a fake
+    root for a receipt whose steps say otherwise. Raises AnchorError if
+    every backend fails; partial success returns a proof with per-backend
+    status. backends may be a tuple of names or a dict of name -> instance
+    (handy for tests).
+    """
+    steps = workflow.get("steps") or []
+    root = merkle_root([s["receipt_id"] for s in steps])
+    receipt_id = workflow.get("receipt_id")
+    entries = []
+    errors = []
+    for name, backend in _resolve_backends(backends, backend_kwargs or {}):
+        try:
+            proof = backend.anchor(root, receipt_id)
+            entries.append(
+                {
+                    "backend": name,
+                    "status": "confirmed",
+                    "proof": proof,
+                    "anchored_at": _now_rfc3339(),
+                }
+            )
+        except Exception as e:  # noqa: BLE001 - loud, listed, never silent
+            errors.append(f"{name}: {e}")
+            entries.append(
+                {
+                    "backend": name,
+                    "status": "failed",
+                    "error": str(e),
+                    "anchored_at": _now_rfc3339(),
+                }
+            )
+    if not any(e["status"] == "confirmed" for e in entries):
+        raise AnchorError("all anchor backends failed: " + "; ".join(errors))
+    return {
+        "format": PROOF_FORMAT,
+        "receipt_id": receipt_id,
+        "merkle_root": root,
+        "mode": "immediate",
+        "anchored_at": _now_rfc3339(),
+        "backends": entries,
+    }
+
+
+def verify_anchor(proof, workflow) -> list:
+    """Independently verify an anchor proof against a workflow receipt.
+
+    Returns a list of failure reasons; [] means the anchor is valid.
+    Needs no network for the core checks: the root is recomputed from
+    the receipt's steps, so truncation and fake-root anchoring are
+    caught offline. Anyone can run this with the proof JSON alone.
+    """
+    failures = []
+    if not isinstance(proof, dict):
+        return ["anchor proof is not a JSON object"]
+    if proof.get("format") != PROOF_FORMAT:
+        failures.append(f"unknown anchor proof format {proof.get('format')!r}")
+    if proof.get("receipt_id") != workflow.get("receipt_id"):
+        failures.append("anchor proof receipt_id does not match the receipt")
+    steps = workflow.get("steps") or []
+    recomputed = merkle_root([s["receipt_id"] for s in steps])
+    if proof.get("merkle_root") != recomputed:
+        failures.append(
+            "anchored merkle_root does not match the root recomputed from "
+            "the receipt steps (possible truncation or tampering: a dropped "
+            "tail changes the root)"
+        )
+        return failures  # root mismatch poisons every backend check
+    for entry in proof.get("backends") or []:
+        if entry.get("status") != "confirmed":
+            continue
+        name = entry.get("backend")
+        cls = _BACKENDS.get(name)
+        if cls is None:
+            failures.append(f"unknown backend {name!r} in proof")
+            continue
+        failures.extend(
+            f"{name}: {f}"
+            for f in cls().verify(entry.get("proof") or {}, recomputed,
+                                 workflow.get("receipt_id"))
+        )
+    return failures
+
+
+def proof_to_json(proof) -> str:
+    return json.dumps(proof, indent=2, ensure_ascii=False)
+
+
+def proof_from_json(text: str) -> dict:
+    return json.loads(text)