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

mdb_engine/auth/utils.py

@@ -11,7 +11,7 @@ import logging
 import re
 import uuid
 from datetime import datetime
-from typing import Any, Dict, List, Optional, Tuple
+from typing import Any
 
 import bcrypt
 from fastapi import Request, Response
@@ -43,7 +43,7 @@ def _detect_browser(user_agent: str) -> str:
     return "unknown"
 
 
-def _detect_os_and_device_type(user_agent: str) -> Tuple[str, str]:
+def _detect_os_and_device_type(user_agent: str) -> tuple[str, str]:
     """Detect OS and device type from user agent string."""
     if not user_agent:
         return "unknown", "desktop"
@@ -64,7 +64,7 @@ def _detect_os_and_device_type(user_agent: str) -> Tuple[str, str]:
     return "unknown", "desktop"
 
 
-def get_device_info(request: Request) -> Dict[str, Any]:
+def get_device_info(request: Request) -> dict[str, Any]:
     """
     Extract device information from request.
 
@@ -95,15 +95,156 @@ def get_device_info(request: Request) -> Dict[str, Any]:
     }
 
 
+def calculate_password_entropy(password: str) -> float:
+    """
+    Calculate the entropy of a password in bits.
+
+    Entropy measures password randomness/unpredictability.
+    Higher entropy = more secure password.
+
+    Character set sizes:
+    - Lowercase: 26
+    - Uppercase: 26
+    - Digits: 10
+    - Special: ~32
+
+    Formula: entropy = length * log2(character_set_size)
+
+    Args:
+        password: Password to calculate entropy for
+
+    Returns:
+        Entropy in bits (float)
+    """
+    import math
+
+    if not password:
+        return 0.0
+
+    # Determine character set size based on what's used
+    char_set_size = 0
+
+    if re.search(r"[a-z]", password):
+        char_set_size += 26
+    if re.search(r"[A-Z]", password):
+        char_set_size += 26
+    if re.search(r"\d", password):
+        char_set_size += 10
+    if re.search(r'[!@#$%^&*(),.?":{}|<>\[\]\\;\'`~_+=\-/]', password):
+        char_set_size += 32
+    if re.search(r"\s", password):
+        char_set_size += 1
+
+    if char_set_size == 0:
+        # Fallback for Unicode or other characters
+        char_set_size = 94  # Printable ASCII assumption
+
+    # Entropy = length * log2(char_set_size)
+    entropy = len(password) * math.log2(char_set_size)
+
+    return round(entropy, 2)
+
+
+def is_common_password(password: str) -> bool:
+    """
+    Check if password is in the common passwords list.
+
+    Uses a bundled list of the top 10,000 most common passwords.
+    Falls back gracefully if the file is not available.
+
+    Args:
+        password: Password to check
+
+    Returns:
+        True if password is common, False otherwise
+    """
+    try:
+        import os
+
+        # Get the path to the common passwords file
+        resources_dir = os.path.join(os.path.dirname(__file__), "resources")
+        common_passwords_path = os.path.join(resources_dir, "common_passwords.txt")
+
+        if not os.path.exists(common_passwords_path):
+            logger.debug("Common passwords file not found, skipping check")
+            return False
+
+        # Read and check (case-insensitive)
+        password_lower = password.lower()
+        with open(common_passwords_path, encoding="utf-8") as f:
+            for line in f:
+                if line.strip().lower() == password_lower:
+                    return True
+
+        return False
+    except OSError as e:
+        logger.warning(f"Error checking common passwords: {e}")
+        return False
+
+
+async def check_password_breach(password: str) -> bool:
+    """
+    Check if password has been exposed in known data breaches.
+
+    Uses the HaveIBeenPwned API with k-anonymity (only sends first 5 chars of hash).
+    This is privacy-preserving - the full password hash is never sent.
+
+    Requires network access. Returns False (not breached) if check fails.
+
+    Args:
+        password: Password to check
+
+    Returns:
+        True if password was found in breaches, False otherwise
+    """
+    try:
+        import hashlib
+
+        import httpx
+
+        # Hash the password
+        sha1_hash = hashlib.sha1(password.encode()).hexdigest().upper()
+        prefix = sha1_hash[:5]
+        suffix = sha1_hash[5:]
+
+        # Query HIBP API (k-anonymity: only send first 5 chars)
+        url = f"https://api.pwnedpasswords.com/range/{prefix}"
+
+        async with httpx.AsyncClient(timeout=5.0) as client:
+            response = await client.get(url)
+            response.raise_for_status()
+
+        # Check if our suffix is in the response
+        for line in response.text.splitlines():
+            hash_suffix, count = line.split(":")
+            if hash_suffix == suffix:
+                logger.debug(f"Password found in {count} breaches")
+                return True
+
+        return False
+
+    except ImportError:
+        logger.debug("httpx not available, skipping breach check")
+        return False
+    except httpx.HTTPError as e:
+        logger.warning(f"Error checking password breaches: {e}")
+        return False
+    except (TimeoutError, ConnectionError, OSError) as e:
+        logger.warning(f"Error checking password breaches: {e}")
+        return False
+
+
 def validate_password_strength(
     password: str,
-    min_length: Optional[int] = None,
-    require_uppercase: Optional[bool] = None,
-    require_lowercase: Optional[bool] = None,
-    require_numbers: Optional[bool] = None,
-    require_special: Optional[bool] = None,
-    config: Optional[Dict[str, Any]] = None,
-) -> Tuple[bool, List[str]]:
+    min_length: int | None = None,
+    require_uppercase: bool | None = None,
+    require_lowercase: bool | None = None,
+    require_numbers: bool | None = None,
+    require_special: bool | None = None,
+    min_entropy_bits: int | None = None,
+    check_common_passwords: bool | None = None,
+    config: dict[str, Any] | None = None,
+) -> tuple[bool, list[str]]:
     """
     Validate password strength with configurable rules.
 
