Skip to content

Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.

Studio: trust forwarded headers only behind an opted-in proxy or the managed tunnel (#14753)

Daniel Hanf04007332cd8
diff --git a/studio/backend/lan_access.py b/studio/backend/lan_access.py
index fe72ffea461..b598e144c8a 100644
--- a/studio/backend/lan_access.py
+++ b/studio/backend/lan_access.py
@@ -247,6 +247,7 @@ def _bind_listener(address: str, port: int) -> socket.socket:
def _listener_config(app, host: str, port: int):
+ from utils.forwarded_headers import uvicorn_forwarded_kwargs
from utils.uvicorn_h11_shutdown import uvicorn_http_protocol
# a TLS launch must not reopen plain HTTP on the network
@@ -267,6 +268,7 @@ def _listener_config(app, host: str, port: int):
access_log = False,
server_header = False,
http = uvicorn_http_protocol(),
+ **uvicorn_forwarded_kwargs(is_colab = False),
)
diff --git a/studio/backend/run.py b/studio/backend/run.py
index a4289e6e936..6c31d91e3ee 100644
--- a/studio/backend/run.py
+++ b/studio/backend/run.py
@@ -2856,16 +2856,16 @@ def run_server(
server_header = False,
http = uvicorn_http_protocol(),
)
- # Colab only: trust X-Forwarded-* from Colab's reverse proxy so the app sees the real https origin.
- # forwarded_allow_ips="*" is safe in Colab's single-user sandbox but too lax for local/standalone.
- if _IS_COLAB:
- config_kwargs["proxy_headers"] = True
- config_kwargs["forwarded_allow_ips"] = "*"
+ # Proxy headers only where trusted, else any loopback peer picks request.client: utils/forwarded_headers.py
+ from utils.forwarded_headers import uvicorn_forwarded_kwargs, wrap_direct_server
+
+ config_kwargs.update(uvicorn_forwarded_kwargs(is_colab = _IS_COLAB))
+ served_app = app if config_kwargs["proxy_headers"] else wrap_direct_server(app, app.state)
if tls is not None:
from utils.studio_tls import StudioTLSConfig
- config = StudioTLSConfig(app, tls = tls, **config_kwargs)
+ config = StudioTLSConfig(served_app, tls = tls, **config_kwargs)
else:
- config = uvicorn.Config(app, **config_kwargs)
+ config = uvicorn.Config(served_app, **config_kwargs)
app.state.studio_tls = tls
app.state.loopback_http_port = None
_server = _ReadyServer(config)
diff --git a/studio/backend/tests/test_forwarded_header_trust.py b/studio/backend/tests/test_forwarded_header_trust.py
new file mode 100644
index 00000000000..1cf3457c338
--- /dev/null
+++ b/studio/backend/tests/test_forwarded_header_trust.py
@@ -0,0 +1,275 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Forwarded headers rewrite the caller only where they are trusted.
+
+uvicorn's defaults (proxy_headers=True, forwarded_allow_ips="127.0.0.1") let any loopback peer set
+request.client from X-Forwarded-For. Behind a same-host proxy that relays the caller's header unchanged,
+every per-IP limiter would key on text the caller chose. These tests drive uvicorn's own app pipeline,
+built with the arguments run.py passes, so they exercise the rewriting uvicorn would really apply."""
+
+import asyncio
+import inspect
+import types
+from pathlib import Path
+
+import httpx
+import pytest
+import uvicorn
+from fastapi import HTTPException
+from starlette.applications import Starlette
+from starlette.requests import Request
+from starlette.responses import JSONResponse
+from starlette.routing import Route
+
+from routes import auth as auth_routes
+from utils import keyless_api_access as kl
+from utils.client_ip import client_ip
+from utils.forwarded_headers import uvicorn_forwarded_kwargs, wrap_direct_server
+from utils.host_policy import is_loopback_host
+
+_TUNNEL_URL = "https://quiet-river.trycloudflare.com"
+_TUNNEL_HOST = "quiet-river.trycloudflare.com"
+
+
[email protected](autouse = True)
+def _clean(monkeypatch):
+ monkeypatch.delenv("UNSLOTH_STUDIO_TRUST_FORWARDED", raising = False)
+ monkeypatch.delenv("FORWARDED_ALLOW_IPS", raising = False)
+
+ def clear():
+ for table in (auth_routes._LOGIN_BUCKETS, auth_routes._LOGIN_IP_BUCKETS):
+ table.clear()
+ for shard in auth_routes._LOGIN_IP_OVERFLOW:
+ shard.clear()
+
+ clear()
+ yield
+ clear()
+
+
+async def _login(request):
+ from models.auth import AuthLoginRequest
+ try:
+ await auth_routes.login(
+ AuthLoginRequest(username = "nobody", password = "wrong-password"), request
+ )
+ except HTTPException as exc:
+ status = exc.status_code
+ else:
+ status = 200
+ return JSONResponse(
+ {
+ "status": status,
+ "client": request.client.host,
+ "scheme": request.url.scheme,
+ "bucket": list(auth_routes._bucket_key(request, "nobody")),
+ "client_ip": client_ip(request),
+ }
+ )
+
+
+def _served(*, is_colab = False, cloudflare_url = None):
+ """uvicorn's loaded app, built the way run.py builds it."""
+ inner = Starlette(routes = [Route("/login", _login, methods = ["POST"])])
+ inner.state.cloudflare_url = cloudflare_url
+ kwargs = uvicorn_forwarded_kwargs(is_colab = is_colab)
+ served = inner if kwargs["proxy_headers"] else wrap_direct_server(inner, inner.state)
+ config = uvicorn.Config(served, log_level = "warning", **kwargs)
+ config.load()
+ return config.loaded_app
+
+
+def _post_all(
+ app,
+ header_sets,
+ peer = "127.0.0.1",
+ host = "127.0.0.1:8888",
+):
+ async def run():
+ transport = httpx.ASGITransport(app = app, client = (peer, 40000))
+ async with httpx.AsyncClient(transport = transport, base_url = f"http://{host}") as c:
+ return [(await c.post("/login", headers = h)).json() for h in header_sets]
+
+ return asyncio.run(run())
+
+
+def _no_user(monkeypatch):
+ monkeypatch.setattr(auth_routes.policy, "installation_is_multi_user", lambda: False)
+ monkeypatch.setattr(auth_routes.storage, "get_user_and_secret", lambda username: None)
+ monkeypatch.setattr(auth_routes.hashing, "equalize_login_work", lambda password: None)
+
+
+def test_spoofed_forwarded_for_from_a_loopback_peer_does_not_pick_the_login_bucket(_no_user):
+ """A same-host proxy relaying the caller's X-Forwarded-For: each guess names a fresh address."""
+ attempts = auth_routes._LOGIN_MAX_FAILS + 3
+ seen = _post_all(
+ _served(),
+ [
+ {"x-forwarded-for": f"203.0.113.{i}", "x-forwarded-proto": "https"}
+ for i in range(attempts)
+ ],
+ )
+ assert {r["client"] for r in seen} == {"127.0.0.1"}
+ assert {tuple(r["bucket"]) for r in seen} == {("127.0.0.1", "nobody")}
+ assert {r["scheme"] for r in seen} == {"http"}
+ statuses = [r["status"] for r in seen]
+ assert statuses[: auth_routes._LOGIN_MAX_FAILS] == [401] * auth_routes._LOGIN_MAX_FAILS
+ assert statuses[-1] == 429
+
+
+def test_the_operator_opt_in_still_honours_forwarded_headers(_no_user, monkeypatch):
+ monkeypatch.setenv("UNSLOTH_STUDIO_TRUST_FORWARDED", "1")
+ assert uvicorn_forwarded_kwargs(is_colab = False) == {"proxy_headers": True}
+ seen = _post_all(
+ _served(),
+ [{"x-forwarded-for": "198.51.100.7", "x-forwarded-proto": "https"}],
+ )
+ assert seen[0]["client"] == "198.51.100.7"
+ assert seen[0]["bucket"] == ["198.51.100.7", "nobody"]
+ assert seen[0]["scheme"] == "https"
+
+
+def test_colab_keeps_its_proxy_header_trust():
+ assert uvicorn_forwarded_kwargs(is_colab = True) == {
+ "proxy_headers": True,
+ "forwarded_allow_ips": "*",
+ }
+
+
+def test_run_server_and_the_lan_listener_use_the_shared_arguments():
+ backend = Path(__file__).resolve().parents[1]
+ run_src = (backend / "run.py").read_text(encoding = "utf-8")
+ assert "uvicorn_forwarded_kwargs(is_colab = _IS_COLAB)" in run_src
+ assert "wrap_direct_server(app, app.state)" in run_src
+ import lan_access
+
+ assert "uvicorn_forwarded_kwargs(is_colab = False)" in inspect.getsource(
+ lan_access._listener_config
+ )
+ config = lan_access._listener_config(Starlette(), "192.168.1.5", 8888)
+ assert config.proxy_headers is False
+
+
+def test_the_managed_tunnel_keeps_its_visitor_address_and_https_scheme(_no_user):
+ headers = {
+ "host": _TUNNEL_HOST,
+ "cf-connecting-ip": "198.51.100.7",
+ "x-forwarded-for": "198.51.100.7",
+ "x-forwarded-proto": "https",
+ }
+ seen = _post_all(_served(cloudflare_url = _TUNNEL_URL), [headers], host = _TUNNEL_HOST)
+ assert seen[0]["client"] == "198.51.100.7"
+ assert seen[0]["scheme"] == "https"
+ assert seen[0]["client_ip"] == "198.51.100.7"
+
+
+ "cloudflare_url, host, peer",
+ [
+ (None, _TUNNEL_HOST, "127.0.0.1"), # no managed tunnel
+ (_TUNNEL_URL, "other.trycloudflare.com", "127.0.0.1"), # Host names another site
+ (_TUNNEL_URL, _TUNNEL_HOST, "192.168.1.50"), # not the local cloudflared
+ ],
+)
+def test_cf_connecting_ip_is_ignored_outside_the_managed_tunnel(
+ _no_user, cloudflare_url, host, peer
+):
+ headers = {"host": host, "cf-connecting-ip": "198.51.100.7", "x-forwarded-proto": "https"}
+ seen = _post_all(_served(cloudflare_url = cloudflare_url), [headers], peer = peer, host = host)
+ assert seen[0]["client"] == peer
+ assert seen[0]["scheme"] == "http"
+ assert seen[0]["client_ip"] != "198.51.100.7"
+
+
+def _request(
+ peer,
+ headers = (),
+ *,
+ cloudflare_url = None,
+ host = "127.0.0.1:8888",
+ server = None,
+):
+ raw = [(b"host", host.encode())] + [(k.encode(), v.encode()) for k, v in headers]
+ state = types.SimpleNamespace(
+ bind_host = "127.0.0.1", secure = False, cloudflare_url = cloudflare_url
+ )
+ return Request(
+ {
+ "type": "http",
+ "method": "GET",
+ "path": "/v1/models",
+ "root_path": "",
+ "headers": raw,
+ "client": (peer, 50000),
+ "server": server or ("127.0.0.1", 8888),
+ "scheme": "http",
+ "query_string": b"",
+ "app": types.SimpleNamespace(state = state),
+ }
+ )
+
+
+def test_client_ip_ignores_cf_connecting_ip_without_the_managed_tunnel():
+ relayed = client_ip(_request("127.0.0.1", [("cf-connecting-ip", "198.51.100.7")]))
+ assert relayed != "198.51.100.7"
+ # Still not a local caller for the reachability checks that read client_ip().
+ assert not is_loopback_host(relayed)
+ assert client_ip(_request("127.0.0.1")) == "127.0.0.1"
+
+
+def test_client_ip_honours_cf_connecting_ip_through_the_managed_tunnel():
+ request = _request(
+ "127.0.0.1",
+ [("cf-connecting-ip", "198.51.100.7")],
+ cloudflare_url = _TUNNEL_URL,
+ host = _TUNNEL_HOST,
+ )
+ assert client_ip(request) == "198.51.100.7"
+ forged_host = _request(
+ "127.0.0.1",
+ [("cf-connecting-ip", "198.51.100.7")],
+ cloudflare_url = _TUNNEL_URL,
+ host = "127.0.0.1:8888",
+ )
+ assert client_ip(forged_host) != "198.51.100.7"
+
+
+_RELAY_HEADERS = [
+ ("x-forwarded-for", "203.0.113.9"),
+ ("x-real-ip", "203.0.113.9"),
+ ("forwarded", "for=203.0.113.9"),
+ ("cf-connecting-ip", "203.0.113.9"),
+ ("x-forwarded-host", "studio.example.com"),
+ ("via", "1.1 proxy"),
+ ("x-forwarded-proto", "https"),
+]
+
+
+def _lan_request(headers = ()):
+ return _request(
+ "192.168.1.90",
+ headers,
+ host = "192.168.1.24:8888",
+ server = ("192.168.1.24", 8888),
+ )
+
+
+def _lan_listener(monkeypatch):
+ import lan_access
+ monkeypatch.setattr(
+ lan_access,
+ "lan_listener_status",
+ lambda: {"running": True, "port": 8888, "addresses": ["192.168.1.24"]},
+ )
+
+
+def test_lan_keyless_inference_still_serves_a_direct_lan_client(_lan_listener):
+ assert kl.keyless_transport_allowed(_lan_request(), "inference") is True
+
+
[email protected]("header", _RELAY_HEADERS)
+def test_lan_keyless_inference_refuses_a_relayed_request(_lan_listener, header):
+ assert kl.keyless_transport_allowed(_lan_request([header]), "inference") is False
diff --git a/studio/backend/tests/test_preview_followups.py b/studio/backend/tests/test_preview_followups.py
index 8aed0d94de0..cbd45f6f9aa 100644
--- a/studio/backend/tests/test_preview_followups.py
+++ b/studio/backend/tests/test_preview_followups.py
@@ -83,9 +83,19 @@ def test_client_ip_uses_rightmost_forwarded_when_trusted(monkeypatch):
assert client_ip(req) == "198.51.100.7"
-def test_client_ip_uses_cf_connecting_ip_on_loopback(monkeypatch):
+def test_client_ip_uses_cf_connecting_ip_only_through_the_managed_tunnel(monkeypatch):
monkeypatch.delenv("UNSLOTH_STUDIO_TRUST_FORWARDED", raising = False)
req = _Req("127.0.0.1", {"cf-connecting-ip": "198.51.100.7"})
+ assert client_ip(req) == "relayed:127.0.0.1"
+ req.scope = {
+ "headers": [
+ (b"host", b"live.trycloudflare.com"),
+ (b"cf-connecting-ip", b"198.51.100.7"),
+ ]
+ }
+ req.app = _types.SimpleNamespace(
+ state = _types.SimpleNamespace(cloudflare_url = "https://live.trycloudflare.com")
+ )
assert client_ip(req) == "198.51.100.7"
diff --git a/studio/backend/utils/client_ip.py b/studio/backend/utils/client_ip.py
index fce297cb705..a91af58e083 100644
--- a/studio/backend/utils/client_ip.py
+++ b/studio/backend/utils/client_ip.py
@@ -9,12 +9,11 @@ Trust model, in order:
one the trusted proxy appended. The leftmost entry is client-controlled and
spoofable, so this assumes a proxy that appends (or overwrites) the header;
only enable the env var behind such a proxy.
- 2. If the socket peer is loopback, honor ``CF-Connecting-IP``. Unsloth's managed
- Cloudflare tunnel terminates at 127.0.0.1, so every tunneled visitor would
- otherwise collapse onto the same socket peer (the local cloudflared process)
- and share one rate-limit bucket. ``CF-Connecting-IP`` is set by Cloudflare's
- edge and can't be forged by a tunneled client.
- 3. Otherwise the socket peer, so a direct LAN caller can't spoof a header to
+ 2. A loopback peer relaying Unsloth's own Cloudflare tunnel (``app.state.cloudflare_url``,
+ Host naming it): ``CF-Connecting-IP``, set by Cloudflare's edge, so tunnel visitors
+ don't share the local cloudflared bucket. Without that tunnel the header is forgeable.
+ 3. Any other loopback relay: ``relayed:<peer>``, one bucket per relay, never a local caller.
+ 4. Otherwise the socket peer, so a direct LAN caller can't spoof a header to
dodge a per-IP limit.
"""
@@ -22,6 +21,7 @@ from __future__ import annotations
import ipaddress
import os
+from urllib.parse import urlparse
_TRUST_FORWARDED_ENV = "UNSLOTH_STUDIO_TRUST_FORWARDED"
@@ -30,6 +30,10 @@ def _trust_forwarded_for() -> bool:
return os.environ.get(_TRUST_FORWARDED_ENV, "").strip().lower() in {"1", "true", "yes"}
+def trust_forwarded_headers() -> bool:
+ return _trust_forwarded_for()
+
+
def _is_loopback(host: str | None) -> bool:
try:
return bool(host) and ipaddress.ip_address(host).is_loopback
@@ -73,12 +77,58 @@ def client_ip(request) -> str:
if normalized:
return normalized
if _is_loopback(peer):
- cf = _normalize_addr(request.headers.get("cf-connecting-ip"))
- if cf:
- return cf
+ if request_from_managed_tunnel(
+ getattr(request, "scope", None), _request_app_state(request)
+ ):
+ cf = _normalize_addr(request.headers.get("cf-connecting-ip"))
+ if cf:
+ return cf
+ if any(request.headers.get(h) is not None for h in _PROXIED_CLIENT_HEADERS):
+ return f"relayed:{peer}"
return peer or "_unknown"
+def _request_app_state(request):
+ try:
+ return request.app.state
+ except Exception:
+ return None
+
+
+def _managed_tunnel_hostname(app_state) -> str | None:
+ url = getattr(app_state, "cloudflare_url", None) if app_state is not None else None
+ if not isinstance(url, str) or not url:
+ return None
+ try:
+ host = urlparse(url).hostname
+ except ValueError:
+ return None
+ return host.lower().rstrip(".") if host else None
+
+
+def request_from_managed_tunnel(scope, app_state) -> bool:
+ """Live published tunnel, one valid ``CF-Connecting-IP``, Host naming it. Caller checks the peer is loopback."""
+ expected = _managed_tunnel_hostname(app_state)
+ if not expected or not isinstance(scope, dict):
+ return False
+ cf_values = []
+ host_values = []
+ for name, value in scope.get("headers") or ():
+ if name == b"cf-connecting-ip":
+ cf_values.append(value)
+ elif name == b"host":
+ host_values.append(value)
+ if len(cf_values) != 1 or len(host_values) != 1:
+ return False
+ try:
+ if _normalize_addr(cf_values[0].decode("latin-1")) is None:
+ return False
+ request_host = urlparse("//" + host_values[0].decode("latin-1")).hostname
+ except (UnicodeDecodeError, ValueError):
+ return False
+ return bool(request_host) and request_host.lower().rstrip(".") == expected
+
+
def _is_loopback_ip(host: str | None) -> bool:
if not host or "%" in host: # a scope id (::1%eth0) is never a plain loopback
return False
diff --git a/studio/backend/utils/forwarded_headers.py b/studio/backend/utils/forwarded_headers.py
new file mode 100644
index 00000000000..776f7783948
--- /dev/null
+++ b/studio/backend/utils/forwarded_headers.py
@@ -0,0 +1,67 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Which forwarded headers rewrite the ASGI client and scheme.
+
+uvicorn's default (``proxy_headers=True``, ``forwarded_allow_ips="127.0.0.1"``) lets any loopback peer pick
+``request.client`` via ``X-Forwarded-For``, so only Colab and ``UNSLOTH_STUDIO_TRUST_FORWARDED`` keep it;
+otherwise only requests from Studio's own Cloudflare tunnel are rewritten.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from utils.client_ip import (
+ _is_loopback_ip,
+ _normalize_addr,
+ request_from_managed_tunnel,
+ trust_forwarded_headers,
+)
+
+
+def uvicorn_forwarded_kwargs(*, is_colab: bool) -> dict[str, Any]:
+ """The ``proxy_headers`` / ``forwarded_allow_ips`` arguments for ``uvicorn.Config``."""
+ if is_colab:
+ return {"proxy_headers": True, "forwarded_allow_ips": "*"}
+ if trust_forwarded_headers():
+ # uvicorn's own behaviour, including FORWARDED_ALLOW_IPS
+ return {"proxy_headers": True}
+ return {"proxy_headers": False}
+
+
+class ManagedTunnelProxyHeaders:
+ """Rewrite client and scheme for requests relayed by Studio's managed Cloudflare tunnel only."""
+
+ def __init__(self, app, app_state):
+ self.app = app
+ self.app_state = app_state
+
+ async def __call__(self, scope, receive, send):
+ if scope.get("type") in ("http", "websocket"):
+ client = scope.get("client")
+ peer = client[0] if client else None
+ if _is_loopback_ip(peer) and request_from_managed_tunnel(scope, self.app_state):
+ headers = scope.get("headers") or ()
+ proto = None
+ cf_ip = None
+ for name, value in headers:
+ if name == b"x-forwarded-proto":
+ proto = value.decode("latin-1").strip()
+ elif name == b"cf-connecting-ip":
+ cf_ip = value.decode("latin-1")
+ scope = dict(scope)
+ if proto in ("http", "https", "ws", "wss"):
+ if scope["type"] == "websocket":
+ scope["scheme"] = proto.replace("http", "ws")
+ else:
+ scope["scheme"] = proto
+ visitor = _normalize_addr(cf_ip)
+ if visitor:
+ scope["client"] = (visitor, 0)
+ await self.app(scope, receive, send)
+
+
+def wrap_direct_server(app, app_state):
+ """The ASGI app to hand uvicorn when its own proxy-header rewriting is off."""
+ return ManagedTunnelProxyHeaders(app, app_state)
diff --git a/studio/backend/utils/keyless_api_access.py b/studio/backend/utils/keyless_api_access.py
index 22a97986fe4..7f9e5302fa5 100644
--- a/studio/backend/utils/keyless_api_access.py
+++ b/studio/backend/utils/keyless_api_access.py
@@ -502,15 +502,17 @@ def keyless_transport_allowed(request: Any, scope: str) -> bool:
return _full_scope_transport_allowed(request, app_state)
if scope != KEYLESS_SCOPE_INFERENCE:
return False
+ from utils.client_ip import names_a_forwarded_client
from utils.lan_access_settings import request_is_loopback, request_on_lan_access
+ # a relaying proxy cannot vouch for its caller: neither grant covers it
+ if names_a_forwarded_client(request):
+ return False
if request_on_lan_access(request):
return True
if _public_tunnel_active(app_state):
return False
- from utils.client_ip import names_a_forwarded_client
-
- return request_is_loopback(request) and not names_a_forwarded_client(request)
+ return request_is_loopback(request)
def keyless_request_allowed(request: Any) -> bool: