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

pip install a2spa

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

pip install "a2spa[pq]"

Basic Usage

from pathlib import Path

from a2spa import build_payload_fields, build_signed_request, policy_input

private_key_text = Path("sender.priv.pem").read_text(encoding="utf-8")

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(...)
• is_authorized_result(...)
• require_authorized_result(...)
• build_debug_snapshot(...)

Signed Bytes

Current A2SPA 2.0 helper compatibility signs the UTF-8 bytes of json.dumps(signable_payload, sort_keys=True) using the normalized signable fields. Do not reimplement canonicalization unless your bytes match canonicalize_payload(...) exactly.

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.