proofbundle 3.2.1__tar.gz → 3.2.2__tar.gz

{proofbundle-3.2.1/src/proofbundle.egg-info → proofbundle-3.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: proofbundle
-Version: 3.2.1
+Version: 3.2.2
 Summary: Emit and verify portable cryptographic evidence bundles, offline: Ed25519 + RFC 6962 Merkle + optional SD-JWT.
 Author: Konrad Gruszka
 License: MIT

{proofbundle-3.2.1 → proofbundle-3.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "proofbundle"
-version = "3.2.1"
+version = "3.2.2"
 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.2.1 → proofbundle-3.2.2}/src/proofbundle/__init__.py

@@ -13,7 +13,7 @@ from __future__ import annotations
 
 from typing import TYPE_CHECKING
 
-__version__ = "3.2.1"
+__version__ = "3.2.2"
 
 # 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

{proofbundle-3.2.1 → proofbundle-3.2.2}/src/proofbundle/cli.py

@@ -1198,7 +1198,8 @@ def _cmd_decision_verify(args: argparse.Namespace) -> int:
                 rp_trust = merged
         result = verify_decision_receipt(env, pub, strict=args.strict, expected_audience=args.aud,
                                          expected_nonce=args.nonce, policy=policy, anchors=anchors,
-                                         rp_trust=rp_trust)
+                                         rp_trust=rp_trust,
+                                         require_derived_subject=args.require_derived_subject)
     except (ProofBundleError, OSError, ValueError) as exc:
         print(f"ERROR: {exc}", file=sys.stderr)
         return 2
@@ -1210,7 +1211,7 @@ def _cmd_decision_verify(args: argparse.Namespace) -> int:
         report = {k: result[k] for k in (
             "ok", "crypto_ok", "structure_ok", "predicate_type_ok", "signer_trusted", "policy_ok",
             "evidence_bound", "audience_ok", "nonce_ok", "freshness_ok", "anchors_ok",
-            "action_outcome_proven", "warnings", "errors",
+            "action_outcome_proven", "subject_binding", "subject_derived_ok", "warnings", "errors",
         )}
         print(json.dumps(report, indent=2))
     else:
@@ -1228,6 +1229,10 @@ def _cmd_decision_verify(args: argparse.Namespace) -> int:
             print(f"ANCHORS: {'OK' if result['anchors_ok'] else 'FAIL'}")
         if result["action_outcome_proven"] is False:
             print("ASSURANCE: actionOutcome=executed is self-asserted (no signed outcomeRef)")
+        if result["subject_binding"] is not None:
+            print(f"SUBJECT: {result['subject_binding']['mode']}")
+        if result["subject_derived_ok"] is not None:
+            print(f"SUBJECT_DERIVED: {'OK' if result['subject_derived_ok'] else 'FAIL'}")
         for e in result["errors"]:
             print(f"  - {e}", file=sys.stderr)
         for w in result["warnings"]:
@@ -1248,6 +1253,10 @@ def _cmd_decision_verify(args: argparse.Namespace) -> int:
     # like the eval verify path, never a silent exit 0 (lens 3 defect).
     if result["audience_ok"] is False or result["nonce_ok"] is False:
         return 2
+    # Finding 05: a caller who explicitly requests --require-derived-subject is asking for the same kind of
+    # fail-closed binding as --aud/--nonce — an EXTERNAL_ATTESTED subject then must not exit 0.
+    if result["subject_derived_ok"] is False:
+        return 2
     # A supplied anchor that FAILS to verify (broken / root-mismatched / unknown type) is a tamper
     # signal — fail-closed, never a silent exit 0 (fix-review Finding 3). None = no anchor supplied.
     if result["anchors_ok"] is False:
@@ -1362,14 +1371,16 @@ def _cmd_outcome_verify(args: argparse.Namespace) -> int:
         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)
+            expected_audience=args.aud, expected_nonce=args.nonce,
+            require_derived_subject=args.require_derived_subject)
     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",
+            "execution_proven", "audience_ok", "nonce_ok", "subject_binding", "subject_derived_ok",
+            "warnings", "errors",
         )}
         print(json.dumps(report, indent=2))
     else:
