fast-clean-architecture 1.0.0__py3-none-any.whl → 1.1.0__py3-none-any.whl

fast_clean_architecture/protocols.py

@@ -0,0 +1,406 @@
+"""Protocol definitions for enhanced type safety in Fast Clean Architecture.
+
+This module provides protocol-based interfaces that enable better type checking,
+modular design, and enhanced security through type constraints.
+"""
+
+from abc import abstractmethod
+from pathlib import Path
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Dict,
+    Generic,
+    List,
+    Optional,
+    Protocol,
+    TypeVar,
+    Union,
+    runtime_checkable,
+)
+
+if TYPE_CHECKING:
+    from .generators.validation_config import ValidationMetrics
+
+from .config import Config
+from .exceptions import ComponentError, SecurityError, ValidationError
+
+# Type variables for generic constraints
+T = TypeVar("T", bound=Union[str, Path])
+ComponentType = TypeVar("ComponentType", bound=str)
+T_contra = TypeVar("T_contra", contravariant=True)
+
+
+@runtime_checkable
+class ComponentGeneratorProtocol(Protocol):
+    """Protocol for component generators with type safety guarantees.
+
+    This protocol ensures that all component generators implement
+    the required methods with proper type annotations and error handling.
+    """
+
+    # Required attributes
+    config: "Config"
+    template_validator: "TemplateValidatorProtocol"
+    path_handler: "SecurePathHandler[Union[str, Path]]"
+
+    def create_component(
+        self,
+        base_path: Path,
+        system_name: str,
+        module_name: str,
+        layer: str,
+        component_type: str,
+        component_name: str,
+        dry_run: bool = False,
+        force: bool = False,
+    ) -> Path:
+        """Create a component with validated inputs and secure file operations.
+
+        Args:
+            base_path: Base directory for component creation
+            system_name: Name of the system (validated)
+            module_name: Name of the module (validated)
+            layer: Architecture layer (domain, application, etc.)
+            component_type: Type of component (entity, service, etc.)
+            component_name: Name of the component (validated)
+            dry_run: If True, only simulate the operation
+            force: If True, overwrite existing files
+
+        Returns:
+            Path to the created component file
+
+        Raises:
+            ValidationError: If inputs are invalid
+            ComponentError: If component creation fails
+            SecurityError: If security constraints are violated
+        """
+        ...
+
+    def validate_component(self, component: Dict[str, Any]) -> bool:
+        """Validate component configuration and structure.
+
+        Args:
+            component: Component configuration dictionary
+
+        Returns:
+            True if component is valid
+
+        Raises:
+            ValidationError: If component is invalid
+        """
+        ...
+
+    def create_multiple_components(
+        self,
+        base_path: Path,
+        system_name: str,
+        module_name: str,
+        components_spec: Dict[str, Dict[str, List[str]]],
+        dry_run: bool = False,
+        force: bool = False,
+    ) -> List[Path]:
+        """Create multiple components from specification.
+
+        Args:
+            base_path: Base directory for component creation
+            system_name: Name of the system (validated)
+            module_name: Name of the module (validated)
+            components_spec: Dict like {
+                "domain": {"entities": ["user", "order"], "repositories": ["user"]},
+                "application": {"services": ["user_service"]}
+            }
+            dry_run: If True, only simulate the operation
+            force: If True, overwrite existing files
+
+        Returns:
+            List of paths to created component files
+
+        Raises:
+            ValidationError: If inputs are invalid
+            ComponentError: If component creation fails
+            SecurityError: If security constraints are violated
+        """
+        ...
+
+
+@runtime_checkable
+class SecurePathHandlerProtocol(Protocol, Generic[T]):
+    """Protocol for secure path handling with generic type constraints.
+
+    This protocol ensures type-safe path operations with security validation.
+    """
+
+    def process(self, path: T) -> T:
+        """Process a path with security validation.
+
+        Args:
+            path: Input path (str or Path)
+
+        Returns:
+            Processed and validated path of the same type
+
+        Raises:
+            SecurityError: If path contains security violations
+            ValidationError: If path is invalid
+        """
+        ...
+
+    def validate_path_security(self, path: T) -> bool:
+        """Validate path for security constraints.
+
+        Args:
+            path: Path to validate
+
+        Returns:
+            True if path is secure
+        """
+        ...
+
+
+@runtime_checkable
+class TemplateValidatorProtocol(Protocol):
+    """Protocol for template validation with security constraints."""
+
+    def validate(
+        self, template_source: str, template_vars: Dict[str, Any]
+    ) -> "ValidationMetrics":
+        """Validate template source and variables.
+
+        Args:
+            template_source: Template source code
+            template_vars: Template variables
+
+        Returns:
+            ValidationMetrics: Metrics from the validation process
+
+        Raises:
+            TemplateError: If template is invalid or insecure
+        """
+        ...
+
+    def sanitize_variables(self, variables: Dict[str, Any]) -> Dict[str, Any]:
+        """Sanitize template variables for security.
+
+        Args:
+            variables: Raw template variables
+
+        Returns:
+            Sanitized variables
+        """
+        ...
+
+
+@runtime_checkable
+class ValidationStrategyProtocol(Protocol, Generic[T_contra]):
+    """Protocol for validation strategies with generic type support."""
+
+    def validate(self, value: T_contra) -> object:
+        """Validate a value according to strategy rules.
+
+        Args:
+            value: Value to validate
+
+        Returns:
+            Validation result
+        """
+        ...
+
+    def get_error_message(self, value: T_contra) -> str:
+        """Get descriptive error message for validation failure.
+
+        Args:
+            value: Invalid value
+
+        Returns:
+            Error message
+        """
+        ...
+
+
+class SecurePathHandler(Generic[T]):
+    """Concrete implementation of secure path handling with generic type constraints.
+
+    This class provides type-safe path operations with security validation,
+    supporting both string and Path types while maintaining type consistency.
+    """
+
+    def __init__(
+        self,
+        max_path_length: int = 4096,
+        allowed_extensions: Optional[List[str]] = None,
+    ):
+        """Initialize secure path handler.
+
+        Args:
+            max_path_length: Maximum allowed path length
+            allowed_extensions: List of allowed file extensions (None for no restriction)
+        """
+        self.max_path_length = max_path_length
+        self.allowed_extensions = allowed_extensions or []
+
+        # Security patterns to detect
+        self._dangerous_patterns = [
+            r"\.\.",  # Path traversal
+            r'[<>:"|?*]',  # Invalid filename characters
+            r"^(CON|PRN|AUX|NUL|COM[1-9]|LPT[1-9])$",  # Windows reserved names
+            r"\x00",  # Null bytes
+        ]
+
+    def process(self, path: T) -> T:
+        """Process a path with comprehensive security validation.
+
+        Args:
+            path: Input path (str or Path)
+
+        Returns:
+            Processed and validated path of the same type
+
+        Raises:
+            SecurityError: If path contains security violations
+            ValidationError: If path is invalid
+        """
+        # Convert to string for validation
+        path_str = str(path)
+
+        # Validate path security
+        if not self.validate_path_security(path):
+            from .exceptions import SecurityError
+
+            raise SecurityError(
+                f"Path security validation failed: {path_str}",
+                security_check="path_traversal_prevention",
+            )
+
+        # Validate path length
+        if len(path_str) > self.max_path_length:
+            raise ValidationError(
+                f"Path too long: {len(path_str)} > {self.max_path_length}"
+            )
+
+        # Validate file extension if specified
+        if self.allowed_extensions:
+            path_obj = Path(path_str)
+            if path_obj.suffix and path_obj.suffix not in self.allowed_extensions:
+                raise ValidationError(f"File extension not allowed: {path_obj.suffix}")
+
+        # Return same type as input
+        if isinstance(path, Path):
+            return Path(path_str)  # type: ignore
+        return path_str  # type: ignore
+
+    def validate_path_security(self, path: T) -> bool:
+        """Validate path for security constraints.
+
+        Args:
+            path: Path to validate
+
+        Returns:
+            True if path is secure
+        """
+        import re
+
+        path_str = str(path)
+
+        # Check for dangerous patterns
+        for pattern in self._dangerous_patterns:
+            if re.search(pattern, path_str, re.IGNORECASE):
+                return False
+
+        # Additional security checks
+        try:
+            # Resolve path to detect traversal attempts
+            resolved = Path(path_str).resolve()
+
+            # Check if resolved path escapes intended directory
+            # This is a basic check - more sophisticated logic may be needed
+            if ".." in str(resolved):
+                return False
+
+        except (OSError, ValueError):
+            return False
+
+        return True
+
+
+class ComponentValidationStrategy(Generic[ComponentType]):
+    """Generic validation strategy for different component types.
+
+    This class provides type-safe validation for various component types
+    while maintaining consistency across the validation process.
+    """
+
+    def __init__(self, component_type: ComponentType, validation_rules: Dict[str, Any]):
+        """Initialize validation strategy.
+
+        Args:
+            component_type: Type of component to validate
+            validation_rules: Rules specific to this component type
+        """
+        self.component_type = component_type
+        self.validation_rules = validation_rules
+
+    def validate(self, component_data: Dict[str, Any]) -> bool:
+        """Validate component data according to type-specific rules.
+
+        Args:
+            component_data: Component configuration data
+
+        Returns:
+            True if component is valid
+
+        Raises:
+            ValidationError: If component is invalid
+        """
+        # Basic validation
+        if not isinstance(component_data, dict):
+            raise ValidationError(
+                f"Component data must be a dictionary, got {type(component_data)}"
+            )
+
+        # Check required fields
+        required_fields = self.validation_rules.get("required_fields", [])
+        for field in required_fields:
+            if field not in component_data:
+                raise ValidationError(
+                    f"Missing required field '{field}' for {self.component_type}"
+                )
+
+        # Validate field types
+        field_types = self.validation_rules.get("field_types", {})
+        for field, expected_type in field_types.items():
+            if field in component_data:
+                if not isinstance(component_data[field], expected_type):
+                    raise ValidationError(
+                        f"Field '{field}' must be of type {expected_type.__name__}, "
+                        f"got {type(component_data[field]).__name__}"
+                    )
+
+        # Validate component name for security if present
+        if "name" in component_data:
+            from fast_clean_architecture.utils import validate_name
+
+            try:
+                validate_name(component_data["name"])
+            except (ValueError, TypeError) as e:
+                raise ValidationError(f"Invalid component name: {e}")
+            except SecurityError:
+                # Re-raise SecurityError as-is for proper handling
+                raise
+
+        return True
+
+    def get_error_message(self, component_data: Dict[str, Any]) -> str:
+        """Get descriptive error message for validation failure.
+
+        Args:
+            component_data: Invalid component data
+
+        Returns:
+            Descriptive error message
+        """
+        try:
+            self.validate(component_data)
+            return "No validation errors found"
+        except ValidationError as e:
+            return f"Validation failed for {self.component_type}: {str(e)}"

fast_clean_architecture/templates/external.py.j2

@@ -1,28 +1,78 @@
-"""
-{{ external_service_name }} client for {{ module_name }} module.
+"""{{ external_service_name }} client for {{ module_name }} module.
+
+SECURITY WARNING:
+- Never log API keys or include them in error messages
+- Store API keys securely using environment variables or secret management
+- Ensure API keys are not committed to version control
 """
 import httpx
+import logging
 from typing import Any, Dict, Optional
-from pydantic import BaseModel
+from pydantic import BaseModel, Field, validator
 
 
 class {{ ExternalServiceName }}Config(BaseModel):
-    """Configuration for {{ ExternalServiceName }} client."""
+    """Configuration for {{ ExternalServiceName }} client.
+    
+    Security Note:
+    - API keys should be loaded from environment variables
+    - Never hardcode API keys in configuration files
+    """
     
     base_url: str
-    api_key: Optional[str] = None
+    api_key: Optional[str] = Field(None, description="API key for authentication (use environment variables)")
     timeout: int = 30
+    
+    @validator('api_key')
+    def validate_api_key(cls, v):
+        """Validate API key without exposing it in logs."""
+        if v and len(v.strip()) == 0:
+            raise ValueError("API key cannot be empty")
+        return v
+    
+    def __repr__(self) -> str:
+        """Safe representation that doesn't expose API key."""
+        return f"{{ ExternalServiceName }}Config(base_url='{self.base_url}', api_key={'***' if self.api_key else None}, timeout={self.timeout})"
+    
+    def __str__(self) -> str:
+        """Safe string representation that doesn't expose API key."""
+        return self.__repr__()
 
 
 class {{ ExternalServiceName }}Client:
