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

mdb_engine/__init__.py

@@ -1,8 +1,11 @@
 """
 MDB_ENGINE - MongoDB Engine
 
-Enterprise-grade engine for building applications
-with automatic database scoping, authentication, and resource management.
+Enterprise-grade engine for building applications with:
+- Automatic database scoping and data isolation
+- Proper dependency injection with service lifetimes
+- Repository pattern for clean data access
+- Authentication and authorization
 
 Usage:
     # Simple usage
@@ -14,14 +17,19 @@ Usage:
     # With FastAPI integration
     app = engine.create_app(slug="my_app", manifest=Path("manifest.json"))
 
-    # With Ray support (optional)
-    engine = MongoDBEngine(..., enable_ray=True)
+    # In routes - use RequestContext for clean DI
+    from mdb_engine import RequestContext
+
+    @app.get("/users/{user_id}")
+    async def get_user(user_id: str, ctx: RequestContext = Depends()):
+        user = await ctx.uow.users.get(user_id)
+        return user
 """
 
 # Authentication
-from .auth import AuthorizationProvider, get_current_user, require_admin
+from .auth import AuthorizationProvider, require_admin
+from .auth import get_current_user as auth_get_current_user  # noqa: F401
 
-# Optional Ray integration
 # Core MongoDB Engine
 from .core import (
     RAY_AVAILABLE,
@@ -36,6 +44,30 @@ from .core import (
 # Database layer
 from .database import AppDB, ScopedMongoWrapper
 
+# FastAPI dependencies
+from .dependencies import (
+    Inject,
+    RequestContext,
+    get_app_config,
+    get_app_slug,
+    get_authz_provider,
+    get_current_user,
+    get_embedding_service,
+    get_engine,
+    get_llm_client,
+    get_llm_model_name,
+    get_memory_service,
+    get_scoped_db,
+    get_unit_of_work,
+    get_user_roles,
+    inject,
+    require_role,
+    require_user,
+)
+
+# DI Container
+from .di import Container, Scope, ScopeManager
+
 # Index management
 from .indexes import (
     AsyncAtlasIndexManager,
@@ -43,14 +75,17 @@ from .indexes import (
     run_index_creation_for_collection,
 )
 
-__version__ = "0.1.6"
+# Repository pattern
+from .repositories import Entity, MongoRepository, Repository, UnitOfWork
+
+__version__ = "0.2.0"  # Major version bump for new DI system
 
 __all__ = [
-    # Core (includes FastAPI integration and optional Ray)
+    # Core Engine
     "MongoDBEngine",
     "ManifestValidator",
     "ManifestParser",
-    # Ray Integration (optional - only active if Ray installed)
+    # Ray Integration (optional)
     "RAY_AVAILABLE",
     "AppRayActor",
     "get_ray_actor_handle",
@@ -58,10 +93,36 @@ __all__ = [
     # Database
     "ScopedMongoWrapper",
     "AppDB",
+    # DI Container
+    "Container",
+    "Scope",
+    "ScopeManager",
+    # Repository Pattern
+    "Repository",
+    "MongoRepository",
+    "Entity",
+    "UnitOfWork",
     # Auth
     "AuthorizationProvider",
-    "get_current_user",
     "require_admin",
+    # FastAPI Dependencies
+    "RequestContext",
+    "get_engine",
+    "get_app_slug",
+    "get_app_config",
+    "get_scoped_db",
+    "get_unit_of_work",
+    "get_embedding_service",
+    "get_memory_service",
+    "get_llm_client",
+    "get_llm_model_name",
+    "get_authz_provider",
+    "get_current_user",
+    "get_user_roles",
+    "require_user",
+    "require_role",
+    "inject",
+    "Inject",
     # Indexes
     "AsyncAtlasIndexManager",
     "AutoIndexManager",

mdb_engine/auth/ARCHITECTURE.md

@@ -0,0 +1,112 @@
+# Authorization Provider Architecture
+
+## Overview
+
+The authorization system uses the **Adapter Pattern** with a strict abstract base class to ensure type safety, fail-closed security, and proper abstraction from third-party libraries.
+
+## Design Principles
+
+1. **Adapter Pattern**: We wrap third-party libraries (Casbin, OSO) without modifying their source code
+2. **Fail-Closed Security**: If authorization evaluation fails, access is denied (never granted)
+3. **Type Safety**: Clear contracts with proper type hints and abstract methods
+4. **Interface Segregation**: Application code only needs `check()`, not engine internals
+5. **Observability**: Structured logging for all authorization decisions and errors
+
+## Architecture
+
+```
+BaseAuthorizationProvider (ABC)
+├── CasbinAdapter
+│   └── Wraps casbin.AsyncEnforcer
+└── OsoAdapter
+    └── Wraps oso_cloud.Client or oso.Oso
+```
+
+## Base Class: `BaseAuthorizationProvider`
+
+Defines the contract that all authorization providers must implement:
+
+- `check(subject, resource, action)` - Primary authorization decision method
+- `add_policy(*params)` - Add policy rules
+- `add_role_for_user(*params)` - Assign roles to users
+- `save_policy()` - Persist policies to storage
+- `has_policy(*params)` - Check if policy exists
+- `has_role_for_user(*params)` - Check if user has role
+- `clear_cache()` - Clear authorization cache
+
+### Fail-Closed Security
+
+All `check()` implementations must:
+1. Catch all exceptions during evaluation
+2. Log errors with full context
+3. Return `False` (deny access) on any error
+4. Never raise exceptions from evaluation failures
+
+### Error Handling
+
+- **Evaluation Errors**: Handled by `_handle_evaluation_error()` - denies access, logs critically
+- **Operation Errors**: Handled by `_handle_operation_error()` - returns False, logs warning
+
+## CasbinAdapter
+
+Wraps `casbin.AsyncEnforcer` and handles:
+- Casbin's `(subject, object, action)` format
+- Thread pool execution to prevent blocking
+- Caching for performance
+- MongoDB persistence via MotorAdapter
+
+### Format Mapping
+
+- `check(subject, resource, action)` → `enforcer.enforce(subject, resource, action)`
+- `add_policy(role, resource, action)` → `enforcer.add_policy(role, resource, action)`
+- `add_role_for_user(user, role)` → `enforcer.add_role_for_user(user, role)`
+
+## OsoAdapter
+
+Wraps OSO Cloud client and handles:
+- OSO's `authorize(actor, action, resource)` format
+- Type marshalling (strings → TypedObject)
+- Thread pool execution
+- Caching for performance
+
+### Format Mapping
+
+- `check(subject, resource, action)` → `client.authorize(TypedObject("User", subject), action, TypedObject("Document", resource))`
+- `add_policy(role, resource, action)` → `client.insert(["grants_permission", role, action, resource])`
+- `add_role_for_user(user, role, [resource])` → `client.insert(["has_role", Value("User", user), role, Value("Document", resource)])`
+
+## Backward Compatibility
+
+The `AuthorizationProvider` Protocol is maintained for backward compatibility. All adapters implement both:
+- The Protocol (for structural typing)
+- The BaseAuthorizationProvider ABC (for inheritance)
+
+## Usage
+
+```python
+from mdb_engine.auth import BaseAuthorizationProvider, CasbinAdapter, OsoAdapter
+
+# Type checking works with both Protocol and ABC
+async def check_permission(
+    provider: BaseAuthorizationProvider,  # or AuthorizationProvider
+    user: str,
+    resource: str,
+    action: str,
+) -> bool:
+    return await provider.check(user, resource, action)
+
+# Runtime type checking
+if provider.is_casbin():
+    # Casbin-specific operations
+    enforcer = provider._enforcer  # Still accessible
+elif provider.is_oso():
+    # OSO-specific operations
+    client = provider._oso  # Still accessible
+```
+
+## Migration Notes
+
+- Existing code using `AuthorizationProvider` Protocol continues to work
+- Code checking `hasattr(provider, "_enforcer")` continues to work
+- New code should use `BaseAuthorizationProvider` for better type safety
+- Helper methods `is_casbin()` and `is_oso()` available for type checking

mdb_engine/auth/README.md

@@ -926,18 +926,132 @@ CSRF protection is **auto-enabled for shared auth mode**. The middleware uses th
 4. SameSite=Lax cookies provide additional protection
 
 **Frontend Integration:**
+
+Helper function for reading cookies:
+
+```javascript
+// Reusable cookie helper
+function getCookie(name) {
+    const value = `; ${document.cookie}`;
+    const parts = value.split(`; ${name}=`);
+    if (parts.length === 2) return parts.pop().split(';').shift();
+    return null;
+}
+```
+
+Include in all state-changing requests:
+
+```javascript
+// POST request with CSRF token
+async function createItem(data) {
+    const response = await fetch('/api/items', {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            'X-CSRF-Token': getCookie('csrf_token')
+        },
+        credentials: 'same-origin',
+        body: JSON.stringify(data)
+    });
+    return response.json();
+}
+
+// DELETE request with CSRF token
+async function deleteItem(id) {
+    const response = await fetch(`/api/items/${id}`, {
+        method: 'DELETE',
+        headers: {
+            'X-CSRF-Token': getCookie('csrf_token')
+        },
+        credentials: 'same-origin'
+    });
+    return response.json();
+}
+```
+
+**Logout Must Be POST:**
+
+For security, logout endpoints should use POST method, not GET:
+
+```javascript
+// Correct: POST with CSRF token
+async function logout() {
+    const response = await fetch('/logout', {
+        method: 'POST',
+        headers: {
+            'X-CSRF-Token': getCookie('csrf_token')
+        },
+        credentials: 'same-origin'
+    });
+    
+    const result = await response.json();
+    if (result.success) {
+        window.location.href = result.redirect || '/login';
+    }
+}
+```
+
+Backend endpoint:
+
+```python
+@app.post("/logout")
+async def logout(request: Request):
+    """Logout must be POST with CSRF token."""
+    response = JSONResponse({"success": True, "redirect": "/login"})
+    response = await logout_user(request, response)
+    return response
+```
+
+**Login/Register JSON Pattern:**
+
+Return JSON responses for AJAX forms:
+
+```python
+@app.post("/login")
+async def login(request: Request, email: str = Form(...), password: str = Form(...)):
+    """Login returning JSON for JavaScript frontend."""
+    result = await authenticate_user(email, password)
+    
+    if result["success"]:
+        json_response = JSONResponse({"success": True, "redirect": "/dashboard"})
+        # Copy auth cookies from result
+        for key, value in result["response"].headers.items():
+            if key.lower() == "set-cookie":
+                json_response.headers.append(key, value)
+        return json_response
+    
+    return JSONResponse(
+        {"success": False, "detail": result.get("error", "Login failed")},
+        status_code=401
+    )
+```
+
+**Error Handling:**
+
+Handle CSRF validation failures (403 status):
+
 ```javascript
-// Read token from cookie
-const csrfToken = document.cookie
-  .split('; ')
-  .find(row => row.startsWith('csrf_token='))
-  ?.split('=')[1];
-
-// Include in requests
-fetch('/api/submit', {
-  method: 'POST',
-  headers: {'X-CSRF-Token': csrfToken}
-});
+async function secureRequest(url, options = {}) {
+    const response = await fetch(url, {
+        ...options,
+        headers: {
+            ...options.headers,
+            'X-CSRF-Token': getCookie('csrf_token')
+        },
+        credentials: 'same-origin'
+    });
+    
+    if (response.status === 403) {
+        const data = await response.json();
+        if (data.detail?.includes('CSRF')) {
+            // Token expired - refresh the page
+            window.location.reload();
+            return null;
+        }
+    }
+    
+    return response;
+}
 ```
 
 ### HSTS (HTTP Strict Transport Security)

mdb_engine/auth/__init__.py

@@ -9,6 +9,9 @@ This module is part of MDB_ENGINE - MongoDB Engine.
 # Audit logging
 from .audit import AuthAction, AuthAuditLog
 
+# Base classes
+from .base import AuthorizationError, BaseAuthorizationProvider
+
 # Casbin Factory
 from .casbin_factory import (
     create_casbin_enforcer,
@@ -123,7 +126,10 @@ from .utils import (
 )
 
 __all__ = [
-    # Provider
+    # Base classes
+    "BaseAuthorizationProvider",
+    "AuthorizationError",
+    # Provider (Protocol for backward compatibility)
     "AuthorizationProvider",
     "CasbinAdapter",
     "OsoAdapter",

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