codexLB-up 1.25.0b10__py3-none-any.whl

app/core/middleware/api_firewall.py

@@ -0,0 +1,111 @@
+from __future__ import annotations
+
+from ipaddress import IPv4Network, IPv6Network
+from typing import cast
+
+from fastapi import FastAPI, Request
+from fastapi.responses import JSONResponse
+from starlette.datastructures import Headers
+from starlette.requests import HTTPConnection
+from starlette.types import ASGIApp, Receive, Scope, Send
+
+from app.core.config.settings import get_settings
+from app.core.errors import openai_error
+from app.core.middleware.firewall_cache import FirewallIPCache, get_firewall_ip_cache
+from app.core.request_locality import (
+    FORWARDED_CHAIN_HEADER_NAMES,
+    parse_trusted_proxy_networks,
+    resolve_connection_client_ip,
+)
+from app.core.socket_peer import raw_socket_peer_host
+from app.db.session import get_background_session
+from app.modules.firewall.repository import FirewallRepository
+from app.modules.firewall.service import FirewallRepositoryPort, FirewallService
+
+
+class ApiFirewallMiddleware:
+    """IP allowlist for ``/v1/*`` and ``/backend-api/codex/*`` HTTP requests.
+
+    Pure ASGI: unprotected paths pass through with a single prefix check, and
+    allow decisions are answered from the in-memory TTL cache; the database is
+    only consulted on a cache miss.
+    """
+
+    def __init__(
+        self,
+        app: ASGIApp,
+        *,
+        trust_proxy_headers: bool,
+        trusted_proxy_networks: tuple[IPv4Network | IPv6Network, ...],
+        firewall_cache: FirewallIPCache,
+    ) -> None:
+        self.app = app
+        self._trust_proxy_headers = trust_proxy_headers
+        self._trusted_proxy_networks = trusted_proxy_networks
+        self._firewall_cache = firewall_cache
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        if scope["type"] != "http" or not _is_protected_api_path(scope["path"]):
+            await self.app(scope, receive, send)
+            return
+
+        client_ip = resolve_connection_client_ip(
+            Headers(scope=scope),
+            raw_socket_peer_host(HTTPConnection(scope)),
+            trust_proxy_headers=self._trust_proxy_headers,
+            trusted_proxy_networks=self._trusted_proxy_networks,
+            allowed_proxy_header_names=FORWARDED_CHAIN_HEADER_NAMES,
+        )
+        firewall_cache = self._firewall_cache
+        cached_decision = await firewall_cache.is_allowed(client_ip) if client_ip is not None else None
+        if cached_decision is not None:
+            is_allowed = cached_decision
+        else:
+            version_before_read = firewall_cache.version
+            async with get_background_session() as session:
+                repository = cast(FirewallRepositoryPort, FirewallRepository(session))
+                service = FirewallService(repository)
+                is_allowed = await service.is_ip_allowed(client_ip)
+            if client_ip is not None:
+                await firewall_cache.set(client_ip, is_allowed, if_version=version_before_read)
+
+        if is_allowed:
+            await self.app(scope, receive, send)
+            return
+
+        response = JSONResponse(
+            status_code=403,
+            content=openai_error("ip_forbidden", "Access denied for client IP", error_type="access_error"),
+        )
+        await response(scope, receive, send)
+
+
+def add_api_firewall_middleware(app: FastAPI) -> None:
+    settings = get_settings()
+    app.add_middleware(
+        ApiFirewallMiddleware,
+        trust_proxy_headers=settings.firewall_trust_proxy_headers,
+        trusted_proxy_networks=parse_trusted_proxy_networks(settings.firewall_trusted_proxy_cidrs),
+        firewall_cache=get_firewall_ip_cache(),
+    )
+
+
+def _is_protected_api_path(path: str) -> bool:
+    if path == "/backend-api/codex" or path.startswith("/backend-api/codex/"):
+        return True
+    return path == "/v1" or path.startswith("/v1/")
+
+
+def _resolve_client_ip(
+    request: Request,
+    *,
+    trust_proxy_headers: bool,
+    trusted_proxy_networks: tuple[IPv4Network | IPv6Network, ...] = (),
+) -> str | None:
+    return resolve_connection_client_ip(
+        request.headers,
+        raw_socket_peer_host(request),
+        trust_proxy_headers=trust_proxy_headers,
+        trusted_proxy_networks=trusted_proxy_networks,
+        allowed_proxy_header_names=FORWARDED_CHAIN_HEADER_NAMES,
+    )

