mdb-engine 0.1.6__py3-none-any.whl → 0.2.0__py3-none-any.whl

mdb_engine/auth/base.py

@@ -0,0 +1,252 @@
+"""
+Authorization Engine Base Classes
+
+Defines the abstract contract for authorization providers using the Adapter Pattern.
+This ensures type safety, fail-closed security, and proper abstraction.
+
+This module is part of MDB_ENGINE - MongoDB Engine.
+"""
+
+from __future__ import annotations
+
+import abc
+import logging
+from typing import Any, Optional
+
+logger = logging.getLogger(__name__)
+
+
+class AuthorizationError(Exception):
+    """
+    Base exception for authorization failures.
+
+    Ensures abstraction doesn't leak - application code doesn't need to know
+    if the failure came from Casbin, OSO, or any other engine.
+    """
+
+    pass
+
+
+class BaseAuthorizationProvider(abc.ABC):
+    """
+    Abstract Base Class defining the contract for authorization providers.
+
+    Design Principles:
+    1. Interface Segregation - Application only needs 'check', not engine internals
+    2. Fail-Closed Security - Errors deny access, never grant it
+    3. Adapter Pattern - Wraps third-party libraries without modifying them
+    4. Type Safety - Clear contracts with proper type hints
+
+    This ABC ensures that all authorization providers:
+    - Have a consistent interface
+    - Fail securely (deny on error)
+    - Provide observability (structured logging)
+    - Handle edge cases gracefully
+    """
+
+    def __init__(self, engine_name: str):
+        """
+        Initialize the base provider.
+
+        Args:
+            engine_name: Human-readable name of the engine (e.g., "Casbin", "OSO Cloud")
+        """
+        self._engine_name = engine_name
+        self._initialized = False
+        logger.info(f"Initializing {engine_name} authorization provider")
+
+    @property
+    def engine_name(self) -> str:
+        """Get the name of the authorization engine."""
+        return self._engine_name
+
+    @property
+    def is_initialized(self) -> bool:
+        """Check if the provider has been properly initialized."""
+        return self._initialized
+
+    @abc.abstractmethod
+    async def check(
+        self,
+        subject: str,
+        resource: str,
+        action: str,
+        user_object: Optional[dict[str, Any]] = None,
+    ) -> bool:
+        """
+        Check if a subject is allowed to perform an action on a resource.
+
+        This is the primary authorization decision method. All implementations
+        must follow fail-closed security: if evaluation fails, deny access.
+
+        Args:
+            subject: Who is making the request (typically email or user ID)
+            resource: What resource they're accessing (e.g., "documents", "clicks")
+            action: What action they want to perform (e.g., "read", "write", "delete")
+            user_object: Optional user object with additional context
+
+        Returns:
+            True if authorized, False otherwise (including on error - fail-closed)
+
+        Raises:
+            AuthorizationError: Only for configuration/initialization errors,
+                not evaluation failures
+        """
+        pass
+
+    @abc.abstractmethod
+    async def add_policy(self, *params: Any) -> bool:
+        """
+        Add a policy rule to the authorization engine.
+
+        Args:
+            *params: Policy parameters (format depends on engine)
+
+        Returns:
+            True if policy was added successfully, False otherwise
+        """
+        pass
+
+    @abc.abstractmethod
+    async def add_role_for_user(self, *params: Any) -> bool:
+        """
+        Assign a role to a user.
+
+        Args:
+            *params: Role assignment parameters (format depends on engine)
+
+        Returns:
+            True if role was assigned successfully, False otherwise
+        """
+        pass
+
+    @abc.abstractmethod
+    async def save_policy(self) -> bool:
+        """
+        Persist policy changes to storage.
+
+        Returns:
+            True if saved successfully, False otherwise
+        """
+        pass
+
+    @abc.abstractmethod
+    async def has_policy(self, *params: Any) -> bool:
+        """
+        Check if a policy exists.
+
+        Args:
+            *params: Policy parameters to check
+
+        Returns:
+            True if policy exists, False otherwise
+        """
+        pass
+
+    @abc.abstractmethod
+    async def has_role_for_user(self, *params: Any) -> bool:
+        """
+        Check if a user has a specific role.
+
+        Args:
+            *params: User and role parameters
+
+        Returns:
+            True if user has the role, False otherwise
+        """
+        pass
+
+    @abc.abstractmethod
+    async def clear_cache(self) -> None:
+        """
+        Clear the authorization cache.
+
+        Should be called when policies or roles are modified to ensure
+        fresh authorization decisions.
+        """
+        pass
+
+    def _mark_initialized(self) -> None:
+        """Mark the provider as initialized (internal use only)."""
+        self._initialized = True
+        logger.info(f"✅ {self._engine_name} authorization provider initialized successfully")
+
+    def is_casbin(self) -> bool:
+        """
+        Check if this provider is a Casbin adapter.
+
+        Returns:
+            True if this is a CasbinAdapter, False otherwise
+        """
+        return hasattr(self, "_enforcer")
+
+    def is_oso(self) -> bool:
+        """
+        Check if this provider is an OSO adapter.
+
+        Returns:
+            True if this is an OsoAdapter, False otherwise
+        """
+        return hasattr(self, "_oso")
+
+    def _handle_evaluation_error(
+        self,
+        subject: str,
+        resource: str,
+        action: str,
+        error: Exception,
+        context: Optional[str] = None,
+    ) -> bool:
+        """
+        Handle authorization evaluation errors with fail-closed security.
+
+        Design Principle: Fail-Closed Security
+        - If the authorization engine crashes or errors, we MUST deny access
+        - Logging the error is critical for observability
+        - Never raise exceptions from evaluation errors (only from config errors)
+
+        Args:
+            subject: Subject that was being checked
+            resource: Resource that was being checked
+            action: Action that was being checked
+            error: The exception that occurred
+            context: Optional context string for logging
+
+        Returns:
+            False (deny access - fail-closed)
+        """
+        context_str = f" ({context})" if context else ""
+        logger.critical(
+            f"{self._engine_name} authorization evaluation failed{context_str}: "
+            f"subject={subject}, resource={resource}, action={action}, "
+            f"error={type(error).__name__}: {error}",
+            exc_info=True,
+        )
+        return False
+
+    def _handle_operation_error(
+        self,
+        operation: str,
+        error: Exception,
+        *params: Any,
+    ) -> bool:
+        """
+        Handle policy/role operation errors.
+
+        These are non-critical operations (adding policies, roles, etc.)
+        so we log warnings but don't fail-closed (return False).
+
+        Args:
+            operation: Name of the operation (e.g., "add_policy")
+            error: The exception that occurred
+            *params: Parameters that were passed to the operation
+
+        Returns:
+            False (operation failed)
+        """
+        logger.warning(
+            f"{self._engine_name} {operation} failed: "
+            f"params={params}, error={type(error).__name__}: {error}",
+            exc_info=True,
+        )
+        return False

