Metadata-Version: 2.4
Name: a2spa
Version: 0.1.1
Summary: A2SPA payload helper library for AI-agent runtime authorization
Author: AI Modularity
License-Expression: LicenseRef-Proprietary
Project-URL: Homepage, https://aimodularity.com/A2SPA
Project-URL: Documentation, https://aimodularity.com/A2SPA/docs
Keywords: a2spa,ai-agents,authorization,payload-helpers,signed-payloads,runtime-security
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: cryptography==45.0.5
Provides-Extra: pq
Requires-Dist: pqcrypto==0.4.0; extra == "pq"

# A2SPA Python Payload Helpers

Helper-only Python package for building, hashing, and signing A2SPA runtime authorization payloads.

The verifier remains server-side. This package does not authorize actions by itself.

## Install

```bash
pip install a2spa
```

For ML-DSA signing support where the optional wheel is available:

```bash
pip install "a2spa[pq]"
```

## Basic Usage

```python
from a2spa import build_payload_fields, build_signed_request, policy_input

payload = build_payload_fields(
    agent_id="user-123_sender",
    target_agent_id="user-123_receiver",
    input_data=policy_input(action="deliver", workflow_scope="messages:deliver"),
)

request_body = build_signed_request(private_key_text, payload)
```

Send `request_body` to `POST /api/verify_payload` with your account API key in the `x-api-key` header.

## Helper Functions

- `build_payload_fields(...)`
- `policy_input(...)`
- `policy_template(...)`
- `state_continuity_claim(...)`
- `canonicalize_payload(...)`
- `compute_payload_hash(...)`
- `finalize_payload(...)`
- `sign_payload(...)`
- `build_signed_request(...)`
- `build_debug_snapshot(...)`

## Security Boundary

Private keys must stay in a secret manager, server environment, or deployment secret. Do not paste private keys into chats, logs, client-side code, or source control.
