capiscio-sdk 0.2.0__py3-none-any.whl

capiscio_sdk/validators/semver.py

@@ -0,0 +1,202 @@
+"""Semantic version validation and comparison."""
+import re
+from typing import Optional, Tuple
+
+from ..types import ValidationResult, ValidationIssue, ValidationSeverity, create_simple_validation_result
+
+
+class SemverValidator:
+    """Validates and compares semantic versions."""
+
+    # Semver regex pattern (simplified but covers most cases)
+    SEMVER_PATTERN = re.compile(
+        r'^(?P<major>0|[1-9]\d*)\.(?P<minor>0|[1-9]\d*)\.(?P<patch>0|[1-9]\d*)'
+        r'(?:-(?P<prerelease>(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)'
+        r'(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?'
+        r'(?:\+(?P<buildmetadata>[0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$'
+    )
+
+    def validate_version(self, version: str, field_name: str = "version") -> ValidationResult:
+        """
+        Validate semantic version format.
+
+        Args:
+            version: Version string to validate
+            field_name: Name of the field being validated
+
+        Returns:
+            ValidationResult
+        """
+        issues = []
+        score = 100
+
+        if not version:
+            issues.append(
+                ValidationIssue(
+                    severity=ValidationSeverity.ERROR,
+                    code="MISSING_VERSION",
+                    message=f"{field_name}: Version is required",
+                    path=field_name,
+                )
+            )
+            return create_simple_validation_result(
+                success=False,
+                issues=issues,
+                simple_score=0,
+                dimension="compliance"
+            )
+
+        if not isinstance(version, str):
+            issues.append(
+                ValidationIssue(
+                    severity=ValidationSeverity.ERROR,
+                    code="INVALID_VERSION_TYPE",
+                    message=f"{field_name}: Version must be a string",
+                    path=field_name,
+                )
+            )
+            return create_simple_validation_result(
+                success=False,
+                issues=issues,
+                simple_score=0,
+                dimension="compliance"
+            )
+
+        # Validate semver format
+        match = self.SEMVER_PATTERN.match(version)
+        if not match:
+            issues.append(
+                ValidationIssue(
+                    severity=ValidationSeverity.ERROR,
+                    code="INVALID_SEMVER_FORMAT",
+                    message=f"{field_name}: Version must follow semantic versioning (e.g., 1.0.0)",
+                    path=field_name,
+                    details={"version": version},
+                )
+            )
+            return create_simple_validation_result(
+                success=False,
+                issues=issues,
+                simple_score=0,
+                dimension="compliance"
+            )
+
+        # Extract version parts
+        major = int(match.group('major'))
+        minor = int(match.group('minor'))
+        patch = int(match.group('patch'))
+        prerelease = match.group('prerelease')
+
+        # Warn about pre-release versions in production
+        if prerelease:
+            issues.append(
+                ValidationIssue(
+                    severity=ValidationSeverity.WARNING,
+                    code="PRERELEASE_VERSION",
+                    message=f"{field_name}: Pre-release version detected ({version})",
+                    path=field_name,
+                    details={"prerelease": prerelease},
+                )
+            )
+            score -= 10
+
+        # Warn about 0.x versions
+        if major == 0:
+            issues.append(
+                ValidationIssue(
+                    severity=ValidationSeverity.INFO,
+                    code="DEVELOPMENT_VERSION",
+                    message=f"{field_name}: Development version (0.x.x) - not stable",
+                    path=field_name,
+                )
+            )
+
+        result = create_simple_validation_result(
+            success=True,
+            issues=issues,
+            simple_score=score,
+            dimension="compliance"
+        )
+        result.metadata = {
+            "major": major,
+            "minor": minor,
+            "patch": patch,
+            "prerelease": prerelease,
+        }
+        return result
+
+    def parse_version(self, version: str) -> Optional[Tuple[int, int, int]]:
+        """
+        Parse semantic version into (major, minor, patch) tuple.
+
+        Args:
+            version: Version string to parse
+
+        Returns:
+            Tuple of (major, minor, patch) or None if invalid
+        """
+        match = self.SEMVER_PATTERN.match(version)
+        if not match:
+            return None
+
+        return (
+            int(match.group('major')),
+            int(match.group('minor')),
+            int(match.group('patch'))
+        )
+
+    def compare_versions(self, version1: str, version2: str) -> int:
+        """
+        Compare two semantic versions.
+
+        Args:
+            version1: First version
+            version2: Second version
+
+        Returns:
+            -1 if version1 < version2
+             0 if version1 == version2
+             1 if version1 > version2
+        """
+        v1 = self.parse_version(version1)
+        v2 = self.parse_version(version2)
+
+        if v1 is None or v2 is None:
+            raise ValueError(f"Invalid version format: {version1} or {version2}")
+
+        # Compare major, minor, patch
+        if v1[0] != v2[0]:
+            return 1 if v1[0] > v2[0] else -1
+        if v1[1] != v2[1]:
+            return 1 if v1[1] > v2[1] else -1
+        if v1[2] != v2[2]:
+            return 1 if v1[2] > v2[2] else -1
+
+        return 0
+
+    def is_compatible(self, version: str, required: str) -> bool:
+        """
+        Check if version is compatible with required version.
+
+        Compatible means version >= required for same major version.
+
+        Args:
+            version: Actual version
+            required: Required minimum version
+
+        Returns:
+            True if compatible
+        """
+        try:
+            comparison = self.compare_versions(version, required)
+            v1 = self.parse_version(version)
+            v2 = self.parse_version(required)
+
+            # Must be same major version
+            if v1 and v2 and v1[0] != v2[0]:
+                return False
+
+            # Must be greater than or equal
+            return comparison >= 0
+        except ValueError:
+            return False

