proofbundle 3.1.3__tar.gz → 3.2.0__tar.gz

{proofbundle-3.1.3/src/proofbundle.egg-info → proofbundle-3.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: proofbundle
-Version: 3.1.3
+Version: 3.2.0
 Summary: Emit and verify portable cryptographic evidence bundles, offline: Ed25519 + RFC 6962 Merkle + optional SD-JWT.
 Author: Konrad Gruszka
 License: MIT
@@ -300,6 +300,10 @@ roadmap.
   a signed outcome is self-assertion. See
   [docs/predicates/decision-receipt.md](https://github.com/b7n0de/proofbundle/blob/main/docs/predicates/decision-receipt.md)
   and [ADR 0001](https://github.com/b7n0de/proofbundle/blob/main/docs/adr/0001-decision-receipt-separate-predicate.md).
+  That signed outcome is the `action-outcome/v0.1` predicate (EXPERIMENTAL, 3.2.0): an executor signs what was
+  actually done, bound by content root to the Decision Receipt, with role separation (executor ≠ decision maker)
+  and `execution_proven` only when an effect digest backs an `executed` status. See
+  [docs/predicates/action-outcome.md](https://github.com/b7n0de/proofbundle/blob/main/docs/predicates/action-outcome.md).
 
 ## Docs
 

{proofbundle-3.1.3 → proofbundle-3.2.0}/README.md

@@ -246,6 +246,10 @@ roadmap.
   a signed outcome is self-assertion. See
   [docs/predicates/decision-receipt.md](https://github.com/b7n0de/proofbundle/blob/main/docs/predicates/decision-receipt.md)
   and [ADR 0001](https://github.com/b7n0de/proofbundle/blob/main/docs/adr/0001-decision-receipt-separate-predicate.md).
+  That signed outcome is the `action-outcome/v0.1` predicate (EXPERIMENTAL, 3.2.0): an executor signs what was
+  actually done, bound by content root to the Decision Receipt, with role separation (executor ≠ decision maker)
+  and `execution_proven` only when an effect digest backs an `executed` status. See
+  [docs/predicates/action-outcome.md](https://github.com/b7n0de/proofbundle/blob/main/docs/predicates/action-outcome.md).
 
 ## Docs
 

{proofbundle-3.1.3 → proofbundle-3.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "proofbundle"
-version = "3.1.3"
+version = "3.2.0"
 description = "Emit and verify portable cryptographic evidence bundles, offline: Ed25519 + RFC 6962 Merkle + optional SD-JWT."
 readme = "README.md"
 requires-python = ">=3.10"

{proofbundle-3.1.3 → proofbundle-3.2.0}/src/proofbundle/__init__.py

@@ -13,7 +13,7 @@ from __future__ import annotations
 
 from typing import TYPE_CHECKING
 
-__version__ = "3.1.3"
+__version__ = "3.2.0"
 
 # The `proofbundle/v0.1` normative spec revision this build implements — kept in sync with the
 # `Revision:` line at the top of SPEC.md by tests/test_docs_truth.py (WP-B1, closes #28). Bump
@@ -47,6 +47,23 @@ __all__ = [
     "beacon_audit_challenge",
     "canonicalize_statement",
     "statement_content_root",
+    "resolve_hash_alg",
+    "compute_dual_hash",
+    "verify_dual_hash",
+    "build_evidence_pack",
+    "verify_evidence_pack",
+    "ots_upgraded_proof_is_self_contained",
+    "build_initial_sequence",
+    "renew_timestamp",
+    "renew_hashtree",
+    "verify_sequence",
+    "last_ats",
+    "evaluate_renewal_policy",
+    "ArchiveTimeStamp",
+    "RenewalPolicy",
+    "verify_mldsa",
+    "verify_slhdsa",
+    "verify_hybrid",
     "VerificationResult",
     "Check",
     "ProofBundleError",
@@ -75,6 +92,23 @@ _LAZY = {
     "beacon_audit_challenge": ".beacon",
     "canonicalize_statement": ".canonical",
     "statement_content_root": ".canonical",
+    "resolve_hash_alg": ".hashalg",
+    "compute_dual_hash": ".hashalg",
+    "verify_dual_hash": ".hashalg",
+    "build_evidence_pack": ".evidence_pack",
+    "verify_evidence_pack": ".evidence_pack",
+    "ots_upgraded_proof_is_self_contained": ".evidence_pack",
+    "build_initial_sequence": ".renewal",
+    "renew_timestamp": ".renewal",
+    "renew_hashtree": ".renewal",
+    "verify_sequence": ".renewal",
+    "last_ats": ".renewal",
+    "evaluate_renewal_policy": ".renewal",
+    "ArchiveTimeStamp": ".renewal",
+    "RenewalPolicy": ".renewal",
+    "verify_mldsa": ".pqsig",
+    "verify_slhdsa": ".pqsig",
+    "verify_hybrid": ".pqsig",
 }
 
 if TYPE_CHECKING:  # static analysers + IDEs see the real names/types; runtime stays lazy
@@ -88,6 +122,13 @@ if TYPE_CHECKING:  # static analysers + IDEs see the real names/types; runtime s
                             verify_sample_opening)
     from .beacon import beacon_audit_challenge
     from .canonical import canonicalize_statement, statement_content_root
+    from .hashalg import compute_dual_hash, resolve_hash_alg, verify_dual_hash
+    from .evidence_pack import (build_evidence_pack, ots_upgraded_proof_is_self_contained,
+                                verify_evidence_pack)
+    from .renewal import (ArchiveTimeStamp, RenewalPolicy, build_initial_sequence,
+                          evaluate_renewal_policy, last_ats, renew_hashtree, renew_timestamp,
+                          verify_sequence)
+    from .pqsig import verify_hybrid, verify_mldsa, verify_slhdsa
     from .prereg import prereg_hash, verify_prereg
     from .statuslist import verify_status_snapshot
     from .tlogproof import verify_tlog_proof

{proofbundle-3.1.3 → proofbundle-3.2.0}/src/proofbundle/anchors_chia_add.py

@@ -19,13 +19,41 @@ import os
 import shutil
 import subprocess
 import time
-from typing import Optional
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Iterator, Optional
 
 from .anchors_chia import ANCHOR_TYPE, verify_offline_merkle
 
 _CHIA_BIN = os.getenv("CHIA_CLI", shutil.which("chia") or "chia")
 
 
+@contextmanager
+def _anchor_in_progress_lock(lock_path: Optional[str]) -> Iterator[None]:
+    """Advisory 'anchor in progress' marker held around the on-chain batch_update + confirmation.
+
+    While an anchor's wallet-using transaction is submitted and confirmed, write a marker FILE at
+    ``lock_path`` (or the ``PROOFBUNDLE_ANCHOR_LOCK_PATH`` env). A SEPARATE process — e.g. a wallet-switch
+    guard that must not log the wallet out from under the transaction — can treat the file's PRESENCE as
+    'an anchor is running'. Removed on completion; a crash leaves it stale, which a conservative guard
+    treats as still-active (fail-safe, never breaks a possibly-live anchor). No-op when no path is set, so
+    the default anchor flow is unchanged and proofbundle stays free of any consumer-specific naming."""
+    path = lock_path or os.getenv("PROOFBUNDLE_ANCHOR_LOCK_PATH")
+    if not path:
+        yield
+        return
+    p = Path(path)
+    p.parent.mkdir(parents=True, exist_ok=True)
+    p.write_text(str(os.getpid()))
+    try:
+        yield
+    finally:
+        try:
+            p.unlink()
+        except OSError:
+            pass
+
+
 class ChiaRpcError(RuntimeError):
     """A Chia RPC/CLI call failed. Fail-closed: the caller aborts, no partial anchor is written."""
 
@@ -125,11 +153,15 @@ def _wait_confirmed(store_id: str, prev_root: Optional[str], *, timeout: int = 1
 
 def anchor_add(canonical_root_hex: str, *, store_id: str, value_digest_hex: Optional[str] = None,
                target: str = "receipt", network: str = "mainnet", fee: int = 100_000_000,
-               wait: bool = True) -> dict:
+               wait: bool = True, lock_path: Optional[str] = None) -> dict:
     """Full flow: insert ``key=canonicalRoot`` (value = ``value_digest`` or the canonicalRoot itself) into the
     store, wait for on-chain confirmation, then export the anchor. Idempotent: a key already present ("Key
     already present") is treated as "already anchored" and re-exported, not an error. Fail-closed: a network
-    failure raises ChiaRpcError and writes NOTHING partial (the caller keeps its receipt untouched)."""
+    failure raises ChiaRpcError and writes NOTHING partial (the caller keeps its receipt untouched).
+
+    ``lock_path`` (or the ``PROOFBUNDLE_ANCHOR_LOCK_PATH`` env) holds an advisory 'anchor in progress' marker
+    file AUTOMATICALLY around the wallet-using batch_update + confirmation, so a separate wallet-switch guard
+    never logs the wallet out mid-anchor. No path → unchanged behaviour."""
     canonical_root_hex = canonical_root_hex if canonical_root_hex.startswith(("0x", "0X")) else "0x" + canonical_root_hex
     canonical_root = bytes.fromhex(canonical_root_hex[2:])
     if len(canonical_root) != 32:
@@ -137,18 +169,19 @@ def anchor_add(canonical_root_hex: str, *, store_id: str, value_digest_hex: Opti
     value_hex = value_digest_hex or canonical_root_hex
     value_hex = value_hex if value_hex.startswith(("0x", "0X")) else "0x" + value_hex
 
-    prev_root = _rpc("data_layer", "get_root", {"id": store_id}).get("hash")
-    changelist = [{"action": "insert", "key": canonical_root_hex, "value": value_hex}]
-    already = False
-    try:
-        _rpc("data_layer", "batch_update",
-             {"id": store_id, "changelist": changelist, "fee": fee, "submit_on_chain": True})
-    except ChiaRpcError as exc:
-        if "already present" in str(exc).lower():
-            already = True                        # idempotent: the digest is already anchored
-        else:
-            raise                                 # any other failure → clean abort, nothing written
-    if wait and not already:
-        _wait_confirmed(store_id, prev_root)
-    return export_anchor(store_id, canonical_root=canonical_root,
-                         target=target, network=network, value=value_hex)
+    with _anchor_in_progress_lock(lock_path):
+        prev_root = _rpc("data_layer", "get_root", {"id": store_id}).get("hash")
+        changelist = [{"action": "insert", "key": canonical_root_hex, "value": value_hex}]
+        already = False
+        try:
+            _rpc("data_layer", "batch_update",
+                 {"id": store_id, "changelist": changelist, "fee": fee, "submit_on_chain": True})
+        except ChiaRpcError as exc:
+            if "already present" in str(exc).lower():
+                already = True                    # idempotent: the digest is already anchored
+            else:
+                raise                             # any other failure → clean abort, nothing written
+        if wait and not already:
+            _wait_confirmed(store_id, prev_root)
+        return export_anchor(store_id, canonical_root=canonical_root,
+                             target=target, network=network, value=value_hex)

{proofbundle-3.1.3 → proofbundle-3.2.0}/src/proofbundle/cli.py

@@ -1303,6 +1303,127 @@ def _cmd_decision_init(args: argparse.Namespace) -> int:
     return 0
 
 
+# ── Action Outcome Receipt (3.2.0, action-outcome/v0.1, EXPERIMENTAL) ──────────
+def _cmd_outcome_init(args: argparse.Namespace) -> int:
+    template = {
+        "schemaVersion": "0.1.0",
+        "outcomeId": "urn:uuid:00000000-0000-0000-0000-000000000000",
+        "decisionRef": {"sha256": "0" * 64},
+        "executor": {"id": "executor://example/runner", "keyId": ""},
+        "requestedActionDigest": {"sha256": "0" * 64},
+        "actualActionDigest": {"sha256": "0" * 64},
+        "responseDigest": {"sha256": "0" * 64},
+        "effectDigest": {"sha256": "0" * 64},
+        "status": "executed",
+        "performedAt": "2026-01-01T00:00:00Z",
+        "policyPurpose": "outcome",
+        "traceContext": {"traceparent": ""},
+        "limitations": [],
+    }
+    out = json.dumps(template, indent=2, ensure_ascii=False)
+    if args.out:
+        with open(args.out, "w", encoding="utf-8") as handle:
+            handle.write(out + "\n")
+        print(f"wrote outcome predicate template {args.out}")
+    else:
+        print(out)
+    return 0
+
+
+def _cmd_outcome_emit(args: argparse.Namespace) -> int:
+    from .outcome import OutcomeReceiptError, emit_outcome_receipt  # noqa: PLC0415
+    signer = _resolve_signer(args)
+    if signer is None:
+        return 2
+    try:
+        with open(args.predicate, encoding="utf-8") as handle:
+            predicate = loads_strict(handle.read())   # WP-C1: a duplicate key must never be signed
+        env = emit_outcome_receipt(predicate, signer, strict=not args.lenient)
+    except (OutcomeReceiptError, ProofBundleError, OSError, ValueError) as exc:
+        print(f"ERROR: {exc}", file=sys.stderr)
+        return 2
+    with open(args.out, "w", encoding="utf-8") as handle:
+        json.dump(env, handle, indent=2)
+        handle.write("\n")
+    print(f"wrote outcome receipt {args.out}")
+    return 0
+
+
+def _cmd_outcome_verify(args: argparse.Namespace) -> int:
+    import base64  # noqa: PLC0415
+    from .outcome import verify_outcome_receipt  # noqa: PLC0415
+    if not args.pub:
+        print("ERROR: --pub <base64 Ed25519 public key> is required", file=sys.stderr)
+        return 2
+    try:
+        with open(args.envelope, encoding="utf-8") as handle:
+            env = loads_strict(handle.read())   # WP-C1: duplicate keys rejected
+        pub = base64.b64decode(args.pub)
+        result = verify_outcome_receipt(
+            env, pub, strict=args.strict,
+            expected_decision_ref=args.expected_decision_ref, decision_maker_id=args.decision_maker_id,
+            expected_audience=args.aud, expected_nonce=args.nonce)
+    except (ProofBundleError, OSError, ValueError) as exc:
+        print(f"ERROR: {exc}", file=sys.stderr)
+        return 2
+    if args.json:
+        report = {k: result[k] for k in (
+            "ok", "crypto_ok", "structure_ok", "predicate_type_ok", "decision_bound", "role_separation_ok",
+            "execution_proven", "audience_ok", "nonce_ok", "warnings", "errors",
+        )}
+        print(json.dumps(report, indent=2))
+    else:
+        print(f"CRYPTO: {'OK' if result['crypto_ok'] else 'FAIL'}")
+        print(f"STRUCTURE: {'OK' if result['structure_ok'] else 'FAIL'}")
+        if result["decision_bound"] is not None:
+            print(f"DECISION_BINDING: {'OK' if result['decision_bound'] else 'MISMATCH'}")
+        if result["role_separation_ok"] is not None:
+            print(f"ROLE_SEPARATION: {'OK' if result['role_separation_ok'] else 'VIOLATED'}")
+        if result["audience_ok"] is not None:
+            print(f"AUDIENCE: {'OK' if result['audience_ok'] else 'MISMATCH'}")
+        if result["nonce_ok"] is not None:
+            print(f"NONCE: {'OK' if result['nonce_ok'] else 'MISMATCH'}")
+        if result["execution_proven"] is False:
+            print("ASSURANCE: status=executed is self-asserted (no effectDigest/actualActionDigest)")
+        for e in result["errors"]:
+            print(f"  - {e}", file=sys.stderr)
+        for w in result["warnings"]:
+            print(f"  ! {w}", file=sys.stderr)
+        if result["crypto_ok"]:
+            print("\nThis proves who signed what happened, bound to the referenced decision. It does not prove "
+                  "the effect was good, correct or desired.")
+        else:
+            print("\nThis receipt did NOT verify (crypto failure); nothing about the outcome is attested.")
+    # Exit contract mirrors decision verify: 1 crypto · 2 malformed/confusion/binding-mismatch · 3 policyPurpose.
+    if not result["crypto_ok"]:
+        return 1
+    if not result["structure_ok"]:
+        return 2
+    if result["decision_bound"] is False or result["role_separation_ok"] is False:
+        return 2
+    if result["audience_ok"] is False or result["nonce_ok"] is False:
+        return 2
+    return 0
+
+
+def _cmd_outcome_inspect(args: argparse.Namespace) -> int:
+    import base64  # noqa: PLC0415
+    try:
+        with open(args.receipt, encoding="utf-8") as handle:
+            obj = loads_strict(handle.read())   # WP-C1
+    except (ProofBundleError, OSError, ValueError) as exc:
+        print(f"ERROR: {exc}", file=sys.stderr)
+        return 2
+    try:
+        statement = loads_strict(base64.b64decode(obj["payload"])) if isinstance(obj, dict) and "payload" in obj else obj
+    except (ProofBundleError, ValueError, TypeError) as exc:
+        print(f"ERROR: {exc}", file=sys.stderr)
+        return 2
+    predicate = statement.get("predicate", statement) if isinstance(statement, dict) else statement
+    print(json.dumps(predicate, indent=2, ensure_ascii=False))
+    return 0
+
+
 def _cmd_policy_explain(args: argparse.Namespace) -> int:
     from .policy import PolicyError, explain_policy, load_policy, policy_warnings  # noqa: PLC0415
     from .policy_profiles import resolve_policy_source  # noqa: PLC0415
@@ -1773,6 +1894,45 @@ def build_parser() -> argparse.ArgumentParser:
     d_inspect.add_argument("receipt", help="path to a DSSE receipt or a raw in-toto Statement")
     d_inspect.set_defaults(func=_cmd_decision_inspect)
 
+    # ── Action Outcome Receipt (3.2.0, action-outcome/v0.1, EXPERIMENTAL) ──
+    outcome = sub.add_parser("outcome", help="action-outcome/v0.1 (EXPERIMENTAL): init/emit/verify/inspect an action outcome")
+    osub = outcome.add_subparsers(dest="outcome_command", required=True)
+
+    o_init = osub.add_parser("init", help="print a template outcome predicate (fill in and sign with 'outcome emit')")
+    o_init.add_argument("--out", default=None, help="write the template to a file instead of stdout")
+    o_init.set_defaults(func=_cmd_outcome_init)
+
+    o_emit = osub.add_parser("emit", help="sign an outcome predicate into a DSSE receipt")
+    o_emit.add_argument("predicate", help="path to the outcome predicate JSON")
+    o_emit.add_argument("--out", required=True, help="output path for the signed outcome receipt")
+    o_emit.add_argument("--key", help="load an existing Ed25519 signing key from file")
+    o_emit.add_argument("--new-key", dest="new_key", help="generate a new signing key and write it to file")
+    o_emit.add_argument("--lenient", action="store_true", help="allow non-strict predicates")
+    o_emit.set_defaults(func=_cmd_outcome_emit)
+
+    o_verify = osub.add_parser(
+        "verify", help="verify an outcome receipt (crypto + structure; decision binding + role separation)",
+        description=("Exit codes: 0 OK · 1 crypto/verification failure · 2 malformed / predicateType confusion "
+                     "/ decision-binding or role-separation mismatch. --expected-decision-ref binds the outcome "
+                     "to a specific decision content root (replay across decisions fails). --decision-maker-id "
+                     "enforces role separation (executor must differ from the decision maker). status=executed "
+                     "without an effect/actual digest is a self-asserted claim, not proof of the effect."))
+    o_verify.add_argument("envelope", help="path to the DSSE outcome receipt")
+    o_verify.add_argument("--pub", required=True, help="executor Ed25519 public key (base64) to verify against")
+    o_verify.add_argument("--expected-decision-ref", dest="expected_decision_ref", default=None,
+                          help="expected decision content root (sha256 hex); a mismatch is a cross-decision replay, fail-closed")
+    o_verify.add_argument("--decision-maker-id", dest="decision_maker_id", default=None,
+                          help="the bound decision's maker id; executor==maker violates role separation (fail-closed)")
+    o_verify.add_argument("--json", action="store_true", help="machine readable output")
+    o_verify.add_argument("--strict", action="store_true", help="enforce strict-v0.1 required fields")
+    o_verify.add_argument("--aud", default=None, help="expected audience (checks validity.audience against replay)")
+    o_verify.add_argument("--nonce", default=None, help="expected nonce (checks validity.nonce against replay)")
+    o_verify.set_defaults(func=_cmd_outcome_verify)
+
+    o_inspect = osub.add_parser("inspect", help="print an outcome receipt's predicate (no crypto verification)")
+    o_inspect.add_argument("receipt", help="path to a DSSE receipt or a raw in-toto Statement")
+    o_inspect.set_defaults(func=_cmd_outcome_inspect)
+
     return parser
 
 

proofbundle-3.2.0/src/proofbundle/evidence_pack.py

@@ -0,0 +1,98 @@
+"""B6 evidence-pack hardening for offline long-term verification (EXPERIMENTAL; ADR 0006).
+
+Goal: a pack built from a receipt verifies OFFLINE on a second machine from bundled data — no calendar,
+no network. The OTS anchor already verifies offline from a relying-party Bitcoin block header
+(``anchors_ots.verify_opentimestamps``); this module adds the PACK layer around it:
+
+* ``ots_upgraded_proof_is_self_contained`` — a proof with a Bitcoin block-header attestation is upgraded
+  and self-contained (the calendar is no longer needed to verify existence-in-Bitcoin). A pending-only or
+  malformed proof is not.
+* ``build_evidence_pack`` — assemble the self-contained proof + the canonical root + the set of calendars
+  it was submitted to (multi-calendar redundancy metadata) and, optionally, a COPY of the Bitcoin block
+  headers as EVIDENCE.
+* ``verify_evidence_pack`` — verify the pack with NO network I/O, delegating to the OTS verifier.
+
+WP-A1 boundary (never crossed). The header a pack bundles is producer-controlled EVIDENCE, never trust —
+a producer could bundle a self-committed, backdated header. Confirmation therefore still needs a
+RELYING-PARTY header (``rp_trust.bitcoin_block_headers``). That header can be an OFFLINE trusted Bitcoin
+checkpoint the relying party ships, so "needs a relying-party header" does NOT mean "needs the network".
+A pack with a bundled header but no relying-party trust is honestly ``needs_rp_trust``, not a pass.
+
+Honesty on scope. The MECHANISM here is complete and tested. Producing a pack from a REAL confirmed
+receipt (submitting to public calendars, waiting for Bitcoin confirmation, ``ots upgrade``) is an
+Owner-gated external anchor submission and is tracked as the OPEN end-to-end step in ADR 0006 — not
+claimed here.
+"""
+from __future__ import annotations
+
+import base64
+from typing import Optional
+
+from .anchors_ots import _classify, verify_opentimestamps
+
+__all__ = [
+    "ots_upgraded_proof_is_self_contained",
+    "build_evidence_pack",
+    "verify_evidence_pack",
+]
+
+
+def ots_upgraded_proof_is_self_contained(proof: bytes) -> bool:
+    """True iff ``proof`` is an UPGRADED OTS proof (a Bitcoin block-header attestation) — self-contained,
+    so verifying existence-in-Bitcoin no longer needs a calendar. A pending-only or malformed proof is
+    False (fail-closed; never over-claim a pending proof as self-contained)."""
+    try:
+        from opentimestamps.core.serialize import BytesDeserializationContext  # noqa: PLC0415
+        from opentimestamps.core.timestamp import DetachedTimestampFile  # noqa: PLC0415
+    except ImportError:
+        return False
+    try:
+        dtf = DetachedTimestampFile.deserialize(BytesDeserializationContext(proof))
+    except Exception:
+        return False
+    has_bitcoin, _heights, _has_pending = _classify(dtf.timestamp)
+    return has_bitcoin
+
+
+def build_evidence_pack(canonical_root: bytes, proof: bytes, *, calendars: list[str],
+                        bundled_headers: Optional[dict[str, str]] = None) -> dict:
+    """Assemble an offline-verifiable evidence pack around an OTS proof.
+
+    ``calendars`` is the set of calendar servers the stamp was submitted to; recording two or more is the
+    multi-calendar redundancy metadata (``calendarRedundancy`` = distinct count). ``bundled_headers`` (a
+    ``height -> block merkle-root hex`` map) is copied into the pack as EVIDENCE only (``frozen`` block,
+    WP-A1: never trusted by the verifier). The pack never contains a secret."""
+    distinct = sorted(set(calendars))
+    pack: dict = {
+        "type": "opentimestamps-evidence-pack",
+        "packVersion": "v0.1",
+        "canonicalRoot": base64.b64encode(canonical_root).decode(),
+        "proof": base64.b64encode(proof).decode(),
+        "selfContained": ots_upgraded_proof_is_self_contained(proof),
+        "calendars": distinct,
+        "calendarRedundancy": len(distinct),
+        "bundledHeaderEvidence": bool(bundled_headers),
+    }
+    if bundled_headers:
+        # producer-controlled EVIDENCE, surfaced in the frozen block; verify_opentimestamps treats it as
+        # frozenEvidence and never as trust (WP-A1).
+        pack["frozen"] = {"bitcoinBlockHeaderMerkleRootsByHeight": dict(bundled_headers)}
+    return pack
+
+
+def verify_evidence_pack(pack: dict, *, rp_trust: Optional[dict] = None,
+                         now: Optional[int] = None) -> dict:
+    """Verify an evidence pack OFFLINE (no network I/O). Delegates to the OTS verifier with the pack's
+    proof + canonical root; the pack's bundled header is passed as ``frozen`` EVIDENCE, and confirmation
+    happens only against a relying-party header (``rp_trust``), which may be an offline checkpoint.
+
+    Returns the OTS verifier's result dict ({ok, detail, warn, status, …}). Fail-closed on a malformed
+    pack (missing/!b64 proof or root)."""
+    try:
+        proof = base64.b64decode(pack["proof"], validate=True)
+        canonical_root = base64.b64decode(pack["canonicalRoot"], validate=True)
+    except (KeyError, ValueError, TypeError) as exc:
+        return {"ok": False, "warn": False, "status": "malformed_pack",
+                "detail": f"evidence pack is missing or has a non-base64 proof/canonicalRoot: {exc}"}
+    frozen = pack.get("frozen") or {}
+    return verify_opentimestamps(proof, canonical_root, frozen=frozen, now=now, rp_trust=rp_trust)

proofbundle-3.2.0/src/proofbundle/hashalg.py

@@ -0,0 +1,177 @@
+"""B2 hash-agility — an explicit registry of hash algorithms with fail-closed resolution and a
+dual-hash helper (ADR 0006).
+
+Why this module exists. proofbundle's surfaces already DECLARE their hash construction per artifact
+(``merkle.hash_alg = "sha256-rfc6962"``, ``contentRootAlg = "jcs-sha256-v1"``, a checkpoint's
+``hashAlg``). What was missing for long-term evidence is a single agility layer: one registry that
+says which hash PRIMITIVES are allowed, which are deprecated, and a resolver that NEVER silently
+defaults a missing/unknown/weak algorithm — the exact place an algorithm-confusion attack would hide
+(RFC 7696 §2.1; ADR 0002 §2 warns of the same at the content-root level). The algorithm id maps to the
+RFC 4998 (ERS) ``digestAlgorithm`` OID, so the B3 renewal chain builds directly on this registry.
+
+Model: the IANA Named Information Hash Algorithm registry (RFC 6920) — an id, a status
+(``current`` / ``deprecated``), and enough to compute and size the digest. Deprecation follows the NIST
+transition (SHA-1 retired; SHA-256/384/512 and the SHA-3 family current — NIST FIPS 180-4 / 202,
+SP 800-131A).
+
+Fail-closed contract:
+  * an absent/empty id is ``MissingHashAlgId`` — there is NO implicit SHA-256;
+  * an id not in the registry is ``UnknownHashAlg``;
+  * a deprecated id is ``DeprecatedHashAlg`` unless the caller explicitly opts into legacy verification
+    (``allow_deprecated=True``) — a verifier may need to read an old receipt, but nothing NEW is ever
+    produced with a weak hash, and a dual-hash's PASS requires at least one current algorithm.
+"""
+from __future__ import annotations
+
+import hashlib
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from typing import Optional
+
+from .errors import Check, ProofBundleError, VerificationResult
+
+__all__ = [
+    "HASH_REGISTRY",
+    "HashAlg",
+    "HashAlgError",
+    "MissingHashAlgId",
+    "UnknownHashAlg",
+    "DeprecatedHashAlg",
+    "resolve_hash_alg",
+    "compute_digest",
+    "compute_dual_hash",
+    "verify_dual_hash",
+]
+
+
+class HashAlgError(ProofBundleError):
+    """Base class for every hash-agility failure (a subclass of ``ProofBundleError``)."""
+
+
+class MissingHashAlgId(HashAlgError):
+    """No algorithm id was given. Fail-closed: proofbundle never defaults a missing hash to SHA-256."""
+
+
+class UnknownHashAlg(HashAlgError):
+    """The algorithm id is not in ``HASH_REGISTRY``. Fail-closed: an unknown hash is never trusted."""
+
+
+class DeprecatedHashAlg(HashAlgError):
+    """The algorithm is known but deprecated and the caller did not opt into legacy verification."""
+
+
+@dataclass(frozen=True)
+class HashAlg:
+    """One registry entry: how to compute the digest, its size, its status, and its ERS OID.
+
+    ``ers_oid`` is the RFC 4998 ``digestAlgorithm`` ``AlgorithmIdentifier`` OID, so a renewal chain (B3)
+    references the same identity this registry defines. ``hashlib_name`` is the ``hashlib.new`` name."""
+
+    id: str
+    hashlib_name: str
+    digest_size: int
+    status: str  # "current" | "deprecated"
+    ers_oid: str
+
+    def new(self) -> "hashlib._Hash":
+        return hashlib.new(self.hashlib_name)
+
+
+# The allowed hash primitives. SHA-256/384/512 (FIPS 180-4) and SHA3-256/512 (FIPS 202) are current;
+# SHA-1 and MD5 are deprecated (kept only so a verifier can READ and clearly reject a legacy receipt).
+# OIDs are the NIST/RFC AlgorithmIdentifier values used by RFC 4998 digestAlgorithm.
+HASH_REGISTRY: dict[str, HashAlg] = {
+    "sha256": HashAlg("sha256", "sha256", 32, "current", "2.16.840.1.101.3.4.2.1"),
+    "sha384": HashAlg("sha384", "sha384", 48, "current", "2.16.840.1.101.3.4.2.2"),
+    "sha512": HashAlg("sha512", "sha512", 64, "current", "2.16.840.1.101.3.4.2.3"),
+    "sha3-256": HashAlg("sha3-256", "sha3_256", 32, "current", "2.16.840.1.101.3.4.2.8"),
+    "sha3-512": HashAlg("sha3-512", "sha3_512", 64, "current", "2.16.840.1.101.3.4.2.10"),
+    "sha1": HashAlg("sha1", "sha1", 20, "deprecated", "1.3.14.3.2.26"),
+    "md5": HashAlg("md5", "md5", 16, "deprecated", "1.2.840.113549.2.5"),
+}
+
+
+def resolve_hash_alg(alg_id: Optional[str], *, allow_deprecated: bool = False) -> HashAlg:
+    """Resolve an algorithm id to its registry entry, fail-closed.
+
+    Raises ``MissingHashAlgId`` for an absent/empty id (no implicit default), ``UnknownHashAlg`` for an
+    id not in the registry, and ``DeprecatedHashAlg`` for a weak algorithm unless ``allow_deprecated``.
+    """
+    if not alg_id or not isinstance(alg_id, str):
+        raise MissingHashAlgId(
+            "a hash algorithm id is required — proofbundle never defaults a missing hash to SHA-256")
+    spec = HASH_REGISTRY.get(alg_id)
+    if spec is None:
+        raise UnknownHashAlg(
+            f"unknown hash algorithm {alg_id!r} — not in the allowed registry "
+            f"({', '.join(sorted(HASH_REGISTRY))})")
+    if spec.status == "deprecated" and not allow_deprecated:
+        raise DeprecatedHashAlg(
+            f"hash algorithm {alg_id!r} is deprecated and rejected by default; a legacy verifier must "
+            "opt in explicitly (allow_deprecated=True)")
+    return spec
+
+
+def compute_digest(data: bytes, alg_id: str, *, allow_deprecated: bool = False) -> str:
+    """Hex digest of ``data`` under ``alg_id`` (fail-closed on missing/unknown/deprecated)."""
+    spec = resolve_hash_alg(alg_id, allow_deprecated=allow_deprecated)
+    h = spec.new()
+    h.update(data)
+    return h.hexdigest()
+
+
+def compute_dual_hash(data: bytes, alg_ids: Sequence[str]) -> dict[str, str]:
+    """Digests of ``data`` under two or more DISTINCT CURRENT algorithms — for a NEW receipt.
+
+    A dual hash lets an old receipt survive the deprecation of one hash: as long as a second,
+    independent current hash still binds the same bytes, the evidence keeps its force while a renewal
+    (B3) migrates it. A new receipt therefore requires at least two distinct current algorithms; a
+    deprecated algorithm is rejected outright (nothing new is produced with a weak hash)."""
+    seen: dict[str, HashAlg] = {}
+    for alg_id in alg_ids:
+        spec = resolve_hash_alg(alg_id)  # current-only: no allow_deprecated on the produce path
+        if spec.id in seen:
+            raise HashAlgError(f"dual hash needs DISTINCT algorithms, {spec.id!r} was given twice")
+        seen[spec.id] = spec
+    if len(seen) < 2:
+        raise HashAlgError(
+            "a dual hash needs at least two distinct current algorithms "
+            "(e.g. sha256 + sha512 or sha256 + sha3-256)")
+    return {alg_id: compute_digest(data, alg_id) for alg_id in seen}
+
+
+def verify_dual_hash(data: bytes, digests: Mapping[str, str]) -> VerificationResult:
+    """Verify that EVERY declared digest binds ``data``, and that at least one is a CURRENT algorithm.
+
+    Fail-closed: an empty map fails; an unknown algorithm fails; a single mismatching leg fails the
+    whole result; a bag of only-deprecated digests fails even when the bytes match (a legacy-only
+    receipt has lost its force and must be renewed, not silently accepted). A deprecated leg is checked
+    (``allow_deprecated``) so its presence is visible, but it cannot by itself carry a PASS."""
+    result = VerificationResult()
+    if not isinstance(digests, Mapping) or not digests:
+        result.checks.append(Check("hashalg:dual", False,
+                                   "digests must be a non-empty mapping of alg -> hex"))
+        return result
+
+    current_ok = 0
+    for alg_id, expected in digests.items():
+        try:
+            spec = resolve_hash_alg(alg_id, allow_deprecated=True)
+        except HashAlgError as exc:
+            result.checks.append(Check(f"hashalg:{alg_id}", False, str(exc)))
+            continue
+        actual = compute_digest(data, alg_id, allow_deprecated=True)
+        match = isinstance(expected, str) and actual == expected.lower()
+        detail = "digest matches" if match else "digest mismatch"
+        if match and spec.status == "deprecated":
+            detail = "digest matches but algorithm is deprecated (does not carry a PASS on its own)"
+        result.checks.append(Check(f"hashalg:{alg_id}", match, detail))
+        if match and spec.status == "current":
+            current_ok += 1
+
+    all_match = all(c.ok for c in result.checks)
+    if all_match and current_ok == 0:
+        result.checks.append(Check(
+            "hashalg:current-binding", False,
+            "no CURRENT-algorithm digest binds the payload — a legacy-only receipt must be renewed"))
+    return result