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

mdb_engine/auth/cookie_utils.py

@@ -51,8 +51,7 @@ def get_secure_cookie_settings(
             # Auto-detect: secure if HTTPS or production environment
             is_https = request.url.scheme == "https"
             is_production = (
-                os.getenv("G_NOME_ENV") == "production"
-                or os.getenv("ENVIRONMENT") == "production"
+                os.getenv("G_NOME_ENV") == "production" or os.getenv("ENVIRONMENT") == "production"
             )
             secure = is_https or is_production
         elif cookie_secure == "true":
@@ -63,8 +62,7 @@ def get_secure_cookie_settings(
         # No config - use environment-based defaults
         is_https = request.url.scheme == "https"
         is_production = (
-            os.getenv("G_NOME_ENV") == "production"
-            or os.getenv("ENVIRONMENT") == "production"
+            os.getenv("G_NOME_ENV") == "production" or os.getenv("ENVIRONMENT") == "production"
         )
         secure = is_https or is_production
 
@@ -153,6 +151,4 @@ def clear_auth_cookies(response, request: Optional[Request] = None):
     response.delete_cookie(key="token", httponly=True, secure=secure, samesite=samesite)
 
     # Delete refresh token cookie
-    response.delete_cookie(
-        key="refresh_token", httponly=True, secure=secure, samesite=samesite
-    )
+    response.delete_cookie(key="refresh_token", httponly=True, secure=secure, samesite=samesite)

mdb_engine/auth/csrf.py

@@ -0,0 +1,373 @@
+"""
+CSRF Protection Middleware
+
+Implements the Double-Submit Cookie pattern for Cross-Site Request Forgery protection.
+Auto-enabled for shared auth mode, with manifest-configurable options.
+
+This module is part of MDB_ENGINE - MongoDB Engine.
+
+Security Features:
+    - Double-submit cookie pattern (industry standard)
+    - Cryptographically secure token generation
+    - Configurable exempt routes for APIs
+    - SameSite cookie attribute for additional protection
+    - Token rotation on each request (optional)
+
+Usage:
+    # Auto-enabled for shared auth mode in engine.create_app()
+
+    # Or manual usage:
+    from mdb_engine.auth.csrf import CSRFMiddleware
+    app.add_middleware(CSRFMiddleware, exempt_routes=["/api/*"])
+
+    # In templates, include the token:
+    <input type="hidden" name="csrf_token" value="{{ csrf_token }}">
+
+    # Or in JavaScript:
+    fetch('/endpoint', {
+        headers: {'X-CSRF-Token': getCookie('csrf_token')}
+    })
+"""
+
+import fnmatch
+import hashlib
+import hmac
+import logging
+import os
+import secrets
+import time
+from typing import Any, Awaitable, Callable, Dict, List, Optional, Set
+
+from fastapi import Request, Response, status
+from fastapi.responses import JSONResponse
+from starlette.middleware.base import BaseHTTPMiddleware
+
+logger = logging.getLogger(__name__)
+
+# Token settings
+CSRF_TOKEN_LENGTH = 32  # 256 bits
+CSRF_COOKIE_NAME = "csrf_token"
+CSRF_HEADER_NAME = "X-CSRF-Token"
+CSRF_FORM_FIELD = "csrf_token"
+DEFAULT_TOKEN_TTL = 3600  # 1 hour
+
+# Methods that require CSRF validation
+UNSAFE_METHODS = {"POST", "PUT", "DELETE", "PATCH"}
+
+
+def generate_csrf_token(secret: Optional[str] = None) -> str:
+    """
+    Generate a cryptographically secure CSRF token.
+
+    Args:
+        secret: Optional secret for HMAC signing (adds tamper detection)
+
+    Returns:
+        URL-safe base64 encoded token
+    """
+    raw_token = secrets.token_urlsafe(CSRF_TOKEN_LENGTH)
+
+    if secret:
+        # Add HMAC signature for tamper detection
+        timestamp = str(int(time.time()))
+        message = f"{raw_token}:{timestamp}"
+        signature = hmac.new(secret.encode(), message.encode(), hashlib.sha256).hexdigest()[:16]
+        return f"{raw_token}:{timestamp}:{signature}"
+
+    return raw_token
+
+
+def validate_csrf_token(
+    token: str,
+    secret: Optional[str] = None,
+    max_age: int = DEFAULT_TOKEN_TTL,
+) -> bool:
+    """
+    Validate a CSRF token.
+
+    Args:
+        token: The token to validate
+        secret: Optional secret for HMAC verification
+        max_age: Maximum token age in seconds
+
+    Returns:
+        True if valid, False otherwise
+    """
+    if not token:
+        return False
+
+    if secret and ":" in token:
+        # Verify HMAC-signed token
+        try:
+            parts = token.split(":")
+            if len(parts) != 3:
+                return False
+
+            raw_token, timestamp_str, signature = parts
+            timestamp = int(timestamp_str)
+
+            # Check age
+            if time.time() - timestamp > max_age:
+                logger.debug("CSRF token expired")
+                return False
+
+            # Verify signature
+            message = f"{raw_token}:{timestamp_str}"
+            expected_sig = hmac.new(secret.encode(), message.encode(), hashlib.sha256).hexdigest()[
+                :16
+            ]
+
+            if not hmac.compare_digest(signature, expected_sig):
+                logger.warning("CSRF token signature mismatch")
+                return False
+
+            return True
+        except (ValueError, IndexError) as e:
+            logger.warning(f"CSRF token validation error: {e}")
+            return False
+
+    # Simple token validation (just check it exists and has reasonable length)
+    return len(token) >= CSRF_TOKEN_LENGTH
+
+
+class CSRFMiddleware(BaseHTTPMiddleware):
+    """
+    CSRF Protection Middleware using Double-Submit Cookie pattern.
+
+    The double-submit cookie pattern works by:
+    1. Setting a CSRF token in a cookie (with HttpOnly=False so JS can read it)
+    2. Requiring the same token in a header or form field
+    3. Since attackers can't read cookies from other domains, they can't forge requests
+
+    Additional protection from SameSite=Lax cookies prevents the browser from
+    sending cookies on cross-site requests.
+    """
+
+    def __init__(
+        self,
+        app,
+        secret: Optional[str] = None,
+        exempt_routes: Optional[List[str]] = None,
+        exempt_methods: Optional[Set[str]] = None,
+        cookie_name: str = CSRF_COOKIE_NAME,
+        header_name: str = CSRF_HEADER_NAME,
+        form_field: str = CSRF_FORM_FIELD,
+        token_ttl: int = DEFAULT_TOKEN_TTL,
+        rotate_tokens: bool = False,
+        secure_cookies: bool = True,
+    ):
+        """
+        Initialize CSRF middleware.
+
+        Args:
+            app: FastAPI application
+            secret: Secret for HMAC token signing (recommended for production)
+            exempt_routes: Routes exempt from CSRF (supports wildcards: /api/*)
+            exempt_methods: HTTP methods exempt from CSRF (default: safe methods)
+            cookie_name: Name of the CSRF cookie
+            header_name: Name of the CSRF header
+            form_field: Name of the CSRF form field
+            token_ttl: Token time-to-live in seconds
+            rotate_tokens: Rotate token on each request (more secure, less convenient)
+            secure_cookies: Use Secure cookie flag (auto-detect HTTPS)
+        """
+        super().__init__(app)
+        self.secret = secret or os.getenv("MDB_ENGINE_CSRF_SECRET")
+        self.exempt_routes = exempt_routes or []
+        self.exempt_methods = exempt_methods or {"GET", "HEAD", "OPTIONS", "TRACE"}
+        self.cookie_name = cookie_name
+        self.header_name = header_name
+        self.form_field = form_field
+        self.token_ttl = token_ttl
+        self.rotate_tokens = rotate_tokens
+        self.secure_cookies = secure_cookies
+
+        logger.info(
+            f"CSRFMiddleware initialized (exempt_routes={self.exempt_routes}, "
+            f"rotate_tokens={rotate_tokens})"
+        )
+
+    def _is_exempt(self, path: str) -> bool:
+        """Check if a path is exempt from CSRF validation."""
+        for pattern in self.exempt_routes:
+            if fnmatch.fnmatch(path, pattern):
+                return True
+        return False
+
+    async def dispatch(
+        self,
+        request: Request,
+        call_next: Callable[[Request], Awaitable[Response]],
+    ) -> Response:
+        """
+        Process request through CSRF middleware.
+        """
+        path = request.url.path
+        method = request.method
+
+        # Skip exempt routes
+        if self._is_exempt(path):
+            return await call_next(request)
+
+        # Skip safe methods
+        if method in self.exempt_methods:
+            # Generate and set token for GET requests (for forms)
+            response = await call_next(request)
+
+            # Set CSRF token cookie if not present
+            if not request.cookies.get(self.cookie_name):
+                token = generate_csrf_token(self.secret)
+                self._set_csrf_cookie(request, response, token)
+
+            # Make token available in request state for templates
+            request.state.csrf_token = request.cookies.get(self.cookie_name) or generate_csrf_token(
+                self.secret
+            )
+
+            return response
+
+        # Validate CSRF token for unsafe methods
+        cookie_token = request.cookies.get(self.cookie_name)
+        if not cookie_token:
+            logger.warning(f"CSRF cookie missing for {method} {path}")
+            return JSONResponse(
+                status_code=status.HTTP_403_FORBIDDEN,
+                content={"detail": "CSRF token missing"},
+            )
+
+        # Get token from header or form
+        header_token = request.headers.get(self.header_name)
+        form_token = None
+
+        # Note: Form-based CSRF token extraction not implemented.
+        # For now, we rely on header-based CSRF for all requests.
+        # TODO: Implement request.form() based extraction if needed.
+
+        submitted_token = header_token or form_token
+
+        if not submitted_token:
+            logger.warning(f"CSRF token not submitted for {method} {path}")
+            return JSONResponse(
+                status_code=status.HTTP_403_FORBIDDEN,
+                content={"detail": "CSRF token not provided in header or form"},
+            )
+
+        # Compare tokens (constant-time comparison)
+        if not hmac.compare_digest(cookie_token, submitted_token):
+            logger.warning(f"CSRF token mismatch for {method} {path}")
+            return JSONResponse(
+                status_code=status.HTTP_403_FORBIDDEN,
+                content={"detail": "CSRF token invalid"},
+            )
+
+        # Validate token (check signature if secret is used)
+        if self.secret and not validate_csrf_token(cookie_token, self.secret, self.token_ttl):
+            logger.warning(f"CSRF token validation failed for {method} {path}")
+            return JSONResponse(
+                status_code=status.HTTP_403_FORBIDDEN,
+                content={"detail": "CSRF token expired or invalid"},
+            )
+
+        # Process request
+        response = await call_next(request)
+
+        # Optionally rotate token
+        if self.rotate_tokens:
+            new_token = generate_csrf_token(self.secret)
+            self._set_csrf_cookie(request, response, new_token)
+
+        return response
+
+    def _set_csrf_cookie(
+        self,
+        request: Request,
+        response: Response,
+        token: str,
+    ) -> None:
+        """Set the CSRF token cookie."""
+        is_https = request.url.scheme == "https"
+        is_production = os.getenv("ENVIRONMENT", "").lower() == "production"
+
+        response.set_cookie(
+            key=self.cookie_name,
+            value=token,
+            httponly=False,  # Must be readable by JavaScript
+            secure=self.secure_cookies and (is_https or is_production),
+            samesite="lax",  # Provides CSRF protection + allows top-level navigation
+            max_age=self.token_ttl,
+            path="/",
+        )
+
+
+def create_csrf_middleware(
+    manifest_auth: Dict[str, Any],
+    secret: Optional[str] = None,
+) -> type:
+    """
+    Create CSRF middleware from manifest configuration.
+
+    Args:
+        manifest_auth: Auth section from manifest
+        secret: Optional CSRF secret (defaults to env var)
+
+    Returns:
+        Configured CSRFMiddleware class
+    """
+    csrf_config = manifest_auth.get("csrf_protection", True)
+
+    # Handle boolean or object config
+    if isinstance(csrf_config, bool):
+        if not csrf_config:
+            # Return a no-op middleware
+            class NoOpMiddleware(BaseHTTPMiddleware):
+                async def dispatch(self, request, call_next):
+                    return await call_next(request)
+
+            return NoOpMiddleware
+
+        # Use defaults
+        exempt_routes = manifest_auth.get("public_routes", [])
+        rotate_tokens = False
+        token_ttl = DEFAULT_TOKEN_TTL
+    else:
+        # Object configuration
+        exempt_routes = csrf_config.get("exempt_routes", manifest_auth.get("public_routes", []))
+        rotate_tokens = csrf_config.get("rotate_tokens", False)
+        token_ttl = csrf_config.get("token_ttl", DEFAULT_TOKEN_TTL)
+
+    # Create configured middleware class
+    class ConfiguredCSRFMiddleware(CSRFMiddleware):
+        def __init__(self, app):
+            super().__init__(
+                app,
+                secret=secret or os.getenv("MDB_ENGINE_CSRF_SECRET"),
+                exempt_routes=exempt_routes,
+                rotate_tokens=rotate_tokens,
+                token_ttl=token_ttl,
+            )
+
+    return ConfiguredCSRFMiddleware
+
+
+# Dependency for getting CSRF token in routes
+def get_csrf_token(request: Request) -> str:
+    """
+    Get or generate CSRF token for use in templates.
+
+    Usage in FastAPI route:
+        @app.get("/form")
+        def form_page(csrf_token: str = Depends(get_csrf_token)):
+            return templates.TemplateResponse("form.html", {"csrf_token": csrf_token})
+    """
+    # Try to get from request state (set by middleware)
+    if hasattr(request.state, "csrf_token"):
+        return request.state.csrf_token
+
+    # Try to get from cookie
+    token = request.cookies.get(CSRF_COOKIE_NAME)
+    if token:
+        return token
+
+    # Generate new token
+    secret = os.getenv("MDB_ENGINE_CSRF_SECRET")
+    return generate_csrf_token(secret)

mdb_engine/auth/decorators.py

@@ -70,10 +70,7 @@ def _is_production_environment() -> bool:
     """Check if running in production environment."""
     import os
 
-    return (
-        os.getenv("G_NOME_ENV") == "production"
-        or os.getenv("ENVIRONMENT") == "production"
-    )
+    return os.getenv("G_NOME_ENV") == "production" or os.getenv("ENVIRONMENT") == "production"
 
 
 def _validate_https(request: Request) -> None:
@@ -189,17 +186,13 @@ def rate_limit_auth(
 
             # Use provided values or config values or defaults
             if max_attempts is None:
-                max_attempts_val = (
-                    rate_limit_config.get("max_attempts") if rate_limit_config else 5
-                )
+                max_attempts_val = rate_limit_config.get("max_attempts") if rate_limit_config else 5
             else:
                 max_attempts_val = max_attempts
 
             if window_seconds is None:
                 window_seconds_val = (
-                    rate_limit_config.get("window_seconds")
-                    if rate_limit_config
-                    else 300
+                    rate_limit_config.get("window_seconds") if rate_limit_config else 300
                 )
             else:
                 window_seconds_val = window_seconds

mdb_engine/auth/dependencies.py

@@ -14,9 +14,11 @@ from typing import Any, Dict, Mapping, Optional, Tuple
 
 import jwt
 from fastapi import Cookie, Depends, HTTPException, Request, status
+from pymongo.errors import PyMongoError
 
 from ..exceptions import ConfigurationError
 from .jwt import decode_jwt_token, extract_token_metadata
+
 # Import from local modules
 from .provider import AuthorizationProvider
 from .session_manager import SessionManager
@@ -164,9 +166,7 @@ async def get_current_user(
             if blacklist:
                 is_revoked = await blacklist.is_revoked(jti)
                 if is_revoked:
-                    logger.info(
-                        f"get_current_user: Token {jti} is blacklisted (revoked)"
-                    )
+                    logger.info(f"get_current_user: Token {jti} is blacklisted (revoked)")
                     return None
 
                 # Also check user-level revocation
@@ -174,9 +174,7 @@ async def get_current_user(
                 if user_id:
                     user_revoked = await blacklist.is_user_revoked(user_id)
                     if user_revoked:
-                        logger.info(
-                            f"get_current_user: All tokens for user {user_id} are revoked"
-                        )
+                        logger.info(f"get_current_user: All tokens for user {user_id} are revoked")
                         return None
 
         payload = decode_jwt_token(token, str(SECRET_KEY))
@@ -184,9 +182,7 @@ async def get_current_user(
         # Verify token type (should be access token for backward compatibility, or no type)
         token_type = payload.get("type")
         if token_type and token_type not in ("access", None):
-            logger.warning(
-                f"get_current_user: Invalid token type '{token_type}' for access token"
-            )
+            logger.warning(f"get_current_user: Invalid token type '{token_type}' for access token")
             return None
 
         logger.debug(
@@ -203,10 +199,12 @@ async def get_current_user(
     except (ValueError, TypeError):
         logger.exception("Validation error decoding JWT token")
         return None
-    except Exception:
-        logger.exception("Unexpected error decoding JWT token")
-        # Re-raise unexpected errors for debugging
-        raise
+    except PyMongoError:
+        logger.exception("Database error checking token blacklist")
+        return None
+    except (AttributeError, KeyError):
+        logger.exception("State access error in get_current_user")
+        return None
 
 
 async def get_current_user_from_request(request: Request) -> Optional[Dict[str, Any]]:
@@ -276,10 +274,12 @@ async def get_current_user_from_request(request: Request) -> Optional[Dict[str,
     except (ValueError, TypeError):
         logger.exception("Validation error decoding JWT token from request")
         return None
-    except Exception:
-        logger.exception("Unexpected error decoding JWT token from request")
-        # Re-raise unexpected errors for debugging
-        raise
+    except PyMongoError:
+        logger.exception("Database error checking token blacklist from request")
+        return None
+    except (AttributeError, KeyError):
+        logger.exception("State access error in get_current_user_from_request")
+        return None
 
 
 async def get_refresh_token(
@@ -314,9 +314,7 @@ async def get_refresh_token(
             if blacklist:
                 is_revoked = await blacklist.is_revoked(jti)
                 if is_revoked:
-                    logger.info(
-                        f"get_refresh_token: Refresh token {jti} is blacklisted"
-                    )
+                    logger.info(f"get_refresh_token: Refresh token {jti} is blacklisted")
                     return None
 
         payload = decode_jwt_token(refresh_token, str(SECRET_KEY))
@@ -350,13 +348,9 @@ async def get_refresh_token(
                 if stored_fingerprint:
                     from .utils import generate_session_fingerprint
 
-                    device_id = request.cookies.get("device_id") or payload.get(
-                        "device_id"
-                    )
+                    device_id = request.cookies.get("device_id") or payload.get("device_id")
                     if device_id:
-                        current_fingerprint = generate_session_fingerprint(
-                            request, device_id
-                        )
+                        current_fingerprint = generate_session_fingerprint(request, device_id)
                         if current_fingerprint != stored_fingerprint:
                             logger.warning(
                                 f"get_refresh_token: Session fingerprint mismatch "
@@ -377,10 +371,12 @@ async def get_refresh_token(
     except (ValueError, TypeError):
         logger.exception("Validation error decoding refresh token")
         return None
-    except Exception:
-        logger.exception("Unexpected error decoding refresh token")
-        # Re-raise unexpected errors for debugging
-        raise
+    except PyMongoError:
+        logger.exception("Database error checking refresh token")
+        return None
+    except (AttributeError, KeyError):
+        logger.exception("State access error in get_refresh_token")
+        return None
 
 
 async def require_admin(
@@ -504,14 +500,14 @@ async def get_current_user_or_redirect(
                 headers={"Location": redirect_url},
                 detail="Not authenticated. Redirecting to login.",
             )
-        except (ValueError, KeyError, AttributeError):
+        except (ValueError, KeyError, AttributeError) as e:
             logger.exception(
                 f"Failed to generate login redirect URL for route '{login_route_name}'"
             )
             raise HTTPException(
                 status_code=status.HTTP_401_UNAUTHORIZED,
                 detail="Authentication required, but redirect failed.",
-            )
+            ) from e
     return dict(user)
 
 
@@ -619,9 +615,7 @@ async def refresh_access_token(
         from ..config import TOKEN_ROTATION_ENABLED
         from .jwt import generate_token_pair
 
-        user_id = refresh_token_payload.get("user_id") or refresh_token_payload.get(
-            "email"
-        )
+        user_id = refresh_token_payload.get("user_id") or refresh_token_payload.get("email")
         old_refresh_jti = refresh_token_payload.get("jti")
         device_id = refresh_token_payload.get("device_id")
 
@@ -653,9 +647,7 @@ async def refresh_access_token(
 
                     device_id = device_id or request.cookies.get("device_id")
                     if device_id:
-                        current_fingerprint = generate_session_fingerprint(
-                            request, device_id
-                        )
+                        current_fingerprint = generate_session_fingerprint(request, device_id)
                         if current_fingerprint != stored_fingerprint:
                             logger.warning(
                                 f"refresh_access_token: Session fingerprint mismatch "
@@ -671,9 +663,7 @@ async def refresh_access_token(
 
         # Use existing device_id or generate new one
         if not device_id:
-            device_id = (
-                str(uuid.uuid4()) if not device_info else device_info.get("device_id")
-            )
+            device_id = str(uuid.uuid4()) if not device_info else device_info.get("device_id")
 
         if device_info:
             device_info["device_id"] = device_id
@@ -741,7 +731,9 @@ async def refresh_access_token(
     except (ValueError, TypeError, jwt.InvalidTokenError):
         logger.exception("Validation error refreshing token")
         return None
-    except Exception:
-        logger.exception("Unexpected error refreshing token")
-        # Re-raise unexpected errors for debugging
-        raise
+    except PyMongoError:
+        logger.exception("Database error refreshing token")
+        return None
+    except (AttributeError, KeyError):
+        logger.exception("State access error refreshing token")
+        return None

mdb_engine/auth/helpers.py

@@ -19,7 +19,7 @@ async def initialize_token_management(app, db):
 
     Args:
         app: FastAPI application instance
-        db: MongoDB database instance (Motor AsyncIOMotorDatabase)
+        db: Scoped MongoDB database instance (ScopedMongoWrapper)
 
     Example:
         from mdb_engine.auth.helpers import initialize_token_management
@@ -27,8 +27,8 @@ async def initialize_token_management(app, db):
 
         @app.on_event("startup")
         async def startup():
-            # Get database from engine
-            db = engine.get_database()
+            # Get scoped database from engine
+            db = engine.get_scoped_db("my_app")
 
             # Initialize token management
             await initialize_token_management(app, db)