-    """Client for {{ external_service_name }} external service."""
+    """Client for {{ external_service_name }} external service.
+    
+    Security Features:
+    - API keys are sanitized from error messages
+    - Logging excludes sensitive information
+    - Safe error handling prevents key exposure
+    """
     
     def __init__(self, config: {{ ExternalServiceName }}Config):
         self._config = config
+        self._logger = logging.getLogger(__name__)
         self._client = httpx.AsyncClient(
             base_url=config.base_url,
             timeout=config.timeout,
         )
+        
+        # Log initialization without exposing API key
+        self._logger.info(f"Initialized {{ ExternalServiceName }}Client for {config.base_url}")
+    
+    def _sanitize_error_message(self, error_msg: str) -> str:
+        """Remove API key from error messages to prevent exposure."""
+        if self._config.api_key:
+            # Replace API key with placeholder in error messages
+            sanitized = error_msg.replace(self._config.api_key, "***API_KEY***")
+            return sanitized
+        return error_msg
+    
+    def _get_safe_headers(self) -> Dict[str, str]:
+        """Get headers with API key, ensuring safe error handling."""
+        headers = {}
+        if self._config.api_key:
+            headers["Authorization"] = f"Bearer {self._config.api_key}"
+        return headers
     
     async def __aenter__(self):
         return self
