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:
- 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. - Bindable's public key for the key named in the Receipt's
signing_key_id. Fetch it once fromGET /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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.