bindable 0.1.3__tar.gz → 0.2.0__tar.gz

bindable-0.2.0/CHANGELOG.md

@@ -0,0 +1,59 @@
+# Changelog
+
+## 0.2.0 (unreleased)
+
+### Added
+
+- `verify_receipt` and `verify_trackpoint` verify the Receipts and Trackpoints
+  Bindable issues today, form `v5`, and the previous form `v4`, offline. A
+  record names its form in its `form` field. The digest is recomputed from
+  the covered fields and compared with the one the record declares, and the
+  signature is checked over that digest with Bindable's public key.
+- `ReceiptVerification` and `TrackpointVerification` gain `form`, the form
+  the record was checked as, and `hash_valid`, the same fact as
+  `chain_hash_valid` under its current name. Existing fields are unchanged.
+- A record that is not the form it claims to be (an unknown field, a missing
+  field, a null where none is allowed, a float, an unknown form version)
+  returns `valid=False` with a reason. It never raises.
+- The test suite proves the canonical bytes, digests and signature checks
+  equal to Bindable's committed test vectors for every form, byte for byte.
+  The vectors are a pinned copy (`tests/forms_pin`), and a test fails if the
+  copy drifts.
+- Form `v6` (Bindable's forms v0.4.0, not yet issued): its Receipt and
+  Trackpoint are v5's with only the form value changed, and are verified the
+  same way; the pinned
+  vectors are now those of forms v0.4.0, with v4 and v5 unchanged.
+- `verify_receipt(receipt, public_key)` and
+  `verify_trackpoint(trackpoint, public_key)`: the key may be given as the
+  second argument as well as by name.
+- The file the Portal's "Download Receipt" saves (the Receipt, the public key
+  it names and its Trackpoint) is accepted as it is: `verify_receipt(file)`
+  checks the Receipt under the file's own key, and the new
+  `verify_bundle(file, public_key=None)` returns a `BundleVerification` for
+  the Receipt, the Trackpoint, and whether the Trackpoint names the Receipt
+  (`link_valid`). A file whose key is not the one the Receipt names fails.
+- `bindable verify <file>` (and `python -m bindable verify <file>`): the same
+  checks from the command line, for a downloaded file or for a bare Receipt or
+  Trackpoint with `--key`; `--json` prints the result; exit 0, 1 or 2.
+- README: "Verify a Receipt offline", with the downloaded file first.
+
+### Changed
+
+- `import bindable` no longer imports the HTTP client: `ActionGate` and
+  `STAGES` are loaded on first use, so the verify path imports no network
+  module. `from bindable import ActionGate` works as before.
+- The test suite runs with sockets refused, and proves in a fresh interpreter
+  that verifying a file imports no network module and opens no socket.
+
+### Fixed
+
+- `bindable.__version__` now matches the package version. 0.1.5 reported
+  `0.1.4`.
+
+### Unchanged
+
+- `verify_receipt(receipt, public_key=key)` keeps working.
+- Receipts and Trackpoints without a `form` field (the 0.1.x layouts) are
+  verified exactly as before.
+- No new dependency. Verification uses the Python standard library and
+  `cryptography` only, and makes no network call.

bindable-0.2.0/PKG-INFO

@@ -0,0 +1,144 @@
+Metadata-Version: 2.5
+Name: bindable
+Version: 0.2.0
+Summary: Python client for the hosted Bindable Action Gate, with offline Receipt verification
+Author: Bindable AI LLC
+License-Expression: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+Requires-Python: >=3.10
+Requires-Dist: cryptography>=42
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# bindable
+
+Bindable Python client — propose, decide, and verify accountable agent actions against the hosted Bindable Action Gate. Offline receipt verification included.
+
+## Install
+
+```
+pip install bindable
+```
+
+## Usage
+
+```python
+import bindable
+
+# Submit a Proposal to the Bindable Action Gate, receive a Decision,
+# record the Outcome, then verify the returned Receipt offline.
+```
+
+## Verify a Receipt offline
+
+Every action Bindable reviews leaves a Receipt: a signed record of what was
+proposed, what was decided and why. Anyone who holds a Receipt can check it on
+their own machine. No network connection is needed, and Bindable is never
+contacted.
+
+### From a downloaded Receipt file
+
+On a Receipt's page in the Portal, **Download Receipt** saves one file,
+`bindable-receipt-<receipt_id>.json`, holding the Receipt, the public key it
+was signed under and, once your Gate has reported, its Trackpoint. Check it
+with no connection at all:
+
+```
+pip install bindable
+bindable verify bindable-receipt-<receipt_id>.json
+```
+
+It prints whether the Receipt and its Trackpoint verify, and that the
+Trackpoint names this Receipt, and exits `0` when everything does, `1` when
+something does not, and `2` when the file cannot be read. Add `--json` for a
+result a program can read, or `--key <pem file>` to check against a key you
+hold rather than the one in the file. The key in the file shows the file
+agrees with itself; to show the Receipt is Bindable's, compare that key with
+the one Bindable publishes at `GET /v1/keys/{signing_key_id}`, or pass it with
+`--key`.
+
+In Python, the same file is accepted as it is, by `verify_receipt(document)`
+for the Receipt alone, or by `verify_bundle(document)` for the Receipt, its
+Trackpoint and the link between them:
+
+```python
+import json
+from bindable import verify_bundle
+
+result = verify_bundle(json.load(open("bindable-receipt-<receipt_id>.json")))
+print("Verified." if result.valid else f"Not verified: {result.reason}")
+```
+
+### From a Receipt and a key
+
+You need two things:
+
+1. **The Receipt**, as JSON. Your Gate returns it with each decision. You can
+   also fetch a Receipt's public form by its ID from
+   `GET /v1/receipts/{receipt_id}/public`, which needs no credential.
+2. **Bindable's public key** for the key named in the Receipt's
+   `signing_key_id`. Fetch it once from `GET /v1/keys/{signing_key_id}` (no
+   credential needed) and keep it. Retired keys stay published, so an old
+   Receipt can always be checked.
+
+Then:
+
+```python
+import json
+from bindable import verify_receipt
+
+receipt = json.load(open("receipt.json"))
+public_key = open("bindable-public-key.pem").read()
+
+result = verify_receipt(receipt, public_key)
+
+if result.valid:
+    print("Genuine and unchanged.")
+else:
+    print("Do not rely on this Receipt:", result.reason)
+```
+
+What the answer tells you:
+
+| Field | Meaning |
+|---|---|
+| `valid` | `True` only when both checks below pass. Rely on the Receipt only then. |
+| `hash_valid` | The Receipt's contents are exactly what was recorded. If even one character of a covered field changed, this is `False`. |
+| `signature_valid` | Bindable's key signed this Receipt. `False` for a different key or a broken signature. `None` if you gave no key. |
+| `form` | Which version of the Receipt layout was checked, for example `"v5"`. |
+| `reason` | A short explanation when `valid` is `False`. Meant for people to read, not for programs to parse. |
+
+`verify_receipt` never raises an exception for a bad or incomplete Receipt.
+It returns `valid=False` with a reason.
+
+Some fields travel beside a Receipt but are not covered by its signature:
+`reason_detail`, `proposal_payload`, `principal_disclosed`, `principal_id`
+and `release_token`. Changing them does not change the result, so do not treat
+them as signed evidence.
+
+A Trackpoint, the record of what your Gate did after the decision, is
+checked the same way with `verify_trackpoint`. If you give a key and the
+Trackpoint carries no signature, the answer is `valid=False`, never a pass on
+the contents alone.
+
+Without a key, both functions check the contents only. Anyone can compute that
+check, so it shows a record is internally consistent, not that Bindable made
+it. Give the key whenever you need to know where a record came from.
+
+**Which Receipts this checks.** Forms `v4` and `v5`, the layouts Bindable
+has issued, and `v6`, the next, defined and ready to check. Receipts from the
+0.1.x releases, which have no `form` field, are still checked the way 0.1.x
+checked them.
+
+The checks use only the Python standard library and the `cryptography`
+package, and import nothing that can reach a network: the HTTP client this
+library also ships is loaded only when you use `ActionGate`. This library
+contains no signing code and no private key.
+
+Status: pre-release

bindable-0.2.0/README.md

