bindable 0.1.2__tar.gz → 0.1.4__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: bindable
-Version: 0.1.2
+Version: 0.1.4
 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.4/bindable/__init__.py

@@ -0,0 +1,33 @@
+"""Bindable — Python client for the hosted Bindable Action Gate.
+
+Submit a Proposal to the Bindable Action Gate via ``ActionGate.decide()``,
+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.
+
+Review resolves the governing Contract by stage. ``decide()`` takes an optional
+``stage`` — one of ``STAGES`` — and omits the field entirely when it is not
+given, leaving the platform's ``development`` default in force.
+"""
+
+from ._version import __version__
+from .client import STAGES, 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",
+    "STAGES",
+    "ActionGate",
+    "BindableAPIError",
+    "ReceiptVerification",
+    "__version__",
+    "decision_from",
+    "load_public_key",
+    "verify_receipt",
+]

bindable-0.1.4/bindable/_version.py

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

{bindable-0.1.2 → bindable-0.1.4}/bindable/client.py

@@ -14,12 +14,38 @@ from __future__ import annotations
 import secrets
 from collections.abc import Mapping
 from types import TracebackType
-from typing import Any
+from typing import Any, Final
 
 import httpx
 
 from bindable.errors import BindableAPIError
 
+#: The stages a Contract can be resolved at, as the platform names them.
+#:
+#: Review resolves the governing Contract BY STAGE. Omitting the field lets the
+#: platform apply its own default, which is ``development`` — correct for
+#: Sandbox work and wrong for a promoted Contract, which exists only at
+#: ``production``. Callers targeting a promoted Contract must say so.
+#:
+#: Single-sourced here so that callers validating their own configuration —
+#: an environment variable, a config file — check against the same tuple
+#: rather than keeping a second copy that can drift.
+STAGES: Final[tuple[str, ...]] = ("development", "test", "production")
+
+
+def _validated_stage(stage: str) -> str:
+    """Return ``stage`` if the platform accepts it, else raise locally.
+
+    Checked here rather than sent hopefully: a bad stage is a caller's
+    configuration mistake, and a named ValueError at the call site is a better
+    answer than a 422 that has already cost a round trip.
+    """
+    if stage not in STAGES:
+        raise ValueError(
+            f"stage must be one of {', '.join(STAGES)}; got {stage!r}"
+        )
+    return stage
+
 
 class ActionGate:
     """Thin, token-authenticated httpx client for the hosted Bindable Action Gate.
@@ -54,13 +80,15 @@ class ActionGate:
         payload: Mapping[str, Any],
         proposed_action_id: str,
         nonce: str | None = None,
+        stage: str | None = None,
     ) -> dict[str, Any]:
         """Submit a Proposal to ``/v1/review`` and return the hosted Outcome dict.
 
-        Sends exactly the five wire fields (persistent_agent_id, action_type,
-        payload, proposed_action_id, nonce) with bearer-token auth. The Outcome
-        is returned verbatim; its ``receipt`` field (when present) can be passed
-        to ``verify_receipt`` for offline verification.
+        Sends the five frozen wire fields (persistent_agent_id, action_type,
+        payload, proposed_action_id, nonce) with bearer-token auth, plus
+        ``stage`` when — and only when — one is given. The Outcome is returned
+        verbatim; its ``receipt`` field (when present) can be passed to
+        ``verify_receipt`` for offline verification.
 
         The endpoint moved from ``/v1/decide`` to ``/v1/review`` in 0.1.2. The
         platform keeps BOTH paths live for a deprecation window, so an older
@@ -74,11 +102,19 @@ class ActionGate:
             proposed_action_id: The caller's id for this proposed action.
             nonce: Replay-protection nonce; a fresh ``secrets.token_hex(16)``
                 is generated when omitted.
+            stage: Which stage to resolve the governing Contract at — one of
+                :data:`STAGES`. Omitted from the request entirely when None,
+                which leaves the platform's own default (``development``) in
+                force and keeps the body byte-identical to a pre-0.1.4 call.
+                A promoted Contract exists only at ``production``, so a caller
+                targeting one must pass it.
 
         Returns:
             The parsed Outcome JSON object as a dict.
 
         Raises:
