mdb-engine 0.4.11__py3-none-any.whl → 0.4.14__py3-none-any.whl

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/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/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.dist-info → mdb_engine-0.4.14.dist-info}/METADATA

@@ -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.dist-info → mdb_engine-0.4.14.dist-info}/RECORD

@@ -1,5 +1,5 @@
 mdb_engine/README.md,sha256=T3EFGcPopY9LslYW3lxgG3hohWkAOmBNbYG0FDMUJiY,3502
-mdb_engine/__init__.py,sha256=Fs_kQ4wpgcfaZcqFh7IJNmbB-nvo9Z1DwUYML3palCM,3554
+mdb_engine/__init__.py,sha256=wfZJ6njS5_immp5ErJ2BzevHJUeZtkXG_xytdni0mH0,3531
 mdb_engine/config.py,sha256=DTAyxfKB8ogyI0v5QR9Y-SJOgXQr_eDBCKxNBSqEyLc,7269
 mdb_engine/constants.py,sha256=eaotvW57TVOg7rRbLziGrVNoP7adgw_G9iVByHezc_A,7837
 mdb_engine/dependencies.py,sha256=MJuYQhZ9ZGzXlip1ha5zba9Rvn04HDPWahJFJH81Q2s,14107
@@ -46,7 +46,7 @@ mdb_engine/core/app_registration.py,sha256=7szt2a7aBkpSppjmhdkkPPYMKGKo0MkLKZeEe
 mdb_engine/core/app_secrets.py,sha256=bo-syg9UUATibNyXEZs-0TTYWG-JaY-2S0yNSGA12n0,10524
 mdb_engine/core/connection.py,sha256=XnwuPG34pJ7kJGJ84T0mhj1UZ6_CLz_9qZf6NRYGIS8,8346
 mdb_engine/core/encryption.py,sha256=RZ5LPF5g28E3ZBn6v1IMw_oas7u9YGFtBcEj8lTi9LM,7515
-mdb_engine/core/engine.py,sha256=vLD4Wt1dqAGx15uQqapw2NnSHQLwJl5TetBJpzWNSTs,150167
+mdb_engine/core/engine.py,sha256=ydYt2z53scf4GzufD8rY5X6gSJEF80VSDm1QDR2pwWQ,151507
 mdb_engine/core/index_management.py,sha256=9-r7MIy3JnjQ35sGqsbj8K_I07vAUWtAVgSWC99lJcE,5555
 mdb_engine/core/manifest.py,sha256=jguhjVPAHMZGxOJcdSGouv9_XiKmxUjDmyjn2yXHCj4,139205
 mdb_engine/core/ray_integration.py,sha256=vexYOzztscvRYje1xTNmXJbi99oJxCaVJAwKfTNTF_E,13610
@@ -86,12 +86,12 @@ mdb_engine/repositories/mongo.py,sha256=Wg32_6v0KHAHumhz5z8QkoqJRWAMJFA7Y2lYIJ7L
 mdb_engine/repositories/unit_of_work.py,sha256=XvmwGOspEDj4hsfOULPsQKjB1QZqh83TJo6vGV4tiqU,5118
 mdb_engine/routing/README.md,sha256=WVvTQXDq0amryrjkCu0wP_piOEwFjLukjmPz2mroWHY,13658
 mdb_engine/routing/__init__.py,sha256=reupjHi_RTc2ZBA4AH5XzobAmqy4EQIsfSUcTkFknUM,2438
-mdb_engine/routing/websockets.py,sha256=3X4OjQv_Nln4UmeifJky0gFhMG8A6alR77I8g1iIOLY,29311
+mdb_engine/routing/websockets.py,sha256=vMpfnGzMrMvqF2ZBwWazS-8cL73nwO1rHoR2XZJTI9k,31667
 mdb_engine/utils/__init__.py,sha256=lDxQSGqkV4fVw5TWIk6FA6_eey_ZnEtMY0fir3cpAe8,236
 mdb_engine/utils/mongo.py,sha256=Oqtv4tQdpiiZzrilGLEYQPo8Vmh8WsTQypxQs8Of53s,3369
-mdb_engine-0.4.11.dist-info/licenses/LICENSE,sha256=hIahDEOTzuHCU5J2nd07LWwkLW7Hko4UFO__ffsvB-8,34523
-mdb_engine-0.4.11.dist-info/METADATA,sha256=P7zS3dkTt-ZqKU4c2yp8pjn57v-1u6gV9S9rtp91PN0,15811
-mdb_engine-0.4.11.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
-mdb_engine-0.4.11.dist-info/entry_points.txt,sha256=INCbYdFbBzJalwPwxliEzLmPfR57IvQ7RAXG_pn8cL8,48
-mdb_engine-0.4.11.dist-info/top_level.txt,sha256=PH0UEBwTtgkm2vWvC9He_EOMn7hVn_Wg_Jyc0SmeO8k,11
-mdb_engine-0.4.11.dist-info/RECORD,,
+mdb_engine-0.4.14.dist-info/licenses/LICENSE,sha256=hIahDEOTzuHCU5J2nd07LWwkLW7Hko4UFO__ffsvB-8,34523
+mdb_engine-0.4.14.dist-info/METADATA,sha256=e6T3Bsq0hTdDSLDQHwb5MyJpsL5-HY2pP9iYev5oAm0,15811
+mdb_engine-0.4.14.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+mdb_engine-0.4.14.dist-info/entry_points.txt,sha256=INCbYdFbBzJalwPwxliEzLmPfR57IvQ7RAXG_pn8cL8,48
+mdb_engine-0.4.14.dist-info/top_level.txt,sha256=PH0UEBwTtgkm2vWvC9He_EOMn7hVn_Wg_Jyc0SmeO8k,11
+mdb_engine-0.4.14.dist-info/RECORD,,