mdb-engine 0.4.11__tar.gz → 0.4.14__tar.gz

{mdb_engine-0.4.11/mdb_engine.egg-info → mdb_engine-0.4.14}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mdb-engine
-Version: 0.4.11
+Version: 0.4.14
 Summary: MongoDB Engine
 Home-page: https://github.com/ranfysvalle02/mdb-engine
 Author: Fabian Valle

{mdb_engine-0.4.11 → mdb_engine-0.4.14}/mdb_engine/__init__.py

@@ -82,13 +82,12 @@ from .repositories import Entity, MongoRepository, Repository, UnitOfWork
 from .utils import clean_mongo_doc, clean_mongo_docs
 
 __version__ = (
-    "0.4.11"  # Automatic WebSocket support improvements
-    # - Improved CORS config merging with proper wildcard handling
-    # - WebSocket route verification after registration
-    # - Startup verification logging for CORS config and WebSocket routes
-    # - Enhanced CSRF middleware error messages with path and CORS status
-    # - Better logging throughout WebSocket registration process
-    # - All WebSocket multi-app SSO features now work automatically
+    "0.4.14"  # WebSocket security documentation and test updates
+    # - Comprehensive security guide (WEBSOCKET_SECURITY_MULTI_APP_SSO.md)
+    # - Updated all documentation to reflect subprotocol-only authentication
+    # - Added integration tests for subprotocol authentication in multi-app SSO
+    # - Enhanced unit test documentation with security-focused explanations
+    # - Complete test coverage for WebSocket security scenarios
 )
 
 __all__ = [

{mdb_engine-0.4.11 → mdb_engine-0.4.14}/mdb_engine/core/engine.py

@@ -1499,8 +1499,9 @@ class MongoDBEngine:
 
         # Add CSRF middleware (after auth - auto-enabled for shared mode)
         # CSRF protection is enabled by default for shared auth mode
+        # SKIP for sub-apps in multi-app setups - parent app handles CSRF
         csrf_config = auth_config.get("csrf_protection", True if auth_mode == "shared" else False)
-        if csrf_config:
+        if csrf_config and not is_sub_app:  # Don't add CSRF to child apps
             from ..auth.csrf import create_csrf_middleware
 
             csrf_middleware = create_csrf_middleware(
@@ -1508,6 +1509,11 @@ class MongoDBEngine:
             )
             app.add_middleware(csrf_middleware)
             logger.info(f"CSRFMiddleware added for '{slug}'")
+        elif csrf_config and is_sub_app:
+            logger.debug(
+                f"CSRFMiddleware skipped for child app '{slug}' - "
+                f"parent app handles CSRF protection for WebSocket routes"
+            )
 
         # Add security middleware (HSTS, headers)
         security_config = auth_config.get("security", {})
@@ -2127,17 +2133,33 @@ class MongoDBEngine:
                 "Path prefix validation failed:\n" + "\n".join(f"  - {e}" for e in errors)
             )
 
-        # Check if any app uses shared auth
+        # Check if any app uses shared auth and collect public routes for CSRF exemption
         has_shared_auth = False
+        all_public_routes = [
+            "/health",
+            "/docs",
+            "/openapi.json",
+            "/_mdb/routes",
+        ]  # Base exempt routes
         for app_config in apps:
             try:
                 manifest_path = app_config["manifest"]
+                path_prefix = app_config.get("path_prefix", f"/{app_config.get('slug')}")
                 with open(manifest_path) as f:
                     app_manifest_pre = json.load(f)
                 auth_config = app_manifest_pre.get("auth", {})
                 if auth_config.get("mode") == "shared":
                     has_shared_auth = True
-                    break
+                # Collect public routes with path prefix for CSRF exemption
+                child_public_routes = auth_config.get("public_routes", [])
+                for route in child_public_routes:
+                    # Add path prefix to make route absolute on parent app
+                    if route.startswith("/"):
+                        prefixed_route = f"{path_prefix.rstrip('/')}{route}"
+                    else:
+                        prefixed_route = f"{path_prefix.rstrip('/')}/{route}"
+                    if prefixed_route not in all_public_routes:
+                        all_public_routes.append(prefixed_route)
             except (FileNotFoundError, json.JSONDecodeError, KeyError) as e:
                 logger.warning(f"Could not check auth mode for app '{app_config.get('slug')}': {e}")
 
@@ -2812,10 +2834,11 @@ class MongoDBEngine:
             from ..auth.csrf import create_csrf_middleware
 
             # Create CSRF middleware with default config (will use parent app's CORS config)
-            # Exempt routes that don't need CSRF (health checks, etc.)
+            # Exempt routes that don't need CSRF (health checks, public routes from child apps)
+            # all_public_routes includes base routes + child app public routes with path prefixes
             parent_csrf_config = {
                 "csrf_protection": True,
-                "public_routes": ["/health", "/docs", "/openapi.json", "/_mdb/routes"],
+                "public_routes": all_public_routes,
             }
             csrf_middleware = create_csrf_middleware(parent_csrf_config)
             parent_app.add_middleware(csrf_middleware)

