fastapi-identity-model 0.2.2__tar.gz → 0.3.0__tar.gz

{fastapi_identity_model-0.2.2 → fastapi_identity_model-0.3.0}/.gitignore

@@ -3,6 +3,9 @@ __pycache__/
 *.py[cod]
 *$py.class
 
+# Local scratch/working artifacts — never committed
+scratch_artifacts/
+
 # C extensions
 *.so
 

{fastapi_identity_model-0.2.2 → fastapi_identity_model-0.3.0}/CHANGELOG.md

@@ -8,6 +8,44 @@ inserted below the marker.
 
 <!-- psr: next release -->
 
+## v0.3.0 (2026-09-05)
+
+### Features
+
+- **fastapi**: Authenticate WebSockets, fix exclusion foot-guns and login self-block
+  ([#604](https://github.com/jamescrowley321/identity-model/pull/604),
+  [`6a88c56`](https://github.com/jamescrowley321/identity-model/commit/6a88c56f5798f2dbfda6a7c2c5f19535eea817ab))
+
+### Testing
+
+- **fastapi**: Address fresh-context adversarial review findings
+  ([#604](https://github.com/jamescrowley321/identity-model/pull/604),
+  [`6a88c56`](https://github.com/jamescrowley321/identity-model/commit/6a88c56f5798f2dbfda6a7c2c5f19535eea817ab))
+
+- **fastapi**: Integration + red-team coverage for WS auth, exclusion, RP composition
+  ([#604](https://github.com/jamescrowley321/identity-model/pull/604),
+  [`6a88c56`](https://github.com/jamescrowley321/identity-model/commit/6a88c56f5798f2dbfda6a7c2c5f19535eea817ab))
+
+- **fastapi**: Wire test_ws_correctness into a gated target
+  ([#604](https://github.com/jamescrowley321/identity-model/pull/604),
+  [`6a88c56`](https://github.com/jamescrowley321/identity-model/commit/6a88c56f5798f2dbfda6a7c2c5f19535eea817ab))
+
+
+## v0.2.3 (2026-09-04)
+
+### Bug Fixes
+
+- **fastapi**: Don't reflect provider/library error internals from the RP callback
+  ([#622](https://github.com/jamescrowley321/identity-model/pull/622),
+  [`2480587`](https://github.com/jamescrowley321/identity-model/commit/2480587a1ef28837ce9b36f928dcd8cef26e07cd))
+
+### Testing
+
+- **fastapi**: Cover the two genericized error branches
+  ([#622](https://github.com/jamescrowley321/identity-model/pull/622),
+  [`2480587`](https://github.com/jamescrowley321/identity-model/commit/2480587a1ef28837ce9b36f928dcd8cef26e07cd))
+
+
 ## v0.2.2 (2026-08-22)
 
 ### Bug Fixes

{fastapi_identity_model-0.2.2 → fastapi_identity_model-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: fastapi-identity-model
-Version: 0.2.2
+Version: 0.3.0
 Summary: FastAPI OIDC/OAuth2 middleware and relying-party router, built on py-identity-model
 Project-URL: Homepage, https://github.com/jamescrowley321/identity-model
 Project-URL: Repository, https://github.com/jamescrowley321/identity-model

{fastapi_identity_model-0.2.2 → fastapi_identity_model-0.3.0}/fastapi_identity_model/__init__.py

@@ -23,8 +23,9 @@ from .dependencies import (
     require_scope,
 )
 from .middleware import TokenValidationMiddleware
-from .rp import build_oidc_router
+from .rp import build_oidc_router, oidc_public_paths
 from .token_manager import TokenManager
+from .ws import build_ws_authenticator
 
 
 try:
@@ -39,11 +40,13 @@ __all__ = [
     "TokenManager",
     "TokenValidationMiddleware",
     "build_oidc_router",
+    "build_ws_authenticator",
     "get_claim_value",
     "get_claim_values",
     "get_claims",
     "get_current_user",
     "get_token",
+    "oidc_public_paths",
     "require_claim",
     "require_scope",
 ]

{fastapi_identity_model-0.2.2 → fastapi_identity_model-0.3.0}/fastapi_identity_model/config.py

@@ -7,7 +7,10 @@ import os
 
 
 def _default_excluded_paths() -> list[str]:
-    return ["/docs", "/openapi.json", "/health"]
+    # Exact paths (the middleware matches excluded_paths exactly by default;
+    # append ``/*`` for a subtree). ``/docs/oauth2-redirect`` is listed
+    # explicitly because exact matching no longer implies the ``/docs`` subtree.
+    return ["/docs", "/docs/oauth2-redirect", "/openapi.json", "/health"]
 
 
 @dataclass

{fastapi_identity_model-0.2.2 → fastapi_identity_model-0.3.0}/fastapi_identity_model/middleware.py

@@ -3,6 +3,12 @@ FastAPI middleware for OAuth2/OIDC token validation.
 
 This module provides middleware components for validating Bearer tokens
 in FastAPI applications using py-identity-model.
+
+Scope: this middleware validates **HTTP** requests only. It extends Starlette's
+``BaseHTTPMiddleware``, which forwards every non-HTTP ASGI scope (WebSocket,
+lifespan) straight to the app without calling ``dispatch`` — so WebSocket
+handshakes are **not** authenticated here (issue #598). Guard WebSocket routes
+with :func:`fastapi_identity_model.build_ws_authenticator` instead.
 """
 
 from collections.abc import Callable
@@ -78,6 +84,32 @@ def _is_upstream_fetch_failure(exc: Exception) -> bool:
     return any(message.startswith(p) for p in _UPSTREAM_FETCH_FAILURE_PREFIXES)
 
 
+def evaluate_token_type(
+    claims: dict,
+    *,
+    require_access_token_marker: bool,
+    access_token_marker_claims: tuple[str, ...],
+) -> str | None:
+    """Reason string if *claims* are the wrong token type for a resource server
+    (an ID token presented as an access token), else ``None``.
+
+    Pure and transport-agnostic so the HTTP middleware and the WebSocket
+    authenticator (:func:`fastapi_identity_model.build_ws_authenticator`) apply
+    a byte-for-byte identical check — the F-07 defence must not diverge between
+    the two entry points. See :meth:`TokenValidationMiddleware._wrong_token_type_error`
+    for the semantics of the two complementary checks.
+    """
+    if any(c in claims for c in _ID_TOKEN_ONLY_CLAIMS):
+        return "ID token cannot be used as an access token"
+    if require_access_token_marker and not any(
+        c in claims for c in access_token_marker_claims
+    ):
+        return (
+            "Access token required; presented token lacks an access-token marker claim"
+        )
+    return None
+
+
 class TokenValidationMiddleware(BaseHTTPMiddleware):
     """
     Middleware for validating Bearer tokens on incoming requests.
@@ -92,10 +124,15 @@ class TokenValidationMiddleware(BaseHTTPMiddleware):
             audience does not enforce ``aud`` for tokens that omit the claim,
             which on a shared multi-tenant issuer accepts tokens minted for
             other clients.
-        excluded_paths: Paths that skip token validation. A path matches if it
-            equals an entry or is a subpath of one (``/docs`` also covers
-            ``/docs/oauth2-redirect``). Pass ``[]`` to exclude nothing. When
-            omitted, defaults to ``/docs``, ``/openapi.json``, ``/health``.
+        excluded_paths: Paths that skip token validation. Matching is **exact**
+            by default: ``/health`` excludes only ``/health``, never
+            ``/health/db-dump`` (issue #600 — exact-match fails closed so a
+            nested route under an excluded prefix is not silently exposed). To
+            exclude a whole subtree, append ``/*`` to the entry: ``/docs/*``
+            excludes ``/docs`` and every path beneath it. Pass ``[]`` to
+            exclude nothing. When omitted, defaults to ``/docs``,
+            ``/docs/oauth2-redirect`` (the Swagger OAuth2 redirect),
+            ``/openapi.json``, ``/health``.
         custom_claims_validator: Optional custom function to validate additional claims
         require_access_token_marker: Opt-in ID-token-substitution defence
             (F-07), default ``False`` (behaviour unchanged). When ``True``, a
@@ -149,21 +186,36 @@ class TokenValidationMiddleware(BaseHTTPMiddleware):
         self.excluded_paths = (
             excluded_paths
             if excluded_paths is not None
-            else ["/docs", "/openapi.json", "/health"]
+            else ["/docs", "/docs/oauth2-redirect", "/openapi.json", "/health"]
         )
         self.custom_claims_validator = custom_claims_validator
 
     def _is_excluded(self, path: str) -> bool:
-        """Whether *path* equals or is a subpath of an excluded entry.
+        """Whether *path* is excluded from token validation.
+
+        Matching is **exact** by default: an entry ``/health`` excludes only
+        ``/health``, never ``/health/db-dump``. To exclude a whole subtree,
+        append ``/*`` to the entry — ``/docs/*`` excludes ``/docs`` and every
+        path beneath it. Exact-by-default fails closed: adding a nested route
+        under an excluded prefix does not silently expose it (issue #600).
+
+        A bare ``/*`` (root subtree) is ignored rather than excluding every
+        path — disabling auth wholesale must be an explicit choice (don't add
+        the middleware), never a one-character typo.
 
-        A bare ``/`` entry matches only the root, never as a subpath prefix
-        (otherwise it would exclude every path).
+        Caution: subtree (``/*``) matching runs on the raw ASGI request path,
+        not a normalized one. If you place a ``..``-resolving handler (e.g. a
+        ``StaticFiles`` mount) under an excluded ``/*`` prefix, a request whose
+        path *string* starts with that prefix but resolves elsewhere is treated
+        as excluded. Keep ``/*`` exclusions off subtrees that normalize paths;
+        the default (exact match) is immune.
         """
         for entry in self.excluded_paths:
-            if path == entry:
-                return True
-            prefix = entry.rstrip("/")
-            if prefix and path.startswith(prefix + "/"):
+            if entry.endswith("/*"):
+                prefix = entry[:-2].rstrip("/")
+                if prefix and (path == prefix or path.startswith(prefix + "/")):
+                    return True
+            elif path == entry:
                 return True
         return False
 
@@ -202,16 +254,11 @@ class TokenValidationMiddleware(BaseHTTPMiddleware):
           access-token marker (``scope``/``scp`` by default). Off by default —
           behaviour unchanged unless explicitly enabled.
         """
-        if any(c in claims for c in _ID_TOKEN_ONLY_CLAIMS):
-            return "ID token cannot be used as an access token"
-        if self.require_access_token_marker and not any(
-            c in claims for c in self.access_token_marker_claims
-        ):
-            return (
-                "Access token required; presented token lacks an "
-                "access-token marker claim"
-            )
-        return None
+        return evaluate_token_type(
+            claims,
+            require_access_token_marker=self.require_access_token_marker,
+            access_token_marker_claims=self.access_token_marker_claims,
+        )
 
     async def _authenticate(self, request: Request, token: str) -> JSONResponse | None:
         """Validate *token* and attach claims; return an error response or None."""

{fastapi_identity_model-0.2.2 → fastapi_identity_model-0.3.0}/fastapi_identity_model/rp.py

@@ -67,6 +67,51 @@ logger = logging.getLogger("fastapi_identity_model")
 
 _STATE_TOKEN_BYTES = 32
 
+# Paths registered by build_oidc_router, relative to the router's mount prefix.
+# /callback is shared by the GET and POST (form_post) handlers.
+_OIDC_ROUTER_PATHS = ("/login", "/callback", "/logout")
+
+
+def oidc_public_paths(prefix: str = "") -> list[str]:
+    """Return the paths ``build_oidc_router`` registers, for the RS middleware.
+
+    A globally-installed :class:`TokenValidationMiddleware` would otherwise
+    demand a Bearer token on ``/login`` and ``/callback`` — routes that by
+    definition have no token yet — making login impossible (issue #599). Feed
+    these into the middleware's ``excluded_paths`` so the login flow is
+    reachable::
+
+        router_prefix = "/auth"
+        app.include_router(build_oidc_router(settings), prefix=router_prefix)
+        app.add_middleware(
+            TokenValidationMiddleware,
+            discovery_url=settings.discovery_url,
+            audience=settings.audience,
+            excluded_paths=[
+                *settings.excluded_paths,
+                *oidc_public_paths(router_prefix),
+            ],
+        )
+
+    Args:
+        prefix: The same ``prefix`` passed to ``include_router`` (``""`` when
+            the router is mounted at the app root). A trailing slash is
+            normalized away.
+
+    Returns:
+        Absolute, exact paths (no ``/*`` subtree wildcard) — the login,
+        callback, and logout endpoints.
+    """
+    base = prefix.rstrip("/")
+    # Normalize a missing leading slash: request paths are always absolute, so a
+    # relative ``base`` ("auth" instead of "/auth") would produce entries that
+    # can never match and silently fail to exclude the login routes. FastAPI's
+    # include_router already requires a leading-slash prefix; this just makes the
+    # helper robust if called directly.
+    if base and not base.startswith("/"):
+        base = f"/{base}"
+    return [f"{base}{route}" for route in _OIDC_ROUTER_PATHS]
+
 
 def _flow_key(session_key: str) -> str:
     """Session key holding transient login-flow state (state/nonce/verifier).
@@ -103,9 +148,13 @@ async def _discover(settings: OIDCSettings) -> DiscoveryDocumentResponse:
         DiscoveryDocumentRequest(address=settings.discovery_url),
     )
     if not disco.is_successful:
+        # Log the provider's specific error for operators; return a generic
+        # detail so the callback endpoint cannot be probed for upstream
+        # internals (mirrors the resource-server middleware's F-18 posture).
+        logger.warning("OIDC discovery failed: %s", disco.error)
         raise HTTPException(
             status_code=status.HTTP_502_BAD_GATEWAY,
-            detail=f"OIDC discovery failed: {disco.error}",
+            detail="Identity provider discovery failed",
         )
     # OIDC Discovery 1.0 §4.3: the document's issuer MUST match the URL the
     # document was retrieved from (issuer mix-up defense). The library only
@@ -114,12 +163,14 @@ async def _discover(settings: OIDCSettings) -> DiscoveryDocumentResponse:
     # document at "https://op/.well-known/openid-configuration".
     expected = _expected_issuer(settings.discovery_url)
     if (disco.issuer or "").rstrip("/") != expected:
+        logger.warning(
+            "Discovery document issuer mismatch: expected %r, got %r",
+            expected,
+            disco.issuer,
+        )
         raise HTTPException(
             status_code=status.HTTP_502_BAD_GATEWAY,
-            detail=(
-                f"Discovery document issuer mismatch: expected '{expected}', "
-                f"got '{disco.issuer}'"
-            ),
+            detail="Identity provider configuration error",
         )
     return disco
 
@@ -181,9 +232,10 @@ async def _exchange_code(
         ),
     )
     if not tok.is_successful or not tok.token:
+        logger.warning("Token exchange failed: %s", tok.error)
         raise HTTPException(
             status_code=status.HTTP_400_BAD_REQUEST,
-            detail=f"Token exchange failed: {tok.error}",
+            detail="Authorization code exchange failed",
         )
     return tok.token
 
@@ -210,9 +262,10 @@ async def _validate_id_token(
             disco_doc_address=settings.discovery_url,
         )
     except PyIdentityModelException as exc:
+        logger.info("ID token validation failed: %s", exc)
         raise HTTPException(
             status_code=status.HTTP_401_UNAUTHORIZED,
-            detail=f"ID token validation failed: {exc}",
+            detail="ID token validation failed",
         ) from exc
 
     # Nonce binding is the RP's responsibility — the library does not check it.
@@ -278,14 +331,19 @@ async def _callback(  # noqa: PLR0913  # request-scoped args + the router's buil
     try:
         cb = parse_authorize_callback_response(callback_url)
     except PyIdentityModelException as exc:
+        logger.info("Malformed authorization callback: %s", exc)
         raise HTTPException(
             status_code=status.HTTP_400_BAD_REQUEST,
-            detail=f"Malformed authorization callback: {exc}",
+            detail="Malformed authorization response",
         ) from exc
     if not cb.is_successful:
+        # ``cb.error`` is the provider's OAuth 2.0 ``error`` param, but it can
+        # carry an attacker-influenced ``error_description``; log it, return a
+        # generic detail rather than reflecting it to the browser.
+        logger.info("Authorization error from provider: %s", cb.error)
         raise HTTPException(
             status_code=status.HTTP_400_BAD_REQUEST,
-            detail=f"Authorization error: {cb.error}",
+            detail="Authorization request failed",
         )
     if not validate_authorize_callback_state(cb, flow["state"]).is_valid:
         raise HTTPException(

fastapi_identity_model-0.3.0/fastapi_identity_model/ws.py

@@ -0,0 +1,236 @@
+"""WebSocket authentication for FastAPI.
+
+:class:`TokenValidationMiddleware` extends Starlette's ``BaseHTTPMiddleware``,
+which forwards every non-HTTP ASGI scope to the app untouched — so WebSocket
+handshakes bypass it entirely and a globally-installed middleware does **not**
+authenticate WebSocket routes (issue #598). Browsers also cannot set an
+``Authorization`` header on the WebSocket handshake, so bearer-in-header auth is
+not transparently available for WebSockets the way it is for HTTP.
+
+:func:`build_ws_authenticator` returns a FastAPI dependency that authenticates a
+WebSocket by validating a Bearer token taken from (in order) the
+``Authorization`` header (non-browser clients) or a query parameter (browsers).
+It runs the **same** core ``validate_token`` path and the **same**
+ID-token-substitution guard (:func:`fastapi_identity_model.middleware.evaluate_token_type`,
+F-07) as the HTTP middleware, and closes the socket with a policy-violation code
+on failure. The close *reason* is generic (mirroring the middleware's F-18
+non-oracle 401); the specific cause is logged server-side.
+
+    from fastapi import Depends, FastAPI, WebSocket
+    from fastapi_identity_model import build_ws_authenticator
+
+    app = FastAPI()
+    ws_auth = build_ws_authenticator(
+        discovery_url="https://op/.well-known/openid-configuration",
+        audience="my-api",
+    )
+
+    @app.websocket("/ws")
+    async def ws(websocket: WebSocket, claims: dict = Depends(ws_auth)):
+        await websocket.accept()
+        await websocket.send_json({"sub": claims.get("sub")})
+
+The browser opens it as ``new WebSocket("wss://host/ws?access_token=<token>")``.
+Prefer a short-lived token in the query string; query strings can land in logs.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+from fastapi import WebSocket, WebSocketException, status  # type: ignore[attr-defined]
+from jwt import InvalidTokenError
+
+from py_identity_model import (
+    NetworkException,
+    PyIdentityModelException,
+    TokenValidationConfig,
+    to_principal,
+)
+from py_identity_model.aio import validate_token
+
+from .middleware import (
+    _DEFAULT_ACCESS_TOKEN_MARKER_CLAIMS,
+    _is_upstream_fetch_failure,
+    evaluate_token_type,
+)
+
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+
+logger = logging.getLogger("fastapi_identity_model")
+
+# Expected number of parts in "Bearer <token>".
+_BEARER_HEADER_PART_COUNT = 2
+
+# WebSocket close codes (RFC 6455 §7.4.1). Auth rejection → policy violation;
+# transient upstream (discovery/JWKS fetch) failure → try again later so the
+# client backs off rather than treating it as a bad token; an unexpected fault
+# → internal error.
+_WS_POLICY_VIOLATION = status.WS_1008_POLICY_VIOLATION
+_WS_TRY_AGAIN_LATER = status.WS_1013_TRY_AGAIN_LATER
+_WS_INTERNAL_ERROR = status.WS_1011_INTERNAL_ERROR
+
+# Generic, non-oracle close reason for every auth rejection cause (signature /
+# audience / expiry / wrong-type), mirroring the middleware's F-18 401 body so
+# the close frame cannot distinguish rejection causes. WebSocket close reasons
+# must be <= 123 UTF-8 bytes (RFC 6455 §5.5.1); this is well under.
+_GENERIC_REJECT_REASON = "Invalid or unauthorized token"
+
+
+def _extract_ws_token(websocket: WebSocket, query_param: str) -> str | None:
+    """Return the bearer token from the Authorization header or query param.
+
+    Header wins when present (non-browser clients). A present-but-malformed
+    Authorization header returns ``None`` rather than falling through to the
+    query param, so a client cannot smuggle a second token past a broken header.
+    """
+    header = websocket.headers.get("Authorization")
+    if header is not None:
+        parts = header.split()
+        if len(parts) == _BEARER_HEADER_PART_COUNT and parts[0].lower() == "bearer":
+            return parts[1]
+        return None
+    token = websocket.query_params.get(query_param)
+    return token or None
+
+
+def build_ws_authenticator(  # noqa: PLR0913  # mirrors the middleware's opt-in F-07 marker config + a WS token-source knob
+    discovery_url: str,
+    audience: str,
+    *,
+    query_param: str = "access_token",
+    custom_claims_validator: Callable | None = None,
+    require_access_token_marker: bool = False,
+    access_token_marker_claims: tuple[str, ...] = _DEFAULT_ACCESS_TOKEN_MARKER_CLAIMS,
+) -> Callable:
+    """Build a FastAPI WebSocket dependency that validates a Bearer token.
+
+    Mirrors :class:`TokenValidationMiddleware` for WebSocket routes, which the
+    HTTP middleware cannot reach (issue #598).
+
+    Args:
+        discovery_url: The OpenID Connect discovery document URL.
+        audience: Expected ``aud`` claim. Required — a ``None`` audience does
+            not enforce ``aud`` for tokens that omit it, which on a shared
+            multi-tenant issuer accepts tokens minted for other clients.
+        query_param: Query-string parameter carrying the token when no
+            ``Authorization`` header is present (browsers). Default
+            ``access_token``.
+        custom_claims_validator: Optional injectable claims validator, threaded
+            into ``TokenValidationConfig`` exactly as the HTTP middleware does.
+        require_access_token_marker: Opt-in ID-token-substitution defence (F-07),
+            default ``False``. See :class:`TokenValidationMiddleware`.
+        access_token_marker_claims: Positive access-token marker claims for
+            ``require_access_token_marker``. Defaults to ``("scope", "scp")``.
+
+    Returns:
+        An async dependency ``(websocket) -> dict`` returning the validated
+        claims. On failure it raises :class:`fastapi.WebSocketException`, which
+        FastAPI turns into a handshake close with the given code — the socket is
+        never accepted. The validated claims/principal/token are also attached
+        to ``websocket.state`` (``.claims`` / ``.user`` / ``.token``).
+
+    Note:
+        This performs **authentication only** — it validates the token and
+        rejects the wrong token type. It does **not** enforce scopes or any
+        authorization, and there is no WebSocket equivalent of
+        ``require_scope``. Check ``claims`` (or ``websocket.state.claims``) for
+        the scopes/roles a route requires yourself, mirroring what
+        ``require_scope`` does for HTTP routes.
+
+        The close *code* (1008 policy / 1013 try-again / 1011 internal) is the
+        WebSocket-native rejection signal — visible to programmatic WS clients
+        and in server logs. A **browser** sees a rejection as an HTTP 403
+        handshake denial (all pre-accept close codes surface the same way), so
+        do not rely on the code being distinguishable browser-side.
+    """
+    if not audience:
+        raise ValueError(
+            "build_ws_authenticator requires a non-empty 'audience'; a "
+            "None/empty audience skips aud enforcement for aud-less tokens."
+        )
+    if require_access_token_marker and not access_token_marker_claims:
+        raise ValueError(
+            "require_access_token_marker=True needs a non-empty "
+            "access_token_marker_claims; an empty set rejects every token."
+        )
+
+    async def authenticate_websocket(websocket: WebSocket) -> dict:
+        token = _extract_ws_token(websocket, query_param)
+        if not token:
+            # Structural failure (no/!bearer token) — distinct from a validation
+            # rejection, exactly as the HTTP middleware distinguishes "Missing
+            # Authorization header" from the generic 401.
+            raise WebSocketException(
+                code=_WS_POLICY_VIOLATION,
+                reason="Missing or malformed bearer token",
+            )
+        try:
+            claims = await validate_token(
+                jwt=token,
+                token_validation_config=TokenValidationConfig(
+                    perform_disco=True,
+                    audience=audience,
+                    claims_validator=custom_claims_validator,
+                ),
+                disco_doc_address=discovery_url,
+            )
+        except PyIdentityModelException as e:
+            if isinstance(e, NetworkException) or _is_upstream_fetch_failure(e):
+                logger.exception("Upstream fetch failure during WS token validation")
+                raise WebSocketException(
+                    code=_WS_TRY_AGAIN_LATER,
+                    reason="Authentication temporarily unavailable",
+                ) from e
+            logger.info("WS token rejected during validation: %s", e)
+            raise WebSocketException(
+                code=_WS_POLICY_VIOLATION, reason=_GENERIC_REJECT_REASON
+            ) from e
+        except InvalidTokenError as e:
+            logger.info("Malformed WS token rejected: %s", e)
+            raise WebSocketException(
+                code=_WS_POLICY_VIOLATION, reason=_GENERIC_REJECT_REASON
+            ) from e
+        except WebSocketException:
+            raise
+        except Exception as e:
+            logger.exception("Unexpected error during WS token validation")
+            raise WebSocketException(
+                code=_WS_INTERNAL_ERROR,
+                reason="Internal error during authentication",
+            ) from e
+
+        wrong_type = evaluate_token_type(
+            claims,
+            require_access_token_marker=require_access_token_marker,
+            access_token_marker_claims=access_token_marker_claims,
+        )
+        if wrong_type is not None:
+            # Log the specific reason; return the generic one to the client.
+            logger.info("WS token rejected (wrong type): %s", wrong_type)
+            raise WebSocketException(
+                code=_WS_POLICY_VIOLATION, reason=_GENERIC_REJECT_REASON
+            )
+
+        # Build the principal under the same fail-closed guard as the HTTP
+        # middleware (which runs to_principal inside its try → 500): an
+        # unexpected failure here becomes a mapped 1011 close, never an
+        # unhandled exception that escapes after the token already validated.
+        try:
+            principal = to_principal(claims)
+        except Exception as e:
+            logger.exception("Unexpected error building principal during WS auth")
+            raise WebSocketException(
+                code=_WS_INTERNAL_ERROR,
+                reason="Internal error during authentication",
+            ) from e
+        websocket.state.user = principal
+        websocket.state.claims = claims
+        websocket.state.token = token
+        return claims
+
+    return authenticate_websocket

{fastapi_identity_model-0.2.2 → fastapi_identity_model-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "fastapi-identity-model"
-version = "0.2.2"
+version = "0.3.0"
 description = "FastAPI OIDC/OAuth2 middleware and relying-party router, built on py-identity-model"
 authors = [{ name = "jamescrowley321", email = "jamescrowley151@gmail.com" }]
 requires-python = ">=3.12"

{fastapi_identity_model-0.2.2 → fastapi_identity_model-0.3.0}/tests/test_config.py

@@ -14,7 +14,12 @@ def test_audience_defaults_to_client_id():
     )
     assert s.audience == "cid"
     assert s.scope == "openid profile email"
-    assert s.excluded_paths == ["/docs", "/openapi.json", "/health"]
+    assert s.excluded_paths == [
+        "/docs",
+        "/docs/oauth2-redirect",
+        "/openapi.json",
+        "/health",
+    ]
 
 
 def test_explicit_audience_preserved():
@@ -57,7 +62,12 @@ def test_from_env_default_excluded_paths(monkeypatch):
     monkeypatch.setenv("OIDC_REDIRECT_URI", "r")
     monkeypatch.delenv("OIDC_EXCLUDED_PATHS", raising=False)
     s = OIDCSettings.from_env()
-    assert s.excluded_paths == ["/docs", "/openapi.json", "/health"]
+    assert s.excluded_paths == [
+        "/docs",
+        "/docs/oauth2-redirect",
+        "/openapi.json",
+        "/health",
+    ]
 
 
 def test_from_env_redirect_uri_optional_for_resource_server(monkeypatch):

{fastapi_identity_model-0.2.2 → fastapi_identity_model-0.3.0}/tests/test_middleware.py

@@ -145,12 +145,13 @@ async def test_id_token_rejected_as_access_token(monkeypatch):
     assert "ID token" in resp.json()["detail"]
 
 
-async def test_excluded_subpath_skips_validation(monkeypatch):
-    # A subpath of an excluded entry is also excluded: it reaches routing
-    # (404, no such route) rather than being blocked with a 401.
+async def test_excluded_subpath_is_validated_by_default(monkeypatch):
+    # Issue #600: matching is exact by default, so a subpath of an excluded
+    # entry ("/health") is NOT excluded — it is validated and, with no token,
+    # rejected 401 (fail closed) rather than silently reaching routing.
     async with _client(_app(monkeypatch, AsyncMock())) as client:
         resp = await client.get("/health/live")
-    assert resp.status_code != 401
+    assert resp.status_code == 401
 
 
 async def test_options_preflight_passes_through(monkeypatch):
@@ -183,7 +184,62 @@ def test_root_excluded_path_is_not_a_catch_all():
     assert mw_obj._is_excluded("/") is True
     assert mw_obj._is_excluded("/api/me") is False
     assert mw_obj._is_excluded("/docs") is True
+
+
+def test_exact_match_default_does_not_exclude_subpaths():
+    # Issue #600: matching is exact by default. A plain "/health" entry must NOT
+    # exclude a nested route — fail closed so a sensitive nested path under an
+    # excluded prefix is not silently exposed.
+    mw_obj = TokenValidationMiddleware(
+        FastAPI(),
+        discovery_url=DISCOVERY_URL,
+        audience="cid",
+        excluded_paths=["/health", "/docs"],
+    )
+    assert mw_obj._is_excluded("/health") is True
+    assert mw_obj._is_excluded("/health/db-dump") is False
+    assert mw_obj._is_excluded("/docs/oauth2-redirect") is False
+
+
+def test_subtree_wildcard_opt_in_excludes_prefix_and_below():
+    # A trailing "/*" is the explicit opt-in for subtree exclusion.
+    mw_obj = TokenValidationMiddleware(
+        FastAPI(),
+        discovery_url=DISCOVERY_URL,
+        audience="cid",
+        excluded_paths=["/docs/*"],
+    )
+    assert mw_obj._is_excluded("/docs") is True
+    assert mw_obj._is_excluded("/docs/oauth2-redirect") is True
+    assert mw_obj._is_excluded("/docs/anything/deep") is True
+    # A sibling that merely shares the string prefix is not under the subtree.
+    assert mw_obj._is_excluded("/docsx") is False
+
+
+def test_bare_star_is_not_a_catch_all():
+    # "/*" (root subtree) must not disable auth wholesale via a one-char typo.
+    mw_obj = TokenValidationMiddleware(
+        FastAPI(),
+        discovery_url=DISCOVERY_URL,
+        audience="cid",
+        excluded_paths=["/*"],
+    )
+    assert mw_obj._is_excluded("/anything") is False
+    assert mw_obj._is_excluded("/") is False
+
+
+def test_default_excluded_paths_cover_swagger_oauth2_redirect():
+    # Exact matching no longer implies the /docs subtree, so the Swagger OAuth2
+    # redirect must be listed explicitly in the defaults.
+    mw_obj = TokenValidationMiddleware(
+        FastAPI(), discovery_url=DISCOVERY_URL, audience="cid"
+    )
+    assert mw_obj._is_excluded("/docs") is True
     assert mw_obj._is_excluded("/docs/oauth2-redirect") is True
+    assert mw_obj._is_excluded("/openapi.json") is True
+    assert mw_obj._is_excluded("/health") is True
+    # But not an arbitrary nested route under the excluded docs path.
+    assert mw_obj._is_excluded("/docs/secret") is False
 
 
 def test_access_token_marker_defaults_off():

{fastapi_identity_model-0.2.2 → fastapi_identity_model-0.3.0}/tests/test_rp.py

@@ -1,3 +1,4 @@
+import logging
 from types import SimpleNamespace
 from unittest.mock import AsyncMock
 from urllib.parse import parse_qs, urlparse
@@ -7,8 +8,14 @@ import httpx
 import pytest
 from starlette.middleware.sessions import SessionMiddleware
 
-from fastapi_identity_model import OIDCSettings, build_oidc_router, rp
-from py_identity_model import TokenValidationException
+from fastapi_identity_model import (
+    OIDCSettings,
+    TokenValidationMiddleware,
+    build_oidc_router,
+    oidc_public_paths,
+    rp,
+)
+from py_identity_model import AuthorizeCallbackException, TokenValidationException
 
 
 pytestmark = pytest.mark.unit
@@ -183,15 +190,20 @@ async def test_callback_missing_code(monkeypatch):
     assert "missing code" in resp.json()["detail"]
 
 
-async def test_login_discovery_failure(monkeypatch):
+async def test_login_discovery_failure(monkeypatch, caplog):
     _patch(monkeypatch, disco=SimpleNamespace(is_successful=False, error="down"))
-    async with _client(_app()) as client:
-        resp = await client.get("/auth/login")
+    with caplog.at_level(logging.WARNING, logger="fastapi_identity_model"):
+        async with _client(_app()) as client:
+            resp = await client.get("/auth/login")
     assert resp.status_code == 502
-    assert "discovery failed" in resp.json()["detail"].lower()
+    # Generic client detail — the provider's specific error must not be echoed
+    # to the browser (#601), but IS logged server-side for operators.
+    assert resp.json()["detail"] == "Identity provider discovery failed"
+    assert "down" not in resp.json()["detail"]
+    assert "down" in caplog.text
 
 
-async def test_login_rejects_discovery_issuer_mismatch(monkeypatch):
+async def test_login_rejects_discovery_issuer_mismatch(monkeypatch, caplog):
     # OIDC Discovery 1.0 §4.3: a document whose issuer does not match the
     # URL it was retrieved from must be rejected (issuer mix-up defense).
     mismatched = SimpleNamespace(
@@ -203,10 +215,15 @@ async def test_login_rejects_discovery_issuer_mismatch(monkeypatch):
         issuer="https://op/INVALID",
     )
     _patch(monkeypatch, disco=mismatched)
-    async with _client(_app()) as client:
-        resp = await client.get("/auth/login")
+    with caplog.at_level(logging.WARNING, logger="fastapi_identity_model"):
+        async with _client(_app()) as client:
+            resp = await client.get("/auth/login")
     assert resp.status_code == 502
-    assert "issuer mismatch" in resp.json()["detail"].lower()
+    # The mismatched issuer value is not reflected to the client (#601)...
+    assert resp.json()["detail"] == "Identity provider configuration error"
+    assert "INVALID" not in resp.json()["detail"]
+    # ...but the expected/got pair is logged for operators.
+    assert "INVALID" in caplog.text
 
 
 async def test_fetch_userinfo_disabled_skips_userinfo(monkeypatch):
@@ -224,26 +241,84 @@ async def test_fetch_userinfo_disabled_skips_userinfo(monkeypatch):
     rp.get_userinfo.assert_not_called()
 
 
-async def test_callback_token_exchange_failure(monkeypatch):
+async def test_callback_token_exchange_failure(monkeypatch, caplog):
     _patch(monkeypatch)
     async with _client(_app()) as client:
         state, _ = await _login(client)
         rp.request_authorization_code_token.return_value = SimpleNamespace(
             is_successful=False, error="invalid_grant", token=None
         )
-        resp = await client.get(f"/auth/callback?code=abc&state={state}")
+        with caplog.at_level(logging.WARNING, logger="fastapi_identity_model"):
+            resp = await client.get(f"/auth/callback?code=abc&state={state}")
     assert resp.status_code == 400
-    assert "Token exchange failed" in resp.json()["detail"]
+    # The provider's grant error is logged, not reflected to the client (#601).
+    assert resp.json()["detail"] == "Authorization code exchange failed"
+    assert "invalid_grant" not in resp.json()["detail"]
+    assert "invalid_grant" in caplog.text
 
 
-async def test_callback_invalid_id_token(monkeypatch):
+async def test_callback_invalid_id_token(monkeypatch, caplog):
     _patch(monkeypatch)
     async with _client(_app()) as client:
         state, _ = await _login(client)
         rp.validate_token.side_effect = TokenValidationException("bad iss")
-        resp = await client.get(f"/auth/callback?code=abc&state={state}")
+        with caplog.at_level(logging.INFO, logger="fastapi_identity_model"):
+            resp = await client.get(f"/auth/callback?code=abc&state={state}")
     assert resp.status_code == 401
-    assert "ID token validation failed" in resp.json()["detail"]
+    # Generic detail — the specific validation cause ("bad iss") is logged, not
+    # returned, so the callback can't be used as a validation-stage oracle (#601).
+    assert resp.json()["detail"] == "ID token validation failed"
+    assert "bad iss" not in resp.json()["detail"]
+    assert "bad iss" in caplog.text
+
+
+async def test_callback_malformed_response_detail_is_generic(monkeypatch, caplog):
+    # A parse failure must return a generic detail: the library's exception
+    # text (which can carry attacker-influenced callback contents) is logged
+    # server-side, never reflected to the browser (#601).
+    secret = "parse-cause-4c2e9a-do-not-leak"
+
+    def _raise(_url):
+        raise AuthorizeCallbackException(secret)
+
+    _patch(monkeypatch)
+    monkeypatch.setattr(rp, "parse_authorize_callback_response", _raise)
+    async with _client(_app()) as client:
+        state, _ = await _login(client)
+        with caplog.at_level(logging.INFO, logger="fastapi_identity_model"):
+            resp = await client.get(f"/auth/callback?code=abc&state={state}")
+    assert resp.status_code == 400
+    # Generic detail — pre-#622 this reflected f"...: {exc}"; the parser's
+    # exception text must not appear anywhere in the response body.
+    assert resp.json()["detail"] == "Malformed authorization response"
+    assert secret not in resp.text
+    # ...but the real cause IS logged for operators.
+    assert secret in caplog.text
+
+
+async def test_callback_provider_error_detail_is_generic(monkeypatch, caplog):
+    # A provider error response (?error=...) must return a generic detail:
+    # neither the provider's error code nor the attacker-controllable
+    # error_description is reflected to the browser (#601).
+    secret = "err-desc-secret-8b7c1d-do-not-leak"
+    _patch(monkeypatch)
+    async with _client(_app()) as client:
+        state, _ = await _login(client)
+        with caplog.at_level(logging.INFO, logger="fastapi_identity_model"):
+            resp = await client.get(
+                f"/auth/callback?state={state}"
+                f"&error=access_denied&error_description={secret}"
+            )
+    assert resp.status_code == 400
+    # Generic detail — pre-#622 this reflected f"Authorization error: {cb.error}".
+    assert resp.json()["detail"] == "Authorization request failed"
+    # Neither the error code nor the attacker-influenced description leaks to
+    # the client...
+    assert "access_denied" not in resp.text
+    assert secret not in resp.text
+    # ...but the error code IS logged for operators (the description is not).
+    assert "access_denied" in caplog.text
+    assert secret not in caplog.text
 
 
 async def test_callback_nonce_mismatch(monkeypatch):
@@ -327,3 +402,74 @@ async def test_logout_clears_session(monkeypatch):
         resp = await client.post("/auth/logout")
         assert resp.status_code == 303
         assert (await client.get("/me")).json() == {}
+
+
+def _composed_app(excluded_paths) -> FastAPI:
+    """App with the login router AND the RS middleware installed together —
+    the combined RP+RS deployment from issue #599."""
+    app = FastAPI()
+    app.add_middleware(SessionMiddleware, secret_key="test-secret")
+    app.include_router(build_oidc_router(SETTINGS), prefix="/auth")
+    app.add_middleware(
+        TokenValidationMiddleware,
+        discovery_url=SETTINGS.discovery_url,
+        audience=SETTINGS.audience,
+        excluded_paths=excluded_paths,
+    )
+
+    @app.get("/protected")
+    async def protected():
+        return {"ok": True}
+
+    return app
+
+
+async def test_middleware_composition_excludes_login_routes(monkeypatch):
+    # Issue #599: with oidc_public_paths wired into excluded_paths, the login
+    # route is reachable THROUGH a globally-installed middleware (302), while a
+    # non-excluded route still requires a token.
+    _patch(monkeypatch)
+    app = _composed_app(oidc_public_paths("/auth"))
+    async with _client(app) as client:
+        login = await client.get("/auth/login")
+        assert login.status_code == 302
+        assert login.headers["location"].startswith("https://op/authorize")
+        assert (await client.get("/protected")).status_code == 401
+
+
+async def test_middleware_without_exclusion_blocks_login(monkeypatch):
+    # The bug #599 fixes: without the exclusion the middleware demands a bearer
+    # token on /auth/login itself, making login impossible.
+    _patch(monkeypatch)
+    app = _composed_app([])
+    async with _client(app) as client:
+        assert (await client.get("/auth/login")).status_code == 401
+
+
+def test_oidc_public_paths_with_prefix():
+    # Issue #599: the RS middleware must be able to exclude the login routes.
+    assert oidc_public_paths("/auth") == [
+        "/auth/login",
+        "/auth/callback",
+        "/auth/logout",
+    ]
+
+
+def test_oidc_public_paths_normalizes_missing_leading_slash():
+    # A relative prefix would yield paths that can never match request.url.path
+    # (always absolute), silently failing to exclude the login routes.
+    assert oidc_public_paths("auth") == [
+        "/auth/login",
+        "/auth/callback",
+        "/auth/logout",
+    ]
+
+
+def test_oidc_public_paths_root_and_trailing_slash():
+    assert oidc_public_paths() == ["/login", "/callback", "/logout"]
+    # A trailing slash on the prefix is normalized away (no doubled slash).
+    assert oidc_public_paths("/auth/") == [
+        "/auth/login",
+        "/auth/callback",
+        "/auth/logout",
+    ]

fastapi_identity_model-0.3.0/tests/test_ws.py

@@ -0,0 +1,239 @@
+"""WebSocket authentication (issue #598).
+
+WebSocket handshakes bypass ``BaseHTTPMiddleware`` entirely, so
+``TokenValidationMiddleware`` cannot guard them. ``build_ws_authenticator``
+provides an equivalent FastAPI dependency that runs the same core
+``validate_token`` path and the same F-07 ID-token-substitution guard, closing
+the socket on failure.
+
+The dependency is exercised directly with a fake ``WebSocket`` (its only ASGI
+surface here is ``.headers`` / ``.query_params`` / ``.state``), isolating the
+authenticator's own logic — the same mock-``validate_token`` approach the HTTP
+middleware tests use. Driving a real handshake via ``starlette.testclient`` is
+avoided on purpose: it pulls in the deprecated httpx TestClient path.
+"""
+
+from types import SimpleNamespace
+
+from fastapi import WebSocketException
+from jwt import DecodeError
+import pytest
+
+from fastapi_identity_model import build_ws_authenticator, ws
+from py_identity_model import NetworkException, TokenValidationException
+
+
+pytestmark = pytest.mark.unit
+
+DISCOVERY_URL = "https://op/.well-known/openid-configuration"
+_ACCESS_CLAIMS = {"sub": "u1", "scope": "read"}
+
+
+class _FakeWebSocket:
+    """Minimal stand-in for starlette's WebSocket for the dependency under test."""
+
+    def __init__(self, *, headers=None, query_params=None):
+        self.headers = headers or {}
+        self.query_params = query_params or {}
+        self.state = SimpleNamespace()
+
+
+def _authenticator(monkeypatch, *, returns=None, raises=None, **kwargs):
+    async def fake_validate_token(**_):
+        if raises is not None:
+            raise raises
+        return dict(returns)
+
+    monkeypatch.setattr(ws, "validate_token", fake_validate_token)
+    return build_ws_authenticator(discovery_url=DISCOVERY_URL, audience="cid", **kwargs)
+
+
+async def test_valid_token_via_query_param(monkeypatch):
+    auth = _authenticator(monkeypatch, returns=_ACCESS_CLAIMS)
+    sock = _FakeWebSocket(query_params={"access_token": "good"})
+    claims = await auth(sock)
+    assert claims["sub"] == "u1"
+    # Validated identity is attached to websocket.state, mirroring request.state.
+    assert sock.state.claims["sub"] == "u1"
+    assert sock.state.token == "good"
+    assert sock.state.user is not None
+
+
+async def test_valid_token_via_authorization_header(monkeypatch):
+    auth = _authenticator(monkeypatch, returns=_ACCESS_CLAIMS)
+    sock = _FakeWebSocket(headers={"Authorization": "Bearer good"})
+    claims = await auth(sock)
+    assert claims["sub"] == "u1"
+
+
+async def test_missing_token_closes_policy_violation(monkeypatch):
+    auth = _authenticator(monkeypatch, returns=_ACCESS_CLAIMS)
+    with pytest.raises(WebSocketException) as exc:
+        await auth(_FakeWebSocket())
+    assert exc.value.code == 1008
+
+
+async def test_malformed_authorization_header_does_not_fall_through(monkeypatch):
+    # A present-but-malformed header must not fall through to the query param;
+    # validate_token must never be reached.
+    called = {"n": 0}
+
+    async def fake_validate_token(**_):
+        called["n"] += 1
+        return dict(_ACCESS_CLAIMS)
+
+    monkeypatch.setattr(ws, "validate_token", fake_validate_token)
+    auth = build_ws_authenticator(discovery_url=DISCOVERY_URL, audience="cid")
+    sock = _FakeWebSocket(
+        headers={"Authorization": "Token abc"}, query_params={"access_token": "good"}
+    )
+    with pytest.raises(WebSocketException) as exc:
+        await auth(sock)
+    assert exc.value.code == 1008
+    assert called["n"] == 0
+
+
+async def test_invalid_token_closes_generic_policy_violation(monkeypatch):
+    auth = _authenticator(monkeypatch, raises=TokenValidationException("bad signature"))
+    with pytest.raises(WebSocketException) as exc:
+        await auth(_FakeWebSocket(query_params={"access_token": "bad"}))
+    assert exc.value.code == 1008
+    # Generic reason — the close frame must not distinguish rejection causes.
+    assert exc.value.reason == "Invalid or unauthorized token"
+
+
+async def test_malformed_jwt_closes_generic_policy_violation(monkeypatch):
+    # A raw pyjwt InvalidTokenError (e.g. DecodeError during header parsing) is a
+    # client error, closed 1008 with the same generic reason as any rejection.
+    auth = _authenticator(monkeypatch, raises=DecodeError("not a jwt"))
+    with pytest.raises(WebSocketException) as exc:
+        await auth(_FakeWebSocket(query_params={"access_token": "xxx"}))
+    assert exc.value.code == 1008
+    assert exc.value.reason == "Invalid or unauthorized token"
+
+
+async def test_upstream_outage_closes_try_again_later(monkeypatch):
+    auth = _authenticator(monkeypatch, raises=NetworkException("provider down"))
+    with pytest.raises(WebSocketException) as exc:
+        await auth(_FakeWebSocket(query_params={"access_token": "good"}))
+    # 1013 Try Again Later, not a policy violation — a transient fault, not a
+    # bad token.
+    assert exc.value.code == 1013
+
+
+async def test_upstream_fetch_failure_prefix_maps_to_try_again_later(monkeypatch):
+    # A discovery/JWKS fetch failure surfaces as a TokenValidationException whose
+    # message carries a known prefix; it must map to 1013, not a 1008 rejection.
+    auth = _authenticator(
+        monkeypatch,
+        raises=TokenValidationException("Network error during discovery: boom"),
+    )
+    with pytest.raises(WebSocketException) as exc:
+        await auth(_FakeWebSocket(query_params={"access_token": "good"}))
+    assert exc.value.code == 1013
+
+
+async def test_unexpected_error_closes_internal_error(monkeypatch):
+    auth = _authenticator(monkeypatch, raises=RuntimeError("boom"))
+    with pytest.raises(WebSocketException) as exc:
+        await auth(_FakeWebSocket(query_params={"access_token": "good"}))
+    assert exc.value.code == 1011
+
+
+async def test_id_token_substitution_rejected(monkeypatch):
+    # An ID-token-only claim (nonce) present → wrong type, rejected even with the
+    # positive-marker check off.
+    auth = _authenticator(
+        monkeypatch, returns={"sub": "u1", "nonce": "n", "scope": "read"}
+    )
+    with pytest.raises(WebSocketException) as exc:
+        await auth(_FakeWebSocket(query_params={"access_token": "idtok"}))
+    assert exc.value.code == 1008
+    assert exc.value.reason == "Invalid or unauthorized token"
+
+
+async def test_require_access_token_marker_rejects_markerless_token(monkeypatch):
+    # Opt-in F-07 positive marker: a token with none of scope/scp is rejected.
+    auth = _authenticator(
+        monkeypatch, returns={"sub": "u1"}, require_access_token_marker=True
+    )
+    with pytest.raises(WebSocketException) as exc:
+        await auth(_FakeWebSocket(query_params={"access_token": "nomarker"}))
+    assert exc.value.code == 1008
+
+
+async def test_marker_token_passes_when_required(monkeypatch):
+    auth = _authenticator(
+        monkeypatch,
+        returns={"sub": "u1", "scope": "read"},
+        require_access_token_marker=True,
+    )
+    claims = await auth(_FakeWebSocket(query_params={"access_token": "ok"}))
+    assert claims["sub"] == "u1"
+
+
+async def test_custom_query_param(monkeypatch):
+    auth = _authenticator(monkeypatch, returns=_ACCESS_CLAIMS, query_param="tok")
+    claims = await auth(_FakeWebSocket(query_params={"tok": "good"}))
+    assert claims["sub"] == "u1"
+
+
+async def test_threads_config_into_validate_token(monkeypatch):
+    # The authenticator must thread audience, discovery URL, perform_disco AND
+    # the injected custom_claims_validator into TokenValidationConfig — a
+    # regression dropping any of these would otherwise pass silently.
+    captured = {}
+
+    async def capturing_validate_token(
+        *, token_validation_config, disco_doc_address, **_
+    ):
+        captured["cfg"] = token_validation_config
+        captured["disco"] = disco_doc_address
+        return dict(_ACCESS_CLAIMS)
+
+    monkeypatch.setattr(ws, "validate_token", capturing_validate_token)
+
+    def my_validator(_claims):
+        return None
+
+    auth = build_ws_authenticator(
+        discovery_url=DISCOVERY_URL,
+        audience="cid",
+        custom_claims_validator=my_validator,
+    )
+    await auth(_FakeWebSocket(query_params={"access_token": "good"}))
+
+    cfg = captured["cfg"]
+    assert cfg.audience == "cid"
+    assert cfg.perform_disco is True
+    assert cfg.claims_validator is my_validator
+    assert captured["disco"] == DISCOVERY_URL
+
+
+async def test_to_principal_failure_closes_internal_error(monkeypatch):
+    # A failure building the principal AFTER the token validated must fail closed
+    # with a mapped 1011, not escape as an unhandled exception (parity with the
+    # HTTP middleware's 500 guard).
+    def _raise(_claims):
+        raise RuntimeError("boom")
+
+    auth = _authenticator(monkeypatch, returns=_ACCESS_CLAIMS)
+    monkeypatch.setattr(ws, "to_principal", _raise)
+    with pytest.raises(WebSocketException) as exc:
+        await auth(_FakeWebSocket(query_params={"access_token": "good"}))
+    assert exc.value.code == 1011
+
+
+def test_empty_audience_raises():
+    with pytest.raises(ValueError, match="audience"):
+        build_ws_authenticator(discovery_url=DISCOVERY_URL, audience="")
+
+
+def test_require_marker_with_empty_claims_raises():
+    with pytest.raises(ValueError, match="access_token_marker_claims"):
+        build_ws_authenticator(
+            discovery_url=DISCOVERY_URL,
+            audience="cid",
+            require_access_token_marker=True,
+            access_token_marker_claims=(),
+        )