@@ -0,0 +1,126 @@
+# bindable
+
+Bindable Python client — propose, decide, and verify accountable agent actions against the hosted Bindable Action Gate. Offline receipt verification included.
+
+## Install
+
+```
+pip install bindable
+```
+
+## Usage
+
+```python
+import bindable
+
+# Submit a Proposal to the Bindable Action Gate, receive a Decision,
+# record the Outcome, then verify the returned Receipt offline.
+```
+
+## Verify a Receipt offline
+
+Every action Bindable reviews leaves a Receipt: a signed record of what was
+proposed, what was decided and why. Anyone who holds a Receipt can check it on
+their own machine. No network connection is needed, and Bindable is never
+contacted.
+
+### From a downloaded Receipt file
+
+On a Receipt's page in the Portal, **Download Receipt** saves one file,
+`bindable-receipt-<receipt_id>.json`, holding the Receipt, the public key it
+was signed under and, once your Gate has reported, its Trackpoint. Check it
+with no connection at all:
+
+```
+pip install bindable
+bindable verify bindable-receipt-<receipt_id>.json
+```
+
+It prints whether the Receipt and its Trackpoint verify, and that the
+Trackpoint names this Receipt, and exits `0` when everything does, `1` when
+something does not, and `2` when the file cannot be read. Add `--json` for a
+result a program can read, or `--key <pem file>` to check against a key you
+hold rather than the one in the file. The key in the file shows the file
+agrees with itself; to show the Receipt is Bindable's, compare that key with
+the one Bindable publishes at `GET /v1/keys/{signing_key_id}`, or pass it with
+`--key`.
+
+In Python, the same file is accepted as it is, by `verify_receipt(document)`
+for the Receipt alone, or by `verify_bundle(document)` for the Receipt, its
+Trackpoint and the link between them:
+
+```python
+import json
+from bindable import verify_bundle
+
+result = verify_bundle(json.load(open("bindable-receipt-<receipt_id>.json")))
+print("Verified." if result.valid else f"Not verified: {result.reason}")
+```
+
+### From a Receipt and a key
+
+You need two things:
+
+1. **The Receipt**, as JSON. Your Gate returns it with each decision. You can
+   also fetch a Receipt's public form by its ID from
+   `GET /v1/receipts/{receipt_id}/public`, which needs no credential.
+2. **Bindable's public key** for the key named in the Receipt's
+   `signing_key_id`. Fetch it once from `GET /v1/keys/{signing_key_id}` (no
+   credential needed) and keep it. Retired keys stay published, so an old
+   Receipt can always be checked.
+
+Then:
+
+```python
+import json
+from bindable import verify_receipt
+
+receipt = json.load(open("receipt.json"))
+public_key = open("bindable-public-key.pem").read()
+
+result = verify_receipt(receipt, public_key)
+
+if result.valid:
+    print("Genuine and unchanged.")
+else:
+    print("Do not rely on this Receipt:", result.reason)
+```
+
+What the answer tells you:
+
+| Field | Meaning |
+|---|---|
+| `valid` | `True` only when both checks below pass. Rely on the Receipt only then. |
+| `hash_valid` | The Receipt's contents are exactly what was recorded. If even one character of a covered field changed, this is `False`. |
+| `signature_valid` | Bindable's key signed this Receipt. `False` for a different key or a broken signature. `None` if you gave no key. |
+| `form` | Which version of the Receipt layout was checked, for example `"v5"`. |
+| `reason` | A short explanation when `valid` is `False`. Meant for people to read, not for programs to parse. |
+
+`verify_receipt` never raises an exception for a bad or incomplete Receipt.
+It returns `valid=False` with a reason.
+
+Some fields travel beside a Receipt but are not covered by its signature:
+`reason_detail`, `proposal_payload`, `principal_disclosed`, `principal_id`
+and `release_token`. Changing them does not change the result, so do not treat
+them as signed evidence.
+
+A Trackpoint, the record of what your Gate did after the decision, is
+checked the same way with `verify_trackpoint`. If you give a key and the
+Trackpoint carries no signature, the answer is `valid=False`, never a pass on
+the contents alone.
+
+Without a key, both functions check the contents only. Anyone can compute that
+check, so it shows a record is internally consistent, not that Bindable made
+it. Give the key whenever you need to know where a record came from.
+
+**Which Receipts this checks.** Forms `v4` and `v5`, the layouts Bindable
+has issued, and `v6`, the next, defined and ready to check. Receipts from the
+0.1.x releases, which have no `form` field, are still checked the way 0.1.x
+checked them.
+
+The checks use only the Python standard library and the `cryptography`
+package, and import nothing that can reach a network: the HTTP client this
+library also ships is loaded only when you use `ActionGate`. This library
+contains no signing code and no private key.
+
+Status: pre-release

