geek-cafe-saas-sdk 0.6.0__py3-none-any.whl

geek_cafe_saas_sdk/lambda_handlers/_base/authorized_secure_handler.py

@@ -0,0 +1,218 @@
+"""
+Authorized Secure Handler with hierarchical routing support.
+
+Extends SecureLambdaHandler to add fine-grained authorization using the
+authorization middleware for hierarchical multi-tenant routes.
+"""
+
+from typing import Dict, Any, Optional, Callable
+from aws_lambda_powertools import Logger
+
+from .secure_handler import SecureLambdaHandler
+from geek_cafe_saas_sdk.middleware.authorization import (
+    Operation,
+    AuthorizationMiddleware,
+    extract_auth_context,
+    extract_resource_context,
+    AuthorizationResult
+)
+
+logger = Logger()
+
+
+class AuthorizedSecureLambdaHandler(SecureLambdaHandler):
+    """
+    Secure handler with built-in authorization for hierarchical routes.
+    
+    Use this when:
+    - Using hierarchical routes: /tenants/{tid}/users/{uid}/resources/{rid}
+    - Need fine-grained authorization (global admin, tenant admin, user)
+    - Want automatic tenant isolation and permission checks
+    
+    The handler:
+    1. Validates JWT via API Gateway (inherited from SecureLambdaHandler)
+    2. Extracts actor from JWT (who is making request)
+    3. Extracts resource from path (what they want to access)
+    4. Checks authorization (can actor access resource?)
+    5. Calls business logic only if authorized
+    
+    Example:
+        handler = create_handler(
+            service_class=MessageService,
+            require_authorization=True,  # Enable authorization
+            operation=Operation.READ,
+            resource_type="message"
+        )
+        
+        def lambda_handler(event, context):
+            return handler.execute(event, context, business_logic)
+        
+        def business_logic(event, service, user_context):
+            # Authorization already checked - just implement logic
+            message_id = event['pathParameters']['message_id']
+            return service.get_by_id(message_id)
+    """
+    
+    def __init__(
+        self,
+        operation: Optional[Operation] = None,
+        resource_type: Optional[str] = None,
+        extract_resource_fn: Optional[Callable[[Dict[str, Any]], Any]] = None,
+        skip_authorization: bool = False,
+        **kwargs
+    ):
+        """
+        Initialize the authorized secure handler.
+        
+        Args:
+            operation: Operation to authorize (READ, WRITE, DELETE, CREATE).
+                      If None, inferred from HTTP method.
+            resource_type: Type of resource (e.g., "message", "contact_thread")
+            extract_resource_fn: Custom function to extract resource context from event
+            skip_authorization: Skip authorization check (for backward compatibility)
+            **kwargs: Arguments passed to SecureLambdaHandler
+        """
+        super().__init__(**kwargs)
+        self.operation = operation
+        self.resource_type = resource_type
+        self.extract_resource_fn = extract_resource_fn
+        self.skip_authorization = skip_authorization
+    
+    def _infer_operation(self, event: Dict[str, Any]) -> Operation:
+        """Infer operation from HTTP method."""
+        method = event.get('httpMethod', 'GET').upper()
+        
+        if method == 'GET':
+            return Operation.READ
+        elif method == 'POST':
+            return Operation.CREATE
+        elif method in ['PUT', 'PATCH']:
+            return Operation.WRITE
+        elif method == 'DELETE':
+            return Operation.DELETE
+        else:
+            return Operation.READ  # Default
+    
+    def _check_authorization(
+        self,
+        event: Dict[str, Any]
+    ) -> Optional[Dict[str, Any]]:
+        """
+        Check if user is authorized to access the resource.
+        
+        Returns:
+            Error response dict if unauthorized, None if authorized
+        """
+        if self.skip_authorization:
+            return None
+        
+        try:
+            # Extract actor from JWT
+            actor = extract_auth_context(event)
+            
+            # Extract resource from path
+            if self.extract_resource_fn:
+                resource = self.extract_resource_fn(event)
+            else:
+                resource = extract_resource_context(event, self.resource_type)
+            
+            # Validate tenant_id is in path
+            if not resource.tenant_id:
+                logger.warning("Authorization check failed: tenant_id not in path parameters")
+                from geek_cafe_saas_sdk.utilities.response import error_response
+                return error_response(
+                    "tenant_id is required in path parameters",
+                    "AUTHORIZATION_ERROR",
+                    400
+                )
+            
+            # Determine operation
+            operation = self.operation if self.operation else self._infer_operation(event)
+            
+            # Check authorization
+            result: AuthorizationResult = AuthorizationMiddleware.can_perform_operation(
+                actor, resource, operation
+            )
+            
+            if not result.allowed:
+                logger.warning(
+                    f"Authorization denied: {result.reason}",
+                    extra={
+                        'actor_user_id': actor.user_id,
+                        'actor_tenant_id': actor.tenant_id,
+                        'resource_tenant_id': resource.tenant_id,
+                        'resource_user_id': resource.user_id,
+                        'resource_id': resource.resource_id,
+                        'operation': operation.value,
+                        'reason': result.reason
+                    }
+                )
+                from geek_cafe_saas_sdk.utilities.response import error_response
+                return error_response(
+                    "You do not have permission to access this resource",
+                    "AUTHORIZATION_DENIED",
+                    403,
+                    additional_data={'reason': result.reason}
+                )
+            
+            # Authorization passed - add context to event for business logic
+            event['authorization_context'] = {
+                'actor': actor,
+                'resource': resource,
+                'operation': operation.value,
+                'reason': result.reason,
+                'context': result.context
+            }
+            
+            # Log successful authorization for audit
+            logger.info(
+                f"Authorization granted: {result.reason}",
+                extra={
+                    'actor_user_id': actor.user_id,
+                    'actor_tenant_id': actor.tenant_id,
+                    'resource_tenant_id': resource.tenant_id,
+                    'resource_user_id': resource.user_id,
+                    'resource_id': resource.resource_id,
+                    'operation': operation.value,
+                    'reason': result.reason
+                }
+            )
+            
+            return None  # Authorized
+            
+        except KeyError as e:
+            logger.error(f"Authorization check failed: Missing JWT claim: {e}")
+            from geek_cafe_saas_sdk.utilities.response import error_response
+            return error_response(
+                f"Missing required authentication claim: {str(e)}",
+                "AUTHENTICATION_ERROR",
+                401
+            )
+        except Exception as e:
+            logger.exception(f"Authorization check failed with unexpected error: {e}")
+            from geek_cafe_saas_sdk.utilities.response import error_response
+            return error_response(
+                "Authorization check failed",
+                "AUTHORIZATION_ERROR",
+                500
+            )
+    
+    def execute(
+        self,
+        event: Dict[str, Any],
+        context: Any,
+        business_logic: Callable[[Dict[str, Any], Any, Dict[str, Any]], Any],
+        injected_service: Optional[Any] = None
+    ) -> Dict[str, Any]:
+        """
+        Execute handler with authorization check.
+        
+        Overrides parent execute() to add authorization before calling business logic.
+        """
+        # Check authorization first
+        auth_error = self._check_authorization(event)
+        if auth_error:
+            return auth_error
+        
+        # Authorization passed - call parent execute (handles everything else)
+        return super().execute(event, context, business_logic, injected_service)

