ha-mcp-dev 9.1.0.dev3267__tar.gz → 9.1.0.dev3271__tar.gz

{ha_mcp_dev-9.1.0.dev3267 → ha_mcp_dev-9.1.0.dev3271}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 9.1.0.dev3267
+Version: 9.1.0.dev3271
 Summary: Home Assistant MCP Server - Complete control of Home Assistant through MCP
 Keywords: mcp,home-assistant,ai,automation,smart-home
 Author: Julien

{ha_mcp_dev-9.1.0.dev3267 → ha_mcp_dev-9.1.0.dev3271}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "ha-mcp-dev"
-version = "9.1.0.dev3267"
+version = "9.1.0.dev3271"
 description = "Home Assistant MCP Server - Complete control of Home Assistant through MCP"
 readme = "README.md"
 requires-python = ">=3.13,<3.15"

{ha_mcp_dev-9.1.0.dev3267 → ha_mcp_dev-9.1.0.dev3271}/pyproject.toml.orig

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "ha-mcp-dev"
-version = "9.1.0.dev3267"
+version = "9.1.0.dev3271"
 description = "Home Assistant MCP Server - Complete control of Home Assistant through MCP"
 readme = "README.md"
 # Upper bound widened to <3.15 so the package installs on Home Assistant's

{ha_mcp_dev-9.1.0.dev3267 → ha_mcp_dev-9.1.0.dev3271}/src/ha_mcp/config_settings.py

@@ -570,6 +570,19 @@ class Settings(BaseSettings):
         ),
     ] = Field("", alias="REDACT_APP_OPTION_KEYS")
 
+    # IPv6 networks, beyond the local ones, that may reach the app's port and
+    # the in-process server's "Local network" port (#2915); see
+    # ``ha_mcp.ipv6_lan_guard``. Read when the listener starts.
+    ipv6_allowed_networks: Annotated[
+        str,
+        Setting(
+            surface="advanced",
+            section="operations",
+            app=_ALL_FLAVORS,
+            restart_required=True,
+        ),
+    ] = Field("", alias="IPV6_ALLOWED_NETWORKS")
+
     # Mandatory best-practice skills — server-side master switch for the
     # write-tool skill_content delivery feature (issue #1182). When True
     # (default), the six write tools (automations / scripts / scenes /

ha_mcp_dev-9.1.0.dev3271/src/ha_mcp/ipv6_lan_guard.py

