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
