proofbundle 1.1.0__tar.gz → 1.2.0__tar.gz

{proofbundle-1.1.0/src/proofbundle.egg-info → proofbundle-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: proofbundle
-Version: 1.1.0
+Version: 1.2.0
 Summary: Emit and verify portable cryptographic evidence bundles, offline: Ed25519 + RFC 6962 Merkle + optional SD-JWT.
 Author: Konrad Gruszka
 License: MIT
@@ -73,7 +73,7 @@ no server, no network.**
 
 **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. 102 tests.
+checks → `OK` or `FAILED`. No network, no daemon, no own crypto. 148 tests.
 
 ## Contents
 
@@ -148,6 +148,12 @@ A bundle is a single JSON document. `proofbundle` checks, offline:
    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
+4. **sd-jwt-key-binding** (optional, v1.2) — if the SD-JWT carries a Key Binding
+   JWT (RFC 9901 §4.3), it is verified **fail-closed**: `typ` is `kb+jwt`,
+   `iat`/`aud`/`nonce`/`sd_hash` are present, `sd_hash` binds the exact presented
+   disclosure set, and the signature verifies under the issuer-bound `cnf.jwk`
+   holder key. A present-but-broken KB-JWT fails the bundle — it is never
+   silently ignored.
 
 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
@@ -160,16 +166,18 @@ flowchart LR
     P["payload bytes"]
     P -->|"Ed25519 sign"| S["signature"]
     P -->|"RFC 6962 anchor"| M["Merkle inclusion proof"]
-    SD["SD-JWT VC (optional)"] -.-> B
+    SD["SD-JWT VC + KB-JWT (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)"]
+    V --> C4["key binding (optional)"]
     C1 --> R{"all checks pass?"}
     C2 --> R
     C3 --> R
+    C4 --> R
     R -->|yes| OK(["=> OK   exit 0"])
     R -->|no| FAIL(["=> FAILED   exit 1"])
 
@@ -215,6 +223,14 @@ Machine-readable output and a non-zero exit code on failure:
 proofbundle verify --json bundle.json   # exit 0 = ok, 1 = failed, 2 = malformed
 ```
 
+Debugging an inclusion proof (v1.2): `--verbose` prints the recomputed Merkle
+root next to the stated root, so a `FAIL` shows *which* root your payload
+actually anchors to:
+
+```bash
+proofbundle verify --verbose bundle.json
+```
+
 Emit a bundle of your own (v0.2): sign a payload with a fresh key and anchor it,
 then verify it anywhere, offline.
 
@@ -289,6 +305,13 @@ vectors vendored from
 [transparency-dev/merkle](https://github.com/transparency-dev/merkle) (see
 `tests/fixtures/`), plus Hypothesis property tests.
 
+Since v1.2 proofbundle also speaks the witness layer:
+[C2SP tlog-cosignature](https://github.com/C2SP/C2SP/blob/main/tlog-cosignature.md)
+(Ed25519 cosignature/v1) — `verify_witnessed_checkpoint` checks a checkpoint is
+both log-signed **and** cosigned by a quorum of distinct witnesses, offline,
+which rules out a split view by the log operator. This is the same
+witnessed-checkpoint pattern Rekor v2 (GA October 2025) institutionalizes.
+
 ## Bundle format (`proofbundle/v0.1`)
 
 The format is specified normatively in [SPEC.md](SPEC.md) (fields, encodings,
@@ -312,23 +335,32 @@ RFC 6962 hashing, verification order) with a machine-readable JSON Schema at
 ```
 
 `sd_jwt_vc` is optional. Base64 fields are standard base64; the SD-JWT compact
-string uses base64url as per the spec.
+string uses base64url as per the spec. The compact string MAY end in a Key
+Binding JWT (instead of the trailing `~`), which is then verified (v1.2).
 
 ## Security notes and scope, stated honestly
 
 The scope is deliberately narrow. It does exactly what it says and no more:
 
-- Ed25519 signatures only, for both the payload and the optional SD-JWT issuer
-  signature.
+- Ed25519 signatures only, for the payload, the optional SD-JWT issuer
+  signature, and the optional KB-JWT holder signature.
 - SD-JWT: the SD-JWT core is now [RFC 9901](https://datatracker.ietf.org/doc/rfc9901/)
   (November 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/));
+  issuer-signed payload, the issuer signature (EdDSA) if a key is supplied, and — since
+  v1.2, fail-closed — a Key Binding JWT if one is attached (RFC 9901 §4.3: `kb+jwt`
+  typ, required `iat`/`aud`/`nonce`/`sd_hash`, `sd_hash` over the presented disclosure
+  set, holder signature under the issuer-bound `cnf.jwk`). `aud`/`nonce` *values* and
+  `iat` freshness are relying-party policy (an offline verifier has no trusted clock);
+  pass `expected_aud`/`expected_nonce` to `verify_key_binding` to enforce them. It does
+  **not** verify 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.
+- Witness cosignatures (v1.2) prove consistency *observations* by the listed
+  witnesses; real split-view resistance additionally requires the witnesses to be
+  operationally independent — a deployment property no file format can supply.
 - The verifier does not fetch anything. Trust anchors (the signer key, the
-  expected root) are inputs you supply out of band.
+  expected root, witness keys) are inputs you supply out of band.
 - No custom cryptography. Ed25519 comes from `cryptography`; Merkle hashing is
   RFC 6962.
 
@@ -404,13 +436,17 @@ threshold was met without revealing the model or the data. See [INTEROP.md](INTE
   in-toto verifier understands it. Alongside the self-hosted-predicate `to_intoto_statement` (see
   [PREDICATE.md](PREDICATE.md)). Metric details live in `annotations` (test-result has no native metric
   field); the model/dataset stay salted commitments, never `sha256`.
-- **C2SP tlog-checkpoint** (v0.9) — `proofbundle.checkpoint.sign_checkpoint(origin, tree_size, root, …)`
-  emits a valid [C2SP](https://github.com/C2SP/C2SP/blob/main/tlog-checkpoint.md) signed note over the
-  RFC 6962 Merkle root, making a receipt witness-network / transparency-log compatible. Pure serialization
-  over the Ed25519 key already in use — no new crypto.
-- **SD-JWT issuance** (RFC 9901, verified Nov 2025) — `proofbundle.sdjwt_issue.issue_sd_jwt(claim, signer,
-  root_b64=…, exact_score=…)` issues the receipt so a holder can disclose `passed` +
-  `threshold` while **withholding the exact score** and the identifier openings. The digest mechanic is
+- **C2SP tlog-checkpoint + cosignatures** (v0.9/v1.2) — `proofbundle.checkpoint.sign_checkpoint(origin,
+  tree_size, root, …)` emits a valid [C2SP](https://github.com/C2SP/C2SP/blob/main/tlog-checkpoint.md)
+  signed note over the RFC 6962 Merkle root; `cosign_checkpoint` / `verify_witnessed_checkpoint` add and
+  check Ed25519 cosignature/v1 witness cosignatures with a quorum threshold, making a receipt
+  witness-network / transparency-log compatible. Pure serialization over the Ed25519 keys already in use
+  — no new crypto.
+- **SD-JWT issuance + Key Binding** (RFC 9901) — `proofbundle.sdjwt_issue.issue_sd_jwt(claim, signer,
+  root_b64=…, exact_score=…, holder_public_key=…)` issues the receipt so a holder can disclose `passed` +
+  `threshold` while **withholding the exact score** and the identifier openings, optionally binding a
+  holder key via `cnf.jwk`; `present_with_key_binding` builds the holder presentation and
+  `proofbundle.kbjwt.verify_key_binding` verifies it (v1.2). The digest mechanic is
   RFC 9901 §4.2.3 (base64url of SHA-256 over the base64url-encoded Disclosure), cross-checked against the
   `sd-jwt-python` reference.
 The signed bundle payload is always the source of truth; the SD-JWT and the in-toto export are derived,
@@ -437,10 +473,15 @@ attestation — see [SECURITY.md](SECURITY.md).
   the RFC 6962 root, an Every Eval Ever converter, and standards-native repositioning.
 - **v1.0** — distribution: opt-in framework integrations that auto-emit a signed receipt of an inspect_ai
   eval (end-of-task hook) or a pytest run (pytest11 plugin), plus a composite GitHub Action.
-- **v1.1 (current release)** — trust hardening: a signed `assurance_level`, a THREAT_MODEL, a self_attested-
+- **v1.1** — trust hardening: a signed `assurance_level`, a THREAT_MODEL, a self_attested-
   without-prereg warning, model-swap + replay + withheld-field checks, and an adversarial No-Fake-PASS suite.
-- **Deferred** (explicitly not yet built) — SD-JWT VC conformance + `vct` metadata,
-  Key-Binding JWT, status lists / revocation, an official in-toto PR, DSSE / a full in-toto client.
+- **v1.2 (current release)** — holder binding + witness quorum: **Key Binding JWT** verification
+  (RFC 9901 §4.3, fail-closed; closes #1) with `cnf.jwk` issuance and holder presentation, **C2SP
+  tlog-cosignature** verification (Ed25519 cosignature/v1, witness quorum, split-view resistance), and
+  `verify --verbose` with the recomputed Merkle root (closes #2).
+- **Deferred** (explicitly not yet built) — SD-JWT VC conformance + `vct` metadata (not an RFC yet),
+  Token Status List verification (draft in the RFC-Editor queue; planned as a bundled snapshot to stay
+  offline), ML-DSA-44 cosignatures, an official in-toto PR, a full in-toto client.
 
 ## Contributing
 

{proofbundle-1.1.0 → proofbundle-1.2.0}/README.md

@@ -28,7 +28,7 @@ no server, no network.**
 
 **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. 102 tests.
+checks → `OK` or `FAILED`. No network, no daemon, no own crypto. 148 tests.
 
 ## Contents
 
@@ -103,6 +103,12 @@ A bundle is a single JSON document. `proofbundle` checks, offline:
    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
+4. **sd-jwt-key-binding** (optional, v1.2) — if the SD-JWT carries a Key Binding
+   JWT (RFC 9901 §4.3), it is verified **fail-closed**: `typ` is `kb+jwt`,
+   `iat`/`aud`/`nonce`/`sd_hash` are present, `sd_hash` binds the exact presented
+   disclosure set, and the signature verifies under the issuer-bound `cnf.jwk`
+   holder key. A present-but-broken KB-JWT fails the bundle — it is never
+   silently ignored.
 
 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
@@ -115,16 +121,18 @@ flowchart LR
     P["payload bytes"]
     P -->|"Ed25519 sign"| S["signature"]
     P -->|"RFC 6962 anchor"| M["Merkle inclusion proof"]
-    SD["SD-JWT VC (optional)"] -.-> B
+    SD["SD-JWT VC + KB-JWT (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)"]
+    V --> C4["key binding (optional)"]
     C1 --> R{"all checks pass?"}
     C2 --> R
     C3 --> R
+    C4 --> R
     R -->|yes| OK(["=> OK   exit 0"])
     R -->|no| FAIL(["=> FAILED   exit 1"])
 
@@ -170,6 +178,14 @@ Machine-readable output and a non-zero exit code on failure:
 proofbundle verify --json bundle.json   # exit 0 = ok, 1 = failed, 2 = malformed
 ```
 
+Debugging an inclusion proof (v1.2): `--verbose` prints the recomputed Merkle
+root next to the stated root, so a `FAIL` shows *which* root your payload
+actually anchors to:
+
+```bash
+proofbundle verify --verbose bundle.json
+```
+
 Emit a bundle of your own (v0.2): sign a payload with a fresh key and anchor it,
 then verify it anywhere, offline.
 
@@ -244,6 +260,13 @@ vectors vendored from
 [transparency-dev/merkle](https://github.com/transparency-dev/merkle) (see
 `tests/fixtures/`), plus Hypothesis property tests.
 
+Since v1.2 proofbundle also speaks the witness layer:
+[C2SP tlog-cosignature](https://github.com/C2SP/C2SP/blob/main/tlog-cosignature.md)
+(Ed25519 cosignature/v1) — `verify_witnessed_checkpoint` checks a checkpoint is
+both log-signed **and** cosigned by a quorum of distinct witnesses, offline,
+which rules out a split view by the log operator. This is the same
+witnessed-checkpoint pattern Rekor v2 (GA October 2025) institutionalizes.
+
 ## Bundle format (`proofbundle/v0.1`)
 
 The format is specified normatively in [SPEC.md](SPEC.md) (fields, encodings,
@@ -267,23 +290,32 @@ RFC 6962 hashing, verification order) with a machine-readable JSON Schema at
 ```
 
 `sd_jwt_vc` is optional. Base64 fields are standard base64; the SD-JWT compact
-string uses base64url as per the spec.
+string uses base64url as per the spec. The compact string MAY end in a Key
+Binding JWT (instead of the trailing `~`), which is then verified (v1.2).
 
 ## Security notes and scope, stated honestly
 
 The scope is deliberately narrow. It does exactly what it says and no more:
 
-- Ed25519 signatures only, for both the payload and the optional SD-JWT issuer
-  signature.
+- Ed25519 signatures only, for the payload, the optional SD-JWT issuer
+  signature, and the optional KB-JWT holder signature.
 - SD-JWT: the SD-JWT core is now [RFC 9901](https://datatracker.ietf.org/doc/rfc9901/)
   (November 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/));
+  issuer-signed payload, the issuer signature (EdDSA) if a key is supplied, and — since
+  v1.2, fail-closed — a Key Binding JWT if one is attached (RFC 9901 §4.3: `kb+jwt`
+  typ, required `iat`/`aud`/`nonce`/`sd_hash`, `sd_hash` over the presented disclosure
+  set, holder signature under the issuer-bound `cnf.jwk`). `aud`/`nonce` *values* and
+  `iat` freshness are relying-party policy (an offline verifier has no trusted clock);
+  pass `expected_aud`/`expected_nonce` to `verify_key_binding` to enforce them. It does
+  **not** verify 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.
+- Witness cosignatures (v1.2) prove consistency *observations* by the listed
+  witnesses; real split-view resistance additionally requires the witnesses to be
+  operationally independent — a deployment property no file format can supply.
 - The verifier does not fetch anything. Trust anchors (the signer key, the
-  expected root) are inputs you supply out of band.
+  expected root, witness keys) are inputs you supply out of band.
 - No custom cryptography. Ed25519 comes from `cryptography`; Merkle hashing is
   RFC 6962.
 
@@ -359,13 +391,17 @@ threshold was met without revealing the model or the data. See [INTEROP.md](INTE
   in-toto verifier understands it. Alongside the self-hosted-predicate `to_intoto_statement` (see
   [PREDICATE.md](PREDICATE.md)). Metric details live in `annotations` (test-result has no native metric
   field); the model/dataset stay salted commitments, never `sha256`.
-- **C2SP tlog-checkpoint** (v0.9) — `proofbundle.checkpoint.sign_checkpoint(origin, tree_size, root, …)`
-  emits a valid [C2SP](https://github.com/C2SP/C2SP/blob/main/tlog-checkpoint.md) signed note over the
-  RFC 6962 Merkle root, making a receipt witness-network / transparency-log compatible. Pure serialization
-  over the Ed25519 key already in use — no new crypto.
-- **SD-JWT issuance** (RFC 9901, verified Nov 2025) — `proofbundle.sdjwt_issue.issue_sd_jwt(claim, signer,
-  root_b64=…, exact_score=…)` issues the receipt so a holder can disclose `passed` +
-  `threshold` while **withholding the exact score** and the identifier openings. The digest mechanic is
+- **C2SP tlog-checkpoint + cosignatures** (v0.9/v1.2) — `proofbundle.checkpoint.sign_checkpoint(origin,
+  tree_size, root, …)` emits a valid [C2SP](https://github.com/C2SP/C2SP/blob/main/tlog-checkpoint.md)
+  signed note over the RFC 6962 Merkle root; `cosign_checkpoint` / `verify_witnessed_checkpoint` add and
+  check Ed25519 cosignature/v1 witness cosignatures with a quorum threshold, making a receipt
+  witness-network / transparency-log compatible. Pure serialization over the Ed25519 keys already in use
+  — no new crypto.
+- **SD-JWT issuance + Key Binding** (RFC 9901) — `proofbundle.sdjwt_issue.issue_sd_jwt(claim, signer,
+  root_b64=…, exact_score=…, holder_public_key=…)` issues the receipt so a holder can disclose `passed` +
+  `threshold` while **withholding the exact score** and the identifier openings, optionally binding a
+  holder key via `cnf.jwk`; `present_with_key_binding` builds the holder presentation and
+  `proofbundle.kbjwt.verify_key_binding` verifies it (v1.2). The digest mechanic is
   RFC 9901 §4.2.3 (base64url of SHA-256 over the base64url-encoded Disclosure), cross-checked against the
   `sd-jwt-python` reference.
 The signed bundle payload is always the source of truth; the SD-JWT and the in-toto export are derived,
@@ -392,10 +428,15 @@ attestation — see [SECURITY.md](SECURITY.md).
   the RFC 6962 root, an Every Eval Ever converter, and standards-native repositioning.
 - **v1.0** — distribution: opt-in framework integrations that auto-emit a signed receipt of an inspect_ai
   eval (end-of-task hook) or a pytest run (pytest11 plugin), plus a composite GitHub Action.
-- **v1.1 (current release)** — trust hardening: a signed `assurance_level`, a THREAT_MODEL, a self_attested-
+- **v1.1** — trust hardening: a signed `assurance_level`, a THREAT_MODEL, a self_attested-
   without-prereg warning, model-swap + replay + withheld-field checks, and an adversarial No-Fake-PASS suite.
-- **Deferred** (explicitly not yet built) — SD-JWT VC conformance + `vct` metadata,
-  Key-Binding JWT, status lists / revocation, an official in-toto PR, DSSE / a full in-toto client.
+- **v1.2 (current release)** — holder binding + witness quorum: **Key Binding JWT** verification
+  (RFC 9901 §4.3, fail-closed; closes #1) with `cnf.jwk` issuance and holder presentation, **C2SP
+  tlog-cosignature** verification (Ed25519 cosignature/v1, witness quorum, split-view resistance), and
+  `verify --verbose` with the recomputed Merkle root (closes #2).
+- **Deferred** (explicitly not yet built) — SD-JWT VC conformance + `vct` metadata (not an RFC yet),
+  Token Status List verification (draft in the RFC-Editor queue; planned as a bundled snapshot to stay
+  offline), ML-DSA-44 cosignatures, an official in-toto PR, a full in-toto client.
 
 ## Contributing
 

{proofbundle-1.1.0 → proofbundle-1.2.0}/pyproject.toml

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

{proofbundle-1.1.0 → proofbundle-1.2.0}/src/proofbundle/__init__.py

@@ -13,17 +13,19 @@ from __future__ import annotations
 
 from typing import TYPE_CHECKING
 
-__version__ = "1.1.0"
+__version__ = "1.2.0"
 
 __all__ = [
     "__version__",
     "SCHEMA",
     "verify_bundle",
     "load_bundle",
+    "recompute_merkle_root_b64",
     "emit_bundle",
     "generate_signer",
     "verify_inclusion",
     "verify_consistency",
+    "verify_key_binding",
     "VerificationResult",
     "Check",
     "ProofBundleError",
@@ -32,15 +34,18 @@ __all__ = [
 # name → backing submodule (relative). Loaded on first attribute access.
 _LAZY = {
     "SCHEMA": ".bundle", "load_bundle": ".bundle", "verify_bundle": ".bundle",
+    "recompute_merkle_root_b64": ".bundle",
     "emit_bundle": ".emit", "generate_signer": ".emit",
     "Check": ".errors", "ProofBundleError": ".errors", "VerificationResult": ".errors",
     "verify_consistency": ".merkle", "verify_inclusion": ".merkle",
+    "verify_key_binding": ".kbjwt",
 }
 
 if TYPE_CHECKING:  # static analysers + IDEs see the real names/types; runtime stays lazy
-    from .bundle import SCHEMA, load_bundle, verify_bundle
+    from .bundle import SCHEMA, load_bundle, recompute_merkle_root_b64, verify_bundle
     from .emit import emit_bundle, generate_signer
     from .errors import Check, ProofBundleError, VerificationResult
+    from .kbjwt import verify_key_binding
     from .merkle import verify_consistency, verify_inclusion
 
 

{proofbundle-1.1.0 → proofbundle-1.2.0}/src/proofbundle/bundle.py

@@ -27,10 +27,24 @@ from typing import Union
 
 from . import merkle
 from .errors import BundleFormatError, UnsupportedError, VerificationResult
+from .kbjwt import holder_key_from_cnf, split_key_binding, verify_key_binding
 from .signature import verify_ed25519
 from .sdjwt import verify_sd_jwt
 
-__all__ = ["SCHEMA", "verify_bundle", "load_bundle"]
+__all__ = ["SCHEMA", "verify_bundle", "load_bundle", "recompute_merkle_root_b64"]
+
+
+def _issuer_requires_holder_binding(sd_part: str) -> bool:
+    """True iff the issuer-signed SD-JWT payload carries a usable ``cnf`` holder key (RFC 7800) — i.e. the
+    issuer REQUIRES proof-of-possession. A presentation without a valid Key Binding JWT is then a bearer
+    downgrade and MUST fail. Malformed/absent → False (no cnf ⇒ no binding required, backward-compatible)."""
+    try:
+        issuer_jwt = sd_part.split("~", 1)[0]
+        payload_b64 = issuer_jwt.split(".")[1].encode("ascii")
+        payload = json.loads(base64.urlsafe_b64decode(payload_b64 + b"=" * (-len(payload_b64) % 4)))
+        return isinstance(payload, dict) and holder_key_from_cnf(payload) is not None
+    except Exception:
+        return False
 
 SCHEMA = "proofbundle/v0.1"
 
@@ -145,5 +159,55 @@ def verify_bundle(bundle: Union[dict, str]) -> VerificationResult:
                 sd_res["sig_ok"],
                 "issuer signature valid" if sd_res["sig_ok"] else "issuer signature invalid",
             )
+        # v1.2, fail-closed: a KB-JWT that is PRESENT must verify (RFC 9901 §4.3). Before
+        # v1.2 a trailing KB-JWT was silently ignored — a downgrade risk. Bundles without
+        # a KB-JWT are untouched ONLY when the issuer did NOT bind a holder key: a v0.9/v1.0/
+        # v1.1 bundle with no ``cnf`` verifies exactly as before.
+        # CRITICAL fix (release review 2026-07-02): if the issuer-signed payload DOES carry a
+        # ``cnf`` holder key (proof-of-possession REQUIRED by the issuer), a presentation with
+        # NO Key Binding JWT is a bearer downgrade — anyone who sees the disclosed SD-JWT could
+        # replay it. That MUST fail, not silently pass.
+        if isinstance(compact, str):
+            sd_part, kb = split_key_binding(compact)
+            if kb is not None:
+                kb_res = verify_key_binding(compact)
+                result.add("sd-jwt-key-binding", kb_res["ok"], kb_res["detail"])
+            elif _issuer_requires_holder_binding(sd_part):
+                result.add(
+                    "sd-jwt-key-binding", False,
+                    "issuer bound a holder key (cnf) but the presentation carries NO Key Binding JWT — "
+                    "required proof-of-possession is missing (bearer downgrade, RFC 9901 §4.3)")
 
     return result
+
+
+def recompute_merkle_root_b64(bundle: Union[dict, str]) -> dict:
+    """Recompute the Merkle root from the bundle's own payload + inclusion proof (v1.2, issue #2).
+
+    Debugging aid for ``proofbundle verify --verbose``: returns
+    ``{"stated_b64": ..., "recomputed_b64": ...}`` where ``recomputed_b64`` is None when the
+    proof cannot be evaluated (e.g. index out of range, proof too short/long). Performs the
+    same strict format validation as :func:`verify_bundle` — malformed input raises
+    ``BundleFormatError``, never a raw traceback.
+    """
+    if isinstance(bundle, str):
+        bundle = load_bundle(bundle)
+    if not isinstance(bundle, dict):
+        raise BundleFormatError("bundle must be a JSON object")
+    payload = _b64d(_require(bundle, "payload_b64", "payload_b64"), "payload_b64")
+    mk = _require_dict(_require(bundle, "merkle", "merkle"), "merkle")
+    leaf_index = _require_int(mk, "leaf_index", "merkle.leaf_index")
+    tree_size = _require_int(mk, "tree_size", "merkle.tree_size")
+    proof_list = _require(mk, "inclusion_proof_b64", "merkle.inclusion_proof_b64")
+    if not isinstance(proof_list, list):
+        raise BundleFormatError("field merkle.inclusion_proof_b64 must be a list")
+    proof = [_b64d(p, "merkle.inclusion_proof_b64[]") for p in proof_list]
+    stated_b64 = _require(mk, "root_b64", "merkle.root_b64")
+    _b64d(stated_b64, "merkle.root_b64")   # validate encoding
+    try:
+        recomputed = merkle.root_from_inclusion(
+            leaf_index, tree_size, merkle.leaf_hash(payload), proof)
+        recomputed_b64 = base64.b64encode(recomputed).decode("ascii")
+    except ValueError as exc:
+        return {"stated_b64": stated_b64, "recomputed_b64": None, "detail": str(exc)}
+    return {"stated_b64": stated_b64, "recomputed_b64": recomputed_b64, "detail": ""}