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.
Python agentaichatgptdeepseekfine-tuninggemmaimage-generationllamallmllmsopenaipythonqwenreinforcement-learningself-hostedstable-diffusiontext-to-speechttsuiunsloth
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.pyindex 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_kwargsfrom 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.pyindex 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 = tlsapp.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.pynew file mode 100644index 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 Falsediff --git a/studio/backend/tests/test_preview_followups.py b/studio/backend/tests/test_preview_followups.pyindex 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.pyindex 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 andspoofable, 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 tododge a per-IP limit."""@@ -22,6 +21,7 @@ from __future__ import annotationsimport ipaddressimport 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 normalizedif _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 loopbackreturn Falsediff --git a/studio/backend/utils/forwarded_headers.py b/studio/backend/utils/forwarded_headers.pynew file mode 100644index 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.pyindex 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_clientfrom 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 Falseif request_on_lan_access(request):return Trueif _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: