bindable 0.1.2__tar.gz → 0.1.3__tar.gz

{bindable-0.1.2 → bindable-0.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: bindable
-Version: 0.1.2
+Version: 0.1.3
 Summary: Python client for the hosted Bindable Action Gate, with offline Receipt verification
 Author: Bindable AI LLC
 License-Expression: Apache-2.0

{bindable-0.1.2 → bindable-0.1.3}/bindable/__init__.py

@@ -1,22 +1,28 @@
 """Bindable — Python client for the hosted Bindable Action Gate.
 
 Submit a Proposal to the Bindable Action Gate via ``ActionGate.decide()``,
-receive a Decision (the Outcome), and verify the returned Receipt offline with
-``verify_receipt``. The client is pure transport; all proof-rule evaluation
-happens on the hosted gate, and receipt verification is fully offline.
+receive an Outcome, and verify the returned Receipt offline with
+``verify_receipt``. Derive the Decision — released or blocked — from the
+signed Receipt with ``decision_from``. The client is pure transport; all
+proof-rule evaluation happens on the hosted gate, and receipt verification
+is fully offline.
 """
 
 from ._version import __version__
 from .client import ActionGate
 from .crypto import load_public_key
+from .decision import BLOCKED, RELEASED, decision_from
 from .errors import BindableAPIError
 from .verify import ReceiptVerification, verify_receipt
 
 __all__ = [
+    "BLOCKED",
+    "RELEASED",
     "ActionGate",
     "BindableAPIError",
     "ReceiptVerification",
     "__version__",
+    "decision_from",
     "load_public_key",
     "verify_receipt",
 ]

bindable-0.1.3/bindable/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.3"

bindable-0.1.3/bindable/decision.py

@@ -0,0 +1,75 @@
+"""The published derivation of a Decision from a signed Receipt.
+
+The Action Review does not return released/blocked. Callers derive it from
+the Receipt, by this rule and only this rule:
+
+    released  iff  verdict == "passed"
+    blocked   for every other verdict, and for any Receipt that cannot be
+              obtained or read.
+
+This is the CANONICAL, PUBLIC derivation. It is deliberately small enough
+to reimplement in any language — TypeScript, Go, Rust, Java — in a few
+lines, and any such reimplementation MUST behave identically:
+
+    // TypeScript, equivalent by construction
+    const decisionFrom = (r: any): "released" | "blocked" =>
+      r?.verdict === "passed" ? "released" : "blocked";
+
+Two properties are load-bearing and must be preserved in every port:
+
+1. The comparison is EXACT. ``"passed"`` releases; ``"Passed"``,
+   ``"PASSED"``, ``" passed"``, and ``True`` do not. Leniency here would
+   let two implementations disagree about the same Receipt.
+2. Blocked is the SAFE DEFAULT. A missing verdict, an unreadable Receipt,
+   a null, a non-mapping, or anything unexpected yields "blocked". This
+   function never raises and never returns "released" on ambiguity.
+
+Reading the verdict is all this does. It performs no I/O, no
+canonicalization, and no cryptography, and it does not establish that the
+Receipt is authentic — pair it with ``verify_receipt`` when the Receipt's
+integrity matters.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+#: The Decision vocabulary. These exact strings are the wire words.
+RELEASED = "released"
+BLOCKED = "blocked"
+
+#: The one verdict value that releases an action.
+PASSED = "passed"
+
+
+def decision_from(receipt: Mapping[str, Any] | None) -> str:
+    """Derive the Decision from a Receipt: ``"released"`` or ``"blocked"``.
+
+    Returns ``"released"`` if and only if the Receipt's ``verdict`` field
+    is exactly ``"passed"``. Everything else — any other verdict, a
+    missing field, an unreadable or absent Receipt — is ``"blocked"``.
+
+    Args:
+        receipt: A Receipt as a plain mapping, the same shape
+            ``verify_receipt`` takes (for example ``outcome["receipt"]``
+            parsed from JSON). ``None`` and malformed values are accepted
+            and yield ``"blocked"``.
+
+    Returns:
+        ``"released"`` or ``"blocked"``. Never raises.
+
+    Example:
+        >>> from bindable import decision_from, verify_receipt
+        >>> receipt = outcome["receipt"]
+        >>> if verify_receipt(receipt, public_key=pem).valid:
+        ...     if decision_from(receipt) == "released":
+        ...         run_the_action()
+        'released'
+    """
+    try:
+        if not isinstance(receipt, Mapping):
+            return BLOCKED
+        return RELEASED if receipt.get("verdict") == PASSED else BLOCKED
+    except Exception:  # noqa: BLE001 - fail-closed: never raise, never release
+        return BLOCKED

{bindable-0.1.2 → bindable-0.1.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "bindable"
-version = "0.1.2"
+version = "0.1.3"
 requires-python = ">=3.10"
 description = "Python client for the hosted Bindable Action Gate, with offline Receipt verification"
 readme = "README.md"

bindable-0.1.3/tests/test_decision_from.py

@@ -0,0 +1,104 @@
+"""decision_from — the published released/blocked derivation.
+
+This rule is reimplemented by counterparties in other languages, so these
+tests pin it precisely: exactly one verdict releases, everything else
+blocks, and nothing raises.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+import pytest
+
+from bindable import BLOCKED, RELEASED, decision_from
+
+_FIX = Path(__file__).parent / "fixtures"
+
+
+# ─── The rule ──────────────────────────────────────────────────────────
+
+
+def test_passed_verdict_releases() -> None:
+    assert decision_from({"verdict": "passed"}) == "released"
+
+
+@pytest.mark.parametrize("verdict", ["failed", "error", "exception"])
+def test_every_other_verdict_blocks(verdict: str) -> None:
+    assert decision_from({"verdict": verdict}) == "blocked"
+
+
+def test_missing_verdict_key_blocks() -> None:
+    """Fail-closed: an absent verdict is never a release."""
+    assert decision_from({}) == "blocked"
+    assert decision_from({"receipt_id": "r1", "chain_hash": "ab" * 32}) == "blocked"
+
+
+@pytest.mark.parametrize("receipt", [
+    None,
+    "not a receipt",
+    ["not", "a", "receipt"],
+    42,
+    object(),
+])
+def test_unreadable_receipt_blocks_without_raising(receipt: Any) -> None:
+    """'Any Receipt that cannot be obtained or read' -> blocked."""
+    assert decision_from(receipt) == "blocked"
+
+
+@pytest.mark.parametrize("verdict", ["Passed", "PASSED", " passed", "passed ", True, 1, None])
+def test_comparison_is_exact(verdict: Any) -> None:
+    """Near-misses must NOT release — leniency would let ports disagree."""
+    assert decision_from({"verdict": verdict}) == "blocked"
+
+
+def test_only_ever_returns_the_two_wire_words() -> None:
+    for receipt in ({"verdict": "passed"}, {"verdict": "failed"}, {}, None):
+        assert decision_from(receipt) in {RELEASED, BLOCKED}
+    assert (RELEASED, BLOCKED) == ("released", "blocked")
+
+
+def test_a_verdict_whose_equality_explodes_still_blocks() -> None:
+    """The function never raises, whatever it is handed."""
+
+    class Hostile:
+        def __eq__(self, other: object) -> bool:
+            raise RuntimeError("boom")
+
+    assert decision_from({"verdict": Hostile()}) == "blocked"
+
+
+# ─── Against real minted Receipts ──────────────────────────────────────
+
+
+@pytest.mark.parametrize("filename,expected", [
+    ("receipt_public_released_rc4.json", "released"),
+    ("receipt_public_blocked_rc4.json", "blocked"),
+])
+def test_real_minted_receipts_derive_the_right_decision(
+    filename: str, expected: str
+) -> None:
+    receipt = json.loads((_FIX / filename).read_text(encoding="utf-8"))
+    assert decision_from(receipt) == expected
+
+
+def test_the_derivation_tracks_the_verdict_field_specifically() -> None:
+    """A released Receipt whose verdict is altered derives blocked.
+
+    (Altering it also breaks the chain hash — that is verify_receipt's job,
+    not this function's. decision_from reads the verdict, nothing more.)
+    """
+    receipt = json.loads(
+        (_FIX / "receipt_public_released_rc4.json").read_text(encoding="utf-8")
+    )
+    assert decision_from(receipt) == "released"
+    receipt["verdict"] = "failed"
+    assert decision_from(receipt) == "blocked"
+
+
+def test_derivation_does_not_depend_on_status_or_failed_rule() -> None:
+    """Only the verdict decides — no other field participates."""
+    assert decision_from({"verdict": "passed", "failed_rule": "r-2"}) == "released"
+    assert decision_from({"verdict": "failed", "status": "released"}) == "blocked"

{bindable-0.1.2 → bindable-0.1.3}/tests/test_version.py

@@ -2,4 +2,4 @@ import bindable
 
 
 def test_version() -> None:
-    assert bindable.__version__ == "0.1.2"
+    assert bindable.__version__ == "0.1.3"

bindable-0.1.2/bindable/_version.py

@@ -1 +0,0 @@
-__version__ = "0.1.2"