@@ -1385,6 +1396,10 @@ def _cmd_outcome_verify(args: argparse.Namespace) -> int:
             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)")
+        if result["subject_binding"] is not None:
+            print(f"SUBJECT: {result['subject_binding']['mode']}")
+        if result["subject_derived_ok"] is not None:
+            print(f"SUBJECT_DERIVED: {'OK' if result['subject_derived_ok'] else 'FAIL'}")
         for e in result["errors"]:
             print(f"  - {e}", file=sys.stderr)
         for w in result["warnings"]:
@@ -1403,6 +1418,10 @@ def _cmd_outcome_verify(args: argparse.Namespace) -> int:
         return 2
     if result["audience_ok"] is False or result["nonce_ok"] is False:
         return 2
+    # Finding 05: a caller who explicitly requests --require-derived-subject is asking for the same kind of
+    # fail-closed binding as --aud/--nonce — an EXTERNAL_ATTESTED subject then must not exit 0.
+    if result["subject_derived_ok"] is False:
+        return 2
     return 0
 
 
@@ -1888,6 +1907,11 @@ def build_parser() -> argparse.ArgumentParser:
     d_verify.add_argument("--bitcoin-header", action="append", default=None, metavar="HEIGHT:MERKLEROOT_HEX",
                           help="WP-A1: a relying-party-supplied Bitcoin block header (internal byte order) "
                                "that confirms an OpenTimestamps statement anchor — frozen is never trusted")
+    d_verify.add_argument("--require-derived-subject", dest="require_derived_subject", action="store_true",
+                          help="Finding 05: fail closed (exit 2) unless the Statement subject is a DERIVED "
+                               "commitment to the predicate (subject_binding.classify_subject) — rejects a "
+                               "self-attested/rehung subject_sha256 override. Default off: an "
+                               "EXTERNAL_ATTESTED subject is still warned, never silent")
     d_verify.set_defaults(func=_cmd_decision_verify)
 
     d_inspect = dsub.add_parser("inspect", help="print a decision receipt's predicate (no crypto verification)")
@@ -1927,6 +1951,11 @@ def build_parser() -> argparse.ArgumentParser:
     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.add_argument("--require-derived-subject", dest="require_derived_subject", action="store_true",
+                          help="Finding 05: fail closed (exit 2) unless the Statement subject is a DERIVED "
+                               "commitment to the predicate (subject_binding.classify_subject) — rejects a "
+                               "self-attested/rehung subject_sha256 override. Default off: an "
+                               "EXTERNAL_ATTESTED subject is still warned, never silent")
     o_verify.set_defaults(func=_cmd_outcome_verify)
 
     o_inspect = osub.add_parser("inspect", help="print an outcome receipt's predicate (no crypto verification)")

{proofbundle-3.2.1 → proofbundle-3.2.2}/src/proofbundle/decision.py

@@ -16,6 +16,7 @@ from typing import Any
 
 from ._strict_json import loads_strict
 from .errors import BundleFormatError, ProofBundleError
+from .subject_binding import nested_closure_violations
 
 DECISION_RECEIPT_PREDICATE_TYPE = "https://b7n0de.com/proofbundle/predicates/decision-receipt/v0.1"
 DECISION_SCHEMA_VERSION = "0.1.0"
@@ -53,6 +54,35 @@ _ALLOWED_TOP = set(_REQUIRED_ALWAYS) | set(_OPTIONAL)
 # Time-bearing paths that, if present, MUST be RFC3339-Z.
 _TIME_PATHS = ("decidedAt", "recordedAt")
 
+# Nested schema closure (Finding 04 / subject_binding.nested_closure_violations): a top-level
+# additionalProperties:false does NOT, by itself, close these nested objects — an undeclared key inside one
+# of them (e.g. `decision: {..., "sneaky": 1}`) previously rode along silently. Every path here was verified
+# against the golden examples (examples/decision_receipt_{allow,deny,escalate}.json,
+# decision_receipt_with_eval_ref.intoto.json) AND the `decision init` CLI template so this closure can never
+# reject the repo's own reference material. `decisionMaker.version` is DELIBERATELY left undeclared — it is
+# the versioned extensions container the module's own docstring describes as "the ONLY way to add fields".
+_NESTED_ALLOWED: dict[str, tuple[str, ...]] = {
+    "decisionMaker": ("id", "version"),
+    "agent": ("id", "version", "configurationDigest"),
+    "principal": ("id", "authnContextRef"),
+    "principal.authnContextRef": ("uri", "digest"),
+    "proposedAction": ("actionType", "target", "method", "parametersDigest", "parametersRef",
+                       "parametersSchemaRef"),
+    "proposedAction.target": ("name", "uri", "digest"),
+    "proposedAction.parametersSchemaRef": ("uri", "digest"),
+    "policyBoundary": ("policyEngine", "policyId", "policyDigest", "decisionPath", "bundleRevision",
+                       "validFrom", "validUntil"),
+    "evidenceRefs[]": ("relation", "digest", "artifactDigest", "uri", "predicateType"),
+    "decision": ("verdict", "reasonCodes", "humanReadableSummary", "obligations", "allowedScope"),
+    "notChecked[]": ("field", "reason", "impact"),
+    "decisionChangeConditions[]": ("conditionType", "description", "requiredEvidenceType"),
+    "actionOutcome": ("status", "performedAt", "outcomeRef"),
+    "actionOutcome.outcomeRef": ("uri", "digest"),
+    "privacy": ("rawInputsIncluded", "redactionProfile", "erased", "masked"),
+    "validity": ("audience", "nonce", "expiresAt"),
+    "inputSnapshot[]": ("name", "uri", "digest", "mediaType"),
+}
+
 
 class DecisionReceiptError(ProofBundleError):
     """A Decision Receipt predicate is malformed (fail-closed)."""
@@ -101,6 +131,13 @@ def validate_decision_predicate(predicate: Any, *, strict: bool = False) -> list
     if sv is not None and (not isinstance(sv, str) or not _SEMVER_0_1_X.match(sv)):
         errors.append(f"schemaVersion must be a 0.1.x string, got {sv!r}")
 
+    # decisionId (Finding 04, analogous to trustPackId in trust_pack.py): the required-field loop above only
+    # checks PRESENCE — an int, a bool or an empty string previously satisfied "decisionId in predicate" and
+    # passed silently.
+    did = predicate.get("decisionId")
+    if "decisionId" in predicate and not (isinstance(did, str) and did):
+        errors.append(f"decisionId must be a non-empty string, got {did!r}")
+
     # decisionType enum
     dt = predicate.get("decisionType")
     if dt is not None and (not isinstance(dt, str) or dt not in _DECISION_TYPES):
@@ -135,13 +172,19 @@ def validate_decision_predicate(predicate: Any, *, strict: bool = False) -> list
     elif "policyBoundary" in predicate:
         errors.append("policyBoundary must be a JSON object")
 
-    # proposedAction inner shape (§6.2): actionType required + a digest OR a ref for the parameters.
+    # proposedAction inner shape (§6.2): actionType required + a digest OR a non-empty ref for the
+    # parameters. Finding 04: a bare `{}` parametersRef previously satisfied `isinstance(..., dict)`
+    # vacuously — `{}` is a dict but carries no actual reference.
     pa = predicate.get("proposedAction")
     if isinstance(pa, dict):
         if not isinstance(pa.get("actionType"), str) or not pa.get("actionType"):
             errors.append("proposedAction.actionType must be a non-empty string")
-        if not (_is_digest(pa.get("parametersDigest")) or isinstance(pa.get("parametersRef"), dict)):
-            errors.append("proposedAction needs a sha256 parametersDigest or a parametersRef")
+        pref = pa.get("parametersRef")
+        pref_ok = isinstance(pref, dict) and bool(pref)
+        if "parametersRef" in pa and not pref_ok:
+            errors.append("proposedAction.parametersRef, when present, must be a non-empty object")
+        if not (_is_digest(pa.get("parametersDigest")) or pref_ok):
+            errors.append("proposedAction needs a sha256 parametersDigest or a non-empty parametersRef")
     elif "proposedAction" in predicate:
         errors.append("proposedAction must be a JSON object")
 
@@ -180,20 +223,28 @@ def validate_decision_predicate(predicate: Any, *, strict: bool = False) -> list
     elif "evidenceRefs" in predicate:
         errors.append("evidenceRefs must be a list")
 
-    # actionOutcome (optional) — status enum
+    # actionOutcome (optional) — must be an object; status enum. Finding 04: a scalar (e.g. the bare
+    # string "executed") previously skipped every check silently (the `isinstance(ao, dict)` guard simply
+    # never entered the block, and nothing else objected to the wrong shape).
     ao = predicate.get("actionOutcome")
     if isinstance(ao, dict):
         st = ao.get("status")
         if not isinstance(st, str) or st not in _OUTCOME_STATUS:
             errors.append(f"actionOutcome.status must be one of {sorted(_OUTCOME_STATUS)}, got {st!r}")
+    elif "actionOutcome" in predicate:
+        errors.append("actionOutcome must be a JSON object")
 
-    # validity — strict interactive requires audience + nonce when present
+    # validity — must be an object; strict interactive mode additionally requires audience + nonce when
+    # present. Finding 04: a scalar validity previously passed the same way actionOutcome did.
     val = predicate.get("validity")
-    if isinstance(val, dict) and strict:
-        if not (isinstance(val.get("audience"), list) and val["audience"]):
-            errors.append("validity.audience (non-empty list) is required in strict mode when validity is present")
-        if not isinstance(val.get("nonce"), str) or not val.get("nonce"):
-            errors.append("validity.nonce is required in strict mode when validity is present")
+    if isinstance(val, dict):
+        if strict:
+            if not (isinstance(val.get("audience"), list) and val["audience"]):
+                errors.append("validity.audience (non-empty list) is required in strict mode when validity is present")
+            if not isinstance(val.get("nonce"), str) or not val.get("nonce"):
+                errors.append("validity.nonce is required in strict mode when validity is present")
+    elif "validity" in predicate:
+        errors.append("validity must be a JSON object")
 
     # privacy inner shape: a bare {} must not pass strict — rawInputsIncluded is the field the policy's
     # allow_raw_inputs gate reads, so it MUST be an explicit boolean (§5.5 privacy).
@@ -203,6 +254,11 @@ def validate_decision_predicate(predicate: Any, *, strict: bool = False) -> list
     elif strict and isinstance(priv, dict) and not isinstance(priv.get("rawInputsIncluded"), bool):
         errors.append("privacy.rawInputsIncluded (boolean) is required in strict mode")
 
+    # Nested schema closure (Finding 04): additionalProperties:false at the TOP level does not, by itself,
+    # close these nested objects — an undeclared key inside decision/policyBoundary/proposedAction/
+    # decisionMaker/evidenceRefs[] (and their sub-objects) previously rode along silently.
+    errors.extend(nested_closure_violations(predicate, _NESTED_ALLOWED))
+
     return errors
 
 
@@ -333,6 +389,7 @@ def _empty_result() -> dict:
         "ok": None, "structure_ok": None, "crypto_ok": None, "signer_trusted": None,
         "predicate_type_ok": None, "policy_ok": None, "evidence_bound": None, "audience_ok": None,
         "nonce_ok": None, "freshness_ok": None, "anchors_ok": None, "action_outcome_proven": None,
+        "subject_binding": None, "subject_derived_ok": None,
         "warnings": [], "errors": [],
     }
 
