mdb-engine 0.1.7__tar.gz → 0.2.1__tar.gz

{mdb_engine-0.1.7/mdb_engine.egg-info → mdb_engine-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mdb-engine
-Version: 0.1.7
+Version: 0.2.1
 Summary: MongoDB Engine
 Home-page: https://github.com/ranfysvalle02/mdb-engine
 Author: Your Name
@@ -85,7 +85,9 @@ pip install mdb-engine
 
 ```python
 from pathlib import Path
+from fastapi import Depends
 from mdb_engine import MongoDBEngine
+from mdb_engine.dependencies import get_scoped_db
 
 # 1. Initialize the engine
 engine = MongoDBEngine(
@@ -96,10 +98,9 @@ engine = MongoDBEngine(
 # 2. Create a FastAPI app with automatic lifecycle management
 app = engine.create_app(slug="my_app", manifest=Path("manifest.json"))
 
-# 3. Use the scoped database - all queries automatically isolated
+# 3. Use request-scoped dependencies - all queries automatically isolated
 @app.post("/tasks")
-async def create_task(task: dict):
-    db = engine.get_scoped_db("my_app")
+async def create_task(task: dict, db=Depends(get_scoped_db)):
     result = await db.tasks.insert_one(task)
     return {"id": str(result.inserted_id)}
 ```
@@ -149,22 +150,29 @@ Supported index types: `regular`, `text`, `vector`, `ttl`, `compound`.
 
 ### 2. CRUD Operations (Auto-Scoped)
 
-All database operations are automatically scoped to your app:
+All database operations are automatically scoped to your app. Use `Depends(get_scoped_db)` in route handlers:
 
 ```python
-db = engine.get_scoped_db("my_app")
+from mdb_engine.dependencies import get_scoped_db
 
-# Create
-await db.tasks.insert_one({"title": "Build feature", "status": "pending"})
+@app.post("/tasks")
+async def create_task(task: dict, db=Depends(get_scoped_db)):
+    result = await db.tasks.insert_one(task)
+    return {"id": str(result.inserted_id)}
 
-# Read  
-tasks = await db.tasks.find({"status": "pending"}).to_list(length=10)
+@app.get("/tasks")
+async def list_tasks(db=Depends(get_scoped_db)):
+    return await db.tasks.find({"status": "pending"}).to_list(length=10)
 
-# Update
-await db.tasks.update_one({"_id": task_id}, {"$set": {"status": "done"}})
+@app.put("/tasks/{task_id}")
+async def update_task(task_id: str, db=Depends(get_scoped_db)):
+    await db.tasks.update_one({"_id": task_id}, {"$set": {"status": "done"}})
+    return {"updated": True}
 
-# Delete
-await db.tasks.delete_one({"_id": task_id})
+@app.delete("/tasks/{task_id}")
+async def delete_task(task_id: str, db=Depends(get_scoped_db)):
+    await db.tasks.delete_one({"_id": task_id})
+    return {"deleted": True}
 ```
 
 **What happens under the hood:**
@@ -210,6 +218,26 @@ async def health():
 | **Multi-App** | Secure cross-app data access | [Multi-App Example](https://github.com/ranfysvalle02/mdb-engine/tree/main/examples/advanced/multi_app) |
 | **SSO** | Shared auth across apps | [Shared Auth Example](https://github.com/ranfysvalle02/mdb-engine/tree/main/examples/advanced/multi_app_shared) |
 
+### AppContext — All Services in One Place ✨
+
+```python
+from fastapi import Depends
+from mdb_engine.dependencies import AppContext
+
+@app.post("/ai-chat")
+async def chat(query: str, ctx: AppContext = Depends()):
+    user = ctx.require_user()  # 401 if not logged in
+    ctx.require_role("user")   # 403 if missing role
+    
+    # Everything available: ctx.db, ctx.embedding_service, ctx.memory, ctx.llm
+    if ctx.llm:
+        response = ctx.llm.chat.completions.create(
+            model=ctx.llm_model,
+            messages=[{"role": "user", "content": query}]
+        )
+        return {"response": response.choices[0].message.content}
+```
+
 ---
 
 ## Full Examples

{mdb_engine-0.1.7 → mdb_engine-0.2.1}/README.md

@@ -20,7 +20,9 @@ pip install mdb-engine
 
 ```python
 from pathlib import Path
+from fastapi import Depends
 from mdb_engine import MongoDBEngine
+from mdb_engine.dependencies import get_scoped_db
 
 # 1. Initialize the engine
 engine = MongoDBEngine(
@@ -31,10 +33,9 @@ engine = MongoDBEngine(
 # 2. Create a FastAPI app with automatic lifecycle management
 app = engine.create_app(slug="my_app", manifest=Path("manifest.json"))
 
-# 3. Use the scoped database - all queries automatically isolated
+# 3. Use request-scoped dependencies - all queries automatically isolated
 @app.post("/tasks")
-async def create_task(task: dict):
-    db = engine.get_scoped_db("my_app")
+async def create_task(task: dict, db=Depends(get_scoped_db)):
     result = await db.tasks.insert_one(task)
     return {"id": str(result.inserted_id)}
 ```
@@ -84,22 +85,29 @@ Supported index types: `regular`, `text`, `vector`, `ttl`, `compound`.
 
 ### 2. CRUD Operations (Auto-Scoped)
 
-All database operations are automatically scoped to your app:
+All database operations are automatically scoped to your app. Use `Depends(get_scoped_db)` in route handlers:
 
 ```python
-db = engine.get_scoped_db("my_app")
+from mdb_engine.dependencies import get_scoped_db
 
-# Create
-await db.tasks.insert_one({"title": "Build feature", "status": "pending"})
+@app.post("/tasks")
+async def create_task(task: dict, db=Depends(get_scoped_db)):
+    result = await db.tasks.insert_one(task)
+    return {"id": str(result.inserted_id)}
 
-# Read  
-tasks = await db.tasks.find({"status": "pending"}).to_list(length=10)
+@app.get("/tasks")
+async def list_tasks(db=Depends(get_scoped_db)):
+    return await db.tasks.find({"status": "pending"}).to_list(length=10)
 
-# Update
-await db.tasks.update_one({"_id": task_id}, {"$set": {"status": "done"}})
+@app.put("/tasks/{task_id}")
+async def update_task(task_id: str, db=Depends(get_scoped_db)):
+    await db.tasks.update_one({"_id": task_id}, {"$set": {"status": "done"}})
+    return {"updated": True}
 
-# Delete
-await db.tasks.delete_one({"_id": task_id})
+@app.delete("/tasks/{task_id}")
+async def delete_task(task_id: str, db=Depends(get_scoped_db)):
+    await db.tasks.delete_one({"_id": task_id})
+    return {"deleted": True}
 ```
 
 **What happens under the hood:**
@@ -145,6 +153,26 @@ async def health():
 | **Multi-App** | Secure cross-app data access | [Multi-App Example](https://github.com/ranfysvalle02/mdb-engine/tree/main/examples/advanced/multi_app) |
 | **SSO** | Shared auth across apps | [Shared Auth Example](https://github.com/ranfysvalle02/mdb-engine/tree/main/examples/advanced/multi_app_shared) |
 
+### AppContext — All Services in One Place ✨
+
+```python
+from fastapi import Depends
+from mdb_engine.dependencies import AppContext
+
+@app.post("/ai-chat")
+async def chat(query: str, ctx: AppContext = Depends()):
+    user = ctx.require_user()  # 401 if not logged in
+    ctx.require_role("user")   # 403 if missing role
+    
+    # Everything available: ctx.db, ctx.embedding_service, ctx.memory, ctx.llm
+    if ctx.llm:
+        response = ctx.llm.chat.completions.create(
+            model=ctx.llm_model,
+            messages=[{"role": "user", "content": query}]
+        )
+        return {"response": response.choices[0].message.content}
+```
+
 ---
 
 ## Full Examples

mdb_engine-0.2.1/mdb_engine/__init__.py

@@ -0,0 +1,130 @@
+"""
+MDB_ENGINE - MongoDB Engine
+
+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, require_admin
+from .auth import get_current_user as auth_get_current_user  # noqa: F401
+
+# Core MongoDB Engine
+from .core import (
+    RAY_AVAILABLE,
+    AppRayActor,
+    ManifestParser,
+    ManifestValidator,
+    MongoDBEngine,
+    get_ray_actor_handle,
+    ray_actor_decorator,
+)
+
+# 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,
+    AutoIndexManager,
+    run_index_creation_for_collection,
+)
+
+# Repository pattern
+from .repositories import Entity, MongoRepository, Repository, UnitOfWork
+
+__version__ = "0.2.1"  # Major version bump for new DI system
+
+__all__ = [
+    # Core Engine
+    "MongoDBEngine",
+    "ManifestValidator",
+    "ManifestParser",
+    # Ray Integration (optional)
+    "RAY_AVAILABLE",
+    "AppRayActor",
+    "get_ray_actor_handle",
+    "ray_actor_decorator",
+    # Database
+    "ScopedMongoWrapper",
+    "AppDB",
+    # DI Container
+    "Container",
+    "Scope",
+    "ScopeManager",
+    # Repository Pattern
+    "Repository",
+    "MongoRepository",
+    "Entity",
+    "UnitOfWork",
+    # Auth
+    "AuthorizationProvider",
+    "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",
+]

mdb_engine-0.2.1/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-0.1.7 → mdb_engine-0.2.1}/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-0.1.7 → mdb_engine-0.2.1}/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",