@@ -114,6 +255,8 @@ def validate_password_strength(
         require_lowercase: Require lowercase letters (default: from config or True)
         require_numbers: Require numbers (default: from config or True)
         require_special: Require special characters (default: from config or False)
+        min_entropy_bits: Minimum entropy in bits (default: from config or 0)
+        check_common_passwords: Check against common passwords (default: from config or False)
         config: Optional password_policy config dict from manifest
 
     Returns:
@@ -125,9 +268,7 @@ def validate_password_strength(
         return False, ["Password is required"]
 
     if config:
-        min_length = (
-            min_length if min_length is not None else config.get("min_length", 8)
-        )
+        min_length = min_length if min_length is not None else config.get("min_length", 8)
         require_uppercase = (
             require_uppercase
             if require_uppercase is not None
@@ -139,14 +280,18 @@ def validate_password_strength(
             else config.get("require_lowercase", True)
         )
         require_numbers = (
-            require_numbers
-            if require_numbers is not None
-            else config.get("require_numbers", True)
+            require_numbers if require_numbers is not None else config.get("require_numbers", True)
         )
         require_special = (
-            require_special
-            if require_special is not None
-            else config.get("require_special", False)
+            require_special if require_special is not None else config.get("require_special", False)
+        )
+        min_entropy_bits = (
+            min_entropy_bits if min_entropy_bits is not None else config.get("min_entropy_bits", 0)
+        )
+        check_common_passwords = (
+            check_common_passwords
+            if check_common_passwords is not None
+            else config.get("check_common_passwords", False)
         )
     else:
         min_length = min_length if min_length is not None else 8
@@ -154,6 +299,10 @@ def validate_password_strength(
         require_lowercase = require_lowercase if require_lowercase is not None else True
         require_numbers = require_numbers if require_numbers is not None else True
         require_special = require_special if require_special is not None else False
+        min_entropy_bits = min_entropy_bits if min_entropy_bits is not None else 0
+        check_common_passwords = (
+            check_common_passwords if check_common_passwords is not None else False
+        )
 
     if len(password) < min_length:
         errors.append(f"Password must be at least {min_length} characters long")
@@ -170,9 +319,62 @@ def validate_password_strength(
     if require_special and not re.search(r'[!@#$%^&*(),.?":{}|<>]', password):
         errors.append("Password must contain at least one special character")
 
+    # Entropy check
+    if min_entropy_bits and min_entropy_bits > 0:
+        entropy = calculate_password_entropy(password)
+        if entropy < min_entropy_bits:
+            errors.append(
+                f"Password is too weak (entropy: {entropy:.0f} bits, "
+                f"required: {min_entropy_bits} bits)"
+            )
+
+    # Common password check
+    if check_common_passwords:
+        if is_common_password(password):
+            errors.append("Password is too common - please choose a unique password")
+
     return len(errors) == 0, errors
 
 
+async def validate_password_strength_async(
+    password: str,
+    config: dict[str, Any] | None = None,
+    check_breaches: bool | None = None,
+) -> tuple[bool, list[str]]:
+    """
+    Async version of validate_password_strength with breach checking.
+
+    This performs all synchronous checks, plus an optional async breach
+    check against HaveIBeenPwned.
+
+    Args:
+        password: Password to validate
+        config: Optional password_policy config dict from manifest
+        check_breaches: Check against HIBP breach database (default: from config or False)
+
+    Returns:
+        Tuple of (is_valid, list_of_errors)
+    """
+    # First, run sync validation
+    is_valid, errors = validate_password_strength(password, config=config)
+
+    # Determine if we should check breaches
+    if check_breaches is None and config:
+        check_breaches = config.get("check_breaches", False)
+    elif check_breaches is None:
+        check_breaches = False
+
+    # Async breach check
+    if check_breaches:
+        if await check_password_breach(password):
+            errors.append(
+                "Password has been exposed in a data breach - " "please choose a different password"
+            )
+            is_valid = False
+
+    return is_valid, errors
+
+
 def generate_session_fingerprint(request: Request, device_id: str) -> str:
     """
     Generate a session fingerprint from request characteristics.
@@ -202,10 +404,10 @@ async def login_user(
     email: str,
     password: str,
     db,
-    config: Optional[Dict[str, Any]] = None,
+    config: dict[str, Any] | None = None,
     remember_me: bool = False,
-    redirect_url: Optional[str] = None,
-) -> Dict[str, Any]:
+    redirect_url: str | None = None,
+) -> dict[str, Any]:
     """
     Handle user login with automatic token generation and cookie setting.
 
@@ -369,8 +571,8 @@ def _validate_email_format(email: str) -> bool:
 
 
 def _get_password_policy_from_config(
-    request: Request, config: Optional[Dict[str, Any]]
-) -> Optional[Dict[str, Any]]:
+    request: Request, config: dict[str, Any] | None
+) -> dict[str, Any] | None:
     """Get password policy from config or request."""
     if config:
         security = config.get("security", {})
@@ -383,8 +585,8 @@ def _get_password_policy_from_config(
 
 
 async def _create_user_document(
-    email: str, password: str, extra_data: Optional[Dict[str, Any]]
-) -> Dict[str, Any]:
+    email: str, password: str, extra_data: dict[str, Any] | None
+) -> dict[str, Any]:
     """Create user document with hashed password."""
     password_hash = bcrypt.hashpw(password.encode("utf-8"), bcrypt.gensalt())
     user_doc = {
@@ -398,9 +600,7 @@ async def _create_user_document(
     return user_doc
 
 
-def _create_registration_response(
-    user_doc: Dict[str, Any], redirect_url: Optional[str]
-) -> Response:
+def _create_registration_response(user_doc: dict[str, Any], redirect_url: str | None) -> Response:
     """Create response for registration."""
     if redirect_url:
         return RedirectResponse(url=redirect_url, status_code=302)
@@ -420,10 +620,10 @@ async def register_user(
     email: str,
     password: str,
     db,
-    config: Optional[Dict[str, Any]] = None,
-    extra_data: Optional[Dict[str, Any]] = None,
-    redirect_url: Optional[str] = None,
-) -> Dict[str, Any]:
+    config: dict[str, Any] | None = None,
+    extra_data: dict[str, Any] | None = None,
+    redirect_url: str | None = None,
+) -> dict[str, Any]:
     """
     Handle user registration with automatic token generation.
 
@@ -478,9 +678,7 @@ async def register_user(
             )
 
         response = _create_registration_response(user_doc, redirect_url)
-        set_auth_cookies(
-            response, access_token, refresh_token, request=request, config=config
-        )
+        set_auth_cookies(response, access_token, refresh_token, request=request, config=config)
 
         response.set_cookie(
             key="device_id",
@@ -510,9 +708,7 @@ async def register_user(
         return {"success": False, "error": "Registration failed. Please try again."}
 
 
-async def _get_user_id_from_request(
-    request: Request, user_id: Optional[str]
-) -> Optional[str]:
+async def _get_user_id_from_request(request: Request, user_id: str | None) -> str | None:
     """Extract user_id from request if not provided."""
     if user_id:
         return user_id
@@ -575,9 +771,7 @@ async def _revoke_session(request: Request) -> None:
             await session_mgr.revoke_session_by_refresh_token(refresh_jti)
 
 
-async def logout_user(
-    request: Request, response: Response, user_id: Optional[str] = None
-) -> Response:
+async def logout_user(request: Request, response: Response, user_id: str | None = None) -> Response:
     """
     Handle user logout with token revocation and cookie clearing.