@@ -340,7 +397,7 @@ def _empty_result() -> dict:
 def verify_decision_receipt(envelope: dict, public_key: bytes, *, strict: bool = False,
                             expected_audience: str | None = None, expected_nonce: str | None = None,
                             policy: dict | None = None, anchors: list | None = None,
-                            rp_trust: dict | None = None) -> dict:
+                            rp_trust: dict | None = None, require_derived_subject: bool = False) -> dict:
     """Verify a DSSE-signed Decision Receipt. Crypto first, then structure over the EXACT signed bytes (never
     re-serialized). Returns the snake_case structured result; each check independent, non-applicable = None.
 
@@ -348,14 +405,21 @@ def verify_decision_receipt(envelope: dict, public_key: bytes, *, strict: bool =
     verdict (crypto AND structure AND predicate-type AND every applicable trust check). The individual
     fields describe the payload only AFTER authentication: when `crypto_ok` is False the bytes are
     unauthenticated, so the trust-derived fields (`audience_ok`, `nonce_ok`, `evidence_bound`,
-    `signer_trusted`, `policy_ok`, `action_outcome_proven`) stay None — and `anchors_ok` is None, or
-    False when anchors were supplied — and an error is recorded, so a consumer that reads e.g.
-    `audience_ok` without checking `crypto_ok`/`ok` cannot read a claim about bytes nobody signed. The
-    CLI gates its exit code on `crypto_ok` first (and reports `ok`).
+    `signer_trusted`, `policy_ok`, `action_outcome_proven`, `subject_derived_ok`) stay None — and
+    `anchors_ok` is None, or False when anchors were supplied — and an error is recorded, so a consumer
+    that reads e.g. `audience_ok` without checking `crypto_ok`/`ok` cannot read a claim about bytes nobody
+    signed. The CLI gates its exit code on `crypto_ok` first (and reports `ok`).
 
     hash_binding (§7.1): the received payload MUST equal its own RFC-8785 canonicalization; a deviation is a
     fail-closed error (only checked when rfc8785 is importable, so plain verify stays dependency-free).
 
+    Subject binding (Finding 05, mirrors outcome.py): `build_decision_statement` allows a caller to
+    OVERRIDE `subject_sha256`, self-attested and NOT cross-checked there. This verify path now classifies
+    the binding via `subject_binding.classify_subject` so a subject-rehang is never a ZERO-signal event: an
+    `EXTERNAL_ATTESTED` subject is ALWAYS warned (`subject_binding`/`warnings`); `require_derived_subject`
+    (opt-in, default False, preserving the documented override use) makes it a hard fail-closed error via
+    `subject_derived_ok`.
+
     Detached anchors (Fix 2 / proofbundle#7): `anchors` is the DETACHED anchor evidence for the decision
     statement's OWN content root (sha256 over the exact signed payload bytes). It is NOT part of the signed
     predicate — an anchor cannot live inside the bytes whose hash it commits. It is verified against the
@@ -455,6 +519,42 @@ def verify_decision_receipt(envelope: dict, public_key: bytes, *, strict: bool =
                     "nonce mismatch or absent validity.nonce — requested replay binding cannot be enforced "
                     "(replay?, fail-closed)")
 
+    # Subject binding (Finding 05, release-review #4 parity with outcome.py): classify whether the subject
+    # genuinely commits to the predicate so a consumer never gets ZERO signal on a subject-rehang override.
+    # An EXTERNAL_ATTESTED subject is ALWAYS warned; require_derived_subject makes it a hard fail-closed
+    # error (opt-in, preserves the documented build_decision_statement override use).
+    if isinstance(statement, dict) and r["crypto_ok"]:
+        if _rfc8785_available():
+            from . import subject_binding as _sb  # noqa: PLC0415
+            try:
+                _cls = _sb.classify_subject(statement)
+            except Exception:  # noqa: BLE001
+                _cls = None
+            if _cls is not None:
+                r["subject_binding"] = {"mode": _cls["mode"], "matches": _cls["matches"]}
+                if not _cls["matches"]:
+                    r["warnings"].append(
+                        "subject is EXTERNAL_ATTESTED — it does not commit to this predicate (subject-rehang); "
+                        "trust it only via a policy that pins the external attester")
+                if require_derived_subject:
+                    r["subject_derived_ok"] = _cls["matches"]
+                    if not _cls["matches"]:
+                        r["errors"].append(
+                            "require_derived_subject: subject is not a DERIVED commitment to the predicate "
+                            "(fail-closed)")
+            elif require_derived_subject:
+                # classify_subject raised (e.g. a predicate the JCS canonicalizer rejects). Do NOT silently
+                # pass the gate on a coincidence elsewhere — make the fail-closed explicit.
+                r["subject_derived_ok"] = False
+                r["errors"].append(
+                    "require_derived_subject: could not classify the subject binding (canonicalization raised) "
+                    "— fail-closed")
+        elif require_derived_subject:
+            r["subject_derived_ok"] = False
+            r["errors"].append(
+                "require_derived_subject but RFC-8785 canonicalizer unavailable — cannot verify subject "
+                "derivation (install proofbundle[eval]), fail-closed")
+
     # Detached anchors (Fix 2): verify anchor evidence for the statement's OWN content root — sha256 over the
     # EXACT signed payload bytes (never re-canonicalized), computed only once the bytes are authentic+canonical.
     _dr_section = policy.get("decision_receipt") if isinstance(policy, dict) else None
@@ -526,5 +626,6 @@ def verify_decision_receipt(envelope: dict, public_key: bytes, *, strict: bool =
         r["crypto_ok"] and r["structure_ok"] and r["predicate_type_ok"]
         and r["policy_ok"] is not False and r["signer_trusted"] is not False
         and r["audience_ok"] is not False and r["nonce_ok"] is not False
-        and r["evidence_bound"] is not False and r["anchors_ok"] is not False)
+        and r["evidence_bound"] is not False and r["anchors_ok"] is not False
+        and r["subject_derived_ok"] is not False)
     return r

{proofbundle-3.2.1 → proofbundle-3.2.2}/src/proofbundle/outcome.py

@@ -23,6 +23,7 @@ from typing import Any
 
 from ._strict_json import loads_strict
 from .errors import BundleFormatError, ProofBundleError
+from .subject_binding import nested_closure_violations
 
 ACTION_OUTCOME_PREDICATE_TYPE = "https://b7n0de.com/proofbundle/predicates/action-outcome/v0.1"
 OUTCOME_SCHEMA_VERSION = "0.1.0"
@@ -47,6 +48,15 @@ _ALLOWED_TOP = set(_REQUIRED_ALWAYS) | set(_OPTIONAL)
 _DIGEST_FIELDS = ("requestedActionDigest", "actualActionDigest", "responseDigest", "effectDigest")
 _TIME_PATHS = ("performedAt", "recordedAt")
 
+# Nested schema closure (Finding 04 / subject_binding.nested_closure_violations): a top-level
+# additionalProperties:false does NOT, by itself, close traceContext/validity — an undeclared key inside
+# one of them previously rode along silently. Verified against `outcome init`'s CLI template
+# (traceContext={"traceparent": ""}) and tests/test_outcome_verify.py's validity={"audience", "nonce"}.
+_NESTED_ALLOWED: dict[str, tuple[str, ...]] = {
+    "traceContext": ("traceparent",),
+    "validity": ("audience", "nonce"),
+}
+
 
 class OutcomeReceiptError(ProofBundleError):
     """An Action Outcome Receipt predicate is malformed (fail-closed)."""
@@ -125,6 +135,18 @@ def validate_outcome_predicate(predicate: Any, *, strict: bool = False) -> list[
     if "traceContext" in predicate and not isinstance(tc, dict):
         errors.append("traceContext must be an object")
 
+    # validity (Finding 04): previously had NO structural check at all — a scalar validity (e.g. the bare
+    # string "n-1") silently reached verify_outcome_receipt, which only guards with
+    # `_val if isinstance(_val, dict) else {}` and so treated it as an absent validity object without ever
+    # flagging the malformed shape.
+    val = predicate.get("validity")
+    if "validity" in predicate and not isinstance(val, dict):
+        errors.append("validity must be an object")
+
+    # Nested schema closure (Finding 04): additionalProperties:false at the TOP level does not, by itself,
+    # close traceContext/validity — an undeclared key inside either previously rode along silently.
+    errors.extend(nested_closure_violations(predicate, _NESTED_ALLOWED))
+
     return errors
 
 

{proofbundle-3.2.1 → proofbundle-3.2.2}/src/proofbundle/public_transparency.py

@@ -23,6 +23,7 @@ general SCITT/RFC-9943 conformance claim without interop vectors, and never that
 """
 from __future__ import annotations
 
