theprotocol-sdk 0.2.0__tar.gz → 0.4.0__tar.gz

{theprotocol_sdk-0.2.0 → theprotocol_sdk-0.4.0}/PKG-INFO

@@ -1,14 +1,14 @@
 Metadata-Version: 2.4
 Name: theprotocol-sdk
-Version: 0.2.0
-Summary: TheProtocol SDK — Build and call A2A agents. Protocol bridges for ACP, ADK, and more.
+Version: 0.4.0
+Summary: A2A v1.0 SDK — Build sovereign AI agents with DID identity. Protocol bridges for Google A2A, ANP, MCP. Works with Vertex AI, AWS AgentCore, LangGraph, CrewAI.
 Project-URL: Homepage, https://theprotocol.cloud
 Project-URL: Documentation, https://api.theprotocol.cloud/docs
 Project-URL: Repository, https://github.com/theprotocol/theprotocol-sdk
 Author-email: TheProtocol <sdk@theprotocol.cloud>
 License: Apache-2.0
 License-File: LICENSE
-Keywords: a2a,agents,ai,mcp,protocol,theprotocol
+Keywords: a2a,a2a-protocol,agent-to-agent,agents,ai-agents,crewai,did,fastapi,federation,json-rpc,langchain,mcp,sovereign,theprotocol,vertex-ai
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: Apache Software License
@@ -127,6 +127,44 @@ Any platform that speaks A2A v1.0 can call your agent directly:
 
 No additional bridges needed. The SDK's JSON-RPC endpoint is the universal interface.
 