+            ValueError: If ``stage`` is given and is not one of :data:`STAGES`.
+                Raised before any request is sent.
             BindableAPIError: If the gate returns a non-2xx response. The
                 error carries ``.status`` and the ``detail`` from the JSON body.
         """
@@ -91,6 +127,8 @@ class ActionGate:
             "proposed_action_id": proposed_action_id,
             "nonce": nonce,
         }
+        if stage is not None:
+            body["stage"] = _validated_stage(stage)
         response = self._client.post(
             f"{self._base_url}/v1/review",
             json=body,

bindable-0.1.4/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.4}/pyproject.toml

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

bindable-0.1.4/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.4/tests/test_stage.py

@@ -0,0 +1,152 @@
+"""The stage parameter: sent when given, absent when not, refused when wrong.
+
+Review resolves the governing Contract BY STAGE, and a promoted Contract exists
+only at ``production``. A client that cannot say which stage it means can only
+ever reach the platform's default, so these tests pin three things: that a
+given stage reaches the wire, that an omitted one leaves the request
+byte-identical to a pre-0.1.4 call, and that a wrong one is refused here rather
+than spent on a round trip.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+import httpx
+import pytest
+
+from bindable import STAGES, ActionGate
+
+_BASE_URL = "https://gate.example.com"
+_TOKEN = "test-token"
+
+_OUTCOME: dict[str, Any] = {
+    "status": "released",
+    "verdict": "passed",
+    "reason": None,
+    "reason_code": None,
+    "receipt": None,
+    "action_result": None,
+}
+
+_FROZEN_FIVE = {
+    "persistent_agent_id",
+    "action_type",
+    "payload",
+    "proposed_action_id",
+    "nonce",
+}
+
+
+def _capture(captured: dict[str, Any]) -> Any:
+    def handler(request: httpx.Request) -> httpx.Response:
+        captured["body"] = json.loads(request.content)
+        captured["raw"] = request.content
+        return httpx.Response(200, json=_OUTCOME)
+
+    return handler
+
+
+def _gate_with(handler: Any) -> ActionGate:
+    gate = ActionGate(base_url=_BASE_URL, token=_TOKEN)
+    gate._client.close()
+    gate._client = httpx.Client(transport=httpx.MockTransport(handler), timeout=5.0)
+    return gate
+
+
+def _decide(gate: ActionGate, **extra: Any) -> dict[str, Any]:
+    return gate.decide(
+        persistent_agent_id="agent_1",
+        action_type="paid_data_call",
+        payload={"matter_id": "MER-2026-014", "call_cost_usd": 12},
+        proposed_action_id="claim_1",
+        nonce="fixednonce",
+        **extra,
+    )
+
+
+# ─── the vocabulary ────────────────────────────────────────────────────
+
+
+def test_the_stages_are_the_three_the_platform_resolves_against() -> None:
+    assert STAGES == ("development", "test", "production")
+
+
+# ─── sent when given ───────────────────────────────────────────────────
+
+
+@pytest.mark.parametrize("stage", STAGES)
+def test_a_given_stage_reaches_the_wire(stage: str) -> None:
+    captured: dict[str, Any] = {}
+    with _gate_with(_capture(captured)) as gate:
+        _decide(gate, stage=stage)
+
+    assert captured["body"]["stage"] == stage
+    assert set(captured["body"]) == _FROZEN_FIVE | {"stage"}
+
+
+def test_production_is_reachable_because_a_promoted_contract_lives_only_there() -> None:
+    """The reason this parameter exists, stated as a test."""
+    captured: dict[str, Any] = {}
+    with _gate_with(_capture(captured)) as gate:
+        _decide(gate, stage="production")
+
+    assert captured["body"]["stage"] == "production"
+
+
+# ─── omitted when None ─────────────────────────────────────────────────
+
+
+def test_an_omitted_stage_is_absent_from_the_wire_entirely() -> None:
+    """Not null, not empty — absent. The platform's default stays in force."""
+    captured: dict[str, Any] = {}
+    with _gate_with(_capture(captured)) as gate:
+        _decide(gate)
+
+    assert "stage" not in captured["body"]
+    assert set(captured["body"]) == _FROZEN_FIVE
+
+
+def test_omitting_the_stage_is_byte_identical_to_passing_none() -> None:
+    """Every pre-0.1.4 caller is untouched: same bytes, not merely same fields."""
+    without: dict[str, Any] = {}
+    explicit_none: dict[str, Any] = {}
+
+    with _gate_with(_capture(without)) as gate:
+        _decide(gate)
+    with _gate_with(_capture(explicit_none)) as gate:
+        _decide(gate, stage=None)
+
+    assert without["raw"] == explicit_none["raw"]
+    assert b"stage" not in without["raw"]
+
+
+# ─── refused when invalid ──────────────────────────────────────────────
+
+
+@pytest.mark.parametrize(
+    "bad", ["prod", "Production", "PRODUCTION", "staging", "dev", "", " development"]
+)
+def test_an_invalid_stage_is_refused_locally(bad: str) -> None:
+    """A configuration mistake, answered here — not spent on a 422."""
+    sent: list[Any] = []
+
+    def handler(request: httpx.Request) -> httpx.Response:  # pragma: no cover
+        sent.append(request)
+        return httpx.Response(200, json=_OUTCOME)
+
+    with _gate_with(handler) as gate, pytest.raises(ValueError) as excinfo:
+        _decide(gate, stage=bad)
+
+    assert sent == []  # nothing left the process
+    message = str(excinfo.value)
+    assert repr(bad) in message
+    for allowed in STAGES:
+        assert allowed in message  # the error names what IS allowed
+
+
+def test_the_refusal_happens_before_the_request_is_built() -> None:
+    """No partial send, no retry ambiguity: the call never starts."""
+    with _gate_with(_capture({})) as gate, pytest.raises(ValueError, match="stage must be one of"):
+        _decide(gate, stage="nope")

{bindable-0.1.2 → bindable-0.1.4}/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.4"

bindable-0.1.2/bindable/__init__.py

@@ -1,22 +0,0 @@
-"""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.
-"""
-
-from ._version import __version__
-from .client import ActionGate
-from .crypto import load_public_key
-from .errors import BindableAPIError
-from .verify import ReceiptVerification, verify_receipt
-
-__all__ = [
-    "ActionGate",
-    "BindableAPIError",
-    "ReceiptVerification",
-    "__version__",
-    "load_public_key",
-    "verify_receipt",
-]

bindable-0.1.2/bindable/_version.py

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