mdb-engine 0.1.6__py3-none-any.whl

mdb_engine/auth/__init__.py

@@ -0,0 +1,128 @@
+"""
+Authentication and Authorization Module
+
+Provides authentication, authorization, and access control for the MongoDB Engine.
+
+This module is part of MDB_ENGINE - MongoDB Engine.
+"""
+
+# Casbin Factory
+from .casbin_factory import (create_casbin_enforcer, get_casbin_model,
+                             initialize_casbin_from_manifest)
+# Cookie utilities
+from .cookie_utils import (clear_auth_cookies, get_secure_cookie_settings,
+                           set_auth_cookies)
+# Decorators
+from .decorators import (auto_token_setup, rate_limit_auth, require_auth,
+                         token_security)
+from .dependencies import (SECRET_KEY, _validate_next_url, get_authz_provider,
+                           get_current_user, get_current_user_from_request,
+                           get_current_user_or_redirect, get_refresh_token,
+                           get_session_manager, get_token_blacklist,
+                           refresh_access_token, require_admin,
+                           require_admin_or_developer, require_permission)
+from .helpers import initialize_token_management
+# Integration
+from .integration import get_auth_config, setup_auth_from_manifest
+from .jwt import (decode_jwt_token, encode_jwt_token, extract_token_metadata,
+                  generate_token_pair)
+# Middleware
+from .middleware import SecurityMiddleware, create_security_middleware
+from .provider import (AUTHZ_CACHE_TTL, AuthorizationProvider, CasbinAdapter,
+                       OsoAdapter)
+from .restrictions import block_demo_users, is_demo_user, require_non_demo_user
+from .session_manager import SessionManager
+from .token_lifecycle import (get_time_until_expiry, get_token_age,
+                              get_token_expiry_time, get_token_info,
+                              is_token_expiring_soon, should_refresh_token,
+                              validate_token_version)
+# Token management
+from .token_store import TokenBlacklist
+from .users import (authenticate_app_user, create_app_session, create_app_user,
+                    ensure_demo_users_exist, ensure_demo_users_for_actor,
+                    get_app_user, get_app_user_role,
+                    get_or_create_anonymous_user, get_or_create_demo_user,
+                    get_or_create_demo_user_for_request,
+                    sync_app_user_to_casbin)
+# Utilities
+from .utils import (get_device_info, login_user, logout_user, register_user,
+                    validate_password_strength)
+
+__all__ = [
+    # Provider
+    "AuthorizationProvider",
+    "CasbinAdapter",
+    "OsoAdapter",
+    "AUTHZ_CACHE_TTL",
+    # JWT
+    "decode_jwt_token",
+    "encode_jwt_token",
+    "generate_token_pair",
+    "extract_token_metadata",
+    # Dependencies
+    "SECRET_KEY",
+    "get_authz_provider",
+    "get_current_user",
+    "get_current_user_from_request",
+    "require_admin",
+    "require_admin_or_developer",
+    "get_current_user_or_redirect",
+    "require_permission",
+    "_validate_next_url",
+    "get_token_blacklist",
+    "get_session_manager",
+    "get_refresh_token",
+    "refresh_access_token",
+    # App-level user management
+    "get_app_user",
+    "create_app_session",
+    "authenticate_app_user",
+    "create_app_user",
+    "get_or_create_anonymous_user",
+    "ensure_demo_users_exist",
+    "get_or_create_demo_user_for_request",
+    "get_or_create_demo_user",
+    "ensure_demo_users_for_actor",
+    "sync_app_user_to_casbin",
+    "get_app_user_role",
+    # Restrictions
+    "is_demo_user",
+    "require_non_demo_user",
+    "block_demo_users",
+    # Token Management
+    "TokenBlacklist",
+    "SessionManager",
+    "get_token_expiry_time",
+    "is_token_expiring_soon",
+    "should_refresh_token",
+    "get_token_age",
+    "get_time_until_expiry",
+    "validate_token_version",
+    "get_token_info",
+    "initialize_token_management",
+    # Utilities
+    "login_user",
+    "register_user",
+    "logout_user",
+    "validate_password_strength",
+    "get_device_info",
+    # Decorators
+    "require_auth",
+    "token_security",
+    "rate_limit_auth",
+    "auto_token_setup",
+    # Cookie utilities
+    "get_secure_cookie_settings",
+    "set_auth_cookies",
+    "clear_auth_cookies",
+    # Middleware
+    "SecurityMiddleware",
+    "create_security_middleware",
+    # Integration
+    "get_auth_config",
+    "setup_auth_from_manifest",
+    # Casbin Factory
+    "get_casbin_model",
+    "create_casbin_enforcer",
+    "initialize_casbin_from_manifest",
+]

