capiscio-sdk 0.2.0__py3-none-any.whl

capiscio_sdk/__init__.py

@@ -0,0 +1,42 @@
+"""Capiscio SDK - Runtime security middleware for A2A agents.
+
+This package provides always-on protection for A2A protocol agents through
+validation, signature verification, and protocol compliance checking.
+
+Example:
+    >>> from capiscio_sdk import secure
+    >>> agent = secure(MyAgentExecutor())
+"""
+
+__version__ = "0.2.0"
+
+# Core exports
+from .executor import CapiscioSecurityExecutor, secure, secure_agent
+from .config import SecurityConfig, DownstreamConfig, UpstreamConfig
+from .errors import (
+    CapiscioSecurityError,
+    CapiscioValidationError,
+    CapiscioSignatureError,
+    CapiscioRateLimitError,
+    CapiscioUpstreamError,
+)
+from .types import ValidationResult, ValidationIssue, ValidationSeverity
+
+__all__ = [
+    "__version__",
+    "CapiscioSecurityExecutor",
+    "secure",
+    "secure_agent",
+    "SecurityConfig",
+    "DownstreamConfig",
+    "UpstreamConfig",
+    "CapiscioSecurityError",
+    "CapiscioValidationError",
+    "CapiscioSignatureError",
+    "CapiscioRateLimitError",
+    "CapiscioUpstreamError",
+    "ValidationResult",
+    "ValidationIssue",
+    "ValidationSeverity",
+]
+

capiscio_sdk/config.py

@@ -0,0 +1,114 @@
+"""Configuration for Capiscio A2A Security."""
+import os
+from typing import Literal
+from pydantic import BaseModel, Field
+
+
+class DownstreamConfig(BaseModel):
+    """Configuration for downstream protection (agents calling you)."""
+
+    validate_schema: bool = True
+    verify_signatures: bool = True
+    require_signatures: bool = False
+    check_protocol_compliance: bool = True
+    enable_rate_limiting: bool = True
+    rate_limit_requests_per_minute: int = 60
+
+
+class UpstreamConfig(BaseModel):
+    """Configuration for upstream protection (calling other agents)."""
+
+    validate_agent_cards: bool = True
+    verify_signatures: bool = True
+    require_signatures: bool = False
+    test_endpoints: bool = False  # Performance impact
+    cache_validation: bool = True
+    cache_timeout: int = 3600  # seconds
+
+
+class SecurityConfig(BaseModel):
+    """Main security configuration."""
+
+    downstream: DownstreamConfig = Field(default_factory=DownstreamConfig)
+    upstream: UpstreamConfig = Field(default_factory=UpstreamConfig)
+    strict_mode: bool = False
+    fail_mode: Literal["block", "monitor", "log"] = "block"
+    log_validation_failures: bool = True
+    timeout_ms: int = 5000
+
+    @classmethod
+    def development(cls) -> "SecurityConfig":
+        """Development preset - permissive."""
+        return cls(
+            downstream=DownstreamConfig(
+                require_signatures=False,
+                enable_rate_limiting=False,
+            ),
+            upstream=UpstreamConfig(
+                require_signatures=False,
+                test_endpoints=False,
+            ),
+            strict_mode=False,
+            fail_mode="log",
+        )
+
+    @classmethod
+    def production(cls) -> "SecurityConfig":
+        """Production preset - balanced."""
+        return cls(
+            downstream=DownstreamConfig(
+                require_signatures=False,
+                enable_rate_limiting=True,
+            ),
+            upstream=UpstreamConfig(
+                require_signatures=False,
+                test_endpoints=False,
+            ),
+            strict_mode=False,
+            fail_mode="block",
+        )
+
+    @classmethod
+    def strict(cls) -> "SecurityConfig":
+        """Strict preset - maximum security."""
+        return cls(
+            downstream=DownstreamConfig(
+                require_signatures=True,
+                enable_rate_limiting=True,
+            ),
+            upstream=UpstreamConfig(
+                require_signatures=True,
+                test_endpoints=True,
+            ),
+            strict_mode=True,
+            fail_mode="block",
+        )
+
+    @classmethod
+    def from_env(cls) -> "SecurityConfig":
+        """Load configuration from environment variables."""
+        return cls(
+            downstream=DownstreamConfig(
+                validate_schema=os.getenv("CAPISCIO_VALIDATE_SCHEMA", "true").lower()
+                == "true",
+                verify_signatures=os.getenv("CAPISCIO_VERIFY_SIGNATURES", "true").lower()
+                == "true",
+                require_signatures=os.getenv("CAPISCIO_REQUIRE_SIGNATURES", "false").lower()
+                == "true",
+                enable_rate_limiting=os.getenv("CAPISCIO_RATE_LIMITING", "true").lower()
+                == "true",
+                rate_limit_requests_per_minute=int(os.getenv("CAPISCIO_RATE_LIMIT_RPM", "60")),
+            ),
+            upstream=UpstreamConfig(
+                validate_agent_cards=os.getenv("CAPISCIO_VALIDATE_UPSTREAM", "true").lower()
+                == "true",
+                verify_signatures=os.getenv(
+                    "CAPISCIO_VERIFY_UPSTREAM_SIGNATURES", "true"
+                ).lower()
+                == "true",
+                cache_validation=os.getenv("CAPISCIO_CACHE_VALIDATION", "true").lower()
+                == "true",
+            ),
+            fail_mode=os.getenv("CAPISCIO_FAIL_MODE", "block"),  # type: ignore
+            timeout_ms=int(os.getenv("CAPISCIO_TIMEOUT_MS", "5000")),
+        )

