geek-cafe-saas-sdk 0.7.5__py3-none-any.whl → 0.8.0__py3-none-any.whl

geek_cafe_saas_sdk/__init__.py

@@ -3,7 +3,7 @@ Geek Cafe Services - Base Reusable Services for SaaS
 
 Version 0.6.0 adds File System Service
 """
-__version__ = "0.7.5"
+__version__ = "0.8.0"
 
 # Import main modules for easier access
 from . import services

geek_cafe_saas_sdk/core/anonymous_context.py

@@ -0,0 +1,321 @@
+"""
+Anonymous Context Factory for Public Operations.
+
+Provides standardized RequestContext for:
+- Anonymous/public operations (contact forms, surveys, voting)
+- System operations (background jobs, scheduled tasks)
+
+Maintains security architecture while allowing public access.
+"""
+
+import os
+from typing import Dict, Any, Optional
+from .request_context import RequestContext
+
+
+class AnonymousContextFactory:
+    """
+    Factory for creating RequestContext for anonymous/public operations.
+    
+    Use this for operations that don't require authentication but still
+    need security context for audit trails and validation.
+    
+    Examples:
+        - Public contact forms
+        - Anonymous voting/polls
+        - Public surveys
+        - Newsletter signups
+        - A/B testing
+    """
+    
+    # Standard user IDs for special contexts
+    ANONYMOUS_USER_ID = "anonymous"
+    SYSTEM_USER_ID = "system"
+    SYSTEM_TENANT_ID = "SYSTEM"  # Used for tenant provisioning operations
+    
+    @staticmethod
+    def create_anonymous_context(
+        tenant_id: str,
+        ip_address: Optional[str] = None,
+        session_id: Optional[str] = None,
+        additional_metadata: Optional[Dict[str, Any]] = None
+    ) -> RequestContext:
+        """
+        Create RequestContext for anonymous operations.
+        
+        Anonymous users:
+        - Belong to a specific tenant
+        - Have limited permissions (public:submit)
+        - Tracked by IP and session for rate limiting
+        - Show as 'anonymous' in audit trail
+        
+        Args:
+            tenant_id: Tenant ID (required - anonymous users still belong to tenant)
+            ip_address: Optional IP address for rate limiting/tracking
+            session_id: Optional session ID for duplicate prevention
+            additional_metadata: Extra metadata (e.g., referrer, user agent)
+            
+        Returns:
+            RequestContext with anonymous user identity
+            
+        Example:
+            >>> from geek_cafe_saas_sdk.core.anonymous_context import AnonymousContextFactory
+            >>> 
+            >>> # In public Lambda handler
+            >>> context = AnonymousContextFactory.create_anonymous_context(
+            ...     tenant_id='tenant_123',
+            ...     ip_address='192.168.1.1',
+            ...     session_id='sess_abc123'
+            ... )
+            >>> 
+            >>> service = ContactThreadService(
+            ...     dynamodb=db,
+            ...     table_name=TABLE,
+            ...     request_context=context
+            ... )
+            >>> 
+            >>> result = service.create(
+            ...     tenant_id='tenant_123',
+            ...     user_id='anonymous',
+            ...     payload={'message': 'Hello'}
+            ... )
+        """
+        if not tenant_id:
+            raise ValueError("tenant_id is required for anonymous context")
+        
+        user_context = {
+            'user_id': AnonymousContextFactory.ANONYMOUS_USER_ID,
+            'tenant_id': tenant_id,
+            'email': 'anonymous@public',
+            'roles': ['public'],
+            'permissions': ['public:submit'],
+            'inboxes': [],
+            
+            # Special flags
+            'is_anonymous': True,
+            'is_authenticated': False,
+            
+            # Tracking for rate limiting and abuse prevention
+            'ip_address': ip_address,
+            'session_id': session_id,
+            
+            # Additional context
+            'metadata': additional_metadata or {}
+        }
+        
+        return RequestContext(user_context)
+    
+    @staticmethod
+    def create_system_context(
+        tenant_id: str,
+        operation_name: Optional[str] = None
+    ) -> RequestContext:
+        """
+        Create RequestContext for system operations.
+        
+        System context:
+        - Used for background jobs and scheduled tasks
+        - Has elevated permissions (*:*:*)
+        - Shows as 'system' in audit trail
+        - Not rate limited
+        
+        Args:
+            tenant_id: Tenant ID for the operation
+            operation_name: Optional name of the operation (for logging)
+            
+        Returns:
+            RequestContext with system identity
+            
+        Example:
+            >>> from geek_cafe_saas_sdk.core.anonymous_context import AnonymousContextFactory
+            >>> 
+            >>> # In background job
+            >>> context = AnonymousContextFactory.create_system_context(
+            ...     tenant_id='tenant_123',
+            ...     operation_name='cleanup_old_data'
+            ... )
+            >>> 
+            >>> service = AnalyticsService(
+            ...     dynamodb=db,
+            ...     table_name=TABLE,
+            ...     request_context=context
+            ... )
+            >>> 
+            >>> result = service.delete_old_records(days_old=90)
+            >>> # Audit trail shows: deleted_by='system'
+        """
+        if not tenant_id:
+            raise ValueError("tenant_id is required for system context")
+        
+        user_context = {
+            'user_id': AnonymousContextFactory.SYSTEM_USER_ID,
+            'tenant_id': tenant_id,
+            'email': 'system@internal',
+            'roles': ['system'],
+            'permissions': ['*:*:*'],  # System has all permissions
+            'inboxes': [],
+            
+            # Special flags
+            'is_system': True,
+            'is_authenticated': True,
+            
+            # Context
+            'operation_name': operation_name,
+            'metadata': {'operation': operation_name} if operation_name else {}
+        }
+        
+        return RequestContext(user_context)
+    
+    @staticmethod
+    def create_test_context(
+        user_id: str = "test_user",
+        tenant_id: str = "test_tenant",
+        roles: Optional[list] = None,
+        permissions: Optional[list] = None
+    ) -> RequestContext:
+        """
+        Create RequestContext for testing.
+        
+        Convenience method for creating test contexts without full JWT setup.
+        
+        Args:
+            user_id: Test user ID
+            tenant_id: Test tenant ID
+            roles: Optional list of roles
+            permissions: Optional list of permissions
+            
+        Returns:
+            RequestContext for testing
+            
+        Example:
+            >>> from geek_cafe_saas_sdk.core.anonymous_context import AnonymousContextFactory
+            >>> 
+            >>> # In test
+            >>> context = AnonymousContextFactory.create_test_context(
+            ...     user_id='user_123',
+            ...     tenant_id='tenant_123',
+            ...     permissions=['messages:create']
+            ... )
+        """
+        user_context = {
+            'user_id': user_id,
+            'tenant_id': tenant_id,
+            'email': f'{user_id}@test.com',
+            'roles': roles or [],
+            'permissions': permissions or [],
+            'inboxes': [],
+            'is_test': True
+        }
+        
+        return RequestContext(user_context)
+    
+    @staticmethod
+    def create_provisioning_context(
+        operation_name: str = "tenant_provisioning"
+    ) -> RequestContext:
+        """
+        Create RequestContext for tenant provisioning operations (signup flow).
+        
+        Provisioning context:
+        - Used for creating new tenants during signup
+        - Has SYSTEM tenant_id to bypass tenant isolation
+        - Has elevated permissions for tenant creation
+        - Shows as 'system' in audit trail
+        
+        Args:
+            operation_name: Name of the provisioning operation (for logging)
+            
+        Returns:
+            RequestContext with system identity for provisioning
+            
+        Example:
+            >>> from geek_cafe_saas_sdk.core.anonymous_context import AnonymousContextFactory
+            >>> 
+            >>> # In signup handler
+            >>> context = AnonymousContextFactory.create_provisioning_context(
+            ...     operation_name='user_signup'
+            ... )
+            >>> 
+            >>> tenant_service = TenantService(
+            ...     dynamodb=db,
+            ...     table_name=TABLE,
+            ...     request_context=context
+            ... )
+            >>> 
+            >>> result = tenant_service.create_with_user(
+            ...     user_payload={...},
+            ...     tenant_payload={...}
+            ... )
+            >>> # Creates new tenant, audit trail shows: created_by='system'
+        """
+        user_context = {
+            'user_id': AnonymousContextFactory.SYSTEM_USER_ID,
+            'tenant_id': AnonymousContextFactory.SYSTEM_TENANT_ID,
+            'email': 'system@internal',
+            'roles': ['system', 'provisioner'],
+            'permissions': ['*:*:*'],  # System has all permissions
+            'inboxes': [],
+            
+            # Special flags
+            'is_system': True,
+            'is_provisioning': True,
+            'is_authenticated': True,
+            
+            # Context
+            'operation_name': operation_name,
+            'metadata': {'operation': operation_name, 'type': 'provisioning'}
+        }
+        
+        return RequestContext(user_context)
+    
+    @staticmethod
+    def is_anonymous(request_context: RequestContext) -> bool:
+        """
+        Check if request context is anonymous.
+        
+        Args:
+            request_context: RequestContext to check
+            
+        Returns:
+            True if anonymous, False otherwise
+        """
+        return request_context._user_context.get('is_anonymous', False)
+    
+    @staticmethod
+    def is_system(request_context: RequestContext) -> bool:
+        """
+        Check if request context is system.
+        
+        Args:
+            request_context: RequestContext to check
+            
+        Returns:
+            True if system, False otherwise
+        """
+        return request_context._user_context.get('is_system', False)
+    
+    @staticmethod
+    def get_ip_address(request_context: RequestContext) -> Optional[str]:
+        """
+        Get IP address from request context.
+        
+        Args:
+            request_context: RequestContext
+            
+        Returns:
+            IP address if available, None otherwise
+        """
+        return request_context._user_context.get('ip_address')
+    
+    @staticmethod
+    def get_session_id(request_context: RequestContext) -> Optional[str]:
+        """
+        Get session ID from request context.
+        
+        Args:
+            request_context: RequestContext
+            
+        Returns:
+            Session ID if available, None otherwise
+        """
+        return request_context._user_context.get('session_id')

geek_cafe_saas_sdk/core/request_context.py

@@ -0,0 +1,184 @@
+"""
+Request Context - Security Token Service for Geek Cafe SaaS SDK.
+
+This module provides a centralized security context that tracks:
+- Authenticated user (from JWT)
+- Target resource (from API path parameters)
+- Authorization helpers (roles, permissions, tenancy validation)
+"""
+
+from typing import Dict, List, Optional, Any
+
+
+class RequestContext:
+    """
+    Security token service - single source of truth for request authentication and authorization.
+    
+    This class separates:
+    - WHO is making the request (authenticated_user_id, authenticated_tenant_id from JWT)
+    - WHAT they're trying to access (target_user_id, target_tenant_id from path)
+    
+    This separation enables proper security validation:
+    - Can user A access resources belonging to user B?
+    - Can user from tenant X access resources in tenant Y?
+    - Does user have required role/permission?
+    """
+    
+    def __init__(self, user_context: Optional[Dict[str, Any]] = None):
+        """
+        Initialize request context from JWT payload.
+        
+        Args:
+            user_context: Dictionary from JWT containing:
+                - user_id: Authenticated user ID
+                - tenant_id: Authenticated user's tenant ID
+                - roles: List of role strings
+                - permissions: List of permission strings
+                - email: User email
+                - inboxes: List of inbox IDs (optional)
+        """
+        self._user_context = user_context or {}
+        
+        # Authenticated user (from JWT)
+        self.authenticated_user_id: Optional[str] = self._user_context.get('user_id')
+        self.authenticated_tenant_id: Optional[str] = self._user_context.get('tenant_id')
+        self.authenticated_user_email: Optional[str] = self._user_context.get('email')
+        self.roles: List[str] = self._user_context.get('roles', [])
+        self.permissions: List[str] = self._user_context.get('permissions', [])
+        self.inboxes: List[str] = self._user_context.get('inboxes', [])
+        
+        # Target resource (from path parameters - set by services)
+        self.target_user_id: Optional[str] = None
+        self.target_tenant_id: Optional[str] = None
+    
+    def set_targets(self, tenant_id: Optional[str] = None, user_id: Optional[str] = None):
+        """
+        Set target resource IDs from path parameters.
+        
+        Args:
+            tenant_id: Target tenant ID from path
+            user_id: Target user ID from path
+        """
+        if tenant_id:
+            self.target_tenant_id = tenant_id
+        if user_id:
+            self.target_user_id = user_id
+    
+    # ========================================
+    # Tenancy Validation
+    # ========================================
+    
+    def is_same_tenancy(self) -> bool:
+        """Check if authenticated user's tenant matches target tenant."""
+        if not self.target_tenant_id:
+            return True  # No target specified, assume same
+        return self.authenticated_tenant_id == self.target_tenant_id
+    
+    def validate_tenant_access(self, tenant_id: str) -> bool:
+        """
+        Validate user can access resources in target tenant.
+        
+        Args:
+            tenant_id: Tenant ID to validate
+            
+        Returns:
+            True if access allowed, False otherwise
+        """
+        # Platform admins can access any tenant
+        if self.is_platform_admin():
+            return True
+        
+        # Regular users can only access their own tenant
+        return self.authenticated_tenant_id == tenant_id
+    
+    # ========================================
+    # User Access Validation
+    # ========================================
+    
+    def is_self_user(self) -> bool:
+        """Check if authenticated user is the same as target user."""
+        if not self.target_user_id:
+            return True  # No target specified
+        return self.authenticated_user_id == self.target_user_id
+    
+    def can_access_user_resource(self, resource_user_id: str) -> bool:
+        """
+        Check if user can access a resource owned by another user.
+        
+        Args:
+            resource_user_id: Owner of the resource
+            
+        Returns:
+            True if access allowed
+        """
+        # Self access
+        if self.authenticated_user_id == resource_user_id:
+            return True
+        
+        # Admins can access
+        if self.is_platform_admin() or self.is_tenant_admin():
+            return True
+        
+        return False
+    
+    # ========================================
+    # Role Checks
+    # ========================================
+    
+    def has_role(self, role: str) -> bool:
+        """Check if user has a specific role."""
+        return role in self.roles
+    
+    def has_any_role(self, roles: List[str]) -> bool:
+        """Check if user has any of the specified roles."""
+        return any(role in self.roles for role in roles)
+    
+    def is_platform_admin(self) -> bool:
+        """Check if user is a platform admin (can access all tenants)."""
+        return 'platform_admin' in self.roles
+    
+    def is_tenant_admin(self) -> bool:
+        """Check if user is admin of their tenant."""
+        return 'tenant_admin' in self.roles
+    
+    def is_admin(self) -> bool:
+        """Check if user is any kind of admin."""
+        return self.is_platform_admin() or self.is_tenant_admin()
+    
+    # ========================================
+    # Permission Checks
+    # ========================================
+    
+    def has_permission(self, permission: str) -> bool:
+        """Check if user has a specific permission."""
+        return permission in self.permissions
+    
+    def has_any_permission(self, permissions: List[str]) -> bool:
+        """Check if user has any of the specified permissions."""
+        return any(perm in self.permissions for perm in permissions)
+    
+    def has_all_permissions(self, permissions: List[str]) -> bool:
+        """Check if user has all specified permissions."""
+        return all(perm in self.permissions for perm in permissions)
+    
+    # ========================================
+    # Utility Methods
+    # ========================================
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert context to dictionary for logging/debugging."""
+        return {
+            'authenticated_user_id': self.authenticated_user_id,
+            'authenticated_tenant_id': self.authenticated_tenant_id,
+            'authenticated_user_email': self.authenticated_user_email,
+            'target_user_id': self.target_user_id,
+            'target_tenant_id': self.target_tenant_id,
+            'roles': self.roles,
+            'permissions': self.permissions,
+            'is_admin': self.is_admin(),
+            'is_same_tenancy': self.is_same_tenancy(),
+            'is_self_user': self.is_self_user(),
+        }
+    
+    def __repr__(self) -> str:
+        return f"RequestContext(user={self.authenticated_user_id}, tenant={self.authenticated_tenant_id})"

geek_cafe_saas_sdk/decorators/__init__.py

@@ -16,7 +16,7 @@ Usage:
     @add_cors
     @parse_request_body(convert_case=True)
     @inject_service(MessageService)
-    def handler(event, context, service):
+    def lambda_handler(event, context, service):
         return service.get_by_id(event['pathParameters']['id'])
 
 Design Principles:

geek_cafe_saas_sdk/decorators/auth.py

@@ -51,14 +51,14 @@ def require_authorization(
     
     Usage:
         @require_authorization(operation=Operation.READ, resource_type="message")
-        def handler(event, context):
+        def lambda_handler(event, context):
             # Authorization already checked
             message_id = event['pathParameters']['message_id']
             return {'statusCode': 200}
         
         # Auto-infer operation from HTTP method
         @require_authorization(resource_type="message")
-        def handler(event, context):
+        def lambda_handler(event, context):
             # GET -> READ, POST -> CREATE, etc.
             pass
     
@@ -181,7 +181,7 @@ def require_admin(handler: Callable) -> Callable:
     
     Usage:
         @require_admin
-        def handler(event, context):
+        def lambda_handler(event, context):
             # User is guaranteed to be an admin
             return {'statusCode': 200}
     
@@ -242,7 +242,7 @@ def require_tenant_admin(handler: Callable) -> Callable:
     
     Usage:
         @require_tenant_admin
-        def handler(event, context):
+        def lambda_handler(event, context):
             # User is tenant admin for their tenant
             return {'statusCode': 200}
     
@@ -296,7 +296,7 @@ def require_platform_admin(handler: Callable) -> Callable:
     
     Usage:
         @require_platform_admin
-        def handler(event, context):
+        def lambda_handler(event, context):
             # User is platform admin
             return {'statusCode': 200}
     
@@ -358,7 +358,7 @@ def public(handler: Callable) -> Callable:
     
     Usage:
         @public
-        def handler(event, context):
+        def lambda_handler(event, context):
             # Public endpoint - no auth check
             return {'statusCode': 200}