Reject short-form loopback on pairing encode paths.

Author: jatinkrmalik

app/pairing.py

@@ -287,20 +287,22 @@ def _from_ifconfig(self) -> None:
 def is_phone_reachable_gateway_url(url: str) -> bool:
     """True when a phone on LAN/VPN can open this gateway base URL.
 
-    Rejects empty hosts, ``localhost``, IPv4/IPv6 loopback, link-local,
-    unspecified, and multicast. Non-IP hostnames (MagicDNS, custom DNS) pass.
+    Rejects empty hosts, ``localhost`` / ``localhost.*``, abbreviated IPv4
+    loopback (``127.1``), IPv4/IPv6 loopback, link-local, unspecified, and
+    multicast. Other non-IP hostnames (MagicDNS, custom DNS) pass without DNS
+    lookup.
     """
     host = urlparse(url).hostname
     if not host:
         return False
-    if host.lower() == "localhost":
+    lowered = host.lower()
+    if lowered == "localhost" or lowered.startswith("localhost."):
         return False
-    try:
-        ip_address = ipaddress.ip_address(host)
-    except ValueError:
+    ip_address = _parse_gateway_host_ip(host)
+    if ip_address is None:
         return True
     if isinstance(ip_address, ipaddress.IPv4Address):
-        return _Ipv4Policy.is_reachable(host)
+        return _Ipv4Policy.is_reachable(str(ip_address))
     blocked = (
         ip_address.is_loopback
         or ip_address.is_link_local
@@ -310,6 +312,21 @@ def is_phone_reachable_gateway_url(url: str) -> bool:
     return not blocked
 
 
+def _parse_gateway_host_ip(host: str) -> ipaddress.IPv4Address | ipaddress.IPv6Address | None:
+    """Parse a URL host as an IP, including short-form IPv4 that ``ip_address`` rejects."""
+    try:
+        return ipaddress.ip_address(host)
+    except ValueError:
+        return _parse_short_ipv4_host(host)
+
+
+def _parse_short_ipv4_host(host: str) -> ipaddress.IPv4Address | None:
+    try:
+        return ipaddress.IPv4Address(socket.inet_aton(host))
+    except OSError:
+        return None
+
+
 def unreachable_pairing_override() -> tuple[str, str] | None:
     """Return ``(env_key, raw_value)`` when a pairing override is set but unusable.
 
@@ -350,6 +367,8 @@ def default_url(cls, port: int, *, saved_pairing_url: str | None = None) -> str
 
     @classmethod
     def _keep_saved(cls, port: int, saved_pairing_url: str) -> bool:
+        if not is_phone_reachable_gateway_url(saved_pairing_url):
+            return False
         if not is_ambient_lan_address(saved_pairing_url):
             return True
         return saved_pairing_url in cls.discover(port)

app/pairing_view.py

@@ -11,6 +11,7 @@
     discover_gateway_base_urls,
     encode_pairing_payload,
     is_ambient_lan_address,
+    is_phone_reachable_gateway_url,
     normalize_gateway_input,
     primary_gateway_base_url,
     qr_svg_for_payload,
@@ -187,9 +188,16 @@ def resolve_pairing_url(ctx: GatewayContext, url: str | None) -> str:
     candidates = discover_gateway_base_urls(ctx.settings.port)
     if url:
         try:
-            return normalize_gateway_input(url, ctx.settings.port)
+            normalized = normalize_gateway_input(url, ctx.settings.port)
         except ValueError as error:
             raise APIProblem(HTTP_400_BAD_REQUEST, "invalid_pairing_url", str(error)) from error
+        if not is_phone_reachable_gateway_url(normalized):
+            raise APIProblem(
+                HTTP_400_BAD_REQUEST,
+                "invalid_pairing_url",
+                "Pairing URL must be phone-reachable (not loopback or link-local).",
+            )
+        return normalized
     if not candidates:
         detail = "No phone-reachable gateway address was detected."
         unreachable = unreachable_pairing_override()

docs/desktop-embed.md

@@ -38,7 +38,10 @@ decode `payload` to recover `{v,url,token}`. Optional
 
 `VOCAGATEWAY_PUBLIC_URL` (alias `VOCAGATEWAY_PAIRING_URL`) must be a
 phone-reachable, non-loopback base URL. The gateway drops loopback and
-link-local overrides from discovery, and the QR never encodes loopback. Set
+link-local overrides from discovery (including short-form loopback like
+`127.1` and `localhost.*`). Pairing encode paths (`/v1/admin/pairing`,
+`qr.svg`, and explicit `?url=`) reject the same hosts, so the QR never
+encodes loopback. Set
 the override whenever auto-discovery would otherwise advertise an address the
 phone cannot open (Docker bridge, reverse proxy, Tailscale Serve hostname).
 

tests/test_pairing.py

@@ -41,12 +41,21 @@ def test_is_phone_reachable_gateway_url() -> None:
     assert is_phone_reachable_gateway_url("http://homelab.example:8765") is True
     assert is_phone_reachable_gateway_url("http://100.101.102.103:8765") is True
     assert is_phone_reachable_gateway_url("http://127.0.0.1:8765") is False
+    assert is_phone_reachable_gateway_url("http://127.1:8765") is False
     assert is_phone_reachable_gateway_url("http://LOCALHOST:8765") is False
+    assert is_phone_reachable_gateway_url("http://localhost.localdomain:8765") is False
     assert is_phone_reachable_gateway_url("http://[::1]:8765") is False
+    assert is_phone_reachable_gateway_url("http://[::ffff:127.0.0.1]:8765") is False
     assert is_phone_reachable_gateway_url("http://[fe80::1]:8765") is False
     assert is_phone_reachable_gateway_url("http://169.254.1.1:8765") is False
 
 
+def test_discover_rejects_short_loopback_public_url(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv(PUBLIC_URL_ENVIRONMENT_VARIABLE, "http://127.1:8765")
+    assert "http://127.1:8765" not in discover_gateway_base_urls(DEFAULT_GATEWAY_PORT)
+    assert "http://127.0.0.1:8765" not in discover_gateway_base_urls(DEFAULT_GATEWAY_PORT)
+
+
 def test_discover_rejects_loopback_public_url(monkeypatch: pytest.MonkeyPatch) -> None:
     monkeypatch.setenv(PUBLIC_URL_ENVIRONMENT_VARIABLE, "http://127.0.0.1:8765")
     assert "http://127.0.0.1:8765" not in discover_gateway_base_urls(DEFAULT_GATEWAY_PORT)

tests/test_pairing_api.py

@@ -7,7 +7,12 @@
 import httpx
 import pytest
 from conftest import TOKEN, FakeEngine, FakeNormalizer
-from starlette.status import HTTP_200_OK, HTTP_401_UNAUTHORIZED, HTTP_503_SERVICE_UNAVAILABLE
+from starlette.status import (
+    HTTP_200_OK,
+    HTTP_400_BAD_REQUEST,
+    HTTP_401_UNAUTHORIZED,
+    HTTP_503_SERVICE_UNAVAILABLE,
+)
 
 from app.config import Settings
 from app.main import create_app
@@ -93,6 +98,20 @@ async def _assert_network_switch_pairing(
 IDENTIFIER_KEY = "id"
 
 
+
+@pytest.mark.asyncio
+async def test_pairing_rejects_loopback_query_url(
+    client: httpx.AsyncClient,
+    authorization: dict[str, str],
+) -> None:
+    response = await client.get(
+        PAIRING_API_PATH,
+        headers=authorization,
+        params={URL_KEY: "http://127.1:8765"},
+    )
+    assert response.status_code == HTTP_400_BAD_REQUEST
+
+
 @pytest.mark.asyncio
 async def test_pairing_rejects_loopback_public_url(
     client: httpx.AsyncClient,