capiscio_sdk/validators/signature.py

@@ -0,0 +1,234 @@
+"""Signature verification for A2A protocol."""
+import logging
+from typing import Any, Dict, List, Optional
+
+from ..types import ValidationResult, ValidationIssue, ValidationSeverity, create_simple_validation_result
+
+logger = logging.getLogger(__name__)
+
+
+class SignatureValidator:
+    """Validates JWS signatures on A2A messages and agent cards."""
+
+    def __init__(self) -> None:
+        """Initialize signature validator."""
+        self._crypto_available = self._check_crypto_availability()
+
+    def _check_crypto_availability(self) -> bool:
+        """Check if cryptography library is available."""
+        try:
+            import jwt  # PyJWT for JWS validation  # noqa: F401
+            return True
+        except ImportError:
+            logger.warning(
+                "PyJWT not installed. Signature verification will be limited. "
+                "Install with: pip install pyjwt cryptography"
+            )
+            return False
+
+    def validate_signature(
+        self, 
+        payload: Dict[str, Any], 
+        signature: str,
+        public_key: Optional[str] = None,
+    ) -> ValidationResult:
+        """
+        Validate a JWS signature.
+
+        Args:
+            payload: The data that was signed
+            signature: The JWS signature to verify
+            public_key: Optional public key for verification
+
+        Returns:
+            ValidationResult with signature validation results
+        """
+        issues: List[ValidationIssue] = []
+        score = 100
+
+        if not self._crypto_available:
+            issues.append(
+                ValidationIssue(
+                    severity=ValidationSeverity.WARNING,
+                    code="CRYPTO_NOT_AVAILABLE",
+                    message="Cryptography library not available for signature verification",
+                    path="signatures",
+                )
+            )
+            return create_simple_validation_result(
+                success=False,
+                issues=issues,
+                simple_score=0,
+                dimension="trust"
+            )
+
+        # Check signature format
+        if not signature or not isinstance(signature, str):
+            issues.append(
+                ValidationIssue(
+                    severity=ValidationSeverity.ERROR,
+                    code="INVALID_SIGNATURE_FORMAT",
+                    message="Signature must be a non-empty string",
+                    path="signatures",
+                )
+            )
+            return create_simple_validation_result(
+                success=False,
+                issues=issues,
+                simple_score=0,
+                dimension="trust"
+            )
+
+        # JWS signatures should have 3 parts separated by dots
+        parts = signature.split('.')
+        if len(parts) != 3:
+            issues.append(
+                ValidationIssue(
+                    severity=ValidationSeverity.ERROR,
+                    code="INVALID_JWS_FORMAT",
+                    message=f"JWS signature must have 3 parts (header.payload.signature), found {len(parts)}",
+                    path="signatures",
+                )
+            )
+            score -= 50
+
+        # Attempt verification if public key provided
+        if public_key:
+            try:
+                import jwt
+                
+                # Verify signature
+                jwt.decode(
+                    signature,
+                    public_key,
+                    algorithms=['RS256', 'ES256', 'PS256'],
+                    options={"verify_signature": True}
+                )
+                
+                # Signature is valid
+                logger.debug("Signature verified successfully")
+                
+            except jwt.InvalidSignatureError:
+                issues.append(
+                    ValidationIssue(
+                        severity=ValidationSeverity.ERROR,
+                        code="SIGNATURE_VERIFICATION_FAILED",
+                        message="Signature verification failed - signature is invalid",
+                        path="signatures",
+                    )
+                )
+                score = 0
+                
+            except jwt.ExpiredSignatureError:
+                issues.append(
+                    ValidationIssue(
+                        severity=ValidationSeverity.ERROR,
+                        code="SIGNATURE_EXPIRED",
+                        message="Signature has expired",
+                        path="signatures",
+                    )
+                )
+                score -= 40
+                
+            except jwt.DecodeError as e:
+                issues.append(
+                    ValidationIssue(
+                        severity=ValidationSeverity.ERROR,
+                        code="SIGNATURE_DECODE_ERROR",
+                        message=f"Failed to decode signature: {str(e)}",
+                        path="signatures",
+                    )
+                )
+                score -= 30
+                
+            except Exception as e:
+                issues.append(
+                    ValidationIssue(
+                        severity=ValidationSeverity.ERROR,
+                        code="SIGNATURE_VERIFICATION_ERROR",
+                        message=f"Signature verification error: {str(e)}",
+                        path="signatures",
+                    )
+                )
+                score = 0
+        else:
+            # No public key provided - can't verify, just validate format
+            issues.append(
+                ValidationIssue(
+                    severity=ValidationSeverity.WARNING,
+                    code="NO_PUBLIC_KEY",
+                    message="Signature format valid but no public key provided for verification",
+                    path="signatures",
+                )
+            )
+            score = 70  # Format is OK but not verified
+
+        # Ensure score doesn't go negative
+        score = max(0, score)
+
+        return create_simple_validation_result(
+            success=score >= 60 and not any(i.severity == ValidationSeverity.ERROR for i in issues),
+            issues=issues,
+            simple_score=score,
+            dimension="trust"
+        )
+
+    def validate_signatures(
+        self,
+        payload: Dict[str, Any],
+        signatures: List[str],
+    ) -> ValidationResult:
+        """
+        Validate multiple JWS signatures.
+
+        Args:
+            payload: The data that was signed
+            signatures: List of JWS signatures to verify
+
+        Returns:
+            Aggregated ValidationResult
+        """
+        all_issues: List[ValidationIssue] = []
+        total_score = 0
+        valid_count = 0
+
+        if not signatures or len(signatures) == 0:
+            all_issues.append(
+                ValidationIssue(
+                    severity=ValidationSeverity.WARNING,
+                    code="NO_SIGNATURES",
+                    message="No signatures found to validate",
+                    path="signatures",
+                )
+            )
+            return create_simple_validation_result(
+                success=False,
+                issues=all_issues,
+                simple_score=50,
+                dimension="trust"
+            )
+
+        for i, sig in enumerate(signatures):
+            result = self.validate_signature(payload, sig)
+            all_issues.extend(result.issues)
+            # Use trust.total since signature validation is trust-related
+            total_score += result.trust.total if result.trust else 0
+            
+            if result.success:
+                valid_count += 1
+
+        # Calculate average score
+        avg_score = total_score // len(signatures) if signatures else 0
+
+        result = create_simple_validation_result(
+            success=valid_count > 0,
+            issues=all_issues,
+            simple_score=avg_score,
+            dimension="trust"
+        )
+        result.metadata = {
+            "total_signatures": len(signatures),
+            "valid_signatures": valid_count,
+            "failed_signatures": len(signatures) - valid_count,
+        }
+        return result

