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

mdb_engine/__init__.py

@@ -1,37 +1,142 @@
 """
 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
+    from mdb_engine import MongoDBEngine
+    engine = MongoDBEngine(mongo_uri=..., db_name=...)
+    await engine.initialize()
+    db = engine.get_scoped_db("my_app")
+
+    # With FastAPI integration
+    app = engine.create_app(slug="my_app", manifest=Path("manifest.json"))
+
+    # 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
+
 # Core MongoDB Engine
-from .core import ManifestParser, ManifestValidator, MongoDBEngine
+from .core import (
+    RAY_AVAILABLE,
+    AppRayActor,
+    ManifestParser,
+    ManifestValidator,
+    MongoDBEngine,
+    get_ray_actor_handle,
+    ray_actor_decorator,
+)
+
 # Database layer
-from .database import AppDB, ScopedMongoWrapper, get_shared_mongo_client
+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, AutoIndexManager,
-                      run_index_creation_for_collection)
+from .indexes import (
+    AsyncAtlasIndexManager,
+    AutoIndexManager,
+    run_index_creation_for_collection,
+)
+
+# Repository pattern
+from .repositories import Entity, MongoRepository, Repository, UnitOfWork
 
-__version__ = "0.1.6"
+# Utilities
+from .utils import clean_mongo_doc, clean_mongo_docs
+
+__version__ = (
+    "0.4.12"  # Fix CSRF middleware rejecting WebSocket connections
+    # - Skip CSRF middleware on child apps in multi-app setups (parent handles it)
+    # - Merge child app public routes into parent CSRF exempt list
+    # - WebSocket connections now work correctly in multi-app SSO setups
+    # - Security maintained: parent app CSRF middleware protects all routes
+)
 
 __all__ = [
-    # Core
+    # Core Engine
     "MongoDBEngine",
     "ManifestValidator",
     "ManifestParser",
+    # Ray Integration (optional)
+    "RAY_AVAILABLE",
+    "AppRayActor",
+    "get_ray_actor_handle",
+    "ray_actor_decorator",
     # Database
     "ScopedMongoWrapper",
     "AppDB",
-    "get_shared_mongo_client",
+    # 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",
     "run_index_creation_for_collection",
+    # Utilities
+    "clean_mongo_doc",
+    "clean_mongo_docs",
 ]

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