capiscio_sdk/errors.py

@@ -0,0 +1,69 @@
+"""Error types for Capiscio A2A Security."""
+from typing import Optional, List, Dict, Any
+from .types import ValidationResult
+
+
+class CapiscioSecurityError(Exception):
+    """Base error for Capiscio security."""
+
+    def __init__(self, message: str, details: Optional[Dict[str, Any]] = None):
+        super().__init__(message)
+        self.message = message
+        self.details = details or {}
+
+
+class CapiscioValidationError(CapiscioSecurityError):
+    """Schema or protocol validation failed."""
+
+    def __init__(
+        self,
+        message: str,
+        validation_result: ValidationResult,
+        errors: Optional[List[str]] = None,
+    ):
+        super().__init__(message)
+        self.validation_result = validation_result
+        self.errors = errors or [issue.message for issue in validation_result.errors]
+
+
+class CapiscioSignatureError(CapiscioSecurityError):
+    """Signature verification failed."""
+
+    def __init__(self, message: str, agent_url: str, reason: str):
+        super().__init__(message)
+        self.agent_url = agent_url
+        self.reason = reason
+
+
+class CapiscioRateLimitError(CapiscioSecurityError):
+    """Rate limit exceeded."""
+
+    def __init__(self, message: str, retry_after_seconds: int):
+        super().__init__(message)
+        self.retry_after_seconds = retry_after_seconds
+
+
+class CapiscioUpstreamError(CapiscioSecurityError):
+    """Upstream agent validation failed."""
+
+    def __init__(
+        self,
+        message: str,
+        agent_url: str,
+        validation_result: ValidationResult,
+    ):
+        super().__init__(message)
+        self.agent_url = agent_url
+        self.validation_result = validation_result
+
+
+class CapiscioConfigError(CapiscioSecurityError):
+    """Configuration error."""
+
+    pass
+
+
+class CapiscioTimeoutError(CapiscioSecurityError):
+    """Operation timed out."""
+
+    pass

capiscio_sdk/executor.py