mdb_engine/auth/casbin_factory.py

@@ -0,0 +1,199 @@
+"""
+Casbin Provider Factory
+
+Provides helper functions to auto-initialize Casbin authorization provider
+from manifest configuration.
+
+This module is part of MDB_ENGINE - MongoDB Engine.
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Dict, Optional
+
+from .casbin_models import DEFAULT_RBAC_MODEL, SIMPLE_ACL_MODEL
+
+if TYPE_CHECKING:
+    import casbin
+
+    from .provider import CasbinAdapter
+
+logger = logging.getLogger(__name__)
+
+
+def get_casbin_model(model_type: str = "rbac") -> str:
+    """
+    Get Casbin model string by type or path.
+
+    Args:
+        model_type: Model type ("rbac", "acl") or path to model file
+
+    Returns:
+        Casbin model string
+    """
+    if model_type == "rbac":
+        return DEFAULT_RBAC_MODEL
+    elif model_type == "acl":
+        return SIMPLE_ACL_MODEL
+    else:
+        # Assume it's a file path
+        model_path = Path(model_type)
+        if model_path.exists():
+            return model_path.read_text()
+        else:
+            logger.warning(
+                f"Casbin model file not found: {model_type}, using default RBAC model"
+            )
+            return DEFAULT_RBAC_MODEL
+
+
+async def create_casbin_enforcer(
+    db,
+    model: str = "rbac",
+    policies_collection: str = "casbin_policies",
+    default_roles: Optional[list] = None,
+) -> casbin.AsyncEnforcer:
+    """
+    Create a Casbin AsyncEnforcer with MongoDB adapter.
+
+    Args:
+        db: MongoDB database instance (Motor AsyncIOMotorDatabase)
+        model: Casbin model type ("rbac", "acl") or path to model file
+        policies_collection: MongoDB collection name for policies
+        default_roles: List of default roles to create (optional)
+
+    Returns:
+        Configured Casbin AsyncEnforcer instance
+
+    Raises:
+        ImportError: If casbin or casbin-motor-adapter is not installed
+    """
+    try:
+        import casbin
+        from casbin_motor_adapter import MotorAdapter
+    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)
+
+    # Create MongoDB adapter
+    adapter = MotorAdapter(db, policies_collection)
+
+    # 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)
+
+    logger.info(
+        f"Casbin enforcer created with model '{model}' and "
+        f"policies collection '{policies_collection}'"
+    )
+
+    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}")
+
+
+async def initialize_casbin_from_manifest(
+    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)
+
+    Returns:
+        CasbinAdapter instance if successfully created, None otherwise
+    """
+    try:
+        from .provider import CasbinAdapter
+
+        auth_policy = auth_config.get("auth_policy", {})
+        provider = auth_policy.get("provider", "casbin")
+
+        # Only proceed if provider is casbin
+        if provider != "casbin":
+            return None
+
+        # Get authorization config
+        authorization = auth_policy.get("authorization", {})
+        model = authorization.get("model", "rbac")
+        policies_collection = authorization.get(
+            "policies_collection", "casbin_policies"
+        )
+        default_roles = authorization.get("default_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 adapter
+        adapter = CasbinAdapter(enforcer)
+
+        logger.info(f"Casbin provider initialized for app '{app_slug}'")
+
+        return adapter
+
+    except ImportError as e:
+        logger.warning(
+            f"Casbin not available for app '{app_slug}': {e}. "
+            "Install with: pip install mdb-engine[casbin]"
+        )
+        return None
+    except (
+        ImportError,
+        AttributeError,
+        TypeError,
+        ValueError,
+        RuntimeError,
+        KeyError,
+    ) as e:
+        logger.error(
+            f"Error initializing Casbin provider for app '{app_slug}': {e}",
+            exc_info=True,
+        )
+        return None

mdb_engine/auth/casbin_models.py

@@ -0,0 +1,46 @@
+"""
+Default Casbin Models
+
+Provides default Casbin model configurations for authorization.
+
+This module is part of MDB_ENGINE - MongoDB Engine.
+"""
+
+# Default RBAC (Role-Based Access Control) model
+# This model supports:
+# - Subject (user/role) -> Object (resource) -> Action (permission)
+# - Role inheritance via g (grouping) rules
+# - Policy effect: allow if any policy matches
+
+DEFAULT_RBAC_MODEL = """
+[request_definition]
+r = sub, obj, act
+
+[policy_definition]
+p = sub, obj, act
+
+[role_definition]
+g = _, _
+
+[policy_effect]
+e = some(where (p.eft == allow))
+
+[matchers]
+m = g(r.sub, p.sub) && r.obj == p.obj && r.act == p.act
+"""
+
+# Alternative: Simple ACL model (no roles)
+# Use this if you don't need role-based access control
+SIMPLE_ACL_MODEL = """
+[request_definition]
+r = sub, obj, act
+
+[policy_definition]
+p = sub, obj, act
+
+[policy_effect]
+e = some(where (p.eft == allow))
+
+[matchers]
+m = r.sub == p.sub && r.obj == p.obj && r.act == p.act
+"""

mdb_engine/auth/config_defaults.py

@@ -0,0 +1,71 @@
+"""
+Authentication Configuration Defaults
+
+Centralized default values for all authentication and security configurations.
+This module provides a single source of truth for all config defaults.
+
+This module is part of MDB_ENGINE - MongoDB Engine.
+"""
+
+from typing import Any, Dict
+
+SECURITY_CONFIG_DEFAULTS: Dict[str, Any] = {
+    "password_policy": {
+        "allow_plain_text": False,
+        "min_length": 8,
+        "require_uppercase": True,
+        "require_lowercase": True,
+        "require_numbers": True,
+        "require_special": False,
+    },
+    "session_fingerprinting": {
+        "enabled": True,
+        "validate_on_login": True,
+        "validate_on_refresh": True,
+        "validate_on_request": False,
+        "strict_mode": False,
+    },
+    "account_lockout": {
+        "enabled": True,
+        "max_failed_attempts": 5,
+        "lockout_duration_seconds": 900,
+        "reset_on_success": True,
+    },
+    "ip_validation": {"enabled": False, "strict": False, "allow_ip_change": True},
+    "token_fingerprinting": {"enabled": True, "bind_to_device": True},
+}
+
+TOKEN_MANAGEMENT_DEFAULTS: Dict[str, Any] = {
+    "enabled": True,
+    "access_token_ttl": 900,
+    "refresh_token_ttl": 604800,
+    "token_rotation": True,
+    "max_sessions_per_user": 10,
+    "session_inactivity_timeout": 1800,
+    "auto_setup": True,
+}
+
+CORS_DEFAULTS: Dict[str, Any] = {
+    "enabled": False,
+    "allow_origins": ["*"],
+    "allow_credentials": False,
+    "allow_methods": ["GET", "POST", "PUT", "DELETE", "PATCH"],
+    "allow_headers": ["*"],
+    "max_age": 3600,
+}
+
+OBSERVABILITY_DEFAULTS: Dict[str, Any] = {
+    "health_checks": {"enabled": True, "endpoint": "/health", "interval_seconds": 30},
+    "metrics": {
+        "enabled": True,
+        "collect_operation_metrics": True,
+        "collect_performance_metrics": True,
+        "custom_metrics": [],
+    },
+    "logging": {
+        "level": "INFO",
+        "format": "json",
+        "include_request_id": True,
+        "log_sensitive_data": False,
+    },
+}

mdb_engine/auth/config_helpers.py

@@ -0,0 +1,213 @@
+"""
+Authentication Config Helper Utilities
+
+Type-safe utility functions for accessing and merging authentication configurations
+from manifest.json and app.state.
+
+This module is part of MDB_ENGINE - MongoDB Engine.
+"""
+
+import logging
+from typing import Any, Dict
+
+from fastapi import Request
+
+from .config_defaults import (CORS_DEFAULTS, OBSERVABILITY_DEFAULTS,
+                              SECURITY_CONFIG_DEFAULTS,
+                              TOKEN_MANAGEMENT_DEFAULTS)
+
+logger = logging.getLogger(__name__)
+
+
+def merge_config_with_defaults(
+    user_config: Dict[str, Any], defaults: Dict[str, Any]
+) -> Dict[str, Any]:
+    """
+    Deep merge user config with defaults.
+
+    User config values take precedence over defaults. Nested dictionaries
+    are merged recursively.
+
+    Args:
+        user_config: User-provided configuration (from manifest)
+        defaults: Default configuration values
+
+    Returns:
+        Merged configuration dictionary
+    """
+    if not user_config:
+        return defaults.copy()
+
+    if not defaults:
+        return user_config.copy()
+
+    merged = defaults.copy()
+
+    for key, value in user_config.items():
+        if key in merged and isinstance(merged[key], dict) and isinstance(value, dict):
+            merged[key] = merge_config_with_defaults(value, merged[key])
+        else:
+            merged[key] = value
+
+    return merged
+
+
+def get_security_config(request: Request) -> Dict[str, Any]:
+    """
+    Get security configuration from app.state with defaults merged.
+
+    Args:
+        request: FastAPI Request object
+
+    Returns:
+        Security configuration dictionary with defaults applied
+    """
+    try:
+        security_config = getattr(request.app.state, "security_config", None)
+        if security_config:
+            return merge_config_with_defaults(security_config, SECURITY_CONFIG_DEFAULTS)
+        return SECURITY_CONFIG_DEFAULTS.copy()
+    except (AttributeError, TypeError, KeyError) as e:
+        logger.warning(f"Error getting security config: {e}, using defaults")
+        return SECURITY_CONFIG_DEFAULTS.copy()
+
+
+def get_password_policy(request: Request) -> Dict[str, Any]:
+    """
+    Get password policy configuration with defaults merged.
+
+    Args:
+        request: FastAPI Request object
+
+    Returns:
+        Password policy configuration dictionary
+    """
+    security_config = get_security_config(request)
+    return security_config.get(
+        "password_policy", SECURITY_CONFIG_DEFAULTS["password_policy"].copy()
+    )
+
+
+def get_session_fingerprinting_config(request: Request) -> Dict[str, Any]:
+    """
+    Get session fingerprinting configuration with defaults merged.
+
+    Args:
+        request: FastAPI Request object
+
+    Returns:
+        Session fingerprinting configuration dictionary
+    """
+    security_config = get_security_config(request)
+    return security_config.get(
+        "session_fingerprinting",
+        SECURITY_CONFIG_DEFAULTS["session_fingerprinting"].copy(),
+    )
+
+
+def get_account_lockout_config(request: Request) -> Dict[str, Any]:
+    """
+    Get account lockout configuration with defaults merged.
+
+    Args:
+        request: FastAPI Request object
+
+    Returns:
+        Account lockout configuration dictionary
+    """
+    security_config = get_security_config(request)
+    return security_config.get(
+        "account_lockout", SECURITY_CONFIG_DEFAULTS["account_lockout"].copy()
+    )
+
+
+def get_ip_validation_config(request: Request) -> Dict[str, Any]:
+    """
+    Get IP validation configuration with defaults merged.
+
+    Args:
+        request: FastAPI Request object
+
+    Returns:
+        IP validation configuration dictionary
+    """
+    security_config = get_security_config(request)
+    return security_config.get(
+        "ip_validation", SECURITY_CONFIG_DEFAULTS["ip_validation"].copy()
+    )
+
+
+def get_token_fingerprinting_config(request: Request) -> Dict[str, Any]:
+    """
+    Get token fingerprinting configuration with defaults merged.
+
+    Args:
+        request: FastAPI Request object
+
+    Returns:
+        Token fingerprinting configuration dictionary
+    """
+    security_config = get_security_config(request)
+    return security_config.get(
+        "token_fingerprinting", SECURITY_CONFIG_DEFAULTS["token_fingerprinting"].copy()
+    )
+
+
+def get_token_management_config(request: Request) -> Dict[str, Any]:
+    """
+    Get token management configuration from app.state with defaults merged.
+
+    Args:
+        request: FastAPI Request object
+
+    Returns:
+        Token management configuration dictionary with defaults applied
+    """
+    try:
+        token_config = getattr(request.app.state, "token_management_config", None)
+        if token_config:
+            return merge_config_with_defaults(token_config, TOKEN_MANAGEMENT_DEFAULTS)
+        return TOKEN_MANAGEMENT_DEFAULTS.copy()
+    except (AttributeError, TypeError, KeyError) as e:
+        logger.warning(f"Error getting token management config: {e}, using defaults")
+        return TOKEN_MANAGEMENT_DEFAULTS.copy()
+
+
+def get_cors_config(request: Request) -> Dict[str, Any]:
+    """
+    Get CORS configuration from app.state with defaults merged.
+
+    Args:
+        request: FastAPI Request object
+
+    Returns:
+        CORS configuration dictionary with defaults applied
+    """
+    try:
+        cors_config = getattr(request.app.state, "cors_config", None)
+        if cors_config:
+            return merge_config_with_defaults(cors_config, CORS_DEFAULTS)
+        return CORS_DEFAULTS.copy()
+    except (AttributeError, TypeError, KeyError) as e:
+        logger.warning(f"Error getting CORS config: {e}, using defaults")
+        return CORS_DEFAULTS.copy()
+
+
+def get_observability_config(request: Request) -> Dict[str, Any]:
+    """
+    Get observability configuration from app.state with defaults merged.
+
+    Args:
+        request: FastAPI Request object
+
+    Returns:
+        Observability configuration dictionary with defaults applied
+    """
+    try:
+        obs_config = getattr(request.app.state, "observability_config", None)
+        if obs_config:
+            return merge_config_with_defaults(obs_config, OBSERVABILITY_DEFAULTS)
+        return OBSERVABILITY_DEFAULTS.copy()
+    except (AttributeError, TypeError, KeyError) as e:
+        logger.warning(f"Error getting observability config: {e}, using defaults")
+        return OBSERVABILITY_DEFAULTS.copy()