10xgraph-api 0.7.0__py3-none-any.whl

tenxgraph_api/src/app/core/auth/jwt_auth.py

@@ -0,0 +1,122 @@
+from typing import Any
+
+from fastapi import Request, Response
+from fastapi.security import HTTPAuthorizationCredentials
+
+from tenxgraph_api.src.app.core import logger
+from tenxgraph_api.src.app.core.auth.base_auth import BaseAuth
+from tenxgraph_api.src.app.core.config.settings import Settings, get_settings
+from tenxgraph_api.src.app.core.exceptions import UserAccountError
+
+
+try:
+    import jwt
+except ImportError:  # pragma: no cover
+    jwt = None  # type: ignore[assignment]
+
+
+# RFC 7518 3.2: an HMAC key must be at least as long as the hash output (256 bits for HS256).
+MIN_HMAC_BYTES = 32
+
+
+def check_jwt_settings(settings: Settings) -> None:
+    """Refuse a guessable HMAC secret at startup (production), warn about it otherwise.
+
+    A short HS* secret can be brute-forced offline from any one token, after which anyone can
+    mint a token for any ``user_id``.
+    """
+    algorithm = (settings.JWT_ALGORITHM or "").upper()
+    secret = settings.JWT_SECRET_KEY or ""
+    if not algorithm.startswith("HS") or len(secret.encode()) >= MIN_HMAC_BYTES:
+        return
+    message = (
+        f"JWT_SECRET_KEY is shorter than {MIN_HMAC_BYTES} bytes, which is too weak for "
+        f"{algorithm}. Generate one with: "
+        "python -c 'import secrets; print(secrets.token_urlsafe(48))'"
+    )
+    if settings.MODE == "production":
+        raise ValueError(message)
+    logger.warning(message)
+
+
+def _unauthorized(message: str, error_code: str) -> UserAccountError:
+    return UserAccountError(message=message, error_code=error_code, status_code=401)
+
+
+class JwtAuth(BaseAuth):
+    def authenticate(
+        self,
+        request: Request,
+        response: Response,
+        credential: HTTPAuthorizationCredentials,
+    ) -> dict[str, Any] | None:
+        """No authentication is required, so return None."""
+        """
+        Get the current user based on the provided HTTP
+        Authorization credentials.
+
+        Args:
+            res (Response): The response object to set headers if needed.
+            credential (HTTPAuthorizationCredentials): The HTTP Authorization
+            credentials obtained from the request.
+
+        Returns:
+            UserSchema: A UserSchema object containing the decoded user information.
+
+        Raises:
+            HTTPException: If the credentials are missing.
+            UserAccountError: If there are token verification errors such as
+                RevokedIdTokenError,
+                UserDisabledError,
+                InvalidIdTokenError,
+                or any other unexpected exceptions.
+        """
+
+        if credential is None:
+            raise _unauthorized("Invalid token, please login again", "REVOKED_TOKEN")
+
+        settings = get_settings()
+        jwt_secret_key = settings.JWT_SECRET_KEY
+        jwt_algorithm = settings.JWT_ALGORITHM
+
+        token = credential.credentials
+
+        if jwt is None:
+            raise ImportError(
+                "PyJWT is required for JWT authentication. "
+                'Install with `pip install "10xgraph-api[jwt]"`'
+            )
+
+        if jwt_secret_key is None or jwt_algorithm is None:
+            raise UserAccountError(
+                message="JWT settings are not configured",
+                error_code="JWT_SETTINGS_NOT_CONFIGURED",
+                status_code=500,
+            )
+
+        required = ["exp"]
+        if settings.JWT_ISSUER:
+            required.append("iss")
+        if settings.JWT_AUDIENCE:
+            required.append("aud")
+        try:
+            decoded_token = jwt.decode(
+                token,
+                jwt_secret_key,
+                algorithms=[jwt_algorithm],
+                issuer=settings.JWT_ISSUER or None,
+                audience=settings.JWT_AUDIENCE or None,
+                options={"require": required},
+            )
+        except jwt.ExpiredSignatureError:
+            raise _unauthorized("Token has expired, please login again", "EXPIRED_TOKEN")
+        except jwt.InvalidTokenError as err:
+            logger.warning("JWT rejected: %s", type(err).__name__)
+            raise _unauthorized("Invalid token, please login again", "INVALID_TOKEN")
+
+        response.headers["WWW-Authenticate"] = 'Bearer realm="auth_required"'
+
+        # check if user_id exists in the token
+        if "user_id" not in decoded_token:
+            raise _unauthorized("Invalid token, user_id missing", "INVALID_TOKEN")
+        return decoded_token