capiscio_sdk/validators/url_security.py

@@ -0,0 +1,269 @@
+"""URL security validation for A2A protocol."""
+import re
+from typing import TYPE_CHECKING, Any, List, Optional
+from urllib.parse import urlparse
+
+from ..types import ValidationResult, ValidationIssue, ValidationSeverity, create_simple_validation_result
+
+if TYPE_CHECKING:
+    from .certificate import CertificateValidator
+
+
+class URLSecurityValidator:
+    """Validates URL security requirements per A2A specification."""
+
+    # Private IPv4 ranges: 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16
+    # Link-local: 169.254.0.0/16
+    PRIVATE_IPV4_PATTERN = re.compile(
+        r'^(10\.|172\.(1[6-9]|2[0-9]|3[01])\.|192\.168\.|169\.254\.)'
+    )
+    
+    # Private IPv6 ranges: fc00::/7, fe80::/10
+    PRIVATE_IPV6_PATTERN = re.compile(r'^(fc|fd|fe[89ab])', re.IGNORECASE)
+    
+    LOCALHOST_NAMES = {'localhost', '127.0.0.1', '::1', '0.0.0.0', '::'}  # nosec B104 - validation constants, not binding
+
+    def __init__(self, certificate_validator: Optional['CertificateValidator'] = None):
+        """Initialize URL security validator.
+        
+        Args:
+            certificate_validator: Optional certificate validator for TLS validation
+        """
+        self._certificate_validator = certificate_validator
+
+    def validate_url(
+        self,
+        url: str,
+        field_name: str = "url",
+        require_https: bool = True
+    ) -> ValidationResult:
+        """
+        Validate URL for security compliance (synchronous version).
+
+        Args:
+            url: URL to validate
+            field_name: Name of the field being validated (for error messages)
+            require_https: Whether HTTPS is required (default: True per A2A spec)
+
+        Returns:
+            ValidationResult with security validation results
+        """
+        issues: List[ValidationIssue] = []
+        score = 100
+
+        # Parse URL
+        try:
+            parsed = urlparse(url)
+        except Exception as e:
+            issues.append(
+                ValidationIssue(
+                    severity=ValidationSeverity.ERROR,
+                    code="INVALID_URL_FORMAT",
+                    message=f"{field_name}: Invalid URL format - {str(e)}",
+                    path=field_name,
+                )
+            )
+            return create_simple_validation_result(
+                success=False,
+                issues=issues,
+                simple_score=0,
+                dimension="trust"
+            )
+
+        # Continue with existing validation logic...
+        return self._validate_url_internal(parsed, url, field_name, require_https, issues, score)
+
+    async def validate_url_with_certificate(
+        self,
+        url: str,
+        field_name: str = "url",
+        require_https: bool = True
+    ) -> ValidationResult:
+        """
+        Validate URL for security compliance including certificate validation (async version).
+
+        Args:
+            url: URL to validate
+            field_name: Name of the field being validated (for error messages)
+            require_https: Whether HTTPS is required (default: True per A2A spec)
+
+        Returns:
+            ValidationResult with security and certificate validation results
+        """
+        issues: List[ValidationIssue] = []
+        score = 100
+
+        # Parse URL
+        try:
+            parsed = urlparse(url)
+        except Exception as e:
+            issues.append(
+                ValidationIssue(
+                    severity=ValidationSeverity.ERROR,
+                    code="INVALID_URL_FORMAT",
+                    message=f"{field_name}: Invalid URL format - {str(e)}",
+                    path=field_name,
+                )
+            )
+            return create_simple_validation_result(
+                success=False,
+                issues=issues,
+                simple_score=0,
+                dimension="trust"
+            )
+
+        # First do standard URL validation
+        result = self._validate_url_internal(parsed, url, field_name, require_https, issues, score)
+        
+        # Then optionally verify TLS certificate
+        if self._certificate_validator and parsed.scheme == "https":
+            cert_result = await self._certificate_validator.validate_url_certificate(url)
+            result.issues.extend(cert_result.issues)
+            # Reduce trust score based on certificate issues
+            if not cert_result.success and cert_result.trust:
+                # Merge certificate trust issues into result
+                if result.trust and result.trust.total:
+                    # Certificate issues reduce trust score
+                    min(result.trust.total, cert_result.trust.total or 0)
+                    # Update success based on combined issues
+                    result.success = not any(i.severity == ValidationSeverity.ERROR for i in result.issues)
+        
+        return result
+
+    def _validate_url_internal(
+        self,
+        parsed: Any,
+        url: str,
+        field_name: str,
+        require_https: bool,
+        issues: List[ValidationIssue],
+        score: int
+    ) -> ValidationResult:
+        """Internal URL validation logic."""
+        
+        # Check scheme
+        if not parsed.scheme:
+            issues.append(
+                ValidationIssue(
+                    severity=ValidationSeverity.ERROR,
+                    code="MISSING_URL_SCHEME",
+                    message=f"{field_name}: URL must include scheme (https://)",
+                    path=field_name,
+                )
+            )
+            score -= 30
+
+        # HTTPS enforcement (A2A specification §5.3)
+        elif require_https and parsed.scheme != 'https':
+            issues.append(
+                ValidationIssue(
+                    severity=ValidationSeverity.ERROR,
+                    code="HTTPS_REQUIRED",
+                    message=f"{field_name}: Must use HTTPS (HTTP not allowed per A2A specification)",
+                    path=field_name,
+                )
+            )
+            score -= 40
+
+        # Check for hostname
+        if not parsed.hostname:
+            issues.append(
+                ValidationIssue(
+                    severity=ValidationSeverity.ERROR,
+                    code="MISSING_HOSTNAME",
+                    message=f"{field_name}: URL must include hostname",
+                    path=field_name,
+                )
+            )
+            score -= 30
+            
+        else:
+            # SSRF Protection: Check for localhost
+            if parsed.hostname.lower() in self.LOCALHOST_NAMES:
+                issues.append(
+                    ValidationIssue(
+                        severity=ValidationSeverity.ERROR,
+                        code="LOCALHOST_NOT_ALLOWED",
+                        message=f"{field_name}: Localhost addresses not allowed (SSRF protection)",
+                        path=field_name,
+                        details={"hostname": parsed.hostname},
+                    )
+                )
+                score -= 50
+
+            # SSRF Protection: Check for private IP addresses
+            elif self._is_private_ip(parsed.hostname):
+                issues.append(
+                    ValidationIssue(
+                        severity=ValidationSeverity.ERROR,
+                        code="PRIVATE_IP_NOT_ALLOWED",
+                        message=f"{field_name}: Private IP addresses not allowed (SSRF protection)",
+                        path=field_name,
+                        details={"hostname": parsed.hostname},
+                    )
+                )
+                score -= 50
+
+            # Check for IP address in hostname (warning)
+            elif self._is_ip_address(parsed.hostname):
+                issues.append(
+                    ValidationIssue(
+                        severity=ValidationSeverity.WARNING,
+                        code="IP_ADDRESS_HOSTNAME",
+                        message=f"{field_name}: Using IP address instead of domain name",
+                        path=field_name,
+                        details={"hostname": parsed.hostname},
+                    )
+                )
+                score -= 10
+
+        # Check for suspicious ports (if specified)
+        if parsed.port:
+            # Allow common HTTPS ports
+            allowed_ports = {443, 8443}
+            if require_https and parsed.port not in allowed_ports:
+                issues.append(
+                    ValidationIssue(
+                        severity=ValidationSeverity.WARNING,
+                        code="NON_STANDARD_PORT",
+                        message=f"{field_name}: Non-standard HTTPS port {parsed.port}",
+                        path=field_name,
+                        details={"port": parsed.port},
+                    )
+                )
+                score -= 5
+
+        # Ensure score doesn't go negative
+        score = max(0, score)
+
+        return create_simple_validation_result(
+            success=score >= 60 and not any(i.severity == ValidationSeverity.ERROR for i in issues),
+            issues=issues,
+            simple_score=score,
+            dimension="trust"
+        )
+
+    def _is_private_ip(self, hostname: str) -> bool:
+        """Check if hostname is a private IP address."""
+        # IPv4 private ranges
+        if self.PRIVATE_IPV4_PATTERN.match(hostname):
+            return True
+        
+        # IPv6 private ranges
+        if self.PRIVATE_IPV6_PATTERN.match(hostname):
+            return True
+        
+        return False
+
+    def _is_ip_address(self, hostname: str) -> bool:
+        """Check if hostname is an IP address (IPv4 or IPv6)."""
+        # IPv4 pattern
+        ipv4_pattern = re.compile(r'^\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}$')
+        if ipv4_pattern.match(hostname):
+            return True
+        
+        # IPv6 pattern (simplified)
+        if ':' in hostname:
+            return True
+        
+        return False