mdb_engine/auth/casbin_factory.py

@@ -11,19 +11,19 @@ from __future__ import annotations
 
 import logging
 from pathlib import Path
-from typing import TYPE_CHECKING, Any, Dict, Optional
+from typing import TYPE_CHECKING, Any, Optional
 
 from .casbin_models import DEFAULT_RBAC_MODEL, SIMPLE_ACL_MODEL
 
 if TYPE_CHECKING:
-    import casbin
+    import casbin  # type: ignore
 
     from .provider import CasbinAdapter
 
 logger = logging.getLogger(__name__)
 
 
-def get_casbin_model(model_type: str = "rbac") -> str:
+async def get_casbin_model(model_type: str = "rbac") -> str:
     """
     Get Casbin model string by type or path.
 
@@ -39,18 +39,32 @@ def get_casbin_model(model_type: str = "rbac") -> str:
         return SIMPLE_ACL_MODEL
     else:
         # Assume it's a file path
+        # Try async file reading first, fallback to sync if not available
         model_path = Path(model_type)
         if model_path.exists():
-            return model_path.read_text()
+            try:
+                # Try async file reading (non-blocking)
+                import aiofiles
+
+                async with aiofiles.open(model_path, "r") as f:
+                    content = await f.read()
+                    logger.debug(f"Read model file asynchronously: {model_path}")
+                    return content
+            except ImportError:
+                # Fallback to sync read if aiofiles not available
+                # This is acceptable during startup initialization
+                logger.debug(
+                    "aiofiles not available, using sync file read (acceptable during startup)"
+                )
+                return model_path.read_text()
         else:
-            logger.warning(
-                f"Casbin model file not found: {model_type}, using default RBAC model"
-            )
+            logger.warning(f"Casbin model file not found: {model_type}, using default RBAC model")
             return DEFAULT_RBAC_MODEL
 
 
 async def create_casbin_enforcer(
-    db,
+    mongo_uri: str,
+    db_name: str,
     model: str = "rbac",
     policies_collection: str = "casbin_policies",
     default_roles: Optional[list] = None,
@@ -59,9 +73,10 @@ async def create_casbin_enforcer(
     Create a Casbin AsyncEnforcer with MongoDB adapter.
 
     Args:
-        db: MongoDB database instance (Motor AsyncIOMotorDatabase)
+        mongo_uri: MongoDB connection URI string
+        db_name: MongoDB database name
         model: Casbin model type ("rbac", "acl") or path to model file
-        policies_collection: MongoDB collection name for policies
+        policies_collection: MongoDB collection name for policies (will be app-scoped)
         default_roles: List of default roles to create (optional)
 
     Returns:
@@ -71,30 +86,94 @@ async def create_casbin_enforcer(
         ImportError: If casbin or casbin-motor-adapter is not installed
     """
     try:
