Metadata-Version: 2.4
Name: hallpass-sdk
Version: 0.2.0
Summary: Python SDK for Hallpass — agent key material, JWT signing, message proofs, and API client.
License-Expression: MIT
Project-URL: Homepage, https://hallpass.org
Project-URL: Repository, https://github.com/bawolf/hallpass
Project-URL: Documentation, https://github.com/bawolf/hallpass/tree/main/packages/sdk-python
Project-URL: Issues, https://github.com/bawolf/hallpass/issues
Keywords: hallpass,agent,verification,did,jwt,sdk
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.27
Requires-Dist: cryptography>=42.0
Requires-Dist: attrs>=23.0
Requires-Dist: python-dateutil>=2.8
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Dynamic: license-file

# 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