+from dataclasses import dataclass
 from typing import Any
 
 from .errors import ProofBundleError
@@ -39,6 +40,79 @@ class PublicTransparencyError(ProofBundleError):
     """A public-transparency policy is malformed (fail-closed)."""
 
 
+@dataclass(frozen=True)
+class ConsistencyVerificationResult:
+    """A relying party's (or independent monitor's) OWN result of checking an RFC 9162 §2.1.4 consistency
+    proof (``merkle.verify_consistency``) between two checkpoints of the SAME log: the *old* (first,
+    smaller) checkpoint the caller previously trusted, and the *new* (second, larger) checkpoint currently
+    being evaluated by ``evaluate_public_transparency``.
+
+    Finding 10: a bare ``consistency_confirmed: bool`` is an UNBOUND plaintext claim — it says nothing
+    about WHICH checkpoint pair was checked, so a ``True`` computed for one (old, new) pair is trivially
+    replayable onto a different, unrelated ``new`` checkpoint. Carrying the checkpoint identities INSIDE
+    the result lets ``evaluate_public_transparency`` bind ``new_origin`` / ``new_tree_size`` /
+    ``new_root_b64`` to the EXACT checkpoint under evaluation before it ever accepts ``confirmed``.
+
+    ``proof_digest`` / ``verifier_version`` / ``policy_digest`` are provenance (which consistency-proof
+    bytes were actually checked, by which verifier build, under which policy) — evidence the check really
+    ran, not merely a hand-typed ``confirmed=True`` (No-Fake omission floor); ``validate()`` requires them
+    non-empty. ``validate()`` also rejects a STRUCTURALLY impossible pair regardless of ``confirmed`` — in
+    particular the same tree size claiming two different roots, which is the signature of a log SPLIT VIEW
+    (a fork), never a valid consistency claim (RFC 9162: equal size implies equal root)."""
+
+    old_origin: str
+    old_tree_size: int
+    old_root_b64: str
+    new_origin: str
+    new_tree_size: int
+    new_root_b64: str
+    proof_digest: str
+    verifier_version: str
+    policy_digest: str
+    confirmed: bool
+
+    def validate(self) -> list[str]:
+        """Fail-closed structural validation (empty list = valid). Never raises on malformed field types —
+        every comparison is guarded so a caller-constructed or deserialized result cannot crash this."""
+        errors: list[str] = []
+
+        def _str(name: str, val: Any) -> bool:
+            ok = isinstance(val, str) and val != ""
+            if not ok:
+                errors.append(f"{name} must be a non-empty string")
+            return ok
+
+        def _size(name: str, val: Any) -> bool:
+            ok = isinstance(val, int) and not isinstance(val, bool) and val >= 0
+            if not ok:
+                errors.append(f"{name} must be a non-negative integer")
+            return ok
+
+        origin_ok = _str("old_origin", self.old_origin) and _str("new_origin", self.new_origin)
+        root_ok = _str("old_root_b64", self.old_root_b64) and _str("new_root_b64", self.new_root_b64)
+        _str("proof_digest", self.proof_digest)
+        _str("verifier_version", self.verifier_version)
+        _str("policy_digest", self.policy_digest)
+        size_ok = _size("old_tree_size", self.old_tree_size) and _size("new_tree_size", self.new_tree_size)
+        if not isinstance(self.confirmed, bool):
+            errors.append("confirmed must be a boolean")
+
+        if size_ok and self.old_tree_size > self.new_tree_size:
+            errors.append(
+                "old_tree_size exceeds new_tree_size — a consistency proof only orders old -> new, "
+                "never the reverse")
+        if size_ok and root_ok and self.old_tree_size == self.new_tree_size \
+                and self.old_root_b64 != self.new_root_b64:
+            errors.append(
+                "old_tree_size == new_tree_size but the roots differ — a split view / fork, never a "
+                "valid consistency claim (RFC 9162: identical tree size implies an identical root)")
+        if origin_ok and self.old_origin != self.new_origin:
+            errors.append(
+                "old_origin and new_origin differ — a consistency proof is only meaningful within one "
+                "log's own history")
+        return errors
+
+
 def validate_public_transparency_policy(policy: Any) -> list[str]:
     """Fail-closed validation of a public-transparency policy object (empty = valid)."""
     errors: list[str] = []