tenxgraph_api/src/app/core/auth/ownership_resolver.py

@@ -0,0 +1,170 @@
+"""Scalable thread-ownership resolution with a two-tier cache.
+
+Thread ownership is *immutable* -- a thread's owner is set when the thread is created and
+never changes; only deletion removes it. That makes the owner safe to cache aggressively, so
+after the first lookup an authorization check costs nothing (an in-process hit) instead of a
+database round-trip per request.
+
+Cache tiers:
+
+- **L1**: a bounded in-process LRU (per worker) with a short TTL.
+- **L2** (optional): a shared Redis, so workers/instances do not each re-hit the database.
+
+Deleting a thread evicts it from this worker's L1 and from L2, but another worker's L1 cannot
+be reached. A deleted id can be created again by a different user, so a stale L1 entry would
+keep granting the old owner access on that worker. The L1 TTL bounds how long that lasts; the
+L2 TTL covers an eviction that failed to reach Redis.
+
+Only *positive* results (a known owner) are cached. A ``None`` result (the thread does not
+exist yet) is **never** cached: a nonexistent thread can become owned by the very next
+request, and a cached ``None`` would let a later caller be treated as the creator of a thread
+someone else just made (a time-of-check/time-of-use hole).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import time
+from collections import OrderedDict
+from collections.abc import Awaitable, Callable
+
+
+logger = logging.getLogger("tenxgraph_api.authorization")
+
+# Sentinel signalling the backing checkpointer cannot resolve ownership at all
+# (``aget_thread_owner`` raised ``NotImplementedError``). Propagated so the caller can
+# degrade gracefully instead of treating every thread as unowned.
+OwnerLookup = Callable[[str], Awaitable["str | int | None"]]
+
+DEFAULT_L1_TTL_SECONDS = 30.0
+DEFAULT_L2_TTL_SECONDS = 3600
+
+
+class ThreadOwnershipResolver:
+    """Resolve (and cache) the owning ``user_id`` for a ``thread_id``.
+
+    Args:
+        lookup: async ``(thread_id) -> user_id | None`` backing lookup (typically
+            ``checkpointer.aget_thread_owner``). May raise ``NotImplementedError`` if the
+            checkpointer cannot resolve ownership; that propagates uncached.
+        redis: optional async Redis-like client (``get``/``set``/``delete`` coroutines).
+            When absent the resolver is L1-only. Redis errors degrade to the DB lookup and
+            never fail a request.
+        max_size: L1 LRU capacity (entries).
+        redis_prefix: key namespace for L2 entries.
+        l1_ttl: seconds an L1 entry is trusted; bounds staleness after a delete elsewhere.
+        l2_ttl: seconds an L2 entry lives in Redis.
+    """
+
+    def __init__(
+        self,
+        lookup: OwnerLookup,
+        *,
+        redis: object | None = None,
+        max_size: int = 10_000,
+        redis_prefix: str = "af:authz:owner",
+        l1_ttl: float = DEFAULT_L1_TTL_SECONDS,
+        l2_ttl: int = DEFAULT_L2_TTL_SECONDS,
+    ) -> None:
+        self._lookup = lookup
+        self._redis = redis
+        self._max_size = max(1, max_size)
+        self._prefix = redis_prefix
+        self._l1_ttl = l1_ttl
+        self._l2_ttl = l2_ttl
+        # key -> (owner, monotonic expiry)
+        self._l1: OrderedDict[str, tuple[str, float]] = OrderedDict()
+        self._lock = asyncio.Lock()
+
+    # ------------------------------------------------------------------ public
+
+    async def owner_of(self, thread_id: str | int) -> str | None:
+        """Return the owning ``user_id`` for ``thread_id``, or None if it has no owner.
+
+        Raises:
+            NotImplementedError: if the backing checkpointer cannot resolve ownership.
+        """
+        key = str(thread_id)
+
+        cached = await self._l1_get(key)
+        if cached is not None:
+            return cached
+
+        from_redis = await self._redis_get(key)
+        if from_redis is not None:
+            await self._l1_put(key, from_redis)
+            return from_redis
+
+        owner = await self._lookup(key)  # may raise NotImplementedError -> propagate
+        if owner is None:
+            return None  # never cache negatives (TOCTOU on new threads)
+
+        owner_str = str(owner)
+        await self._l1_put(key, owner_str)
+        await self._redis_set(key, owner_str)
+        return owner_str
+
+    async def evict(self, thread_id: str | int) -> None:
+        """Drop any cached owner for ``thread_id`` (call when a thread is deleted)."""
+        key = str(thread_id)
+        async with self._lock:
+            self._l1.pop(key, None)
+        await self._redis_delete(key)
+
+    # ------------------------------------------------------------------ L1
+
+    async def _l1_get(self, key: str) -> str | None:
+        async with self._lock:
+            entry = self._l1.get(key)
+            if entry is None:
+                return None
+            owner, expires_at = entry
+            if time.monotonic() >= expires_at:
+                del self._l1[key]
+                return None
+            self._l1.move_to_end(key)  # mark most-recently-used
+            return owner
+
+    async def _l1_put(self, key: str, owner: str) -> None:
+        async with self._lock:
+            self._l1[key] = (owner, time.monotonic() + self._l1_ttl)
+            self._l1.move_to_end(key)
+            while len(self._l1) > self._max_size:
+                self._l1.popitem(last=False)  # evict least-recently-used
+
+    # ------------------------------------------------------------------ L2 (Redis)
+
+    def _redis_key(self, key: str) -> str:
+        return f"{self._prefix}:{key}"
+
+    async def _redis_get(self, key: str) -> str | None:
+        if self._redis is None:
+            return None
+        try:
+            value = await self._redis.get(self._redis_key(key))  # type: ignore[attr-defined]
+        except Exception as exc:  # degrade to DB; never fail the request
+            logger.debug("Ownership L2 get failed for %s: %s", key, exc)
+            return None
+        if value is None:
+            return None
+        return value.decode() if isinstance(value, bytes | bytearray) else str(value)
+
+    async def _redis_set(self, key: str, owner: str) -> None:
+        if self._redis is None:
+            return
+        try:
+            # evict() removes the entry on delete; the TTL covers an eviction that failed.
+            await self._redis.set(  # type: ignore[attr-defined]
+                self._redis_key(key), owner, ex=self._l2_ttl
+            )
+        except Exception as exc:
+            logger.debug("Ownership L2 set failed for %s: %s", key, exc)
+
+    async def _redis_delete(self, key: str) -> None:
+        if self._redis is None:
+            return
+        try:
+            await self._redis.delete(self._redis_key(key))  # type: ignore[attr-defined]
+        except Exception as exc:
+            logger.debug("Ownership L2 delete failed for %s: %s", key, exc)

tenxgraph_api/src/app/core/auth/permissions.py

@@ -0,0 +1,354 @@
+"""
+Unified authentication and authorization dependency for FastAPI endpoints.
+
+This module provides a reusable dependency that combines authentication and
+authorization checks, reducing code duplication across routers.
+"""
+
+import email.message
+from collections.abc import Callable
+from typing import Any, NoReturn
+
+from fastapi import HTTPException, Response, WebSocket, WebSocketException
+from fastapi.security import HTTPAuthorizationCredentials
+from injectq.integrations import InjectAPI
+from starlette.requests import HTTPConnection
+
+from tenxgraph_api.src.app.core import logger
+from tenxgraph_api.src.app.core.auth.auth_backend import BaseAuth
+from tenxgraph_api.src.app.core.auth.authorization import AuthorizationBackend
+from tenxgraph_api.src.app.core.auth.request_config import normalize_thread_id
+from tenxgraph_api.src.app.core.config.graph_config import GraphConfig
+from tenxgraph_api.src.app.core.exceptions.general_exception import GeneralException
+from tenxgraph_api.src.app.core.utils.log_sanitizer import sanitize_for_logging
+
+
+# Sec-WebSocket-Protocol sentinel carrying the bearer token for browser WebSocket clients.
+# The client offers two subprotocols: this sentinel followed by the raw JWT, e.g.
+#   new WebSocket(url, ["10xgraph-bearer", "<jwt>"])
+# The token rides in a request header, so -- unlike ``?token=`` -- it never lands in URLs,
+# access logs, or browser history. The server must echo the sentinel on accept() (see
+# ``ws_bearer_subprotocol``) or browsers fail the handshake.
+WS_BEARER_SUBPROTOCOL = "10xgraph-bearer"
+# Pre-rename sentinel, still sent by released clients; accepted until 2.0.
+LEGACY_WS_BEARER_SUBPROTOCOL = "agentflow-bearer"
+_BEARER_SUBPROTOCOLS = (WS_BEARER_SUBPROTOCOL, LEGACY_WS_BEARER_SUBPROTOCOL)
+
+# A bearer-carrying Sec-WebSocket-Protocol offer is exactly [sentinel, token].
+_BEARER_SUBPROTOCOL_PARTS = 2
+
+
+def _subprotocols(connection: HTTPConnection) -> list[str]:
+    header = connection.headers.get("sec-websocket-protocol")
+    if not header:
+        return []
+    return [p.strip() for p in header.split(",") if p.strip()]
+
+
+def ws_bearer_subprotocol(connection: HTTPConnection) -> str | None:
+    """Return the subprotocol to echo on ``accept()`` when the client used it for the token.
+
+    Browsers require the server to confirm one of the offered subprotocols; when the bearer
+    sentinel was offered, accept with it. Returns ``None`` otherwise (plain ``accept()``).
+    """
+    parts = _subprotocols(connection)
+    if parts and parts[0] in _BEARER_SUBPROTOCOLS:
+        return parts[0]
+    return None
+
+
+def _extract_credential(
+    connection: HTTPConnection,
+) -> HTTPAuthorizationCredentials | None:
+    """Extract bearer credentials from a request or WebSocket connection.
+
+    Mirrors ``HTTPBearer(auto_error=False)`` but works for both HTTP and WebSocket routes
+    (FastAPI cannot inject ``HTTPBearer`` on a WebSocket route). Token sources, most secure
+    first:
+
+    1. ``Authorization: Bearer <token>`` header -- for non-browser clients.
+    2. ``Sec-WebSocket-Protocol: 10xgraph-bearer, <token>`` (legacy: ``agentflow-bearer``) --
+       browser-settable and kept out of URLs/logs; the preferred browser mechanism.
+    3. ``?token=<token>`` query parameter -- last-resort fallback; the token is exposed in
+       URLs/access logs/history, so prefer (2) for browser clients.
+    """
+    authorization = connection.headers.get("Authorization")
+    if authorization:
+        scheme, _, token = authorization.partition(" ")
+        if scheme.lower() == "bearer" and token:
+            return HTTPAuthorizationCredentials(scheme=scheme, credentials=token)
+
+    # [sentinel, token] -- the two subprotocols a browser client offers to carry the bearer.
+    parts = _subprotocols(connection)
+    if len(parts) >= _BEARER_SUBPROTOCOL_PARTS and parts[0] in _BEARER_SUBPROTOCOLS and parts[1]:
+        return HTTPAuthorizationCredentials(scheme="Bearer", credentials=parts[1])
+
+    ws_token = connection.query_params.get("token")
+    if ws_token:
+        is_ws = False
+        if hasattr(connection, "scope") and isinstance(connection.scope, dict):
+            is_ws = connection.scope.get("type") == "websocket"
+        if not is_ws:
+            from fastapi import WebSocket
+
+            is_ws = isinstance(connection, WebSocket)
+        if is_ws:
+            return HTTPAuthorizationCredentials(scheme="Bearer", credentials=ws_token)
+
+    return None
+
+
+# RFC 6455 close code 1008 "Policy Violation" -- the right signal for an auth/authz
+# rejection at the WebSocket handshake.
+WS_POLICY_VIOLATION = 1008
+
+
+def _is_json_content_type(content_type: str | None) -> bool:
+    """Whether FastAPI parses a body with this content type as JSON.
+
+    Mirrors ``fastapi.routing``: a missing content type, ``application/json`` and any
+    ``application/*+json`` are all parsed as JSON. Reading fewer types here would let a
+    request skip the thread check while the route still receives its body.
+    """
+    if not content_type:
+        return True
+    message = email.message.Message()
+    message["content-type"] = content_type
+    if message.get_content_maintype() != "application":
+        return False
+    subtype = message.get_content_subtype()
+    return subtype == "json" or subtype.endswith("+json")
+
+
+def _reject(connection: HTTPConnection, status_code: int, detail: str) -> NoReturn:
+    """Reject a connection with the error type appropriate to its protocol.
+
+    FastAPI translates an ``HTTPException`` into a response only on HTTP routes; on a
+    WebSocket route it propagates unhandled and tears the socket down abruptly (close
+    1006) with a server-side error log. Raise ``WebSocketException`` (close 1008) there
+    instead so the client sees a clean policy-violation rejection.
+    """
+    if isinstance(connection, WebSocket):
+        raise WebSocketException(code=WS_POLICY_VIOLATION, reason=detail)
+    raise HTTPException(status_code=status_code, detail=detail)
+
+
+class RequirePermission:
+    """
+    FastAPI dependency that combines authentication and authorization.
+
+    This class-based dependency verifies user authentication and checks
+    authorization in a single step, reducing boilerplate code in endpoints.
+
+    Usage:
+        @router.post("/v1/resource")
+        async def endpoint(
+            user: dict = Depends(RequirePermission("resource", "action"))
+        ):
+            # User is authenticated and authorized
+            pass
+
+    Args:
+        resource: Resource type being accessed (e.g., "graph", "checkpointer", "store")
+        action: Action being performed (e.g., "invoke", "read", "write", "delete")
+        extract_resource_id: Optional function to extract resource_id from request
+    """
+
+    def __init__(
+        self,
+        resource: str,
+        action: str,
+        extract_resource_id: Callable[[HTTPConnection], str | None] | None = None,
+    ):
+        """
+        Initialize the permission requirement.
+
+        Args:
+            resource: Resource type (graph, checkpointer, store)
+            action: Action type (invoke, stream, read, write, delete, etc.)
+            extract_resource_id: Optional callable that extracts resource_id from request
+        """
+        self.resource = resource
+        self.action = action
+        self.extract_resource_id_fn = extract_resource_id
+
+    async def __call__(  # noqa: PLR0912
+        self,
+        connection: HTTPConnection,
+        response: Response,
+        config: GraphConfig = InjectAPI(GraphConfig),
+        auth_backend: BaseAuth = InjectAPI(BaseAuth),
+        authz: AuthorizationBackend = InjectAPI(AuthorizationBackend),
+    ) -> dict[str, Any]:
+        """
+        Verify authentication and authorization.
+
+        ``connection`` is typed as ``HTTPConnection`` (the common base of ``Request``
+        and ``WebSocket``) so this dependency resolves on both HTTP and WebSocket
+        routes; FastAPI cannot inject a ``Request`` on a WebSocket route.
+
+        Returns:
+            dict: User information if authenticated and authorized
+
+        Raises:
+            HTTPException: 401/403 on HTTP routes when auth or authz fails.
+            WebSocketException: close 1008 on WebSocket routes for the same failures
+                (FastAPI does not translate an HTTPException on a WS handshake).
+        """
+        # Extract bearer credentials from the Authorization header, with a
+        # ``?token=`` query fallback for browser WebSocket clients (see
+        # _extract_credential). Works for both HTTP and WebSocket connections.
+        credential = _extract_credential(connection)
+
+        # Step 1: Check if auth is configured
+        backend = config.auth_config()
+
+        # If auth is not configured, skip authentication and authorization entirely
+        if not backend:
+            logger.debug(
+                f"Auth not configured, skipping auth/authz for {self.resource}:{self.action}"
+            )
+            return {}
+
+        # Step 2: Authentication (reusing verify_current_user logic)
+        user = {}
+        if not auth_backend:
+            logger.error("Auth backend is not configured")
+            user = {}
+        else:
+            try:
+                user_result = auth_backend.authenticate(
+                    connection,
+                    response,
+                    credential,
+                )
+            except HTTPException as exc:
+                # JWT/custom backends signal auth failure with HTTPException; convert it
+                # to a clean WebSocket close on WS routes (see _reject).
+                _reject(connection, exc.status_code, str(exc.detail))
+            except GeneralException as exc:
+                # JwtAuth raises UserAccountError (401). HTTP routes render it through its
+                # exception handler; a WebSocket has no handler, so close it cleanly.
+                if isinstance(connection, WebSocket):
+                    _reject(connection, exc.status_code, exc.message)
+                raise
+            if user_result and "user_id" not in user_result:
+                logger.error("Authentication failed: 'user_id' not found in user info")
+            user = user_result or {}
+
+        # Step 3: Extract resource_id if available
+        resource_id = None
+        if self.extract_resource_id_fn:
+            resource_id = self.extract_resource_id_fn(connection)
+        else:
+            resource_id = self._extract_resource_id_from_path(connection)
+            if resource_id is None:
+                resource_id = await self._extract_resource_id_from_body(connection)
+
+        # Step 4: Scope check -- does this identity carry the permission for this
+        # endpoint at all? The required scope is "<resource>:<action>". Scopes come from
+        # the authenticated identity (user["scopes"], populated by the auth backend / JWT
+        # claims). If the identity declares no scopes, we stay permissive (backward
+        # compatible) -- once scopes are issued, they are enforced.
+        required_scope = f"{self.resource}:{self.action}"
+        scopes_fn = getattr(authz, "scopes_for", None)
+        granted_scopes = scopes_fn(user) if callable(scopes_fn) else None
+        if granted_scopes is None and isinstance(user, dict):
+            granted_scopes = user.get("scopes")  # fallback for backends without scopes_for
+        if granted_scopes is not None and required_scope not in granted_scopes:
+            logger.warning(f"Missing scope '{required_scope}' for user {user.get('user_id')}")
+            _reject(connection, 403, f"Missing required scope: {required_scope}")
+
+        # Step 5: Object-level authorization (ownership etc.)
+        if not await authz.authorize(
+            user,
+            self.resource,
+            self.action,
+            resource_id=resource_id,
+        ):
+            logger.warning(
+                f"Authorization failed for user {user.get('user_id')} "
+                f"on {self.resource}:{self.action}"
+            )
+            _reject(
+                connection,
+                403,
+                f"Not authorized to {self.action} {self.resource}",
+            )
+
+        # Step 6: Stamp the trusted authz block into the user object. Every service copies
+        # this user into config["user"], so the isolation policy + scopes reach every
+        # downstream call (checkpointer, store, graph execution). Overwrites anything the
+        # client sent -- not hijackable.
+        if isinstance(user, dict) and user.get("user_id"):
+            from tenxgraph.core.authz import build_authz
+
+            scope_fn = getattr(authz, "isolation_scope", None)
+            iso_scope = scope_fn() if callable(scope_fn) else "none"
+            user["authz"] = build_authz(
+                user["user_id"],
+                scope=iso_scope,
+                scopes=granted_scopes if granted_scopes is not None else [],
+            )
+
+        # Log successful auth/authz (with sanitized user info)
+        logger.debug(
+            f"Auth/Authz success for {self.resource}:{self.action}, "
+            f"user: {sanitize_for_logging(user)}"
+        )
+
+        return user
+
+    def _extract_resource_id_from_path(self, connection: HTTPConnection) -> str | None:
+        """
+        Extract resource ID from request path parameters.
+
+        Looks for common patterns like thread_id, memory_id in path params.
+
+        Args:
+            connection: FastAPI request or WebSocket connection
+
+        Returns:
+            Resource ID as string, or None if not found
+        """
+        # Check path parameters
+        path_params = connection.path_params
+
+        # Common resource ID patterns
+        for param_name in ["thread_id", "memory_id", "namespace"]:
+            if param_name in path_params:
+                return str(path_params[param_name])
+
+        return None
+
+    async def _extract_resource_id_from_body(self, connection: HTTPConnection) -> str | None:
+        """Extract the thread ID a request body targets.
+
+        The body is read exactly when FastAPI would parse it as JSON, and the ID is normalised
+        the same way the services normalise it, so the thread checked here is the thread that
+        runs. Routes read either the root ``thread_id`` (stop, fix) or ``config.thread_id``
+        (invoke, stream); a body that names two different threads is rejected rather than
+        letting the check and the service pick different ones.
+        """
+        from starlette.requests import Request
+
+        if not isinstance(connection, Request):
+            return None
+        if not _is_json_content_type(connection.headers.get("content-type")):
+            return None
+
+        try:
+            body = await connection.json()
+        except Exception as exc:
+            # FastAPI rejects a malformed body itself before the route runs.
+            logger.debug("Failed to parse request body for thread_id: %s", exc)
+            return None
+        if not isinstance(body, dict):
+            return None
+
+        root_id = normalize_thread_id(body.get("thread_id"))
+        cfg = body.get("config")
+        config_id = normalize_thread_id(cfg.get("thread_id")) if isinstance(cfg, dict) else None
+        if root_id and config_id and root_id != config_id:
+            _reject(connection, 400, "thread_id and config.thread_id must match")
+        return root_id or config_id