proxilion 0.0.1__py3-none-any.whl

proxilion/engines/__init__.py

@@ -0,0 +1,287 @@
+"""
+Policy engines for Proxilion.
+
+This module provides the policy engine abstraction layer, enabling
+pluggable authorization backends. Available engines:
+
+- SimplePolicyEngine: Built-in engine using Policy classes (no dependencies)
+- CasbinPolicyEngine: Integration with Casbin (requires casbin package)
+- OPAPolicyEngine: Integration with Open Policy Agent (requires OPA server)
+
+Quick Start:
+    >>> from proxilion.engines import EngineFactory
+    >>>
+    >>> # Create a simple engine
+    >>> engine = EngineFactory.create("simple")
+    >>>
+    >>> # Or create with configuration
+    >>> engine = EngineFactory.create("casbin", {
+    ...     "model_path": "model.conf",
+    ...     "policy_path": "policy.csv",
+    ... })
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from proxilion.engines.base import (
+    BasePolicyEngine,
+    EngineCapabilities,
+    EngineNotAvailableError,
+    PolicyEngine,
+    PolicyEngineError,
+    PolicyEvaluationError,
+    PolicyLoadError,
+)
+from proxilion.engines.simple import SimplePolicyEngine
+
+logger = logging.getLogger(__name__)
+
+# Type alias for engine types
+EngineType = str  # "simple", "casbin", "opa"
+
+
+class EngineFactory:
+    """
+    Factory for creating policy engine instances.
+
+    The EngineFactory provides a unified interface for creating
+    policy engines based on configuration. It handles dependency
+    checking and provides helpful error messages when optional
+    engines are not available.
+
+    Example:
+        >>> # Create with default configuration
+        >>> engine = EngineFactory.create("simple")
+        >>>
+        >>> # Create with custom configuration
+        >>> engine = EngineFactory.create("casbin", {
+        ...     "model_path": "model.conf",
+        ...     "policy_path": "policy.csv",
+        ... })
+        >>>
+        >>> # Create OPA engine
+        >>> engine = EngineFactory.create("opa", {
+        ...     "opa_url": "http://localhost:8181",
+        ...     "policy_path": "v1/data/myapp/authz",
+        ... })
+
+    Available Engine Types:
+        - "simple": Built-in SimplePolicyEngine (always available)
+        - "casbin": CasbinPolicyEngine (requires casbin package)
+        - "opa": OPAPolicyEngine (requires OPA server)
+    """
+
+    # Registry of available engine types
+    _engines: dict[str, type[BasePolicyEngine]] = {
+        "simple": SimplePolicyEngine,
+    }
+
+    @classmethod
+    def create(
+        cls,
+        engine_type: str = "simple",
+        config: dict[str, Any] | None = None,
+    ) -> BasePolicyEngine:
+        """
+        Create a policy engine instance.
+
+        Args:
+            engine_type: The type of engine to create.
+            config: Engine-specific configuration.
+
+        Returns:
+            An initialized policy engine instance.
+
+        Raises:
+            EngineNotAvailableError: If the engine type is not available.
+            PolicyEngineError: If engine initialization fails.
+
+        Example:
+            >>> engine = EngineFactory.create("simple")
+            >>> engine = EngineFactory.create("casbin", {
+            ...     "model_path": "model.conf",
+            ...     "policy_path": "policy.csv",
+            ... })
+        """
+        engine_type = engine_type.lower()
+
+        # Handle casbin engine (lazy import due to optional dependency)
+        if engine_type == "casbin":
+            return cls._create_casbin_engine(config)
+
+        # Handle OPA engine
+        if engine_type == "opa":
+            return cls._create_opa_engine(config)
+
+        # Check built-in engines
+        if engine_type not in cls._engines:
+            available = cls.get_available_engines()
+            raise EngineNotAvailableError(
+                f"Unknown engine type: '{engine_type}'. "
+                f"Available engines: {', '.join(available)}",
+                engine_name=engine_type,
+            )
+
+        engine_class = cls._engines[engine_type]
+        return engine_class(config)
+
+    @classmethod
+    def _create_casbin_engine(
+        cls,
+        config: dict[str, Any] | None,
+    ) -> BasePolicyEngine:
+        """Create a Casbin engine instance."""
+        try:
+            from proxilion.engines.casbin_engine import CasbinPolicyEngine
+            return CasbinPolicyEngine(config)
+        except ImportError:
+            raise EngineNotAvailableError(
+                "Casbin engine requires the 'casbin' package. "
+                "Install with: pip install proxilion[casbin]",
+                engine_name="casbin",
+            ) from None
+
+    @classmethod
+    def _create_opa_engine(
+        cls,
+        config: dict[str, Any] | None,
+    ) -> BasePolicyEngine:
+        """Create an OPA engine instance."""
+        from proxilion.engines.opa_engine import OPAPolicyEngine
+        return OPAPolicyEngine(config)
+
+    @classmethod
+    def register(
+        cls,
+        engine_type: str,
+        engine_class: type[BasePolicyEngine],
+    ) -> None:
+        """
+        Register a custom engine type.
+
+        This allows extending Proxilion with custom policy engines.
+
+        Args:
+            engine_type: The name for this engine type.
+            engine_class: The engine class to register.
+
+        Example:
+            >>> class MyCustomEngine(BasePolicyEngine):
+            ...     def evaluate(self, user, action, resource, context=None):
+            ...         # Custom logic
+            ...         pass
+            >>>
+            >>> EngineFactory.register("custom", MyCustomEngine)
+            >>> engine = EngineFactory.create("custom")
+        """
+        cls._engines[engine_type.lower()] = engine_class
+        logger.debug(f"Registered engine type: {engine_type}")
+
+    @classmethod
+    def unregister(cls, engine_type: str) -> bool:
+        """
+        Unregister an engine type.
+
+        Args:
+            engine_type: The engine type to remove.
+
+        Returns:
+            True if the engine was unregistered.
+        """
+        engine_type = engine_type.lower()
+        if engine_type in cls._engines and engine_type != "simple":
+            del cls._engines[engine_type]
+            return True
+        return False
+
+    @classmethod
+    def get_available_engines(cls) -> list[str]:
+        """
+        Get a list of available engine types.
+
+        Returns:
+            List of engine type names that can be created.
+        """
+        engines = list(cls._engines.keys())
+
+        # Check if casbin is available
+        try:
+            import casbin  # noqa: F401
+            engines.append("casbin")
+        except ImportError:
+            pass
+
+        # OPA is always "available" (it just needs a server)
+        engines.append("opa")
+
+        return sorted(set(engines))
+
+    @classmethod
+    def is_available(cls, engine_type: str) -> bool:
+        """
+        Check if an engine type is available.
+
+        Args:
+            engine_type: The engine type to check.
+
+        Returns:
+            True if the engine can be created.
+        """
+        engine_type = engine_type.lower()
+
+        if engine_type in cls._engines:
+            return True
+
+        if engine_type == "casbin":
+            try:
+                import casbin  # noqa: F401
+                return True
+            except ImportError:
+                return False
+
+        return engine_type == "opa"
+
+
+# Convenience function for creating engines
+def create_engine(
+    engine_type: str = "simple",
+    config: dict[str, Any] | None = None,
+) -> BasePolicyEngine:
+    """
+    Create a policy engine instance.
+
+    Convenience function that delegates to EngineFactory.create().
+
+    Args:
+        engine_type: The type of engine to create.
+        config: Engine-specific configuration.
+
+    Returns:
+        An initialized policy engine instance.
+
+    Example:
+        >>> from proxilion.engines import create_engine
+        >>> engine = create_engine("simple")
+    """
+    return EngineFactory.create(engine_type, config)
+
+
+__all__ = [
+    # Protocol and base classes
+    "PolicyEngine",
+    "BasePolicyEngine",
+    "EngineCapabilities",
+    # Engines
+    "SimplePolicyEngine",
+    # Factory
+    "EngineFactory",
+    "create_engine",
+    # Exceptions
+    "PolicyEngineError",
+    "PolicyLoadError",
+    "PolicyEvaluationError",
+    "EngineNotAvailableError",
+]

proxilion/engines/base.py

@@ -0,0 +1,266 @@
+"""
+Policy engine base classes and protocols for Proxilion.
+
+This module defines the PolicyEngine protocol that all policy engines
+must implement, enabling pluggable authorization backends like
+Casbin, OPA, or custom implementations.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from abc import ABC, abstractmethod
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from proxilion.types import AuthorizationResult, UserContext
+
+
+@runtime_checkable
+class PolicyEngine(Protocol):
+    """
+    Protocol defining the interface for policy engines.
+
+    All policy engines must implement this protocol to be compatible
+    with Proxilion. This includes the built-in SimplePolicyEngine,
+    as well as optional integrations like Casbin and OPA.
+
+    The protocol requires both synchronous and asynchronous evaluation
+    methods to support different application architectures.
+
+    Example:
+        >>> class CustomEngine:
+        ...     def evaluate(
+        ...         self, user: UserContext, action: str,
+        ...         resource: str, context: dict
+        ...     ) -> AuthorizationResult:
+        ...         # Custom authorization logic
+        ...         return AuthorizationResult(allowed=True, reason="Custom check passed")
+        ...
+        ...     async def evaluate_async(
+        ...         self, user: UserContext, action: str,
+        ...         resource: str, context: dict
+        ...     ) -> AuthorizationResult:
+        ...         return self.evaluate(user, action, resource, context)
+        ...
+        ...     def load_policies(self, source: str | Path) -> None:
+        ...         pass
+    """
+
+    def evaluate(
+        self,
+        user: UserContext,
+        action: str,
+        resource: str,
+        context: dict[str, Any] | None = None,
+    ) -> AuthorizationResult:
+        """
+        Evaluate an authorization request synchronously.
+
+        Args:
+            user: The user context containing identity and roles.
+            action: The action being attempted (e.g., "read", "execute").
+            resource: The resource being accessed (e.g., "database_query").
+            context: Additional context for the authorization decision.
+
+        Returns:
+            AuthorizationResult indicating whether the action is allowed.
+        """
+        ...
+
+    async def evaluate_async(
+        self,
+        user: UserContext,
+        action: str,
+        resource: str,
+        context: dict[str, Any] | None = None,
+    ) -> AuthorizationResult:
+        """
+        Evaluate an authorization request asynchronously.
+
+        This method is useful for engines that need to make external
+        calls (e.g., OPA server) or perform I/O operations.
+
+        Args:
+            user: The user context containing identity and roles.
+            action: The action being attempted.
+            resource: The resource being accessed.
+            context: Additional context for the authorization decision.
+
+        Returns:
+            AuthorizationResult indicating whether the action is allowed.
+        """
+        ...
+
+    def load_policies(self, source: str | Path) -> None:
+        """
+        Load policies from a source.
+
+        The source format depends on the engine:
+        - SimplePolicyEngine: Python module path or directory
+        - CasbinPolicyEngine: Path to policy.csv file
+        - OPAPolicyEngine: Path to Rego files or OPA bundle
+
+        Args:
+            source: Path or identifier for the policy source.
+        """
+        ...
+
+
+class BasePolicyEngine(ABC):
+    """
+    Abstract base class for policy engines.
+
+    Provides common functionality and default implementations
+    for policy engines. Engines can extend this class instead
+    of implementing the Protocol directly.
+
+    Attributes:
+        name: Human-readable name for the engine.
+        config: Configuration dictionary passed during initialization.
+    """
+
+    name: str = "base"
+
+    def __init__(self, config: dict[str, Any] | None = None) -> None:
+        """
+        Initialize the policy engine.
+
+        Args:
+            config: Engine-specific configuration options.
+        """
+        self.config = config or {}
+        self._initialized = False
+
+    @abstractmethod
+    def evaluate(
+        self,
+        user: UserContext,
+        action: str,
+        resource: str,
+        context: dict[str, Any] | None = None,
+    ) -> AuthorizationResult:
+        """
+        Evaluate an authorization request.
+
+        Subclasses must implement this method.
+
+        Args:
+            user: The user context.
+            action: The action being attempted.
+            resource: The resource being accessed.
+            context: Additional context.
+
+        Returns:
+            AuthorizationResult with the decision.
+        """
+        pass
+
+    async def evaluate_async(
+        self,
+        user: UserContext,
+        action: str,
+        resource: str,
+        context: dict[str, Any] | None = None,
+    ) -> AuthorizationResult:
+        """
+        Async version of evaluate.
+
+        Default implementation wraps the sync version.
+        Override for truly async implementations.
+
+        Args:
+            user: The user context.
+            action: The action being attempted.
+            resource: The resource being accessed.
+            context: Additional context.
+
+        Returns:
+            AuthorizationResult with the decision.
+        """
+        # Run sync version in thread pool for non-blocking behavior
+        loop = asyncio.get_event_loop()
+        return await loop.run_in_executor(
+            None, self.evaluate, user, action, resource, context
+        )
+
+    def load_policies(self, source: str | Path) -> None:
+        """
+        Load policies from a source.
+
+        Default implementation does nothing. Override in subclasses
+        that support external policy loading.
+
+        Args:
+            source: Path or identifier for policy source.
+        """
+        pass
+
+    def is_initialized(self) -> bool:
+        """Check if the engine has been initialized."""
+        return self._initialized
+
+    def get_config(self, key: str, default: Any = None) -> Any:
+        """Get a configuration value."""
+        return self.config.get(key, default)
+
+
+class EngineCapabilities:
+    """
+    Describes the capabilities of a policy engine.
+
+    This class helps the Proxilion core understand what features
+    an engine supports, enabling graceful degradation when features
+    are unavailable.
+    """
+
+    def __init__(
+        self,
+        supports_async: bool = True,
+        supports_caching: bool = False,
+        supports_explain: bool = False,
+        supports_partial_eval: bool = False,
+        supports_hot_reload: bool = False,
+        max_batch_size: int = 1,
+    ) -> None:
+        """
+        Initialize engine capabilities.
+
+        Args:
+            supports_async: Whether async evaluation is truly async.
+            supports_caching: Whether the engine caches decisions.
+            supports_explain: Whether the engine can explain decisions.
+            supports_partial_eval: Whether partial evaluation is supported.
+            supports_hot_reload: Whether policies can be reloaded at runtime.
+            max_batch_size: Maximum number of requests in batch evaluation.
+        """
+        self.supports_async = supports_async
+        self.supports_caching = supports_caching
+        self.supports_explain = supports_explain
+        self.supports_partial_eval = supports_partial_eval
+        self.supports_hot_reload = supports_hot_reload
+        self.max_batch_size = max_batch_size
+
+
+class PolicyEngineError(Exception):
+    """Base exception for policy engine errors."""
+
+    def __init__(self, message: str, engine_name: str | None = None) -> None:
+        self.engine_name = engine_name
+        super().__init__(f"[{engine_name or 'unknown'}] {message}")
+
+
+class PolicyLoadError(PolicyEngineError):
+    """Raised when policies fail to load."""
+    pass
+
+
+class PolicyEvaluationError(PolicyEngineError):
+    """Raised when policy evaluation fails."""
+    pass
+
+
+class EngineNotAvailableError(PolicyEngineError):
+    """Raised when a required engine is not available."""
+    pass