capiscio-sdk 0.2.0__tar.gz → 0.3.0__tar.gz

{capiscio_sdk-0.2.0 → capiscio_sdk-0.3.0}/CHANGELOG.md

@@ -90,13 +90,27 @@ pip install capiscio-sdk==0.1.0
 
 ## [Unreleased]
 
-### Planned for v0.2.0
-- Signature verification (crypto validation)
-- Agent card validation
-- Upstream agent testing
-- Integration tests
-- End-to-end tests
-- Performance benchmarks
+## [0.3.0] - 2025-11-22
+
+### Added
+- **SimpleGuard Security Strategy**:
+  - **Identity**: Ed25519 JWS signature verification (`X-Capiscio-JWS` header).
+  - **Integrity**: SHA-256 Body Hash verification (`bh` claim) to prevent payload tampering.
+  - **Freshness**: Replay protection using `exp` (expiration) and `iat` (issued at) claims with a 60-second window.
+  - **Zero Config**: Secure by default with minimal setup.
+- **FastAPI Integration**:
+  - `CapiscioMiddleware`: Automatic request validation and identity injection into `request.state.agent_id`.
+  - `Server-Timing` header support for telemetry (verification time).
+- **Telemetry**:
+  - Added `dur` (duration) metric to `Server-Timing` header for monitoring security overhead.
+- **Documentation**:
+  - Updated `README.md` with "Enforcement First" strategy.
+  - Updated `SECURITY.md` with threat model and verification steps.
+  - Added `examples/secure_ping_pong` demo.
+
+### Changed
+- **Breaking Change**: Shifted from "Validation" focus to "Enforcement" focus.
+- Updated `pyproject.toml` dependencies to include `cryptography` and `pyjwt`.
 
 ### Planned for v1.0.0
 - Full A2A v1.0 compliance

{capiscio_sdk-0.2.0 → capiscio_sdk-0.3.0}/CONTRIBUTING.md

@@ -1,4 +1,4 @@
-# Contributing to CapiscIO A2A Security
+# Contributing to CapiscIO Python SDK
 
 Thank you for your interest in contributing! This document provides guidelines for contributing to the project.
 

capiscio_sdk-0.3.0/PKG-INFO

