proofbundle 2.0.0b1__tar.gz → 2.0.0b3__tar.gz

{proofbundle-2.0.0b1/src/proofbundle.egg-info → proofbundle-2.0.0b3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: proofbundle
-Version: 2.0.0b1
+Version: 2.0.0b3
 Summary: Emit and verify portable cryptographic evidence bundles, offline: Ed25519 + RFC 6962 Merkle + optional SD-JWT.
 Author: Konrad Gruszka
 License: MIT
@@ -27,7 +27,12 @@ Requires-Dist: cryptography>=42
 Provides-Extra: sdjwt
 Provides-Extra: eval
 Requires-Dist: rfc8785>=0.1.4; extra == "eval"
+Provides-Extra: anchors
+Requires-Dist: rfc3161-client>=1.0.6; extra == "anchors"
+Requires-Dist: opentimestamps>=0.4.5; extra == "anchors"
+Requires-Dist: rfc8785>=0.1.4; extra == "anchors"
 Provides-Extra: adapters
+Provides-Extra: chia
 Provides-Extra: experimental
 Provides-Extra: pq
 Requires-Dist: cryptography>=48; extra == "pq"
@@ -56,15 +61,19 @@ Dynamic: license-file
 
 <h1>proofbundle</h1>
 
-**Turn an AI eval result into one portable, offline-verifiable receipt.**
-It proves *who signed these exact bytes* and *that nothing changed since* — not that the number is
-true. Ed25519 + RFC 6962 Merkle, one file, no server, no network.
+**AI eval results need receipts.**
+
+Turn an AI evaluation result into one portable, offline-verifiable receipt. It proves *who signed
+these exact bytes* and *that nothing changed since* — not that the number is true. Ed25519 + RFC 6962
+Merkle, one file, no server, no network.
 
 [![CI](https://github.com/b7n0de/proofbundle/actions/workflows/ci.yml/badge.svg)](https://github.com/b7n0de/proofbundle/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/proofbundle.svg)](https://pypi.org/project/proofbundle/)
+[![Python](https://img.shields.io/pypi/pyversions/proofbundle.svg)](https://pypi.org/project/proofbundle/)
 [![License: MIT](https://img.shields.io/badge/license-MIT-D6248A.svg)](LICENSE)
 [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
 [![Mutation tested](https://img.shields.io/badge/tests-mutation_gated-D6248A.svg)](scripts/mutation_check.py)
-<!-- PyPI / Downloads / SLSA / PEP 740 badges are enabled on the first PyPI release — see RELEASE.md. -->
+<!-- SLSA / PEP 740 attestation badges follow once the first attested release lands, see RELEASE.md. -->
 
 </div>
 
@@ -109,6 +118,13 @@ This boundary is the point, not a weakness. A receipt makes a claim **attributab
 and — with pre-registration and per-sample auditing — bounded and spot-checkable**. Full detail:
 **[THREAT_MODEL.md](THREAT_MODEL.md)**.
 
+## In plain language
+
+A proofbundle receipt is the cash-register receipt of an AI test result: it shows who claimed the
+number and that nobody quietly changed it afterwards. It does not show the test was good — the way a
+cash-register receipt does not show the meal was good — but without a receipt there is nothing to
+check at all.
+
 ## How it fits together
 
 ```mermaid
@@ -133,13 +149,24 @@ flowchart LR
 - **Transparency-log interop** — C2SP `tlog-checkpoint` / cosignature / `.tlog-proof`, with
   post-quantum **ML-DSA-44** witness cosignatures. Optional Token-Status-List revocation snapshots.
 - **Per-sample audit** — commit to every sample; an auditor challenges random indices (with a fresh
-  nonce or a **public randomness beacon**, v1.9) and openings must bind to the signed root. Catches
-  1% sample-doctoring with 95% confidence at 300 samples, regardless of run size.
+  nonce or a **public randomness beacon**, v1.9) and openings must bind to the signed root. With
+  such an auditor-supplied or beacon-bound challenge, 300 samples catch 1% sample-doctoring with 95%
+  confidence, regardless of run size — a challenge the issuer chose itself does not give this
+  guarantee.
 - **Pre-registration** — `proofbundle prereg <plan>` commits to the protocol before the run, so
   best-of-many publishing becomes visible.
 - **Integrations** — opt-in inspect_ai end-of-task hook and pytest plugin (emit only when
   `PROOFBUNDLE_EMIT=1` / `--proofbundle`), plus a Hugging Face Community Evals bridge. See
-  [INTEGRATIONS.md](INTEGRATIONS.md).
+  [INTEGRATIONS.md](INTEGRATIONS.md), or the end-to-end walkthrough
+  [docs/INSPECT_HAPPY_PATH.md](docs/INSPECT_HAPPY_PATH.md) — run an eval, get a receipt, verify it offline.
+- **External time anchors** *(v2.0 beta, the `[anchors]` extra)* — an optional `anchors[]` layer that
+  attaches external evidence of *when* a commitment or receipt existed, from a party the producer does not
+  control. Two built-in types verify offline: **RFC 3161** TSA tokens (against a frozen cert chain) and
+  **OpenTimestamps** Bitcoin proofs (honest pending → confirmed lifecycle). A `register_anchor_type`
+  extension interface lets a third party ship its own fail-closed type; two worked examples ship — a
+  first-party **`chia-datalayer/v1`** (offline Merkle inclusion of a canonical root under a published Chia
+  DataLayer root) and a third-party **`markovian-provenance/v1`** (a wallet-attributable, Bitcoin-anchored
+  stamp). See [docs/ANCHORS.md](docs/ANCHORS.md).
 
 ## Docs
 
@@ -154,6 +181,7 @@ flowchart LR
 | Honest comparison to Rekor / in-toto / OMS / ValiChord | [INTEROP.md](INTEROP.md) |
 | Regulatory mapping (and what to never claim) | [COMPLIANCE.md](COMPLIANCE.md) |
 | Funders / role fit | [docs/PROJECT_BRIEF.md](docs/PROJECT_BRIEF.md) |
+| External time anchors + the bring-your-own-type extension interface (v2.0 beta) | [docs/ANCHORS.md](docs/ANCHORS.md) |
 | **Preview:** TEE-attestation bridge (v2.0 beta) | [docs/EXPERIMENTAL_ENCLAVE.md](docs/EXPERIMENTAL_ENCLAVE.md) |
 
 ## Install
@@ -170,7 +198,7 @@ Requires Python 3.10+. The verify path never rolls its own crypto — Ed25519 co
 
 ## Status & scope
 
-Beta, SemVer-committed, 303 tests + a CI mutation gate + property-based parser fuzzing. Correctness
+Beta, SemVer-committed, with a CI test suite behind a mutation gate + property-based parser fuzzing. Correctness
 is anchored to external RFC 6962 vectors and a real Rekor proof, not just its own bundles. It is
 **not** a log service, a full in-toto client, a TEE, a consensus network, or a compliance product
 by itself — it is the small, offline, standards-native receipt layer between them. Security policy:

{proofbundle-2.0.0b1 → proofbundle-2.0.0b3}/README.md

@@ -7,15 +7,19 @@
 
 <h1>proofbundle</h1>
 
-**Turn an AI eval result into one portable, offline-verifiable receipt.**
-It proves *who signed these exact bytes* and *that nothing changed since* — not that the number is
-true. Ed25519 + RFC 6962 Merkle, one file, no server, no network.
+**AI eval results need receipts.**
+
+Turn an AI evaluation result into one portable, offline-verifiable receipt. It proves *who signed
+these exact bytes* and *that nothing changed since* — not that the number is true. Ed25519 + RFC 6962
+Merkle, one file, no server, no network.
 
 [![CI](https://github.com/b7n0de/proofbundle/actions/workflows/ci.yml/badge.svg)](https://github.com/b7n0de/proofbundle/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/proofbundle.svg)](https://pypi.org/project/proofbundle/)
+[![Python](https://img.shields.io/pypi/pyversions/proofbundle.svg)](https://pypi.org/project/proofbundle/)
 [![License: MIT](https://img.shields.io/badge/license-MIT-D6248A.svg)](LICENSE)
 [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
 [![Mutation tested](https://img.shields.io/badge/tests-mutation_gated-D6248A.svg)](scripts/mutation_check.py)
-<!-- PyPI / Downloads / SLSA / PEP 740 badges are enabled on the first PyPI release — see RELEASE.md. -->
+<!-- SLSA / PEP 740 attestation badges follow once the first attested release lands, see RELEASE.md. -->
 
 </div>
 
@@ -60,6 +64,13 @@ This boundary is the point, not a weakness. A receipt makes a claim **attributab
 and — with pre-registration and per-sample auditing — bounded and spot-checkable**. Full detail:
 **[THREAT_MODEL.md](THREAT_MODEL.md)**.
 
+## In plain language
+
+A proofbundle receipt is the cash-register receipt of an AI test result: it shows who claimed the
+number and that nobody quietly changed it afterwards. It does not show the test was good — the way a
+cash-register receipt does not show the meal was good — but without a receipt there is nothing to
+check at all.
+
 ## How it fits together
 
 ```mermaid
@@ -84,13 +95,24 @@ flowchart LR
 - **Transparency-log interop** — C2SP `tlog-checkpoint` / cosignature / `.tlog-proof`, with
   post-quantum **ML-DSA-44** witness cosignatures. Optional Token-Status-List revocation snapshots.
 - **Per-sample audit** — commit to every sample; an auditor challenges random indices (with a fresh
-  nonce or a **public randomness beacon**, v1.9) and openings must bind to the signed root. Catches
-  1% sample-doctoring with 95% confidence at 300 samples, regardless of run size.
+  nonce or a **public randomness beacon**, v1.9) and openings must bind to the signed root. With
+  such an auditor-supplied or beacon-bound challenge, 300 samples catch 1% sample-doctoring with 95%
+  confidence, regardless of run size — a challenge the issuer chose itself does not give this
+  guarantee.
 - **Pre-registration** — `proofbundle prereg <plan>` commits to the protocol before the run, so
   best-of-many publishing becomes visible.
 - **Integrations** — opt-in inspect_ai end-of-task hook and pytest plugin (emit only when
   `PROOFBUNDLE_EMIT=1` / `--proofbundle`), plus a Hugging Face Community Evals bridge. See
-  [INTEGRATIONS.md](INTEGRATIONS.md).
+  [INTEGRATIONS.md](INTEGRATIONS.md), or the end-to-end walkthrough
+  [docs/INSPECT_HAPPY_PATH.md](docs/INSPECT_HAPPY_PATH.md) — run an eval, get a receipt, verify it offline.
+- **External time anchors** *(v2.0 beta, the `[anchors]` extra)* — an optional `anchors[]` layer that
+  attaches external evidence of *when* a commitment or receipt existed, from a party the producer does not
+  control. Two built-in types verify offline: **RFC 3161** TSA tokens (against a frozen cert chain) and
+  **OpenTimestamps** Bitcoin proofs (honest pending → confirmed lifecycle). A `register_anchor_type`
+  extension interface lets a third party ship its own fail-closed type; two worked examples ship — a
+  first-party **`chia-datalayer/v1`** (offline Merkle inclusion of a canonical root under a published Chia
+  DataLayer root) and a third-party **`markovian-provenance/v1`** (a wallet-attributable, Bitcoin-anchored
+  stamp). See [docs/ANCHORS.md](docs/ANCHORS.md).
 
 ## Docs
 
@@ -105,6 +127,7 @@ flowchart LR
 | Honest comparison to Rekor / in-toto / OMS / ValiChord | [INTEROP.md](INTEROP.md) |
 | Regulatory mapping (and what to never claim) | [COMPLIANCE.md](COMPLIANCE.md) |
 | Funders / role fit | [docs/PROJECT_BRIEF.md](docs/PROJECT_BRIEF.md) |
+| External time anchors + the bring-your-own-type extension interface (v2.0 beta) | [docs/ANCHORS.md](docs/ANCHORS.md) |
 | **Preview:** TEE-attestation bridge (v2.0 beta) | [docs/EXPERIMENTAL_ENCLAVE.md](docs/EXPERIMENTAL_ENCLAVE.md) |
 
 ## Install
@@ -121,7 +144,7 @@ Requires Python 3.10+. The verify path never rolls its own crypto — Ed25519 co
 
 ## Status & scope
 
-Beta, SemVer-committed, 303 tests + a CI mutation gate + property-based parser fuzzing. Correctness
+Beta, SemVer-committed, with a CI test suite behind a mutation gate + property-based parser fuzzing. Correctness
 is anchored to external RFC 6962 vectors and a real Rekor proof, not just its own bundles. It is
 **not** a log service, a full in-toto client, a TEE, a consensus network, or a compliance product
 by itself — it is the small, offline, standards-native receipt layer between them. Security policy:

{proofbundle-2.0.0b1 → proofbundle-2.0.0b3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "proofbundle"
-version = "2.0.0b1"
+version = "2.0.0b3"
 description = "Emit and verify portable cryptographic evidence bundles, offline: Ed25519 + RFC 6962 Merkle + optional SD-JWT."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -44,8 +44,19 @@ sdjwt = []
 # path (verify_bundle / decode_eval_claim) never canonicalizes — it checks stored bytes — so the
 # verifier stays dependency-free. `pip install proofbundle[eval]` adds emit-side canonicalization.
 eval = ["rfc8785>=0.1.4"]
+# EXPERIMENTAL: external time anchors (proofbundle.anchors) — RFC 3161 TSA + OpenTimestamps. Opt-in and
+# clearly experimental (API/format may change). rfc3161-client (Trail of Bits) is deliberately offline —
+# it verifies an RFC 3161 token against bundled roots, no network in the verify path. opentimestamps is
+# the OTS proof library. rfc8785 gives the receipt its canonical (JCS) root. The base install stays
+# anchor-free (only cryptography); a receipt with no anchors verifies unchanged.
+anchors = ["rfc3161-client>=1.0.6", "opentimestamps>=0.4.5", "rfc8785>=0.1.4"]
 # The lm-eval adapter reads exported results.json (no import) → pure stdlib.
 adapters = []
+# chia-datalayer/v1 anchor WRITER (anchors_chia_add). Needs no extra Python package — it drives the
+# stable `chia rpc data_layer|full_node` CLI of a locally installed, cert-authed Chia node (the DataLayer
+# node is the real dependency, not a wheel). Declared so `pip install proofbundle[chia]` is a documented,
+# discoverable install target. VERIFYING an anchor offline (anchors_chia) needs neither this nor a node.
+chia = []
 # EXPERIMENTAL (v2.0 preview): the TEE-attestation bridge (proofbundle.experimental.enclave).
 # Opt-in and clearly unstable — API/wire-format may change or be removed without deprecation.
 # No new runtime dependency (pure stdlib + the core `cryptography`); the extra exists to signal

{proofbundle-2.0.0b1 → proofbundle-2.0.0b3}/src/proofbundle/__init__.py

@@ -13,7 +13,7 @@ from __future__ import annotations
 
 from typing import TYPE_CHECKING
 
-__version__ = "2.0.0b1"
+__version__ = "2.0.0b3"
 
 __all__ = [
     "__version__",

proofbundle-2.0.0b3/src/proofbundle/anchors.py

@@ -0,0 +1,194 @@
+"""Generic external time-anchor layer for proofbundle receipts (EXPERIMENTAL; `[anchors]` extra).
+
+An **anchor** is external evidence that a target existed at (or before) a time — something the receipt's
+own Ed25519 + Merkle structure cannot establish on its own, because a self-emitted timestamp is only
+producer-clock testimony. Two targets, **never mixed**:
+
+* ``preRegistration`` — "the commitment existed BEFORE the run" (backdating protection; the point raised
+  in in-toto/attestation#565).
+* ``receipt`` — "the receipt existed from time T" (publication proof).
+
+Each ``anchors[]`` entry is ``{type, target, canonicalRoot, proof, anchoredAt}``:
+
+* ``type`` — ``rfc3161-tsa`` | ``opentimestamps`` | ``<extension>/vN``.
+* ``target`` — ``receipt`` | ``preRegistration`` (see above).
+* ``canonicalRoot`` — base64 of the canonical root of the target: for ``receipt`` the RFC 8785 (JCS)
+  sha256 of the receipt bundle; for ``preRegistration`` the sha256 of the raw protocol bytes (the
+  receipt's ``prereg_sha256``). The anchor timestamps THIS root.
+* ``proof`` — base64 of the type-specific proof (an RFC 3161 token, an OpenTimestamps proof, ...).
+* ``anchoredAt`` — RFC 3339 Z, INFORMATIVE only (the trusted time comes from the proof, not this field).
+
+**Verify contract (fail-closed).** Missing/empty ``anchors`` → SKIP (never FAIL — consistent with
+in-toto's Monotonic Principle: deny only when an attestation is present and wrong). Present → fail-closed:
+a root mismatch, an unknown type, or a broken proof is a FAIL, never silent. ``require`` (CLI
+``--require-anchor <type|any>``) turns "no verifying anchor" into a FAIL.
+
+**Cross-target safety.** ``canonicalRoot`` is compared to the root of the anchor's OWN ``target`` — a
+``preRegistration`` anchor can never validate a ``receipt`` target and vice versa (the roots differ).
+
+**Lean core.** This module is pure dispatch + schema; the RFC 3161 / OpenTimestamps verifiers lazy-import
+their libraries and are only needed with the ``[anchors]`` extra. The base install pulls only
+``cryptography``; a bundle with no anchors verifies unchanged. Anchoring writes a NEW file — a network
+error while stamping never corrupts the local receipt.
+"""
+from __future__ import annotations
+
+import base64
+import binascii
+import hashlib
+from typing import Callable, Optional
+
+from .errors import BundleFormatError
+
+ANCHOR_TARGETS = ("receipt", "preRegistration")
+_ANCHOR_KEYS = {"type", "target", "canonicalRoot", "proof", "anchoredAt", "frozen"}
+
+# type name -> verifier callable:
+#   (proof: bytes, canonical_root: bytes, *, frozen: dict, now: Optional[int]) -> {"ok": bool, "detail": str}
+_VERIFIERS: dict[str, Callable] = {}
+
+
+def register_anchor_type(type_name: str, verifier: Callable) -> None:
+    """Register a verifier for an anchor ``type``. A third party ships its own type this way (see
+    docs/ANCHORS.md). The verifier MUST be fail-closed: return ``{"ok": False, ...}`` on any doubt,
+    never raise for an ordinary bad proof."""
+    if not type_name or not isinstance(type_name, str) or not callable(verifier):
+        raise BundleFormatError("register_anchor_type needs a non-empty name and a callable verifier")
+    _VERIFIERS[type_name] = verifier
+
+
+def registered_anchor_types() -> tuple:
+    _ensure_builtin_types()
+    return tuple(sorted(_VERIFIERS))
+
+
+def _ensure_builtin_types() -> None:
+    """Lazily register the built-in anchor verifiers (rfc3161-tsa, opentimestamps). Each needs the
+    ``[anchors]`` extra; if a library is absent the type stays UNREGISTERED — which the verify path
+    treats as an unknown type → FAIL (fail-closed), exactly the behaviour we want without the extra."""
+    if "rfc3161-tsa" not in _VERIFIERS:
+        try:
+            from . import anchors_rfc3161  # noqa: PLC0415
+            _VERIFIERS["rfc3161-tsa"] = anchors_rfc3161.verify_rfc3161
+        except Exception:   # extra missing / import failure → leave unregistered (fail-closed)
+            pass
+    if "opentimestamps" not in _VERIFIERS:
+        try:
+            from . import anchors_ots  # noqa: PLC0415
+            _VERIFIERS["opentimestamps"] = anchors_ots.verify_opentimestamps
+        except Exception:
+            pass
+    # chia-datalayer/v1: the first FIRST-PARTY extension anchor. Its offline Merkle verifier (level i) is
+    # PURE SHA-256 — no Chia software, no extra — so it always registers (writing an anchor via anchor-add
+    # needs the [chia] extra + a node, but VERIFYING one offline does not).
+    if "chia-datalayer/v1" not in _VERIFIERS:
+        try:
+            from . import anchors_chia  # noqa: PLC0415
+            _VERIFIERS[anchors_chia.ANCHOR_TYPE] = anchors_chia.verify_chia_datalayer
+        except Exception:   # pragma: no cover - pure module, import should not fail
+            pass
+
+
+def _b64d(value, field: str) -> bytes:
+    if not isinstance(value, str):
+        raise BundleFormatError(f"anchor {field} must be a base64 string")
+    try:
+        return base64.b64decode(value, validate=True)
+    except (ValueError, binascii.Error) as exc:
+        raise BundleFormatError(f"anchor {field} is not valid base64") from exc
+
+
+def receipt_canonical_root(bundle: dict) -> bytes:
+    """The RFC 8785 (JCS) sha256 of the receipt bundle — the canonical root a ``receipt`` anchor stamps.
+    Uses a real RFC 8785 canonicalizer (the ``[anchors]``/``[eval]`` extra); never a home-grown sort."""
+    try:
+        import rfc8785  # noqa: PLC0415
+    except ImportError as exc:   # pragma: no cover - guarded by the extra
+        raise BundleFormatError(
+            "receipt anchoring needs the RFC 8785 canonicalizer — install proofbundle[anchors]") from exc
+    return hashlib.sha256(rfc8785.dumps(bundle)).digest()
+
+
+def prereg_canonical_root(prereg_sha256_hex: str) -> bytes:
+    """The canonical root a ``preRegistration`` anchor stamps: the sha256 (raw bytes) of the eval
+    protocol file, i.e. the receipt's ``prereg_sha256``."""
+    if not isinstance(prereg_sha256_hex, str) or len(prereg_sha256_hex) != 64:
+        raise BundleFormatError("prereg canonical root needs a 64-char hex sha256")
+    try:
+        return bytes.fromhex(prereg_sha256_hex)
+    except ValueError as exc:
+        raise BundleFormatError("prereg_sha256 is not valid hex") from exc
+
+
+def verify_anchor(anchor: dict, *, target_roots: dict, now: Optional[int] = None) -> dict:
+    """Verify ONE anchor entry, fail-closed. ``target_roots`` maps a target name to its canonical root
+    bytes (only the targets that exist for this receipt). Returns ``{ok, type, target, detail}``."""
+    _ensure_builtin_types()
+    if not isinstance(anchor, dict):
+        raise BundleFormatError("each anchor must be a JSON object")
+    unknown = set(anchor) - _ANCHOR_KEYS
+    if unknown:
+        raise BundleFormatError(f"anchor has unknown field(s) {sorted(unknown)}")
+    atype = anchor.get("type")
+    target = anchor.get("target")
+    out = {"ok": False, "warn": False, "status": "fail", "type": atype, "target": target, "detail": ""}
+    if target not in ANCHOR_TARGETS:
+        out["detail"] = f"anchor target must be one of {ANCHOR_TARGETS}"
+        return out
+    if not isinstance(atype, str) or atype not in _VERIFIERS:
+        # Unknown type is a FAIL, not a SKIP — an anchor we cannot check must never pass silently.
+        out["detail"] = (f"no verifier registered for anchor type {atype!r} "
+                         "(install proofbundle[anchors] or register the extension type)")
+        return out
+    expected_root = target_roots.get(target)
+    if expected_root is None:
+        out["detail"] = f"the receipt has no {target} target to anchor against"
+        return out
+    canonical_root = _b64d(anchor.get("canonicalRoot"), "canonicalRoot")
+    if canonical_root != expected_root:
+        # cross-target safety: a preRegistration anchor's root never equals the receipt root, and v.v.
+        out["detail"] = f"canonicalRoot does not match the {target} root (cross-target or tampered)"
+        return out
+    proof = _b64d(anchor.get("proof"), "proof")
+    try:
+        res = _VERIFIERS[atype](proof, canonical_root, frozen=anchor.get("frozen") or {}, now=now)
+    except Exception as exc:   # a verifier must be fail-closed; if it raises, treat as FAIL, never pass
+        out["detail"] = f"anchor verifier error (fail-closed): {exc}"
+        return out
+    out["ok"] = bool(res.get("ok"))
+    out["warn"] = bool(res.get("warn"))
+    out["status"] = res.get("status") or ("pass" if out["ok"] else ("warn" if out["warn"] else "fail"))
+    out["detail"] = res.get("detail", "")
+    return out
+
+
+def verify_anchors(anchors, *, target_roots: dict, require: Optional[str] = None,
+                   now: Optional[int] = None) -> dict:
+    """Verify a receipt's ``anchors``. Missing/empty → SKIP (unless ``require`` is set → FAIL). Present →
+    fail-closed PASS/FAIL over every entry. ``require`` is ``None`` | ``'any'`` | a type string; when set,
+    at least one anchor of that type (or any) must verify. Returns ``{status, detail, results}`` with
+    ``status`` in {PASS, FAIL, SKIP}."""
+    if not anchors:
+        if require:
+            return {"status": "FAIL", "detail": f"--require-anchor {require} set but the receipt has no anchors",
+                    "results": []}
+        return {"status": "SKIP", "detail": "no external time anchors present", "results": []}
+    if not isinstance(anchors, list):
+        raise BundleFormatError("anchors must be a list")
+    results = [verify_anchor(a, target_roots=target_roots, now=now) for a in anchors]
+    if require:   # a warn/pending/inclusion-only anchor never SATISFIES a requirement — only a full one
+        want = None if require == "any" else require
+        matched = [r for r in results if r["ok"] and not r["warn"] and (want is None or r["type"] == want)]
+        if not matched:
+            return {"status": "FAIL",
+                    "detail": f"--require-anchor {require}: no verifying anchor of that type",
+                    "results": results}
+    hard_fail = any(not r["ok"] and not r["warn"] for r in results)
+    if hard_fail:
+        status = "FAIL"                       # a broken/unbound/unknown anchor is never silent
+    elif any(r["warn"] for r in results):
+        status = "WARN"                       # e.g. a PENDING OpenTimestamps proof — not a full anchor yet
+    else:
+        status = "PASS"
+    detail = f"{sum(r['ok'] for r in results)}/{len(results)} anchor(s) verified"
+    return {"status": status, "detail": detail, "results": results}

proofbundle-2.0.0b3/src/proofbundle/anchors_chia.py

@@ -0,0 +1,196 @@
+"""Chia DataLayer anchor (``chia-datalayer/v1``) — the first first-party extension anchor type.
+
+This is the **offline Merkle verifier** (level i of the three-level honesty documented in ``docs/ANCHORS.md``):
+it proves, with **pure SHA-256 and NO Chia software**, that a key/value pair is included under a published
+DataLayer root. It does NOT prove the chain binding (that the ``published_root`` is actually an unspent
+singleton on the heaviest chain) — that is level ii (light wallet) / level iii (own full node), which need
+Chia software and are reported separately, never conflated here.
+
+Wire facts (Chia 2.7.x / chia_rs datalayer, pinned in the adapter spec; re-check against the live version
+before trusting — Chia moves modules): a DataLayer ``get_proof`` yields, per key:
+
+    key_clvm_hash  = CLVM tree hash of the key atom   = sha256(0x01 ‖ key_atom)
+    value_clvm_hash= CLVM tree hash of the value atom = sha256(0x01 ‖ value_atom)
+    node_hash (leaf) = sha256(0x02 ‖ key_clvm_hash ‖ value_clvm_hash)
+    internal node    = sha256(0x02 ‖ left ‖ right)
+    ascent: each layer carries other_hash_side (0=LEFT sibling / 1=RIGHT sibling), other_hash, combined_hash
+    root = layers[-1].combined_hash   (or node_hash when layers == [])
+
+The anchor's ``proof`` field (base64 in the bundle, decoded to bytes by ``verify_anchor``) is the **UTF-8 JSON**
+of a proof object with those hex fields; ``canonical_root`` is the ``value_digest`` the anchor stamps.
+
+Fail-closed: any structural problem, hash mismatch, or ascent inconsistency returns ``{"ok": False, ...}``.
+Never raises for an ordinary bad proof.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from typing import Optional
+
+ANCHOR_TYPE = "chia-datalayer/v1"
+
+# CLVM tree-hash / node-hash domain-separation prefixes (Chia DataLayer Merkle set).
+_ATOM_PREFIX = b"\x01"   # sha256(0x01 ‖ atom) = CLVM tree hash of an atom
+_NODE_PREFIX = b"\x02"   # sha256(0x02 ‖ left ‖ right) = internal/leaf node hash
+
+_HASH_LEN = 32           # sha256 digest length
+_MAX_LAYERS = 256        # a DataLayer tree of 2**256 leaves is absurd; bound the ascent (DoS guard)
+_MAX_PROOF_BYTES = 131072  # real chia-datalayer proofs are ~2.5 KB; cap the input before json.loads (DoS guard)
+
+
+def _h(*parts: bytes) -> bytes:
+    m = hashlib.sha256()
+    for p in parts:
+        m.update(p)
+    return m.digest()
+
+
+def _hexatom(value, field: str) -> bytes:
+    """Decode an arbitrary-length hex string (optionally 0x-prefixed) to bytes. DataLayer keys/values are
+    atoms of any length — only the HASHES are fixed at 32 bytes (see _hexbytes)."""
+    if not isinstance(value, str):
+        raise ValueError(f"{field} must be a hex string")
+    s = value[2:] if value[:2] in ("0x", "0X") else value
+    return bytes.fromhex(s)   # raises ValueError on non-hex / odd length
+
+
+def _hexbytes(value, field: str) -> bytes:
+    """Decode a 32-byte hash hex string (optionally 0x-prefixed) to bytes, else raise ValueError."""
+    b = _hexatom(value, field)
+    if len(b) != _HASH_LEN:
+        raise ValueError(f"{field} must be {_HASH_LEN} bytes (got {len(b)})")
+    return b
+
+
+def clvm_atom_hash(atom: bytes) -> bytes:
+    """CLVM tree hash of a raw atom: sha256(0x01 ‖ atom). Public helper (Paket 1 anchor-add reuses it)."""
+    return _h(_ATOM_PREFIX, atom)
+
+
+def leaf_node_hash(key_clvm_hash: bytes, value_clvm_hash: bytes) -> bytes:
+    """DataLayer leaf hash: sha256(0x02 ‖ key_clvm_hash ‖ value_clvm_hash)."""
+    return _h(_NODE_PREFIX, key_clvm_hash, value_clvm_hash)
+
+
+def merkle_root_from_layers(node_hash: bytes, inclusion_layers: list) -> bytes:
+    """Recompute the DataLayer root by ascending ``inclusion_layers`` from ``node_hash``.
+
+    Each layer is ``{"other_hash_side": 0|1, "other_hash": hex, "combined_hash": hex}``. ``other_hash_side``
+    is the side of the SIBLING: 0 = sibling on the LEFT → sha256(0x02 ‖ other ‖ cur); 1 = sibling on the
+    RIGHT → sha256(0x02 ‖ cur ‖ other). Each layer's declared ``combined_hash`` MUST equal the recomputed
+    value (fail-closed) — this is what makes the proof self-consistent, not just plausible.
+
+    Returns the root bytes. Raises ValueError on any structural/consistency problem.
+    """
+    if not isinstance(inclusion_layers, list):
+        raise ValueError("inclusion_layers must be a list")
+    if len(inclusion_layers) > _MAX_LAYERS:
+        raise ValueError("inclusion_layers too deep")
+    cur = node_hash
+    for i, layer in enumerate(inclusion_layers):
+        if not isinstance(layer, dict):
+            raise ValueError(f"layer {i} must be an object")
+        side = layer.get("other_hash_side")
+        if side not in (0, 1):
+            raise ValueError(f"layer {i} other_hash_side must be 0 (LEFT) or 1 (RIGHT)")
+        other = _hexbytes(layer.get("other_hash"), f"layer {i} other_hash")
+        declared = _hexbytes(layer.get("combined_hash"), f"layer {i} combined_hash")
+        combined = _h(_NODE_PREFIX, other, cur) if side == 0 else _h(_NODE_PREFIX, cur, other)
+        if combined != declared:
+            raise ValueError(f"layer {i} combined_hash inconsistent with the recomputed hash")
+        cur = combined
+    return cur
+
+
+def verify_offline_merkle(proof_obj: dict, canonical_root: bytes) -> dict:
+    """Pure offline verification (level i). ``proof_obj`` is the decoded chia-datalayer proof dict.
+
+    The BINDING to the target is via the DataLayer KEY: the anchor's ``canonicalRoot`` IS the key stored in
+    the store (``key = canonicalRoot``), so the proof must carry the raw ``key``, it must EQUAL
+    ``canonical_root``, and it must be the atom that hashes (``sha256(0x01‖key)``) to ``key_clvm_hash`` — whose
+    leaf ascends through ``inclusion_layers`` to ``published_root``. This ties ``canonical_root``
+    cryptographically to the Merkle path; an unrelated (even genuine) proof for a DIFFERENT key can no longer
+    be relabelled to this target by swapping a decoupled digest field.
+
+    Checks, all fail-closed:
+      1. raw ``key`` present AND == ``canonical_root`` AND ``sha256(0x01‖key) == key_clvm_hash``
+      2. (optional) raw ``value`` → ``sha256(0x01‖value) == value_clvm_hash``
+      3. leaf ``node_hash == sha256(0x02‖key_clvm‖value_clvm)`` (when declared)
+      4. ascending ``inclusion_layers`` reproduces ``published_root`` (each layer's combined_hash self-consistent)
+
+    Proves ONLY that ``canonical_root`` is a key included under ``published_root``; NOT that ``published_root``
+    is on-chain (that is level ii/iii, needs Chia software — see docs/ANCHORS.md).
+    """
+    try:
+        key_clvm = _hexbytes(proof_obj.get("key_clvm_hash"), "key_clvm_hash")
+        value_clvm = _hexbytes(proof_obj.get("value_clvm_hash"), "value_clvm_hash")
+        published_root = _hexbytes(proof_obj.get("published_root"), "published_root")
+        layers = proof_obj.get("inclusion_layers")
+
+        # (1) BINDING — the raw DataLayer key IS the target canonicalRoot, and it is the atom under key_clvm_hash.
+        raw_key = proof_obj.get("key")
+        if not isinstance(raw_key, str) or not raw_key:
+            return {"ok": False, "detail": "proof missing the raw key (required to bind canonicalRoot to the leaf)"}
+        key_bytes = _hexatom(raw_key, "key")
+        if key_bytes != canonical_root:
+            return {"ok": False, "detail": "the anchored DataLayer key does not equal the target canonicalRoot (cross-target/tampered/forged)"}
+        if clvm_atom_hash(key_bytes) != key_clvm:
+            return {"ok": False, "detail": "key_clvm_hash does not match sha256(0x01 || key)"}
+
+        # (2) optional: raw value atom (ANY length) → value_clvm_hash
+        raw_value = proof_obj.get("value")
+        if isinstance(raw_value, str) and raw_value:
+            if clvm_atom_hash(_hexatom(raw_value, "value")) != value_clvm:
+                return {"ok": False, "detail": "value_clvm_hash does not match sha256(0x01 || value)"}
+
+        # (3) leaf hash
+        leaf = leaf_node_hash(key_clvm, value_clvm)
+        declared_node = proof_obj.get("node_hash")
+        if declared_node is not None and _hexbytes(declared_node, "node_hash") != leaf:
+            return {"ok": False, "detail": "node_hash does not match sha256(0x02 || key_clvm || value_clvm)"}
+
+        # (4) ascend to the root
+        root = merkle_root_from_layers(leaf, layers if layers is not None else [])
+        if root != published_root:
+            return {"ok": False, "detail": "inclusion_layers do not reproduce published_root (not included)"}
+
+    except ValueError as exc:
+        return {"ok": False, "detail": f"malformed chia-datalayer proof: {exc}"}
+    return {"ok": True, "detail": "chia-datalayer merkle: canonicalRoot (as DataLayer key) included under published_root (level i, offline; chain binding NOT checked here)"}
+
+
+def verify_chia_datalayer(proof: bytes, canonical_root: bytes, *, frozen: Optional[dict] = None,
+                          now: Optional[int] = None) -> dict:
+    """Registered anchor verifier for ``chia-datalayer/v1`` (see ``register_anchor_type``).
+
+    ``proof`` is the UTF-8 JSON of the proof object; ``canonical_root`` is the target's root bytes. Returns
+    ``{"ok", "warn", "status", "detail"}``, fail-closed. LEVEL i ONLY: proves the Merkle inclusion under the
+    published root offline; it deliberately does NOT assert the chain binding (an anchor that is Merkle-valid
+    but whose published_root was never on-chain would pass HERE — the honest, documented boundary; a relying
+    party who needs the chain binding runs level ii/iii with Chia software, see docs/ANCHORS.md).
+    """
+    if not isinstance(proof, (bytes, bytearray)):
+        return {"ok": False, "warn": False, "status": "fail", "detail": "chia-datalayer proof must be bytes"}
+    if len(proof) > _MAX_PROOF_BYTES:
+        return {"ok": False, "warn": False, "status": "fail", "detail": f"chia-datalayer proof too large (> {_MAX_PROOF_BYTES} bytes)"}
+    # Unconditional fail-closed backstop: a verifier must NEVER crash its caller on a hostile proof. Enumerating
+    # exception types (ValueError, ...) misses RecursionError (deeply nested JSON), MemoryError, or a TypeError
+    # from a non-bytes canonical_root — all of which a caller-controlled proof could trigger. Catch everything.
+    try:
+        proof_obj = json.loads(bytes(proof).decode("utf-8"))
+        if not isinstance(proof_obj, dict):
+            return {"ok": False, "warn": False, "status": "fail", "detail": "chia-datalayer proof JSON must be an object"}
+        res = verify_offline_merkle(proof_obj, bytes(canonical_root))
+    except Exception as exc:   # noqa: BLE001 - deliberate fail-closed backstop for ANY hostile input
+        return {"ok": False, "warn": False, "status": "fail", "detail": f"chia-datalayer proof rejected (fail-closed): {type(exc).__name__}"}
+    if not bool(res.get("ok")):
+        return {"ok": False, "warn": False, "status": "fail", "detail": res.get("detail", "")}
+    # LEVEL i is proven (offline Merkle inclusion) → ok=True. But level i is NOT external time / chain-binding
+    # evidence: a self-fabricated tree with a never-on-chain published_root passes here (the documented
+    # boundary). So this is marked warn=True (status 'warn'), exactly like an un-upgraded OpenTimestamps
+    # PENDING proof — it must NOT satisfy --require-anchor and it aggregates as WARN, never a clean PASS that
+    # would read as a full external-time anchor. A relying party who needs the chain binding runs level
+    # ii/iii with Chia software (see docs/ANCHORS.md); the require-matcher gates on ok AND NOT warn.
+    return {"ok": True, "warn": True, "status": "warn", "detail": res.get("detail", "")}