@@ -72,13 +146,25 @@ def evaluate_public_transparency(
     signed_note: str, policy: dict, *, log_vkey: str | None = None,
     witness_vkeys: list | None = None, expected_root_b64: str | None = None,
     expected_tree_size: int | None = None, consistency_confirmed: bool | None = None,
+    consistency_result: "ConsistencyVerificationResult | None" = None,
+    strict_consistency: bool = False,
 ) -> dict:
     """Evaluate a signed checkpoint against a public-transparency policy → unified named-status verdict.
 
     ``consistency_confirmed`` is the relying party's OWN result of a consistency-proof check (append-only, no
     fork) computed elsewhere; when the policy requires consistency it MUST be True, else FAIL. It is passed in
     (not computed here) because a consistency proof is between two checkpoints the relying party holds — this
-    layer records the verdict, fail-closed. Read PUBLIC_TRANSPARENCY — never an individual status alone."""
+    layer records the verdict, fail-closed. Read PUBLIC_TRANSPARENCY — never an individual status alone.
+
+    ``consistency_result`` (finding 10, additive): a typed ``ConsistencyVerificationResult`` instead of the
+    bare ``consistency_confirmed`` boolean. Preferred, because it BINDS the confirmation to this exact
+    checkpoint — ``new_origin`` / ``new_tree_size`` / ``new_root_b64`` are checked against the values this
+    call itself parses from ``signed_note`` BEFORE ``confirmed`` is ever accepted, and its own
+    ``.validate()`` rejects a structurally impossible (e.g. split-view) pair regardless of ``confirmed``.
+    When both are supplied, ``consistency_result`` takes precedence. ``strict_consistency=True`` refuses
+    the unbound bare-boolean path entirely (CONSISTENCY FAILs if only ``consistency_confirmed`` is given) —
+    additive: the default (``strict_consistency=False``) preserves every existing caller's behavior
+    exactly."""
     from . import checkpoint as cp  # noqa: PLC0415
 
     perrs = validate_public_transparency_policy(policy)
@@ -150,8 +236,35 @@ def evaluate_public_transparency(
             errors.append("checkpoint tree size does not equal the relying party's expected tree size")
 
     # CONSISTENCY — required-and-confirmed → PASS; required-and-not-confirmed → FAIL (fail-closed).
+    # finding 10: a typed consistency_result (preferred) is BOUND to this exact checkpoint before its
+    # `confirmed` is accepted; a bare consistency_confirmed boolean is an unbound plaintext claim, and
+    # strict_consistency=True refuses it entirely.
     if bool(policy.get("requireConsistencyProof")):
-        if consistency_confirmed is True:
+        if consistency_result is not None:
+            cerrs = consistency_result.validate()
+            if cerrs:
+                statuses["CONSISTENCY"] = "FAIL"
+                errors.extend(f"consistency result invalid: {e}" for e in cerrs)
+            elif not (parsed_ok and consistency_result.new_origin == origin
+                     and consistency_result.new_tree_size == tree_size
+                     and consistency_result.new_root_b64 == root):
+                statuses["CONSISTENCY"] = "FAIL"
+                errors.append(
+                    "consistency result does not bind to this checkpoint (new_origin/new_tree_size/"
+                    "new_root_b64 do not match the checkpoint being evaluated) — wrong checkpoint pair, "
+                    "fail-closed")
+            elif consistency_result.confirmed is True:
+                statuses["CONSISTENCY"] = "PASS"
+            else:
+                statuses["CONSISTENCY"] = "FAIL"
+                errors.append("consistency result is bound to this checkpoint but confirmed is not True")
+        elif strict_consistency:
+            statuses["CONSISTENCY"] = "FAIL"
+            errors.append(
+                "requireConsistencyProof with strict_consistency=True needs a typed "
+                "ConsistencyVerificationResult — a bare consistency_confirmed boolean is an unbound "
+                "plaintext claim and is rejected (fail-closed)")
+        elif consistency_confirmed is True:
             statuses["CONSISTENCY"] = "PASS"
         else:
             statuses["CONSISTENCY"] = "FAIL"