@@ -0,0 +1,126 @@
+Metadata-Version: 2.4
+Name: capiscio-sdk
+Version: 0.3.0
+Summary: Runtime security middleware for A2A agents
+Project-URL: Homepage, https://capisc.io
+Project-URL: Documentation, https://docs.capisc.io/sdk-python
+Project-URL: Repository, https://github.com/capiscio/capiscio-sdk-python
+Project-URL: Issues, https://github.com/capiscio/capiscio-sdk-python/issues
+Author-email: Capiscio Team <team@capisc.io>
+License: Apache-2.0
+License-File: LICENSE
+Keywords: a2a,agent,agent-to-agent,middleware,security,validation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+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
+Requires-Python: >=3.10
+Requires-Dist: a2a-sdk>=0.1.0
+Requires-Dist: cachetools>=5.3.0
+Requires-Dist: cryptography>=42.0.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pyjwt[crypto]>=2.8.0
+Provides-Extra: dev
+Requires-Dist: black>=24.0.0; extra == 'dev'
+Requires-Dist: fastapi>=0.100.0; extra == 'dev'
+Requires-Dist: mypy>=1.9.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.3.0; extra == 'dev'
+Requires-Dist: starlette>=0.27.0; extra == 'dev'
+Requires-Dist: types-cachetools>=5.3.0; extra == 'dev'
+Provides-Extra: web
+Requires-Dist: fastapi>=0.100.0; extra == 'web'
+Requires-Dist: starlette>=0.27.0; extra == 'web'
+Description-Content-Type: text/markdown
+
+# CapiscIO SDK (Python)
+
+**Enforcement-First Security for A2A Agents.**
+
+[![PyPI version](https://badge.fury.io/py/capiscio-sdk.svg)](https://badge.fury.io/py/capiscio-sdk)
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+
+**CapiscIO** is the "Customs Officer" for your AI Agent. It provides military-grade Identity and Integrity enforcement for the [Agent-to-Agent (A2A) Protocol](https://github.com/google/A2A) with **zero configuration**.
+
+## 🚀 The 60-Second Upgrade
+
+Turn any FastAPI application into a Verified A2A Agent in 3 lines of code.
+
+```python
+from fastapi import FastAPI
+from capiscio_sdk.simple_guard import SimpleGuard
+from capiscio_sdk.integrations.fastapi import CapiscioMiddleware
+
+# 1. Initialize Guard (Auto-generates keys in dev_mode)
+guard = SimpleGuard(dev_mode=True)
+
+app = FastAPI()
+
+# 2. Add Enforcement Middleware
+app.add_middleware(CapiscioMiddleware, guard=guard)
+
+@app.post("/agent/task")
+async def handle_task(request: Request):
+    # 🔒 Only reachable if Identity + Integrity are verified
+    caller = request.state.agent_id
+    return {"status": "accepted", "verified_caller": caller}
+```
+
+## 🛡️ What You Get (Out of the Box)
+
+1.  **Zero-Config Identity**:
+    *   Auto-generates **Ed25519** keys and `agent-card.json` on first run.
+    *   No manual key management required for development.
+
+2.  **Payload Integrity**:
+    *   Enforces **SHA-256 Body Hash (`bh`)** verification.
+    *   Blocks tampered payloads instantly (returns `403 Forbidden`).
+
+3.  **Replay Protection**:
+    *   Enforces strict **60-second** token expiration (`exp`).
+    *   Prevents replay attacks and ensures freshness.
+
+4.  **Performance Telemetry**:
+    *   Adds `<1ms` overhead.
+    *   Includes `Server-Timing` headers for transparent monitoring.
+
+## Installation
+
+```bash
+pip install capiscio-sdk
+```
+
+## How It Works
+
+### 1. The Handshake
+CapiscIO enforces the **A2A Trust Protocol**:
+*   **Sender**: Signs the request body (JWS + Body Hash).
+*   **Receiver**: Verifies the signature and re-hashes the body to ensure integrity.
+
+### 2. The "Customs Officer"
+The `SimpleGuard` acts as a local authority. It manages your agent's "Passport" (Agent Card) and verifies the "Visas" (Tokens) of incoming requests.
+
+### 3. Telemetry
+Every response includes a `Server-Timing` header showing exactly how fast the verification was:
+```http
+Server-Timing: capiscio-auth;dur=0.618;desc="CapiscIO Verification"
+```
+
+## Documentation
+
+- [Official Documentation](https://docs.capisc.io)
+- [A2A Protocol Spec](https://github.com/google/A2A)
+
+## License
+
+Apache License 2.0 - see [LICENSE](LICENSE) for details.

capiscio_sdk-0.3.0/README.md

@@ -0,0 +1,82 @@
+# CapiscIO SDK (Python)
+
+**Enforcement-First Security for A2A Agents.**
+
+[![PyPI version](https://badge.fury.io/py/capiscio-sdk.svg)](https://badge.fury.io/py/capiscio-sdk)
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+
+**CapiscIO** is the "Customs Officer" for your AI Agent. It provides military-grade Identity and Integrity enforcement for the [Agent-to-Agent (A2A) Protocol](https://github.com/google/A2A) with **zero configuration**.
+
+## 🚀 The 60-Second Upgrade
+
+Turn any FastAPI application into a Verified A2A Agent in 3 lines of code.
+
+```python
+from fastapi import FastAPI
+from capiscio_sdk.simple_guard import SimpleGuard
+from capiscio_sdk.integrations.fastapi import CapiscioMiddleware
+
+# 1. Initialize Guard (Auto-generates keys in dev_mode)
+guard = SimpleGuard(dev_mode=True)
+
+app = FastAPI()
+
+# 2. Add Enforcement Middleware
+app.add_middleware(CapiscioMiddleware, guard=guard)
+
+@app.post("/agent/task")
+async def handle_task(request: Request):
+    # 🔒 Only reachable if Identity + Integrity are verified
+    caller = request.state.agent_id
+    return {"status": "accepted", "verified_caller": caller}
+```
+
+## 🛡️ What You Get (Out of the Box)
+
+1.  **Zero-Config Identity**:
+    *   Auto-generates **Ed25519** keys and `agent-card.json` on first run.
+    *   No manual key management required for development.
+
+2.  **Payload Integrity**:
+    *   Enforces **SHA-256 Body Hash (`bh`)** verification.
+    *   Blocks tampered payloads instantly (returns `403 Forbidden`).
+
+3.  **Replay Protection**:
+    *   Enforces strict **60-second** token expiration (`exp`).
+    *   Prevents replay attacks and ensures freshness.
+
+4.  **Performance Telemetry**:
+    *   Adds `<1ms` overhead.
+    *   Includes `Server-Timing` headers for transparent monitoring.
+
+## Installation
+
+```bash
+pip install capiscio-sdk
+```
+
+## How It Works
+
+### 1. The Handshake
+CapiscIO enforces the **A2A Trust Protocol**:
+*   **Sender**: Signs the request body (JWS + Body Hash).
+*   **Receiver**: Verifies the signature and re-hashes the body to ensure integrity.
+
+### 2. The "Customs Officer"
+The `SimpleGuard` acts as a local authority. It manages your agent's "Passport" (Agent Card) and verifies the "Visas" (Tokens) of incoming requests.
+
+### 3. Telemetry
+Every response includes a `Server-Timing` header showing exactly how fast the verification was:
+```http
+Server-Timing: capiscio-auth;dur=0.618;desc="CapiscIO Verification"
+```
+
+## Documentation
+
+- [Official Documentation](https://docs.capisc.io)
+- [A2A Protocol Spec](https://github.com/google/A2A)
+
+## License
+
+Apache License 2.0 - see [LICENSE](LICENSE) for details.

{capiscio_sdk-0.2.0 → capiscio_sdk-0.3.0}/RELEASE_GUIDE.md

@@ -1,4 +1,4 @@
-# Release Guide - CapiscIO A2A Security
+# Release Guide - CapiscIO Python SDK
 
 This guide explains how to release a new version of the package.
 

{capiscio_sdk-0.2.0 → capiscio_sdk-0.3.0}/SECURITY.md

@@ -4,7 +4,8 @@
 
 | Version | Supported          |
 | ------- | ------------------ |
-| 0.1.x   | :white_check_mark: |
+| 0.2.x   | :white_check_mark: |
+| 0.1.x   | :x:                |
 
 ## Reporting a Vulnerability
 
@@ -32,7 +33,7 @@ Include:
 
 ## Security Best Practices
 
-When using CapiscIO A2A Security:
+When using the CapiscIO Python SDK:
 
 1. **Keep dependencies updated**
    ```bash

{capiscio_sdk-0.2.0 → capiscio_sdk-0.3.0}/capiscio_sdk/__init__.py

@@ -12,6 +12,7 @@ __version__ = "0.2.0"
 
 # Core exports
 from .executor import CapiscioSecurityExecutor, secure, secure_agent
+from .simple_guard import SimpleGuard
 from .config import SecurityConfig, DownstreamConfig, UpstreamConfig
 from .errors import (
     CapiscioSecurityError,
@@ -25,6 +26,7 @@ from .types import ValidationResult, ValidationIssue, ValidationSeverity
 __all__ = [
     "__version__",
     "CapiscioSecurityExecutor",
+    "SimpleGuard",
     "secure",
     "secure_agent",
     "SecurityConfig",

{capiscio_sdk-0.2.0 → capiscio_sdk-0.3.0}/capiscio_sdk/config.py

@@ -1,4 +1,4 @@
-"""Configuration for Capiscio A2A Security."""
+"""Configuration for Capiscio Python SDK."""
 import os
 from typing import Literal
 from pydantic import BaseModel, Field

{capiscio_sdk-0.2.0 → capiscio_sdk-0.3.0}/capiscio_sdk/errors.py

@@ -1,4 +1,4 @@
-"""Error types for Capiscio A2A Security."""
+"""Error types for Capiscio Python SDK."""
 from typing import Optional, List, Dict, Any
 from .types import ValidationResult
 
@@ -67,3 +67,13 @@ class CapiscioTimeoutError(CapiscioSecurityError):
     """Operation timed out."""
 
     pass
+
+
+class ConfigurationError(CapiscioSecurityError):
+    """Missing keys or invalid paths (SimpleGuard)."""
+    pass
+
+
+class VerificationError(CapiscioSecurityError):
+    """Invalid signature, expired token, or untrusted key (SimpleGuard)."""
+    pass

{capiscio_sdk-0.2.0 → capiscio_sdk-0.3.0}/capiscio_sdk/executor.py

@@ -138,6 +138,23 @@ class CapiscioSecurityExecutor:
         # Cancellation just passes through - no security checks needed
         await self.delegate.cancel(context, event_queue)
 
+    async def validate_agent_card(self, url: str) -> ValidationResult:
+        """
+        Validate an agent card from a URL.
+        
+        Args:
+            url: URL to the agent card or agent root
+            
+        Returns:
+            ValidationResult with scores
+        """
+        from .validators.agent_card import AgentCardValidator
+        validator = AgentCardValidator()
+        try:
+            return await validator.fetch_and_validate(url)
+        finally:
+            await validator.http_client.aclose()
+
     def _validate_message(self, message: Dict[str, Any]) -> ValidationResult:
         """Validate message with caching."""
         # Try cache first

capiscio_sdk-0.3.0/capiscio_sdk/integrations/fastapi.py

@@ -0,0 +1,73 @@
+"""FastAPI integration for Capiscio SimpleGuard."""
+from typing import Callable, Awaitable, Any, Dict
+try:
+    from starlette.middleware.base import BaseHTTPMiddleware
+    from starlette.requests import Request
+    from starlette.responses import JSONResponse, Response
+    from starlette.types import ASGIApp
+except ImportError:
+    raise ImportError("FastAPI/Starlette is required for this integration. Install with 'pip install fastapi'.")
+
+from ..simple_guard import SimpleGuard
+from ..errors import VerificationError
+import time
+
+class CapiscioMiddleware(BaseHTTPMiddleware):
+    """
+    Middleware to enforce A2A identity verification on incoming requests.
+    """
+    def __init__(self, app: ASGIApp, guard: SimpleGuard) -> None:
+        super().__init__(app)
+        self.guard = guard
+
+    async def dispatch(
+        self, 
+        request: Request, 
+        call_next: Callable[[Request], Awaitable[Response]]
+    ) -> Response:
+        # Allow health checks or public endpoints if needed
+        # For now, we assume everything under /agent/ needs protection
+        # But let's just check for the header.
+        
+        if request.method == "OPTIONS":
+            return await call_next(request)
+
+        auth_header = request.headers.get("X-Capiscio-JWS")
+        
+        # If no header, we might let it pass but mark as unverified?
+        # The mandate says: "Returns 401 (missing) or 403 (invalid)."
+        if not auth_header:
+             return JSONResponse(
+                 {"error": "Missing X-Capiscio-JWS header. This endpoint is protected by CapiscIO."}, 
+                 status_code=401
+             )
+
+        start_time = time.perf_counter()
+        try:
+            # Read the body for integrity check
+            body_bytes = await request.body()
+            
+            # Verify the JWS with body
+            payload = self.guard.verify_inbound(auth_header, body=body_bytes)
+            
+            # Reset the receive channel so downstream can read the body
+            async def receive() -> Dict[str, Any]:
+                return {"type": "http.request", "body": body_bytes, "more_body": False}
+            request._receive = receive
+            
+            # Inject claims into request.state
+            request.state.agent = payload
+            request.state.agent_id = payload.get("iss")
+            
+        except VerificationError as e:
+            return JSONResponse({"error": f"Access Denied: {str(e)}"}, status_code=403)
+        
+        verification_duration = (time.perf_counter() - start_time) * 1000
+
+        response = await call_next(request)
+        
+        # Add Server-Timing header (standard for performance metrics)
+        # Syntax: metric_name;dur=123.4;desc="Description"
+        response.headers["Server-Timing"] = f"capiscio-auth;dur={verification_duration:.3f};desc=\"CapiscIO Verification\""
+        
+        return response