fix(transport): bind dual-stack for IPv6 --allow-host CIDRs (#421)

Code-review follow-up: the bind was hardcoded 0.0.0.0 (IPv4-only), so an IPv6
--allow-host CIDR set the guard to accept IPv6 hosts but the socket never
listened on IPv6. Add a shared bind_host_for_networks() helper (single source
of truth for the HTTP, WebSocket, and reload binds, mirroring the shared
evaluate_loopback) that binds '::' when any requested network is IPv6 and
'0.0.0.0' for an IPv4-only allowlist.

https://claude.ai/code/session_01Jq5X4ivngAf1N6r5UX2BVw

Author: claude

src/godot_ai/__init__.py

@@ -122,7 +122,7 @@ def main(argv: Sequence[str] | None = None) -> None:
 
     ## #421: parse --allow-host CIDRs. A typo here fails loudly at startup
     ## rather than silently binding loopback-only (or worse, wide open).
-    from godot_ai.transport.origin_guard import parse_allow_hosts
+    from godot_ai.transport.origin_guard import bind_host_for_networks, parse_allow_hosts
 
     try:
         allow_host_networks = parse_allow_hosts(args.allow_host or [])
@@ -131,11 +131,11 @@ def main(argv: Sequence[str] | None = None) -> None:
 
     ## Widen the HTTP bind off loopback only when an allowlist is named. The
     ## DNS-rebinding guard still gates every request by the CIDR(s); binding
-    ## 0.0.0.0 without the guard would be the footgun this flag avoids.
+    ## off loopback without the guard would be the footgun this flag avoids.
     if allow_host_networks and args.transport in ("sse", "streamable-http"):
         import fastmcp
 
-        fastmcp.settings.host = "0.0.0.0"  # noqa: S104
+        fastmcp.settings.host = bind_host_for_networks(allow_host_networks)
 
     from godot_ai.runtime_info import install_pid_file
 

src/godot_ai/asgi.py

@@ -195,7 +195,9 @@ def run_with_reload(
 
     ## Bind off loopback only when an allowlist is named; the guard (rebuilt
     ## inside create_app from the same env) still gates every request.
-    bind_host = "0.0.0.0" if allow_host_networks else fastmcp.settings.host  # noqa: S104
+    from godot_ai.transport.origin_guard import bind_host_for_networks
+
+    bind_host = bind_host_for_networks(allow_host_networks) or fastmcp.settings.host
 
     src_dir = str(Path(__file__).resolve().parent.parent)
     uvicorn.run(

src/godot_ai/server.py

@@ -64,7 +64,11 @@
 from godot_ai.tools.testing import register_testing_tools
 from godot_ai.tools.theme import register_theme_tools
 from godot_ai.tools.ui import register_ui_tools
-from godot_ai.transport.origin_guard import IPNetwork, LocalhostOnlyHTTPMiddleware
+from godot_ai.transport.origin_guard import (
+    IPNetwork,
+    LocalhostOnlyHTTPMiddleware,
+    bind_host_for_networks,
+)
 from godot_ai.transport.websocket import GodotWebSocketServer
 
 logger = logging.getLogger(__name__)
@@ -113,7 +117,7 @@ def create_server(
     ## #421: --allow-host opt-in. When set, expose both transports to the
     ## named LAN CIDR(s) — bind the WS server off loopback and hand the
     ## networks to its rebinding guard. None/empty = unchanged loopback-only.
-    ws_bind_host = "0.0.0.0" if allow_host_networks else "127.0.0.1"  # noqa: S104
+    ws_bind_host = bind_host_for_networks(allow_host_networks) or "127.0.0.1"
 
     # Capture ws_port in the lifespan closure
     @asynccontextmanager

src/godot_ai/transport/origin_guard.py

@@ -112,6 +112,24 @@ def parse_allow_hosts(values: Iterable[str]) -> list[IPNetwork]:
     return networks
 
 
+def bind_host_for_networks(networks: Sequence[IPNetwork] | None) -> str | None:
+    """Bind address that exposes the transports to ``networks`` (issue #421).
+
+    Returns ``None`` when no networks are named so callers keep their
+    loopback default (the byte-for-byte unchanged path). Otherwise returns
+    ``"::"`` when any requested network is IPv6 — on a dual-stack host that
+    also accepts IPv4 — and ``"0.0.0.0"`` for an IPv4-only allowlist, so an
+    IPv6 ``--allow-host`` actually listens on IPv6 instead of silently
+    binding IPv4-only. Centralized so the HTTP bind, the WebSocket bind, and
+    the reload runner can't disagree about where to listen.
+    """
+    if not networks:
+        return None
+    if any(isinstance(net, ipaddress.IPv6Network) for net in networks):
+        return "::"  # noqa: S104 — opt-in, and the guard still gates every request
+    return "0.0.0.0"  # noqa: S104 — same
+
+
 def _host_ip_in_networks(host_header: str, networks: Sequence[IPNetwork] | None) -> bool:
     """Whether the Host header's IP literal falls inside one of ``networks``.
 

tests/unit/test_origin_guard.py

@@ -13,6 +13,7 @@
 
 from godot_ai.transport.origin_guard import (
     LocalhostOnlyHTTPMiddleware,
+    bind_host_for_networks,
     evaluate_loopback,
     is_allowed_host,
     is_allowed_origin,
@@ -566,3 +567,20 @@ async def test_middleware_rejects_lan_host_without_opt_in() -> None:
     )
     assert inner_called is False
     assert sent[0]["status"] == 403
+
+
+def test_bind_host_for_networks_none_keeps_loopback_default() -> None:
+    # No opt-in → None so callers keep their loopback default.
+    assert bind_host_for_networks(None) is None
+    assert bind_host_for_networks([]) is None
+
+
+def test_bind_host_for_networks_ipv4_only() -> None:
+    assert bind_host_for_networks(parse_allow_hosts(["192.168.1.0/24"])) == "0.0.0.0"
+
+
+def test_bind_host_for_networks_ipv6_present_binds_dual_stack() -> None:
+    # An IPv6 allowlist must actually listen on IPv6, not silently bind v4-only.
+    assert bind_host_for_networks(parse_allow_hosts(["fd00::/8"])) == "::"
+    # Mixed families also bind "::" (dual-stack accepts v4-mapped on Linux).
+    assert bind_host_for_networks(parse_allow_hosts(["192.168.1.0/24", "fd00::/8"])) == "::"