{mdb_engine-0.4.11 → mdb_engine-0.4.14}/mdb_engine/routing/websockets.py

@@ -311,10 +311,15 @@ async def authenticate_websocket(
     websocket: Any, app_slug: str, require_auth: bool = True
 ) -> tuple[str | None, str | None]:
     """
-    Authenticate a WebSocket connection.
+    Authenticate a WebSocket connection via Sec-WebSocket-Protocol header.
+
+    Uses subprotocol tunneling to pass JWT tokens securely:
+    - Client: new WebSocket(url, [token])
+    - Server: Extracts token from sec-websocket-protocol header
+    - Bypasses CSRF issues and avoids URL logging risks
 
     Args:
-        websocket: FastAPI WebSocket instance
+        websocket: FastAPI WebSocket instance (can access headers before accept)
         app_slug: App slug for context
         require_auth: Whether authentication is required
 
@@ -335,59 +340,57 @@ async def authenticate_websocket(
         return None, None
 
     try:
-        # Try to get token from query params or cookies
         token = None
-        query_token = None
-        cookie_token = None
-
-        # Check query parameters
-        # FastAPI WebSocket query params are accessed via websocket.query_params
-        if hasattr(websocket, "query_params"):
-            if websocket.query_params:
-                query_token = websocket.query_params.get("token")
-                logger.info(
-                    f"WebSocket query_params for app '{app_slug}': {dict(websocket.query_params)}"
-                )
-                if query_token:
-                    token = query_token
-                    logger.info(
-                        f"WebSocket token found in query params for app "
-                        f"'{app_slug}' (length: {len(query_token)})"
-                    )
-            else:
-                logger.info(f"WebSocket query_params is empty for app '{app_slug}'")
-        else:
-            logger.warning(f"WebSocket has no query_params attribute for app '{app_slug}'")
+        selected_subprotocol = None
 
-        # If no token in query, try to get from cookies (if available)
-        # Check both ws_token (non-httponly, for JS access) and token (httponly)
-        if not token:
-            if hasattr(websocket, "cookies"):
-                cookie_token = websocket.cookies.get("ws_token") or websocket.cookies.get("token")
-                if cookie_token:
-                    token = cookie_token
-                    logger.debug(f"WebSocket token found in cookies for app '{app_slug}'")
-            else:
-                logger.debug(f"WebSocket has no cookies attribute for app '{app_slug}'")
-
-        logger.info(
-            f"WebSocket auth check for app '{app_slug}': "
-            f"query_token={bool(query_token)}, "
-            f"cookie_token={bool(cookie_token)}, "
-            f"final_token={bool(token)}, require_auth={require_auth}"
-        )
+        # Sec-WebSocket-Protocol (Subprotocol Tunneling)
+        # Browsers allow: new WebSocket(url, ["token", "THE_JWT_STRING"])
+        # This bypasses CSRF issues and avoids URL logging risks
+        try:
+            protocol_header = None
+            # Try multiple ways to access headers (FastAPI WebSocket compatibility)
+            if hasattr(websocket, "headers") and websocket.headers is not None:
+                # FastAPI WebSocket.headers is case-insensitive dict-like
+                protocol_header = websocket.headers.get("sec-websocket-protocol")
+
+            # Fallback: access via scope (ASGI standard) if headers not available
+            if not protocol_header and hasattr(websocket, "scope") and "headers" in websocket.scope:
+                headers_dict = dict(websocket.scope["headers"])
+                # Headers are bytes in ASGI, need to decode
+                protocol_header_bytes = headers_dict.get(b"sec-websocket-protocol")
+                if protocol_header_bytes:
+                    protocol_header = protocol_header_bytes.decode("utf-8")
+
+            if protocol_header:
+                # Header format: "protocol1, protocol2, ..." or just "token"
+                protocols = [p.strip() for p in protocol_header.split(",")]
+                logger.debug(f"WebSocket subprotocols for app '{app_slug}': {protocols}")
+
+                # Look for a JWT-like token in the protocols
+                # JWTs are typically long (>20 chars) and don't contain spaces
+                for protocol in protocols:
+                    if len(protocol) > 20 and " " not in protocol:
+                        token = protocol
+                        selected_subprotocol = protocol
+                        logger.info(
+                            f"WebSocket token found in subprotocol for app '{app_slug}' "
+                            f"(length: {len(protocol)})"
+                        )
+                        break
+        except (AttributeError, TypeError, KeyError, UnicodeDecodeError) as e:
+            logger.debug(f"Could not access WebSocket headers for subprotocol check: {e}")
 
         if not token:
             logger.warning(
-                f"No token found for WebSocket connection to app '{app_slug}' "
-                f"(require_auth={require_auth})"
+                f"No token found in subprotocol header for WebSocket connection to app "
+                f"'{app_slug}' (require_auth={require_auth}). "
+                f"Use: new WebSocket(url, [token]) to pass JWT token as subprotocol."
             )
             if require_auth:
-                # Don't close before accepting - return error info instead
-                # The caller will handle closing after accept
                 return None, None  # Signal auth failure
             return None, None
 
+        # Decode and validate token
         import jwt
 
         from ..auth.dependencies import SECRET_KEY
@@ -398,6 +401,13 @@ async def authenticate_websocket(
             user_id = payload.get("sub") or payload.get("user_id")
             user_email = payload.get("email")
 
+            # Store selected subprotocol on websocket scope for accept() to use
+            if selected_subprotocol:
+                # Store in scope so _accept_websocket_connection can access it
+                if hasattr(websocket, "scope"):
+                    websocket.scope["_selected_subprotocol"] = selected_subprotocol
+                logger.debug(f"Stored subprotocol '{selected_subprotocol}' for WebSocket accept")
+
             logger.info(f"WebSocket authenticated successfully for app '{app_slug}': {user_email}")
             return user_id, user_email
         except (jwt.ExpiredSignatureError, jwt.InvalidTokenError) as decode_error:
@@ -409,7 +419,6 @@ async def authenticate_websocket(
     except (ValueError, TypeError, AttributeError, KeyError, RuntimeError) as e:
         logger.error(f"WebSocket authentication failed for app '{app_slug}': {e}", exc_info=True)
         if require_auth:
-            # Don't close before accepting - return error info instead
             return None, None  # Signal auth failure
         return None, None
 
@@ -470,11 +479,32 @@ def get_message_handler(
 
 
 async def _accept_websocket_connection(websocket: Any, app_slug: str) -> None:
-    """Accept WebSocket connection with error handling."""
+    """
+    Accept WebSocket connection with subprotocol support.
+
+    If authentication found a token in the Sec-WebSocket-Protocol header,
+    we must accept with that specific subprotocol or the browser will reject
+    the connection.
+    """
     try:
-        await websocket.accept()
+        # Check if auth stored a selected subprotocol
+        selected_subprotocol = None
+        if hasattr(websocket, "scope"):
+            selected_subprotocol = websocket.scope.get("_selected_subprotocol")
+
+        if selected_subprotocol:
+            # Accept with the specific subprotocol the client requested
+            await websocket.accept(subprotocol=selected_subprotocol)
+            logger.info(
+                f"✅ WebSocket accepted for app '{app_slug}' "
+                f"with subprotocol '{selected_subprotocol}'"
+            )
+        else:
+            # Standard accept without subprotocol
+            await websocket.accept()
+            logger.info(f"✅ WebSocket accepted for app '{app_slug}'")
+
         print(f"✅ [WEBSOCKET ACCEPTED] App: '{app_slug}'")
-        logger.info(f"✅ WebSocket accepted for app '{app_slug}'")
     except (RuntimeError, ConnectionError, OSError) as accept_error:
         print(f"❌ [WEBSOCKET ACCEPT FAILED] App: '{app_slug}', Error: {accept_error}")
         logger.error(
@@ -654,13 +684,23 @@ def create_websocket_endpoint(
                 f"(require_auth={require_auth}, query_params={query_str})"
             )
 
-            # Accept connection FIRST (required before we can do anything)
-            await _accept_websocket_connection(websocket, app_slug)
+            # CRITICAL: Authenticate BEFORE accepting connection
+            # This prevents CSRF middleware from rejecting established connections
+            # We can access headers/query_params before accept() is called
+            user_id, user_email = await authenticate_websocket(websocket, app_slug, require_auth)
 
-            # Authenticate connection (after accept, so we can close properly if needed)
-            user_id, user_email = await _authenticate_websocket_connection(
-                websocket, app_slug, require_auth
-            )
+            # Handle authentication failure
+            if require_auth and not user_id:
+                logger.warning(
+                    f"WebSocket authentication failed for app '{app_slug}' - rejecting connection"
+                )
+                # Reject without accepting - FastAPI will send 403 if accept() not called
+                # We can't call websocket.close() before accept(), so we just return
+                # The connection will be rejected by the server
+                return
+
+            # Accept connection (with subprotocol if token was in protocol header)
+            await _accept_websocket_connection(websocket, app_slug)
 
             # Connect with metadata (websocket already accepted)
             connection = await manager.connect(websocket, user_id=user_id, user_email=user_email)

{mdb_engine-0.4.11 → mdb_engine-0.4.14/mdb_engine.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mdb-engine
-Version: 0.4.11
+Version: 0.4.14
 Summary: MongoDB Engine
 Home-page: https://github.com/ranfysvalle02/mdb-engine
 Author: Fabian Valle

{mdb_engine-0.4.11 → mdb_engine-0.4.14}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "mdb-engine"
-version = "0.4.11"
+version = "0.4.14"
 description = "MongoDB Engine"
 readme = "README.md"
 requires-python = ">=3.10"

{mdb_engine-0.4.11 → mdb_engine-0.4.14}/setup.py

@@ -14,7 +14,7 @@ if readme_file.exists():
 
 setup(
     name="mdb-engine",
-    version="0.4.11",
+    version="0.4.14",
     description="MongoDB Engine",
     long_description=long_description,
     long_description_content_type="text/markdown",