Coverage for src/ai_shell/vpn.py: 91%
272 statements
« prev ^ index » next coverage.py v7.17.0, created at 2026-11-17 21:40 +0000
« prev ^ index » next coverage.py v7.17.0, created at 2026-11-17 21:40 +0000
1"""A VPN container whose HTTP proxy carries the host Chrome's traffic.
3Some hosts have an address that sites refuse: a cloud dev box, anything in a
4datacenter. Google sign-in is the usual casualty. ai-shell cannot change the
5host's route (no root on a dev box, and the dev container must keep its
6direct path to Anthropic), so it runs the VPN in a container of its own,
7`gluetun <https://github.com/qdm12/gluetun>`_, and hands only the browser to
8it: gluetun's HTTP proxy listens on loopback, and Chrome is started with
9``--proxy-server`` pointing at it (``claude.chrome_proxy: vpn``).
11Provider: NordVPN over WireGuard. The credential is a NordVPN access token
12(``NORDVPN_TOKEN`` in ``~/.augint/.env``; Nord Account, NordVPN, Manual
13setup, Access token). gluetun needs the account's WireGuard private key, so
14the token is traded for it once through NordVPN's API and the key is cached
15under ``~/.augint/vpn/``; the token can expire, the key does not.
17An account that owns a NordVPN dedicated IP gets it without being asked: the
18same token names the dedicated-IP server (``/v1/users/services``), and
19gluetun is pinned to that server (``SERVER_HOSTNAMES``). A shared NordVPN
20exit is a datacenter address like any other and Google scores it the same
21way; the dedicated IP is the one the account's owner already uses. The
22hostname is cached next to the key; ``NORDVPN_SERVER`` in ``.env`` overrides
23it (a hostname, or ``any`` for a shared server).
25The container is a host-level singleton (``augint-shell-vpn``), like the LLM
26stack: one per machine, shared by every project and account. Rootless Podman
27runs it: ``NET_ADMIN`` and ``/dev/net/tun`` are enough, no root.
28"""
30from __future__ import annotations
32import base64
33import hashlib
34import json
35import logging
36import os
37import re
38import time
39import urllib.error
40import urllib.request
41from collections.abc import Callable, Mapping
42from pathlib import Path
43from typing import TYPE_CHECKING, Any
45from ai_shell.exceptions import AiShellError
47if TYPE_CHECKING:
48 from ai_shell.config import AiShellConfig
49 from ai_shell.container import ContainerManager
51logger = logging.getLogger(__name__)
53VPN_CONTAINER = "augint-shell-vpn"
54VPN_IMAGE = "docker.io/qmcgaw/gluetun:latest"
55#: ``chrome_proxy: vpn`` means "the proxy of ai-shell's own VPN container".
56VPN_PROXY_SENTINEL = "vpn"
57VPN_TOKEN_VAR = "NORDVPN_TOKEN"
58VPN_KEY_VAR = "NORDVPN_WIREGUARD_PRIVATE_KEY"
59#: Pins gluetun to one NordVPN server (``us2943`` or ``us2943.nordvpn.com``);
60#: ``any`` forces a shared server even when the account has a dedicated IP.
61VPN_SERVER_VAR = "NORDVPN_SERVER"
62VPN_SERVER_ANY = "any"
63NORDVPN_CREDENTIALS_URL = "https://api.nordvpn.com/v1/users/services/credentials"
64NORDVPN_SERVICES_URL = "https://api.nordvpn.com/v1/users/services"
65NORDVPN_SERVERS_URL = "https://api.nordvpn.com/v1/servers"
66NORDVPN_SERVER_SUFFIX = ".nordvpn.com"
67_SERVER_HOSTNAME = re.compile(r"^[a-z0-9][a-z0-9.-]*[a-z0-9]$")
68#: Container label that records the settings it was created with, so a
69#: changed country, key or firewall setting recreates it instead of
70#: silently keeping the old one.
71VPN_CONFIG_LABEL = "ai-shell.vpn.config"
72VPN_CHECK_URL = "https://api.ipify.org"
73VPN_READY_TIMEOUT_SECONDS = 120.0
74VPN_POLL_INTERVAL_SECONDS = 2.0
75VPN_LOG_TAIL_LINES = 15
76_WIREGUARD_KEY_BYTES = 32
79class VpnUnavailable(AiShellError):
80 """The VPN container could not be started or never came up."""
83# ---------------------------------------------------------------- credentials
86def vpn_state_dir() -> Path:
87 """Directory for the cached WireGuard key and the firewall marker."""
88 return Path.home() / ".augint" / "vpn"
91def key_cache_path() -> Path:
92 """Where the WireGuard private key derived from the token is kept (mode 0600)."""
93 return vpn_state_dir() / "nordvpn-wireguard.key"
96def server_cache_path() -> Path:
97 """Where the account's dedicated-IP server hostname is kept (empty file: none)."""
98 return vpn_state_dir() / "nordvpn-server"
101def firewall_off_marker() -> Path:
102 """Present when gluetun's firewall failed here once; the container then runs without it."""
103 return vpn_state_dir() / "firewall-off"
106def _valid_wireguard_key(key: str) -> bool:
107 try:
108 return len(base64.b64decode(key, validate=True)) == _WIREGUARD_KEY_BYTES
109 except (ValueError, TypeError):
110 return False
113def fetch_wireguard_key(token: str) -> str:
114 """Trade a NordVPN access token for the account's WireGuard private key."""
115 auth = base64.b64encode(f"token:{token.strip()}".encode()).decode("ascii")
116 request = urllib.request.Request( # noqa: S310 - fixed https URL
117 NORDVPN_CREDENTIALS_URL,
118 headers={"Authorization": f"Basic {auth}", "Accept": "application/json"},
119 )
120 try:
121 # Fixed https URL to NordVPN's API, never a user-supplied scheme.
122 # nosemgrep: python.lang.security.audit.dynamic-urllib-use-detected.dynamic-urllib-use-detected
123 with urllib.request.urlopen(request, timeout=20) as response: # noqa: S310 # nosec B310
124 payload = json.loads(response.read().decode("utf-8"))
125 except urllib.error.HTTPError as exc:
126 if exc.code in (401, 403):
127 raise VpnUnavailable(
128 f"NordVPN refused the access token ({exc.code}). Tokens expire on the "
129 f"schedule chosen when they were made: make a new one (Nord Account, NordVPN, "
130 f"Manual setup, Access token) and put it in ~/.augint/.env as {VPN_TOKEN_VAR}=..."
131 ) from exc
132 raise VpnUnavailable(f"NordVPN API answered {exc.code} for the credentials call.") from exc
133 except (urllib.error.URLError, OSError, ValueError) as exc:
134 raise VpnUnavailable(f"Could not reach the NordVPN API: {exc}") from exc
135 key = payload.get("nordlynx_private_key") if isinstance(payload, dict) else None
136 if not isinstance(key, str) or not _valid_wireguard_key(key):
137 raise VpnUnavailable(
138 "NordVPN's credentials call returned no usable WireGuard key "
139 "(nordlynx_private_key). Is the token a NordVPN access token, not a password?"
140 )
141 return key
144def _nordvpn_get(url: str, token: str | None = None) -> Any:
145 """GET a NordVPN API URL as JSON; *token* adds the ``token:<token>`` basic auth."""
146 headers = {"Accept": "application/json"}
147 if token:
148 auth = base64.b64encode(f"token:{token.strip()}".encode()).decode("ascii")
149 headers["Authorization"] = f"Basic {auth}"
150 request = urllib.request.Request(url, headers=headers) # noqa: S310 - fixed https URLs
151 try:
152 # Fixed https URLs under api.nordvpn.com, never a user-supplied scheme.
153 # nosemgrep: python.lang.security.audit.dynamic-urllib-use-detected.dynamic-urllib-use-detected
154 with urllib.request.urlopen(request, timeout=20) as response: # noqa: S310 # nosec B310
155 return json.loads(response.read().decode("utf-8"))
156 except urllib.error.HTTPError as exc:
157 raise VpnUnavailable(f"NordVPN API answered {exc.code} for {url}.") from exc
158 except (urllib.error.URLError, OSError, ValueError) as exc:
159 raise VpnUnavailable(f"Could not reach the NordVPN API: {exc}") from exc
162def fetch_dedicated_ip_server(token: str) -> str:
163 """Hostname of the account's dedicated-IP server, or ``""`` when it owns none.
165 ``/v1/users/services`` lists the account's services; the ``dedicated_ip``
166 one carries the server ids under ``details.servers``. ``/v1/servers``
167 filtered by that id gives the hostname gluetun filters on.
168 """
169 services = _nordvpn_get(NORDVPN_SERVICES_URL, token)
170 server_ids: list[int] = []
171 for item in services if isinstance(services, list) else []:
172 if not isinstance(item, dict):
173 continue
174 service = item.get("service")
175 identifier = service.get("identifier") if isinstance(service, dict) else None
176 if identifier != "dedicated_ip":
177 continue
178 details = item.get("details")
179 servers = details.get("servers") if isinstance(details, dict) else None
180 for server in servers if isinstance(servers, list) else []:
181 server_id = server.get("id") if isinstance(server, dict) else None
182 if isinstance(server_id, int):
183 server_ids.append(server_id)
184 if not server_ids:
185 return ""
186 url = f"{NORDVPN_SERVERS_URL}?filters[servers.id]={server_ids[0]}&fields[servers.hostname]"
187 servers = _nordvpn_get(url)
188 first = servers[0] if isinstance(servers, list) and servers else None
189 hostname = first.get("hostname") if isinstance(first, dict) else None
190 if not isinstance(hostname, str) or not hostname:
191 raise VpnUnavailable(
192 f"NordVPN lists a dedicated IP on server id {server_ids[0]} but /v1/servers "
193 "returned no hostname for it."
194 )
195 return normalize_server(hostname)
198def normalize_server(value: str) -> str:
199 """``us2943`` or ``US2943.nordvpn.com`` to ``us2943.nordvpn.com``; ``any`` or empty to ``""``."""
200 server = value.strip().lower()
201 if not server or server == VPN_SERVER_ANY:
202 return ""
203 if "." not in server:
204 server += NORDVPN_SERVER_SUFFIX
205 if not _SERVER_HOSTNAME.match(server):
206 raise VpnUnavailable(
207 f"{VPN_SERVER_VAR}={value!r} is not a NordVPN server name (us2943 or "
208 f"us2943.nordvpn.com, or '{VPN_SERVER_ANY}')."
209 )
210 return server
213def configured_server(env: Mapping[str, str | None]) -> str | None:
214 """The pinned server without any API call: ``NORDVPN_SERVER``, else the cache, else None."""
215 override = env.get(VPN_SERVER_VAR)
216 if override is not None and override.strip():
217 return normalize_server(override)
218 cache = server_cache_path()
219 if cache.is_file():
220 return normalize_server(cache.read_text(encoding="utf-8"))
221 return None
224def resolve_server(
225 env: Mapping[str, str | None],
226 *,
227 fetch: Callable[[str], str] = fetch_dedicated_ip_server,
228) -> str:
229 """The NordVPN server gluetun is pinned to, ``""`` for any server.
231 Order: ``NORDVPN_SERVER`` in *env* (``any`` means a shared server), the
232 cached answer from an earlier lookup, then the account's dedicated-IP
233 server looked up with ``NORDVPN_TOKEN`` and cached (an empty cache file
234 records "no dedicated IP"). Without a token nothing is pinned. A token
235 NordVPN refuses leaves the server unpinned instead of blocking a start
236 whose WireGuard key is already cached.
237 """
238 known = configured_server(env)
239 if known is not None:
240 return known
241 token = (env.get(VPN_TOKEN_VAR) or "").strip()
242 if not token:
243 return ""
244 try:
245 server = fetch(token)
246 except VpnUnavailable as exc:
247 if " 401 " in str(exc) or " 403 " in str(exc):
248 logger.warning("NordVPN did not accept the dedicated-IP lookup: %s", exc)
249 return ""
250 raise
251 _write_private(server_cache_path(), server + "\n")
252 logger.info("Cached the NordVPN server %r at %s", server, server_cache_path())
253 return server
256def resolve_wireguard_key(
257 env: Mapping[str, str | None],
258 *,
259 fetch: Callable[[str], str] = fetch_wireguard_key,
260 prompt_token: Callable[[], str] | None = None,
261) -> str:
262 """Return the WireGuard private key for gluetun.
264 Order: ``NORDVPN_WIREGUARD_PRIVATE_KEY`` in *env*, the cached key from an
265 earlier token exchange, then ``NORDVPN_TOKEN`` in *env* (traded for the
266 key and cached), then *prompt_token* when given. A missing credential is
267 an error that names the exact line to add.
268 """
269 direct = (env.get(VPN_KEY_VAR) or "").strip()
270 if direct:
271 if not _valid_wireguard_key(direct):
272 raise VpnUnavailable(f"{VPN_KEY_VAR} is not a WireGuard private key (44 characters).")
273 return direct
274 cache = key_cache_path()
275 if cache.is_file():
276 cached = cache.read_text(encoding="utf-8").strip()
277 if _valid_wireguard_key(cached):
278 return cached
279 logger.warning("Ignoring an unreadable cached key at %s", cache)
280 token = (env.get(VPN_TOKEN_VAR) or "").strip()
281 if not token and prompt_token is not None:
282 token = prompt_token().strip()
283 if not token:
284 raise VpnUnavailable(
285 "No NordVPN credential. Add one line to ~/.augint/.env:\n"
286 f" {VPN_TOKEN_VAR}=<access token from Nord Account, NordVPN, Manual setup>\n"
287 f"(or {VPN_KEY_VAR}=<WireGuard private key>). The token is exchanged once for the "
288 "WireGuard key, which is cached under ~/.augint/vpn/."
289 )
290 key = fetch(token)
291 _write_private(cache, key + "\n")
292 logger.info("Cached the NordVPN WireGuard key at %s", cache)
293 return key
296def _write_private(path: Path, text: str) -> None:
297 path.parent.mkdir(parents=True, exist_ok=True)
298 path.write_text(text, encoding="utf-8")
299 try:
300 os.chmod(path, 0o600)
301 except OSError: # pragma: no cover - Windows
302 pass
305# ------------------------------------------------------------------ container
308def config_digest(key: str, country: str, firewall: bool, proxy_port: int, server: str = "") -> str:
309 """Short digest of the settings a container was created with (no secret in it)."""
310 material = f"{key}\n{country}\n{int(firewall)}\n{proxy_port}\n{VPN_IMAGE}\n{server}".encode()
311 return hashlib.sha256(material).hexdigest()[:16]
314def run_kwargs(
315 *, key: str, country: str, firewall: bool, proxy_port: int, digest: str, server: str = ""
316) -> dict[str, Any]:
317 """``containers.run`` arguments for the gluetun container.
319 *server* pins gluetun to one hostname (the account's dedicated-IP server)
320 and then replaces the country filter: gluetun ANDs its filters, and a
321 country that does not match the pinned server would leave it no server.
322 """
323 environment = {
324 "VPN_SERVICE_PROVIDER": "nordvpn",
325 "VPN_TYPE": "wireguard",
326 "WIREGUARD_PRIVATE_KEY": key,
327 "HTTPPROXY": "on",
328 "HTTPPROXY_STEALTH": "on",
329 "HTTPPROXY_LISTENING_ADDRESS": ":8888",
330 "FIREWALL": "on" if firewall else "off",
331 # Not a general-purpose VPN host: nothing else joins its network.
332 "DOT": "on",
333 "UPDATER_PERIOD": "24h",
334 }
335 if server:
336 environment["SERVER_HOSTNAMES"] = server
337 elif country:
338 environment["SERVER_COUNTRIES"] = country
339 return {
340 "image": VPN_IMAGE,
341 "name": VPN_CONTAINER,
342 "detach": True,
343 "cap_add": ["NET_ADMIN"],
344 "devices": ["/dev/net/tun:/dev/net/tun:rwm"],
345 "ports": {"8888/tcp": ("127.0.0.1", proxy_port)},
346 "environment": environment,
347 "labels": {VPN_CONFIG_LABEL: digest},
348 "restart_policy": {"Name": "unless-stopped"},
349 }
352def proxy_url(proxy_port: int) -> str:
353 """The proxy Chrome is pointed at."""
354 return f"http://127.0.0.1:{proxy_port}"
357def exit_address(proxy: str, timeout: float = 6.0) -> str | None:
358 """The public address seen through *proxy*, or ``None`` when it does not answer."""
359 opener = urllib.request.build_opener(
360 urllib.request.ProxyHandler({"http": proxy, "https": proxy})
361 )
362 try:
363 with opener.open(VPN_CHECK_URL, timeout=timeout) as response: # noqa: S310
364 address = response.read(64).decode("ascii", "replace").strip()
365 except (urllib.error.URLError, OSError, ValueError):
366 return None
367 return address or None
370def _tail(text: str, lines: int = VPN_LOG_TAIL_LINES) -> str:
371 return "\n".join(text.strip().splitlines()[-lines:])
374def _looks_like_firewall_failure(log: str) -> bool:
375 lowered = log.lower()
376 return "firewall" in lowered and ("iptables" in lowered or "nftables" in lowered)
379def wait_for_proxy(
380 proxy: str,
381 *,
382 status: Callable[[], str | None],
383 logs: Callable[[], str],
384 timeout: float = VPN_READY_TIMEOUT_SECONDS,
385 sleep: Callable[[float], None] = time.sleep,
386) -> str:
387 """Poll until *proxy* carries traffic; return the exit address.
389 Raises :class:`VpnUnavailable` with the container's last log lines when
390 the container stops or the timeout passes.
391 """
392 deadline = time.monotonic() + timeout
393 while True:
394 address = exit_address(proxy)
395 if address:
396 return address
397 state = status()
398 if state not in ("running", "created", "restarting", "starting"):
399 raise VpnUnavailable(
400 f"The VPN container {VPN_CONTAINER} is {state or 'gone'}. Its last log lines:\n"
401 f"{_tail(logs())}"
402 )
403 if time.monotonic() >= deadline:
404 raise VpnUnavailable(
405 f"The VPN container is running but its proxy at {proxy} did not carry traffic "
406 f"within {int(timeout)} seconds. Its last log lines:\n{_tail(logs())}"
407 )
408 sleep(VPN_POLL_INTERVAL_SECONDS)
411def _container_logs(container: Any) -> str:
412 try:
413 raw = container.logs(tail=200)
414 except Exception as exc: # pragma: no cover - defensive
415 return f"(no logs: {exc})"
416 if isinstance(raw, bytes):
417 return raw.decode("utf-8", "replace")
418 return str(raw)
421def _container_status(manager: ContainerManager) -> str | None:
422 try:
423 return manager.container_status(VPN_CONTAINER)
424 except Exception: # pragma: no cover - defensive
425 return None
428def ensure_vpn(
429 manager: ContainerManager,
430 *,
431 key: str,
432 country: str = "",
433 firewall: bool = True,
434 proxy_port: int = 8888,
435 server: str = "",
436 echo: Callable[[str], None] | None = None,
437) -> str:
438 """Make sure the VPN container runs with these settings and its proxy works.
440 Returns the proxy URL. A container created with other settings is
441 replaced. *server* pins gluetun to one NordVPN hostname (see
442 :func:`resolve_server`). When gluetun cannot set up its firewall (rootless Podman on some
443 hosts), the container is recreated once with the firewall off and a
444 marker is written so later launches start that way at once.
445 """
446 echo = echo or (lambda _line: None)
447 if firewall and firewall_off_marker().is_file():
448 firewall = False
449 proxy = proxy_url(proxy_port)
450 digest = config_digest(key, country, firewall, proxy_port, server)
452 container = manager._get_container(VPN_CONTAINER)
453 if container is not None:
454 labels = getattr(container, "labels", None)
455 current = labels.get(VPN_CONFIG_LABEL) if isinstance(labels, dict) else None
456 if current != digest:
457 echo("VPN container settings changed; recreating it.")
458 manager.remove_container(VPN_CONTAINER)
459 container = None
460 elif container.status != "running":
461 echo("Starting the VPN container.")
462 container.start()
463 if container is None:
464 echo(f"Creating the VPN container ({VPN_IMAGE}).")
465 manager._pull_image_if_needed(VPN_IMAGE)
466 manager.client.containers.run(
467 **run_kwargs(
468 key=key,
469 country=country,
470 firewall=firewall,
471 proxy_port=proxy_port,
472 digest=digest,
473 server=server,
474 )
475 )
477 def logs() -> str:
478 current = manager._get_container(VPN_CONTAINER)
479 return _container_logs(current) if current is not None else "(container gone)"
481 try:
482 address = wait_for_proxy(proxy, status=lambda: _container_status(manager), logs=logs)
483 except VpnUnavailable as exc:
484 if not firewall or not _looks_like_firewall_failure(str(exc)):
485 raise
486 echo(
487 "gluetun could not set up its firewall in this container runtime; "
488 "running it without one (the proxy still goes through the tunnel)."
489 )
490 _write_private(firewall_off_marker(), "gluetun firewall failed here once\n")
491 manager.remove_container(VPN_CONTAINER)
492 return ensure_vpn(
493 manager,
494 key=key,
495 country=country,
496 firewall=False,
497 proxy_port=proxy_port,
498 server=server,
499 echo=echo,
500 )
501 where = f" (server {server})" if server else ""
502 echo(f"VPN up: traffic through the proxy leaves from {address}{where}.")
503 return proxy
506def ensure_vpn_for_config(
507 manager: ContainerManager,
508 config: AiShellConfig,
509 *,
510 env_file: Path | None = None,
511 prompt_token: Callable[[], str] | None = None,
512 echo: Callable[[str], None] | None = None,
513) -> str:
514 """Resolve the credential from the layered ``.env`` and start the VPN."""
515 from ai_shell.defaults import _load_layered_dotenv
517 env: dict[str, str | None] = dict(os.environ)
518 env.update(_load_layered_dotenv(config.project_dir, env_file))
520 def remembered_prompt() -> str:
521 # A token typed at the prompt also serves the dedicated-IP lookup.
522 token = prompt_token() if prompt_token is not None else ""
523 env[VPN_TOKEN_VAR] = token
524 return token
526 key = resolve_wireguard_key(
527 env, prompt_token=remembered_prompt if prompt_token is not None else None
528 )
529 server = resolve_server(env)
530 if server:
531 (echo or (lambda _line: None))(f"Using the account's dedicated-IP server {server}.")
532 return ensure_vpn(
533 manager,
534 key=key,
535 country=config.vpn_country,
536 firewall=config.vpn_firewall,
537 proxy_port=config.vpn_proxy_port,
538 server=server,
539 echo=echo,
540 )
543def vpn_status(manager: ContainerManager, proxy_port: int = 8888) -> dict[str, str | None]:
544 """Container state, the pinned server (no API call) and, when it runs, the exit address."""
545 state = _container_status(manager)
546 address = exit_address(proxy_url(proxy_port)) if state == "running" else None
547 try:
548 server = configured_server(os.environ) or None
549 except VpnUnavailable:
550 server = None
551 return {
552 "status": state,
553 "exit_address": address,
554 "proxy": proxy_url(proxy_port),
555 "server": server,
556 }
559def remove_vpn(manager: ContainerManager) -> bool:
560 """Stop and remove the VPN container and forget the firewall marker. True if one existed."""
561 for path in (firewall_off_marker(), server_cache_path()):
562 if path.is_file():
563 path.unlink()
564 if manager._get_container(VPN_CONTAINER) is None:
565 return False
566 manager.remove_container(VPN_CONTAINER)
567 return True