install_state.py 19 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490
  1. """Has this OS user already used Hermes on this computer?
  2. The desktop's welcome trial goes only to a first install, once per OS user, so ``onboarding.start``
  3. asks this before it claims one. The answer is about the OS user, not the active profile: it looks at
  4. every Hermes root the machine names (default roots, channel and package roots, the roots gateway
  5. services and the ``hermes`` launcher point at) and at a marker file no Hermes setting can move.
  6. This is product gating, not security: the inference API's limits stop abuse. So it reads only small
  7. known files, never scans the disk, never writes into a Hermes root, and treats doubt as "used".
  8. """
  9. from __future__ import annotations
  10. import contextlib
  11. import enum
  12. import json
  13. import os
  14. import re
  15. import sqlite3
  16. import sys
  17. import threading
  18. from collections.abc import Callable, Iterable, Iterator
  19. from dataclasses import dataclass
  20. from functools import cache, cached_property
  21. from glob import glob
  22. from pathlib import Path
  23. from typing import Any
  24. _MAX_FILE_BYTES = 1 << 20
  25. class Evidence(enum.Enum):
  26. """Why the machine counts as used. For logs and tests; never shown to users."""
  27. MACHINE_MARKER = "machine-marker" # an earlier probe or trial claim on this machine
  28. ONBOARDING_DONE = "onboarding-done" # a root's config has ``onboarding.run: false``
  29. NAMED_PROFILE = "named-profile" # a live profile someone created
  30. PROVIDER_CONFIG = "provider-config" # config.yaml picks a provider other than auto
  31. PROVIDER_KEY = "provider-key" # .env holds a provider, tool, messaging or skill key
  32. PROVIDER_LOGIN = "provider-login" # auth.json / nous_auth.json holds a login or a guest
  33. MESSAGES = "messages" # state.db holds a message
  34. UNREADABLE = "unreadable" # a root we could not, or must not, read
  35. @dataclass(frozen=True, slots=True)
  36. class Finding:
  37. evidence: Evidence
  38. where: Path
  39. @dataclass(frozen=True, slots=True)
  40. class InstallState:
  41. findings: tuple[Finding, ...]
  42. @property
  43. def existing(self) -> bool:
  44. return bool(self.findings)
  45. @property
  46. def fresh(self) -> bool:
  47. return not self.findings
  48. Source = Callable[[], Iterable[Path]]
  49. @dataclass(frozen=True, slots=True)
  50. class Places:
  51. """Where to look. ``markers[0]`` is the marker this process writes; every entry is read."""
  52. markers: tuple[Path, ...]
  53. sources: tuple[Source, ...]
  54. protected: tuple[Path, ...] = ()
  55. @classmethod
  56. def of_this_machine(cls) -> Places:
  57. from hermes_platform.resolver import known_dirs
  58. return cls(
  59. markers=tuple(_expand_all(known_dirs.machine_marker_files())),
  60. sources=(_active_root, _home_globs, _shared_auth_dir, _registry_home, _service_homes, _launcher_root),
  61. protected=_protected_dirs(),
  62. )
  63. def machine_places() -> Places:
  64. """The seam tests replace; production always looks at the real machine."""
  65. return Places.of_this_machine()
  66. @cache
  67. def probe() -> InstallState:
  68. """One answer per process (the first finding wins). :func:`mark_machine_used` clears it."""
  69. places = machine_places()
  70. if marker := next((m for m in places.markers if m.is_file()), None):
  71. return InstallState((Finding(Evidence.MACHINE_MARKER, marker),))
  72. for root in candidate_roots(places):
  73. if finding := root_evidence(root, places):
  74. if finding.evidence is not Evidence.UNREADABLE: # doubt blocks the trial, never marks
  75. _write_marker({}, answer_moved=False) # this probe is the answer; nothing to recompute
  76. return InstallState((finding,))
  77. return InstallState(())
  78. def existing_install() -> bool:
  79. return probe().existing
  80. def mark_machine_used() -> None:
  81. """Record that this OS user has a used install, or just claimed the trial. Atomic, idempotent.
  82. Overwrites a reservation (:func:`reserve_trial`): a claim consumes it."""
  83. _write_marker({})
  84. _TRIAL_RESERVED = {"trial": "reserved"}
  85. # Covers a claim's checks, its mint (bounded by its own auth lock and HTTP timeouts) and the marker write.
  86. CLAIM_LOCK_TIMEOUT_SECONDS = 30.0
  87. _claim_lock_holder = threading.local()
  88. @contextlib.contextmanager
  89. def claim_lock() -> Iterator[None]:
  90. """One welcome-trial claim at a time for this OS user, whichever Hermes data root it runs from
  91. (stable and canary started together hold different auth locks). Beside the marker it guards, and
  92. taken before any auth lock."""
  93. places = machine_places()
  94. if not places.markers:
  95. yield
  96. return
  97. from hermes_cli.auth import _file_lock
  98. lock_path = places.markers[0].with_name(places.markers[0].name + ".lock")
  99. with _file_lock(lock_path, _claim_lock_holder, CLAIM_LOCK_TIMEOUT_SECONDS,
  100. f"Timed out waiting for the welcome-trial claim lock ({lock_path})"):
  101. yield
  102. def reserve_trial() -> None:
  103. """The first desktop boot found a fresh install: keep the trial for it, so a later use (a chat
  104. before onboarding ran, a key added) does not take it away. The marker also makes the probe read
  105. "used" from now on; :func:`trial_reserved` is what the claim checks instead."""
  106. _write_marker(_TRIAL_RESERVED)
  107. def trial_reserved() -> bool:
  108. return any(_read_marker(marker) == _TRIAL_RESERVED for marker in machine_places().markers)
  109. def _write_marker(content: dict[str, str], *, answer_moved: bool = True) -> None:
  110. places = machine_places()
  111. if places.markers:
  112. from utils import atomic_json_write
  113. marker = places.markers[0]
  114. marker.parent.mkdir(parents=True, exist_ok=True)
  115. atomic_json_write(marker, content) # unique temp name: two backends may mark at once
  116. probe.cache_clear()
  117. if answer_moved:
  118. from hermes_cli import onboarding_due
  119. onboarding_due.invalidate()
  120. def _read_marker(marker: Path) -> Any:
  121. try:
  122. return json.loads(_read_text(marker)) if marker.is_file() else None
  123. except (OSError, ValueError, UnicodeError):
  124. return None
  125. # ── where to look ─────────────────────────────────────────────────────────────────────────────
  126. def candidate_roots(places: Places) -> Iterator[Path]:
  127. """Each named root once, existing directories only. A root inside a protected folder is yielded
  128. unresolved: :func:`root_evidence` reports it without touching it."""
  129. seen: set[Path] = set()
  130. for source in places.sources:
  131. for raw in source():
  132. path = Path(os.path.abspath(os.path.expanduser(str(raw))))
  133. if not _is_protected(path, places):
  134. try:
  135. path = path.resolve()
  136. except OSError:
  137. continue
  138. if not path.is_dir():
  139. continue
  140. if path not in seen:
  141. seen.add(path)
  142. yield path
  143. def _is_protected(path: Path, places: Places) -> bool:
  144. return _inside(path, places.protected)
  145. def _inside(path: Path, dirs: Iterable[Path]) -> bool:
  146. return any(path == d or d in path.parents for d in dirs)
  147. def _protected_dirs() -> tuple[Path, ...]:
  148. from hermes_platform.resolver import known_dirs
  149. return tuple(_expand_all(known_dirs.mac_privacy_protected_dirs()))
  150. def _expand_all(patterns: Iterable[str]) -> Iterator[Path]:
  151. """Expand ``~`` and environment variables (``$X`` on POSIX, ``%X%`` on Windows), then globs. An
  152. entry naming an unset variable is dropped."""
  153. for pattern in patterns:
  154. expanded = os.path.expanduser(os.path.expandvars(pattern))
  155. if "$" in expanded or "%" in expanded:
  156. continue
  157. if any(ch in expanded for ch in "*?["):
  158. yield from (Path(hit) for hit in sorted(glob(expanded)))
  159. else:
  160. yield Path(expanded)
  161. def _active_root() -> Iterable[Path]:
  162. from hermes_constants import _get_platform_default_hermes_home, get_default_hermes_root
  163. return (get_default_hermes_root(), _get_platform_default_hermes_home())
  164. def _home_globs() -> Iterable[Path]:
  165. from hermes_platform.resolver import known_dirs
  166. return _expand_all(known_dirs.hermes_home_globs())
  167. def _shared_auth_dir() -> Iterable[Path]:
  168. raw = os.environ.get("HERMES_SHARED_AUTH_DIR", "").strip()
  169. return (Path(raw),) if raw else ()
  170. def _registry_home() -> Iterable[Path]:
  171. """The ``HERMES_HOME`` older Windows installers saved for the user (the desktop honours it)."""
  172. if sys.platform != "win32":
  173. return ()
  174. import winreg
  175. try:
  176. with winreg.OpenKey(winreg.HKEY_CURRENT_USER, "Environment") as key:
  177. value, _kind = winreg.QueryValueEx(key, "HERMES_HOME")
  178. except OSError:
  179. return ()
  180. return (Path(os.path.expandvars(str(value))),) if str(value).strip() else ()
  181. def _service_homes() -> Iterable[Path]:
  182. """The ``HERMES_HOME`` of every gateway service this OS user runs: its own definitions, the
  183. machine-wide units that run as it, and the launchers its Scheduled Tasks start. Another account's
  184. gateway is that account's install."""
  185. from hermes_cli import gateway_windows
  186. from hermes_platform.resolver import known_dirs
  187. for machine_wide, globs in ((False, known_dirs.gateway_service_definition_globs()),
  188. (True, known_dirs.system_gateway_service_definition_globs())):
  189. for definition in _expand_all(globs):
  190. yield from _definition_homes(definition, machine_wide=machine_wide)
  191. for launcher in gateway_windows.registered_task_launchers():
  192. yield from _definition_homes(Path(launcher), machine_wide=False, follow=False)
  193. def _definition_homes(definition: Path, *, machine_wide: bool, follow: bool = True) -> Iterator[Path]:
  194. """The homes one definition names, and those named by the launchers it starts (the Windows
  195. Startup-folder fallback names only its launcher). Unreadable: none."""
  196. from hermes_cli.gateway_runtime_service_identity import launcher_text
  197. from hermes_cli.gateway_service_owner import service_definition_homes, service_definition_launchers
  198. try:
  199. text = launcher_text(_read_bytes(definition))
  200. except (OSError, UnicodeError, ValueError):
  201. return
  202. account = _unit_account(text) or ("root" if machine_wide else None)
  203. if account is not None and not _is_this_account(account):
  204. return
  205. yield from (Path(home.strip().strip('"')) for home in service_definition_homes(text))
  206. if follow:
  207. for launcher in service_definition_launchers(text):
  208. yield from _definition_homes(Path(launcher), machine_wide=False, follow=False)
  209. def _unit_account(unit: str) -> str | None:
  210. """The account a systemd unit runs as (its last ``User=``), or None when it names none."""
  211. accounts = re.findall(r"^\s*User=\s*(\S+)\s*$", unit, flags=re.MULTILINE)
  212. return accounts[-1] if accounts else None
  213. def _is_this_account(account: str) -> bool:
  214. import pwd
  215. try:
  216. uid = int(account) if account.isdigit() else pwd.getpwnam(account).pw_uid
  217. except KeyError: # no such account: the unit cannot run as anyone here
  218. return False
  219. return uid == os.getuid() # windows-footgun: ok — only systemd units name a User=
  220. def _launcher_root() -> Iterable[Path]:
  221. """The root that owns the ``hermes`` on PATH: its launcher execs that root's ``tools/`` Python."""
  222. from hermes_cli._launchers import _launcher_python
  223. from hermes_platform.resolver import locate_command
  224. found = locate_command("hermes").command
  225. if not found:
  226. return ()
  227. protected = _protected_dirs()
  228. launcher = Path(os.path.abspath(found[0]))
  229. if not _inside(launcher, protected):
  230. launcher = launcher.resolve()
  231. if _inside(launcher, protected):
  232. return (launcher.parent,) # reading it would raise a macOS permission prompt; reported as unreadable
  233. python = _launcher_python(launcher)
  234. owners = [p.parent for p in (python.parents if python else ()) if p.name == "tools"]
  235. if not owners and launcher.parent.name == "bin" and launcher.parent.parent.name == ".hermes":
  236. owners = [launcher.parent.parent.parent.parent] # <root>/<checkout>/.hermes/bin/hermes
  237. return owners[:1]
  238. # ── what counts as used, per root ─────────────────────────────────────────────────────────────
  239. def root_evidence(root: Path, places: Places) -> Finding | None:
  240. if _is_protected(root, places):
  241. return Finding(Evidence.UNREADABLE, root)
  242. home = _Root(root, places.protected)
  243. for evidence, check in CHECKS:
  244. try:
  245. if check(home):
  246. return Finding(evidence, root)
  247. except (OSError, ValueError, UnicodeError, sqlite3.Error):
  248. return Finding(Evidence.UNREADABLE, root)
  249. return None
  250. class _Root:
  251. """One root's files, each read at most once. No ``load_config``: it writes SOUL.md and the
  252. directory skeleton into the root it reads."""
  253. def __init__(self, path: Path, protected: tuple[Path, ...] = ()) -> None:
  254. self.path = path
  255. self.protected = protected
  256. def file(self, name: str) -> Path:
  257. """*name* in this root, resolved before anything opens it. A link into a protected folder
  258. raises: following it would raise the macOS permission prompt, so it counts as unreadable."""
  259. return _unprotected(self.path / name, self.protected)
  260. @cached_property
  261. def config(self) -> dict[str, Any]:
  262. return _read_mapping(self.file("config.yaml"), _parse_yaml)
  263. @cached_property
  264. def auth_stores(self) -> tuple[dict[str, Any], ...]:
  265. # The shared-auth override names the directory itself, so its file sits at the top.
  266. names = ("auth.json", "shared/nous_auth.json", "nous_auth.json")
  267. return tuple(_read_mapping(self.file(name), json.loads) for name in names)
  268. def _unprotected(path: Path, protected: tuple[Path, ...]) -> Path:
  269. resolved = path.resolve()
  270. if _inside(resolved, protected):
  271. raise PermissionError(f"{path} leads into a protected folder")
  272. return resolved
  273. def _onboarding_done(home: _Root) -> bool:
  274. section = home.config.get("onboarding")
  275. return isinstance(section, dict) and section.get("run") is False
  276. def _named_profile(home: _Root) -> bool:
  277. from hermes_constants import PROFILE_ID_RE, named_profile_has_identity, named_profile_is_deleted
  278. profiles = home.file("profiles")
  279. if not profiles.is_dir():
  280. return False
  281. for entry in profiles.iterdir():
  282. if entry.name == "default" or not PROFILE_ID_RE.match(entry.name):
  283. continue
  284. entry = _unprotected(entry, home.protected)
  285. if entry.is_dir() and named_profile_has_identity(entry) and not named_profile_is_deleted(entry):
  286. return True
  287. return False
  288. def _provider_config(home: _Root) -> bool:
  289. model = home.config.get("model")
  290. provider = model.get("provider") if isinstance(model, dict) else None
  291. return isinstance(provider, str) and provider.strip() not in ("", "auto")
  292. # A deployment secret, not something a user entered.
  293. _IGNORED_ENV_KEYS = frozenset({"HERMES_ANON_API_SECRET"})
  294. _USER_ENV_CATEGORIES = frozenset({"provider", "tool", "messaging", "skill"})
  295. def _provider_key(home: _Root) -> bool:
  296. from hermes_cli.config_defaults import OPTIONAL_ENV_VARS
  297. from agent.secret_scope import load_env_file
  298. path = home.file(".env")
  299. if not path.is_file():
  300. return False
  301. _read_text(path) # too large or unreadable raises, so doubt counts as used; the tokenizer swallows both
  302. return any(value and key not in _IGNORED_ENV_KEYS
  303. and (OPTIONAL_ENV_VARS.get(key) or {}).get("category") in _USER_ENV_CATEGORIES
  304. for key, value in load_env_file(path).items())
  305. def _provider_login(home: _Root) -> bool:
  306. """A login, an active provider or a guest (only a connector action or a trial claim makes one),
  307. or a credential the user added by hand. Pool rows Hermes seeds on its own (shell env keys, other
  308. tools' CLI logins) prove nothing."""
  309. for store in home.auth_stores:
  310. providers = store.get("providers")
  311. if store.get("active_provider") or (isinstance(providers, dict) and any(providers.values())):
  312. return True
  313. if store.get("auth_method") or store.get("anon_token") or store.get("refresh_token"):
  314. return True # nous_auth.json holds one provider state at its top level
  315. pool = store.get("credential_pool")
  316. rows = (row for rows in (pool.values() if isinstance(pool, dict) else ()) if isinstance(rows, list)
  317. for row in rows if isinstance(row, dict))
  318. if any(str(row.get("source", "")).split(":", 1)[0] == "manual" for row in rows):
  319. return True
  320. return False
  321. _DB_BUSY_SECONDS = 1.0
  322. _DB_BUSY_ERRORS = frozenset({"SQLITE_BUSY", "SQLITE_LOCKED"})
  323. def _messages(home: _Root) -> bool:
  324. db = home.file("state.db")
  325. if not db.is_file():
  326. return False
  327. # Read-only URI, never the state registry: that opens a writer and migrates a schema we do not own.
  328. try:
  329. with contextlib.closing(sqlite3.connect(f"{db.as_uri()}?mode=ro", uri=True, timeout=_DB_BUSY_SECONDS)) as conn:
  330. if conn.execute("SELECT 1 FROM sqlite_master WHERE type='table' AND name='messages'").fetchone() is None:
  331. return False
  332. return conn.execute("SELECT 1 FROM messages LIMIT 1").fetchone() is not None
  333. except sqlite3.OperationalError as exc:
  334. # Still locked after sqlite's own retries: a first boot is creating or healing this database
  335. # right now. A lock is not a message, and reading it as "unreadable" would cost a new user the trial.
  336. if getattr(exc, "sqlite_errorname", "") in _DB_BUSY_ERRORS:
  337. return False
  338. raise
  339. CHECKS: tuple[tuple[Evidence, Callable[[_Root], bool]], ...] = (
  340. (Evidence.ONBOARDING_DONE, _onboarding_done),
  341. (Evidence.NAMED_PROFILE, _named_profile),
  342. (Evidence.PROVIDER_CONFIG, _provider_config),
  343. (Evidence.PROVIDER_KEY, _provider_key),
  344. (Evidence.PROVIDER_LOGIN, _provider_login),
  345. (Evidence.MESSAGES, _messages), # last: the only check that opens a database
  346. )
  347. # ── small readers ─────────────────────────────────────────────────────────────────────────────
  348. def _read_bytes(path: Path) -> bytes:
  349. if path.stat().st_size > _MAX_FILE_BYTES:
  350. raise ValueError(f"{path} is larger than {_MAX_FILE_BYTES} bytes")
  351. return path.read_bytes()
  352. def _read_text(path: Path) -> str:
  353. return _read_bytes(path).decode("utf-8-sig")
  354. def _read_mapping(path: Path, parse: Callable[[str], Any]) -> dict[str, Any]:
  355. if not path.is_file():
  356. return {}
  357. data = parse(_read_text(path))
  358. return data if isinstance(data, dict) else {}
  359. def _parse_yaml(text: str) -> Any:
  360. import hermes_yaml
  361. try:
  362. return hermes_yaml.safe_load(text)
  363. except hermes_yaml.YAMLError as exc:
  364. raise ValueError(str(exc)) from exc