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

svc_infra/api/fastapi/docs/add.py

@@ -0,0 +1,163 @@
+from __future__ import annotations
+
+import json
+from collections.abc import Callable
+from pathlib import Path
+
+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: str | None = 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:
+        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:
+        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:
+        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:
+            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: Callable[[], None] | 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:
+        on_generate()
+        return {"status": "ok"}
+
+    app.include_router(router)
+
+
+__all__ = ["add_docs", "add_sdk_generation_stub"]

svc_infra/api/fastapi/docs/landing.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
+from collections.abc import Iterable
 from dataclasses import dataclass
-from typing import Iterable, List, Optional
 
 FAVICON_DATA_URI = (
     "data:image/svg+xml,"
@@ -14,9 +14,9 @@ FAVICON_DATA_URI = (
 
 @dataclass(frozen=True)
 class DocTargets:
-    swagger: Optional[str] = None
-    redoc: Optional[str] = None
-    openapi_json: Optional[str] = None
+    swagger: str | None = None
+    redoc: str | None = None
+    openapi_json: str | None = None
 
 
 @dataclass(frozen=True)
@@ -31,7 +31,7 @@ def _btn(label: str, href: str) -> str:
 
 def _card(spec: CardSpec) -> str:
     tag = "/" if spec.tag.strip("/") == "" else f"/{spec.tag.strip('/')}"
-    links: List[str] = []
+    links: list[str] = []
     if spec.docs.swagger:
         links.append(_btn("Swagger", spec.docs.swagger))
     if spec.docs.redoc:
@@ -115,7 +115,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

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 import copy
-from typing import Dict, Iterable, List, Optional, Set, Tuple
+from collections.abc import Iterable
 
 from fastapi import FastAPI
 from fastapi.openapi.docs import get_redoc_html, get_swagger_ui_html
@@ -10,15 +10,15 @@ from fastapi.responses import HTMLResponse
 from svc_infra.app.env import CURRENT_ENVIRONMENT, DEV_ENV, LOCAL_ENV, Environment
 
 # (prefix, swagger_path, redoc_path, openapi_path, title)
-DOC_SCOPES: List[Tuple[str, str, str, str, str]] = []
+DOC_SCOPES: list[tuple[str, str, str, str, str]] = []
 
 _HTTP_METHODS = {"get", "put", "post", "delete", "patch", "options", "head", "trace"}
 
 
 def _path_included(
     path: str,
-    include_prefixes: Optional[Iterable[str]] = None,
-    exclude_prefixes: Optional[Iterable[str]] = None,
+    include_prefixes: Iterable[str] | None = None,
+    exclude_prefixes: Iterable[str] | None = None,
 ) -> bool:
     def _match(pfx: str) -> bool:
         pfx = pfx.rstrip("/") or "/"
@@ -31,7 +31,7 @@ def _path_included(
     return True
 
 
-def _collect_refs(obj, refset: Set[Tuple[str, str]]):
+def _collect_refs(obj, refset: set[tuple[str, str]]):
     if isinstance(obj, dict):
         for k, v in obj.items():
             if k == "$ref" and isinstance(v, str) and v.startswith("#/components/"):
@@ -46,8 +46,8 @@ def _collect_refs(obj, refset: Set[Tuple[str, str]]):
 
 
 def _close_over_component_refs(
-    full_components: Dict, initial: Set[Tuple[str, str]]
-) -> Set[Tuple[str, str]]:
+    full_components: dict, initial: set[tuple[str, str]]
+) -> set[tuple[str, str]]:
     to_visit = list(initial)
     seen = set(initial)
     while to_visit:
@@ -55,7 +55,7 @@ def _close_over_component_refs(
         comp = (full_components or {}).get(section, {}).get(name)
         if not isinstance(comp, dict):
             continue
-        nested: Set[Tuple[str, str]] = set()
+        nested: set[tuple[str, str]] = set()
         _collect_refs(comp, nested)
         for ref in nested:
             if ref not in seen:
@@ -65,14 +65,21 @@ def _close_over_component_refs(
 
 
 def _prune_to_paths(
-    full_schema: Dict, keep_paths: Dict[str, dict], title_suffix: Optional[str]
-) -> Dict:
+    full_schema: dict,
+    keep_paths: dict[str, dict],
+    title_suffix: str | None,
+    server_prefix: str | None = None,
+) -> dict:
     schema = copy.deepcopy(full_schema)
     schema["paths"] = keep_paths
 
-    used_tags: Set[str] = set()
-    direct_refs: Set[Tuple[str, str]] = set()
-    used_security_schemes: Set[str] = set()
+    # 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()
 
     for path_item in keep_paths.values():
         for method, op in path_item.items():
@@ -88,7 +95,7 @@ def _prune_to_paths(
     comps = schema.get("components") or {}
     all_refs = _close_over_component_refs(comps, direct_refs)
 
-    pruned_components: Dict[str, Dict] = {}
+    pruned_components: dict[str, dict] = {}
     if isinstance(comps, dict):
         for section, items in comps.items():
             keep_names = {name for (sec, name) in all_refs if sec == section}
@@ -114,41 +121,62 @@ def _prune_to_paths(
 
 
 def _build_filtered_schema(
-    full_schema: Dict,
+    full_schema: dict,
     *,
-    include_prefixes: Optional[List[str]] = None,
-    exclude_prefixes: Optional[List[str]] = None,
-    title_suffix: Optional[str] = None,
-) -> Dict:
+    include_prefixes: list[str] | None = None,
+    exclude_prefixes: list[str] | None = None,
+    title_suffix: str | None = None,
+) -> 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)
     }
-    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:
+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:
+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
+    app.openapi = root_filtered_openapi  # type: ignore[method-assign]
 
 
-def _current_registered_scopes() -> List[str]:
+def _current_registered_scopes() -> list[str]:
     return [scope for (scope, *_rest) in DOC_SCOPES]
 
 
@@ -158,7 +186,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: Iterable[Environment | str] | None,
+) -> set[Environment] | None:
     if envs is None:
         return None
     out: set[Environment] = set()
@@ -173,19 +203,31 @@ def add_prefixed_docs(
     prefix: str,
     title: str,
     auto_exclude_from_root: bool = True,
-    visible_envs: Optional[Iterable[Environment | str]] = (LOCAL_ENV, DEV_ENV),
+    visible_envs: Iterable[Environment | str] | None = (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"
 
     _ensure_original_openapi_saved(app)
-    _scope_cache: Dict | None = None
+    _scope_cache: dict | None = None
 
     def _scoped_schema():
         nonlocal _scope_cache
@@ -211,9 +253,6 @@ 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

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-from typing import Callable
+from collections.abc import Callable
 
 from fastapi import APIRouter
 
@@ -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

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
-from typing import Any, Optional, Sequence
+from collections.abc import Sequence
+from typing import Any
 
 from ..auth.security import (
     AllowIdentity,
@@ -10,12 +11,18 @@ 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
 
 
-def _merge(base: Optional[Sequence[Any]], extra: Optional[Sequence[Any]]) -> list[Any]:
+def _merge(base: Sequence[Any] | None, extra: Sequence[Any] | None) -> list[Any]:
     out: list[Any] = []
     if base:
         out.extend(base)
@@ -26,7 +33,7 @@ def _merge(base: Optional[Sequence[Any]], extra: Optional[Sequence[Any]]) -> lis
 
 # PUBLIC (but attach OptionalIdentity for convenience)
 def optional_identity_router(
-    *, dependencies: Optional[Sequence[Any]] = None, **kwargs: Any
+    *, dependencies: Sequence[Any] | None = None, **kwargs: Any
 ) -> DualAPIRouter:
     r = DualAPIRouter(dependencies=_merge([AllowIdentity], dependencies), **kwargs)
     apply_default_security(r, default_security=[])  # public looking in docs
@@ -35,9 +42,7 @@ def optional_identity_router(
 
 
 # PROTECTED: any auth (JWT/cookie OR API key)
-def protected_router(
-    *, dependencies: Optional[Sequence[Any]] = None, **kwargs: Any
-) -> DualAPIRouter:
+def protected_router(*, dependencies: Sequence[Any] | None = None, **kwargs: Any) -> DualAPIRouter:
     r = DualAPIRouter(dependencies=_merge([RequireIdentity], dependencies), **kwargs)
     apply_default_security(
         r,
@@ -52,7 +57,7 @@ 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: Sequence[Any] | None = None, **kwargs: Any) -> DualAPIRouter:
     r = DualAPIRouter(dependencies=_merge([RequireUser()], dependencies), **kwargs)
     apply_default_security(
         r, default_security=[{"OAuth2PasswordBearer": []}, {"SessionCookie": []}]
@@ -62,7 +67,7 @@ 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: Sequence[Any] | None = 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 +92,118 @@ 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: Sequence[Any] | None = 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: Sequence[Any] | None = 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: Sequence[Any] | None = 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: Sequence[Any] | None = 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

svc_infra/api/fastapi/dual/public.py

@@ -20,3 +20,28 @@ def public_router(**kwargs: Any) -> DualAPIRouter:
     apply_default_responses(r, DEFAULT_PUBLIC)
 
     return r
+
+
+def ws_public_router(**kwargs: Any) -> DualAPIRouter:
+    """
+    Public WebSocket router: no auth dependencies.
+
+    Use this for WebSocket endpoints that don't require authentication.
+    This is the WebSocket equivalent of `public_router()`.
+
+    Example:
+        router = ws_public_router(prefix="/api")
+
+        @router.websocket("/ws/public")
+        async def ws_endpoint(websocket: WebSocket):
+            await websocket.accept()
+            # No auth required - anyone can connect
+            async for msg in websocket.iter_json():
+                await websocket.send_json({"echo": msg})
+    """
+    r = DualAPIRouter(**kwargs)
+
+    # Keep OpenAPI consistent - no security requirement
+    apply_default_security(r, default_security=[])
+
+    return r