+## Payment & mTLS Authentication
+
+Enforce payment on your agent's A2A endpoints and authenticate callers via SPIFFE mTLS:
+
+```python
+# Agent side — require payment tokens on all A2A calls
+from theprotocol.payment import PaymentVerifier
+from theprotocol.agent import create_a2a_router
+from fastapi import Depends
+
+verifier = PaymentVerifier(
+    registry_url="https://api.theprotocol.cloud",
+    agent_did="did:theprotocol:my-agent",
+)
+router = create_a2a_router(my_agent, dependencies=[Depends(verifier)])
+```
+
+```python
+# Caller side — acquire payment token before calling an agent
+from theprotocol.payment import PaymentClient
+
+client = PaymentClient("https://api.theprotocol.cloud")
+token = await client.get_token(agent_jwt, target_did="...", amount="0.5")
+headers = {"X-Payment-Token": token}
+```
+
+```python
+# mTLS — authenticate agent-to-agent calls with SPIFFE SVIDs
+from theprotocol.payment import A2AAuthenticator, MtlsAgentClient
+
+# Verify incoming mTLS + payment tokens (hybrid auth)
+auth = A2AAuthenticator(registry_url="https://api.theprotocol.cloud")
+
+# Make outbound mTLS calls using your agent's SVID
+client = MtlsAgentClient(cert_dir="/certs")
+result = await client.call(target_url, payload)
+```
+
 ## MCP Tools
 
 For governance, staking, transfers, and discovery — use [MCP tools](https://api.theprotocol.cloud/mcp/sse) (19 tools via Claude Desktop or any MCP client).

{theprotocol_sdk-0.2.0 → theprotocol_sdk-0.4.0}/README.md

@@ -86,6 +86,44 @@ Any platform that speaks A2A v1.0 can call your agent directly:
 
 No additional bridges needed. The SDK's JSON-RPC endpoint is the universal interface.
 
+## Payment & mTLS Authentication
+
+Enforce payment on your agent's A2A endpoints and authenticate callers via SPIFFE mTLS:
+
+```python
+# Agent side — require payment tokens on all A2A calls
+from theprotocol.payment import PaymentVerifier
+from theprotocol.agent import create_a2a_router
+from fastapi import Depends
+
+verifier = PaymentVerifier(
+    registry_url="https://api.theprotocol.cloud",
+    agent_did="did:theprotocol:my-agent",
+)
+router = create_a2a_router(my_agent, dependencies=[Depends(verifier)])
+```
+
+```python
+# Caller side — acquire payment token before calling an agent
+from theprotocol.payment import PaymentClient
+
+client = PaymentClient("https://api.theprotocol.cloud")
+token = await client.get_token(agent_jwt, target_did="...", amount="0.5")
+headers = {"X-Payment-Token": token}
+```
+
+```python
+# mTLS — authenticate agent-to-agent calls with SPIFFE SVIDs
+from theprotocol.payment import A2AAuthenticator, MtlsAgentClient
+
+# Verify incoming mTLS + payment tokens (hybrid auth)
+auth = A2AAuthenticator(registry_url="https://api.theprotocol.cloud")
+
+# Make outbound mTLS calls using your agent's SVID
+client = MtlsAgentClient(cert_dir="/certs")
+result = await client.call(target_url, payload)
+```
+
 ## MCP Tools
 
 For governance, staking, transfers, and discovery — use [MCP tools](https://api.theprotocol.cloud/mcp/sse) (19 tools via Claude Desktop or any MCP client).

{theprotocol_sdk-0.2.0 → theprotocol_sdk-0.4.0}/pyproject.toml

@@ -4,15 +4,15 @@ build-backend = "hatchling.build"
 
 [project]
 name = "theprotocol-sdk"
-version = "0.2.0"
-description = "TheProtocol SDK — Build and call A2A agents. Protocol bridges for ACP, ADK, and more."
+version = "0.4.0"
+description = "A2A v1.0 SDK — Build sovereign AI agents with DID identity. Protocol bridges for Google A2A, ANP, MCP. Works with Vertex AI, AWS AgentCore, LangGraph, CrewAI."
 readme = "README.md"
 license = {text = "Apache-2.0"}
 requires-python = ">=3.10"
 authors = [
     {name = "TheProtocol", email = "sdk@theprotocol.cloud"},
 ]
-keywords = ["agents", "a2a", "protocol", "ai", "mcp", "theprotocol"]
+keywords = ["agents", "a2a", "a2a-protocol", "agent-to-agent", "ai-agents", "mcp", "did", "sovereign", "federation", "vertex-ai", "langchain", "crewai", "fastapi", "json-rpc", "theprotocol"]
 classifiers = [
     "Development Status :: 3 - Alpha",
     "Intended Audience :: Developers",

{theprotocol_sdk-0.2.0 → theprotocol_sdk-0.4.0}/src/theprotocol/__init__.py

@@ -7,4 +7,4 @@ Usage:
     from theprotocol.client import A2AClient, KeyManager
 """
 
-__version__ = "0.1.0"
+__version__ = "0.4.0"

{theprotocol_sdk-0.2.0 → theprotocol_sdk-0.4.0}/src/theprotocol/agent/router.py

@@ -1,9 +1,21 @@
 """FastAPI router factory for A2A agents.
-Accepts both A2A v1.0 and v0.3 wire formats. Responds in v1.0."""
+Accepts both A2A v1.0 and v0.3 wire formats. Responds in v1.0.
+
+Payment enforcement (f045):
+  When REGISTRY_URL env var is set, a PaymentVerifier is automatically
+  injected into the router dependencies. This means every SDK-based agent
+  gets payment verification by default when deployed to the network.
+
+  - REGISTRY_URL set → payment verification ON (required=True by default)
+  - PAYMENT_REQUIRED=false → verification runs but doesn't reject (log only)
+  - REGISTRY_URL not set → no verification (dev/testing mode)
+  - Price=0 agents: caller still gets a 0 AVT token (proves identity), no funds move
+"""
 
 import json
 import inspect
 import logging
+import os
 from typing import Any, Dict, Optional, Union, List, Callable, AsyncGenerator
 
 import pydantic
@@ -87,10 +99,19 @@ def create_a2a_router(
     tags: Optional[List[str]] = None,
     task_store: Optional[BaseTaskStore] = None,
     dependencies: Optional[list] = None,
+    payment_required: Optional[bool] = None,
 ) -> APIRouter:
     """
     Create a FastAPI router that exposes an A2A agent via JSON-RPC 2.0.
 
+    Payment enforcement is automatic when REGISTRY_URL env var is set:
+    - REGISTRY_URL → PaymentVerifier injected (agents must receive payment tokens)
+    - AGENT_DID → identifies this agent for token target validation
+    - PAYMENT_REQUIRED=false → verify but don't reject (log only mode)
+    - TRUSTED_REGISTRIES → comma-separated URLs for cross-registry tokens
+
+    Override with payment_required=False to explicitly disable.
+
     Example::
 
         from theprotocol.agent import BaseA2AAgent, create_a2a_router
@@ -102,7 +123,11 @@ def create_a2a_router(
             ...
 
         app = FastAPI()
+        # Payment verification is automatic if REGISTRY_URL is set
         app.include_router(create_a2a_router(MyAgent()))
+
+        # Explicitly disable payment verification
+        app.include_router(create_a2a_router(MyAgent(), payment_required=False))
     """
     if tags is None:
         tags = ["A2A Protocol"]
@@ -110,7 +135,60 @@ def create_a2a_router(
         task_store = InMemoryTaskStore()
     store = task_store
 
-    router = APIRouter(prefix=prefix, tags=tags, dependencies=dependencies or [])
+    # Build dependencies list
+    all_deps = list(dependencies or [])
+
+    # Auto-inject PaymentVerifier if REGISTRY_URL is configured
+    _registry_url = os.environ.get("REGISTRY_URL", "")
+    _agent_did = os.environ.get("AGENT_DID", "")
+    _pay_required = payment_required
+    if _pay_required is None:
+        _pay_required = os.environ.get("PAYMENT_REQUIRED", "true").lower() != "false"
+
+    if _registry_url and _agent_did and _pay_required is not False:
+        try:
+            from ..payment.verifier import PaymentVerifier
+            _trusted_raw = os.environ.get("TRUSTED_REGISTRIES", "")
+            _trusted = [u.strip() for u in _trusted_raw.split(",") if u.strip()] if _trusted_raw else None
+            _verifier = PaymentVerifier(
+                registry_url=_registry_url,
+                agent_did=_agent_did,
+                required=bool(_pay_required),
+                trusted_registries=_trusted,
+            )
+            all_deps.append(Depends(_verifier))
+            logger.info(
+                f"[A2A Router] PaymentVerifier auto-injected "
+                f"(registry={_registry_url}, did={_agent_did[:30]}, required={_pay_required})"
+            )
+        except ImportError:
+            logger.warning("[A2A Router] PaymentVerifier import failed — payment module not installed")
+        except Exception as e:
+            logger.warning(f"[A2A Router] PaymentVerifier setup failed: {e}")
+    elif _registry_url and not _agent_did:
+        logger.warning("[A2A Router] REGISTRY_URL set but AGENT_DID missing — payment verification disabled")
+
+    # f052: Auto-inject A2AAuthenticator if SPIRE socket is available (IRONHAND)
+    _spiffe_socket = os.environ.get("SPIFFE_ENDPOINT_SOCKET", "")
+    _enable_mtls = os.environ.get("ENABLE_MTLS", "").lower() == "true"
+    if _spiffe_socket and _enable_mtls:
+        try:
+            from ..payment.authenticator import A2AAuthenticator
+            _authenticator = A2AAuthenticator(
+                payment_verifier=_verifier if "_verifier" in dir() else None,
+                required=False,
+            )
+            all_deps.append(Depends(_authenticator))
+            logger.info(
+                f"[A2A Router] A2AAuthenticator auto-injected (mTLS enabled, "
+                f"socket={_spiffe_socket[:40]})"
+            )
+        except ImportError:
+            logger.warning("[A2A Router] A2AAuthenticator import failed — mTLS module not installed")
+        except Exception as e:
+            logger.warning(f"[A2A Router] A2AAuthenticator setup failed: {e}")
+
+    router = APIRouter(prefix=prefix, tags=tags, dependencies=all_deps)
 
     # Discover @a2a_method decorated handlers
     decorated: Dict[str, Callable] = {}

theprotocol_sdk-0.4.0/src/theprotocol/payment/__init__.py

@@ -0,0 +1,33 @@
+"""
+TheProtocol A2A Payment Module — f045
+
+Provides payment verification middleware for agents and a client helper
+for acquiring payment tokens before A2A calls.
+
+Usage (agent-side — enforce payment on all A2A calls):
+
+    from theprotocol.payment import PaymentVerifier
+    from theprotocol.agent import create_a2a_router
+    from fastapi import Depends
+
+    verifier = PaymentVerifier(
+        registry_url="https://api.theprotocol.cloud",
+        agent_did="did:theprotocol:my-agent",
+    )
+    router = create_a2a_router(my_agent, dependencies=[Depends(verifier)])
+
+Usage (caller-side — get a payment token before calling an agent):
+
+    from theprotocol.payment import PaymentClient
+
+    client = PaymentClient("https://api.theprotocol.cloud")
+    token = await client.get_token(agent_jwt, target_did="...", amount="0.5")
+    # Pass token as X-Payment-Token header in A2A request
+"""
+
+from .verifier import PaymentVerifier
+from .client import PaymentClient
+from .authenticator import A2AAuthenticator
+from .mtls_client import MtlsAgentClient
+
+__all__ = ["PaymentVerifier", "PaymentClient", "A2AAuthenticator", "MtlsAgentClient"]

theprotocol_sdk-0.4.0/src/theprotocol/payment/authenticator.py

@@ -0,0 +1,410 @@
+"""
+f052: A2AAuthenticator — Hybrid mTLS + Payment Token Authentication (IRONHAND)
+
+FastAPI Depends() middleware that authenticates A2A callers via:
+  1. mTLS client certificate (SPIFFE SVID) — extracted from X-SSL-Client-Cert header
+     (behind nginx) or TLS connection info (direct connection)
+  2. Payment token (X-Payment-Token header) — delegated to PaymentVerifier
+
+Both can coexist on the same request (belt-and-suspenders).
+
+Revocation enforcement:
+  - Maintains a shared blocklist of revoked SPIFFE IDs
+  - Polls GET /api/v1/agent/revoked-identities every 60 seconds (fallback)
+  - Rejects any mTLS call from a blocklisted SPIFFE ID immediately
+
+Usage:
+    from theprotocol.payment.authenticator import A2AAuthenticator
+    authenticator = A2AAuthenticator(payment_verifier=my_verifier)
+    @app.post("/a2a", dependencies=[Depends(authenticator)])
+"""
+import asyncio
+import logging
+import os
+import threading
+import time
+import urllib.parse
+from typing import Any, ClassVar, Dict, Optional, Set
+
+try:
+    from starlette.requests import Request as StarletteRequest
+except ImportError:
+    StarletteRequest = Any  # type: ignore
+
+logger = logging.getLogger(__name__)
+
+# ── Shared revocation blocklist (class-level, all instances) ──────────
+_revoked_spiffe_ids: Set[str] = set()
+_blocklist_poller_started = False
+_blocklist_ws_started = False
+_blocklist_lock = threading.Lock()
+
+
+def _extract_spiffe_id_from_pem(pem_str: str) -> Optional[str]:
+    """Parse a PEM certificate and extract the SPIFFE ID from the URI SAN."""
+    try:
+        from cryptography import x509
+        from cryptography.x509.oid import ExtensionOID
+
+        cert = x509.load_pem_x509_certificate(pem_str.encode("utf-8"))
+        try:
+            san_ext = cert.extensions.get_extension_for_oid(
+                ExtensionOID.SUBJECT_ALTERNATIVE_NAME
+            )
+            for name in san_ext.value.get_values_for_type(
+                x509.UniformResourceIdentifier
+            ):
+                if name.startswith("spiffe://"):
+                    return name
+        except x509.ExtensionNotFound:
+            pass
+    except ImportError:
+        logger.warning(
+            "[A2AAuthenticator] cryptography library not installed — "
+            "cannot parse client certs"
+        )
+    except Exception as e:
+        logger.debug(f"[A2AAuthenticator] Failed to parse PEM cert: {e}")
+    return None
+
+
+def _did_from_spiffe_id(spiffe_id: str, trust_domain: str) -> Optional[str]:
+    """Extract agent DID from SPIFFE ID path.
+
+    spiffe://agentvault.com/agent/did-theprotocol-4c78...
+    → did:theprotocol:4c78...
+    """
+    prefix = f"spiffe://{trust_domain}/agent/"
+    if not spiffe_id.startswith(prefix):
+        return None
+    sanitized = spiffe_id[len(prefix):]
+    parts = sanitized.split("-", 2)
+    if len(parts) >= 3:
+        return f"{parts[0]}:{parts[1]}:{parts[2]}"
+    return sanitized.replace("-", ":")
+
+
+def _start_blocklist_poller(registry_url: str, poll_interval: int = 60):
+    """Start a background thread that polls the revoked-identities endpoint.
+
+    This is the fallback mechanism. The primary is EventStore WebSocket (future).
+    Runs as a daemon thread — dies with the process.
+    """
+    global _blocklist_poller_started
+    with _blocklist_lock:
+        if _blocklist_poller_started:
+            return
+        _blocklist_poller_started = True
+
+    def _poll():
+        import urllib.request
+        import json
+
+        url = f"{registry_url}/api/v1/agent/revoked-identities"
+        while True:
+            try:
+                time.sleep(poll_interval)
+                req = urllib.request.Request(url, method="GET")
+                with urllib.request.urlopen(req, timeout=10) as resp:
+                    data = json.loads(resp.read())
+                    revoked = data.get("revoked", [])
+                    new_ids = {r["spiffe_id"] for r in revoked if r.get("spiffe_id")}
+                    if new_ids != _revoked_spiffe_ids:
+                        added = new_ids - _revoked_spiffe_ids
+                        removed = _revoked_spiffe_ids - new_ids
+                        _revoked_spiffe_ids.clear()
+                        _revoked_spiffe_ids.update(new_ids)
+                        if added:
+                            logger.info(
+                                f"[A2AAuthenticator] Blocklist updated: "
+                                f"+{len(added)} revoked, -{len(removed)} restored, "
+                                f"total={len(_revoked_spiffe_ids)}"
+                            )
+            except Exception as e:
+                logger.debug(f"[A2AAuthenticator] Blocklist poll failed: {e}")
+
+    t = threading.Thread(target=_poll, daemon=True, name="ironhand-blocklist-poller")
+    t.start()
+    logger.info(
+        f"[A2AAuthenticator] Blocklist poller started "
+        f"(registry={registry_url}, interval={poll_interval}s)"
+    )
+
+
+def _start_ws_listener(event_store_ws_url: str):
+    """Start a background thread that listens to EventStore WebSocket for
+    real-time revocation/enrollment events. Sub-1s blocklist updates.
+
+    Subscribes to:
+      - events:AgentMtlsRevoked → add to blocklist
+      - events:AgentMtlsEnrolled → remove from blocklist
+
+    Auto-reconnects with exponential backoff on disconnect.
+    """
+    global _blocklist_ws_started
+    with _blocklist_lock:
+        if _blocklist_ws_started:
+            return
+        _blocklist_ws_started = True
+
+    def _ws_loop():
+        import json
+
+        ws_url = f"{event_store_ws_url.rstrip('/')}/ws/events"
+        backoff = 1
+
+        while True:
+            try:
+                import websockets.sync.client as ws_sync
+                logger.info(f"[A2AAuthenticator] WS connecting to {ws_url}")
+
+                with ws_sync.connect(ws_url, close_timeout=5) as ws:
+                    # Read welcome message
+                    welcome = ws.recv(timeout=10)
+                    logger.info(f"[A2AAuthenticator] WS connected to EventStore")
+
+                    # Subscribe to revocation + enrollment channels
+                    ws.send(json.dumps({"action": "subscribe", "channel": "events:AgentMtlsRevoked"}))
+                    ws.recv(timeout=5)  # confirmation
+                    ws.send(json.dumps({"action": "subscribe", "channel": "events:AgentMtlsEnrolled"}))
+                    ws.recv(timeout=5)  # confirmation
+
+                    logger.info(
+                        "[A2AAuthenticator] WS subscribed to AgentMtlsRevoked + AgentMtlsEnrolled"
+                    )
+                    backoff = 1  # reset on successful connection
+
+                    # Listen for events
+                    while True:
+                        raw = ws.recv(timeout=300)  # 5min keepalive timeout
+                        try:
+                            msg = json.loads(raw)
+                        except (json.JSONDecodeError, TypeError):
+                            continue
+
+                        if msg.get("type") != "event":
+                            continue
+
+                        event = msg.get("event", {})
+                        event_type = event.get("event_type", "")
+                        event_data = event.get("data", {})
+                        spiffe_id = event_data.get("spiffe_id", "")
+
+                        if not spiffe_id:
+                            continue
+
+                        if event_type == "AgentMtlsRevoked":
+                            _revoked_spiffe_ids.add(spiffe_id)
+                            logger.info(
+                                f"[A2AAuthenticator] WS REVOKED: {spiffe_id} "
+                                f"(blocklist={len(_revoked_spiffe_ids)})"
+                            )
+                        elif event_type == "AgentMtlsEnrolled":
+                            _revoked_spiffe_ids.discard(spiffe_id)
+                            logger.info(
+                                f"[A2AAuthenticator] WS ENROLLED: {spiffe_id} removed from blocklist "
+                                f"(blocklist={len(_revoked_spiffe_ids)})"
+                            )
+
+            except ImportError:
+                logger.warning(
+                    "[A2AAuthenticator] websockets library not installed — "
+                    "WS listener disabled, using polling only"
+                )
+                return  # exit thread permanently
+            except Exception as e:
+                logger.warning(
+                    f"[A2AAuthenticator] WS disconnected: {e}. "
+                    f"Reconnecting in {backoff}s..."
+                )
+                time.sleep(backoff)
+                backoff = min(backoff * 2, 30)
+
+    t = threading.Thread(target=_ws_loop, daemon=True, name="ironhand-ws-listener")
+    t.start()
+    logger.info(f"[A2AAuthenticator] WS listener started (url={event_store_ws_url})")
+
+
+class A2AAuthenticator:
+    """Hybrid authenticator: mTLS identity + payment token.
+
+    Tries mTLS first (X-SSL-Client-Cert header from nginx, or raw TLS info).
+    Falls back to PaymentVerifier for payment token auth.
+    Both can coexist on the same request (belt-and-suspenders).
+
+    Revocation: checks caller's SPIFFE ID against a shared blocklist updated via:
+    1. EventStore WebSocket (sub-1s, if EVENT_STORE_WS_URL configured)
+    2. Polling GET /agent/revoked-identities (60s fallback)
+    A revoked identity gets an immediate 403, even if the SVID cert is still
+    cryptographically valid.
+
+    Args:
+        payment_verifier: Optional PaymentVerifier instance for fallback.
+        trust_domain: Expected SPIFFE trust domain (default: agentvault.com).
+        required: If True, raises 401 when neither mTLS nor payment succeeds.
+        registry_url: Registry URL for blocklist polling (default: REGISTRY_URL env).
+        poll_interval: Blocklist poll interval in seconds (default: 60).
+        event_store_ws_url: EventStore WebSocket URL for real-time revocation (default: EVENT_STORE_WS_URL env).
+    """
+
+    def __init__(
+        self,
+        payment_verifier: Any = None,
+        trust_domain: str = "agentvault.com",
+        required: bool = False,
+        registry_url: str = "",
+        poll_interval: int = 60,
+        event_store_ws_url: str = "",
+    ):
+        self.payment_verifier = payment_verifier
+        self.required = required
+        # Support comma-separated trust domains for cross-frame federation
+        if "," in trust_domain:
+            self.trusted_domains = [d.strip() for d in trust_domain.split(",") if d.strip()]
+        else:
+            self.trusted_domains = [trust_domain]
+        self.trust_domain = self.trusted_domains[0]  # primary domain (backward compat)
+
+        # Start blocklist poller if registry URL is available
+        reg_url = registry_url or os.environ.get("REGISTRY_URL", "")
+        if reg_url:
+            _start_blocklist_poller(reg_url, poll_interval)
+
+        # Start EventStore WebSocket listener for sub-1s revocation
+        es_ws_url = event_store_ws_url or os.environ.get("EVENT_STORE_WS_URL", "")
+        if es_ws_url:
+            _start_ws_listener(es_ws_url)
+
+    async def __call__(self, request: StarletteRequest) -> Dict[str, Any]:
+        """FastAPI Depends() entry point."""
+        result: Dict[str, Any] = {
+            "verified": False,
+            "method": None,
+            "agent_did": None,
+            "spiffe_id": None,
+        }
+
+        # --- Strategy 1: mTLS client certificate ---
+        spiffe_id = self._try_extract_spiffe_id(request)
+        if spiffe_id:
+            # CHECK BLOCKLIST FIRST — immediate revocation enforcement
+            if spiffe_id in _revoked_spiffe_ids:
+                logger.warning(
+                    f"[A2AAuthenticator] BLOCKED revoked identity: {spiffe_id}"
+                )
+                from fastapi import HTTPException
+                raise HTTPException(
+                    status_code=403,
+                    detail=f"Agent identity revoked: {spiffe_id}",
+                )
+
+            # Validate trust domain (supports cross-frame federation)
+            matched_domain = None
+            for td in self.trusted_domains:
+                if spiffe_id.startswith(f"spiffe://{td}/agent/"):
+                    matched_domain = td
+                    break
+
+            if matched_domain:
+                agent_did = _did_from_spiffe_id(spiffe_id, matched_domain)
+                result = {
+                    "verified": True,
+                    "method": "mtls",
+                    "agent_did": agent_did,
+                    "spiffe_id": spiffe_id,
+                }
+                logger.debug(
+                    f"[A2AAuthenticator] mTLS verified: {spiffe_id} → {agent_did}"
+                )
+                if hasattr(request, "state"):
+                    request.state.mtls_auth = result
+                return result
+            else:
+                logger.warning(
+                    f"[A2AAuthenticator] SPIFFE ID from untrusted domain: {spiffe_id}"
+                )
+
+        # --- Strategy 2: Payment token (fallback) ---
+        if self.payment_verifier is not None:
+            try:
+                payment_result = await self.payment_verifier(request)
+                if payment_result and payment_result.get("verified"):
+                    result = {
+                        "verified": True,
+                        "method": "payment",
+                        "agent_did": payment_result.get("caller_did"),
+                        "spiffe_id": None,
+                        "payment_info": payment_result,
+                    }
+                    if hasattr(request, "state"):
+                        request.state.mtls_auth = result
+                    return result
+            except Exception as e:
+                if self.required:
+                    raise
+                logger.debug(f"[A2AAuthenticator] Payment verification failed: {e}")
+
+        # --- Neither worked ---
+        if self.required:
+            from fastapi import HTTPException
+            raise HTTPException(
+                status_code=401,
+                detail="Authentication required: provide mTLS client cert or payment token",
+            )
+
+        if hasattr(request, "state"):
+            request.state.mtls_auth = result
+        return result
+
+    def _try_extract_spiffe_id(self, request: Any) -> Optional[str]:
+        """Try to extract SPIFFE ID from the request."""
+        # Method 1: nginx forwards URL-encoded PEM cert
+        cert_header = None
+        if hasattr(request, "headers"):
+            cert_header = request.headers.get("X-SSL-Client-Cert")
+            if not cert_header:
+                cert_header = request.headers.get("x-ssl-client-cert")
+
+        if cert_header:
+            pem_str = urllib.parse.unquote(cert_header)
+            spiffe_id = _extract_spiffe_id_from_pem(pem_str)
+            if spiffe_id:
+                return spiffe_id
+
+        # Method 2: Direct SPIFFE ID header
+        if hasattr(request, "headers"):
+            direct_id = request.headers.get("X-SPIFFE-ID")
+            if direct_id and any(direct_id.startswith(f"spiffe://{d}/") for d in self.trusted_domains):
+                return direct_id
+
+        # Method 3: ASGI TLS scope
+        if hasattr(request, "scope"):
+            tls_info = request.scope.get("extensions", {}).get("tls")
+            if tls_info:
+                client_certs = tls_info.get("client_cert_chain", [])
+                if client_certs:
+                    spiffe_id = _extract_spiffe_id_from_pem(client_certs[0])
+                    if spiffe_id:
+                        return spiffe_id
+
+        return None
+
+    @staticmethod
+    def add_to_blocklist(spiffe_id: str):
+        """Manually add a SPIFFE ID to the revocation blocklist.
+
+        Used by EventStore WebSocket listener (future) or manual override.
+        """
+        _revoked_spiffe_ids.add(spiffe_id)
+        logger.info(f"[A2AAuthenticator] Added to blocklist: {spiffe_id}")
+
+    @staticmethod
+    def remove_from_blocklist(spiffe_id: str):
+        """Remove a SPIFFE ID from the blocklist (re-enrollment)."""
+        _revoked_spiffe_ids.discard(spiffe_id)
+        logger.info(f"[A2AAuthenticator] Removed from blocklist: {spiffe_id}")
+
+    @staticmethod
+    def get_blocklist() -> Set[str]:
+        """Return current blocklist (for monitoring/debugging)."""
+        return set(_revoked_spiffe_ids)

theprotocol_sdk-0.4.0/src/theprotocol/payment/client.py

@@ -0,0 +1,107 @@
+"""
+A2A Payment Client — helper for acquiring and settling payment tokens.
+
+Used by orchestrators and agents that call other agents.
+
+    client = PaymentClient("https://api.theprotocol.cloud")
+    token = await client.get_token(agent_jwt, "did:theprotocol:weather", "0.5")
+    # ... call agent A2A with X-Payment-Token header ...
+    await client.settle(agent_jwt, token, task_id="weather-123")
+"""
+import logging
+from typing import Optional, Dict
+
+import httpx
+
+logger = logging.getLogger(__name__)
+
+
+class PaymentClient:
+    """Client for the registry A2A payment authorization system."""
+
+    def __init__(self, registry_url: str):
+        self.base = registry_url.rstrip("/")
+
+    def a2a_headers(self, token: str) -> Dict[str, str]:
+        """
+        Build headers to include in an A2A request.
+        Returns both X-Payment-Token and X-Payment-Issuer for cross-registry support.
+        """
+        return {
+            "X-Payment-Token": token,
+            "X-Payment-Issuer": self.base,
+        }
+
+    async def get_token(
+        self,
+        agent_jwt: str,
+        target_did: str,
+        amount: str,
+        contract_id: Optional[int] = None,
+        ttl_seconds: int = 900,
+    ) -> str:
+        """
+        Request a payment token from the registry.
+
+        Returns the plain token string to include as X-Payment-Token header.
+        Use a2a_headers(token) to get both X-Payment-Token and X-Payment-Issuer.
+        Raises on failure (insufficient balance, target not found, etc.).
+        """
+        async with httpx.AsyncClient(timeout=10.0) as client:
+            resp = await client.post(
+                f"{self.base}/api/v1/a2a-payment/authorize",
+                json={
+                    "target_agent_did": target_did,
+                    "amount": amount,
+                    "contract_id": contract_id,
+                    "ttl_seconds": ttl_seconds,
+                },
+                headers={"Authorization": f"Bearer {agent_jwt}"},
+            )
+            if resp.status_code == 200:
+                data = resp.json()
+                logger.info(f"[PaymentClient] Token acquired: {amount} AVT → {target_did}")
+                return data["token"]
+            error = resp.json() if resp.headers.get("content-type", "").startswith("application/json") else {"detail": resp.text}
+            detail = error.get("detail", str(error))
+            raise RuntimeError(f"Payment authorization failed ({resp.status_code}): {detail}")
+
+    async def settle(
+        self,
+        agent_jwt: str,
+        token: str,
+        task_id: Optional[str] = None,
+        success: bool = True,
+    ) -> Dict:
+        """
+        Settle a payment token after task completion.
+        Triggers the actual TEG transfer from caller to target.
+        """
+        async with httpx.AsyncClient(timeout=15.0) as client:
+            resp = await client.post(
+                f"{self.base}/api/v1/a2a-payment/settle",
+                json={
+                    "token": token,
+                    "task_id": task_id,
+                    "success": success,
+                },
+                headers={"Authorization": f"Bearer {agent_jwt}"},
+            )
+            if resp.status_code == 200:
+                data = resp.json()
+                logger.info(f"[PaymentClient] Settled: {data.get('settlement_tx_id', '?')}")
+                return data
+            error = resp.json() if resp.headers.get("content-type", "").startswith("application/json") else {"detail": resp.text}
+            raise RuntimeError(f"Settlement failed ({resp.status_code}): {error.get('detail', str(error))}")
+
+    async def release(self, agent_jwt: str, token: str) -> Dict:
+        """Release an unused payment token (cancel)."""
+        async with httpx.AsyncClient(timeout=10.0) as client:
+            resp = await client.post(
+                f"{self.base}/api/v1/a2a-payment/release",
+                json={"token": token},
+                headers={"Authorization": f"Bearer {agent_jwt}"},
+            )
+            if resp.status_code == 200:
+                return resp.json()
+            raise RuntimeError(f"Release failed ({resp.status_code})")

theprotocol_sdk-0.4.0/src/theprotocol/payment/mtls_client.py

@@ -0,0 +1,139 @@
+"""
+f052: MtlsAgentClient — SPIRE SVID-based mTLS Client for Agent-to-Agent Calls (IRONHAND)
+
+Wraps httpx.AsyncClient with the agent's SVID certificate for outbound mTLS calls.
+The agent fetches its SVID from SPIRE via the workload API and stores the cert/key/bundle
+to disk. This client reads those files for TLS configuration.
+
+Usage:
+    client = MtlsAgentClient(cert_dir="/tmp/svid")
+    result = await client.call_agent(
+        "https://bravo:8152/a2a",
+        method="tasks/send",
+        params={"message": {"role": "user", "parts": [{"text": "Hello"}]}},
+    )
+"""
+import json
+import logging
+from typing import Any, Dict, Optional
+from uuid import uuid4
+
+logger = logging.getLogger(__name__)
+
+try:
+    import httpx
+
+    _HTTPX_AVAILABLE = True
+except ImportError:
+    _HTTPX_AVAILABLE = False
+
+
+def _extract_spiffe_id_from_cert(cert_path: str) -> Optional[str]:
+    """Read a PEM certificate file and extract the SPIFFE ID from the URI SAN."""
+    try:
+        from cryptography import x509
+        from cryptography.x509.oid import ExtensionOID
+
+        with open(cert_path, "rb") as f:
+            cert = x509.load_pem_x509_certificate(f.read())
+        san_ext = cert.extensions.get_extension_for_oid(
+            ExtensionOID.SUBJECT_ALTERNATIVE_NAME
+        )
+        for name in san_ext.value.get_values_for_type(
+            x509.UniformResourceIdentifier
+        ):
+            if name.startswith("spiffe://"):
+                return name
+    except Exception as e:
+        logger.debug(f"[MtlsAgentClient] Failed to read SPIFFE ID from {cert_path}: {e}")
+    return None
+
+
+class MtlsAgentClient:
+    """httpx client with SPIRE SVID for outbound mTLS agent-to-agent calls.
+
+    Reads certificate, key, and CA bundle from a directory populated by the
+    SVID fetcher (svid_fetcher.py) or cert-writer sidecar.
+
+    Args:
+        cert_dir: Directory containing svid.pem, key.pem, bundle.pem.
+        timeout: Request timeout in seconds.
+    """
+
+    def __init__(self, cert_dir: str = "/tmp/svid", timeout: float = 30.0):
+        if not _HTTPX_AVAILABLE:
+            raise ImportError("httpx is required for MtlsAgentClient")
+
+        self.cert_path = f"{cert_dir}/svid.pem"
+        self.key_path = f"{cert_dir}/key.pem"
+        self.bundle_path = f"{cert_dir}/bundle.pem"
+        self.timeout = timeout
+        self._own_spiffe_id: Optional[str] = None
+
+    @property
+    def cert(self) -> tuple:
+        """Certificate + key tuple for httpx."""
+        return (self.cert_path, self.key_path)
+
+    def get_own_spiffe_id(self) -> Optional[str]:
+        """Read own SPIFFE ID from the SVID certificate SAN."""
+        if self._own_spiffe_id is None:
+            self._own_spiffe_id = _extract_spiffe_id_from_cert(self.cert_path)
+        return self._own_spiffe_id
+
+    async def call_agent(
+        self,
+        url: str,
+        method: str,
+        params: Optional[Dict[str, Any]] = None,
+        payment_token: Optional[str] = None,
+        request_id: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Send a JSON-RPC 2.0 request to another agent over mTLS.
+
+        Args:
+            url: Target agent's mTLS endpoint (https://...)
+            method: JSON-RPC method (e.g., "tasks/send")
+            params: Method parameters
+            payment_token: Optional payment token (belt-and-suspenders)
+            request_id: Optional JSON-RPC request ID
+
+        Returns:
+            Parsed JSON response from the target agent.
+        """
+        headers: Dict[str, str] = {"Content-Type": "application/json"}
+        if payment_token:
+            headers["X-Payment-Token"] = payment_token
+
+        payload = {
+            "jsonrpc": "2.0",
+            "method": method,
+            "params": params or {},
+            "id": request_id or str(uuid4()),
+        }
+
+        logger.debug(
+            f"[MtlsAgentClient] mTLS call → {url} method={method} "
+            f"spiffe_id={self.get_own_spiffe_id()}"
+        )
+
+        async with httpx.AsyncClient(
+            cert=self.cert,
+            verify=self.bundle_path,
+            timeout=self.timeout,
+        ) as client:
+            response = await client.post(
+                url, content=json.dumps(payload), headers=headers
+            )
+            response.raise_for_status()
+            return response.json()
+
+    async def health_check(self, url: str) -> Dict[str, Any]:
+        """Check an agent's health endpoint over mTLS."""
+        async with httpx.AsyncClient(
+            cert=self.cert,
+            verify=self.bundle_path,
+            timeout=10.0,
+        ) as client:
+            response = await client.get(url)
+            return response.json()

theprotocol_sdk-0.4.0/src/theprotocol/payment/verifier.py

@@ -0,0 +1,173 @@
+"""
+A2A Payment Verifier — FastAPI middleware for agent-side payment enforcement.
+
+Agents add this as a dependency to their A2A router. It verifies the
+X-Payment-Token header against the issuing registry before allowing the request.
+
+Supports cross-registry verification: if the token was issued by a different
+registry (indicated via X-Payment-Issuer header), the verifier checks the
+issuer against a trusted registries whitelist and verifies with that registry.
+
+    verifier = PaymentVerifier(
+        registry_url="https://api.theprotocol.cloud",
+        agent_did="did:theprotocol:my-agent",
+        required=True,
+        min_amount="0.1",
+        trusted_registries=["https://registry-b.theprotocol.cloud"],
+    )
+    router = create_a2a_router(agent, dependencies=[Depends(verifier)])
+"""
+import logging
+import time
+from decimal import Decimal
+from typing import Optional, Dict, Any, List
+
+import httpx
+
+logger = logging.getLogger(__name__)
+
+# Bounded TTL cache: {cache_key: (result_dict, expire_time)}
+_verify_cache: Dict[str, tuple] = {}
+_CACHE_TTL = 5  # seconds — short to prevent replay of released tokens
+_CACHE_MAX = 200  # max entries — prevents unbounded memory growth
+
+
+class PaymentVerifier:
+    """
+    FastAPI dependency that verifies A2A payment tokens.
+
+    On each incoming A2A request:
+    1. Extracts X-Payment-Token and optional X-Payment-Issuer headers
+    2. Determines which registry to verify against (local or issuer)
+    3. Calls POST /api/v1/a2a-payment/verify on the issuing registry
+    4. Validates response (valid, target matches, not expired)
+    5. Stores payment info in request.state.payment
+
+    Cross-registry flow:
+    - Caller on Registry A gets token from Registry A
+    - Caller sends to agent on Registry B with X-Payment-Issuer: https://api.theprotocol.cloud
+    - Agent B's verifier sees issuer != local, checks trusted_registries whitelist
+    - If trusted, verifies against Registry A's /a2a-payment/verify endpoint
+    """
+
+    def __init__(
+        self,
+        registry_url: str,
+        agent_did: str,
+        required: bool = True,
+        min_amount: Optional[str] = None,
+        cache_ttl: int = _CACHE_TTL,
+        trusted_registries: Optional[List[str]] = None,
+    ):
+        self.registry_url = registry_url.rstrip("/")
+        self.agent_did = agent_did
+        self.required = required
+        self.min_amount = Decimal(min_amount) if min_amount else None
+        self.cache_ttl = cache_ttl
+        # Build trusted set: always trust own registry + any explicitly listed
+        self._trusted = {self.registry_url}
+        if trusted_registries:
+            for url in trusted_registries:
+                self._trusted.add(url.rstrip("/"))
+
+    async def __call__(self, request: Any) -> Dict[str, Any]:
+        """FastAPI Depends() entry point."""
+        from fastapi import HTTPException
+
+        token = (
+            request.headers.get("X-Payment-Token")
+            or request.headers.get("x-payment-token")
+        )
+
+        if not token:
+            if self.required:
+                raise HTTPException(status_code=402, detail="Payment Required — include X-Payment-Token header")
+            request.state.payment = {"verified": False}
+            return {"verified": False}
+
+        # Determine issuing registry
+        issuer = (
+            request.headers.get("X-Payment-Issuer")
+            or request.headers.get("x-payment-issuer")
+            or ""
+        ).rstrip("/")
+
+        if issuer and issuer != self.registry_url:
+            # Cross-registry token — check whitelist
+            if issuer not in self._trusted:
+                if self.required:
+                    raise HTTPException(402, f"Payment issuer not trusted: {issuer}")
+                request.state.payment = {"verified": False, "error": "untrusted_issuer"}
+                return {"verified": False}
+            verify_url = issuer
+        else:
+            verify_url = self.registry_url
+
+        # Check cache (bounded, short TTL)
+        cache_key = f"{verify_url}:{token}"
+        now = time.time()
+        cached = _verify_cache.get(cache_key)
+        if cached and cached[1] > now:
+            result = cached[0]
+        else:
+            result = await self._verify_with_registry(verify_url, token)
+            if result.get("valid"):
+                # Prune if at capacity
+                if len(_verify_cache) >= _CACHE_MAX:
+                    expired = [k for k, v in _verify_cache.items() if v[1] <= now]
+                    for k in expired:
+                        del _verify_cache[k]
+                    if len(_verify_cache) >= _CACHE_MAX:
+                        _verify_cache.clear()
+                _verify_cache[cache_key] = (result, now + self.cache_ttl)
+
+        if not result.get("valid"):
+            if self.required:
+                raise HTTPException(
+                    status_code=402,
+                    detail=f"Payment token invalid: {result.get('error', 'verification failed')}",
+                )
+            request.state.payment = {"verified": False, "error": result.get("error")}
+            return {"verified": False}
+
+        # Verify target DID
+        if result.get("target_agent_did") != self.agent_did:
+            if self.required:
+                raise HTTPException(402, "Payment token not issued for this agent")
+            request.state.payment = {"verified": False, "error": "wrong_target"}
+            return {"verified": False}
+
+        # Check minimum amount
+        if self.min_amount and Decimal(result.get("amount", "0")) < self.min_amount:
+            if self.required:
+                raise HTTPException(402, f"Payment insufficient: {result['amount']} < {self.min_amount}")
+            request.state.payment = {"verified": False, "error": "insufficient_amount"}
+            return {"verified": False}
+
+        payment_info = {
+            "verified": True,
+            "token": token,
+            "token_id": result.get("token_id"),
+            "caller_did": result.get("caller_did"),
+            "target_agent_did": result.get("target_agent_did"),
+            "amount": result.get("amount"),
+            "contract_id": result.get("contract_id"),
+            "issuer_registry": verify_url,
+        }
+        request.state.payment = payment_info
+        return payment_info
+
+    async def _verify_with_registry(self, registry_url: str, token: str) -> dict:
+        """Call a registry's verify endpoint."""
+        try:
+            async with httpx.AsyncClient(timeout=5.0) as client:
+                resp = await client.post(
+                    f"{registry_url}/api/v1/a2a-payment/verify",
+                    json={"token": token, "target_agent_did": self.agent_did},
+                )
+                if resp.status_code == 200:
+                    return resp.json()
+                return {"valid": False, "error": f"Registry returned {resp.status_code}"}
+        except Exception as e:
+            logger.error(f"[PaymentVerifier] Verification failed ({registry_url}): {e}")
+            return {"valid": False, "error": str(e)}