proofbundle 2.0.0b1__tar.gz → 2.0.0b2__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: proofbundle
-Version: 2.0.0b1
+Version: 2.0.0b2
 Summary: Emit and verify portable cryptographic evidence bundles, offline: Ed25519 + RFC 6962 Merkle + optional SD-JWT.
 Author: Konrad Gruszka
 License: MIT
@@ -27,6 +27,10 @@ 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: experimental
 Provides-Extra: pq
@@ -56,9 +60,11 @@ 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)
 [![License: MIT](https://img.shields.io/badge/license-MIT-D6248A.svg)](LICENSE)
@@ -109,6 +115,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 +146,16 @@ 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.
 
 ## Docs
 
@@ -170,7 +186,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.0b2}/README.md

@@ -7,9 +7,11 @@
 
 <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)
 [![License: MIT](https://img.shields.io/badge/license-MIT-D6248A.svg)](LICENSE)
@@ -60,6 +62,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 +93,16 @@ 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.
 
 ## Docs
 
@@ -121,7 +133,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.0b2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "proofbundle"
-version = "2.0.0b1"
+version = "2.0.0b2"
 description = "Emit and verify portable cryptographic evidence bundles, offline: Ed25519 + RFC 6962 Merkle + optional SD-JWT."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -44,6 +44,12 @@ 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 = []
 # EXPERIMENTAL (v2.0 preview): the TEE-attestation bridge (proofbundle.experimental.enclave).

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

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

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

@@ -0,0 +1,185 @@
+"""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
+
+
+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 anchor never SATISFIES a requirement — only a real verified one
+        want = None if require == "any" else require
+        matched = [r for r in results if r["ok"] 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.0b2/src/proofbundle/anchors_ots.py

@@ -0,0 +1,91 @@
+"""OpenTimestamps anchor (EXPERIMENTAL; the `[anchors]` extra).
+
+Honest lifecycle (this is where OTS is easy to over-claim):
+
+* A fresh stamp is submitted to public calendars and is **PENDING** — it commits your root but is not
+  yet anchored in Bitcoin. A pending proof is a WARN, never a full-strength anchor.
+* ``ots upgrade`` embeds the Bitcoin block-header path; only then is the proof **upgraded** and
+  self-contained (no calendar needed to verify).
+* Verifying an upgraded proof still needs the Bitcoin **block header** for the attested height — per the
+  documented client path, a local (pruned) Bitcoin node. There is no documented "header file instead of
+  a node" mode, and we do not claim one. If the caller supplies the block header (its Merkle root) in the
+  anchor's ``frozen`` block, we verify against it offline; otherwise we report, honestly, that the proof
+  is upgraded but Bitcoin verification needs a node/header — we never silently PASS it.
+
+``proof`` is the serialized detached OTS proof; ``canonicalRoot`` is the exact bytes that were stamped.
+"""
+from __future__ import annotations
+
+from typing import Optional
+
+
+def _classify(timestamp):
+    """Return (has_bitcoin, bitcoin_heights, has_pending) over all attestations in the proof."""
+    from opentimestamps.core.notary import (  # noqa: PLC0415
+        BitcoinBlockHeaderAttestation, PendingAttestation,
+    )
+    heights, has_pending = [], False
+    for _msg, att in timestamp.all_attestations():
+        if isinstance(att, BitcoinBlockHeaderAttestation):
+            heights.append(att.height)
+        elif isinstance(att, PendingAttestation):
+            has_pending = True
+    return (bool(heights), heights, has_pending)
+
+
+def verify_opentimestamps(proof: bytes, canonical_root: bytes, *, frozen: dict,
+                          now: Optional[int] = None) -> dict:
+    """Fail-closed OTS verify. Returns {ok, detail, warn, status}. A pending proof is warn (status
+    'pending'); an upgraded proof with no supplied block header is not-ok-but-not-warn honest report
+    (status 'upgraded_unverified'); an upgraded proof verified against a supplied header is ok (status
+    'confirmed')."""
+    try:
+        from opentimestamps.core.serialize import BytesDeserializationContext  # noqa: PLC0415
+        from opentimestamps.core.timestamp import DetachedTimestampFile  # noqa: PLC0415
+    except ImportError:
+        return {"ok": False, "warn": False, "status": "no_lib",
+                "detail": "opentimestamps anchor needs proofbundle[anchors] (opentimestamps)"}
+    try:
+        dtf = DetachedTimestampFile.deserialize(BytesDeserializationContext(proof))
+    except Exception as exc:   # any malformed proof → FAIL (fail-closed)
+        return {"ok": False, "warn": False, "status": "malformed",
+                "detail": f"OTS proof did not deserialize: {exc}"}
+    # structural binding: the proof must commit to EXACTLY the canonical root
+    if dtf.file_digest != canonical_root:
+        return {"ok": False, "warn": False, "status": "unbound",
+                "detail": "OTS proof does not commit to the target canonical root"}
+    has_bitcoin, heights, has_pending = _classify(dtf.timestamp)
+    if not has_bitcoin:
+        if has_pending:
+            return {"ok": False, "warn": True, "status": "pending",
+                    "detail": "OTS proof is PENDING (submitted to calendars, not yet on Bitcoin) — "
+                              "run `ots upgrade`; not a full anchor yet"}
+        return {"ok": False, "warn": False, "status": "empty",
+                "detail": "OTS proof has no Bitcoin or pending attestation"}
+    # upgraded: to verify offline we need the block's Merkle root for the attested height, supplied by a
+    # trusted (local pruned) Bitcoin node — proofbundle never fetches it. BitcoinBlockHeaderAttestation's
+    # own check is exactly `attestation_message == block_header.hashMerkleRoot`; we do that comparison
+    # directly against the supplied root (equivalent, and avoids reconstructing a full CBlockHeader).
+    headers = frozen.get("bitcoinBlockHeaderMerkleRootsByHeight") or {}
+    for msg, att in dtf.timestamp.all_attestations():
+        height = getattr(att, "height", None)
+        if height is None:
+            continue
+        merkle_root_hex = headers.get(str(height))
+        if not merkle_root_hex:
+            continue
+        try:
+            expected = bytes.fromhex(merkle_root_hex)
+        except ValueError:
+            return {"ok": False, "warn": False, "status": "bad_header",
+                    "detail": f"supplied Bitcoin block merkle root for height {height} is not valid hex"}
+        if msg == expected:
+            return {"ok": True, "warn": False, "status": "confirmed",
+                    "detail": f"OTS proof confirmed: committed in the Bitcoin block at height {height} "
+                              "(merkle root supplied by a trusted node)"}
+        return {"ok": False, "warn": False, "status": "block_mismatch",
+                "detail": f"OTS Bitcoin attestation at height {height} does not match the supplied "
+                          "block merkle root"}
+    return {"ok": False, "warn": False, "status": "upgraded_unverified",
+            "detail": f"OTS proof is upgraded (Bitcoin height {heights}) but no block header was supplied "
+                      "— offline verification needs a local (pruned) Bitcoin node; not claiming a pass"}

proofbundle-2.0.0b2/src/proofbundle/anchors_rfc3161.py

@@ -0,0 +1,90 @@
+"""RFC 3161 Time-Stamp Authority anchor (EXPERIMENTAL; the `[anchors]` extra).
+
+Verification is OFFLINE (Trail of Bits ``rfc3161-client`` — deliberately no network in verify): an RFC
+3161 token is checked against the TSA certificate chain **frozen into the anchor at emit time**. Freezing
+matters because a TSA can rotate its certificate (FreeTSA rotated in March 2026); an old token is then
+only re-verifiable against the chain that was current when it was issued. The frozen material lives in the
+anchor's ``frozen`` block as base64 DER, so no PEM files travel with a receipt.
+
+``proof`` is the base64 DER of the RFC 3161 response; ``canonicalRoot`` is the exact bytes that were
+timestamped (the anchor layer has already matched it to the receipt's target root). Creating an anchor
+(``create_rfc3161_anchor``) does the network call to the TSA and writes a NEW anchor object; a network
+error there never touches the local receipt.
+"""
+from __future__ import annotations
+
+import base64
+from typing import Optional
+
+
+def _load_der_cert(b64: str):
+    from cryptography import x509  # noqa: PLC0415
+    return x509.load_der_x509_certificate(base64.b64decode(b64))
+
+
+def verify_rfc3161(proof: bytes, canonical_root: bytes, *, frozen: dict, now: Optional[int] = None) -> dict:
+    """Fail-closed offline verify of an RFC 3161 token against the frozen chain. Returns {ok, detail}."""
+    try:
+        import rfc3161_client as tsp  # noqa: PLC0415
+    except ImportError:
+        return {"ok": False, "detail": "rfc3161-tsa anchor needs proofbundle[anchors] (rfc3161-client)"}
+    roots = frozen.get("rootCertsDerB64") or []
+    if not roots:
+        return {"ok": False, "detail": "frozen chain is missing rootCertsDerB64 (cannot verify offline)"}
+    try:
+        response = tsp.decode_timestamp_response(proof)
+        builder = tsp.VerifierBuilder()
+        for rb in roots:
+            builder = builder.add_root_certificate(_load_der_cert(rb))
+        for ib in frozen.get("intermediateCertsDerB64", []) or []:
+            builder = builder.add_intermediate_certificate(_load_der_cert(ib))
+        tsa_b64 = frozen.get("tsaCertDerB64")
+        if tsa_b64:
+            builder = builder.tsa_certificate(_load_der_cert(tsa_b64))
+        builder.build().verify_message(response, canonical_root)
+    except Exception as exc:   # any verify failure is a FAIL, never a silent pass (fail-closed)
+        return {"ok": False, "detail": f"RFC 3161 token did not verify against the frozen chain: {exc}"}
+    return {"ok": True, "detail": "RFC 3161 token verified offline against the frozen TSA chain"}
+
+
+def create_rfc3161_anchor(canonical_root: bytes, target: str, *, tsa_url: str,
+                          root_certs_der: list, tsa_cert_der: Optional[bytes] = None,
+                          intermediate_certs_der: Optional[list] = None,
+                          anchored_at: Optional[str] = None, timeout: int = 30) -> dict:
+    """Stamp ``canonical_root`` at ``tsa_url`` and return a NEW anchor object with the chain frozen in.
+
+    Network call (POST an RFC 3161 query). The caller supplies the TSA's root cert(s) (and, for TSAs that
+    do not embed it, the TSA cert) so the chain can be frozen for offline re-verification. This function
+    only builds and returns the anchor dict — writing it into a receipt is the caller's job, so a network
+    failure here never corrupts the local receipt.
+    """
+    import urllib.request  # noqa: PLC0415
+
+    import rfc3161_client as tsp  # noqa: PLC0415
+    request = tsp.TimestampRequestBuilder().data(canonical_root).cert_request().build()
+    http = urllib.request.Request(
+        tsa_url, data=request.as_bytes(), method="POST",
+        headers={"Content-Type": "application/timestamp-query",
+                 "Accept": "application/timestamp-reply"})
+    with urllib.request.urlopen(http, timeout=timeout) as resp:
+        token = resp.read()
+    # sanity: the response must be granted and verify against the supplied chain before we freeze it
+    frozen: dict = {
+        "rootCertsDerB64": [base64.b64encode(c).decode("ascii") for c in root_certs_der],
+    }
+    if tsa_cert_der:
+        frozen["tsaCertDerB64"] = base64.b64encode(tsa_cert_der).decode("ascii")
+    if intermediate_certs_der:
+        frozen["intermediateCertsDerB64"] = [base64.b64encode(c).decode("ascii")
+                                             for c in intermediate_certs_der]
+    check = verify_rfc3161(token, canonical_root, frozen=frozen)
+    if not check["ok"]:
+        raise RuntimeError(f"refusing to build anchor: fresh token did not verify — {check['detail']}")
+    return {
+        "type": "rfc3161-tsa",
+        "target": target,
+        "canonicalRoot": base64.b64encode(canonical_root).decode("ascii"),
+        "proof": base64.b64encode(token).decode("ascii"),
+        "anchoredAt": anchored_at,
+        "frozen": frozen,
+    }

{proofbundle-2.0.0b1 → proofbundle-2.0.0b2}/src/proofbundle/bundle.py

@@ -153,6 +153,7 @@ def verify_bundle(bundle: Union[dict, str], *, expected_aud=None, expected_nonce
 
     # 3. optional SD-JWT selective disclosure credential
     sd = bundle.get("sd_jwt_vc")
+    kb_binding_checked = False   # F4: did a KB-JWT (the aud/nonce carrier) actually get verified?
     if sd is not None:
         sd = _require_dict(sd, "sd_jwt_vc")
         _reject_unknown(sd, _SD_KEYS, "sd_jwt_vc")
@@ -186,6 +187,7 @@ def verify_bundle(bundle: Union[dict, str], *, expected_aud=None, expected_nonce
             if kb is not None:
                 kb_res = verify_key_binding(compact, expected_aud=expected_aud, expected_nonce=expected_nonce)
                 result.add("sd-jwt-key-binding", kb_res["ok"], kb_res["detail"])
+                kb_binding_checked = True
             elif _issuer_requires_holder_binding(sd_part):
                 result.add(
                     "sd-jwt-key-binding", False,
@@ -206,6 +208,18 @@ def verify_bundle(bundle: Union[dict, str], *, expected_aud=None, expected_nonce
                     "binding is unverifiable, refusing (fail-closed; supply "
                     "sd_jwt_vc.issuer_public_key_b64)")
 
+    # F4 (v1.9.2, fail-closed): supplying expected_aud/expected_nonce asks for RFC 9901 §7.3
+    # replay/audience binding. A bundle with no verifiable KB-JWT (no sd_jwt_vc at all, or an
+    # sd_jwt_vc without a Key Binding JWT) carries nothing to bind to — returning OK anyway is a
+    # downgrade trap: the verifier believes the presentation was bound to its aud/nonce when it was
+    # not. Refuse the binding it asked for but cannot be enforced. Verifiers that pass no expected_*
+    # are unaffected (backward-compatible: the check only fires when a binding was actually requested).
+    if (expected_aud is not None or expected_nonce is not None) and not kb_binding_checked:
+        result.add(
+            "sd-jwt-key-binding", False,
+            "expected_aud/expected_nonce were supplied but the bundle carries no verifiable Key "
+            "Binding JWT — the requested replay/audience binding cannot be enforced (fail-closed)")
+
     return result