proofbundle 0.3.0__py3-none-any.whl

proofbundle/__init__.py

@@ -0,0 +1,30 @@
+"""proofbundle, an offline verifier for portable cryptographic evidence bundles.
+
+Verify, fully offline and in pure Python, that a payload was Ed25519 signed and
+anchored under an RFC 6962 Merkle root, with optional SD-JWT selective
+disclosure. The verification half of a signed, third-party-verifiable evidence
+receipt.
+"""
+
+from __future__ import annotations
+
+from .bundle import SCHEMA, load_bundle, verify_bundle
+from .emit import emit_bundle, generate_signer
+from .errors import Check, ProofBundleError, VerificationResult
+from .merkle import verify_consistency, verify_inclusion
+
+__version__ = "0.3.0"
+
+__all__ = [
+    "__version__",
+    "SCHEMA",
+    "verify_bundle",
+    "load_bundle",
+    "emit_bundle",
+    "generate_signer",
+    "verify_inclusion",
+    "verify_consistency",
+    "VerificationResult",
+    "Check",
+    "ProofBundleError",
+]

proofbundle/bundle.py

@@ -0,0 +1,109 @@
+"""Evidence bundle model and offline verification.
+
+An evidence bundle is a single self-contained JSON document. ``verify_bundle``
+checks, fully offline and without any running log server:
+
+  1. ed25519-signature   the payload is signed by the stated public key
+  2. merkle-inclusion    the payload is anchored under the stated tree root
+                         (RFC 6962 / RFC 9162 inclusion proof)
+  3. sd-jwt (optional)   any embedded SD-JWT selective-disclosure credential is
+                         well formed and, if a key is given, issuer-signed
+
+The verifier treats ``payload`` as opaque bytes: it proves *that these exact
+bytes were signed and anchored*, not what they mean. That keeps v0.1 small and
+correct. Turning a reproducible eval run into such a payload is the job of the
+emitter (see ``emit.py``, roadmap).
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+from typing import Union
+
+from . import merkle
+from .errors import BundleFormatError, UnsupportedError, VerificationResult
+from .signature import verify_ed25519
+from .sdjwt import verify_sd_jwt
+
+__all__ = ["SCHEMA", "verify_bundle", "load_bundle"]
+
+SCHEMA = "proofbundle/v0.1"
+
+
+def _b64d(value: str, field: str) -> bytes:
+    try:
+        return base64.b64decode(value, validate=True)
+    except (ValueError, TypeError) as exc:
+        raise BundleFormatError(f"field {field} is not valid base64") from exc
+
+
+def _require(obj: dict, key: str, field: str):
+    if key not in obj:
+        raise BundleFormatError(f"missing field {field}")
+    return obj[key]
+
+
+def load_bundle(path: str) -> dict:
+    """Read and JSON-parse a bundle file."""
+    with open(path, "r", encoding="utf-8") as handle:
+        return json.load(handle)
+
+
+def verify_bundle(bundle: Union[dict, str]) -> VerificationResult:
+    """Verify an evidence bundle (a dict or a path to a JSON file)."""
+    if isinstance(bundle, str):
+        bundle = load_bundle(bundle)
+    if not isinstance(bundle, dict):
+        raise BundleFormatError("bundle must be a JSON object")
+
+    schema = bundle.get("schema")
+    if schema != SCHEMA:
+        raise UnsupportedError(f"unsupported schema {schema!r}, expected {SCHEMA!r}")
+
+    result = VerificationResult()
+    payload = _b64d(_require(bundle, "payload_b64", "payload_b64"), "payload_b64")
+
+    # 1. signature over the payload
+    sig = _require(bundle, "signature", "signature")
+    alg = sig.get("alg")
+    if alg != "ed25519":
+        raise UnsupportedError(f"signature alg {alg!r} not supported in v0.1")
+    pub = _b64d(_require(sig, "public_key_b64", "signature.public_key_b64"), "signature.public_key_b64")
+    raw_sig = _b64d(_require(sig, "sig_b64", "signature.sig_b64"), "signature.sig_b64")
+    sig_ok = verify_ed25519(pub, raw_sig, payload)
+    result.add("ed25519-signature", sig_ok, "payload signed by stated key" if sig_ok else "invalid signature")
+
+    # 2. merkle inclusion of the payload
+    mk = _require(bundle, "merkle", "merkle")
+    hash_alg = mk.get("hash_alg", "sha256-rfc6962")
+    if hash_alg != "sha256-rfc6962":
+        raise UnsupportedError(f"merkle hash_alg {hash_alg!r} not supported in v0.1")
+    leaf_index = int(_require(mk, "leaf_index", "merkle.leaf_index"))
+    tree_size = int(_require(mk, "tree_size", "merkle.tree_size"))
+    proof = [_b64d(p, "merkle.inclusion_proof_b64[]") for p in mk.get("inclusion_proof_b64", [])]
+    root = _b64d(_require(mk, "root_b64", "merkle.root_b64"), "merkle.root_b64")
+    incl_ok = merkle.verify_inclusion(payload, leaf_index, tree_size, proof, root)
+    result.add(
+        "merkle-inclusion",
+        incl_ok,
+        f"anchored at index {leaf_index} of {tree_size}" if incl_ok else "inclusion proof failed",
+    )
+
+    # 3. optional SD-JWT selective disclosure credential
+    sd = bundle.get("sd_jwt_vc")
+    if sd is not None:
+        compact = _require(sd, "compact", "sd_jwt_vc.compact")
+        issuer_pub = None
+        if sd.get("issuer_public_key_b64"):
+            issuer_pub = _b64d(sd["issuer_public_key_b64"], "sd_jwt_vc.issuer_public_key_b64")
+        sd_res = verify_sd_jwt(compact, issuer_pub)
+        result.add("sd-jwt-disclosures", sd_res["structure_ok"], sd_res["detail"])
+        if sd_res["sig_checked"]:
+            result.add(
+                "sd-jwt-issuer-signature",
+                sd_res["sig_ok"],
+                "issuer signature valid" if sd_res["sig_ok"] else "issuer signature invalid",
+            )
+
+    return result

proofbundle/cli.py

@@ -0,0 +1,89 @@
+"""Command line interface: ``proofbundle verify`` and ``proofbundle emit``."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from . import __version__
+from .bundle import verify_bundle
+from .emit import emit_bundle, generate_signer, load_signer, save_signer
+from .errors import ProofBundleError
+
+
+def _cmd_verify(args: argparse.Namespace) -> int:
+    try:
+        result = verify_bundle(args.bundle)
+    except ProofBundleError as exc:
+        if args.json:
+            print(json.dumps({"ok": False, "error": str(exc)}))
+        else:
+            print(f"ERROR: {exc}", file=sys.stderr)
+        return 2
+
+    if args.json:
+        print(json.dumps(result.as_dict(), indent=2))
+    else:
+        for check in result.checks:
+            print(str(check))
+        print("=> OK" if result.ok else "=> FAILED")
+    return 0 if result.ok else 1
+
+
+def _cmd_emit(args: argparse.Namespace) -> int:
+    if args.new_key and args.key:
+        print("ERROR: use either --key or --new-key, not both", file=sys.stderr)
+        return 2
+    if args.new_key:
+        signer = generate_signer()
+        save_signer(signer, args.new_key)
+        print(f"wrote new signing key to {args.new_key} (keep this secret)", file=sys.stderr)
+    elif args.key:
+        signer = load_signer(args.key)
+    else:
+        print("ERROR: provide --key <file> or --new-key <file>", file=sys.stderr)
+        return 2
+
+    with open(args.payload_file, "rb") as handle:
+        payload = handle.read()
+
+    bundle = emit_bundle(payload, signer)
+    with open(args.out, "w", encoding="utf-8") as handle:
+        json.dump(bundle, handle, indent=2)
+        handle.write("\n")
+    print(f"wrote {args.out}")
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="proofbundle",
+        description="Emit and verify portable cryptographic evidence bundles, offline.",
+    )
+    parser.add_argument("--version", action="version", version=f"proofbundle {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    verify = sub.add_parser("verify", help="verify an evidence bundle JSON file")
+    verify.add_argument("bundle", help="path to the bundle JSON file")
+    verify.add_argument("--json", action="store_true", help="machine readable output")
+    verify.set_defaults(func=_cmd_verify)
+
+    emit = sub.add_parser("emit", help="sign and anchor a payload into a bundle")
+    emit.add_argument("--payload-file", required=True, help="file whose bytes become the payload")
+    emit.add_argument("--out", required=True, help="path to write the bundle JSON")
+    emit.add_argument("--key", help="use an existing 32 byte raw Ed25519 seed file")
+    emit.add_argument("--new-key", help="generate a signing key and save it to this file")
+    emit.set_defaults(func=_cmd_emit)
+
+    return parser
+
+
+def main(argv=None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

proofbundle/emit.py

@@ -0,0 +1,138 @@
+"""Evidence bundle emitter (v0.2).
+
+Sign a payload with Ed25519 and anchor it as the last leaf of an RFC 6962
+Merkle tree, producing a bundle that ``verify_bundle`` accepts. This is the
+counterpart to the verifier: create the evidence here, check it anywhere with
+``proofbundle verify``, fully offline.
+
+The v0.3 eval-receipt emitter (wrap one evaluation run into a signed,
+selectively disclosable receipt) is still a roadmap stub at the bottom of this
+module.
+"""
+
+from __future__ import annotations
+
+import base64
+import os
+from typing import Optional, Sequence
+
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
+from cryptography.hazmat.primitives.serialization import (
+    Encoding,
+    NoEncryption,
+    PrivateFormat,
+    PublicFormat,
+)
+
+from . import merkle
+from .bundle import SCHEMA
+
+__all__ = [
+    "generate_signer",
+    "save_signer",
+    "load_signer",
+    "emit_bundle",
+]
+
+
+def _b64(data: bytes) -> str:
+    return base64.b64encode(data).decode("ascii")
+
+
+def _raw_pub(key: Ed25519PrivateKey) -> bytes:
+    return key.public_key().public_bytes(Encoding.Raw, PublicFormat.Raw)
+
+
+def generate_signer() -> Ed25519PrivateKey:
+    """Generate a fresh Ed25519 signing key."""
+    return Ed25519PrivateKey.generate()
+
+
+def save_signer(key: Ed25519PrivateKey, path: str) -> None:
+    """Write the 32 byte raw Ed25519 private seed to ``path``, mode 0600.
+
+    This is a secret. The file is created owner-read/write only (never
+    world-readable, even briefly), so an accidental commit or a shared directory
+    does not leak the key. Store it out of version control and treat it like a
+    key, not like data.
+    """
+    raw = key.private_bytes(Encoding.Raw, PrivateFormat.Raw, NoEncryption())
+    # Open with 0600 from the start to avoid a world-readable window.
+    fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+    with os.fdopen(fd, "wb") as handle:
+        handle.write(raw)
+
+
+def load_signer(path: str) -> Ed25519PrivateKey:
+    """Load an Ed25519 signing key from a 32 byte raw seed file."""
+    with open(path, "rb") as handle:
+        return Ed25519PrivateKey.from_private_bytes(handle.read())
+
+
+def emit_bundle(
+    payload: bytes,
+    signer: Ed25519PrivateKey,
+    *,
+    prior_leaves: Sequence[bytes] = (),
+    sd_jwt_vc: Optional[dict] = None,
+) -> dict:
+    """Produce a ``proofbundle/v0.1`` bundle for ``payload``.
+
+    The payload is signed with ``signer`` and appended as the last leaf of an
+    RFC 6962 Merkle tree over ``prior_leaves + [payload]``. The returned dict is
+    accepted by :func:`proofbundle.verify_bundle`.
+
+    ``sd_jwt_vc`` is passed through verbatim if given (for example
+    ``{"compact": "...", "issuer_public_key_b64": "..."}``).
+    """
+    leaves = list(prior_leaves) + [payload]
+    index = len(leaves) - 1
+    root = merkle.merkle_tree_hash(leaves)
+    proof = merkle.inclusion_proof(leaves, index)
+    signature = signer.sign(payload)
+
+    bundle = {
+        "schema": SCHEMA,
+        "payload_b64": _b64(payload),
+        "signature": {
+            "alg": "ed25519",
+            "public_key_b64": _b64(_raw_pub(signer)),
+            "sig_b64": _b64(signature),
+        },
+        "merkle": {
+            "hash_alg": "sha256-rfc6962",
+            "leaf_index": index,
+            "tree_size": len(leaves),
+            "inclusion_proof_b64": [_b64(p) for p in proof],
+            "root_b64": _b64(root),
+        },
+    }
+    if sd_jwt_vc is not None:
+        bundle["sd_jwt_vc"] = sd_jwt_vc
+    return bundle
+
+
+# --------------------------------------------------------------------------
+# Roadmap stub, v0.3
+# --------------------------------------------------------------------------
+
+
+class NotYetImplemented(NotImplementedError):
+    """Raised by roadmap functions that are planned but not implemented yet."""
+
+
+def emit_eval_receipt(*args, **kwargs):  # pragma: no cover - roadmap stub
+    """v0.3, the core differentiator.
+
+    Wrap one evaluation framework run (Inspect AI, lm-evaluation-harness) into a
+    signed receipt whose payload is a minimal, RFC 8785 canonicalized claim such
+    as ``{"suite": "...", "threshold": 0.8, "passed": true}``, optionally wrapped
+    as an SD-JWT VC so a holder can disclose "passed above threshold" without
+    revealing the model, weights or dataset, carrying a cluster-bootstrap
+    confidence interval, a multiple-testing correction and a preregistration
+    hash. Built on top of :func:`emit_bundle`.
+    """
+    raise NotYetImplemented(
+        "emit_eval_receipt lands in v0.3. Use emit_bundle for a generic signed, "
+        "anchored bundle today."
+    )

proofbundle/errors.py

@@ -0,0 +1,54 @@
+"""Exception and result types for proofbundle."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import List
+
+
+class ProofBundleError(Exception):
+    """Base class for all proofbundle errors."""
+
+
+class BundleFormatError(ProofBundleError):
+    """The bundle JSON is missing fields or is malformed."""
+
+
+class UnsupportedError(ProofBundleError):
+    """The bundle uses an algorithm or schema this version does not support."""
+
+
+@dataclass
+class Check:
+    """Result of a single verification step."""
+
+    name: str
+    ok: bool
+    detail: str = ""
+
+    def __str__(self) -> str:  # pragma: no cover - cosmetic
+        mark = "PASS" if self.ok else "FAIL"
+        return f"[{mark}] {self.name}: {self.detail}".rstrip(": ")
+
+
+@dataclass
+class VerificationResult:
+    """Aggregate result of verifying an evidence bundle."""
+
+    checks: List[Check] = field(default_factory=list)
+
+    @property
+    def ok(self) -> bool:
+        """True only if every check that ran passed and at least one ran."""
+        return bool(self.checks) and all(c.ok for c in self.checks)
+
+    def add(self, name: str, ok: bool, detail: str = "") -> None:
+        self.checks.append(Check(name, ok, detail))
+
+    def as_dict(self) -> dict:
+        return {
+            "ok": self.ok,
+            "checks": [
+                {"name": c.name, "ok": c.ok, "detail": c.detail} for c in self.checks
+            ],
+        }

proofbundle/merkle.py

@@ -0,0 +1,186 @@
+"""RFC 6962 / RFC 9162 Merkle tree hashing, inclusion and consistency proofs.
+
+This module implements the Certificate Transparency Merkle tree exactly as
+specified in RFC 6962 (updated by RFC 9162), so bundles verify against the same
+primitives used by Sigstore Rekor, Certificate Transparency and tlog-tiles.
+
+Leaf hash:  SHA-256(0x00 || data)
+Node hash:  SHA-256(0x01 || left || right)
+
+Only the verification functions (``root_from_inclusion``, ``verify_inclusion``,
+``verify_consistency``) are part of the stable public API. The tree builder and
+proof generators are provided so tests and examples can produce real proofs and
+so callers can anchor their own evidence, but a production log would generate
+these on the server side.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+from typing import List
+
+__all__ = [
+    "leaf_hash",
+    "merkle_tree_hash",
+    "inclusion_proof",
+    "consistency_proof",
+    "root_from_inclusion",
+    "verify_inclusion",
+    "verify_consistency",
+]
+
+
+def leaf_hash(data: bytes) -> bytes:
+    """RFC 6962 leaf hash: SHA-256(0x00 || data)."""
+    return hashlib.sha256(b"\x00" + data).digest()
+
+
+def _node_hash(left: bytes, right: bytes) -> bytes:
+    """RFC 6962 interior node hash: SHA-256(0x01 || left || right)."""
+    return hashlib.sha256(b"\x01" + left + right).digest()
+
+
+def _largest_power_of_two_less_than(n: int) -> int:
+    """Largest power of two k such that k < n <= 2k, for n >= 2."""
+    if n < 2:
+        raise ValueError("n must be >= 2")
+    k = 1
+    while k * 2 < n:
+        k *= 2
+    return k
+
+
+def merkle_tree_hash(leaves: List[bytes]) -> bytes:
+    """Merkle Tree Hash (MTH) over a list of leaf *data* values (RFC 6962 2.1)."""
+    n = len(leaves)
+    if n == 0:
+        return hashlib.sha256(b"").digest()
+    if n == 1:
+        return leaf_hash(leaves[0])
+    k = _largest_power_of_two_less_than(n)
+    return _node_hash(merkle_tree_hash(leaves[:k]), merkle_tree_hash(leaves[k:]))
+
+
+def inclusion_proof(leaves: List[bytes], index: int) -> List[bytes]:
+    """Audit path for ``leaves[index]`` (siblings ordered leaf to root)."""
+    n = len(leaves)
+    if not 0 <= index < n:
+        raise ValueError("index out of range")
+    return _inclusion(leaves, index)
+
+
+def _inclusion(leaves: List[bytes], m: int) -> List[bytes]:
+    n = len(leaves)
+    if n == 1:
+        return []
+    k = _largest_power_of_two_less_than(n)
+    if m < k:
+        return _inclusion(leaves[:k], m) + [merkle_tree_hash(leaves[k:])]
+    return _inclusion(leaves[k:], m - k) + [merkle_tree_hash(leaves[:k])]
+
+
+def consistency_proof(leaves: List[bytes], first: int) -> List[bytes]:
+    """Consistency proof between tree sizes ``first`` and ``len(leaves)`` (RFC 6962 2.1.2)."""
+    second = len(leaves)
+    if not 0 < first <= second:
+        raise ValueError("require 0 < first <= len(leaves)")
+    return _subproof(first, leaves, True)
+
+
+def _subproof(m: int, leaves: List[bytes], b: bool) -> List[bytes]:
+    n = len(leaves)
+    if m == n:
+        return [] if b else [merkle_tree_hash(leaves)]
+    k = _largest_power_of_two_less_than(n)
+    if m <= k:
+        return _subproof(m, leaves[:k], b) + [merkle_tree_hash(leaves[k:])]
+    return _subproof(m - k, leaves[k:], False) + [merkle_tree_hash(leaves[:k])]
+
+
+def root_from_inclusion(
+    leaf_index: int, tree_size: int, computed_leaf_hash: bytes, proof: List[bytes]
+) -> bytes:
+    """Recompute the tree root from an inclusion proof (RFC 9162 2.1.3.2)."""
+    if not 0 <= leaf_index < tree_size:
+        raise ValueError("leaf_index out of range for tree_size")
+    fn = leaf_index
+    sn = tree_size - 1
+    r = computed_leaf_hash
+    for p in proof:
+        if sn == 0:
+            raise ValueError("inclusion proof too long")
+        if (fn & 1) == 1 or fn == sn:
+            r = _node_hash(p, r)
+            if (fn & 1) == 0:
+                while (fn & 1) == 0 and fn != 0:
+                    fn >>= 1
+                    sn >>= 1
+        else:
+            r = _node_hash(r, p)
+        fn >>= 1
+        sn >>= 1
+    if sn != 0:
+        raise ValueError("inclusion proof too short")
+    return r
+
+
+def verify_inclusion(
+    leaf_data: bytes,
+    leaf_index: int,
+    tree_size: int,
+    proof: List[bytes],
+    expected_root: bytes,
+) -> bool:
+    """Return True iff ``leaf_data`` is included at ``leaf_index`` under ``expected_root``."""
+    try:
+        computed = root_from_inclusion(leaf_index, tree_size, leaf_hash(leaf_data), proof)
+    except ValueError:
+        return False
+    return hmac.compare_digest(computed, expected_root)
+
+
+def verify_consistency(
+    first_size: int,
+    second_size: int,
+    proof: List[bytes],
+    first_root: bytes,
+    second_root: bytes,
+) -> bool:
+    """Return True iff ``first_root`` is a consistent prefix of ``second_root`` (RFC 9162 2.1.4.2)."""
+    if first_size <= 0 or first_size > second_size:
+        return False
+    if first_size == second_size:
+        return not proof and hmac.compare_digest(first_root, second_root)
+    path = list(proof)
+    # If first is an exact power of two, prepend first_root to the path.
+    if first_size & (first_size - 1) == 0:
+        path = [first_root] + path
+    if not path:
+        return False
+    fn = first_size - 1
+    sn = second_size - 1
+    while fn & 1:
+        fn >>= 1
+        sn >>= 1
+    fr = path[0]
+    sr = path[0]
+    for c in path[1:]:
+        if sn == 0:
+            return False
+        if (fn & 1) == 1 or fn == sn:
+            fr = _node_hash(c, fr)
+            sr = _node_hash(c, sr)
+            if (fn & 1) == 0:
+                while (fn & 1) == 0 and fn != 0:
+                    fn >>= 1
+                    sn >>= 1
+        else:
+            sr = _node_hash(sr, c)
+        fn >>= 1
+        sn >>= 1
+    return (
+        fn == 0
+        and hmac.compare_digest(fr, first_root)
+        and hmac.compare_digest(sr, second_root)
+    )

proofbundle/sdjwt.py

@@ -0,0 +1,134 @@
+"""Minimal SD-JWT selective disclosure verification.
+
+The SD-JWT *core* is now a published standard, RFC 9901 (December 2025). This
+module verifies the heart of it: that every presented Disclosure hashes to a
+digest that is actually committed in the issuer-signed JWT payload, and, if an
+issuer public key is supplied and the algorithm is EdDSA, that the issuer
+signature over the JWT is valid.
+
+Note the layering: RFC 9901 is the SD-JWT mechanism; **SD-JWT VC** (the
+credential type profile) is still an IETF draft,
+``draft-ietf-oauth-sd-jwt-vc`` — this verifier does not yet do VC-level checks.
+
+Scope of v0.1, stated honestly (see README security notes):
+  - EdDSA (Ed25519) issuer signatures only.
+  - No Key Binding JWT verification (a trailing key-binding token is ignored).
+  - No X.509 / trust-list / status-list checks, no ``vct`` type-metadata
+    resolution. Full SD-JWT VC conformance is on the roadmap.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+from typing import Optional, Set
+
+from .signature import verify_ed25519
+
+__all__ = ["verify_sd_jwt"]
+
+_HASH_ALG = {"sha-256": "sha256", "sha-384": "sha384", "sha-512": "sha512"}
+
+
+def _b64url_decode(s: str) -> bytes:
+    raw = s.encode("ascii")
+    return base64.urlsafe_b64decode(raw + b"=" * (-len(raw) % 4))
+
+
+def _b64url_nopad(b: bytes) -> str:
+    return base64.urlsafe_b64encode(b).rstrip(b"=").decode("ascii")
+
+
+def _digest(disclosure_b64: str, alg: str) -> str:
+    h = hashlib.new(_HASH_ALG[alg])
+    h.update(disclosure_b64.encode("ascii"))
+    return _b64url_nopad(h.digest())
+
+
+def _collect_committed_digests(node, out: Set[str]) -> None:
+    if isinstance(node, dict):
+        for key, value in node.items():
+            if key == "_sd" and isinstance(value, list):
+                out.update(d for d in value if isinstance(d, str))
+            elif key == "...":
+                if isinstance(value, str):
+                    out.add(value)
+            else:
+                _collect_committed_digests(value, out)
+    elif isinstance(node, list):
+        for item in node:
+            _collect_committed_digests(item, out)
+
+
+def verify_sd_jwt(compact: str, issuer_pubkey: Optional[bytes] = None) -> dict:
+    """Verify an SD-JWT compact serialization.
+
+    Returns a dict with keys: ``structure_ok`` (disclosures all committed),
+    ``sig_checked``, ``sig_ok``, ``alg`` and ``detail``.
+    """
+    result = {
+        "structure_ok": False,
+        "sig_checked": False,
+        "sig_ok": False,
+        "alg": None,
+        "detail": "",
+    }
+    parts = compact.split("~")
+    if len(parts) < 1 or parts[0].count(".") != 2:
+        result["detail"] = "not a compact SD-JWT"
+        return result
+
+    header_b64, payload_b64, sig_b64 = parts[0].split(".")
+    try:
+        header = json.loads(_b64url_decode(header_b64))
+        payload = json.loads(_b64url_decode(payload_b64))
+    except (ValueError, json.JSONDecodeError):
+        result["detail"] = "malformed JWT header or payload"
+        return result
+
+    alg = header.get("alg")
+    result["alg"] = alg
+    sd_alg = payload.get("_sd_alg", "sha-256")
+    if sd_alg not in _HASH_ALG:
+        result["detail"] = f"unsupported _sd_alg {sd_alg}"
+        return result
+
+    # Disclosures are the non-empty middle parts; a trailing key-binding token
+    # (which contains dots) is ignored in v0.1.
+    disclosures = [p for p in parts[1:] if p and p.count(".") == 0]
+
+    committed: Set[str] = set()
+    _collect_committed_digests(payload, committed)
+
+    all_committed = True
+    for d in disclosures:
+        try:
+            parsed = json.loads(_b64url_decode(d))
+        except (ValueError, json.JSONDecodeError):
+            all_committed = False
+            break
+        if not (isinstance(parsed, list) and len(parsed) in (2, 3)):
+            all_committed = False
+            break
+        if _digest(d, sd_alg) not in committed:
+            all_committed = False
+            break
+    result["structure_ok"] = all_committed and bool(parts[0])
+
+    if issuer_pubkey is not None:
+        result["sig_checked"] = True
+        if alg == "EdDSA":
+            signing_input = f"{header_b64}.{payload_b64}".encode("ascii")
+            try:
+                result["sig_ok"] = verify_ed25519(
+                    issuer_pubkey, _b64url_decode(sig_b64), signing_input
+                )
+            except ValueError:
+                result["sig_ok"] = False
+        else:
+            result["detail"] = f"issuer signature alg {alg} not supported in v0.1"
+
+    if not result["detail"]:
+        result["detail"] = f"{len(disclosures)} disclosure(s)"
+    return result

proofbundle/signature.py

@@ -0,0 +1,29 @@
+"""Ed25519 signature verification.
+
+Wraps ``cryptography`` so we never implement signature math ourselves. Only
+verification is exposed as public API; key generation and signing live in the
+examples and are meant for tests and local demos, not for production issuance.
+"""
+
+from __future__ import annotations
+
+from cryptography.exceptions import InvalidSignature
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
+
+__all__ = ["verify_ed25519"]
+
+
+def verify_ed25519(public_key: bytes, signature: bytes, message: bytes) -> bool:
+    """Return True iff ``signature`` is a valid Ed25519 signature over ``message``.
+
+    ``public_key`` must be the 32 byte raw Ed25519 public key and ``signature``
+    the 64 byte raw signature. Any malformed input returns False rather than
+    raising, so callers get a boolean per check.
+    """
+    if len(public_key) != 32 or len(signature) != 64:
+        return False
+    try:
+        Ed25519PublicKey.from_public_bytes(public_key).verify(signature, message)
+        return True
+    except (InvalidSignature, ValueError):
+        return False

proofbundle-0.3.0.dist-info/METADATA

@@ -0,0 +1,291 @@
+Metadata-Version: 2.4
+Name: proofbundle
+Version: 0.3.0
+Summary: Emit and verify portable cryptographic evidence bundles, offline: Ed25519 + RFC 6962 Merkle + optional SD-JWT.
+Author: Konrad Gruszka
+License: MIT
+Project-URL: Homepage, https://b7n0de.com
+Project-URL: Repository, https://github.com/b7n0de/proofbundle
+Project-URL: Issues, https://github.com/b7n0de/proofbundle/issues
+Project-URL: Changelog, https://github.com/b7n0de/proofbundle/blob/main/CHANGELOG.md
+Project-URL: Documentation, https://github.com/b7n0de/proofbundle#readme
+Keywords: cryptography,merkle,transparency-log,ed25519,sd-jwt,verifiable-credentials,attestation,provenance,rfc6962
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security :: Cryptography
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: cryptography>=42
+Provides-Extra: sdjwt
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: ruff>=0.5; extra == "dev"
+Requires-Dist: jsonschema>=4; extra == "dev"
+Requires-Dist: mypy>=1.8; extra == "dev"
+Requires-Dist: build>=1; extra == "dev"
+Requires-Dist: hypothesis>=6; extra == "dev"
+Dynamic: license-file
+
+<div align="center">
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="assets/b7n0de-logo-dark.svg">
+  <img alt="b7n0de, Verified AI Work" src="assets/b7n0de-logo.svg" height="60">
+</picture>
+
+<h1>proofbundle</h1>
+
+**Emit and verify, fully offline, portable evidence that a piece of data was
+signed and anchored in a tamper-evident log — and optionally carries a
+selectively disclosable credential. Pure Python, no server, no daemon, one JSON file.**
+
+[![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?color=D6248A)](https://pypi.org/project/proofbundle/)
+[![Python](https://img.shields.io/pypi/pyversions/proofbundle.svg?color=D6248A)](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)
+[![SLSA build provenance](https://img.shields.io/badge/SLSA-build_provenance-D6248A.svg)](https://slsa.dev)
+
+</div>
+
+**At a glance:** `proofbundle emit` signs and anchors a payload; `proofbundle
+verify` checks one self-contained `bundle.json` with three offline cryptographic
+checks → `OK` or `FAILED`. No network, no daemon, no own crypto. 25 tests.
+
+## Contents
+
+- [Why](#why)
+- [What it verifies](#what-it-verifies)
+- [How it fits together](#how-it-fits-together)
+- [Install](#install)
+- [Quickstart](#quickstart)
+- [Interoperability](#interoperability)
+- [Bundle format](#bundle-format-proofbundlev01)
+- [Security notes and scope](#security-notes-and-scope-stated-honestly)
+- [Roadmap](#roadmap)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Why
+
+Cryptographic evidence today usually needs a running service to check it.
+Sigstore Rekor, Certificate Transparency and other transparency logs are
+excellent, but verifying an inclusion proof normally means talking to a log
+server or wiring up Go tooling. There is no small, portable, Python-native
+verifier that takes one self-contained file and answers a simple question
+offline:
+
+*Were these exact bytes signed by this key, and anchored under this Merkle root,
+yes or no.*
+
+`proofbundle` is that verifier — and, since v0.2, the matching emitter. It is
+the verification half of a larger idea: turning a reproducible result (for
+example an AI evaluation run) into a signed, third-party-verifiable, selectively
+disclosable receipt. The verifier shipped first, small and correct, so it could
+be reviewed and trusted on its own; `emit_bundle` now creates bundles that
+`verify_bundle` accepts, fully offline on both sides.
+
+## What it verifies
+
+A bundle is a single JSON document. `proofbundle` checks, offline:
+
+1. **ed25519-signature** — the payload was signed by the stated Ed25519 key
+2. **merkle-inclusion** — the payload is anchored under the stated tree root,
+   using an RFC 6962 / RFC 9162 inclusion proof (the same primitive as Rekor and
+   Certificate Transparency)
+3. **sd-jwt** (optional) — an embedded SD-JWT selective-disclosure credential is
+   well formed, and if an issuer key is given, correctly issuer-signed
+
+The verifier treats the payload as opaque bytes. It proves that these exact
+bytes were signed and anchored, not what they mean. That is on purpose: it keeps
+the trusted core tiny.
+
+## How it fits together
+
+```mermaid
+flowchart LR
+    P["payload bytes"]
+    P -->|"Ed25519 sign"| S["signature"]
+    P -->|"RFC 6962 anchor"| M["Merkle inclusion proof"]
+    SD["SD-JWT VC (optional)"] -.-> B
+    S --> B["bundle.json"]
+    M --> B
+    B --> V{{"proofbundle verify"}}
+    V --> C1["ed25519-signature"]
+    V --> C2["merkle-inclusion"]
+    V --> C3["sd-jwt (optional)"]
+    C1 --> R{"all checks pass?"}
+    C2 --> R
+    C3 --> R
+    R -->|yes| OK(["=> OK &nbsp; exit 0"])
+    R -->|no| FAIL(["=> FAILED &nbsp; exit 1"])
+
+    style V fill:#D6248A,stroke:#D6248A,color:#fff
+    style OK fill:#D6248A,stroke:#D6248A,color:#fff
+    style FAIL fill:#ef4444,stroke:#ef4444,color:#fff
+```
+
+## Install
+
+```bash
+pip install proofbundle
+```
+
+Requires Python 3.9+ and [`cryptography`](https://cryptography.io). Signature
+math is delegated to `cryptography`; this project never rolls its own crypto.
+The Merkle and SD-JWT logic is pure standard library.
+
+SD-JWT support is an optional extra (it adds no runtime dependency beyond the
+core `cryptography`, so the trusted core stays lean):
+
+```bash
+pip install "proofbundle[sdjwt]"
+```
+
+## Quickstart
+
+```bash
+# generate a real example bundle with throwaway keys
+python examples/make_example.py
+
+# verify it
+proofbundle verify examples/example_bundle.json
+```
+
+<div align="center">
+<img src="assets/demo.svg" alt="proofbundle verify output: four PASS checks and OK" width="680">
+</div>
+
+Machine-readable output and a non-zero exit code on failure:
+
+```bash
+proofbundle verify --json bundle.json   # exit 0 = ok, 1 = failed, 2 = malformed
+```
+
+Emit a bundle of your own (v0.2): sign a payload with a fresh key and anchor it,
+then verify it anywhere, offline.
+
+```bash
+proofbundle emit --payload-file result.json --new-key signer.key --out bundle.json
+proofbundle verify bundle.json
+```
+
+Library use:
+
+```python
+from proofbundle import verify_bundle
+
+result = verify_bundle("bundle.json")
+print(result.ok)          # True / False
+for check in result.checks:
+    print(check.name, check.ok, check.detail)
+```
+
+Verify a consistency proof between two log states directly:
+
+```python
+from proofbundle import verify_consistency
+verify_consistency(first_size, second_size, proof, first_root, second_root)  # -> bool
+```
+
+## Interoperability
+
+proofbundle uses the same RFC 6962 / RFC 9162 Merkle primitive as
+[Sigstore Rekor](https://docs.sigstore.dev/) and Certificate Transparency, so its
+`verify_inclusion` checks a real proof from a live transparency log, not just its
+own bundles. [`examples/rekor_interop.py`](examples/rekor_interop.py) verifies a
+real Sigstore Rekor inclusion proof (a committed fixture, `logIndex` 25579 in a
+4.16-million-entry tree) **fully offline**, and documents the field mapping from
+the Rekor bundle and its C2SP `tlog-checkpoint` signed note to proofbundle's
+`merkle` object. Correctness is also checked against external RFC 6962 test
+vectors vendored from
+[transparency-dev/merkle](https://github.com/transparency-dev/merkle) (see
+`tests/fixtures/`), plus Hypothesis property tests.
+
+## Bundle format (`proofbundle/v0.1`)
+
+The format is specified normatively in [SPEC.md](SPEC.md) (fields, encodings,
+RFC 6962 hashing, verification order) with a machine-readable JSON Schema at
+[`schemas/proofbundle_v0_1.schema.json`](schemas/proofbundle_v0_1.schema.json).
+
+```json
+{
+  "schema": "proofbundle/v0.1",
+  "payload_b64": "<the exact bytes that were signed and anchored>",
+  "signature": { "alg": "ed25519", "public_key_b64": "...", "sig_b64": "..." },
+  "merkle": {
+    "hash_alg": "sha256-rfc6962",
+    "leaf_index": 1,
+    "tree_size": 4,
+    "inclusion_proof_b64": ["...", "..."],
+    "root_b64": "..."
+  },
+  "sd_jwt_vc": { "compact": "<sd-jwt>", "issuer_public_key_b64": "..." }
+}
+```
+
+`sd_jwt_vc` is optional. Base64 fields are standard base64; the SD-JWT compact
+string uses base64url as per the spec.
+
+## Security notes and scope, stated honestly
+
+This is v0.1. It does exactly what it says and no more:
+
+- Ed25519 signatures only, for both the payload and the optional SD-JWT issuer
+  signature.
+- SD-JWT: the SD-JWT core is now [RFC 9901](https://datatracker.ietf.org/doc/rfc9901/)
+  (Dec 2025); this verifies that every presented disclosure is committed in the
+  issuer-signed payload, and the issuer signature (EdDSA) if a key is supplied. It
+  does **not** verify a Key Binding JWT, an X.509 or trust-list chain, status
+  lists, or `vct` type metadata. **SD-JWT VC** (the credential-type profile) is
+  still an IETF draft ([draft-ietf-oauth-sd-jwt-vc](https://datatracker.ietf.org/doc/draft-ietf-oauth-sd-jwt-vc/));
+  full VC conformance is on the roadmap.
+- The verifier does not fetch anything. Trust anchors (the signer key, the
+  expected root) are inputs you supply out of band.
+- No custom cryptography. Ed25519 comes from `cryptography`; Merkle hashing is
+  RFC 6962.
+
+If you find a correctness or security issue, please open an issue or see
+[SECURITY.md](SECURITY.md).
+
+## Roadmap
+
+- **v0.1** — the offline verifier plus a real example bundle.
+- **v0.2 (current release)** — the emitter: `emit_bundle` signs a payload with
+  Ed25519 and anchors it as the last leaf of an RFC 6962 Merkle tree, producing
+  a bundle that `verify_bundle` accepts. Available as `proofbundle emit`.
+- **v0.3** — an eval-receipt emitter: wrap one evaluation framework run
+  ([Inspect AI](https://github.com/UKGovernmentBEIS/inspect_ai),
+  [lm-evaluation-harness](https://github.com/EleutherAI/lm-evaluation-harness))
+  into a signed receipt whose payload is a minimal canonical claim, for example
+  `{"suite": "...", "threshold": 0.8, "passed": true}`, optionally wrapped as an
+  SD-JWT VC so a holder can disclose *passed above threshold* without revealing
+  the model, weights or dataset, and carrying a cluster-bootstrap confidence
+  interval, a multiple-testing correction and a preregistration hash.
+
+That last step is the point: today no widely used AI project turns a
+reproducible evaluation result into a signed, third-party-verifiable,
+selectively disclosable receipt. This repository is the trustworthy verification
+core that makes it possible.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) and the
+[Code of Conduct](CODE_OF_CONDUCT.md). Good first issues are labeled
+[`good-first-issue`](https://github.com/b7n0de/proofbundle/labels/good-first-issue).
+The verifier core aims to stay small, dependency-light and correct.
+
+## License
+
+MIT, see [LICENSE](LICENSE).
+
+---
+
+<p align="center"><sub>proofbundle is part of <b>b7n0de</b>, Verified AI Work &middot; <a href="https://b7n0de.com">b7n0de.com</a></sub></p>

proofbundle-0.3.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+proofbundle/__init__.py,sha256=WkhrTxUxBqfNE2HhSZpsdO3zi5O5DeCr-6oAUN8E8xU,851
+proofbundle/bundle.py,sha256=GIZrKGXO1shczL0CTN5ORvdeWKlmNLCXQyvSD3TtkPs,4438
+proofbundle/cli.py,sha256=d0Gp3ocpbCP3OZQQ5ftU4fuHd_1I26CcPdkDEllSd70,3057
+proofbundle/emit.py,sha256=jrdFsgNsiuOfPCI2euCSk2VizG3t-iRTTP4OPunUKVI,4612
+proofbundle/errors.py,sha256=zDwnBWTfuLWZdFoekj6bu_KZd668bj-j_DgKMv9hmEU,1435
+proofbundle/merkle.py,sha256=vc-_JX7cJ6APNY49R-jVESbIE4689IJRokNQOMp2kDc,5861
+proofbundle/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+proofbundle/sdjwt.py,sha256=B9Vy81IUrtyq2GHOhkS7reWtnsS4x16DAeioKL2cKns,4633
+proofbundle/signature.py,sha256=jrHQtJPQCp0-doPYoV5rlgDU8UhUOXknVx2EE95dJ6E,1104
+proofbundle-0.3.0.dist-info/licenses/LICENSE,sha256=5Jiib6WCXMfnvSVE-XCQBZvTdD21rgcMJoWoag5VXLE,1071
+proofbundle-0.3.0.dist-info/METADATA,sha256=lzbp4pc8n5OtFtUnFOHGjpRx9Z52JMDmuyAmHhbF-zc,11595
+proofbundle-0.3.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+proofbundle-0.3.0.dist-info/entry_points.txt,sha256=sUKwm8FUtcr2Fgpi6-mkvzdD57NcMCO3kF6eGQVaARU,53
+proofbundle-0.3.0.dist-info/top_level.txt,sha256=lI10iF5LAz1Cg2LiOztawA6KQe0sgTvS0JgK03nejJI,12
+proofbundle-0.3.0.dist-info/RECORD,,

proofbundle-0.3.0.dist-info/WHEEL

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

proofbundle-0.3.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+proofbundle = proofbundle.cli:main

proofbundle-0.3.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Konrad Gruszka
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

proofbundle-0.3.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+proofbundle