geek_cafe_saas_sdk/lambda_handlers/_base/base_handler.py

@@ -0,0 +1,185 @@
+"""
+Base Lambda handler with common functionality.
+
+Provides a foundation for creating Lambda handlers with standardized
+request/response handling, error management, and service injection.
+"""
+
+import json
+from typing import Dict, Any, Callable, Optional, Type, TypeVar
+from aws_lambda_powertools import Logger
+
+from geek_cafe_saas_sdk.utilities.response import (
+    error_response,
+    service_result_to_response,
+)
+from geek_cafe_saas_sdk.utilities.lambda_event_utility import LambdaEventUtility
+from geek_cafe_saas_sdk.middleware.auth import extract_user_context
+from .service_pool import ServicePool
+
+logger = Logger()
+
+T = TypeVar('T')  # Service type
+
+
+class BaseLambdaHandler:
+    """
+    Base class for Lambda handlers with common functionality.
+    
+    Handles:
+    - Request body parsing and case conversion
+    - Service initialization and pooling
+    - User context extraction
+    - Response formatting
+    - Event unwrapping (SQS, SNS, etc.)
+    
+    """
+    
+    def __init__(
+        self,
+        service_class: Optional[Type[T]] = None,
+        service_kwargs: Optional[Dict[str, Any]] = None,
+        require_body: bool = False,
+        convert_case: bool = True,
+        unwrap_message: bool = True,
+        apply_cors: bool = True,
+        apply_error_handling: bool = True,
+        require_auth: bool = True,
+    ):
+        self.service_class = service_class
+        self.service_kwargs = service_kwargs or {}
+        self.require_body = require_body
+        self.convert_case = convert_case
+        self.unwrap_message = unwrap_message
+        self.apply_cors = apply_cors
+        self.apply_error_handling = apply_error_handling
+        self.require_auth = require_auth
+
+        # Initialize service pool if a class is provided
+        self._service_pool = ServicePool(service_class, **self.service_kwargs) if service_class else None
+
+    def _get_service(self, injected_service: Optional[T]) -> Optional[T]:
+        """
+        Get service instance (injected or from pool).
+        """
+        if injected_service:
+            return injected_service
+        
+        if self._service_pool:
+            return self._service_pool.get()
+        
+        # Fallback for direct instantiation if pooling is not used (rare)
+        if self.service_class:
+            return self.service_class(**self.service_kwargs)
+
+        return None
+
+    def execute(
+        self,
+        event: Dict[str, Any],
+        context: Any,
+        business_logic: Callable[[Dict[str, Any], Any, Dict[str, Any]], Any],
+        injected_service: Optional[T] = None
+    ) -> Dict[str, Any]:
+        """
+        Execute the Lambda handler with the given business logic.
+        
+        Args:
+            event: Lambda event dictionary
+            context: Lambda context object
+            business_logic: Callable that implements the business logic
+            injected_service: Optional service instance for testing
+            
+        Returns:
+            Lambda response dictionary
+        """
+        try:
+            # Unwrap message if needed (SQS, SNS, etc.)
+            if self.unwrap_message and "message" in event:
+                event = event["message"]
+            
+            # Validate requestContext presence (Rule #4)
+            if "requestContext" not in event:
+                return error_response(
+                    "requestContext missing from event. Ensure API Gateway is properly configured.",
+                    "CONFIGURATION_ERROR",
+                    500
+                )
+            
+            # Validate authentication if required
+            if self.require_auth:
+                authorizer = event.get("requestContext", {}).get("authorizer")
+                if not authorizer or not authorizer.get("claims", {}).get("custom:user_id"):
+                    return error_response(
+                        "Authentication required but not provided",
+                        "AUTHENTICATION_REQUIRED",
+                        401
+                    )
+            
+            # Check if body is required
+            if self.require_body and not event.get("body"):
+                return error_response(
+                    "Request body is required",
+                    "VALIDATION_ERROR",
+                    400
+                )
+            
+            # Parse and validate body
+            if event.get("body"):
+                try:
+                    body = LambdaEventUtility.get_body_from_event(event, raise_on_error=self.require_body)
+                    if body and self.convert_case:
+                        body = LambdaEventUtility.to_snake_case_for_backend(body)
+                    if body:
+                        event["parsed_body"] = body
+                except (ValueError, KeyError) as e:
+                    # If error handling is disabled, let the exception propagate for testing
+                    if not self.apply_error_handling:
+                        raise
+                    return error_response(
+                        str(e),
+                        "VALIDATION_ERROR",
+                        400
+                    )
+            
+            # Extract user context from authorizer claims
+            user_context = extract_user_context(event)
+            
+            # Get service instance
+            service = self._get_service(injected_service)
+            
+            # Execute business logic
+            result = business_logic(event, service, user_context)
+            
+            # Determine appropriate HTTP status code based on HTTP method
+            http_method = event.get('httpMethod', '').upper()
+            if http_method == 'POST':
+                success_status = 201  # Created
+            elif http_method == 'DELETE':
+                success_status = 204  # No Content
+            else:
+                success_status = 200  # OK (GET, PUT, PATCH, etc.)
+            
+            # Format response - handle both ServiceResult and plain dict
+            if hasattr(result, 'success'):
+                # It's a ServiceResult object
+                response = service_result_to_response(result, success_status=success_status)
+            else:
+                # It's a plain dict - wrap it in a success response
+                from geek_cafe_saas_sdk.utilities.response import success_response
+                response = success_response(result, success_status)
+            
+            # Note: CORS headers are already added by success_response/service_result_to_response
+            # The apply_cors flag is for decorator usage, not runtime response modification
+            return response
+            
+        except Exception as e:
+            logger.exception(f"Handler execution error: {e}")
+            if self.apply_error_handling:
+                # Convert exception to error response (error_response is imported at top)
+                return error_response(
+                    str(e),
+                    "INTERNAL_ERROR",
+                    500
+                )
+            raise