@@ -0,0 +1,216 @@
+"""Security executor wrapper for A2A agents."""
+import logging
+from typing import Any, Dict, Optional, Callable
+from functools import wraps
+
+try:
+    from a2a.server.agent_execution import RequestContext
+except ImportError:
+    RequestContext = Any  # type: ignore[misc,assignment]
+
+from .config import SecurityConfig
+from .validators import MessageValidator, ProtocolValidator
+from .infrastructure import ValidationCache, RateLimiter
+from .types import ValidationResult
+from .errors import (
+    CapiscioValidationError,
+    CapiscioRateLimitError,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class CapiscioSecurityExecutor:
+    """
+    Security wrapper for A2A agent executors.
+    
+    Provides runtime validation, rate limiting, and security checks
+    for A2A agent interactions. Implements the AgentExecutor interface.
+    """
+
+    def __init__(
+        self,
+        delegate: Any,
+        config: Optional[SecurityConfig] = None,
+    ):
+        """
+        Initialize security executor.
+
+        Args:
+            delegate: The agent executor to wrap (must implement AgentExecutor interface)
+            config: Security configuration (defaults to production preset)
+        """
+        self.delegate = delegate
+        self.config = config or SecurityConfig.production()
+        
+        # Initialize components
+        self._message_validator = MessageValidator()
+        self._protocol_validator = ProtocolValidator()
+        
+        # Initialize infrastructure
+        self._cache: Optional[ValidationCache]
+        self._rate_limiter: Optional[RateLimiter]
+        
+        if self.config.upstream.cache_validation:
+            self._cache = ValidationCache(
+                max_size=1000,
+                ttl=self.config.upstream.cache_timeout,
+            )
+        else:
+            self._cache = None
+            
+        if self.config.downstream.enable_rate_limiting:
+            self._rate_limiter = RateLimiter(
+                requests_per_minute=self.config.downstream.rate_limit_requests_per_minute
+            )
+        else:
+            self._rate_limiter = None
+
+    async def execute(self, context: RequestContext, event_queue: Any) -> None:
+        """
+        Execute agent with security checks.
+
+        Args:
+            context: RequestContext with message and task information
+            event_queue: EventQueue for publishing events
+
+        Raises:
+            CapiscioValidationError: If validation fails in block mode
+            CapiscioRateLimitError: If rate limit exceeded in block mode
+        """
+        # Extract message for validation
+        message = context.message
+        if not message:
+            logger.warning("No message in context")
+            await self.delegate.execute(context, event_queue)
+            return
+        
+        # Convert message to dict for validation (our validators expect dict format)
+        message_dict = message.model_dump() if hasattr(message, 'model_dump') else {}
+        
+        # Extract identifier for rate limiting
+        identifier = message_dict.get("message_id") or message.message_id
+        
+        # Check rate limit
+        if self._rate_limiter and identifier:
+            try:
+                self._rate_limiter.consume(identifier)
+            except CapiscioRateLimitError as e:
+                if self.config.fail_mode == "block":
+                    raise
+                elif self.config.fail_mode == "monitor":
+                    logger.warning(f"Rate limit exceeded for {identifier}: {e}")
+                # Continue execution in log/monitor mode
+
+        # Validate message
+        if self.config.downstream.validate_schema:
+            validation_result = self._validate_message(message_dict)
+            
+            if not validation_result.success:
+                error = CapiscioValidationError(
+                    "Message validation failed", validation_result
+                )
+                
+                if self.config.fail_mode == "block":
+                    raise error
+                elif self.config.fail_mode == "monitor":
+                    logger.warning(f"Validation failed: {error.errors}")
+                elif self.config.fail_mode == "log":
+                    logger.info(f"Validation issues detected: {validation_result.issues}")
+
+        # Execute delegate
+        try:
+            await self.delegate.execute(context, event_queue)
+        except Exception as e:
+            if self.config.fail_mode != "log":
+                raise
+            logger.error(f"Delegate execution failed: {e}")
+            raise
+
+    async def cancel(self, context: RequestContext, event_queue: Any) -> None:
+        """
+        Cancel task with passthrough to delegate.
+
+        Args:
+            context: RequestContext with task to cancel
+            event_queue: EventQueue for publishing cancellation event
+        """
+        # Cancellation just passes through - no security checks needed
+        await self.delegate.cancel(context, event_queue)
+
+    def _validate_message(self, message: Dict[str, Any]) -> ValidationResult:
+        """Validate message with caching."""
+        # Try cache first
+        if self._cache:
+            message_id = message.get("id")
+            if message_id:
+                cached = self._cache.get(message_id)
+                if cached:
+                    logger.debug(f"Using cached validation for message {message_id}")
+                    return cached
+
+        # Validate
+        result = self._message_validator.validate(message)
+        
+        # Cache result
+        if self._cache and message.get("id"):
+            msg_id = message.get("id")
+            if isinstance(msg_id, str):
+                self._cache.set(msg_id, result)
+            
+        return result
+
+    def __getattr__(self, name: str) -> Any:
+        """Delegate attribute access to wrapped executor."""
+        return getattr(self.delegate, name)
+
+
+def secure(
+    agent: Any,
+    config: Optional[SecurityConfig] = None,
+) -> CapiscioSecurityExecutor:
+    """
+    Wrap an agent executor with security middleware (minimal pattern).
+
+    Args:
+        agent: Agent executor to wrap
+        config: Security configuration (defaults to production)
+
+    Returns:
+        Secured agent executor
+
+    Example:
+        ```python
+        agent = secure(MyAgentExecutor())
+        ```
+    """
+    return CapiscioSecurityExecutor(agent, config)
+
+
+def secure_agent(
+    config: Optional[SecurityConfig] = None,
+) -> Callable[[type], Callable[..., CapiscioSecurityExecutor]]:
+    """
+    Decorator to secure an agent executor class (decorator pattern).
+
+    Args:
+        config: Security configuration (defaults to production)
+
+    Returns:
+        Decorator function
+
+    Example:
+        ```python
+        @secure_agent(config=SecurityConfig.strict())
+        class MyAgent:
+            def execute(self, message):
+                # ... agent logic
+        ```
+    """
+    def decorator(cls: type) -> Callable[..., CapiscioSecurityExecutor]:
+        @wraps(cls)
+        def wrapper(*args: Any, **kwargs: Any) -> CapiscioSecurityExecutor:
+            instance = cls(*args, **kwargs)
+            return CapiscioSecurityExecutor(instance, config)
+        return wrapper
+    return decorator

capiscio_sdk/infrastructure/__init__.py

@@ -0,0 +1,5 @@
+"""Infrastructure components."""
+from .cache import ValidationCache
+from .rate_limiter import RateLimiter
+
+__all__ = ["ValidationCache", "RateLimiter"]

capiscio_sdk/infrastructure/cache.py

@@ -0,0 +1,73 @@
+"""Validation result caching."""
+import time
+from typing import Optional
+from cachetools import TTLCache
+from ..types import ValidationResult, CacheEntry
+
+
+class ValidationCache:
+    """In-memory cache for validation results with TTL."""
+
+    def __init__(self, max_size: int = 1000, ttl: int = 300):
+        """
+        Initialize validation cache.
+
+        Args:
+            max_size: Maximum number of entries to cache
+            ttl: Time-to-live in seconds (default 5 minutes)
+        """
+        self._cache: TTLCache[str, CacheEntry] = TTLCache(maxsize=max_size, ttl=ttl)
+        self._ttl = ttl
+
+    def get(self, key: str) -> Optional[ValidationResult]:
+        """
+        Get validation result from cache.
+
+        Args:
+            key: Cache key (e.g., agent URL or message ID)
+
+        Returns:
+            Cached ValidationResult or None if not found
+        """
+        entry = self._cache.get(key)
+        if entry is None:
+            return None
+
+        return entry.result
+
+    def set(self, key: str, result: ValidationResult) -> None:
+        """
+        Store validation result in cache.
+
+        Args:
+            key: Cache key
+            result: ValidationResult to cache
+        """
+        entry = CacheEntry(
+            result=result,
+            cached_at=time.time(),
+            ttl=self._ttl,
+        )
+        self._cache[key] = entry
+
+    def invalidate(self, key: str) -> None:
+        """
+        Remove entry from cache.
+
+        Args:
+            key: Cache key to invalidate
+        """
+        self._cache.pop(key, None)
+
+    def clear(self) -> None:
+        """Clear all entries from cache."""
+        self._cache.clear()
+
+    def size(self) -> int:
+        """
+        Get current cache size.
+
+        Returns:
+            Number of entries in cache
+        """
+        return len(self._cache)

capiscio_sdk/infrastructure/rate_limiter.py

@@ -0,0 +1,110 @@
+"""Rate limiting implementation."""
+import time
+from typing import Dict
+from ..types import RateLimitInfo
+from ..errors import CapiscioRateLimitError
+
+
+class RateLimiter:
+    """Token bucket rate limiter."""
+
+    def __init__(self, requests_per_minute: int = 60):
+        """
+        Initialize rate limiter.
+
+        Args:
+            requests_per_minute: Maximum requests allowed per minute
+        """
+        self._requests_per_minute = requests_per_minute
+        self._buckets: Dict[str, Dict[str, float]] = {}
+        self._bucket_capacity = requests_per_minute
+        self._refill_rate = requests_per_minute / 60.0  # tokens per second
+
+    def check(self, identifier: str) -> RateLimitInfo:
+        """
+        Check rate limit for identifier without consuming tokens.
+
+        Args:
+            identifier: Unique identifier (e.g., agent URL or IP address)
+
+        Returns:
+            RateLimitInfo with current rate limit status
+        """
+        now = time.time()
+        bucket = self._get_or_create_bucket(identifier, now)
+
+        # Calculate current tokens (don't actually refill yet)
+        time_elapsed = now - bucket["last_refill"]
+        tokens_to_add = time_elapsed * self._refill_rate
+        current_tokens = min(
+            self._bucket_capacity, bucket["tokens"] + tokens_to_add
+        )
+
+        # Calculate reset time (when bucket will be full again)
+        tokens_needed = self._bucket_capacity - current_tokens
+        seconds_to_full = tokens_needed / self._refill_rate if tokens_needed > 0 else 0
+        reset_at = now + seconds_to_full
+
+        return RateLimitInfo(
+            requests_allowed=self._requests_per_minute,
+            requests_used=int(self._bucket_capacity - current_tokens),
+            reset_at=reset_at,
+        )
+
+    def consume(self, identifier: str, tokens: float = 1.0) -> None:
+        """
+        Consume tokens from bucket.
+
+        Args:
+            identifier: Unique identifier
+            tokens: Number of tokens to consume (default 1.0)
+
+        Raises:
+            CapiscioRateLimitError: If rate limit exceeded
+        """
+        now = time.time()
+        bucket = self._get_or_create_bucket(identifier, now)
+
+        # Refill tokens first
+        time_elapsed = now - bucket["last_refill"]
+        tokens_to_add = time_elapsed * self._refill_rate
+        bucket["tokens"] = min(
+            self._bucket_capacity, bucket["tokens"] + tokens_to_add
+        )
+        bucket["last_refill"] = now
+
+        # Check if enough tokens available
+        if bucket["tokens"] < tokens:
+            # Calculate retry after time
+            tokens_needed = tokens - bucket["tokens"]
+            retry_after = tokens_needed / self._refill_rate
+
+            raise CapiscioRateLimitError(
+                f"Rate limit exceeded for {identifier}",
+                retry_after_seconds=int(retry_after) + 1,
+            )
+
+        # Consume tokens
+        bucket["tokens"] -= tokens
+
+    def reset(self, identifier: str) -> None:
+        """
+        Reset rate limit for identifier.
+
+        Args:
+            identifier: Unique identifier to reset
+        """
+        self._buckets.pop(identifier, None)
+
+    def clear(self) -> None:
+        """Clear all rate limit buckets."""
+        self._buckets.clear()
+
+    def _get_or_create_bucket(self, identifier: str, now: float) -> Dict[str, float]:
+        """Get or create bucket for identifier."""
+        if identifier not in self._buckets:
+            self._buckets[identifier] = {
+                "tokens": float(self._bucket_capacity),
+                "last_refill": now,
+            }
+        return self._buckets[identifier]

capiscio_sdk/scoring/__init__.py

@@ -0,0 +1,42 @@
+"""Multi-dimensional scoring system for A2A validation.
+
+This module provides three independent scoring dimensions:
+- Compliance: Protocol specification adherence (0-100)
+- Trust: Security and authenticity signals (0-100)  
+- Availability: Operational readiness (0-100)
+
+Each dimension has its own rating scale and breakdown structure,
+allowing users to make nuanced decisions based on their priorities.
+"""
+
+from .types import (
+    ComplianceScore,
+    TrustScore,
+    AvailabilityScore,
+    ComplianceBreakdown,
+    TrustBreakdown,
+    AvailabilityBreakdown,
+    ComplianceRating,
+    TrustRating,
+    AvailabilityRating,
+    ScoringContext,
+)
+from .compliance import ComplianceScorer
+from .trust import TrustScorer
+from .availability import AvailabilityScorer
+
+__all__ = [
+    "ComplianceScore",
+    "TrustScore",
+    "AvailabilityScore",
+    "ComplianceBreakdown",
+    "TrustBreakdown",
+    "AvailabilityBreakdown",
+    "ComplianceRating",
+    "TrustRating",
+    "AvailabilityRating",
+    "ScoringContext",
+    "ComplianceScorer",
+    "TrustScorer",
+    "AvailabilityScorer",
+]