@@ -0,0 +1,204 @@
+"""Keep the IPv6 listener local-network-only, like IPv4 behind NAT (issue #2915).
+
+IPv4 clients reach the wildcard listener only from the LAN unless the user
+forwards a port. IPv6 has no NAT: a router that admits inbound IPv6 would put
+the port on the internet. This guard refuses IPv6 peers outside loopback,
+link-local, unique-local, the host's own on-link networks and an operator
+allowlist, and leaves IPv4 exactly as it was.
+
+It judges the socket peer, never ``X-Forwarded-For``: the guard wraps uvicorn's
+``ProxyHeadersMiddleware`` itself (uvicorn's server-level one is turned off),
+so proxy headers are applied after the check with uvicorn's default trusted
+proxies. A local reverse proxy keeps working and a forged header cannot get a
+peer through.
+"""
+
+from __future__ import annotations
+
+import ipaddress
+import logging
+import os
+import time
+from collections.abc import Iterable
+from typing import Any
+
+from uvicorn.middleware.proxy_headers import ProxyHeadersMiddleware
+
+logger = logging.getLogger(__name__)
+
+SETTING_NAME = "Extra IPv6 networks allowed (ipv6_allowed_networks)"
+_ALWAYS_LOCAL = tuple(
+    ipaddress.IPv6Network(net) for net in ("::1/128", "fe80::/10", "fc00::/7")
+)
+_ROUTES_FILE = "/proc/net/ipv6_route"
+_RTF_UP, _RTF_GATEWAY, _RTF_REJECT = 0x0001, 0x0002, 0x0200
+_ROUTES_TTL_SECONDS = 30.0
+# A directly connected network is a LAN prefix (/64, at most a /48 site).
+# Shorter device routes are catch-alls, such as a VPN client's 2000::/4 or
+# ::/1, and would make every internet address look local.
+_MIN_ON_LINK_PREFIX = 48
+# Distinct refused peers logged at WARNING before the rest drop to DEBUG, so
+# scanners cannot flood the log.
+_WARNED_PEERS_CAP = 256
+
+
+def _split_entries(text: str) -> list[str]:
+    return [e.strip() for e in text.replace(",", "\n").splitlines() if e.strip()]
+
+
+def _parse_entry(entry: str) -> ipaddress.IPv6Network | None:
+    try:
+        network = ipaddress.ip_network(entry, strict=False)
+    except ValueError:
+        return None
+    return network if isinstance(network, ipaddress.IPv6Network) else None
+
+
+def invalid_allowed_networks(text: str) -> list[str]:
+    """Return the allowlist entries that are not IPv6 networks."""
+    return [entry for entry in _split_entries(text) if _parse_entry(entry) is None]
+
+
+def parse_allowed_networks(text: str) -> tuple[ipaddress.IPv6Network, ...]:
+    """Parse the operator allowlist: IPv6 networks separated by commas or lines.
+
+    The settings page rejects invalid entries on save; one set another way
+    (app options, environment) is logged and skipped rather than failing
+    startup.
+    """
+    networks = []
+    for entry in _split_entries(text):
+        network = _parse_entry(entry)
+        if network is None:
+            logger.error(
+                "Ignoring %s entry %r: not an IPv6 network", SETTING_NAME, entry
+            )
+            continue
+        networks.append(network)
+    return tuple(networks)
+
+
+def configured_allowed_networks() -> tuple[ipaddress.IPv6Network, ...]:
+    """Return the allowlist from the server's settings."""
+    from .config import get_global_settings
+
+    return parse_allowed_networks(get_global_settings().ipv6_allowed_networks)
+
+
+def on_link_ipv6_networks(
+    routes_file: str = _ROUTES_FILE,
+) -> tuple[ipaddress.IPv6Network, ...]:
+    """Return the IPv6 networks the host reaches directly, from the kernel routes.
+
+    These are the local networks: the LAN prefix even when the host's own
+    address is a DHCPv6 /128, any docker bridge. Never the default route, a
+    route through a gateway, a reject route, a catch-all shorter than /48, or
+    the loopback device's own-address routes. An unreadable table yields none,
+    so the guard fails closed.
+    """
+    try:
+        with open(routes_file, encoding="ascii") as fh:
+            lines = fh.read().splitlines()
+    except OSError:
+        return ()
+    networks = set()
+    for line in lines:
+        fields = line.split()
+        if len(fields) < 10:
+            continue
+        dest, plen, _src, _src_plen, next_hop, _metric, _ref, _use, flags, dev = fields[
+            :10
+        ]
+        prefix_len, route_flags = int(plen, 16), int(flags, 16)
+        if (
+            dev == "lo"
+            or prefix_len < _MIN_ON_LINK_PREFIX
+            or int(next_hop, 16) != 0
+            or not route_flags & _RTF_UP
+            or route_flags & (_RTF_GATEWAY | _RTF_REJECT)
+        ):
+            continue
+        network = ipaddress.IPv6Network((int(dest, 16), prefix_len), strict=False)
+        if not network.is_multicast:
+            networks.add(network)
+    return tuple(networks)
+
+
+class IPv6LanGuard:
+    """ASGI middleware refusing IPv6 peers outside the local network."""
+
+    def __init__(
+        self,
+        app: Any,
+        allowed_networks: Iterable[ipaddress.IPv6Network] = (),
+        trusted_proxies: str | None = None,
+        routes_file: str = _ROUTES_FILE,
+    ) -> None:
+        # uvicorn's own Config default (since 0.53), which this replaces in the
+        # stack: a local proxy may reach the server over either loopback.
+        trusted = trusted_proxies or os.environ.get(
+            "FORWARDED_ALLOW_IPS", "127.0.0.1,::1"
+        )
+        self._app = ProxyHeadersMiddleware(app, trusted_hosts=trusted)
+        self._allowed = _ALWAYS_LOCAL + tuple(allowed_networks)
+        self._routes_file = routes_file
+        self._on_link: tuple[ipaddress.IPv6Network, ...] = ()
+        self._on_link_at = float("-inf")
+        self._warned: set[str] = set()
+
+    def _peer_allowed(self, client: tuple[str, int] | None) -> bool:
+        if not client:
+            return True  # no peer address (e.g. a unix socket)
+        try:
+            peer = ipaddress.ip_address(client[0].split("%", 1)[0])
+        except ValueError:
+            return False  # not an IP (e.g. Starlette TestClient's "testclient")
+        if isinstance(peer, ipaddress.IPv4Address) or peer.ipv4_mapped:
+            return True  # IPv4 is not filtered
+        if any(peer in net for net in self._allowed):
+            return True
+        now = time.monotonic()
+        if now - self._on_link_at > _ROUTES_TTL_SECONDS:
+            self._on_link = on_link_ipv6_networks(self._routes_file)
+            self._on_link_at = now
+        return any(peer in net for net in self._on_link)
+
+    def _log_refusal(self, peer: str) -> None:
+        level = logging.DEBUG
+        if peer not in self._warned and len(self._warned) < _WARNED_PEERS_CAP:
+            self._warned.add(peer)
+            level = logging.WARNING
+        logger.log(
+            level,
+            "Refused IPv6 connection from %s: outside the local network "
+            "(add its network to %s to permit it)",
+            peer,
+            SETTING_NAME,
+        )
+
+    async def __call__(self, scope: Any, receive: Any, send: Any) -> None:
+        if scope["type"] not in ("http", "websocket") or self._peer_allowed(
+            scope.get("client")
+        ):
+            await self._app(scope, receive, send)
+            return
+        self._log_refusal(scope["client"][0])
+        if scope["type"] == "websocket":
+            await send({"type": "websocket.close", "code": 1008})
+            return
+        await send(
+            {
+                "type": "http.response.start",
+                "status": 403,
+                "headers": [(b"content-type", b"text/plain; charset=utf-8")],
+            }
+        )
+        await send(
+            {
+                "type": "http.response.body",
+                "body": (
+                    "IPv6 access is limited to the local network. To allow this "
+                    f"network, add it to {SETTING_NAME}.\n"
+                ).encode(),
+            }
+        )

ha_mcp_dev-9.1.0.dev3271/src/ha_mcp/listen_sockets.py

@@ -0,0 +1,111 @@
+"""Listening sockets for the IPv4 wildcard bind host (issue #2915).
+
+Binding ``0.0.0.0`` accepts IPv4 clients only, and ``::`` alone is IPv6-only
+because asyncio sets ``IPV6_V6ONLY``. The app and the in-process server keep
+``0.0.0.0`` as their configured and displayed host, so every log line and
+connect URL stays as before, and hand uvicorn one socket per address family.
+
+Stdlib only: the component's tests load this file without importing ha_mcp.
+"""
+
+from __future__ import annotations
+
+import errno
+import logging
+import socket
+from collections.abc import Callable
+
+logger = logging.getLogger(__name__)
+
+ALL_INTERFACES_V4 = "0.0.0.0"
+
+
+def wildcard_listen_sockets(host: str, port: int) -> list[_ListenSocket] | None:
+    """Bind ``port`` on every IPv4 and IPv6 address when ``host`` is ``0.0.0.0``.
+
+    Returns ``None`` for any other host, which uvicorn then binds itself. Like
+    asyncio's ``create_server(host=None)``, a family the machine has disabled is
+    skipped. IPv6 is also skipped, with a warning, when another process holds
+    the port there while IPv4 bound. Any other bind error (such as the port
+    being in use on IPv4) is raised, and so is ``OSError`` when no family binds.
+    """
+    if host != ALL_INTERFACES_V4:
+        return None
+    sockets: list[_ListenSocket] = []
+    try:
+        for family, kind, proto, _name, address in socket.getaddrinfo(
+            None, port, socket.AF_UNSPEC, socket.SOCK_STREAM, 0, socket.AI_PASSIVE
+        ):
+            try:
+                sock = _ListenSocket(family, kind, proto)
+            except OSError:
+                continue
+            sockets.append(sock)
+            sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+            if family == socket.AF_INET6:
+                sock.setsockopt(socket.IPPROTO_IPV6, socket.IPV6_V6ONLY, 1)
+            try:
+                sock.bind(address)
+            except OSError as err:
+                if not _ipv6_bind_skippable(err, family, sockets, port):
+                    raise
+                sockets.remove(sock)
+                sock.close()
+    except BaseException:
+        for opened in sockets:
+            opened.close()
+        raise
+    if not sockets:
+        raise OSError(f"No address family could bind port {port}")
+    return sockets
+
+
+def _ipv6_bind_skippable(
+    err: OSError, family: int, sockets: list[_ListenSocket], port: int
+) -> bool:
+    """Return True when a failed IPv6 bind should leave the server on IPv4."""
+    if family != socket.AF_INET6:
+        return False
+    if err.errno == errno.EADDRNOTAVAIL:
+        return True  # IPv6 disabled with sysctl
+    # Another process holding the port on IPv6 only must not stop the IPv4
+    # listener the server had before IPv6 was added.
+    if err.errno == errno.EADDRINUSE and any(
+        sock.family == socket.AF_INET for sock in sockets
+    ):
+        logger.warning("Port %d is already in use on IPv6; serving IPv4 only", port)
+        return True
+    return False
+
+
+def announce_when_listening(sockets: list[_ListenSocket], host: str, port: int) -> None:
+    """Log uvicorn's "Uvicorn running on ..." line once ``sockets`` are serving.
+
+    uvicorn skips that line when handed pre-bound sockets, assuming a process
+    manager logged it. The sockets log it themselves from the ``listen()`` call
+    that starts serving them, which is the point in uvicorn's startup where it
+    would have logged it, on its thread, so the startup log reads as before.
+    """
+    pending = {id(sock) for sock in sockets}
+
+    def listened(sock: socket.socket) -> None:
+        pending.discard(id(sock))
+        if not pending:
+            logging.getLogger("uvicorn.error").info(
+                "Uvicorn running on http://%s:%d (Press CTRL+C to quit)", host, port
+            )
+
+    for sock in sockets:
+        sock.on_listen = listened
+
+
+class _ListenSocket(socket.socket):
+    """A socket that reports the ``listen()`` call that starts serving it."""
+
+    on_listen: Callable[[socket.socket], None] | None = None
+
+    def listen(self, *args: int) -> None:
+        super().listen(*args)
+        if self.on_listen is not None:
+            callback, self.on_listen = self.on_listen, None
+            callback(self)

{ha_mcp_dev-9.1.0.dev3267 → ha_mcp_dev-9.1.0.dev3271}/src/ha_mcp/settings_ui/_handlers_advanced.py

@@ -295,6 +295,23 @@ def _check_advanced_bounds_choices(fname: str, coerced: Any) -> JSONResponse | N
     return None
 
 
+def _check_ipv6_networks(fname: str, value: str) -> JSONResponse | None:
+    """Reject allowlist entries that are not IPv6 networks, naming them."""
+    from ..ipv6_lan_guard import invalid_allowed_networks
+
+    invalid = invalid_allowed_networks(value)
+    if not invalid:
+        return None
+    return JSONResponse(
+        create_error_response(
+            ErrorCode.VALIDATION_INVALID_PARAMETER,
+            f"{fname!r} has entries that are not IPv6 networks: {', '.join(invalid)}.",
+            suggestions=["Enter IPv6 networks such as 2001:db8:5::/48."],
+        ),
+        status_code=400,
+    )
+
+
 def _validate_one_advanced_field(
     fname: str,
     raw: Any,
@@ -343,6 +360,8 @@ def _validate_one_advanced_field(
     if coerce_err is not None:
         return None, is_addon_synced, coerce_err
     bounds_err = _check_advanced_bounds_choices(fname, coerced)
+    if bounds_err is None and fname == "ipv6_allowed_networks":
+        bounds_err = _check_ipv6_networks(fname, coerced)
     if bounds_err is not None:
         return None, is_addon_synced, bounds_err
     return coerced, is_addon_synced, None

{ha_mcp_dev-9.1.0.dev3267 → ha_mcp_dev-9.1.0.dev3271}/src/ha_mcp/settings_ui/locales/en.json

@@ -458,6 +458,8 @@
     "advanced.max_retries.help": "Retry budget per failed REST call.",
     "advanced.verify_ssl.label": "Verify TLS certificates",
     "advanced.verify_ssl.help": "Verify the Home Assistant server's TLS certificate. Turn this off only on a trusted network, for a self-signed certificate or a hostname mismatch: it weakens transport security.",
+    "advanced.ipv6_allowed_networks.label": "Extra IPv6 networks allowed",
+    "advanced.ipv6_allowed_networks.help": "IPv6 clients reach this server's own port only from the local network: loopback, link-local, unique local (fc00::/7) and the networks the Home Assistant host is directly connected to. IPv4 is unaffected. List other IPv6 networks to allow, separated by commas or new lines (for example 2001:db8:5::/48). Adding ::/0 allows every IPv6 client, including from the internet if your router lets inbound IPv6 through.",
     "advanced.fuzzy_threshold.label": "Fuzzy-search threshold",
     "advanced.fuzzy_threshold.help": "Lower values allow looser entity matching.",
     "advanced.automation_config_time_budget.label": "Automation config time budget (s)",