svc-infra 0.1.595__py3-none-any.whl → 0.1.706__py3-none-any.whl

svc_infra/api/fastapi/dependencies/ratelimit.py

@@ -1,14 +1,27 @@
 from __future__ import annotations
 
+import logging
 import time
-from typing import Callable
+from typing import Callable, Optional
 
 from fastapi import HTTPException
 from starlette.requests import Request
 
-from svc_infra.api.fastapi.middleware.ratelimit_store import InMemoryRateLimitStore, RateLimitStore
+from svc_infra.api.fastapi.middleware.ratelimit_store import (
+    InMemoryRateLimitStore,
+    RateLimitStore,
+)
 from svc_infra.obs.metrics import emit_rate_limited
 
+logger = logging.getLogger(__name__)
+
+try:
+    from svc_infra.api.fastapi.tenancy.context import (
+        resolve_tenant_id as _resolve_tenant_id,
+    )
+except Exception:  # pragma: no cover - minimal builds
+    _resolve_tenant_id = None  # type: ignore[assignment]
+
 
 class RateLimiter:
     def __init__(
@@ -17,24 +30,52 @@ class RateLimiter:
         limit: int,
         window: int = 60,
         key_fn: Callable = lambda r: "global",
+        limit_resolver: Optional[
+            Callable[[Request, Optional[str]], Optional[int]]
+        ] = None,
+        scope_by_tenant: bool = False,
         store: RateLimitStore | None = None,
     ):
         self.limit = limit
         self.window = window
         self.key_fn = key_fn
+        self._limit_resolver = limit_resolver
+        self.scope_by_tenant = scope_by_tenant
         self.store = store or InMemoryRateLimitStore(limit=limit)
 
     async def __call__(self, request: Request):
+        # Try resolving tenant when asked
+        tenant_id = None
+        if self.scope_by_tenant or self._limit_resolver:
+            try:
+                if _resolve_tenant_id is not None:
+                    tenant_id = await _resolve_tenant_id(request)
+            except Exception:
+                tenant_id = None
+
         key = self.key_fn(request)
-        count, limit, reset = self.store.incr(str(key), self.window)
-        if count > limit:
-            retry = max(0, reset - int(time.time()))
+        if self.scope_by_tenant and tenant_id:
+            key = f"{key}:tenant:{tenant_id}"
+
+        eff_limit = self.limit
+        if self._limit_resolver:
             try:
-                emit_rate_limited(str(key), limit, retry)
+                v = self._limit_resolver(request, tenant_id)
+                eff_limit = int(v) if v is not None else self.limit
             except Exception:
-                pass
+                eff_limit = self.limit
+
+        count, store_limit, reset = self.store.incr(str(key), self.window)
+        if count > eff_limit:
+            retry = max(0, reset - int(time.time()))
+            try:
+                emit_rate_limited(str(key), eff_limit, retry)
+            except Exception as e:
+                logger.warning("Failed to emit rate limit metric: %s", e)
             raise HTTPException(
-                status_code=429, detail="Rate limit exceeded", headers={"Retry-After": str(retry)}
+                status_code=429,
+                detail="Rate limit exceeded",
+                headers={"Retry-After": str(retry)},
             )
 
 
@@ -46,21 +87,44 @@ def rate_limiter(
     limit: int,
     window: int = 60,
     key_fn: Callable = lambda r: "global",
+    limit_resolver: Optional[Callable[[Request, Optional[str]], Optional[int]]] = None,
+    scope_by_tenant: bool = False,
     store: RateLimitStore | None = None,
 ):
     store_ = store or InMemoryRateLimitStore(limit=limit)
 
     async def dep(request: Request):
+        tenant_id = None
+        if scope_by_tenant or limit_resolver:
+            try:
+                if _resolve_tenant_id is not None:
+                    tenant_id = await _resolve_tenant_id(request)
+            except Exception:
+                tenant_id = None
+
         key = key_fn(request)
-        count, lim, reset = store_.incr(str(key), window)
-        if count > lim:
-            retry = max(0, reset - int(time.time()))
+        if scope_by_tenant and tenant_id:
+            key = f"{key}:tenant:{tenant_id}"
+
+        eff_limit = limit
+        if limit_resolver:
             try:
-                emit_rate_limited(str(key), lim, retry)
+                v = limit_resolver(request, tenant_id)
+                eff_limit = int(v) if v is not None else limit
             except Exception:
-                pass
+                eff_limit = limit
+
+        count, _store_limit, reset = store_.incr(str(key), window)
+        if count > eff_limit:
+            retry = max(0, reset - int(time.time()))
+            try:
+                emit_rate_limited(str(key), eff_limit, retry)
+            except Exception as e:
+                logger.warning("Failed to emit rate limit metric: %s", e)
             raise HTTPException(
-                status_code=429, detail="Rate limit exceeded", headers={"Retry-After": str(retry)}
+                status_code=429,
+                detail="Rate limit exceeded",
+                headers={"Retry-After": str(retry)},
             )
 
     return dep

svc_infra/api/fastapi/docs/add.py

@@ -0,0 +1,173 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Callable, Optional
+
+from fastapi import FastAPI, Request
+from fastapi.openapi.docs import get_redoc_html, get_swagger_ui_html
+from fastapi.responses import HTMLResponse, JSONResponse
+
+from .landing import CardSpec, DocTargets, render_index_html
+from .scoped import DOC_SCOPES
+
+
+def add_docs(
+    app: FastAPI,
+    *,
+    redoc_url: str = "/redoc",
+    swagger_url: str = "/docs",
+    openapi_url: str = "/openapi.json",
+    export_openapi_to: Optional[str] = None,
+    # Landing page options
+    landing_url: str = "/",
+    include_landing: bool = True,
+) -> None:
+    """Enable docs endpoints and optionally export OpenAPI schema to disk on startup.
+
+    We mount docs and OpenAPI routes explicitly so this works even when configured post-init.
+    """
+
+    # OpenAPI JSON route
+    async def openapi_handler() -> JSONResponse:  # noqa: ANN201
+        return JSONResponse(app.openapi())
+
+    app.add_api_route(
+        openapi_url, openapi_handler, methods=["GET"], include_in_schema=False
+    )
+
+    # Swagger UI route
+    async def swagger_ui(request: Request) -> HTMLResponse:  # noqa: ANN201
+        resp = get_swagger_ui_html(openapi_url=openapi_url, title="API Docs")
+        theme = request.query_params.get("theme")
+        if theme == "dark":
+            return _with_dark_mode(resp)
+        return resp
+
+    app.add_api_route(swagger_url, swagger_ui, methods=["GET"], include_in_schema=False)
+
+    # Redoc route
+    async def redoc_ui(request: Request) -> HTMLResponse:  # noqa: ANN201
+        resp = get_redoc_html(openapi_url=openapi_url, title="API ReDoc")
+        theme = request.query_params.get("theme")
+        if theme == "dark":
+            return _with_dark_mode(resp)
+        return resp
+
+    app.add_api_route(redoc_url, redoc_ui, methods=["GET"], include_in_schema=False)
+
+    # Optional export to disk on startup
+    if export_openapi_to:
+        export_path = Path(export_openapi_to)
+
+        async def _export_docs() -> None:
+            # Startup export
+            spec = app.openapi()
+            export_path.parent.mkdir(parents=True, exist_ok=True)
+            export_path.write_text(json.dumps(spec, indent=2))
+
+        app.add_event_handler("startup", _export_docs)
+
+    # Optional landing page with the same look/feel as setup_service_api
+    if include_landing:
+        # Avoid path collision; if landing_url is already taken for GET, fallback to "/_docs"
+        existing_paths = {
+            (getattr(r, "path", None) or getattr(r, "path_format", None))
+            for r in getattr(app, "routes", [])
+            if getattr(r, "methods", None) and "GET" in r.methods
+        }
+        landing_path = landing_url or "/"
+        if landing_path in existing_paths:
+            landing_path = "/_docs"
+
+        async def _landing() -> HTMLResponse:  # noqa: ANN201
+            cards: list[CardSpec] = []
+            # Root docs card using the provided paths
+            cards.append(
+                CardSpec(
+                    tag="",
+                    docs=DocTargets(
+                        swagger=swagger_url, redoc=redoc_url, openapi_json=openapi_url
+                    ),
+                )
+            )
+            # Scoped docs (if any were registered via add_prefixed_docs)
+            for scope, swagger, redoc, openapi_json, _title in DOC_SCOPES:
+                cards.append(
+                    CardSpec(
+                        tag=scope.strip("/"),
+                        docs=DocTargets(
+                            swagger=swagger, redoc=redoc, openapi_json=openapi_json
+                        ),
+                    )
+                )
+            html = render_index_html(
+                service_name=app.title or "API", release=app.version or "", cards=cards
+            )
+            return HTMLResponse(html)
+
+        app.add_api_route(
+            landing_path, _landing, methods=["GET"], include_in_schema=False
+        )
+
+
+def _with_dark_mode(resp: HTMLResponse) -> HTMLResponse:
+    """Return a copy of the HTMLResponse with a minimal dark-theme CSS injected.
+
+    We avoid depending on custom Swagger/ReDoc builds; this works by inlining a small CSS
+    block and toggling a `.dark` class on the body element.
+    """
+    try:
+        raw_body = resp.body
+        if isinstance(raw_body, memoryview):
+            raw_body = raw_body.tobytes()
+        body = raw_body.decode("utf-8", errors="ignore")
+    except Exception:  # pragma: no cover - very unlikely
+        return resp
+
+    css = _DARK_CSS
+    if "</head>" in body:
+        body = body.replace("</head>", f"<style>\n{css}\n</style></head>", 1)
+    # add class to body to allow stronger selectors
+    body = body.replace("<body>", '<body class="dark">', 1)
+    return HTMLResponse(
+        content=body, status_code=resp.status_code, headers=dict(resp.headers)
+    )
+
+
+_DARK_CSS = """
+/* Minimal dark mode override for Swagger/ReDoc */
+@media (prefers-color-scheme: dark) { :root { color-scheme: dark; } }
+html.dark, body.dark { background: #0b0e14; color: #e0e6f1; }
+#swagger, .redoc-wrap { background: transparent; }
+a { color: #62aef7; }
+"""
+
+
+def add_sdk_generation_stub(
+    app: FastAPI,
+    *,
+    on_generate: Optional[Callable[[], None]] = None,
+    openapi_path: str = "/openapi.json",
+) -> None:
+    """Hook to add an SDK generation stub.
+
+    Provide `on_generate()` to run generation (e.g., openapi-generator). This is a stub only; we
+    don't ship a hard dependency. If `on_generate` is provided, we expose `/_docs/generate-sdk`.
+    """
+    from svc_infra.api.fastapi.dual.public import public_router
+
+    if not on_generate:
+        return
+
+    router = public_router(prefix="/_docs", include_in_schema=False)
+
+    @router.post("/generate-sdk")
+    async def _generate() -> dict:  # noqa: ANN201
+        on_generate()
+        return {"status": "ok"}
+
+    app.include_router(router)
+
+
+__all__ = ["add_docs", "add_sdk_generation_stub"]

svc_infra/api/fastapi/docs/landing.py

@@ -50,7 +50,9 @@ def _card(spec: CardSpec) -> str:
     """.strip()
 
 
-def render_index_html(*, service_name: str, release: str, cards: Iterable[CardSpec]) -> str:
+def render_index_html(
+    *, service_name: str, release: str, cards: Iterable[CardSpec]
+) -> str:
     grid = "\n".join(_card(c) for c in cards)
     return f"""
 <!doctype html>
@@ -115,7 +117,7 @@ def render_index_html(*, service_name: str, release: str, cards: Iterable[CardSp
     <section class="grid">
       {grid}
     </section>
-    <footer>Tip: each card exposes Swagger, ReDoc, and a pretty JSON view.</footer>
+    <footer>Tip: each card exposes Swagger, ReDoc, and a JSON view.</footer>
   </div>
 </body>
 </html>

svc_infra/api/fastapi/docs/scoped.py

@@ -65,11 +65,18 @@ def _close_over_component_refs(
 
 
 def _prune_to_paths(
-    full_schema: Dict, keep_paths: Dict[str, dict], title_suffix: Optional[str]
+    full_schema: Dict,
+    keep_paths: Dict[str, dict],
+    title_suffix: Optional[str],
+    server_prefix: Optional[str] = None,
 ) -> Dict:
     schema = copy.deepcopy(full_schema)
     schema["paths"] = keep_paths
 
+    # Set server URL for scoped docs
+    if server_prefix is not None:
+        schema["servers"] = [{"url": server_prefix}]
+
     used_tags: Set[str] = set()
     direct_refs: Set[Tuple[str, str]] = set()
     used_security_schemes: Set[str] = set()
@@ -103,7 +110,9 @@ def _prune_to_paths(
 
     if "tags" in schema and isinstance(schema["tags"], list):
         schema["tags"] = [
-            t for t in schema["tags"] if isinstance(t, dict) and t.get("name") in used_tags
+            t
+            for t in schema["tags"]
+            if isinstance(t, dict) and t.get("name") in used_tags
         ]
 
     info = dict(schema.get("info") or {})
@@ -122,30 +131,55 @@ def _build_filtered_schema(
 ) -> Dict:
     paths = full_schema.get("paths", {}) or {}
     keep_paths = {
-        p: v for p, v in paths.items() if _path_included(p, include_prefixes, exclude_prefixes)
+        p: v
+        for p, v in paths.items()
+        if _path_included(p, include_prefixes, exclude_prefixes)
     }
-    return _prune_to_paths(full_schema, keep_paths, title_suffix)
+
+    # Determine the server prefix for scoped docs
+    server_prefix = None
+    if include_prefixes and len(include_prefixes) == 1:
+        # Single include prefix = scoped docs
+        server_prefix = include_prefixes[0].rstrip("/") or "/"
+
+        # Strip prefix from paths to make them relative to the server
+        stripped_paths = {}
+        for path, spec in keep_paths.items():
+            if path.startswith(server_prefix) and path != server_prefix:
+                # Remove prefix, keeping the leading slash
+                relative_path = path[len(server_prefix) :]
+                stripped_paths[relative_path] = spec
+            else:
+                # Path equals prefix or doesn't start with it
+                stripped_paths[path] = spec
+        keep_paths = stripped_paths
+
+    return _prune_to_paths(
+        full_schema, keep_paths, title_suffix, server_prefix=server_prefix
+    )
 
 
 def _ensure_original_openapi_saved(app: FastAPI) -> None:
     if not hasattr(app.state, "_scoped_original_openapi"):
-        app.state._scoped_original_openapi = app.openapi  # type: ignore[attr-defined]
+        app.state._scoped_original_openapi = app.openapi
 
 
 def _get_full_schema_from_original(app: FastAPI) -> Dict:
     _ensure_original_openapi_saved(app)
-    return copy.deepcopy(app.state._scoped_original_openapi())  # type: ignore[attr-defined]
+    return copy.deepcopy(app.state._scoped_original_openapi())
 
 
 def _install_root_filter(app: FastAPI, exclude_prefixes: List[str]) -> None:
     _ensure_original_openapi_saved(app)
-    app.state._scoped_root_exclusions = sorted(set(exclude_prefixes))  # type: ignore[attr-defined]
+    app.state._scoped_root_exclusions = sorted(set(exclude_prefixes))
 
     def root_filtered_openapi():
         full_schema = _get_full_schema_from_original(app)
-        return _build_filtered_schema(full_schema, exclude_prefixes=app.state._scoped_root_exclusions)  # type: ignore[attr-defined]
+        return _build_filtered_schema(
+            full_schema, exclude_prefixes=app.state._scoped_root_exclusions
+        )
 
-    app.openapi = root_filtered_openapi
+    setattr(app, "openapi", root_filtered_openapi)
 
 
 def _current_registered_scopes() -> List[str]:
@@ -158,7 +192,9 @@ def _ensure_root_excludes_registered_scopes(app: FastAPI) -> None:
         _install_root_filter(app, scopes)
 
 
-def _normalize_envs(envs: Optional[Iterable[Environment | str]]) -> Optional[set[Environment]]:
+def _normalize_envs(
+    envs: Optional[Iterable[Environment | str]],
+) -> Optional[set[Environment]]:
     if envs is None:
         return None
     out: set[Environment] = set()
@@ -175,11 +211,23 @@ def add_prefixed_docs(
     auto_exclude_from_root: bool = True,
     visible_envs: Optional[Iterable[Environment | str]] = (LOCAL_ENV, DEV_ENV),
 ) -> None:
+    scope = prefix.rstrip("/") or "/"
+
+    # Always exclude from root if requested, regardless of environment
+    if auto_exclude_from_root:
+        _ensure_original_openapi_saved(app)
+        # Add to exclusion list for root docs
+        if not hasattr(app.state, "_scoped_root_exclusions"):
+            app.state._scoped_root_exclusions = []
+        if scope not in app.state._scoped_root_exclusions:
+            app.state._scoped_root_exclusions.append(scope)
+            _install_root_filter(app, app.state._scoped_root_exclusions)
+
+    # Only create scoped docs in allowed environments
     allow = _normalize_envs(visible_envs)
     if allow is not None and CURRENT_ENVIRONMENT not in allow:
         return
 
-    scope = prefix.rstrip("/") or "/"
     openapi_path = f"{scope}/openapi.json"
     swagger_path = f"{scope}/docs"
     redoc_path = f"{scope}/redoc"
@@ -211,9 +259,8 @@ def add_prefixed_docs(
 
     DOC_SCOPES.append((scope, swagger_path, redoc_path, openapi_path, title))
 
-    if auto_exclude_from_root:
-        _ensure_root_excludes_registered_scopes(app)
-
 
-def replace_root_openapi_with_exclusions(app: FastAPI, *, exclude_prefixes: List[str]) -> None:
+def replace_root_openapi_with_exclusions(
+    app: FastAPI, *, exclude_prefixes: List[str]
+) -> None:
     _install_root_filter(app, exclude_prefixes)

svc_infra/api/fastapi/dual/__init__.py

@@ -1,12 +1,16 @@
 from .dualize import dualize_protected, dualize_public, dualize_service, dualize_user
-from .protected import (
+from .protected import (  # WebSocket routers with auth (DualAPIRouter with JWT auth, no DB required)
     optional_identity_router,
     protected_router,
     roles_router,
     service_router,
     user_router,
+    ws_optional_router,
+    ws_protected_router,
+    ws_scopes_router,
+    ws_user_router,
 )
-from .public import public_router
+from .public import public_router, ws_public_router
 from .router import DualAPIRouter
 
 __all__ = [
@@ -21,4 +25,10 @@ __all__ = [
     "user_router",
     "service_router",
     "roles_router",
+    # WebSocket routers
+    "ws_public_router",
+    "ws_protected_router",
+    "ws_user_router",
+    "ws_scopes_router",
+    "ws_optional_router",
 ]

svc_infra/api/fastapi/dual/dualize.py

@@ -27,7 +27,7 @@ def dualize_into(
         prefix="",  # prevent double-prefixing on include_router
         tags=list(src.tags or []),
         dependencies=list(src.dependencies or []),
-        default_response_class=src.default_response_class,  # type: ignore[arg-type]
+        default_response_class=src.default_response_class,
         responses=dict(src.responses or {}),
         callbacks=list(src.callbacks or []),
         routes=[],  # start empty

svc_infra/api/fastapi/dual/protected.py

@@ -10,8 +10,14 @@ from ..auth.security import (
     RequireService,
     RequireUser,
 )
+from ..auth.ws_security import AllowWSIdentity, RequireWSIdentity, RequireWSScopes
 from ..openapi.apply import apply_default_responses, apply_default_security
-from ..openapi.responses import DEFAULT_PROTECTED, DEFAULT_PUBLIC, DEFAULT_SERVICE, DEFAULT_USER
+from ..openapi.responses import (
+    DEFAULT_PROTECTED,
+    DEFAULT_PUBLIC,
+    DEFAULT_SERVICE,
+    DEFAULT_USER,
+)
 from .router import DualAPIRouter
 
 
@@ -52,7 +58,9 @@ def protected_router(
 
 
 # USER-ONLY (no API-key-only access)
-def user_router(*, dependencies: Optional[Sequence[Any]] = None, **kwargs: Any) -> DualAPIRouter:
+def user_router(
+    *, dependencies: Optional[Sequence[Any]] = None, **kwargs: Any
+) -> DualAPIRouter:
     r = DualAPIRouter(dependencies=_merge([RequireUser()], dependencies), **kwargs)
     apply_default_security(
         r, default_security=[{"OAuth2PasswordBearer": []}, {"SessionCookie": []}]
@@ -62,7 +70,9 @@ def user_router(*, dependencies: Optional[Sequence[Any]] = None, **kwargs: Any)
 
 
 # SERVICE-ONLY (API key required)
-def service_router(*, dependencies: Optional[Sequence[Any]] = None, **kwargs: Any) -> DualAPIRouter:
+def service_router(
+    *, dependencies: Optional[Sequence[Any]] = None, **kwargs: Any
+) -> DualAPIRouter:
     r = DualAPIRouter(dependencies=_merge([RequireService()], dependencies), **kwargs)
     apply_default_security(r, default_security=[{"APIKeyHeader": []}])
     apply_default_responses(r, DEFAULT_SERVICE)
@@ -87,10 +97,122 @@ def scopes_router(*scopes: str, **kwargs: Any) -> DualAPIRouter:
 # ROLE-GATED (example using roles attribute or resolver passed by caller)
 def roles_router(*roles: str, role_resolver=None, **kwargs):
     r = DualAPIRouter(
-        dependencies=[RequireUser(), RequireRoles(*roles, resolver=role_resolver)], **kwargs
+        dependencies=[RequireUser(), RequireRoles(*roles, resolver=role_resolver)],
+        **kwargs,
     )
     apply_default_security(
         r, default_security=[{"OAuth2PasswordBearer": []}, {"SessionCookie": []}]
     )
     apply_default_responses(r, DEFAULT_USER)
     return r
+
+
+# ---------- WebSocket Routers (Lightweight JWT, no DB required) ----------
+
+
+def ws_protected_router(
+    *, dependencies: Optional[Sequence[Any]] = None, **kwargs: Any
+) -> DualAPIRouter:
+    """
+    Protected WebSocket router - requires valid JWT token.
+
+    Uses lightweight JWT validation (no database access required).
+    Token can be passed via:
+    - Query param: ?token=<jwt>
+    - Header: Authorization: Bearer <jwt>
+    - Cookie: auth cookie
+    - Subprotocol: access_token.<jwt>
+
+    Example:
+        router = ws_protected_router()
+
+        @router.websocket("/ws")
+        async def ws_endpoint(websocket: WebSocket, principal: WSIdentity):
+            user_id = str(principal.id)
+            await websocket.accept()
+            ...
+    """
+    r = DualAPIRouter(dependencies=_merge([RequireWSIdentity], dependencies), **kwargs)
+    # WebSocket doesn't have OpenAPI security, but we set it for documentation
+    apply_default_security(
+        r, default_security=[{"OAuth2PasswordBearer": []}, {"SessionCookie": []}]
+    )
+    return r
+
+
+def ws_optional_router(
+    *, dependencies: Optional[Sequence[Any]] = None, **kwargs: Any
+) -> DualAPIRouter:
+    """
+    Optional auth WebSocket router - allows anonymous connections.
+
+    If a valid JWT is provided, principal will be set.
+    If no token or invalid token, principal will be None.
+
+    Example:
+        router = ws_optional_router()
+
+        @router.websocket("/ws/public")
+        async def ws_endpoint(websocket: WebSocket, principal: WSOptionalIdentity):
+            user_id = str(principal.id) if principal else "anonymous"
+            await websocket.accept()
+            ...
+    """
+    r = DualAPIRouter(dependencies=_merge([AllowWSIdentity], dependencies), **kwargs)
+    apply_default_security(r, default_security=[])
+    return r
+
+
+def ws_user_router(
+    *, dependencies: Optional[Sequence[Any]] = None, **kwargs: Any
+) -> DualAPIRouter:
+    """
+    User-only WebSocket router - requires valid user JWT (no API key).
+
+    Uses lightweight JWT validation (no database access required).
+    This is the WebSocket equivalent of `user_router()`.
+
+    Example:
+        router = ws_user_router()
+
+        @router.websocket("/ws/user")
+        async def ws_endpoint(websocket: WebSocket, principal: WSIdentity):
+            # principal.id, principal.email, principal.scopes from JWT
+            await websocket.accept()
+            ...
+    """
+    r = DualAPIRouter(dependencies=_merge([RequireWSIdentity], dependencies), **kwargs)
+    apply_default_security(
+        r, default_security=[{"OAuth2PasswordBearer": []}, {"SessionCookie": []}]
+    )
+    return r
+
+
+def ws_scopes_router(
+    *scopes: str, dependencies: Optional[Sequence[Any]] = None, **kwargs: Any
+) -> DualAPIRouter:
+    """
+    Scope-gated WebSocket router - requires valid JWT with specific scopes.
+
+    Uses lightweight JWT validation (no database access required).
+    This is the WebSocket equivalent of `scopes_router()`.
+
+    Example:
+        router = ws_scopes_router("chat:read", "chat:write")
+
+        @router.websocket("/ws/chat")
+        async def ws_endpoint(websocket: WebSocket, principal: WSIdentity):
+            # principal has verified scopes
+            await websocket.accept()
+            ...
+    """
+    r = DualAPIRouter(
+        dependencies=_merge(
+            [RequireWSIdentity, RequireWSScopes(*scopes)], dependencies
+        ),
+        **kwargs,
+    )
+    apply_default_security(
+        r, default_security=[{"OAuth2PasswordBearer": []}, {"SessionCookie": []}]
+    )
+    return r