browser_connect.py 58 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090109110921093109410951096109710981099110011011102110311041105110611071108110911101111111211131114111511161117111811191120112111221123112411251126112711281129113011311132113311341135113611371138113911401141114211431144114511461147114811491150115111521153115411551156115711581159116011611162116311641165116611671168
  1. """Shared helpers for attaching Hermes to a local Chromium-family CDP port.
  2. Resolves the default Chromium browser + real profile dir, snapshots that profile for the
  3. ``browser.use_real_profile`` consent path, and discovers/launches a debug browser on a
  4. loopback CDP port (dual-stack: IPv4 first, then IPv6).
  5. """
  6. from __future__ import annotations
  7. import contextlib
  8. import json
  9. import logging
  10. import ntpath
  11. import os
  12. import platform
  13. import posixpath
  14. import re
  15. import shlex
  16. import shutil
  17. import socket
  18. import sqlite3
  19. import subprocess
  20. import time
  21. import urllib.parse
  22. import urllib.request
  23. from dataclasses import dataclass, field
  24. from pathlib import Path
  25. from agent.deadline import poll_until
  26. from agent.proxy_bypass import is_loopback_host
  27. from hermes_constants import get_hermes_home
  28. logger = logging.getLogger(__name__)
  29. DEFAULT_BROWSER_CDP_PORT = 9222
  30. DEFAULT_BROWSER_CDP_URL = f"http://127.0.0.1:{DEFAULT_BROWSER_CDP_PORT}"
  31. @dataclass(frozen=True)
  32. class _Browser:
  33. """Per-browser install/profile locations for one Chromium-family product."""
  34. key: str
  35. mac_app: str
  36. mac_support: tuple[str, ...] # under ~/Library/Application Support
  37. win_bins: tuple[str, ...] # shutil.which names on Windows
  38. win_install: tuple[tuple[str, ...], ...] # under Program Files / LOCALAPPDATA
  39. win_profile: tuple[str, ...] # under LOCALAPPDATA
  40. linux_bins: tuple[str, ...] # shutil.which names on Linux
  41. linux_paths: tuple[str, ...] # known absolute install paths
  42. linux_config: str # under $XDG_CONFIG_HOME
  43. # PATH names tried by chromium_executable() when they differ from linux_bins
  44. # (channel/alias binaries are launch candidates only).
  45. linux_exec: tuple[str, ...] | None = None
  46. # Launch-candidate order (chrome, chromium, brave, brave-origin, edge) is the tuple
  47. # order. ``brave-origin`` is Brave's standalone paid build: same Chromium core but a
  48. # fully distinct install identity (Brave-Origin product path, ``BraveOHTML`` ProgId,
  49. # ``com.brave.Browser.origin`` bundle id) that installs side-by-side with Brave. Its
  50. # profile is NOT under Brave-Browser and must never be conflated with the ``brave``
  51. # key — a "brave" lookup resolving to the Origin binary drives the wrong profile.
  52. # Positional layout per entry: key, mac_app / mac_support, win_bins / win_install /
  53. # win_profile / linux_bins / linux_paths / linux_config [, linux_exec].
  54. _BROWSERS = (
  55. _Browser(
  56. "chrome", "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
  57. ("Google", "Chrome"), ("chrome.exe", "chrome"),
  58. (("Google", "Chrome", "Application", "chrome.exe"),),
  59. ("Google", "Chrome", "User Data"),
  60. ("google-chrome", "google-chrome-stable"),
  61. ("/opt/google/chrome/chrome", "/usr/bin/google-chrome", "/usr/bin/google-chrome-stable"),
  62. "google-chrome"),
  63. _Browser(
  64. "chromium", "/Applications/Chromium.app/Contents/MacOS/Chromium",
  65. ("Chromium",), ("chromium.exe", "chromium"),
  66. (("Chromium", "Application", "chrome.exe"), ("Chromium", "Application", "chromium.exe")),
  67. ("Chromium", "User Data"),
  68. ("chromium-browser", "chromium"),
  69. ("/usr/bin/chromium-browser", "/usr/bin/chromium"),
  70. "chromium"),
  71. _Browser(
  72. "brave", "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",
  73. ("BraveSoftware", "Brave-Browser"), ("brave.exe", "brave"),
  74. (("BraveSoftware", "Brave-Browser", "Application", "brave.exe"),),
  75. ("BraveSoftware", "Brave-Browser", "User Data"),
  76. ("brave-browser", "brave-browser-stable", "brave"),
  77. ("/usr/bin/brave-browser", "/usr/bin/brave-browser-stable", "/usr/bin/brave",
  78. "/snap/bin/brave", "/opt/brave.com/brave/brave-browser", "/opt/brave.com/brave/brave",
  79. "/opt/brave-bin/brave"),
  80. "BraveSoftware/Brave-Browser"),
  81. _Browser(
  82. "brave-origin", "/Applications/Brave Origin.app/Contents/MacOS/Brave Origin",
  83. ("BraveSoftware", "Brave-Origin"), ("brave-origin.exe", "brave-origin"),
  84. (("BraveSoftware", "Brave-Origin", "Application", "brave.exe"),
  85. ("BraveSoftware", "Brave-Origin", "Application", "brave-origin.exe")),
  86. ("BraveSoftware", "Brave-Origin", "User Data"),
  87. ("brave-origin", "brave-origin-nightly"),
  88. ("/usr/bin/brave-origin", "/opt/brave.com/brave-origin/brave-origin",
  89. "/opt/brave.com/brave-origin-nightly/brave-origin"),
  90. "BraveSoftware/Brave-Origin", linux_exec=("brave-origin",)),
  91. _Browser(
  92. "edge", "/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge",
  93. ("Microsoft Edge",), ("msedge.exe", "msedge"),
  94. (("Microsoft", "Edge", "Application", "msedge.exe"),),
  95. ("Microsoft", "Edge", "User Data"),
  96. ("microsoft-edge", "microsoft-edge-stable", "msedge"),
  97. ("/usr/bin/microsoft-edge", "/usr/bin/microsoft-edge-stable",
  98. "/opt/microsoft/msedge/microsoft-edge", "/opt/microsoft/msedge/msedge"),
  99. "microsoft-edge", linux_exec=("microsoft-edge", "microsoft-edge-stable")),
  100. )
  101. _BROWSER_BY_KEY = {b.key: b for b in _BROWSERS}
  102. # --- Default-Chromium resolution (``browser.use_real_profile``) ------------------------
  103. # Only Chromium-family browsers are supported; a non-Chromium default (Firefox, Safari)
  104. # resolves to None and the caller fails closed. Each platform table is a STABLE map plus a
  105. # CHANNEL list: Beta/Dev/Canary are recognized but unsupported (their profiles live in dirs
  106. # the tables don't carry) and are matched FIRST so they fail closed instead of being
  107. # swallowed into the stable family — driving the wrong profile is a wrong-principal bug
  108. # (#95549 invariant).
  109. # Windows UserChoice ProgId prefixes → key. Case-insensitive PREFIX match so
  110. # version suffixes (``ChromeHTML.X``) still resolve.
  111. _WINDOWS_PROGID_MAP = (
  112. ("chromehtml", "chrome"), ("msedgehtm", "edge"),
  113. ("braveohtml", "brave-origin"), # Brave Origin stable (brave-core install_static)
  114. ("bravehtml", "brave"), ("chromiumhtm", "chromium"))
  115. # ``ChromeBHTML`` = Beta, ``ChromeDHTML`` = Dev, ``ChromeSSHTML`` = Canary (SxS);
  116. # ``MSEdge[BDC]HTML`` = Edge channels; Brave Origin Beta=BraveOBHTML, Dev=BraveODHTML,
  117. # Nightly/SxS=BraveOSHTM (no trailing L — 10-char cap).
  118. _WINDOWS_CHANNEL_PROGIDS = (
  119. "chromebhtml", "chromedhtml", "chromesshtml", "chromecanaryhtml",
  120. "msedgebhtml", "msedgedhtml", "msedgechtml",
  121. "bravebetahtml", "bravenightlyhtml",
  122. "braveobhtml", "braveodhtml", "braveoshtm")
  123. # Linux xdg default-web-browser .desktop name fragments → key (SUBSTRING match),
  124. # including Flatpak application ids (``com.google.Chrome.desktop``).
  125. _LINUX_DESKTOP_MAP = (
  126. ("google-chrome", "chrome"), ("com.google.chrome", "chrome"), ("chromium", "chromium"),
  127. # ORDER MATTERS: ``brave-origin.desktop`` contains the bare ``brave`` fragment,
  128. # so the substring scan must hit the Origin entry first (#95549).
  129. ("brave-origin", "brave-origin"), ("brave", "brave"),
  130. ("microsoft-edge", "edge"), ("com.microsoft.edge", "edge"), ("msedge", "edge"))
  131. _LINUX_CHANNEL_FRAGMENTS = (
  132. "google-chrome-beta", "google-chrome-unstable", "google-chrome-canary",
  133. "com.google.chrome.beta", "com.google.chrome.dev", "com.google.chrome.canary",
  134. "microsoft-edge-beta", "microsoft-edge-dev", "microsoft-edge-canary",
  135. "brave-browser-beta", "brave-browser-nightly", "brave-browser-dev",
  136. "brave-origin-beta", "brave-origin-nightly", "brave-origin-dev")
  137. # Where sandboxed Linux packages keep the profile instead of $XDG_CONFIG_HOME.
  138. _LINUX_FLATPAK_IDS = {"chrome": "com.google.Chrome", "chromium": "org.chromium.Chromium",
  139. "brave": "com.brave.Browser", "edge": "com.microsoft.Edge"}
  140. _LINUX_SNAP_PROFILE_PARTS = {
  141. "chromium": ("snap", "chromium", "common", "chromium"),
  142. "brave": ("snap", "brave", "current", ".config", "BraveSoftware", "Brave-Browser")}
  143. # macOS LaunchServices bundle-id → key. EXACT match (not prefix): ``com.google.chrome.beta``
  144. # must not be read as ``com.google.chrome``, nor ``com.brave.browser.origin`` (Homebrew
  145. # cask id for Brave Origin) as plain ``com.brave.browser``.
  146. _DARWIN_BUNDLE_MAP = (
  147. ("com.google.chrome", "chrome"), ("com.microsoft.edgemac", "edge"),
  148. ("com.brave.browser", "brave"), ("com.brave.browser.origin", "brave-origin"),
  149. ("org.chromium.chromium", "chromium"))
  150. _DARWIN_CHANNEL_BUNDLES = (
  151. "com.google.chrome.beta", "com.google.chrome.dev", "com.google.chrome.canary",
  152. "com.microsoft.edgemac.beta", "com.microsoft.edgemac.dev", "com.microsoft.edgemac.canary",
  153. "com.brave.browser.beta", "com.brave.browser.nightly",
  154. "com.brave.browser.origin.beta", "com.brave.browser.origin.dev",
  155. "com.brave.browser.origin.nightly")
  156. # Sentinel for a recognized-but-unsupported Chromium CHANNEL default. Distinct from
  157. # None (non-Chromium) so the caller can give a channel-specific message.
  158. UNSUPPORTED_CHANNEL = "__unsupported_channel__"
  159. def real_profile_data_dir(browser: str, system: str | None = None) -> str | None:
  160. """Default user-data-dir for ``browser`` on ``system`` (None if unknown). Linux tries native
  161. ($XDG_CONFIG_HOME), snap and Flatpak — first existing wins, else native so the caller's
  162. error names it. Darwin/Windows paths are not stat'ed."""
  163. b = _BROWSER_BY_KEY.get(browser)
  164. if b is None:
  165. return None
  166. system = system or platform.system()
  167. home = os.path.expanduser("~")
  168. if system == "Darwin":
  169. return posixpath.join(home, "Library", "Application Support", *b.mac_support)
  170. if system == "Windows":
  171. local = os.environ.get("LOCALAPPDATA") or ntpath.join(home, "AppData", "Local")
  172. return ntpath.join(local, *b.win_profile)
  173. config = os.environ.get("XDG_CONFIG_HOME") or posixpath.join(home, ".config")
  174. linux_parts = b.linux_config.split("/")
  175. candidates = [posixpath.join(config, *linux_parts)]
  176. if browser in _LINUX_SNAP_PROFILE_PARTS:
  177. candidates.append(posixpath.join(home, *_LINUX_SNAP_PROFILE_PARTS[browser]))
  178. if browser in _LINUX_FLATPAK_IDS:
  179. candidates.append(posixpath.join(home, ".var", "app", _LINUX_FLATPAK_IDS[browser], "config",
  180. *linux_parts))
  181. return next((c for c in candidates if os.path.isdir(c)), candidates[0])
  182. def _first_present(paths) -> str | None:
  183. return next((p for p in paths if p and os.path.isfile(p)), None)
  184. def chromium_executable(browser: str, system: str | None = None) -> str | None:
  185. """Return the first present executable for a Chromium ``browser``."""
  186. b = _BROWSER_BY_KEY.get(browser)
  187. if b is None:
  188. return None
  189. system = system or platform.system()
  190. if system == "Darwin":
  191. return _first_present((b.mac_app,))
  192. if system == "Windows":
  193. bases = [
  194. os.environ.get("PROGRAMFILES", r"C:\Program Files"),
  195. os.environ.get("PROGRAMFILES(X86)", r"C:\Program Files (x86)"),
  196. os.environ.get("LOCALAPPDATA", str(Path.home() / "AppData" / "Local"))]
  197. return _first_present(os.path.join(base, *parts) for base in bases for parts in b.win_install)
  198. # Linux: PATH lookup first, then the known absolute install paths.
  199. found = next(filter(None, map(shutil.which, b.linux_exec or b.linux_bins)), None)
  200. return found or _first_present(b.linux_paths)
  201. def _classify_default(value: str, channels, table, match) -> str | None:
  202. """Map an OS default-browser identifier to a canonical key. Channels are checked FIRST: a
  203. Beta/Dev/Canary id must fail closed (UNSUPPORTED_CHANNEL), never match the stable profile."""
  204. if any(match(value, chan) for chan in channels):
  205. return UNSUPPORTED_CHANNEL
  206. return next((browser for frag, browser in table if match(value, frag)), None)
  207. _WINDOWS_HTTPS_ASSOC = r"Software\Microsoft\Windows\Shell\Associations\UrlAssociations\https"
  208. def _windows_shell_progid(scheme: str) -> str | None:
  209. """Effective ProgId for a URL scheme as the Windows Shell resolves it."""
  210. try:
  211. import ctypes
  212. from ctypes import wintypes
  213. query = ctypes.WinDLL("shlwapi", use_last_error=True).AssocQueryStringW
  214. query.argtypes = [wintypes.DWORD, wintypes.DWORD, wintypes.LPCWSTR, wintypes.LPCWSTR,
  215. wintypes.LPWSTR, ctypes.POINTER(wintypes.DWORD)]
  216. query.restype = ctypes.c_long
  217. buf = ctypes.create_unicode_buffer(256)
  218. size = wintypes.DWORD(len(buf))
  219. # 20 = ASSOCSTR_PROGID. ASSOCSTR_EXECUTABLE can fail (0x80070483) on 25H2.
  220. if query(0, 20, scheme, None, buf, ctypes.byref(size)) != 0:
  221. return None
  222. return buf.value or None
  223. except (AttributeError, OSError): # non-Windows host
  224. return None
  225. def _windows_registry_progid() -> str | None:
  226. """Registry fallback. Windows 11 25H2 Settings writes only ``UserChoiceLatest\\ProgId``;
  227. the legacy ``UserChoice`` key can be stale, missing, or present without a value."""
  228. try:
  229. import winreg # type: ignore
  230. except ImportError:
  231. return None
  232. for sub in (r"UserChoiceLatest\ProgId", "UserChoice"):
  233. try:
  234. with winreg.OpenKey(winreg.HKEY_CURRENT_USER, rf"{_WINDOWS_HTTPS_ASSOC}\{sub}") as key:
  235. prog_id, _ = winreg.QueryValueEx(key, "ProgId")
  236. except OSError:
  237. continue
  238. if prog_id:
  239. return str(prog_id)
  240. return None
  241. def _detect_default_windows() -> str | None:
  242. prog_id = _windows_shell_progid("https") or _windows_registry_progid()
  243. if not prog_id:
  244. return None
  245. return _classify_default(prog_id.lower(), _WINDOWS_CHANNEL_PROGIDS,
  246. _WINDOWS_PROGID_MAP, str.startswith)
  247. def _run_stdout(argv: list[str]) -> str | None:
  248. try:
  249. return subprocess.run(argv, capture_output=True, text=True, encoding="utf-8",
  250. errors="replace", timeout=5, check=False).stdout
  251. except Exception:
  252. return None
  253. def _launchservices_https_handler(dump: str) -> str | None:
  254. """Bundle id registered for ``https`` in ``defaults read … LSHandlers`` output (an array of
  255. ``{ … }`` dicts). Only the ``LSHandlerURLScheme = https`` entry counts — a browser
  256. registered for another scheme or a file type must not be mistaken for the default."""
  257. entries: list[str] = []
  258. depth, buf = 0, []
  259. for ch in dump:
  260. depth += (ch == "{") - (ch == "}")
  261. if ch == "{" and depth == 1:
  262. buf = []
  263. elif ch == "}" and depth == 0:
  264. entries.append("".join(buf))
  265. elif depth >= 1:
  266. buf.append(ch)
  267. for entry in entries:
  268. low = entry.lower()
  269. if not re.search(r'lshandlerurlscheme\s*=\s*"?https"?\s*;', low):
  270. continue
  271. # Strip the nested LSHandlerPreferredVersions block first: on macOS 26 it carries
  272. # a VERSION NUMBER (LSHandlerRoleAll = "7559.97";), not the "-" placeholder older
  273. # releases used, and the role regex below would return it instead of the bundle id.
  274. # Left in, the role regex below would match that version before the real bundle id sitting at the
  275. # entry's own level and return "7559.97" — which maps to no browser, so detection fails on a machine
  276. # whose default IS Chrome (PR #95620 review).
  277. low = re.sub(r"lshandlerpreferredversions\s*=\s*\{[^}]*\}\s*;", "", low)
  278. # The real bundle id is the first non-"-" role value at this level.
  279. roles = re.findall(r'lshandlerrole(?:all|viewer)\s*=\s*"?([a-z0-9.\-]+)"?\s*;', low)
  280. return next((role for role in roles if role != "-"), None)
  281. return None
  282. def _detect_default_darwin() -> str | None:
  283. out = _run_stdout(["defaults", "read",
  284. "com.apple.LaunchServices/com.apple.launchservices.secure", "LSHandlers"])
  285. bundle = _launchservices_https_handler(out) if out is not None else None
  286. if not bundle:
  287. return None
  288. # Exact match. A non-Chromium https handler (Safari, Firefox, Arc, …) or an unknown
  289. # channel bundle fails closed: no "first installed Chromium wins" fallback.
  290. return _classify_default(bundle.lower(), _DARWIN_CHANNEL_BUNDLES, _DARWIN_BUNDLE_MAP, str.__eq__)
  291. def _detect_default_linux() -> str | None:
  292. out = (_run_stdout(["xdg-settings", "get", "default-web-browser"]) or "").strip().lower()
  293. # Substring match; channels first because ``google-chrome-beta.desktop`` contains
  294. # the stable ``google-chrome`` fragment.
  295. return _classify_default(out, _LINUX_CHANNEL_FRAGMENTS, _LINUX_DESKTOP_MAP, str.__contains__)
  296. def detect_default_chromium(system: str | None = None) -> str | None:
  297. """Return the canonical key of the default Chromium browser, or None."""
  298. detect = {"Windows": _detect_default_windows, "Darwin": _detect_default_darwin}
  299. return detect.get(system or platform.system(), _detect_default_linux)()
  300. # --- Real-profile SNAPSHOT launch -------------------------------------------------------
  301. # Never drive the live default user-data-dir: Chromium ≥136 (Google builds) refuses remote
  302. # debugging on it, and the user's running browser holds it (SingletonLock). Instead snapshot
  303. # the real profile into ``~/.hermes/browser-profile/`` and launch the user's real binary on
  304. # the copy — with NO mock-keychain/basic-store switches, so OS-keyring-encrypted cookies
  305. # decrypt exactly as in the user's own browser.
  306. # Excluded from the snapshot: caches/telemetry AND replay-prone state that hangs a fresh
  307. # Chromium's renderer (extensions + service workers spin up on launch and wedge JS eval;
  308. # IndexedDB/GPUCache add hundreds of MB). Only auth/login state is kept.
  309. _SNAPSHOT_IGNORES = (
  310. "*Cache*", # Cache, Code Cache, GPUCache, GrShaderCache, ShaderCache, GraphiteDawnCache, component_crx_cache, ...
  311. "Extensions", # wallets/etc.: 100s of MB, and hang the renderer headless
  312. "Extension*", # Extension State, Extension Rules, Extension Scripts
  313. "Local Extension Settings",
  314. "Service Worker", # replays on launch → wedges the renderer
  315. "IndexedDB", "Crash Reports", "Crashpad", "BrowserMetrics*", "Snapshots",
  316. "OptimizationGuide*", "optimization_guide_model_store", "Safe Browsing", "SafetyTips",
  317. "OnDeviceHeadSuggestModel", "segmentation_platform", "Sync Data", "Shared Dictionary",
  318. "History*", # large; not needed for auth
  319. "Favicons*",
  320. "Singleton*", # live-instance symlinks; never valid in a copy
  321. "RunningChromeVersion", "SingletonSocket", "*.tmp",
  322. "*-journal", # SQLite rollback journals — sidecars of the auth DBs,
  323. "*-wal", # which are copied via online-backup; a stale sidecar
  324. "*-shm", # next to a backed-up DB corrupts it.
  325. "BrowserMetrics-spare.pma",
  326. )
  327. # Auth-bearing files re-synced from the live profile on EVERY consented launch (the full
  328. # tree is copied only when the snapshot doesn't exist yet). RELATIVE TO A PROFILE DIR; the
  329. # caller mirrors them into the copy's ``Default``. No ``-journal``/``-wal`` sidecars: the
  330. # DBs come via sqlite online-backup (committed state folded in); a stale journal corrupts.
  331. _AUTH_REFRESH_PROFILE_FILES = (
  332. "Cookies", "Network/Cookies", "Login Data", "Login Data For Account", "Web Data", "Preferences")
  333. def real_profile_copy_dir(browser: str) -> str:
  334. """Return the hermes-owned snapshot dir for ``browser``'s real profile."""
  335. return str(get_hermes_home() / "browser-profile" / browser)
  336. def _last_used_profile(src: str) -> str:
  337. """Profile dir Chrome last used (``Local State`` → profile.last_used), else ``Default``. The
  338. signed-in session usually lives in the profile actually browsed (``Profile 6``), not Default."""
  339. try:
  340. with open(os.path.join(src, "Local State"), encoding="utf-8-sig", errors="replace") as fh:
  341. state = json.load(fh)
  342. last = ((state.get("profile") or {}).get("last_used")) or "Default"
  343. except (OSError, ValueError, AttributeError):
  344. last = "Default"
  345. return last if isinstance(last, str) and os.path.isdir(os.path.join(src, last)) else "Default"
  346. def _secure_snapshot(path: str, *, contents: bool = False) -> None:
  347. """Lock down a snapshot dir (or, with ``contents``, everything INSIDE it) as a secret store.
  348. It holds the user's Cookies / Login Data, so it gets the same owner-only perms (managed-mode /
  349. NixOS group-share carve-out, HERMES_UID/GID) as every Hermes secret dir — via ``_secure_dir``/
  350. ``_secure_file``, not a bespoke chmod. Contents matter too (#96729): ``copy2`` keeps Chrome's
  351. 0644 and sqlite backups land umask-wide, so cookies were world-readable under the
  352. ``HERMES_HOME_MODE`` hatch. Best-effort; never blocks a launch."""
  353. try:
  354. from hermes_cli.config import _secure_dir, _secure_file
  355. if not contents:
  356. _secure_dir(path)
  357. return
  358. for root, dirs, files in os.walk(path):
  359. for d in dirs:
  360. _secure_dir(os.path.join(root, d))
  361. for f in files:
  362. _secure_file(os.path.join(root, f))
  363. except Exception as e:
  364. logger.debug("could not secure real-profile snapshot %s %s: %s",
  365. "contents" if contents else "dir", path, e)
  366. # Auth files that are SQLite databases: on Windows a running Chrome holds these with an
  367. # exclusive lock, so a raw copy raises WinError 32 and a best-effort skip leaves the copy
  368. # signed-out. They are copied via SQLite's online-backup API instead. Matched by basename.
  369. _SQLITE_AUTH_DBS = frozenset({"Cookies", "Login Data", "Login Data For Account", "Web Data"})
  370. # Budget for one auth DB's online backup. A running browser holds Login Data / Login Data For
  371. # Account / Web Data with a hot write lock, so backup makes no progress and this deadline is
  372. # what fails — the reason users see, so it is a named constant rather than a bare string.
  373. _AUTH_BACKUP_DEADLINE_S = 5.0
  374. _AUTH_DB_LOCKED = ("SQLite backup made no progress within five seconds — "
  375. "a running browser holds a write lock on it")
  376. # Session cookies keep the copy signed in. Login Data / Web Data are saved passwords and
  377. # autofill, which a running Chrome on macOS/Linux holds with a write lock even when Cookies
  378. # copy in milliseconds; failing the snapshot over them forced users to quit Chrome before
  379. # every browser session. They get a short best-effort budget and are skipped when locked.
  380. _SESSION_AUTH_DBS = frozenset({"Cookies"})
  381. _OPTIONAL_AUTH_BACKUP_DEADLINE_S = 0.5
  382. def _copy_auth_file(src_file: str, dst_file: str, *, deadline_s: float | None = None) -> str | None:
  383. """Copy auth state; returns None on success, else WHY the file could not be snapshotted.
  384. A DB that cannot be backed up consistently within the deadline is refused, never raw-copied."""
  385. os.makedirs(os.path.dirname(dst_file), exist_ok=True)
  386. try:
  387. if os.path.basename(src_file) in _SQLITE_AUTH_DBS:
  388. deadline = time.monotonic() + (_AUTH_BACKUP_DEADLINE_S if deadline_s is None else deadline_s)
  389. last_remaining: list[int | None] = [None]
  390. def check_deadline(_status: int, remaining: int, total: int) -> None:
  391. # A held write lock makes every step fail with ``remaining`` unchanged; a
  392. # large DB on a slow disk keeps shrinking it. Only the former is "locked" —
  393. # the all-locked message tells the user to quit the browser.
  394. before = total if last_remaining[0] is None else last_remaining[0]
  395. last_remaining[0] = remaining
  396. if _status != sqlite3.SQLITE_DONE and time.monotonic() >= deadline:
  397. if remaining < before:
  398. raise TimeoutError(f"SQLite backup exceeded {_AUTH_BACKUP_DEADLINE_S:g}s "
  399. "while still making progress")
  400. raise TimeoutError(_AUTH_DB_LOCKED)
  401. # SQLite must coordinate both ends: immutable ignores committed source WAL,
  402. # while replacing only the destination file can replay its abandoned WAL.
  403. # Connection busy timeouts do not bound backup's retry loop; its callback does.
  404. with contextlib.closing(sqlite3.connect(
  405. Path(src_file).resolve().as_uri() + "?mode=ro", uri=True, timeout=0.0)) as source:
  406. with contextlib.closing(sqlite3.connect(dst_file, timeout=0.0)) as out:
  407. source.backup(out, pages=256, progress=check_deadline, sleep=0.1)
  408. else:
  409. shutil.copy2(src_file, dst_file)
  410. return None
  411. except (OSError, sqlite3.Error) as e:
  412. # A raw DB copy can lose committed WAL or overwrite a locked destination.
  413. logger.debug("real-profile: could not copy %s: %s", src_file, e)
  414. return str(e) or type(e).__name__
  415. def _mirror_profile_auth(src: str, dst: str, source_profile: str) -> dict[str, str]:
  416. """Mirror ``source_profile``'s auth files into the copy's ``Default`` (the launched browser opens it);
  417. returns ``{relative name: reason}`` for the session-cookie DBs that could NOT be copied ({} =
  418. the signed-in state is usable). Locked password/autofill DBs are logged and skipped."""
  419. failed: dict[str, str] = {}
  420. for rel in _AUTH_REFRESH_PROFILE_FILES:
  421. s = os.path.join(src, source_profile, rel)
  422. if not os.path.isfile(s):
  423. continue
  424. base = os.path.basename(rel)
  425. session_db = base in _SESSION_AUTH_DBS
  426. reason = _copy_auth_file(s, os.path.join(dst, "Default", rel),
  427. deadline_s=None if session_db else _OPTIONAL_AUTH_BACKUP_DEADLINE_S)
  428. if not reason or base not in _SQLITE_AUTH_DBS:
  429. continue
  430. if session_db:
  431. failed[rel] = reason
  432. else:
  433. why = "the running browser holds a write lock on it" if reason == _AUTH_DB_LOCKED else reason
  434. logger.info("real-profile snapshot: skipped %s (%s); session cookies still copied", rel, why)
  435. return failed
  436. def _unavailable_auth_dbs_error(browser: str, failed: dict[str, str]) -> str:
  437. """Message naming WHICH session-cookie databases could not be snapshotted and WHY, so it never
  438. reads as "close the browser" when the real cause is an unreadable file (and vice versa)."""
  439. names = ", ".join(failed)
  440. if all(reason == _AUTH_DB_LOCKED for reason in failed.values()):
  441. return (f"{browser} is running and holds the profile's {names} with a write lock, so their "
  442. "SQLite backup made no progress within five seconds. Hermes does not fall back to a "
  443. "raw file copy (it could lose committed logins). Fully quit "
  444. f"{browser} (including any background instance) and retry, or turn "
  445. "browser.use_real_profile off.")
  446. details = "; ".join(f"{name}: {reason}" for name, reason in failed.items())
  447. return (f"could not read the '{browser}' profile's login data ({details}). "
  448. f"Close {browser} and retry, or turn browser.use_real_profile off.")
  449. _SNAPSHOT_DONE_MARKER = ".hermes-snapshot-complete"
  450. # Prefix stamped on the "profile is locked" error so the calling layer can recognize the
  451. # needs-the-browser-closed condition and surface the close-with-approval flow.
  452. _PROFILE_LOCKED_PREFIX = "[profile-locked] "
  453. def _profile_is_locked(src: str, source_profile: str) -> bool:
  454. """True when the active profile's cookie DB can't be opened (browser running). On Windows a
  455. running browser holds Cookies deny-all (PermissionError); this FAST probe fails closed BEFORE
  456. the heavy snapshot so a locked profile never hangs the launch. Always False on POSIX."""
  457. db = _first_present( # modern Network/ location first
  458. os.path.join(src, source_profile, rel)
  459. for rel in (os.path.join("Network", "Cookies"), "Cookies"))
  460. if not db:
  461. return False # nothing to lock; let the copy path handle "no cookies"
  462. try:
  463. with open(db, "rb"):
  464. return False
  465. except OSError as e: # other OSErrors are transient — don't declare locked; let the copy try
  466. return isinstance(e, PermissionError)
  467. def _browser_setting(key: str):
  468. """``browser.<key>`` from the effective user config (managed overlay, ``${VAR}`` expanded); None when
  469. unset/unreadable."""
  470. try:
  471. from hermes_cli.config_effective import load_user_config_effective
  472. browser_cfg = load_user_config_effective().get("browser", {})
  473. return browser_cfg.get(key) if isinstance(browser_cfg, dict) else None
  474. except Exception as e:
  475. logger.debug("could not read %s: %s", key, e)
  476. return None
  477. def _real_profile_pin() -> str | None:
  478. """Pinned source profile dir name from ``browser.real_profile_pin`` (ALWAYS copied when set).
  479. Unset, the snapshot follows ``profile.last_used``, which can hand the agent the wrong identity.
  480. """
  481. pin = _browser_setting("real_profile_pin")
  482. return pin.strip() if isinstance(pin, str) and pin.strip() else None
  483. def _resolve_source_profile(src: str) -> tuple[str | None, str | None]:
  484. """``(profile_dir_name, error)``: the pin if set, else last_used. A pin missing under ``src``
  485. FAILS CLOSED — falling back would silently browse as the wrong identity (wrong-principal)."""
  486. pin = _real_profile_pin()
  487. if pin:
  488. if os.path.isdir(os.path.join(src, pin)):
  489. return pin, None
  490. return None, (
  491. f"browser.real_profile_pin is set to '{pin}' but that profile directory does not "
  492. f"exist under {src!r}. Profile directories are named like 'Default' or 'Profile 2' "
  493. f"— list them with: ls {src!r}. Fix the pin, or remove it to fall back to the "
  494. "last-used profile.")
  495. return _last_used_profile(src), None
  496. def _real_profile_autoclose() -> bool:
  497. """Whether browser.real_profile_autoclose consent is on (config read)."""
  498. return bool(_browser_setting("real_profile_autoclose") or False)
  499. def _processes_holding_profile(src: str):
  500. """Yield psutil.Process instances holding ``src`` open: Chromium-family binaries whose
  501. cmdline references THIS user-data-dir — never an unrelated same-PID process. An unreadable
  502. cmdline is skipped."""
  503. try:
  504. import psutil
  505. except ImportError: # hard dep; defensive
  506. return
  507. norm = os.path.normcase(os.path.normpath(src))
  508. browser_bins = (
  509. "chrome", "chrome.exe", "chromium", "chromium.exe", "chrome_crashpad",
  510. "brave", "brave.exe", "msedge", "msedge.exe", "google chrome")
  511. for proc in psutil.process_iter(["name", "cmdline"]):
  512. try:
  513. name = (proc.info.get("name") or "").lower()
  514. cmd = proc.info.get("cmdline") or []
  515. joined = " ".join(cmd)
  516. except (psutil.NoSuchProcess, psutil.AccessDenied, OSError):
  517. continue
  518. argv0 = cmd[0].lower() if cmd else "" # some platforms report a generic name
  519. if not any(b in name or b in argv0 for b in browser_bins):
  520. continue
  521. # Binding: the exact user-data-dir must appear in the cmdline, normalized.
  522. if (norm in os.path.normcase(os.path.normpath(joined))
  523. or f"--user-data-dir={src}".lower() in joined.lower()):
  524. yield proc
  525. def close_browser_holding_profile(src: str, timeout: float = 15.0) -> tuple[bool, str]:
  526. """Terminate the browser process tree holding ``src`` and wait for release. CONSENTED,
  527. DESTRUCTIVE (unsaved tab/form state is lost): only call after the user agreed."""
  528. try:
  529. import psutil
  530. except ImportError:
  531. return False, "psutil unavailable — cannot close the browser automatically."
  532. procs = list(_processes_holding_profile(src))
  533. if not procs:
  534. # Already closed, or the holder is a different user / unreadable — caller re-probes.
  535. return False, "no matching browser process found holding the profile."
  536. # Include child processes (renderers, GPU, crashpad) for a full tree kill.
  537. gone_errs = (psutil.NoSuchProcess, psutil.AccessDenied)
  538. targets = list(procs)
  539. for p in procs:
  540. with contextlib.suppress(*gone_errs):
  541. targets.extend(p.children(recursive=True))
  542. for p in targets:
  543. with contextlib.suppress(*gone_errs):
  544. p.terminate()
  545. alive = psutil.wait_procs(targets, timeout=min(timeout, 8.0))[1]
  546. for p in alive:
  547. with contextlib.suppress(*gone_errs):
  548. p.kill()
  549. psutil.wait_procs(alive, timeout=3.0)
  550. # The lock releases slightly after the process exits on Windows; poll.
  551. source_profile = _resolve_source_profile(src)[0] or _last_used_profile(src)
  552. if poll_until(lambda: not _profile_is_locked(src, source_profile), timeout, 0.5):
  553. return True, "closed the browser and the profile lock released."
  554. return False, (
  555. "closed the browser processes but the profile is still locked — "
  556. "another instance may have relaunched (background/tray mode).")
  557. def _sync_local_state(src: str, dst: str, source_profile: str) -> None:
  558. """Copy ``Local State`` into the snapshot and rewrite it for the single ``Default`` profile.
  559. Verbatim it names the SOURCE profile (last_used="Profile 2", info_cache of 2/4/7) the copy
  560. lacks, so Chrome would start SIGNED OUT. CRITICAL: Default's entry must be the SOURCE profile's
  561. identity (Default DIR holds its cookies), else Chrome demands "Continue as <name>" each launch.
  562. """
  563. ls_src, ls_dst = os.path.join(src, "Local State"), os.path.join(dst, "Local State")
  564. if os.path.isfile(ls_src):
  565. try:
  566. shutil.copy2(ls_src, ls_dst)
  567. except OSError as e:
  568. logger.debug("real-profile snapshot: skipped Local State: %s", e)
  569. try:
  570. with open(ls_dst, encoding="utf-8-sig") as fh:
  571. state = json.load(fh)
  572. prof = state.get("profile")
  573. if isinstance(prof, dict):
  574. cache = prof.get("info_cache")
  575. if isinstance(cache, dict):
  576. src_entry = cache.get(source_profile) or cache.get("Default")
  577. if src_entry:
  578. prof["info_cache"] = {"Default": src_entry}
  579. prof["last_used"] = "Default"
  580. prof["last_active_profiles"] = ["Default"]
  581. with open(ls_dst, "w", encoding="utf-8") as fh:
  582. json.dump(state, fh)
  583. except (OSError, ValueError) as e:
  584. logger.debug("real-profile snapshot: could not normalize Local State: %s", e)
  585. def _locked_profile_error(browser: str) -> str:
  586. """Fail-closed message for a locked profile; offers auto-close only when consent arms it.
  587. NEVER kill from here: closing the browser is destructive and must be an explicit per-attempt,
  588. user-approved step. A still-locked retry blocks again — no auto-retry, no loop."""
  589. if _real_profile_autoclose():
  590. msg = (
  591. f"{browser} is running and has its profile locked, so its login data can't be copied "
  592. "yet. Hermes can close it for you (this quits the browser — you'll lose unsaved "
  593. "tabs). Ask the user to confirm, then close it and retry; if it's still locked after "
  594. "that, they must fully quit it (including any background/tray instance).")
  595. else:
  596. msg = (
  597. f"{browser} is running and has its profile locked, so its login data can't be copied. "
  598. "Fully quit the browser (including any background/tray instance) and retry, or turn "
  599. "browser.use_real_profile off. (Enable browser.real_profile_autoclose to let Hermes "
  600. "offer to close it for you.)")
  601. return _PROFILE_LOCKED_PREFIX + msg
  602. def _copy_profile_tree(src: str, dst: str, source_profile: str) -> None:
  603. """Fresh (or torn-and-rebuilding) copy of the ACTIVE profile dir into the copy's Default,
  604. minus caches AND the SQLite auth DBs (raw copytree of a Chrome-held file raises on Windows);
  605. ``_mirror_profile_auth`` copies the DBs lock-aware instead."""
  606. dst_default = os.path.join(dst, "Default")
  607. try:
  608. shutil.rmtree(dst_default, ignore_errors=True)
  609. shutil.copytree(
  610. os.path.join(src, source_profile),
  611. dst_default,
  612. dirs_exist_ok=True,
  613. symlinks=False,
  614. ignore=shutil.ignore_patterns(*_SNAPSHOT_IGNORES, *_SQLITE_AUTH_DBS),
  615. ignore_dangling_symlinks=True)
  616. except shutil.Error as multi:
  617. # Per-file failures (browser mid-write) are non-fatal.
  618. logger.info(
  619. "real-profile snapshot: %d file(s) skipped copying %s/%s",
  620. len(multi.args[0]) if multi.args else 0, src, source_profile)
  621. def _drop_singleton_leftovers(dst: str) -> None:
  622. """Never carry live-instance leftovers into the copy (they make Chrome think it's open)."""
  623. for leftover in ("SingletonLock", "SingletonSocket", "SingletonCookie"):
  624. with contextlib.suppress(OSError):
  625. os.unlink(os.path.join(dst, leftover))
  626. def _snapshot_source(marker: str) -> str | None:
  627. """Source profile name a completed snapshot was taken from (the done marker's content)."""
  628. try:
  629. with open(marker, encoding="utf-8-sig") as fh:
  630. return fh.read().strip() or None
  631. except OSError:
  632. return None
  633. def _reuse_snapshot(browser: str, dst: str) -> tuple[str, None]:
  634. """Serve the last completed snapshot as-is when the live profile is locked. Its logins are as
  635. fresh as that copy; the next launch with the browser closed re-syncs them. Refusing instead
  636. would drop the session to a signed-out browser although a usable copy is on disk."""
  637. _drop_singleton_leftovers(dst)
  638. logger.info("real-profile: %s holds its profile lock; reusing the last snapshot in %s "
  639. "(logins as of that copy)", browser, dst)
  640. return dst, None
  641. def snapshot_real_profile(browser: str, src: str | None = None) -> tuple[str | None, str | None]:
  642. """Snapshot ``browser``'s real ACTIVE profile into the hermes copy dir; returns ``(dst, err)``.
  643. Copies ``Local State`` plus the active profile's auth files into the copy's ``Default``. The
  644. completion marker is written only after full success, so a torn first copy (disk full, Ctrl+C)
  645. never looks "already populated" — it is redone from scratch. A locked live profile (Windows,
  646. browser running) reuses a completed snapshot of the same source profile without re-syncing;
  647. only a missing or other-profile snapshot fails with the locked error."""
  648. src = src or real_profile_data_dir(browser)
  649. if not src or not os.path.isdir(src):
  650. return None, (
  651. f"profile directory for '{browser}' was not found ({src!r}). "
  652. "Launch that browser at least once, or turn browser.use_real_profile off.")
  653. source_profile, resolve_err = _resolve_source_profile(src)
  654. if resolve_err or not source_profile:
  655. return None, resolve_err
  656. dst = real_profile_copy_dir(browser)
  657. marker = os.path.join(dst, _SNAPSHOT_DONE_MARKER)
  658. # Only a copy that previously COMPLETED counts as populated; a half-written tree is
  659. # rebuilt — otherwise a torn first copy poisons freshness forever.
  660. populated = os.path.isfile(marker)
  661. same_source = populated and _snapshot_source(marker) == source_profile
  662. # Fast lock probe BEFORE any copy: a blocking file op on a Windows-locked cookie DB can
  663. # hang the launch for minutes. Never trips on POSIX, where a running browser only locks the
  664. # password/autofill DBs, which ``_mirror_profile_auth`` skips.
  665. if _profile_is_locked(src, source_profile):
  666. return _reuse_snapshot(browser, dst) if same_source else (None, _locked_profile_error(browser))
  667. try:
  668. if populated and not same_source:
  669. # Drop another profile's marker BEFORE re-syncing: an interrupted sync must never leave
  670. # it vouching for this profile's cookies on a later locked reuse.
  671. os.unlink(marker)
  672. os.makedirs(dst, exist_ok=True)
  673. # Secure the snapshot dir AND its browser-profile parent on EVERY launch so a failed
  674. # first attempt or an older-build dir still converges to owner-only perms.
  675. for path in filter(None, (os.path.dirname(dst), dst)):
  676. _secure_snapshot(path)
  677. _sync_local_state(src, dst, source_profile)
  678. if not populated:
  679. _copy_profile_tree(src, dst, source_profile)
  680. # Both paths: lock-aware auth DB copy into Default — also the per-launch re-sync.
  681. failed_dbs = _mirror_profile_auth(src, dst, source_profile)
  682. if failed_dbs: # no session cookies: a "real profile" launch would be signed out
  683. return None, _unavailable_auth_dbs_error(browser, failed_dbs)
  684. _drop_singleton_leftovers(dst)
  685. # Mark complete only after everything above succeeded.
  686. try:
  687. with open(marker, "w", encoding="utf-8") as fh:
  688. fh.write(source_profile)
  689. except OSError as e:
  690. logger.debug("real-profile snapshot: could not write done marker: %s", e)
  691. # AFTER the marker write so the marker itself is covered; every pass, so old snapshots heal.
  692. _secure_snapshot(dst, contents=True)
  693. except OSError as e:
  694. return None, f"could not snapshot the '{browser}' profile into {dst}: {e}"
  695. return dst, None
  696. def cleanup_real_profile_snapshots() -> None:
  697. """Delete the whole real-profile snapshot store when consent is OFF (idempotent)."""
  698. root = str(get_hermes_home() / "browser-profile")
  699. if os.path.isdir(root):
  700. shutil.rmtree(root, ignore_errors=True)
  701. logger.info("real-profile: removed snapshot store %s (consent off)", root)
  702. def _debug_candidate_paths(system: str):
  703. """Yield possible debug-browser binaries in launch order (may include None/missing)."""
  704. install_bases = (os.environ.get("ProgramFiles"), os.environ.get("ProgramFiles(x86)"),
  705. os.environ.get("LOCALAPPDATA"))
  706. for b in _BROWSERS:
  707. if system == "Darwin":
  708. yield b.mac_app
  709. elif system == "Windows":
  710. yield from map(shutil.which, b.win_bins)
  711. for base in filter(None, install_bases):
  712. for parts in b.win_install:
  713. yield os.path.join(base, *parts)
  714. else:
  715. yield from map(shutil.which, b.linux_bins)
  716. yield from b.linux_paths
  717. if system not in ("Darwin", "Windows"):
  718. # WSL: Windows installs under ``/mnt/c/...`` are POSIX paths regardless of the host
  719. # OS, so join with posixpath (os.path.join would emit backslashes on nt).
  720. for b in _BROWSERS:
  721. for base in ("/mnt/c/Program Files", "/mnt/c/Program Files (x86)"):
  722. for parts in b.win_install:
  723. yield posixpath.join(base, *parts)
  724. def get_chrome_debug_candidates(system: str) -> list[str]:
  725. candidates: dict[str, str] = {} # normalized -> first path seen (dedupe, keep order)
  726. for path in filter(None, _debug_candidate_paths(system)):
  727. normalized = os.path.normcase(os.path.normpath(path))
  728. if normalized not in candidates and os.path.isfile(path):
  729. candidates[normalized] = path
  730. return list(candidates.values())
  731. def chrome_debug_data_dir() -> str:
  732. return str(get_hermes_home() / "chrome-debug")
  733. def _managed_install() -> bool:
  734. """True when a package manager (NixOS) owns this install's modes.
  735. Read once per creation so the *creation* mode honours the same carve-out
  736. ``hermes_cli.config._secure_dir`` applies to reconciliation. Import is
  737. local and failure means "not managed": an unimportable config module is
  738. the single-user source-install case, where 0700 is the right default.
  739. """
  740. try:
  741. from hermes_cli.config import is_managed
  742. return bool(is_managed())
  743. except Exception: # pragma: no cover - defensive
  744. return False
  745. def _ensure_chrome_debug_data_dir(data_dir: str) -> None:
  746. """Create the Chromium user-data-dir owner-only (0700), except managed.
  747. ``chrome-debug`` is a real Chromium profile: Cookies, Login Data, and
  748. Local Storage live here. Created with a bare ``os.makedirs`` it inherits
  749. the umask and lands 0755, so every other local account could list and
  750. read those stores. ``HERMES_HOME`` is 0700 by default, which contains the
  751. damage — but the documented ``HERMES_HOME_MODE=0701`` hatch (so nginx can
  752. traverse to a served subdirectory) makes a 0755 child genuinely
  753. world-readable.
  754. The mode is passed to ``os.makedirs`` so it is set *at creation* — no
  755. window where the profile sits world-readable before a follow-up chmod.
  756. Policy is then reconciled by ``hermes_cli.config._secure_dir``, the house
  757. helper, rather than a hand-rolled chmod: it skips managed/NixOS installs,
  758. honours ``HERMES_HOME_MODE``, and applies ``HERMES_UID``/``HERMES_GID``
  759. ownership so a root-created dir does not lock out uid-mapped Docker
  760. workers (#34107).
  761. **Managed installs are skipped at creation too, not just at
  762. reconciliation.** ``_secure_dir`` returns early under ``is_managed()``
  763. because the NixOS module deliberately shares state group-wise, and
  764. ``chrome-debug`` is *not* one of the directories its ``systemd.tmpfiles``
  765. rules pre-create — it is made lazily at runtime, so a hardcoded 0700 here
  766. would be the only thing setting its mode and would silently override that
  767. design. On such a host the gateway and a hostUsers CLI share one
  768. ``$HERMES_HOME`` through the hermes group, so a 0700 profile created by
  769. whichever ran first locks the other out of the browser entirely.
  770. Omitting the explicit mode there lets the inherited setgid + umask decide,
  771. matching ``ensure_hermes_home``'s managed branch.
  772. Reconciling unconditionally also heals a profile an older Hermes left at
  773. 0755, which is the whole point — the exposure is on disk already. It is
  774. safe against a *running* browser: only group/other bits are dropped, the
  775. owner keeps ``rwx``, and POSIX checks the mode at ``open()`` rather than
  776. on already-open descriptors, so an attached Chromium keeps reading and
  777. writing its profile. On Windows POSIX mode bits are advisory (``chmod``
  778. only toggles the read-only flag), so this is best-effort there.
  779. """
  780. if _managed_install():
  781. # Managed mode: the NixOS-configured umask/setgid owns the mode, and
  782. # _secure_dir would no-op here anyway.
  783. os.makedirs(data_dir, exist_ok=True)
  784. return
  785. os.makedirs(data_dir, mode=0o700, exist_ok=True)
  786. try:
  787. from hermes_cli.config import _secure_dir
  788. _secure_dir(data_dir)
  789. except Exception as exc: # pragma: no cover - defensive
  790. logger.debug("browser debug launch: profile dir chmod skipped: %s", exc)
  791. def _open_launch_stderr_log(path: str):
  792. """Open the launch stderr log owner-only (0600), truncating as before.
  793. Opened with a plain ``open(path, "wb")`` this lands 0644 under a default
  794. umask — a fixed, guessable name inside the profile dir hardened just
  795. above. Under ``HERMES_HOME_MODE=0701`` the directory is traversable but
  796. unlistable, so a predictable filename is exactly the case that stays
  797. reachable; the uuid-named files elsewhere in the profile do not.
  798. Two halves, covering different installs:
  799. * **At creation** the mode is passed to ``os.open``, so the file is never
  800. briefly group/other-readable. ``O_TRUNC`` keeps the existing
  801. per-candidate overwrite semantics.
  802. * **On an already-existing log** ``O_CREAT`` applies ``mode`` only to a
  803. file it actually creates, so the inode keeps whatever it had. An older
  804. Hermes left this file at 0644 on disk, so creation-time hardening alone
  805. would leave every *upgrading* install exposed at the one path in this
  806. change with a guessable name. ``hermes_cli.config._secure_file``
  807. reconciles it, for the same reason ``_ensure_chrome_debug_data_dir``
  808. delegates to ``_secure_dir``: that helper is the single owner of the
  809. owner-only file policy — it skips managed/NixOS installs and containers
  810. and is where Windows ACL enforcement lands (#77527). Ordering: the
  811. reconcile runs *after* the truncating open and *before* any bytes are
  812. written, so the tighten lands while the file is empty.
  813. The managed/NixOS carve-out applies at creation here too — the same defect
  814. the profile directory had. This log is created lazily at runtime and is
  815. not covered by the module's ``systemd.tmpfiles`` rules; the gateway and an
  816. interactive ``hostUsers`` CLI share one ``$HERMES_HOME`` at two uids
  817. through the hermes group, and a 0600 log created by whichever ran first
  818. makes the other's truncating open fail with ``EACCES`` — and because every
  819. candidate binary reuses this one path, that fails *the whole launch*.
  820. There the inherited ``UMask = "0007"`` decides, like the merge base's
  821. plain ``open()``.
  822. """
  823. managed = _managed_install()
  824. # 0o666 rather than 0o600 on managed installs so the configured umask
  825. # decides, matching the merge base's plain open() and the carve-out
  826. # _ensure_chrome_debug_data_dir applies to the directory.
  827. create_mode = 0o666 if managed else 0o600
  828. flags = os.O_WRONLY | os.O_CREAT | os.O_TRUNC
  829. try:
  830. fd = os.open(path, flags, create_mode)
  831. except OSError:
  832. # Same fallback the pre-fix code had: let a genuinely unopenable path
  833. # surface to launch_chrome_debug's per-candidate handler.
  834. handle = open(path, "wb")
  835. else:
  836. handle = os.fdopen(fd, "wb")
  837. if not managed:
  838. try:
  839. from hermes_cli.config import _secure_file
  840. _secure_file(path)
  841. except Exception as exc: # pragma: no cover - defensive
  842. logger.debug("browser debug launch: stderr log chmod skipped: %s", exc)
  843. return handle
  844. def _chrome_debug_args(port: int) -> list[str]:
  845. return [f"--remote-debugging-port={port}", f"--user-data-dir={chrome_debug_data_dir()}",
  846. "--no-first-run", "--no-default-browser-check"]
  847. def _tcp_open(host: str, port: int, timeout: float) -> bool:
  848. try:
  849. with socket.create_connection((host, port), timeout=timeout):
  850. return True
  851. except OSError:
  852. return False
  853. def is_browser_debug_ready(url: str, timeout: float = 1.0) -> bool:
  854. """Return True when ``url`` exposes a reachable Chrome DevTools endpoint."""
  855. parsed = urllib.parse.urlparse(url if "://" in url else f"http://{url}")
  856. try:
  857. port = parsed.port or (443 if parsed.scheme in {"https", "wss"} else 80)
  858. except ValueError:
  859. return False
  860. if parsed.scheme in {"ws", "wss"} and parsed.path.startswith("/devtools/browser/"):
  861. return bool(parsed.hostname) and _tcp_open(parsed.hostname, port, timeout)
  862. scheme = {"ws": "http", "wss": "https"}.get(parsed.scheme, parsed.scheme)
  863. if scheme not in {"http", "https"} or not parsed.netloc:
  864. return False
  865. root = f"{scheme}://{parsed.netloc}".rstrip("/")
  866. # Loopback readiness must not route through getproxies() (env or macOS system proxy, #110565).
  867. handlers = [urllib.request.ProxyHandler({})] if is_loopback_host(parsed.hostname) else []
  868. opener = urllib.request.build_opener(*handlers)
  869. for probe in (f"{root}/json/version", f"{root}/json"):
  870. try:
  871. with opener.open(probe, timeout=timeout) as resp:
  872. if 200 <= getattr(resp, "status", 200) < 300:
  873. return True
  874. except Exception:
  875. continue
  876. return False
  877. # Both loopback literals, IPv4 FIRST: Windows (and some Linux setups) can hand each loopback
  878. # to a different process — Chrome asked to bind :9222 while VS Code's js-debug holds
  879. # 127.0.0.1:9222 comes up on [::1]:9222 only, invisible to an IPv4-only probe.
  880. _LOOPBACK_PROBE_HOSTS = ("127.0.0.1", "[::1]")
  881. _LOOPBACK_SOCKET_HOSTS = ("127.0.0.1", "::1")
  882. def discover_local_cdp_url(port: int, timeout: float = 1.0) -> str | None:
  883. """Return the first loopback URL (IPv4 first, then IPv6) speaking CDP, else None."""
  884. urls = (f"http://{host}:{port}" for host in _LOOPBACK_PROBE_HOSTS)
  885. return next((url for url in urls if is_browser_debug_ready(url, timeout=timeout)), None)
  886. def local_port_in_use(port: int, timeout: float = 0.5) -> bool:
  887. """True when either loopback accepts TCP on ``port``. Used AFTER a failed CDP probe to tell
  888. "port is free, launch here" from "another application is squatting it; a launch would fight"."""
  889. return any(_tcp_open(host, port, timeout) for host in _LOOPBACK_SOCKET_HOSTS)
  890. def find_free_debug_port(preferred: int = DEFAULT_BROWSER_CDP_PORT, attempts: int = 10) -> int:
  891. """First port after ``preferred`` bindable on both loopbacks; ``preferred + 1`` if none binds
  892. (the launch then fails with a clear browser-side error instead of silently doing nothing)."""
  893. def bindable(family, host, port) -> bool:
  894. try:
  895. with socket.socket(family, socket.SOCK_STREAM) as sock:
  896. sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
  897. sock.bind((host, port))
  898. return True
  899. except OSError:
  900. return False
  901. loopbacks = ((socket.AF_INET, "127.0.0.1"), (socket.AF_INET6, "::1"))
  902. ports = range(preferred + 1, preferred + 1 + attempts)
  903. return next((p for p in ports if all(bindable(f, h, p) for f, h in loopbacks)), preferred + 1)
  904. def manual_chrome_debug_command(port: int = DEFAULT_BROWSER_CDP_PORT, system: str | None = None) -> str | None:
  905. system = system or platform.system()
  906. candidates = get_chrome_debug_candidates(system)
  907. if candidates:
  908. argv = [candidates[0], *_chrome_debug_args(port)]
  909. return subprocess.list2cmdline(argv) if system == "Windows" else shlex.join(argv)
  910. if system == "Darwin":
  911. return (f'open -a "Google Chrome" --args --remote-debugging-port={port} '
  912. f'--user-data-dir="{chrome_debug_data_dir()}" --no-first-run '
  913. "--no-default-browser-check")
  914. return None
  915. def _detach_kwargs(system: str) -> dict:
  916. if system != "Windows":
  917. # /browser connect launches the USER's debug browser: it must outlive this Hermes (the connection persists in
  918. # BROWSER_CDP_URL and a later session re-attaches to it), and it is never ours to stop.
  919. return {"start_new_session": True} # detached-spawn: ok — the user's browser, meant to outlive Hermes
  920. flags = (getattr(subprocess, "DETACHED_PROCESS", 0)
  921. | getattr(subprocess, "CREATE_NEW_PROCESS_GROUP", 0))
  922. return {"creationflags": flags} if flags else {}
  923. def _wait_for_browser_debug_ready_or_exit(
  924. proc: subprocess.Popen, port: int, timeout: float = 2.0, interval: float = 0.1) -> str:
  925. """Classify a launched browser as "ready", "exited" or "starting". The grace window only needs
  926. to catch a candidate that exits immediately; slower browsers may still finish starting later."""
  927. deadline = time.monotonic() + timeout
  928. while time.monotonic() < deadline:
  929. # Dual-stack: a squatter on the IPv4 loopback can push the browser to bind [::1] only.
  930. if discover_local_cdp_url(port, timeout=min(interval, 0.2)):
  931. return "ready"
  932. if proc.poll() is not None:
  933. return "exited"
  934. time.sleep(interval)
  935. return "starting"
  936. _LAUNCH_STDERR_LOG = "launch-stderr.log"
  937. _STDERR_TAIL_LIMIT = 2000
  938. @dataclass
  939. class LaunchAttempt:
  940. """Outcome of one candidate-binary launch attempt."""
  941. binary: str
  942. state: str # "ready" | "starting" | "exited" | "spawn-failed"
  943. returncode: int | None = None
  944. stderr_tail: str = ""
  945. @dataclass
  946. class ChromeDebugLaunch:
  947. """Result of ``launch_chrome_debug``: ``launched`` = a browser was spawned and is ready or
  948. still starting (NOT a guarantee the CDP port ever opens); ``attempts`` explains *why* not."""
  949. launched: bool = False
  950. attempts: list[LaunchAttempt] = field(default_factory=list)
  951. @property
  952. def hint(self) -> str | None:
  953. """Best user-facing explanation for a failed/soft launch, if any."""
  954. for attempt in self.attempts:
  955. if attempt.state == "exited" and attempt.returncode == 0:
  956. name = os.path.basename(attempt.binary)
  957. return (
  958. f"{name} exited immediately without opening the debug port — an already-running "
  959. f"{name} instance likely absorbed the launch (Chromium's single-instance "
  960. "behavior). Close ALL of its processes (including background/tray instances) "
  961. "and retry /browser connect.")
  962. for attempt in self.attempts:
  963. if attempt.state == "exited" and attempt.stderr_tail:
  964. return (
  965. f"{os.path.basename(attempt.binary)} exited before the debug port opened: "
  966. f"{attempt.stderr_tail.splitlines()[-1].strip()}")
  967. return None
  968. def _read_stderr_tail(path: str) -> str:
  969. try:
  970. with open(path, "rb") as fh:
  971. return fh.read()[-_STDERR_TAIL_LIMIT:].decode("utf-8", errors="replace").strip()
  972. except OSError:
  973. return ""
  974. def launch_chrome_debug(
  975. port: int = DEFAULT_BROWSER_CDP_PORT, system: str | None = None) -> ChromeDebugLaunch:
  976. """Launch a Chromium-family browser with remote debugging, trying each candidate in turn. One
  977. that exits before the CDP port opens (crash, singleton forward, bad profile dir) is logged with
  978. exit code + stderr tail and the next is tried."""
  979. system = system or platform.system()
  980. result = ChromeDebugLaunch()
  981. candidates = get_chrome_debug_candidates(system)
  982. if not candidates:
  983. logger.info("browser debug launch: no Chromium-family binary found (system=%s)", system)
  984. return result
  985. data_dir = chrome_debug_data_dir()
  986. _ensure_chrome_debug_data_dir(data_dir)
  987. stderr_path = os.path.join(data_dir, _LAUNCH_STDERR_LOG)
  988. for candidate in candidates:
  989. try:
  990. with _open_launch_stderr_log(stderr_path) as stderr_file:
  991. proc = subprocess.Popen(
  992. [candidate, *_chrome_debug_args(port)],
  993. stdout=subprocess.DEVNULL, stderr=stderr_file, **_detach_kwargs(system))
  994. except Exception as exc:
  995. result.attempts.append(LaunchAttempt(binary=candidate, state="spawn-failed"))
  996. logger.info("browser debug launch: failed to spawn %s: %s", candidate, exc)
  997. continue
  998. logger.info(
  999. "browser debug launch: spawned %s (pid=%s) with --remote-debugging-port=%d",
  1000. candidate, getattr(proc, "pid", None), port)
  1001. state = _wait_for_browser_debug_ready_or_exit(proc, port)
  1002. attempt = LaunchAttempt(binary=candidate, state=state)
  1003. result.attempts.append(attempt)
  1004. if state != "exited":
  1005. result.launched = True
  1006. return result
  1007. attempt.returncode = getattr(proc, "returncode", None)
  1008. attempt.stderr_tail = _read_stderr_tail(stderr_path)
  1009. logger.warning(
  1010. "browser debug launch: %s exited (code=%s) before port %d opened%s",
  1011. candidate, attempt.returncode, port,
  1012. f"; stderr tail: {attempt.stderr_tail}" if attempt.stderr_tail else "")
  1013. return result