Skip to main content

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

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:

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:

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

Metadata

Release files for bindable 0.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for bindable 0.2.0
File Size Uploaded Provenance Actions
bindable-0.2.0.tar.gz 79.4 kB Without provenance Details for bindable-0.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for bindable 0.2.0
File Interpreter ABI Platform Actions
bindable-0.2.0-py3-none-any.whl Python 3 none any Details for bindable-0.2.0-py3-none-any.whl

Total release size: 120.0 kB

Release files / bindable-0.2.0.tar.gz

Download URL bindable-0.2.0.tar.gz
Size 79.4 kB
Tags Source
SHA-256 checksum
How to use checksums
00096868bb20e0c8bf986d047dee03a4b71d724890dbfea34e7fc12f2fc00ba0
BLAKE2b-256 checksum
How to use checksums
998b5735285fe6707465388c91847d679c0cb59f9aabb17f37418652c3cc3cd0
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.2

Release files / bindable-0.2.0-py3-none-any.whl

Download URL bindable-0.2.0-py3-none-any.whl
Size 40.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
3a4ee45edf586bd6467cbd652abeb7949a77c07d65928c424e9f285293c27cc6
BLAKE2b-256 checksum
How to use checksums
141c51595182c7e11b0364bfc109e2f6ee56b8457e42786b0191c1eac8214a62
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.2

Security for bindable 0.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page