-        import casbin
-        from casbin_motor_adapter import MotorAdapter
+        import casbin  # type: ignore
+        from casbin_motor_adapter import Adapter  # type: ignore
     except ImportError as e:
         raise ImportError(
             "Casbin dependencies not installed. Install with: pip install mdb-engine[casbin]"
         ) from e
 
-    # Get model string
-    model_str = get_casbin_model(model)
+    # Get model string (async)
+    model_str = await get_casbin_model(model)
 
     # Create MongoDB adapter
-    adapter = MotorAdapter(db, policies_collection)
+    # Try to pass policies_collection if supported by the adapter
+    logger.debug(
+        f"Creating Casbin MotorAdapter with URI: {mongo_uri[:50]}..., "
+        f"db_name: {db_name}, collection: {policies_collection}"
+    )
+    try:
+        # Try passing collection name as third parameter
+        try:
+            adapter = Adapter(mongo_uri, db_name, policies_collection)
+            logger.debug(
+                f"Casbin MotorAdapter created successfully with custom "
+                f"collection '{policies_collection}'"
+            )
+        except TypeError:
+            # Fallback: adapter doesn't support collection parameter, use default
+            logger.warning(
+                "Adapter doesn't support custom collection name, " "using default collection"
+            )
+            adapter = Adapter(mongo_uri, db_name)
+            logger.debug("Casbin MotorAdapter created successfully (using default collection)")
+    except (RuntimeError, ValueError, AttributeError, TypeError, ConnectionError):
+        logger.exception("Failed to create Casbin MotorAdapter")
+        raise
 
     # Create enforcer with model and adapter
