a2a-firewall-sdk 0.2.0__tar.gz

a2a_firewall_sdk-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Manan Jayeshkumar Panchal
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

a2a_firewall_sdk-0.2.0/PKG-INFO

@@ -0,0 +1,194 @@
+Metadata-Version: 2.4
+Name: a2a-firewall-sdk
+Version: 0.2.0
+Summary: Python SDK for the A2A Firewall — inter-agent governance mesh with Ed25519 identity, Macaroon delegation, and cryptographic lineage
+Author-email: Manan JP <mananjp@users.noreply.github.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/mananjp/a2a-firewall
+Project-URL: Documentation, https://github.com/mananjp/a2a-firewall#readme
+Project-URL: Repository, https://github.com/mananjp/a2a-firewall
+Project-URL: Issues, https://github.com/mananjp/a2a-firewall/issues
+Project-URL: Changelog, https://github.com/mananjp/a2a-firewall/releases
+Keywords: a2a,firewall,agent,multi-agent,security,governance,ed25519,delegation
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.27.0
+Provides-Extra: crypto
+Requires-Dist: cryptography>=42.0.0; extra == "crypto"
+Provides-Extra: otel
+Requires-Dist: opentelemetry-api>=1.27.0; extra == "otel"
+Provides-Extra: all
+Requires-Dist: cryptography>=42.0.0; extra == "all"
+Requires-Dist: opentelemetry-api>=1.27.0; extra == "all"
+Dynamic: license-file
+
+# a2a-firewall-sdk
+
+**Python SDK for the [A2A Firewall](https://github.com/mananjp/a2a-firewall)** — an inter-agent governance mesh that inspects, signs, and attenuates every message between AI agents.
+
+[![PyPI version](https://img.shields.io/pypi/v/a2a-firewall-sdk)](https://pypi.org/project/a2a-firewall-sdk/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+
+## What It Does
+
+The A2A Firewall sits between agents in any multi-agent system and enforces security policies on every inter-agent message:
+
+- **6-layer detection pipeline** — schema validation, permission checks, rule engine, CVE risk scoring, LLM semantic analysis, and policy decisions
+- **Ed25519 message signing** — every message is cryptographically signed, creating a tamper-evident hash chain
+- **Macaroon-style delegation** — capabilities attenuate (narrow) at each delegation hop, never widen
+- **< 20ms p99 deterministic latency** — crypto and rule layers run without LLM calls
+
+This SDK handles all of that automatically: signing, chain hashing, delegation token management, and OpenTelemetry tracing.
+
+## Installation
+
+```bash
+pip install a2a-firewall-sdk
+```
+
+With Ed25519 signing support:
+```bash
+pip install "a2a-firewall-sdk[crypto]"
+```
+
+With OpenTelemetry tracing:
+```bash
+pip install "a2a-firewall-sdk[all]"
+```
+
+## Quick Start
+
+```python
+from a2a_firewall import A2AFirewall, FirewallConfig
+
+# Configure the SDK
+firewall = A2AFirewall(FirewallConfig(
+    firewall_url="https://a2a-firewall-backend.onrender.com",
+    agent_api_key="your_workspace_api_key",
+    agent_id="your-agent-uuid",
+    workspace_id="your-workspace-uuid",
+    agent_private_key="ed25519-private-key-hex",  # optional: enables message signing
+    fail_mode="closed",  # "closed" = block on error, "open" = allow on error
+))
+
+# Send a message through the firewall
+response = firewall.send(
+    receiver_agent_id="target-agent-uuid",
+    task_type="research",
+    payload={"query": "What are the latest fraud trends?"},
+)
+
+print(f"Decision: {response.decision}")  # "allow" | "block" | "review"
+print(f"Risk score: {response.risk_score}")
+print(f"Task ID: {response.task_id}")
+```
+
+## Delegation Tokens
+
+Create attenuable delegation tokens when forwarding tasks between agents:
+
+```python
+# Agent A delegates to Agent B with narrowed permissions
+delegation_token = firewall.create_delegation_token(
+    root_key_hex="workspace-root-key-hex",
+    receiver_agent_id="agent-b-uuid",
+    task_type="research",    # restrict to research tasks only
+    max_risk=0.5,            # cap risk threshold
+)
+
+# The token carries caveats that can only narrow, never widen
+response = firewall.send(
+    receiver_agent_id="agent-b-uuid",
+    task_type="research",
+    payload={"query": "Summarize findings"},
+)
+```
+
+## Verify Incoming Messages
+
+```python
+# Verify a message received from another agent
+result = firewall.verify_message(
+    sender_public_key="sender-ed25519-public-key-hex",
+    message_hash="sha256-message-hash",
+    signature="ed25519-signature-hex",
+    expected_parent_chain_hash="previous-chain-hash",  # optional
+)
+assert result["signature_valid"]
+assert result["chain_valid"]
+```
+
+## Fail Modes
+
+| Mode | Behavior |
+|------|----------|
+| `closed` (default) | Raises `FirewallBlockedError` if the firewall is unreachable |
+| `open` | Allows the message through if the firewall is unreachable |
+
+## OpenTelemetry
+
+When `opentelemetry-api` is installed, the SDK automatically creates spans for every `firewall.inspect` call with `task_type`, `decision`, and `risk_score` attributes. No configuration needed.
+
+```bash
+pip install "a2a-firewall-sdk[otel]"
+```
+
+## API Reference
+
+### `FirewallConfig`
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `firewall_url` | `str` | required | Base URL of the A2A Firewall backend |
+| `agent_api_key` | `str` | required | Workspace API key for authentication |
+| `workspace_id` | `str` | `""` | Workspace identifier |
+| `agent_id` | `str` | `""` | This agent's identifier |
+| `agent_private_key` | `str` | `""` | Ed25519 private key (hex) for message signing |
+| `timeout_seconds` | `float` | `5.0` | HTTP request timeout |
+| `fail_mode` | `str` | `"closed"` | `"closed"` or `"open"` |
+
+### `FirewallResponse`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `task_id` | `str` | Unique task identifier |
+| `decision` | `str` | `"allow"`, `"block"`, or `"review"` |
+| `allowed` | `bool` | Whether the message is allowed to proceed |
+| `risk_score` | `float` | Risk score (0.0 to 1.0) |
+| `violations` | `list[dict]` | List of detected violations |
+| `latency_ms` | `int` | Inspection latency in milliseconds |
+
+### `FirewallBlockedError`
+
+Raised when `raise_on_block=True` (default) and the message is blocked.
+
+```python
+try:
+    firewall.send(...)
+except FirewallBlockedError as e:
+    print(f"Blocked: {e.reason}, risk: {e.risk_score}")
+    print(f"Violations: {e.violations}")
+```
+
+## Links
+
+- **GitHub**: [github.com/mananjp/a2a-firewall](https://github.com/mananjp/a2a-firewall)
+- **Live Demo**: [a2a-firewall.onrender.com](https://a2a-firewall.onrender.com)
+- **TypeScript SDK**: [@a2a-firewall/sdk on npm](https://www.npmjs.com/package/@a2a-firewall/sdk)
+
+## License
+
+MIT

a2a_firewall_sdk-0.2.0/README.md

@@ -0,0 +1,158 @@
+# a2a-firewall-sdk
+
+**Python SDK for the [A2A Firewall](https://github.com/mananjp/a2a-firewall)** — an inter-agent governance mesh that inspects, signs, and attenuates every message between AI agents.
+
+[![PyPI version](https://img.shields.io/pypi/v/a2a-firewall-sdk)](https://pypi.org/project/a2a-firewall-sdk/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+
+## What It Does
+
+The A2A Firewall sits between agents in any multi-agent system and enforces security policies on every inter-agent message:
+
+- **6-layer detection pipeline** — schema validation, permission checks, rule engine, CVE risk scoring, LLM semantic analysis, and policy decisions
+- **Ed25519 message signing** — every message is cryptographically signed, creating a tamper-evident hash chain
+- **Macaroon-style delegation** — capabilities attenuate (narrow) at each delegation hop, never widen
+- **< 20ms p99 deterministic latency** — crypto and rule layers run without LLM calls
+
+This SDK handles all of that automatically: signing, chain hashing, delegation token management, and OpenTelemetry tracing.
+
+## Installation
+
+```bash
+pip install a2a-firewall-sdk
+```
+
+With Ed25519 signing support:
+```bash
+pip install "a2a-firewall-sdk[crypto]"
+```
+
+With OpenTelemetry tracing:
+```bash
+pip install "a2a-firewall-sdk[all]"
+```
+
+## Quick Start
+
+```python
+from a2a_firewall import A2AFirewall, FirewallConfig
+
+# Configure the SDK
+firewall = A2AFirewall(FirewallConfig(
+    firewall_url="https://a2a-firewall-backend.onrender.com",
+    agent_api_key="your_workspace_api_key",
+    agent_id="your-agent-uuid",
+    workspace_id="your-workspace-uuid",
+    agent_private_key="ed25519-private-key-hex",  # optional: enables message signing
+    fail_mode="closed",  # "closed" = block on error, "open" = allow on error
+))
+
+# Send a message through the firewall
+response = firewall.send(
+    receiver_agent_id="target-agent-uuid",
+    task_type="research",
+    payload={"query": "What are the latest fraud trends?"},
+)
+
+print(f"Decision: {response.decision}")  # "allow" | "block" | "review"
+print(f"Risk score: {response.risk_score}")
+print(f"Task ID: {response.task_id}")
+```
+
+## Delegation Tokens
+
+Create attenuable delegation tokens when forwarding tasks between agents:
+
+```python
+# Agent A delegates to Agent B with narrowed permissions
+delegation_token = firewall.create_delegation_token(
+    root_key_hex="workspace-root-key-hex",
+    receiver_agent_id="agent-b-uuid",
+    task_type="research",    # restrict to research tasks only
+    max_risk=0.5,            # cap risk threshold
+)
+
+# The token carries caveats that can only narrow, never widen
+response = firewall.send(
+    receiver_agent_id="agent-b-uuid",
+    task_type="research",
+    payload={"query": "Summarize findings"},
+)
+```
+
+## Verify Incoming Messages
+
+```python
+# Verify a message received from another agent
+result = firewall.verify_message(
+    sender_public_key="sender-ed25519-public-key-hex",
+    message_hash="sha256-message-hash",
+    signature="ed25519-signature-hex",
+    expected_parent_chain_hash="previous-chain-hash",  # optional
+)
+assert result["signature_valid"]
+assert result["chain_valid"]
+```
+
+## Fail Modes
+
+| Mode | Behavior |
+|------|----------|
+| `closed` (default) | Raises `FirewallBlockedError` if the firewall is unreachable |
+| `open` | Allows the message through if the firewall is unreachable |
+
+## OpenTelemetry
+
+When `opentelemetry-api` is installed, the SDK automatically creates spans for every `firewall.inspect` call with `task_type`, `decision`, and `risk_score` attributes. No configuration needed.
+
+```bash
+pip install "a2a-firewall-sdk[otel]"
+```
+
+## API Reference
+
+### `FirewallConfig`
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `firewall_url` | `str` | required | Base URL of the A2A Firewall backend |
+| `agent_api_key` | `str` | required | Workspace API key for authentication |
+| `workspace_id` | `str` | `""` | Workspace identifier |
+| `agent_id` | `str` | `""` | This agent's identifier |
+| `agent_private_key` | `str` | `""` | Ed25519 private key (hex) for message signing |
+| `timeout_seconds` | `float` | `5.0` | HTTP request timeout |
+| `fail_mode` | `str` | `"closed"` | `"closed"` or `"open"` |
+
+### `FirewallResponse`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `task_id` | `str` | Unique task identifier |
+| `decision` | `str` | `"allow"`, `"block"`, or `"review"` |
+| `allowed` | `bool` | Whether the message is allowed to proceed |
+| `risk_score` | `float` | Risk score (0.0 to 1.0) |
+| `violations` | `list[dict]` | List of detected violations |
+| `latency_ms` | `int` | Inspection latency in milliseconds |
+
+### `FirewallBlockedError`
+
+Raised when `raise_on_block=True` (default) and the message is blocked.
+
+```python
+try:
+    firewall.send(...)
+except FirewallBlockedError as e:
+    print(f"Blocked: {e.reason}, risk: {e.risk_score}")
+    print(f"Violations: {e.violations}")
+```
+
+## Links
+
+- **GitHub**: [github.com/mananjp/a2a-firewall](https://github.com/mananjp/a2a-firewall)
+- **Live Demo**: [a2a-firewall.onrender.com](https://a2a-firewall.onrender.com)
+- **TypeScript SDK**: [@a2a-firewall/sdk on npm](https://www.npmjs.com/package/@a2a-firewall/sdk)
+
+## License
+
+MIT

a2a_firewall_sdk-0.2.0/a2a_firewall/__init__.py

@@ -0,0 +1,10 @@
+"""A2A Firewall Python SDK — full identity, delegation, and signing integration."""
+from a2a_firewall.client import (
+    A2AFirewall,
+    FirewallBlockedError,
+    FirewallConfig,
+    FirewallResponse,
+)
+
+__all__ = ["A2AFirewall", "FirewallBlockedError", "FirewallConfig", "FirewallResponse"]
+__version__ = "0.2.0"

a2a_firewall_sdk-0.2.0/a2a_firewall/client.py

@@ -0,0 +1,397 @@
+"""A2A Firewall Python SDK — full identity, delegation, and signing integration.
+
+Usage:
+    from a2a_firewall import A2AFirewall, FirewallConfig
+
+    config = FirewallConfig(
+        firewall_url="http://localhost:8000",
+        workspace_id="ws-uuid",
+        agent_id="agent-uuid",
+        agent_api_key="agt_xxx",
+        agent_private_key="ed25519-hex",        # for signing messages
+        workspace_root_pubkey="ed25519-hex",     # for verifying cards
+        fail_mode="closed",
+    )
+    firewall = A2AFirewall(config)
+
+    response = firewall.send(
+        receiver_agent_id="target-uuid",
+        task_type="research",
+        payload={"query": "What is fraud?"},
+    )
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import time
+import uuid
+from dataclasses import dataclass, field
+from typing import Any, Optional
+
+import httpx
+
+try:
+    from opentelemetry import trace
+    from opentelemetry.trace import SpanKind, Status, StatusCode
+
+    _OTEL_AVAILABLE = True
+except ImportError:
+    _OTEL_AVAILABLE = False
+
+# ---------------------------------------------------------------------------
+# Config
+# ---------------------------------------------------------------------------
+
+@dataclass
+class FirewallConfig:
+    firewall_url: str
+    agent_api_key: str
+    workspace_id: str = ""
+    agent_id: str = ""
+    agent_private_key: str = ""
+    workspace_root_pubkey: str = ""
+    timeout_seconds: float = 5.0
+    fail_mode: str = "closed"
+    review_poll_interval: float = 2.0
+    review_max_wait: float = 60.0
+
+
+# ---------------------------------------------------------------------------
+# Response & Error types
+# ---------------------------------------------------------------------------
+
+@dataclass
+class FirewallResponse:
+    task_id: str
+    decision: str  # "allow" | "block" | "review"
+    allowed: bool
+    risk_score: float
+    violations: list[dict[str, Any]]
+    review_token: Optional[str] = None
+    block_reason: Optional[str] = None
+    latency_ms: int = 0
+    trace_id: Optional[str] = None
+
+
+class FirewallBlockedError(Exception):
+    def __init__(self, task_id: str, reason: str, risk_score: float, violations: list[dict[str, Any]]):
+        self.task_id = task_id
+        self.reason = reason
+        self.risk_score = risk_score
+        self.violations = violations
+        super().__init__(f"Task {task_id} blocked: {reason}")
+
+
+# ---------------------------------------------------------------------------
+# Crypto helpers (self-contained, no backend dependency)
+# ---------------------------------------------------------------------------
+
+def _sha256_hex(data: bytes) -> str:
+    return hashlib.sha256(data).hexdigest()
+
+
+def _compute_message_hash(payload: dict[str, Any], sender_id: str, receiver_id: str, timestamp: float) -> str:
+    canonical = json.dumps(
+        {"payload": payload, "sender": sender_id, "receiver": receiver_id, "ts": timestamp},
+        sort_keys=True, separators=(",", ":"),
+    ).encode()
+    return _sha256_hex(canonical)
+
+
+def _compute_chain_hash(parent_chain_hash: str | None, message_hash: str) -> str:
+    parent = parent_chain_hash or _sha256_hex(b"\x00" * 32)
+    return _sha256_hex(bytes.fromhex(parent) + bytes.fromhex(message_hash))
+
+
+def _ed25519_sign(private_key_hex: str, message: bytes) -> str:
+    from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
+    raw = bytes.fromhex(private_key_hex)
+    key = Ed25519PrivateKey.from_private_bytes(raw)
+    return key.sign(message).hex()
+
+
+def _ed25519_verify(public_key_hex: str, signature_hex: str, message: bytes) -> bool:
+    from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
+    try:
+        key = Ed25519PublicKey.from_public_bytes(bytes.fromhex(public_key_hex))
+        key.verify(bytes.fromhex(signature_hex), message)
+        return True
+    except Exception:
+        return False
+
+
+# ---------------------------------------------------------------------------
+# Delegation token (compact serialization)
+# ---------------------------------------------------------------------------
+
+def _hmac_sha256(key: bytes, data: bytes) -> bytes:
+    return hmac.new(key, data, hashlib.sha256).digest()
+
+
+def _mint_delegation_token(root_key_hex: str, location: str, agent_id: str, caveats: list[str]) -> dict[str, Any]:
+    root_key = bytes.fromhex(root_key_hex) if len(root_key_hex) == 64 else root_key_hex.encode()[:32]
+    msg = f"{location}\n{agent_id}\n".encode() + "\n".join(caveats).encode()
+    sig = _hmac_sha256(root_key, msg).hex()
+    return {"location": location, "identifier": agent_id, "caveats": caveats, "signature": sig}
+
+
+def _attenuate_token(token: dict[str, Any], root_key_hex: str, new_caveats: list[str]) -> dict[str, Any]:
+    root_key = bytes.fromhex(root_key_hex) if len(root_key_hex) == 64 else root_key_hex.encode()[:32]
+    all_caveats = token["caveats"] + new_caveats
+    msg = f"{token['location']}\n{token['identifier']}\n".encode() + "\n".join(all_caveats).encode()
+    sig = _hmac_sha256(root_key, msg).hex()
+    return {"location": token["location"], "identifier": token["identifier"], "caveats": all_caveats, "signature": sig}
+
+
+def _token_to_compact(token: dict[str, Any]) -> str:
+    return json.dumps(token, separators=(",", ":"))
+
+
+# ---------------------------------------------------------------------------
+# Main SDK class
+# ---------------------------------------------------------------------------
+
+class A2AFirewall:
+    def __init__(self, config: FirewallConfig):
+        self.config = config
+        self._ctx: dict[str, Any] = {}
+        self._http = httpx.Client(
+            base_url=config.firewall_url,
+            headers={"Authorization": f"Bearer {config.agent_api_key}"},
+            timeout=config.timeout_seconds,
+        )
+        self._chain_hash: str | None = None
+        self._delegation_token: dict[str, Any] | None = None
+        self._delegation_chain: list[str] = []
+
+    # -- Context management --
+
+    def set_context(
+        self,
+        task_id: str,
+        root_task_id: str,
+        trace_id: str | None = None,
+        span_id: str | None = None,
+        chain_hash: str | None = None,
+        delegation_token: str | None = None,
+    ) -> None:
+        """Set lineage context for the next send (called when processing a received task)."""
+        self._ctx = {
+            "current_task_id": task_id,
+            "root_task_id": root_task_id,
+            "trace_id": trace_id,
+            "span_id": span_id,
+        }
+        if chain_hash:
+            self._chain_hash = chain_hash
+        if delegation_token:
+            self._delegation_token = json.loads(delegation_token)
+
+    # -- Signing --
+
+    def _sign_payload(self, payload: dict[str, Any], receiver_id: str) -> tuple[str, str, str, float]:
+        """Sign a payload and compute chain hash.
+
+        Returns (message_hash, chain_hash, signature, timestamp).
+        """
+        now = time.time()
+        msg_hash = _compute_message_hash(payload, self.config.agent_id, receiver_id, now)
+        chain_hash = _compute_chain_hash(self._chain_hash, msg_hash)
+
+        signature = ""
+        if self.config.agent_private_key:
+            signature = _ed25519_sign(self.config.agent_private_key, bytes.fromhex(msg_hash))
+
+        self._chain_hash = chain_hash
+        return msg_hash, chain_hash, signature, now
+
+    # -- Delegation --
+
+    def create_delegation_token(
+        self,
+        root_key_hex: str,
+        receiver_agent_id: str,
+        task_type: str | None = None,
+        max_risk: float | None = None,
+    ) -> str:
+        """Create a delegation token for forwarding to another agent."""
+        caveats = [f"receiver={receiver_agent_id}"]
+        if task_type:
+            caveats.append(f"task_type={task_type}")
+        if max_risk is not None:
+            caveats.append(f"max_risk={max_risk}")
+
+        if self._delegation_token:
+            token = _attenuate_token(self._delegation_token, root_key_hex, caveats)
+        else:
+            token = _mint_delegation_token(root_key_hex, self.config.workspace_id, self.config.agent_id, caveats)
+
+        self._delegation_token = token
+        self._delegation_chain.append(receiver_agent_id)
+        return _token_to_compact(token)
+
+    # ---------------------------------------------------------------------------
+    # OTel helpers
+    # ---------------------------------------------------------------------------
+
+    # -- Core send --
+
+    def send(
+        self,
+        receiver_agent_id: str,
+        task_type: str,
+        payload: dict[str, Any],
+        resource_type: str | None = None,
+        resource_id: str | None = None,
+        action: str | None = None,
+        parent_task_id: str | None = None,
+        root_task_id: str | None = None,
+        declared_intent: str | None = None,
+        raise_on_block: bool = True,
+        schema_version: str = "v1",
+        depth: int = 0,
+    ) -> FirewallResponse:
+        """Send a message through the firewall with automatic signing and delegation."""
+        task_id = str(uuid.uuid4())
+        msg_hash, chain_hash, signature, timestamp = self._sign_payload(payload, receiver_agent_id)
+
+        body: dict[str, Any] = {
+            "task_id": task_id,
+            "parent_task_id": parent_task_id or self._ctx.get("current_task_id"),
+            "root_task_id": root_task_id or self._ctx.get("root_task_id") or task_id,
+            "receiver_agent_id": receiver_agent_id,
+            "task_type": task_type,
+            "schema_version": schema_version,
+            "resource_type": resource_type,
+            "resource_id": resource_id,
+            "action": action,
+            "payload": payload,
+            "declared_intent": declared_intent,
+            "trace_id": self._ctx.get("trace_id"),
+            "parent_span_id": self._ctx.get("span_id"),
+            "sdk_version": "0.2.0",
+            "depth": depth,
+            "sender_signature": signature,
+            "message_hash": msg_hash,
+            "timestamp": timestamp,
+        }
+
+        # Include delegation token if active
+        if self._delegation_token:
+            body["delegation_token"] = _token_to_compact(self._delegation_token)
+
+        # ── OTel (auto when opentelemetry-api installed) ──
+        span = None
+        if _OTEL_AVAILABLE:
+            span = trace.get_tracer("a2a-firewall-sdk", "0.2.0").start_span(
+                "firewall.inspect", kind=SpanKind.CLIENT,
+                attributes={"task_type": task_type, "receiver_agent_id": receiver_agent_id},
+            )
+            sc = span.get_span_context()
+            if sc.is_valid:
+                body["trace_id"] = format(sc.trace_id, "032x")
+                body["parent_span_id"] = format(sc.span_id, "016x")
+
+        try:
+            resp = self._http.post("/v1/firewall/inspect", json=body)
+            resp.raise_for_status()
+            data = resp.json()
+            fw = FirewallResponse(
+                task_id=data["task_id"],
+                decision=data["decision"],
+                allowed=data["allowed_to_proceed"],
+                risk_score=data["risk_score"],
+                violations=data.get("violations", []),
+                review_token=data.get("review_token"),
+                block_reason=data.get("block_reason"),
+                latency_ms=data.get("latency_ms", 0),
+                trace_id=data.get("trace_id"),
+            )
+            if span:
+                span.set_attribute("decision", fw.decision)
+                span.set_attribute("risk_score", fw.risk_score)
+                span.set_status(Status(StatusCode.OK))
+        except httpx.TimeoutException:
+            if span:
+                span.set_status(Status(StatusCode.ERROR, "timeout"))
+                span.record_exception("firewall_unreachable")
+            if self.config.fail_mode == "closed":
+                raise FirewallBlockedError(task_id, "firewall_unreachable", 1.0, [])
+            return FirewallResponse(
+                task_id=task_id, decision="allow", allowed=True,
+                risk_score=0.0, violations=[], latency_ms=-1,
+            )
+        except httpx.HTTPStatusError as e:
+            if span:
+                span.set_status(Status(StatusCode.ERROR, f"HTTP {e.response.status_code}"))
+                span.record_exception(e)
+            raise RuntimeError(f"Firewall HTTP error: {e.response.status_code}") from e
+        finally:
+            if span:
+                span.end()
+
+        if fw.decision == "review":
+            fw = self._wait_for_review(fw)
+
+        if not fw.allowed and raise_on_block:
+            raise FirewallBlockedError(fw.task_id, fw.block_reason or "unknown", fw.risk_score, fw.violations)
+
+        return fw
+
+    # -- Review polling --
+
+    def _wait_for_review(self, fw: FirewallResponse) -> FirewallResponse:
+        deadline = time.monotonic() + self.config.review_max_wait
+        while time.monotonic() < deadline:
+            time.sleep(self.config.review_poll_interval)
+            try:
+                r = self._http.get(f"/v1/review/{fw.review_token}/status")
+                s = r.json()
+                if s["status"] == "approved":
+                    fw.decision = "allow"
+                    fw.allowed = True
+                    return fw
+                if s["status"] == "rejected":
+                    fw.decision = "block"
+                    fw.allowed = False
+                    fw.block_reason = f"Rejected: {s.get('reviewer_notes', '')}"
+                    return fw
+            except Exception:
+                pass
+        fw.decision = "block"
+        fw.allowed = False
+        fw.block_reason = "review_timeout"
+        return fw
+
+    # -- Verify incoming --
+
+    def verify_message(
+        self,
+        sender_public_key: str,
+        message_hash: str,
+        signature: str,
+        expected_parent_chain_hash: str | None = None,
+    ) -> dict[str, Any]:
+        """Verify an incoming message's Ed25519 signature and chain hash."""
+        sig_valid = _ed25519_verify(sender_public_key, signature, bytes.fromhex(message_hash))
+
+        chain_valid = True
+        if expected_parent_chain_hash:
+            expected_chain = _compute_chain_hash(expected_parent_chain_hash, message_hash)
+            chain_valid = expected_chain == self._chain_hash
+
+        return {"signature_valid": sig_valid, "chain_valid": chain_valid}
+
+    # -- Utility --
+
+    def get_delegation_chain(self) -> list[str]:
+        return list(self._delegation_chain)
+
+    def get_chain_hash(self) -> str | None:
+        return self._chain_hash
+
+    def close(self) -> None:
+        self._http.close()

a2a_firewall_sdk-0.2.0/a2a_firewall_sdk.egg-info/PKG-INFO

@@ -0,0 +1,194 @@
+Metadata-Version: 2.4
+Name: a2a-firewall-sdk
+Version: 0.2.0
+Summary: Python SDK for the A2A Firewall — inter-agent governance mesh with Ed25519 identity, Macaroon delegation, and cryptographic lineage
+Author-email: Manan JP <mananjp@users.noreply.github.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/mananjp/a2a-firewall
+Project-URL: Documentation, https://github.com/mananjp/a2a-firewall#readme
+Project-URL: Repository, https://github.com/mananjp/a2a-firewall
+Project-URL: Issues, https://github.com/mananjp/a2a-firewall/issues
+Project-URL: Changelog, https://github.com/mananjp/a2a-firewall/releases
+Keywords: a2a,firewall,agent,multi-agent,security,governance,ed25519,delegation
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.27.0
+Provides-Extra: crypto
+Requires-Dist: cryptography>=42.0.0; extra == "crypto"
+Provides-Extra: otel
+Requires-Dist: opentelemetry-api>=1.27.0; extra == "otel"
+Provides-Extra: all
+Requires-Dist: cryptography>=42.0.0; extra == "all"
+Requires-Dist: opentelemetry-api>=1.27.0; extra == "all"
+Dynamic: license-file
+
+# a2a-firewall-sdk
+
+**Python SDK for the [A2A Firewall](https://github.com/mananjp/a2a-firewall)** — an inter-agent governance mesh that inspects, signs, and attenuates every message between AI agents.
+
+[![PyPI version](https://img.shields.io/pypi/v/a2a-firewall-sdk)](https://pypi.org/project/a2a-firewall-sdk/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+
+## What It Does
+
+The A2A Firewall sits between agents in any multi-agent system and enforces security policies on every inter-agent message:
+
+- **6-layer detection pipeline** — schema validation, permission checks, rule engine, CVE risk scoring, LLM semantic analysis, and policy decisions
+- **Ed25519 message signing** — every message is cryptographically signed, creating a tamper-evident hash chain
+- **Macaroon-style delegation** — capabilities attenuate (narrow) at each delegation hop, never widen
+- **< 20ms p99 deterministic latency** — crypto and rule layers run without LLM calls
+
+This SDK handles all of that automatically: signing, chain hashing, delegation token management, and OpenTelemetry tracing.
+
+## Installation
+
+```bash
+pip install a2a-firewall-sdk
+```
+
+With Ed25519 signing support:
+```bash
+pip install "a2a-firewall-sdk[crypto]"
+```
+
+With OpenTelemetry tracing:
+```bash
+pip install "a2a-firewall-sdk[all]"
+```
+
+## Quick Start
+
+```python
+from a2a_firewall import A2AFirewall, FirewallConfig
+
+# Configure the SDK
+firewall = A2AFirewall(FirewallConfig(
+    firewall_url="https://a2a-firewall-backend.onrender.com",
+    agent_api_key="your_workspace_api_key",
+    agent_id="your-agent-uuid",
+    workspace_id="your-workspace-uuid",
+    agent_private_key="ed25519-private-key-hex",  # optional: enables message signing
+    fail_mode="closed",  # "closed" = block on error, "open" = allow on error
+))
+
+# Send a message through the firewall
+response = firewall.send(
+    receiver_agent_id="target-agent-uuid",
+    task_type="research",
+    payload={"query": "What are the latest fraud trends?"},
+)
+
+print(f"Decision: {response.decision}")  # "allow" | "block" | "review"
+print(f"Risk score: {response.risk_score}")
+print(f"Task ID: {response.task_id}")
+```
+
+## Delegation Tokens
+
+Create attenuable delegation tokens when forwarding tasks between agents:
+
+```python
+# Agent A delegates to Agent B with narrowed permissions
+delegation_token = firewall.create_delegation_token(
+    root_key_hex="workspace-root-key-hex",
+    receiver_agent_id="agent-b-uuid",
+    task_type="research",    # restrict to research tasks only
+    max_risk=0.5,            # cap risk threshold
+)
+
+# The token carries caveats that can only narrow, never widen
+response = firewall.send(
+    receiver_agent_id="agent-b-uuid",
+    task_type="research",
+    payload={"query": "Summarize findings"},
+)
+```
+
+## Verify Incoming Messages
+
+```python
+# Verify a message received from another agent
+result = firewall.verify_message(
+    sender_public_key="sender-ed25519-public-key-hex",
+    message_hash="sha256-message-hash",
+    signature="ed25519-signature-hex",
+    expected_parent_chain_hash="previous-chain-hash",  # optional
+)
+assert result["signature_valid"]
+assert result["chain_valid"]
+```
+
+## Fail Modes
+
+| Mode | Behavior |
+|------|----------|
+| `closed` (default) | Raises `FirewallBlockedError` if the firewall is unreachable |
+| `open` | Allows the message through if the firewall is unreachable |
+
+## OpenTelemetry
+
+When `opentelemetry-api` is installed, the SDK automatically creates spans for every `firewall.inspect` call with `task_type`, `decision`, and `risk_score` attributes. No configuration needed.
+
+```bash
+pip install "a2a-firewall-sdk[otel]"
+```
+
+## API Reference
+
+### `FirewallConfig`
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `firewall_url` | `str` | required | Base URL of the A2A Firewall backend |
+| `agent_api_key` | `str` | required | Workspace API key for authentication |
+| `workspace_id` | `str` | `""` | Workspace identifier |
+| `agent_id` | `str` | `""` | This agent's identifier |
+| `agent_private_key` | `str` | `""` | Ed25519 private key (hex) for message signing |
+| `timeout_seconds` | `float` | `5.0` | HTTP request timeout |
+| `fail_mode` | `str` | `"closed"` | `"closed"` or `"open"` |
+
+### `FirewallResponse`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `task_id` | `str` | Unique task identifier |
+| `decision` | `str` | `"allow"`, `"block"`, or `"review"` |
+| `allowed` | `bool` | Whether the message is allowed to proceed |
+| `risk_score` | `float` | Risk score (0.0 to 1.0) |
+| `violations` | `list[dict]` | List of detected violations |
+| `latency_ms` | `int` | Inspection latency in milliseconds |
+
+### `FirewallBlockedError`
+
+Raised when `raise_on_block=True` (default) and the message is blocked.
+
+```python
+try:
+    firewall.send(...)
+except FirewallBlockedError as e:
+    print(f"Blocked: {e.reason}, risk: {e.risk_score}")
+    print(f"Violations: {e.violations}")
+```
+
+## Links
+
+- **GitHub**: [github.com/mananjp/a2a-firewall](https://github.com/mananjp/a2a-firewall)
+- **Live Demo**: [a2a-firewall.onrender.com](https://a2a-firewall.onrender.com)
+- **TypeScript SDK**: [@a2a-firewall/sdk on npm](https://www.npmjs.com/package/@a2a-firewall/sdk)
+
+## License
+
+MIT

a2a_firewall_sdk-0.2.0/a2a_firewall_sdk.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+LICENSE
+README.md
+pyproject.toml
+a2a_firewall/__init__.py
+a2a_firewall/client.py
+a2a_firewall_sdk.egg-info/PKG-INFO
+a2a_firewall_sdk.egg-info/SOURCES.txt
+a2a_firewall_sdk.egg-info/dependency_links.txt
+a2a_firewall_sdk.egg-info/requires.txt
+a2a_firewall_sdk.egg-info/top_level.txt
+tests/test_client.py

a2a_firewall_sdk-0.2.0/a2a_firewall_sdk.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

a2a_firewall_sdk-0.2.0/a2a_firewall_sdk.egg-info/requires.txt

@@ -0,0 +1,11 @@
+httpx>=0.27.0
+
+[all]
+cryptography>=42.0.0
+opentelemetry-api>=1.27.0
+
+[crypto]
+cryptography>=42.0.0
+
+[otel]
+opentelemetry-api>=1.27.0

a2a_firewall_sdk-0.2.0/a2a_firewall_sdk.egg-info/top_level.txt

@@ -0,0 +1 @@
+a2a_firewall

a2a_firewall_sdk-0.2.0/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "a2a-firewall-sdk"
+version = "0.2.0"
+description = "Python SDK for the A2A Firewall — inter-agent governance mesh with Ed25519 identity, Macaroon delegation, and cryptographic lineage"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+    { name = "Manan JP", email = "mananjp@users.noreply.github.com" },
+]
+keywords = ["a2a", "firewall", "agent", "multi-agent", "security", "governance", "ed25519", "delegation"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Security",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+dependencies = ["httpx>=0.27.0"]
+
+[project.optional-dependencies]
+crypto = ["cryptography>=42.0.0"]
+otel = ["opentelemetry-api>=1.27.0"]
+all = ["cryptography>=42.0.0", "opentelemetry-api>=1.27.0"]
+
+[project.urls]
+Homepage = "https://github.com/mananjp/a2a-firewall"
+Documentation = "https://github.com/mananjp/a2a-firewall#readme"
+Repository = "https://github.com/mananjp/a2a-firewall"
+Issues = "https://github.com/mananjp/a2a-firewall/issues"
+Changelog = "https://github.com/mananjp/a2a-firewall/releases"
+
+[tool.setuptools.packages.find]
+include = ["a2a_firewall*"]

a2a_firewall_sdk-0.2.0/setup.cfg

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

a2a_firewall_sdk-0.2.0/tests/test_client.py

@@ -0,0 +1,153 @@
+import hashlib
+import json
+import pytest
+from unittest.mock import MagicMock, patch
+from a2a_firewall import A2AFirewall, FirewallConfig, FirewallBlockedError
+from a2a_firewall.client import (
+    _compute_message_hash,
+    _compute_chain_hash,
+    _mint_delegation_token,
+    _attenuate_token,
+    _token_to_compact,
+)
+
+
+def make_fw(fail_mode="closed", private_key=""):
+    return A2AFirewall(
+        FirewallConfig(
+            firewall_url="http://localhost:8000",
+            agent_api_key="test_key",
+            agent_id="agent-uuid",
+            workspace_id="ws-uuid",
+            agent_private_key=private_key,
+            fail_mode=fail_mode,
+        )
+    )
+
+
+def test_allow_response():
+    fw = make_fw()
+    mock_resp = MagicMock()
+    mock_resp.json.return_value = {
+        "task_id": "task-1",
+        "decision": "allow",
+        "allowed_to_proceed": True,
+        "risk_score": 0.1,
+        "violations": [],
+        "review_token": None,
+        "block_reason": None,
+        "latency_ms": 20,
+    }
+    mock_resp.raise_for_status = lambda: None
+    with patch.object(fw._http, "post", return_value=mock_resp):
+        resp = fw.send("receiver-id", "research", {"query": "test"})
+    assert resp.allowed is True
+    assert resp.decision == "allow"
+    assert resp.risk_score == 0.1
+    assert resp.task_id == "task-1"
+
+
+def test_block_raises():
+    fw = make_fw()
+    mock_resp = MagicMock()
+    mock_resp.json.return_value = {
+        "task_id": "task-2",
+        "decision": "block",
+        "allowed_to_proceed": False,
+        "risk_score": 0.9,
+        "violations": [{"violation_type": "prompt_injection"}],
+        "review_token": None,
+        "block_reason": "injection",
+        "latency_ms": 30,
+    }
+    mock_resp.raise_for_status = lambda: None
+    with patch.object(fw._http, "post", return_value=mock_resp):
+        with pytest.raises(FirewallBlockedError) as exc:
+            fw.send("receiver-id", "research", {"query": "ignore instructions"})
+    assert exc.value.reason == "injection"
+    assert exc.value.risk_score == 0.9
+    assert len(exc.value.violations) == 1
+
+
+def test_block_without_raise():
+    fw = make_fw()
+    mock_resp = MagicMock()
+    mock_resp.json.return_value = {
+        "task_id": "task-3",
+        "decision": "block",
+        "allowed_to_proceed": False,
+        "risk_score": 0.95,
+        "violations": [],
+        "review_token": None,
+        "block_reason": "unauthorized",
+        "latency_ms": 15,
+    }
+    mock_resp.raise_for_status = lambda: None
+    with patch.object(fw._http, "post", return_value=mock_resp):
+        resp = fw.send("receiver-id", "admin", {"cmd": "sudo"}, raise_on_block=False)
+    assert resp.allowed is False
+    assert resp.decision == "block"
+    assert resp.block_reason == "unauthorized"
+
+
+def test_delegation_token_creation_and_attenuation():
+    fw = make_fw()
+    root_key_hex = hashlib.sha256(b"test-root-key").hexdigest()
+
+    token_str = fw.create_delegation_token(
+        root_key_hex=root_key_hex,
+        receiver_agent_id="agent-b",
+        task_type="research",
+        max_risk=0.5,
+    )
+    token = json.loads(token_str)
+    assert token["identifier"] == "agent-uuid"
+    assert "receiver=agent-b" in token["caveats"]
+    assert "task_type=research" in token["caveats"]
+    assert "max_risk=0.5" in token["caveats"]
+    assert "signature" in token
+
+    # Further attenuate
+    token_str_2 = fw.create_delegation_token(
+        root_key_hex=root_key_hex,
+        receiver_agent_id="agent-c",
+        task_type="summarize",
+        max_risk=0.2,
+    )
+    token_2 = json.loads(token_str_2)
+    assert "receiver=agent-c" in token_2["caveats"]
+    assert "max_risk=0.2" in token_2["caveats"]
+    assert fw.get_delegation_chain() == ["agent-b", "agent-c"]
+
+
+def test_context_management():
+    fw = make_fw()
+    fw.set_context(
+        task_id="parent-123",
+        root_task_id="root-456",
+        trace_id="trace-789",
+        span_id="span-abc",
+        chain_hash="hash-def",
+    )
+    assert fw._ctx["current_task_id"] == "parent-123"
+    assert fw._ctx["root_task_id"] == "root-456"
+    assert fw.get_chain_hash() == "hash-def"
+
+
+def test_fail_open_mode():
+    import httpx
+    fw = make_fw(fail_mode="open")
+    with patch.object(fw._http, "post", side_effect=httpx.TimeoutException("timeout")):
+        resp = fw.send("receiver-id", "research", {"query": "test"})
+    assert resp.allowed is True
+    assert resp.decision == "allow"
+    assert resp.latency_ms == -1
+
+
+def test_fail_closed_mode():
+    import httpx
+    fw = make_fw(fail_mode="closed")
+    with patch.object(fw._http, "post", side_effect=httpx.TimeoutException("timeout")):
+        with pytest.raises(FirewallBlockedError) as exc:
+            fw.send("receiver-id", "research", {"query": "test"})
+    assert exc.value.reason == "firewall_unreachable"