@@ -31,31 +81,58 @@ class {{ ExternalServiceName }}Client:
         await self._client.aclose()
     
     async def get_data(self, endpoint: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
-        """Get data from external service."""
-        headers = {}
-        if self._config.api_key:
-            headers["Authorization"] = f"Bearer {self._config.api_key}"
-        
-        response = await self._client.get(
-            endpoint,
-            params=params,
-            headers=headers,
-        )
-        response.raise_for_status()
-        
-        return response.json()
+        """Get data from external service with secure error handling."""
+        try:
+            headers = self._get_safe_headers()
+            
+            # Log request without exposing sensitive data
+            self._logger.debug(f"Making GET request to {endpoint}")
+            
+            response = await self._client.get(
+                endpoint,
+                params=params,
+                headers=headers,
+            )
+            response.raise_for_status()
+            
+            return response.json()
+            
+        except httpx.HTTPError as e:
+            # Sanitize error message to prevent API key exposure
+            safe_error_msg = self._sanitize_error_message(str(e))
+            self._logger.error(f"HTTP error in get_data: {safe_error_msg}")
+            raise httpx.HTTPError(safe_error_msg) from e
+        except Exception as e:
+            # Sanitize any other errors
+            safe_error_msg = self._sanitize_error_message(str(e))
+            self._logger.error(f"Unexpected error in get_data: {safe_error_msg}")
+            raise Exception(safe_error_msg) from e
     
     async def post_data(self, endpoint: str, data: Dict[str, Any]) -> Dict[str, Any]:
-        """Post data to external service."""
-        headers = {"Content-Type": "application/json"}
-        if self._config.api_key:
-            headers["Authorization"] = f"Bearer {self._config.api_key}"
-        
-        response = await self._client.post(
-            endpoint,
-            json=data,
-            headers=headers,
-        )
-        response.raise_for_status()
-        
-        return response.json()
+        """Post data to external service with secure error handling."""
+        try:
+            headers = {"Content-Type": "application/json"}
+            headers.update(self._get_safe_headers())
+            
+            # Log request without exposing sensitive data
+            self._logger.debug(f"Making POST request to {endpoint}")
+            
+            response = await self._client.post(
+                endpoint,
+                json=data,
+                headers=headers,
+            )
+            response.raise_for_status()
+            
+            return response.json()
+            
+        except httpx.HTTPError as e:
+            # Sanitize error message to prevent API key exposure
+            safe_error_msg = self._sanitize_error_message(str(e))
+            self._logger.error(f"HTTP error in post_data: {safe_error_msg}")
+            raise httpx.HTTPError(safe_error_msg) from e
+        except Exception as e:
+            # Sanitize any other errors
+            safe_error_msg = self._sanitize_error_message(str(e))
+            self._logger.error(f"Unexpected error in post_data: {safe_error_msg}")
+            raise Exception(safe_error_msg) from e