bindable-0.2.0/bindable/__init__.py

@@ -0,0 +1,63 @@
+"""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.
+
+Offline verification imports nothing that can reach a network. The transport
+client, which does, is imported only when ``ActionGate`` or ``STAGES`` is first
+used, so ``from bindable import verify_receipt`` and ``bindable verify`` load
+no HTTP library at all.
+"""
+
+from typing import TYPE_CHECKING, Any
+
+from ._version import __version__
+from .crypto import load_public_key
+from .decision import BLOCKED, RELEASED, decision_from
+from .errors import BindableAPIError
+from .verify import (
+    BundleVerification,
+    ReceiptVerification,
+    TrackpointVerification,
+    verify_bundle,
+    verify_receipt,
+    verify_trackpoint,
+)
+
+if TYPE_CHECKING:
+    from .client import STAGES, ActionGate
+
+
+def __getattr__(name: str) -> Any:
+    """The transport client, imported on first use."""
+    if name in ("ActionGate", "STAGES"):
+        from . import client
+
+        return getattr(client, name)
+    raise AttributeError(f"module 'bindable' has no attribute {name!r}")
+
+
+__all__ = [
+    "BLOCKED",
+    "RELEASED",
+    "STAGES",
+    "ActionGate",
+    "BindableAPIError",
+    "BundleVerification",
+    "ReceiptVerification",
+    "TrackpointVerification",
+    "__version__",
+    "decision_from",
+    "load_public_key",
+    "verify_bundle",
+    "verify_receipt",
+    "verify_trackpoint",
+]

bindable-0.2.0/bindable/__main__.py

@@ -0,0 +1,7 @@
+"""``python -m bindable verify <file>``, the same as ``bindable verify <file>``."""
+
+import sys
+
+from bindable.cli import main
+
+sys.exit(main())

bindable-0.2.0/bindable/_canonical_trackpoint.py

@@ -0,0 +1,53 @@
+"""Canonical hash-input serialization for trackpoints (form v3).
+
+Single source of truth for the canonical input over which a trackpoint's
+chain_hash is computed, and — on production — what its signature covers.
+``verify_trackpoint`` reconstructs this input to verify offline; the platform
+constructs it when appending. Both must be byte-identical.
+
+FIFTEEN FIELDS, form v3 (2026-09-03). Form v2 hashed thirteen: ``gate_runner``
+and ``stage`` were excluded only because rows predated the columns, and
+including them then would have split the chain at an undocumented instant. Both
+chains restarted at genesis on 2026-09-03 with zero rows, so that reason is gone
+and both fields are now covered.
+
+``chain_hash`` is NOT in this input — it is the OUTPUT. A signature covers this
+canonical record, which is equivalent to signing the chain_hash by ECDSA's
+standard construction.
+
+Pure and deterministic: no I/O, no mutation. Keys are sorted by RFC 8785 at
+serialization, so the order written here is for readers, not for the digest.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Mapping
+
+#: The fifteen hashed field names, in the order a reader should think about them.
+CANONICAL_FIELDS: tuple[str, ...] = (
+    "trackpoint_id",
+    "receipt_id",
+    "persistent_agent_id",
+    "principal_id",
+    "outcome",
+    "action_result",
+    "proposed_at",
+    "decided_at",
+    "enforced_at",
+    "gate_version",
+    "gate_kind",
+    "gate_runner",
+    "stage",
+    "environment",
+    "previous_hash",
+)
+
+
+def _canonical_trackpoint_input(trackpoint: Mapping[str, Any]) -> dict[str, Any]:
+    """Return the canonical hash input for one trackpoint.
+
+    Timestamps are hashed as the wire strings the platform wrote
+    (ISO 8601 UTC, millisecond precision, ``Z`` suffix). They are taken
+    verbatim: a verifier must not reformat a value it is checking.
+    """
+    return {name: trackpoint.get(name) for name in CANONICAL_FIELDS}