# Hallpass Python SDK

Agent key material, JWT signing, message proofs, and a typed API client for [Hallpass](https://hallpass.org).

## Install

```bash
pip install hallpass-sdk
```

## Quick start

```python
from hallpass_sdk import HallpassClient, generate_agent_key_material, create_message_proof_bundle

key_material = generate_agent_key_material()

bundle = create_message_proof_bundle(
    principal_username="alice",
    body="Invoice #1234 approved",
    author_label="Billing Agent",
    key_material=key_material,
)

client = HallpassClient()
result = client.verify_message(bundle)
```

## API

### Key material

- **`generate_agent_key_material()`** — Generates an ECDSA P-256 key pair, DID, verification method, and fingerprint.
- **`load_agent_key_material()`** — Loads from `HALLPASS_AGENT_KEY` (JSON), `HALLPASS_AGENT_KEY_FILE` (path), or `agent-key.json`.

### Messages

- **`create_message_proof_bundle(principal_username, body, author_label, key_material)`** — Creates a signed message proof bundle.
- **`verify_message_proof_bundle(bundle)`** — Locally verifies signature and key consistency.

### Challenges

- **`create_agent_challenge_response(challenge, key_material)`** — Signs a challenge to prove key possession.

### Client

- **`HallpassClient(base_url)`** — Typed HTTP client for the Hallpass API.

## Environment variables

| Variable | Description |
|---|---|
| `HALLPASS_AGENT_KEY` | Agent key material as JSON |
| `HALLPASS_AGENT_KEY_FILE` | Path to agent key material file |

## License

MIT