geek_cafe_saas_sdk/lambda_handlers/_base/handler_factory.py

@@ -0,0 +1,256 @@
+"""
+Factory for creating Lambda handlers based on configuration.
+
+Centralizes handler selection logic and provides a single point
+for configuring authentication strategy across all Lambda functions.
+"""
+
+import os
+from typing import Optional, Type, TypeVar, Any
+from aws_lambda_powertools import Logger
+
+from .base_handler import BaseLambdaHandler
+from .api_key_handler import ApiKeyLambdaHandler
+from .public_handler import PublicLambdaHandler
+from .secure_handler import SecureLambdaHandler
+from .authorized_secure_handler import AuthorizedSecureLambdaHandler
+
+logger = Logger()
+
+T = TypeVar('T')  # Service type
+
+
+class HandlerFactory:
+    """
+    Factory for creating Lambda handlers with appropriate authentication.
+    
+    Configuration via environment variables:
+    
+    - AUTH_TYPE (default: "secure"):
+        - "secure": Uses API Gateway authorizer (Cognito/Lambda/IAM)
+        - "api_key": Validates x-api-key header against API_KEY env var
+        - "public": No authentication required
+        - "none": Alias for "public"
+    
+    - AUTH_STRICT (default: "true"):
+        - "true": Strict validation, fail if auth is missing
+        - "false": Permissive mode for local dev/testing
+    
+    Usage:
+        # Simple usage - defaults to secure handler
+        handler = HandlerFactory.create(
+            service_class=VoteService,
+            require_body=True
+        )
+        
+        # Explicit type
+        handler = HandlerFactory.create(
+            service_class=VoteService,
+            auth_type="api_key",  # Override environment
+            require_body=True
+        )
+        
+        # Public endpoint
+        handler = HandlerFactory.create_public(
+            service_class=ConfigService
+        )
+        
+        # In lambda function
+        def lambda_handler(event, context):
+            return handler.execute(event, context, business_logic)
+    """
+    
+    # Auth type constants
+    AUTH_TYPE_SECURE = "secure"
+    AUTH_TYPE_API_KEY = "api_key"
+    AUTH_TYPE_PUBLIC = "public"
+    AUTH_TYPE_NONE = "none"  # Alias for public
+    
+    # Environment variable names
+    ENV_AUTH_TYPE = "AUTH_TYPE"
+    ENV_AUTH_STRICT = "AUTH_STRICT"
+    
+    @classmethod
+    def create(
+        cls,
+        service_class: Optional[Type[T]] = None,
+        auth_type: Optional[str] = None,
+        strict: Optional[bool] = None,
+        require_authorization: bool = False,
+        operation: Optional[Any] = None,
+        resource_type: Optional[str] = None,
+        **handler_kwargs
+    ) -> BaseLambdaHandler:
+        """
+        Create a handler with appropriate authentication and optional authorization.
+        
+        Args:
+            service_class: Service class to instantiate
+            auth_type: Override AUTH_TYPE env var ("secure", "api_key", "public")
+            strict: Override AUTH_STRICT env var (True/False)
+            require_authorization: Enable fine-grained authorization for hierarchical routes
+            operation: Operation to authorize (Operation.READ, etc.). If None, inferred from HTTP method
+            resource_type: Type of resource for authorization (e.g., "message", "contact_thread")
+            **handler_kwargs: Additional arguments for handler (require_body, etc.)
+            
+        Returns:
+            Configured handler instance
+        
+        Examples:
+            # Simple secure handler (existing behavior)
+            handler = HandlerFactory.create(service_class=MessageService)
+            
+            # With authorization for hierarchical routes
+            handler = HandlerFactory.create(
+                service_class=MessageService,
+                require_authorization=True,
+                operation=Operation.READ,
+                resource_type="message"
+            )
+        """
+        # Get auth type from args or environment
+        if auth_type is None:
+            auth_type = os.getenv(cls.ENV_AUTH_TYPE, cls.AUTH_TYPE_SECURE).lower()
+        else:
+            auth_type = auth_type.lower()
+        
+        # Get strict mode
+        if strict is None:
+            strict_str = os.getenv(cls.ENV_AUTH_STRICT, "true").lower()
+            strict = strict_str in ("true", "1", "yes")
+        
+        # Log configuration
+        logger.info(
+            f"Creating handler with auth_type={auth_type}, strict={strict}, "
+            f"service={service_class.__name__ if service_class else 'None'}"
+        )
+        
+        # Prepare service kwargs, including the system inbox ID if applicable
+        service_kwargs = {}
+        if service_class and hasattr(service_class, '__init__') and 'system_inbox_id' in service_class.__init__.__code__.co_varnames:
+            service_kwargs['system_inbox_id'] = os.getenv('SYSTEM_INBOX_ID', 'support-inbox')
+
+        # Create appropriate handler
+        if auth_type == cls.AUTH_TYPE_API_KEY:
+            return ApiKeyLambdaHandler(
+                service_class=service_class,
+                service_kwargs=service_kwargs,
+                **handler_kwargs
+            )
+        elif auth_type in (cls.AUTH_TYPE_PUBLIC, cls.AUTH_TYPE_NONE):
+            return PublicLambdaHandler(
+                service_class=service_class,
+                service_kwargs=service_kwargs,
+                **handler_kwargs
+            )
+        elif auth_type == cls.AUTH_TYPE_SECURE:
+            # Use AuthorizedSecureLambdaHandler if authorization is required
+            if require_authorization:
+                return AuthorizedSecureLambdaHandler(
+                    service_class=service_class,
+                    service_kwargs=service_kwargs,
+                    require_authorizer_claims=strict,
+                    operation=operation,
+                    resource_type=resource_type,
+                    **handler_kwargs
+                )
+            else:
+                return SecureLambdaHandler(
+                    service_class=service_class,
+                    service_kwargs=service_kwargs,
+                    require_authorizer_claims=strict,
+                    **handler_kwargs
+                )
+        else:
+            logger.warning(
+                f"Unknown auth_type '{auth_type}', defaulting to secure handler"
+            )
+            # Use AuthorizedSecureLambdaHandler if authorization is required
+            if require_authorization:
+                return AuthorizedSecureLambdaHandler(
+                    service_class=service_class,
+                    service_kwargs=service_kwargs,
+                    require_authorizer_claims=strict,
+                    operation=operation,
+                    resource_type=resource_type,
+                    **handler_kwargs
+                )
+            else:
+                return SecureLambdaHandler(
+                    service_class=service_class,
+                    service_kwargs=service_kwargs,
+                    require_authorizer_claims=strict,
+                    **handler_kwargs
+                )
+    
+    @classmethod
+    def create_secure(
+        cls,
+        service_class: Optional[Type[T]] = None,
+        **handler_kwargs
+    ) -> SecureLambdaHandler:
+        """
+        Create a secure handler (API Gateway authorizer).
+        
+        Convenience method that explicitly creates a secure handler
+        regardless of environment configuration.
+        """
+        return SecureLambdaHandler(
+            service_class=service_class,
+            **handler_kwargs
+        )
+    
+    @classmethod
+    def create_api_key(
+        cls,
+        service_class: Optional[Type[T]] = None,
+        **handler_kwargs
+    ) -> ApiKeyLambdaHandler:
+        """
+        Create an API key handler.
+        
+        Convenience method that explicitly creates an API key handler
+        regardless of environment configuration.
+        """
+        return ApiKeyLambdaHandler(
+            service_class=service_class,
+            **handler_kwargs
+        )
+    
+    @classmethod
+    def create_public(
+        cls,
+        service_class: Optional[Type[T]] = None,
+        **handler_kwargs
+    ) -> PublicLambdaHandler:
+        """
+        Create a public handler (no auth).
+        
+        Convenience method that explicitly creates a public handler
+        regardless of environment configuration.
+        """
+        return PublicLambdaHandler(
+            service_class=service_class,
+            **handler_kwargs
+        )
+
+
+# Convenience function for quick handler creation
+def create_handler(
+    service_class: Optional[Type[T]] = None,
+    **kwargs
+) -> BaseLambdaHandler:
+    """
+    Convenience function for creating handlers.
+    
+    Equivalent to HandlerFactory.create()
+    
+    Example:
+        from geek_cafe_saas_sdk.lambda_handlers import create_handler
+        
+        handler = create_handler(
+            service_class=VoteService,
+            require_body=True
+        )
+    """
+    return HandlerFactory.create(service_class=service_class, **kwargs)