Grayscale/nanobot
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(webui): support trusted proxy bootstrap auth

Browse Source
This commit is contained in:
concertypin
2026-08-04 21:53:16 +08:00
committed by Xubin Ren
parent 170c7083ed
commit 5cd14a42df
6 changed files with 299 additions and 7 deletions
Download Patch File Download Diff File Expand all files Collapse all files
nanobot/channels/websocket/runtime.py
+48 -1
View File
@@ -4,6 +4,7 @@ from __future__ import annotations
import asyncio
import hmac
import ipaddress
import json
import re
import ssl
@@ -13,7 +14,7 @@ from contextlib import suppress
from pathlib import Path
from typing import Any, Self, TypeGuard, cast
from pydantic import Field, field_validator, model_validator
from pydantic import Field, PrivateAttr, field_validator, model_validator
from websockets.asyncio.server import ServerConnection, serve, unix_serve
from websockets.exceptions import ConnectionClosed
from websockets.http11 import Request as WsRequest
@@ -89,6 +90,51 @@ from nanobot.webui.websocket_logging import websockets_server_logger
_WEBUI_HTTP_OPEN_TIMEOUT_S = 360.0
class TrustedProxyAuthConfig(Base):
"""Authentication assertions accepted from explicitly trusted proxy peers."""
trusted_peer_cidrs: list[str] = Field(min_length=1)
assertion_header: str = Field(min_length=1)
_trusted_peer_networks: tuple[ipaddress.IPv4Network | ipaddress.IPv6Network, ...] = PrivateAttr(
default=()
)
@field_validator("trusted_peer_cidrs")
@classmethod
def validate_trusted_peer_cidrs(cls, values: list[str]) -> list[str]:
normalized: list[str] = []
for value in values:
value = value.strip()
try:
network = ipaddress.ip_network(value, strict=False)
except ValueError as exc:
raise ValueError(f"invalid trusted proxy CIDR: {value!r}") from exc
if network.prefixlen == 0:
raise ValueError("universal trusted proxy CIDRs are not allowed")
if isinstance(network, ipaddress.IPv6Network):
mapped_start = ipaddress.IPv6Address("::ffff:0:0")
mapped_end = ipaddress.IPv6Address("::ffff:ffff:ffff")
if mapped_start in network and mapped_end in network:
raise ValueError("trusted proxy CIDRs must not cover all IPv4-mapped addresses")
normalized.append(network.with_prefixlen)
return normalized
@field_validator("assertion_header")
@classmethod
def validate_assertion_header(cls, value: str) -> str:
value = value.strip()
if not value or any(char.isspace() or ord(char) < 0x21 for char in value):
raise ValueError("assertion_header must be a valid HTTP header name")
return value
@model_validator(mode="after")
def compile_trusted_peer_networks(self) -> Self:
self._trusted_peer_networks = tuple(
ipaddress.ip_network(value, strict=False) for value in self.trusted_peer_cidrs
)
return self
class WebSocketConfig(Base):
"""WebSocket server channel configuration.
@@ -117,6 +163,7 @@ class WebSocketConfig(Base):
token: str = ""
token_issue_path: str = ""
token_issue_secret: str = ""
trusted_proxy_auth: TrustedProxyAuthConfig | None = None
token_ttl_s: int = Field(default=300, ge=30, le=86_400)
websocket_requires_token: bool = True
allow_from: list[str] = Field(default_factory=lambda: ["*"])
nanobot/channels/websocket/tests/test_websocket_http_routes.py
+122
View File
@@ -3321,6 +3321,128 @@ def test_local_browser_request_requires_loopback_host_and_forwarded_origin() ->
)
def _trusted_proxy_config(
cidrs: list[str] | None = None,
*,
assertion_header: str = "Cf-Access-Jwt-Assertion",
) -> dict[str, Any]:
return {
"trustedProxyAuth": {
"trustedPeerCidrs": cidrs or ["127.0.0.1/32"],
"assertionHeader": assertion_header,
}
}
def test_trusted_proxy_requires_non_empty_assertion(bus: MagicMock) -> None:
channel = _ch(bus, **_trusted_proxy_config())
for assertion in (None, "", " "):
headers = {"Cf-Access-Jwt-Assertion": assertion} if assertion is not None else {}
resp = channel.gateway.http._handle_bootstrap(_LOCAL, _FakeReq(headers))
assert resp.status_code == 403
def test_trusted_proxy_rejects_untrusted_peer_spoof(bus: MagicMock) -> None:
channel = _ch(bus, **_trusted_proxy_config())
resp = channel.gateway.http._handle_bootstrap(
_REMOTE,
_FakeReq({"Cf-Access-Jwt-Assertion": "spoofed"}),
)
assert resp.status_code == 403
def test_trusted_proxy_accepts_assertion_without_forwarded_header_trust(
bus: MagicMock,
) -> None:
assertion = "opaque-upstream-assertion"
channel = _ch(bus, **_trusted_proxy_config())
log = MagicMock()
channel.gateway.http._log = log
resp = channel.gateway.http._handle_bootstrap(
_LOCAL,
_FakeReq(
{
"Host": "nanobot.example",
"X-Forwarded-For": "203.0.113.42",
"Forwarded": "for=203.0.113.42;host=nanobot.example",
"X-Real-IP": "203.0.113.42",
"X-Forwarded-Host": "nanobot.example",
"Cf-Access-Jwt-Assertion": assertion,
}
),
)
assert resp.status_code == 200
body = resp.body.decode()
assert assertion not in body
assert assertion not in repr(log.mock_calls)
payload = json.loads(body)
assert payload["token"].startswith("nbwt_")
assert payload["api_token"].startswith("nbwt_")
assert payload["api_token"] != payload["token"]
def test_forwarding_headers_alone_never_authorize_bootstrap(bus: MagicMock) -> None:
channel = _ch(bus)
resp = channel.gateway.http._handle_bootstrap(
_REMOTE,
_FakeReq(
{
"Host": "nanobot.example",
"X-Forwarded-For": "127.0.0.1",
"Forwarded": "for=127.0.0.1",
"X-Real-IP": "127.0.0.1",
}
),
)
assert resp.status_code == 403
def test_trusted_proxy_does_not_override_bootstrap_secret(bus: MagicMock) -> None:
channel = _ch(
bus,
tokenIssueSecret="route-secret",
**_trusted_proxy_config(),
)
resp = channel.gateway.http._handle_bootstrap(
_LOCAL,
_FakeReq({"Cf-Access-Jwt-Assertion": "present"}),
)
assert resp.status_code == 401
@pytest.mark.parametrize(
("peer", "cidr"),
[
("127.0.0.1", "127.0.0.1/32"),
("::1", "::1/128"),
("::ffff:127.0.0.1", "127.0.0.0/24"),
("127.0.0.1", "::ffff:127.0.0.0/120"),
],
)
def test_trusted_proxy_matches_ip_versions_and_mapped_peers(
bus: MagicMock,
peer: str,
cidr: str,
) -> None:
from nanobot.webui.http_utils import is_trusted_proxy_authenticated_request
config = WebSocketConfig.model_validate(_trusted_proxy_config([cidr]))
request = _FakeReq({"Cf-Access-Jwt-Assertion": "present"})
assert is_trusted_proxy_authenticated_request(_FakeConn((peer, 12345)), request.headers, config)
@pytest.mark.parametrize(
"cidr",
["not-a-cidr", "0.0.0.0/0", "::/0", "::/1", "::ffff:0:0/96"],
)
def test_trusted_proxy_rejects_invalid_or_universal_cidrs(
cidr: str,
) -> None:
from pydantic_core import ValidationError
with pytest.raises(ValidationError):
WebSocketConfig.model_validate(_trusted_proxy_config([cidr]))
def test_wildcard_host_without_auth_raises_on_startup(bus: MagicMock) -> None:
import pytest
from pydantic_core import ValidationError
nanobot/webui/http_utils.py
+44
View File
@@ -169,6 +169,50 @@ def is_localhost(connection: Any) -> bool:
return host in {"127.0.0.1", "::1", "localhost"}
def _connection_ip(connection: Any) -> ipaddress.IPv4Address | ipaddress.IPv6Address | None:
addr = getattr(connection, "remote_address", None)
host = cast(Any, addr[0] if isinstance(addr, tuple) else addr)
if not isinstance(host, str):
return None
try:
return ipaddress.ip_address(host)
except ValueError:
return None
def _address_matches_network(
address: ipaddress.IPv4Address | ipaddress.IPv6Address,
network: ipaddress.IPv4Network | ipaddress.IPv6Network,
) -> bool:
if isinstance(address, ipaddress.IPv4Address):
if isinstance(network, ipaddress.IPv4Network):
return address in network
return ipaddress.IPv6Address(f"::ffff:{address}") in network
if isinstance(network, ipaddress.IPv6Network):
return address in network
mapped = address.ipv4_mapped
return mapped is not None and mapped in network
def is_trusted_proxy_authenticated_request(
connection: Any,
headers: Any,
config: Any,
) -> bool:
"""Return True when a configured proxy peer presents a non-empty assertion."""
trusted_proxy_auth = getattr(config, "trusted_proxy_auth", None)
if trusted_proxy_auth is None:
return False
address = _connection_ip(connection)
if address is None:
return False
networks = getattr(trusted_proxy_auth, "_trusted_peer_networks", ())
if not any(_address_matches_network(address, network) for network in networks):
return False
assertion_header = getattr(trusted_proxy_auth, "assertion_header", "")
return bool(case_insensitive_header(headers, assertion_header))
def _host_without_port(value: str) -> str:
value = value.strip().strip('"').strip("'")
if not value:
nanobot/webui/ws_http.py
+10 -2
View File
@@ -60,6 +60,9 @@ from nanobot.webui.http_utils import (
from nanobot.webui.http_utils import (
is_localhost as _is_localhost,
)
from nanobot.webui.http_utils import (
is_trusted_proxy_authenticated_request as _is_trusted_proxy_authenticated_request,
)
from nanobot.webui.http_utils import (
issue_route_secret_matches as _issue_route_secret_matches,
)
@@ -372,13 +375,18 @@ class GatewayHTTPHandler:
def _handle_bootstrap(self, connection: Any, request: Any) -> Response:
secret = self.config.token_issue_secret.strip() or self.config.token.strip()
is_local_browser = _is_local_browser_request(connection, request.headers)
is_proxy_authenticated = _is_trusted_proxy_authenticated_request(
connection,
request.headers,
self.config,
)
if secret:
if not _issue_route_secret_matches(request.headers, secret):
return _http_error(401, "Unauthorized")
elif not is_local_browser:
elif not (is_local_browser or is_proxy_authenticated):
return _http_error(403, "bootstrap is localhost-only")
api_token_allowed = bool(secret) or is_local_browser
api_token_allowed = bool(secret) or is_local_browser or is_proxy_authenticated
if not self.tokens.can_issue(include_api_token=api_token_allowed):
return _http_response(
json.dumps({"error": "too many outstanding tokens"}).encode("utf-8"),