app/core/middleware/app_version.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+from fastapi import FastAPI
+from starlette.datastructures import MutableHeaders
+from starlette.types import ASGIApp, Message, Receive, Scope, Send
+
+from app import __version__
+
+
+class AppVersionMiddleware:
+    """Append ``X-App-Version`` to every 200-499 HTTP response.
+
+    Pure ASGI (no ``BaseHTTPMiddleware``) so streaming responses relay chunks
+    without an extra task and memory-stream hop. 5xx responses and WebSocket
+    scopes never carry the header, and a route-owned ``X-App-Version`` value is
+    preserved (see ``openspec/specs/api-response-metadata/spec.md``).
+    """
+
+    def __init__(self, app: ASGIApp) -> None:
+        self.app = app
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        if scope["type"] != "http":
+            await self.app(scope, receive, send)
+            return
+
+        async def send_with_app_version(message: Message) -> None:
+            if message["type"] == "http.response.start" and 200 <= message["status"] < 500:
+                headers = MutableHeaders(raw=message.setdefault("headers", []))
+                headers.setdefault("X-App-Version", __version__)
+            await send(message)
+
+        await self.app(scope, receive, send_with_app_version)
+
+
+def add_app_version_middleware(app: FastAPI) -> None:
+    app.add_middleware(AppVersionMiddleware)

app/core/middleware/dashboard_auth_proxy.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+from typing import Any, cast
+
+from fastapi import FastAPI
+from starlette.requests import HTTPConnection
+from starlette.types import ASGIApp, Receive, Scope, Send
+
+from app.core.auth.dashboard_mode import DashboardAuthMode
+from app.core.config.settings import get_settings
+from app.core.request_locality import is_trusted_proxy_source, parse_trusted_proxy_networks
+from app.core.socket_peer import raw_socket_peer_host
+
+
+class DashboardAuthProxyHeaderSanitizerMiddleware:
+    def __init__(self, app: ASGIApp) -> None:
+        self.app = app
+        settings = get_settings()
+        self._enabled = settings.dashboard_auth_mode == DashboardAuthMode.TRUSTED_HEADER
+        self._trust_proxy_headers = settings.firewall_trust_proxy_headers
+        self._trusted_proxy_networks = parse_trusted_proxy_networks(settings.firewall_trusted_proxy_cidrs)
+        self._trusted_header_name = settings.dashboard_auth_proxy_header.lower().encode("latin-1")
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        if not self._enabled or scope["type"] != "http":
+            await self.app(scope, receive, send)
+            return
+
+        client_host = raw_socket_peer_host(HTTPConnection(scope))
+        if (
+            self._trust_proxy_headers
+            and client_host
+            and is_trusted_proxy_source(client_host, self._trusted_proxy_networks)
+        ):
+            await self.app(scope, receive, send)
+            return
+
+        headers = cast(list[tuple[bytes, bytes]], scope.get("headers", []))
+        if not any(name.lower() == self._trusted_header_name for name, _ in headers):
+            await self.app(scope, receive, send)
+            return
+
+        scrubbed_scope = {**scope, "headers": _filter_headers(headers, self._trusted_header_name)}
+        await self.app(scrubbed_scope, receive, send)
+
+
+def add_dashboard_auth_proxy_middleware(app: FastAPI) -> None:
+    app.add_middleware(cast(Any, DashboardAuthProxyHeaderSanitizerMiddleware))
+
+
+def _filter_headers(headers: list[tuple[bytes, bytes]], target: bytes) -> list[tuple[bytes, bytes]]:
+    return [(name, value) for name, value in headers if name.lower() != target]
+
+
+__all__ = ["add_dashboard_auth_proxy_middleware", "DashboardAuthProxyHeaderSanitizerMiddleware"]

app/core/middleware/dashboard_csrf.py

@@ -0,0 +1,177 @@
+"""Reject cross-site browser requests that would mutate dashboard state.
+
+The dashboard authenticates with a ``SameSite=Lax`` session cookie or, on
+loopback without a password, with no credential at all. Neither protects a
+mutation that a foreign page triggers from the operator's browser, so this
+middleware inspects the browser-controlled ``Sec-Fetch-Site`` and ``Origin``
+headers before routing and answers ``403 cross_site_request_rejected`` when
+the request did not come from the dashboard's own origin.
+
+Only unsafe methods under ``/api/`` are inspected. Bearer-authenticated
+data-plane routes (``/api/fleet/``, ``/api/codex/``) and any request carrying
+an ``Authorization: Bearer`` header are exempt because a foreign page cannot
+attach that header without CORS consent. Requests without either header come
+from non-browser clients and pass through unchanged.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, cast
+from urllib.parse import urlsplit
+
+from fastapi import FastAPI
+from starlette._utils import get_route_path
+from starlette.responses import JSONResponse
+from starlette.types import ASGIApp, Receive, Scope, Send
+
+from app.core.errors import dashboard_error
+
+CROSS_SITE_REQUEST_REJECTED_CODE = "cross_site_request_rejected"
+CROSS_SITE_REQUEST_REJECTED_MESSAGE = "Cross-site dashboard requests are not allowed"
+
+_SAFE_METHODS = frozenset({"GET", "HEAD", "OPTIONS"})
+_PROTECTED_PATH_PREFIX = "/api/"
+_BEARER_AUTHENTICATED_PATH_PREFIXES = ("/api/fleet/", "/api/codex/")
+_ALLOWED_FETCH_SITES = frozenset({"same-origin", "none"})
+_DEFAULT_PORTS = {"http": 80, "https": 443}
+
+logger = logging.getLogger(__name__)
+
+
+def _header(headers: list[tuple[bytes, bytes]], name: bytes) -> str | None:
+    for key, value in headers:
+        if key.lower() == name:
+            return value.decode("latin-1")
+    return None
+
+
+def _has_bearer_authorization(headers: list[tuple[bytes, bytes]]) -> bool:
+    authorization = _header(headers, b"authorization")
+    if authorization is None:
+        return False
+    scheme, _, credentials = authorization.strip().partition(" ")
+    return scheme.lower() == "bearer" and credentials.strip() != ""
+
+
+def _origin_tuple(scheme: str, netloc: str) -> tuple[str, str, int] | None:
+    scheme = scheme.lower()
+    default_port = _DEFAULT_PORTS.get(scheme)
+    if default_port is None:
+        return None
+    try:
+        parsed = urlsplit(f"//{netloc}")
+        hostname = parsed.hostname
+        port = parsed.port
+    except ValueError:
+        return None
+    if not hostname:
+        return None
+    return scheme, hostname.lower(), port if port is not None else default_port
+
+
+def _parse_origin_header(value: str) -> tuple[str, str, int] | None:
+    try:
+        parsed = urlsplit(value.strip())
+    except ValueError:
+        return None
+    if not parsed.scheme or not parsed.netloc:
+        return None
+    return _origin_tuple(parsed.scheme, parsed.netloc)
+
+
+def _request_origin(scope: Scope, headers: list[tuple[bytes, bytes]]) -> tuple[str, str, int] | None:
+    host = _header(headers, b"host")
+    if host is None:
+        return None
+    return _origin_tuple(str(scope.get("scheme", "http")), host.strip())
+
+
+def _is_protected(scope: Scope, headers: list[tuple[bytes, bytes]]) -> bool:
+    if scope["type"] != "http":
+        return False
+    if str(scope.get("method", "GET")).upper() in _SAFE_METHODS:
+        return False
+    path = get_route_path(scope)
+    if not path.startswith(_PROTECTED_PATH_PREFIX) or path.startswith(_BEARER_AUTHENTICATED_PATH_PREFIXES):
+        return False
+    return not _has_bearer_authorization(headers)
+
+
+def _format_origin(origin: tuple[str, str, int] | None) -> str:
+    if origin is None:
+        return "-"
+    scheme, host, port = origin
+    host_text = f"[{host}]" if ":" in host else host
+    return f"{scheme}://{host_text}:{port}"
+
+
+def _rejection_reason(scope: Scope, headers: list[tuple[bytes, bytes]]) -> str | None:
+    """Return a log-safe reason when the request must be rejected, else ``None``.
+
+    The reason names only the ``Sec-Fetch-Site`` value or the presented ``Origin``
+    (scheme, host, port; path and query stripped) next to the expected origin
+    derived from the request scheme and ``Host`` header. No other header values
+    are included.
+    """
+
+    fetch_site = _header(headers, b"sec-fetch-site")
+    if fetch_site is not None:
+        site = fetch_site.strip().lower()
+        return None if site in _ALLOWED_FETCH_SITES else f"sec_fetch_site={site or '-'}"
+
+    origin = _header(headers, b"origin")
+    if origin is None:
+        return None
+    expected = _request_origin(scope, headers)
+    if origin.strip().lower() == "null":
+        return f"origin=null expected={_format_origin(expected)}"
+    presented = _parse_origin_header(origin)
+    if presented is None or expected is None or presented != expected:
+        return f"origin={_format_origin(presented)} expected={_format_origin(expected)}"
+    return None
+
+
+class DashboardCsrfMiddleware:
+    def __init__(self, app: ASGIApp) -> None:
+        self.app = app
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        if scope["type"] != "http":
+            await self.app(scope, receive, send)
+            return
+
+        headers = cast(list[tuple[bytes, bytes]], scope.get("headers", []))
+        if not _is_protected(scope, headers):
+            await self.app(scope, receive, send)
+            return
+
+        reason = _rejection_reason(scope, headers)
+        if reason is None:
+            await self.app(scope, receive, send)
+            return
+
+        logger.warning(
+            "dashboard_error_response method=%s path=%s status=403 code=%s %s",
+            scope.get("method"),
+            get_route_path(scope),
+            CROSS_SITE_REQUEST_REJECTED_CODE,
+            reason,
+        )
+        response = JSONResponse(
+            status_code=403,
+            content=dashboard_error(CROSS_SITE_REQUEST_REJECTED_CODE, CROSS_SITE_REQUEST_REJECTED_MESSAGE),
+        )
+        await response(scope, receive, send)
+
+
+def add_dashboard_csrf_middleware(app: FastAPI) -> None:
+    app.add_middleware(cast(Any, DashboardCsrfMiddleware))
+
+
+__all__ = [
+    "CROSS_SITE_REQUEST_REJECTED_CODE",
+    "CROSS_SITE_REQUEST_REJECTED_MESSAGE",
+    "DashboardCsrfMiddleware",
+    "add_dashboard_csrf_middleware",
+]

app/core/middleware/dashboard_gzip.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+from starlette.middleware.gzip import GZipMiddleware
+from starlette.types import ASGIApp, Receive, Scope, Send
+
+# Only dashboard-facing paths are compressed. Proxy paths (/backend-api,
+# /v1, websockets) stream SSE and must never pass through a compressing
+# wrapper; dashboard API responses are JSON and the built SPA assets are
+# text-heavy (the uncompressed JS bundle alone is ~1.7 MB).
+_COMPRESSED_PATH_PREFIXES = ("/api/", "/assets/")
+
+
+class DashboardGZipMiddleware:
+    """Apply gzip to dashboard API and static-asset responses only."""
+
+    def __init__(self, app: ASGIApp, minimum_size: int = 1024) -> None:
+        self._plain = app
+        self._gzip = GZipMiddleware(app, minimum_size=minimum_size)
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        if (
+            scope["type"] == "http"
+            and scope.get("path", "").startswith(_COMPRESSED_PATH_PREFIXES)
+            and not _has_range_header(scope)
+        ):
+            await self._gzip(scope, receive, send)
+            return
+        await self._plain(scope, receive, send)
+
+
+def _has_range_header(scope: Scope) -> bool:
+    """Ranged requests bypass gzip: FileResponse builds the 206 and its
+    Content-Range against the uncompressed file, so compressing the body
+    afterwards would describe offsets the encoded bytes no longer match.
+    Header-name casing is normalized because not every ASGI server
+    lowercases request header names."""
+    return any(name.lower() == b"range" for name, _ in scope.get("headers", ()))
+
+
+def add_dashboard_gzip_middleware(app) -> None:
+    app.add_middleware(DashboardGZipMiddleware)

app/core/middleware/dashboard_overrides.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+import logging
+import time
+
+from starlette.types import ASGIApp, Receive, Scope, Send
+
+from app.core.config.dashboard_overrides import bind_dashboard_overrides, reset_dashboard_overrides
+from app.core.config.settings_cache import get_settings_cache
+
+logger = logging.getLogger(__name__)
+
+_SNAPSHOT_FAILURE_LOG_INTERVAL_SECONDS = 60.0
+
+
+class DashboardOverridesMiddleware:
+    """Bind the dashboard-managed ``Settings`` overrides for the lifetime of one request or socket.
+
+    Reads the ``SettingsCache`` snapshot (TTL 5 s, cross-replica invalidated) once
+    per HTTP request or WebSocket connection and exposes the non-NULL dashboard
+    columns through ``with_dashboard_overrides`` to every consumer downstream,
+    including tasks the request spawns (they inherit the context). When the
+    snapshot cannot be refreshed, the last row the cache loaded is used; only
+    before the first successful load does the environment fallback apply.
+    """
+
+    def __init__(self, app: ASGIApp) -> None:
+        self.app = app
+        self._last_failure_logged_at = 0.0
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        if scope["type"] not in {"http", "websocket"}:
+            await self.app(scope, receive, send)
+            return
+        cache = get_settings_cache()
+        try:
+            row = await cache.get()
+        except Exception:  # noqa: BLE001 - never fail a request over an unreadable snapshot
+            row = cache.cached_row()
+            self._log_snapshot_failure(stale_row_available=row is not None)
+        if row is None:
+            await self.app(scope, receive, send)
+            return
+        token = bind_dashboard_overrides(row)
+        try:
+            await self.app(scope, receive, send)
+        finally:
+            reset_dashboard_overrides(token)
+
+    def _log_snapshot_failure(self, *, stale_row_available: bool) -> None:
+        now = time.monotonic()
+        if now - self._last_failure_logged_at < _SNAPSHOT_FAILURE_LOG_INTERVAL_SECONDS:
+            return
+        self._last_failure_logged_at = now
+        logger.warning(
+            "dashboard settings snapshot unavailable; %s",
+            "using the last loaded dashboard values" if stale_row_available else "using environment values",
+            exc_info=True,
+        )

app/core/middleware/firewall_cache.py

@@ -0,0 +1,91 @@
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass
+
+import anyio
+
+# Default TTL when the firewall cache is constructed before settings are
+# resolved. The application normally tunes this via
+# ``firewall_ip_cache_ttl_seconds`` (env ``CODEX_LB_FIREWALL_IP_CACHE_TTL_SECONDS``),
+# read lazily on first access in :func:`get_firewall_ip_cache`. The default is
+# intentionally well above the worst-case request-handling latency so the cache
+# provides real relief on hot paths under load.
+DEFAULT_FIREWALL_IP_CACHE_TTL_SECONDS = 30
+
+
+@dataclass(slots=True)
+class _CachedFirewallDecision:
+    allowed: bool
+    expires_at: float
+
+
+class FirewallIPCache:
+    def __init__(self, ttl_seconds: int = DEFAULT_FIREWALL_IP_CACHE_TTL_SECONDS) -> None:
+        if ttl_seconds <= 0:
+            raise ValueError("ttl_seconds must be positive")
+        self._ttl_seconds = ttl_seconds
+        self._cache: dict[str, _CachedFirewallDecision] = {}
+        self._lock = anyio.Lock()
+        self._version = 0
+
+    @property
+    def ttl_seconds(self) -> int:
+        return self._ttl_seconds
+
+    @property
+    def version(self) -> int:
+        return self._version
+
+    async def is_allowed(self, ip: str) -> bool | None:
+        entry = self._cache.get(ip)
+        if entry is None:
+            return None
+        if time.monotonic() >= entry.expires_at:
+            return None
+        return entry.allowed
+
+    async def set(self, ip: str, allowed: bool, *, if_version: int | None = None) -> None:
+        async with self._lock:
+            if if_version is not None and if_version != self._version:
+                return
+            self._cache[ip] = _CachedFirewallDecision(
+                allowed=allowed,
+                expires_at=time.monotonic() + self._ttl_seconds,
+            )
+
+    def invalidate_all(self) -> None:
+        self._cache.clear()
+        self._version += 1
+
+
+_firewall_ip_cache: FirewallIPCache | None = None
+
+
+def _resolve_configured_ttl() -> int:
+    """Read the configured TTL from settings, falling back to the default.
+
+    Settings access is wrapped because the cache may be constructed before the
+    settings module is fully initialised (e.g. during early module-import in
+    tests).
+    """
+    try:
+        from app.core.config.settings import get_settings
+
+        return int(get_settings().firewall_ip_cache_ttl_seconds)
+    except Exception:  # pragma: no cover — defensive only
+        return DEFAULT_FIREWALL_IP_CACHE_TTL_SECONDS
+
+
+def get_firewall_ip_cache() -> FirewallIPCache:
+    global _firewall_ip_cache
+    if _firewall_ip_cache is None:
+        _firewall_ip_cache = FirewallIPCache(ttl_seconds=_resolve_configured_ttl())
+    return _firewall_ip_cache
+
+
+def reset_firewall_ip_cache_for_testing() -> None:
+    """Drop the cached singleton so the next ``get_firewall_ip_cache()`` call
+    re-reads settings. Test-only helper."""
+    global _firewall_ip_cache
+    _firewall_ip_cache = None