a2spa 0.1.0__tar.gz

a2spa-0.1.0/MANIFEST.in

@@ -0,0 +1,8 @@
+include sdk/README.md
+recursive-include sdk/a2spa py.typed
+prune tests
+prune routes
+prune templates
+prune static
+prune a2spa_sdk
+prune scripts

a2spa-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,36 @@
+# A2SPA
+
+A2SPA is a runtime authorization layer for AI-agent actions. It verifies signed payloads, enforces agent policy, checks state continuity, and emits execution receipts before work is allowed to proceed.
+
+This repository contains the Flask verifier application, dashboard, integration docs, and Python/Node payload helper libraries.
+
+## What A2SPA Verifies
+
+- A registered agent signed the payload with an active key.
+- The payload has not been replayed with a reused nonce.
+- The sender and receiver policies allow the requested action, scope, spend, currency, and delegation claim.
+- Optional state continuity still matches the registered state hash, sequence, status, and expiry.
+- The verifier can emit a signed execution receipt for audit trails.
+
+## Public Product Routes
+
+- `/A2SPA/` - product homepage.
+- `/A2SPA/docs` - human and AI-assistant integration docs.
+- `/A2SPA/integrations` - integration pack and starter guidance.
+- `/A2SPA/agentspoofed` - agent-spoofing threat page.
+- `/A2SPA/dashboard` - authenticated control plane.
+- `/A2SPA/profile` - authenticated account, balance, API-key metadata, and notification status.
+
+## Payload Helper Boundary
+
+Distributed helper packages may build payloads, canonicalize them, sign them, and help construct policy/state-continuity claims. Verifier logic and enforcement decisions stay server-side in the Flask application.
+
+## Local Verification
+
+```bash
+python -m pytest
+```
+
+Use `.env.example` for local configuration shape only. Do not commit real `.env` files, Firebase service accounts, receipt-signing keys, API keys, SMTP passwords, or private agent keys.
+
+Production operations guidance belongs in private runbooks, not in this repository.

a2spa-0.1.0/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "a2spa"
+version = "0.1.0"
+description = "A2SPA payload helper library for AI-agent runtime authorization"
+readme = "sdk/README.md"
+requires-python = ">=3.11"
+license = "LicenseRef-Proprietary"
+authors = [
+  { name = "AI Modularity" },
+]
+keywords = ["a2spa", "ai-agents", "authorization", "payload-helpers", "signed-payloads", "runtime-security"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Security",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+  "cryptography==45.0.5",
+]
+
+[project.optional-dependencies]
+pq = ["pqcrypto==0.4.0"]
+
+[project.urls]
+Homepage = "https://aimodularity.com/A2SPA"
+Documentation = "https://aimodularity.com/A2SPA/docs"
+Repository = "https://github.com/gavincapriola/A2SPA"
+
+[tool.setuptools]
+package-dir = {"" = "sdk"}
+packages = ["a2spa"]
+
+[tool.setuptools.package-data]
+a2spa = ["py.typed"]

a2spa-0.1.0/sdk/README.md

@@ -0,0 +1,50 @@
+# 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/sdk/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-0.1.0/sdk/a2spa/py.typed

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

a2spa-0.1.0/sdk/a2spa.egg-info/PKG-INFO

@@ -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/sdk/a2spa.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+MANIFEST.in
+README.md
+pyproject.toml
+sdk/README.md
+sdk/a2spa/__init__.py
+sdk/a2spa/py.typed
+sdk/a2spa.egg-info/PKG-INFO
+sdk/a2spa.egg-info/SOURCES.txt
+sdk/a2spa.egg-info/dependency_links.txt
+sdk/a2spa.egg-info/requires.txt
+sdk/a2spa.egg-info/top_level.txt

a2spa-0.1.0/sdk/a2spa.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

a2spa-0.1.0/sdk/a2spa.egg-info/requires.txt

@@ -0,0 +1,4 @@
+cryptography==45.0.5
+
+[pq]
+pqcrypto==0.4.0

a2spa-0.1.0/sdk/a2spa.egg-info/top_level.txt

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

a2spa-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+