-    enforcer = casbin.AsyncEnforcer()
-    await enforcer.set_model(casbin.new_model_from_string(model_str))
-    enforcer.set_adapter(adapter)
-
-    # Load policies from database
-    await enforcer.load_policy()
-
-    # Create default roles if specified
-    if default_roles:
-        await _create_default_roles(enforcer, default_roles)
+    # AsyncEnforcer can accept model string or Model object
+    logger.debug("Creating Casbin AsyncEnforcer with model and adapter...")
+    try:
+        logger.debug(f"Model string length: {len(model_str)} chars")
+        logger.debug(f"Adapter type: {type(adapter)}")
+
+        # Create Model object from string
+        model = casbin.Model()
+        model.load_model_from_text(model_str)
+        logger.debug(f"Model object created successfully, type: {type(model)}")
+
+        # Create enforcer with Model object and adapter
+        # AsyncEnforcer auto-loads by default (auto_load=True), so we don't need manual load
+        logger.debug("Calling casbin.AsyncEnforcer(model, adapter)...")
+        enforcer = casbin.AsyncEnforcer(model, adapter)
+        logger.debug("Enforcer created successfully")
+
+        # Check if policies were auto-loaded
+        # If auto_load is enabled (default), policies are already loaded
+        # Only manually load if auto_load was disabled
+        if not getattr(enforcer, "auto_load", True):
+            logger.debug("Auto-load disabled, manually loading policies...")
+            await enforcer.load_policy()
+            logger.debug("Policies loaded successfully")
+        else:
+            logger.debug("Policies auto-loaded by AsyncEnforcer constructor")
+    except (RuntimeError, ValueError, AttributeError, TypeError, OSError):
+        logger.exception("Failed to create or configure Casbin enforcer")
+        # Try alternative: use temp file approach
+        logger.info("Attempting alternative: using temporary model file...")
+        try:
+            import os
+            import tempfile
+
+            with tempfile.NamedTemporaryFile(mode="w", suffix=".conf", delete=False) as f:
+                f.write(model_str)
+                temp_model_path = f.name
+            try:
+                enforcer = casbin.AsyncEnforcer(temp_model_path, adapter)
+                logger.info("✅ Enforcer created successfully using temp model file")
+                # Clean up temp file
+                os.unlink(temp_model_path)
+            except (RuntimeError, ValueError, AttributeError, TypeError, OSError) as e2:
+                if os.path.exists(temp_model_path):
+                    os.unlink(temp_model_path)
+                logger.exception("Alternative approach also failed")
+                raise RuntimeError("Failed to create Casbin enforcer") from e2
+        except (OSError, RuntimeError) as e2:
+            logger.exception("Failed to try alternative approach")
+            raise RuntimeError("Failed to create Casbin enforcer") from e2
+
+    # Note: Removed default_roles creation - roles exist implicitly when assigned to users
 
     logger.info(
         f"Casbin enforcer created with model '{model}' and "
@@ -104,40 +183,20 @@ async def create_casbin_enforcer(
     return enforcer
 
 
-async def _create_default_roles(enforcer: "casbin.AsyncEnforcer", roles: list) -> None:
-    """
-    Create default roles in Casbin (as grouping rules).
-
-    Args:
-        enforcer: Casbin AsyncEnforcer instance
-        roles: List of role names to create
-    """
-    for role in roles:
-        # Create a grouping rule: role -> role (self-reference for role existence)
-        # This ensures the role exists in the system
-        # Actual user-role assignments will be added when users are created
-        try:
-            # Check if role already exists
-            existing = await enforcer.get_roles_for_user(role)
-            if not existing:
-                # Add role as a self-grouping rule to ensure it exists
-                # This is a common pattern to "register" roles
-                await enforcer.add_grouping_policy(role, role)
-                logger.debug(f"Created default Casbin role: {role}")
-        except (AttributeError, TypeError, ValueError, RuntimeError) as e:
-            logger.warning(f"Error creating default role '{role}': {e}")
+# Removed _create_default_roles function - roles exist implicitly when assigned to users
+# No need to "create" roles beforehand with self-referencing policies
 
 
 async def initialize_casbin_from_manifest(
-    engine, app_slug: str, auth_config: Dict[str, Any]
-) -> Optional["CasbinAdapter"]:
+    engine, app_slug: str, auth_config: dict[str, Any]
+) -> Optional[CasbinAdapter]:
     """
     Initialize Casbin provider from manifest configuration.
 
     Args:
         engine: MongoDBEngine instance
         app_slug: App slug identifier
-        auth_config: Auth configuration dict from manifest (contains auth_policy)
+        auth_config: Full manifest config dict (contains auth.policy or auth_policy)
 
     Returns:
         CasbinAdapter instance if successfully created, None otherwise
@@ -145,42 +204,176 @@ async def initialize_casbin_from_manifest(
     try:
         from .provider import CasbinAdapter
 
-        auth_policy = auth_config.get("auth_policy", {})
+        # Support both old (auth_policy) and new (auth.policy) structures
+        auth = auth_config.get("auth", {})
+        auth_policy = auth.get("policy", {}) or auth_config.get("auth_policy", {})
         provider = auth_policy.get("provider", "casbin")
 
         # Only proceed if provider is casbin
         if provider != "casbin":
+            logger.debug(f"Provider is '{provider}', not 'casbin' - skipping Casbin initialization")
             return None
 
+        logger.info(f"Initializing Casbin provider for app '{app_slug}'...")
+
         # Get authorization config
         authorization = auth_policy.get("authorization", {})
         model = authorization.get("model", "rbac")
-        policies_collection = authorization.get(
-            "policies_collection", "casbin_policies"
-        )
+        policies_collection = authorization.get("policies_collection", "casbin_policies")
         default_roles = authorization.get("default_roles", [])
+        initial_policies = authorization.get("initial_policies", [])
+        initial_roles = authorization.get("initial_roles", [])
 
-        # Get database from engine
-        db = engine.get_database()
-
-        # Create enforcer
-        enforcer = await create_casbin_enforcer(
-            db=db,
-            model=model,
-            policies_collection=policies_collection,
-            default_roles=default_roles,
+        # Create enforcer with MongoDB connection info from engine
+        logger.debug(
+            f"Creating Casbin enforcer with URI: {engine.mongo_uri[:50]}..., "
+            f"db: {engine.db_name}"
         )
+        try:
+            enforcer = await create_casbin_enforcer(
+                mongo_uri=engine.mongo_uri,
+                db_name=engine.db_name,
+                model=model,
+                policies_collection=policies_collection,
+                default_roles=default_roles,
+            )
+            logger.debug("Casbin enforcer created successfully")
+        except (
+            RuntimeError,
+            ValueError,
+            AttributeError,
+            TypeError,
+            ConnectionError,
+            ImportError,
+        ):
+            logger.exception(f"Failed to create Casbin enforcer for '{app_slug}'")
+            return None
 
         # Create adapter
-        adapter = CasbinAdapter(enforcer)
+        try:
+            adapter = CasbinAdapter(enforcer)
+            logger.info("✅ CasbinAdapter created successfully")
+        except (RuntimeError, ValueError, AttributeError, TypeError):
+            logger.exception(f"Failed to create CasbinAdapter for '{app_slug}'")
+            return None
+
+        # Set up initial policies if configured
+        if initial_policies:
+            logger.info(f"Setting up {len(initial_policies)} initial policies...")
+            for policy in initial_policies:
+                if isinstance(policy, (list, tuple)) and len(policy) >= 3:
+                    role, resource, action = policy[0], policy[1], policy[2]
+                    try:
+                        # Check if policy already exists
+                        exists = await adapter.has_policy(role, resource, action)
+                        if exists:
+                            logger.debug(f"  Policy already exists: {role} -> {resource}:{action}")
+                        else:
+                            added = await adapter.add_policy(role, resource, action)
+                            if added:
+                                logger.debug(f"  Added policy: {role} -> {resource}:{action}")
+                            else:
+                                logger.warning(
+                                    f"  Failed to add policy: {role} -> " f"{resource}:{action}"
+                                )
+                    except (ValueError, TypeError, RuntimeError, AttributeError) as e:
+                        logger.warning(f"  Failed to add policy {policy}: {e}", exc_info=True)
+
+        # Set up initial role assignments if configured
+        # Disable auto_save during bulk operations for better performance
+        if initial_roles:
+            logger.info(f"Setting up {len(initial_roles)} initial role assignments...")
+            # Temporarily disable auto_save to avoid writing on every iteration
+            original_auto_save = getattr(enforcer, "auto_save", True)
+            try:
+                enforcer.auto_save = False
+                logger.debug("Disabled auto_save for bulk role assignment")
+            except AttributeError:
+                # Some enforcer implementations don't support auto_save attribute
+                logger.debug("auto_save attribute not available, proceeding with default behavior")
+
+            for role_assignment in initial_roles:
+                if isinstance(role_assignment, dict):
+                    user = role_assignment.get("user")
+                    role = role_assignment.get("role")
+                    if user and role:
+                        try:
+                            # Check if role assignment already exists
+                            exists = await adapter.has_role_for_user(user, role)
+                            logger.debug(
+                                f"  Checking role assignment: {user} -> {role}, " f"exists={exists}"
+                            )
+                            if exists:
+                                logger.info(f"  ✓ Role assignment already exists: {user} -> {role}")
+                            else:
+                                logger.info(f"  Adding role assignment: {user} -> {role}")
+                                # Use enforcer directly with add_grouping_policy
+                                added = await enforcer.add_grouping_policy(user, role)
+                                if added:
+                                    logger.info(
+                                        f"  ✓ Successfully assigned role '{role}' "
+                                        f"to user '{user}'"
+                                    )
+                                else:
+                                    logger.warning(
+                                        f"  ⚠ Failed to assign role '{role}' to "
+                                        f"user '{user}' - add_grouping_policy returned False"
+                                    )
+                        except (ValueError, TypeError, RuntimeError, AttributeError):
+                            logger.exception(f"  ✗ Exception assigning role {role_assignment}")
+
+            # Restore auto_save setting
+            if hasattr(enforcer, "auto_save"):
+                enforcer.auto_save = original_auto_save
+                logger.debug("Restored auto_save setting")
+
+        # Verify that policies and roles were set up correctly
+        if initial_policies:
+            verified = 0
+            for policy in initial_policies:
+                if isinstance(policy, (list, tuple)) and len(policy) >= 3:
+                    role, resource, action = policy[0], policy[1], policy[2]
+                    if await adapter.has_policy(role, resource, action):
+                        verified += 1
+            logger.info(f"Verified {verified}/{len(initial_policies)} policies exist in memory")
+
+        if initial_roles:
+            verified = 0
+            for role_assignment in initial_roles:
+                if isinstance(role_assignment, dict):
+                    user = role_assignment.get("user")
+                    role = role_assignment.get("role")
+                    if user and role and await adapter.has_role_for_user(user, role):
+                        verified += 1
+            logger.info(
+                f"Verified {verified}/{len(initial_roles)} role assignments " f"exist in memory"
+            )
+
+        # Save policies to persist them to database
+        # Only save if auto_save was disabled (to avoid double-saving)
+        if not getattr(enforcer, "auto_save", True):
+            saved = await adapter.save_policy()
+            if saved:
+                logger.debug("Policies saved to database successfully")
+            else:
+                logger.warning(
+                    "Failed to save policies to database - they may not " "persist across restarts"
+                )
+        else:
+            logger.debug(
+                "Skipping manual save_policy() - auto_save is enabled, "
+                "policies already persisted"
+            )
 
-        logger.info(f"Casbin provider initialized for app '{app_slug}'")
+        logger.info(f"✅ Casbin provider initialized for app '{app_slug}'")
+        logger.info(f"✅ CasbinAdapter ready for use - type: {type(adapter).__name__}")
 
         return adapter
 
     except ImportError as e:
+        # ImportError is expected if Casbin is not installed - use warning, not error
         logger.warning(
-            f"Casbin not available for app '{app_slug}': {e}. "
+            f"❌ Casbin not available for app '{app_slug}': {e}. "
             "Install with: pip install mdb-engine[casbin]"
         )
         return None
@@ -192,8 +385,10 @@ async def initialize_casbin_from_manifest(
         RuntimeError,
         KeyError,
     ) as e:
-        logger.error(
-            f"Error initializing Casbin provider for app '{app_slug}': {e}",
-            exc_info=True,
+        logger.exception(f"❌ Error initializing Casbin provider for app '{app_slug}': {e}")
+        # Informational message, not exception logging
+        logger.error(  # noqa: TRY400
+            f"❌ Casbin provider initialization FAILED for '{app_slug}' - "
+            "check logs above for detailed error information"
         )
         return None