a2spa 0.1.0__py3-none-any.whl

a2spa/__init__.py

@@ -0,0 +1,313 @@
+import base64
+import copy
+import hashlib
+import json
+import re
+import textwrap
+import uuid
+from datetime import datetime, timezone
+from typing import Any
+
+from cryptography.hazmat.primitives import hashes, serialization
+from cryptography.hazmat.primitives.asymmetric import padding
+
+try:
+    from pqcrypto.sign import ml_dsa_65 as _mldsa
+except Exception:  # pragma: no cover - optional wheel availability is platform-specific
+    _mldsa = None
+
+
+CLASSICAL_RSA_SHA256_PROFILE = "a2spa.classical.rsa_pkcs1v15_sha256.v1"
+PQ_MLDSA_PROFILE = "a2spa.pq.mldsa.v1"
+DEFAULT_SIGNATURE_PROFILE = CLASSICAL_RSA_SHA256_PROFILE
+MLDSA_PRIVATE_KEY_LABEL = "A2SPA ML-DSA-65 PRIVATE KEY"
+SIGNABLE_PAYLOAD_FIELDS = (
+    "agent_id",
+    "target_agent_id",
+    "timestamp",
+    "nonce",
+    "input",
+    "output",
+    "alert_threshold",
+)
+OPTIONAL_SIGNABLE_PAYLOAD_FIELDS = (
+    "crypto_profile",
+    "state_continuity",
+)
+DEFAULT_ALERT_THRESHOLD = 10
+EXPECTED_HASH_RE = re.compile(r"expected:\s*([0-9a-f]{64})", re.IGNORECASE)
+
+
+def _csv(values) -> list[str]:
+    if values in (None, ""):
+        return []
+    if isinstance(values, str):
+        values = [values]
+    return [str(value).strip() for value in values if str(value).strip()]
+
+
+def policy_template(template: str, **overrides) -> dict[str, Any]:
+    templates = {
+        "calendar": {
+            "allowed_actions": ["schedule_meeting", "update_event"],
+            "allowed_workflow_scopes": ["calendar:write"],
+        },
+        "email": {
+            "allowed_actions": ["send_email", "draft_email"],
+            "allowed_workflow_scopes": ["email:send", "email:draft"],
+        },
+        "payment_reservation": {
+            "allowed_actions": ["reserve"],
+            "allowed_intents": ["payment_reservation"],
+            "allowed_workflow_scopes": ["payments:reserve"],
+            "allowed_currencies": ["USD"],
+            "max_spend_usd": 100.0,
+            "require_state_continuity_for_spend": True,
+        },
+        "crm_write": {
+            "allowed_actions": ["create_contact", "update_contact"],
+            "allowed_workflow_scopes": ["crm:write"],
+        },
+    }
+    if template not in templates:
+        raise ValueError(f"Unknown policy template: {template}")
+    policy = dict(templates[template])
+    policy.update({key: value for key, value in overrides.items() if value is not None})
+    return policy
+
+
+def policy_input(
+    *,
+    action: str | None = None,
+    intent: str | None = None,
+    workflow_scope: str | None = None,
+    workflow_scopes=None,
+    amount_usd: str | float | None = None,
+    currency: str | None = None,
+    on_behalf_of: str | None = None,
+    **extra,
+) -> dict[str, Any]:
+    data = dict(extra)
+    if action:
+        data["action"] = action
+    if intent:
+        data["intent"] = intent
+    scopes = _csv(workflow_scopes)
+    if workflow_scope:
+        data["workflow_scope"] = workflow_scope
+    elif scopes:
+        data["workflow_scopes"] = scopes
+    if amount_usd is not None:
+        data["amount_usd"] = str(amount_usd)
+    if currency:
+        data["currency"] = currency
+    if on_behalf_of:
+        data["on_behalf_of"] = on_behalf_of
+    return data
+
+
+def canonicalize_value(value: Any) -> str:
+    return json.dumps(value, sort_keys=True)
+
+
+def canonical_state_hash(state: dict) -> str:
+    if not isinstance(state, dict):
+        raise ValueError("state must be an object")
+    return hashlib.sha256(canonicalize_value(state).encode("utf-8")).hexdigest()
+
+
+def state_continuity_claim(state_id: str, state: dict, sequence: int, expires_at: str | None = None) -> dict[str, Any]:
+    claim = {
+        "state_id": state_id,
+        "state_hash": canonical_state_hash(state),
+        "sequence": int(sequence),
+    }
+    if expires_at:
+        claim["expires_at"] = expires_at
+    return claim
+
+
+def strip_security_fields(payload: dict) -> dict:
+    return {key: copy.deepcopy(value) for key, value in payload.items() if key not in {"hash", "signature"}}
+
+
+def normalize_signable_payload(payload: dict) -> dict:
+    normalized = {field: copy.deepcopy(payload[field]) for field in SIGNABLE_PAYLOAD_FIELDS if field in payload}
+    normalized.setdefault("alert_threshold", DEFAULT_ALERT_THRESHOLD)
+    for field in OPTIONAL_SIGNABLE_PAYLOAD_FIELDS:
+        if field in payload and payload[field] is not None:
+            normalized[field] = copy.deepcopy(payload[field])
+    return normalized
+
+
+def canonicalize_payload(payload: dict) -> str:
+    return json.dumps(normalize_signable_payload(payload), sort_keys=True)
+
+
+def prepare_signed_bytes(payload: dict) -> bytes:
+    return canonicalize_payload(payload).encode("utf-8")
+
+
+def compute_payload_hash(payload: dict) -> str:
+    return hashlib.sha256(prepare_signed_bytes(payload)).hexdigest()
+
+
+def finalize_payload(payload_before_hash: dict) -> dict:
+    finalized = strip_security_fields(payload_before_hash)
+    finalized["hash"] = compute_payload_hash(finalized)
+    return finalized
+
+
+def build_request_body(payload: dict, signature: str) -> dict:
+    return {
+        "payload": copy.deepcopy(payload),
+        "signature": signature,
+    }
+
+
+def build_payload_fields(
+    *,
+    agent_id: str,
+    target_agent_id: str,
+    input_data: Any,
+    output_data: Any = None,
+    alert_threshold: int = 10,
+    signature_profile: str = DEFAULT_SIGNATURE_PROFILE,
+    state_continuity: dict | None = None,
+    nonce: str | None = None,
+    timestamp: str | None = None,
+) -> dict[str, Any]:
+    payload = {
+        "agent_id": agent_id,
+        "target_agent_id": target_agent_id,
+        "timestamp": timestamp or datetime.now(timezone.utc).isoformat(),
+        "nonce": nonce or str(uuid.uuid4()),
+        "input": input_data,
+        "output": output_data if output_data is not None else {"status": "ready"},
+        "alert_threshold": alert_threshold,
+        "crypto_profile": signature_profile,
+    }
+    if state_continuity:
+        payload["state_continuity"] = state_continuity
+    return payload
+
+
+def sign_payload_rsa(private_key_pem: str, payload: dict) -> str:
+    private_key = serialization.load_pem_private_key(private_key_pem.encode("utf-8"), password=None)
+    return private_key.sign(
+        prepare_signed_bytes(payload),
+        padding.PKCS1v15(),
+        hashes.SHA256(),
+    ).hex()
+
+
+def _dearmor_mldsa_private_key(key_text: str) -> bytes:
+    if _mldsa is None:
+        raise RuntimeError("pqcrypto is required for ML-DSA signing")
+    if not isinstance(key_text, str):
+        raise ValueError("Invalid ML-DSA private key")
+
+    begin = f"-----BEGIN {MLDSA_PRIVATE_KEY_LABEL}-----"
+    end = f"-----END {MLDSA_PRIVATE_KEY_LABEL}-----"
+    normalized = key_text.strip().replace("\r\n", "\n")
+    if not normalized.startswith(begin) or not normalized.endswith(end):
+        raise ValueError("Invalid ML-DSA private key envelope")
+
+    body = normalized[len(begin) : -len(end)]
+    raw = base64.b64decode("".join(body.split()), validate=True)
+    if len(raw) != _mldsa.SECRET_KEY_SIZE:
+        raise ValueError("Invalid ML-DSA private key length")
+    return raw
+
+
+def sign_payload_mldsa(private_key_text: str, payload: dict) -> str:
+    if _mldsa is None:
+        raise RuntimeError("pqcrypto is required for ML-DSA signing")
+    return _mldsa.sign(_dearmor_mldsa_private_key(private_key_text), prepare_signed_bytes(payload)).hex()
+
+
+def sign_payload(private_key_text: str, payload: dict, signature_profile: str | None = None) -> str:
+    profile = signature_profile or payload.get("crypto_profile") or CLASSICAL_RSA_SHA256_PROFILE
+    if profile == PQ_MLDSA_PROFILE:
+        return sign_payload_mldsa(private_key_text, payload)
+    if profile == CLASSICAL_RSA_SHA256_PROFILE:
+        return sign_payload_rsa(private_key_text, payload)
+    raise ValueError(f"Unsupported signature profile for client signing: {profile}")
+
+
+def build_signed_request(private_key_text: str, payload_before_hash: dict) -> dict[str, Any]:
+    payload = finalize_payload(payload_before_hash)
+    signature = sign_payload(private_key_text, payload_before_hash, payload_before_hash.get("crypto_profile"))
+    return build_request_body(payload, signature)
+
+
+def extract_expected_hash(error_text: str | None) -> str | None:
+    if not error_text:
+        return None
+    match = EXPECTED_HASH_RE.search(str(error_text))
+    return match.group(1) if match else None
+
+
+def build_debug_snapshot(
+    payload_before_hash: dict,
+    signature: str | None = None,
+    final_payload: dict | None = None,
+    server_error_text: str | None = None,
+) -> dict[str, Any]:
+    pre_hash_payload = strip_security_fields(payload_before_hash)
+    request_payload = copy.deepcopy(final_payload) if final_payload is not None else finalize_payload(pre_hash_payload)
+    canonical_string = canonicalize_payload(pre_hash_payload)
+    signed_bytes = canonical_string.encode("utf-8")
+    snapshot = {
+        "payload_before_hash": pre_hash_payload,
+        "canonical_string": canonical_string,
+        "canonical_bytes_hex": signed_bytes.hex(),
+        "client_computed_hash": hashlib.sha256(signed_bytes).hexdigest(),
+        "final_request_body": build_request_body(request_payload, signature) if signature is not None else {"payload": request_payload},
+        "server_expected_hash": extract_expected_hash(server_error_text),
+    }
+    if server_error_text is not None:
+        snapshot["server_error"] = server_error_text
+    return snapshot
+
+
+class A2SPAClient:
+    def __init__(self, agent_id: str, private_key_text: str):
+        self.agent_id = agent_id
+        self.private_key_text = private_key_text
+
+    def build_signed_request(self, target_agent_id: str, input_data: Any, output_data: Any = None, **kwargs):
+        payload = build_payload_fields(
+            agent_id=self.agent_id,
+            target_agent_id=target_agent_id,
+            input_data=input_data,
+            output_data=output_data,
+            **kwargs,
+        )
+        return build_signed_request(self.private_key_text, payload)
+
+
+__all__ = [
+    "A2SPAClient",
+    "CLASSICAL_RSA_SHA256_PROFILE",
+    "PQ_MLDSA_PROFILE",
+    "build_debug_snapshot",
+    "build_payload_fields",
+    "build_request_body",
+    "build_signed_request",
+    "canonical_state_hash",
+    "canonicalize_payload",
+    "canonicalize_value",
+    "compute_payload_hash",
+    "extract_expected_hash",
+    "finalize_payload",
+    "normalize_signable_payload",
+    "policy_input",
+    "policy_template",
+    "prepare_signed_bytes",
+    "sign_payload",
+    "sign_payload_mldsa",
+    "sign_payload_rsa",
+    "state_continuity_claim",
+    "strip_security_fields",
+]

a2spa/py.typed

@@ -0,0 +1 @@
+partial

a2spa-0.1.0.dist-info/METADATA

@@ -0,0 +1,73 @@
+Metadata-Version: 2.4
+Name: a2spa
+Version: 0.1.0
+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
+Project-URL: Repository, https://github.com/gavincapriola/A2SPA
+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.

a2spa-0.1.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+a2spa/__init__.py,sha256=sjh8oEn2CrH12uk_Wn3FL-7nQbSez8Ad2EpTGGReMs4,10565
+a2spa/py.typed,sha256=la67KBlbjXN-_-DfGNcdOcjYumVpKG_Tkw-8n5dnGB4,8
+a2spa-0.1.0.dist-info/METADATA,sha256=VRAjgJ2lDEWQ-jzc0uO3VDXhSg7pa5omvuJpWtUKXxc,2355
+a2spa-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+a2spa-0.1.0.dist-info/top_level.txt,sha256=5Krwx745tG4iHAhA1uz15_BCXA8QAuGjfhcSy9xWB7E,6
+a2spa-0.1.0.dist-info/RECORD,,

a2spa-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

a2spa-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+a2spa