macos_tcc_anchor.py 13 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367
  1. """Stable macOS TCC anchor for the uv-managed Python interpreter.
  2. macOS TCC grants are keyed to the interpreter binary's path; a venv ``bin/python`` that symlinks
  3. into uv's store changes identity on every interpreter upgrade. The anchor replaces it with a
  4. signed real-file copy, gated on a real boot, with uv's alias names (``python3``,
  5. ``python3.N``) materialized as real-file copies too (never symlinks — the #95541 crash shape)
  6. and the store's ``libpython*`` hardlinked into ``venv/lib/`` (existing ``LC_RPATH`` already points
  7. at ``@executable_path/../lib``). All functions are no-ops off macOS and for non-uv interpreters,
  8. and never raise to callers.
  9. """
  10. from __future__ import annotations
  11. import contextlib
  12. import errno
  13. import logging
  14. import os
  15. import platform
  16. import re
  17. import shutil
  18. import subprocess
  19. import sys
  20. import tempfile
  21. from pathlib import Path
  22. from pm.environments import venv_python
  23. from utils import atomic_write_text
  24. logger = logging.getLogger(__name__)
  25. _MARKER_NAME = ".tcc-anchor-source"
  26. _STORE_COMMON_MARKERS = ("cpython-", "-macos-")
  27. # Recognize both historical interpreter locations during upgrades.
  28. _STORE_ROOT_MARKERS = ("/uv/python/", "/.hermes-runtime/python/")
  29. _ALIAS_NAMES = ("python3", f"python3.{sys.version_info.minor}")
  30. _STORE_BIN_NAMES = (f"python3.{sys.version_info.minor}", "python3", "python")
  31. class _BootGateFailed(Exception):
  32. """Staged copy refused to boot; the live venv must stay untouched."""
  33. def _marker_value(source_file: Path) -> str:
  34. """Fully resolved so symlinked spellings of the same store binary compare equal."""
  35. return os.path.realpath(str(source_file))
  36. def is_macos() -> bool:
  37. return platform.system() == "Darwin"
  38. def _is_uv_macos_store(path: str) -> bool:
  39. normalized = path.replace("\\", "/")
  40. if not all(marker in normalized for marker in _STORE_COMMON_MARKERS):
  41. return False
  42. return any(marker in normalized for marker in _STORE_ROOT_MARKERS)
  43. def _venv_dir(project_root: Path | None = None) -> Path | None:
  44. root = Path(project_root) if project_root is not None else Path(__file__).resolve().parents[1]
  45. return next((root / n for n in ("venv", ".venv") if _present(venv_python(root / n))), None)
  46. def _present(path: Path) -> bool:
  47. return path.is_file() or path.is_symlink()
  48. def _interpreter_file(src: str | Path) -> Path | None:
  49. """Return the interpreter binary file at/inside *src*."""
  50. p = Path(src)
  51. if p.is_file():
  52. return p
  53. if not p.is_dir():
  54. return None
  55. try:
  56. candidates = [p / n for n in _STORE_BIN_NAMES] + sorted(
  57. c for c in p.glob("python3.*") if not c.name.endswith((".dSYM", ".txt"))
  58. )
  59. return next((c for c in candidates if c.is_file()), None)
  60. except OSError:
  61. return None
  62. def _interpreter_source(venv_dir: Path) -> str | None:
  63. """Return the interpreter file the venv currently resolves to (symlink target or pyvenv.cfg home)."""
  64. venv_py = venv_python(venv_dir)
  65. if venv_py.is_symlink():
  66. try:
  67. return str(venv_py.resolve(strict=False))
  68. except OSError:
  69. return None
  70. cfg = venv_dir / "pyvenv.cfg"
  71. if not cfg.is_file():
  72. return None
  73. try:
  74. lines = cfg.read_text(encoding="utf-8-sig").splitlines()
  75. except OSError:
  76. return None
  77. home = next((l.partition("=")[2].strip() for l in lines if l.lower().startswith("home")), "")
  78. interp = _interpreter_file(home) if home else None
  79. return str(interp) if interp is not None else None
  80. def _managed_venv(project_root: Path | None) -> tuple[Path, Path, str] | str:
  81. """``(venv_dir, venv_py, source)`` for a uv-managed macOS venv, else the skip reason."""
  82. if not is_macos():
  83. return "not macOS"
  84. venv_dir = _venv_dir(project_root)
  85. if venv_dir is None:
  86. return "no venv interpreter"
  87. source = _interpreter_source(venv_dir)
  88. if source is None or not _is_uv_macos_store(source):
  89. return "interpreter not uv-managed (stable path)"
  90. return venv_dir, venv_python(venv_dir), source
  91. def _anchor_marker(venv_bin: Path) -> Path:
  92. return venv_bin / _MARKER_NAME
  93. def _marker_matches(venv_bin: Path, expected: str) -> bool:
  94. marker = _anchor_marker(venv_bin)
  95. try:
  96. return marker.is_file() and marker.read_text(encoding="utf-8-sig").strip() == expected
  97. except OSError:
  98. return False
  99. def _write_marker(venv_bin: Path, source_file: Path) -> None:
  100. """Atomic: a concurrent ensure (update + doctor --fix) must never read a torn marker, which
  101. would compare unequal and trigger a spurious reinstall."""
  102. atomic_write_text(
  103. _anchor_marker(venv_bin),
  104. _marker_value(source_file),
  105. tmp_prefix=f"{_MARKER_NAME}.",
  106. )
  107. def _store_root(source_file: Path) -> Path:
  108. # .../cpython-<ver>-macos-*/bin/python3.N → store root
  109. return source_file.resolve(strict=False).parent.parent
  110. def _provision_libpython(venv_dir: Path, source_file: Path, *, refresh: bool = False) -> None:
  111. """Hardlink (else copy) store ``libpython*`` into ``venv/lib/``.
  112. Provision-if-present: a surplus hardlink on a statically-linked build is free; a missed
  113. detection is the only way the dylib-not-found crash returns.
  114. See #95425.
  115. """
  116. src_lib = _store_root(source_file) / "lib"
  117. if not src_lib.is_dir():
  118. return
  119. dst_lib = venv_dir / "lib"
  120. try:
  121. dst_lib.mkdir(parents=True, exist_ok=True)
  122. for src in src_lib.glob("libpython*"):
  123. if not src.is_file():
  124. continue
  125. dst = dst_lib / src.name
  126. if dst.exists() or dst.is_symlink():
  127. if not refresh:
  128. continue
  129. try:
  130. dst.unlink()
  131. except OSError:
  132. continue
  133. try:
  134. os.link(src, dst)
  135. except OSError:
  136. try:
  137. shutil.copy2(src, dst)
  138. except OSError:
  139. logger.debug("libpython provision failed for %s", src, exc_info=True)
  140. except OSError:
  141. logger.debug("libpython provision skipped", exc_info=True)
  142. def _stage_copy(venv_bin: Path, prefix: str, source: Path) -> Path:
  143. """Copy *source* to a unique (mkstemp) executable staging file in *venv_bin*.
  144. Unique names mean a concurrent ensure cannot promote another run's truncated interim copy.
  145. """
  146. fd, tmp_name = tempfile.mkstemp(prefix=prefix, dir=str(venv_bin))
  147. os.close(fd)
  148. tmp_path = Path(tmp_name)
  149. try:
  150. shutil.copy2(source, tmp_path)
  151. os.chmod(tmp_path, source.stat().st_mode | 0o111)
  152. except BaseException:
  153. _discard(tmp_path)
  154. raise
  155. return tmp_path
  156. def _discard(tmp_path: Path | None) -> None:
  157. if tmp_path is not None:
  158. with contextlib.suppress(OSError):
  159. tmp_path.unlink(missing_ok=True)
  160. def _copy_alias(venv_bin: Path, name: str, anchor: Path) -> bool:
  161. """Materialize *name* as a real-file copy of *anchor* (atomic rename).
  162. Returns False (and warns) on failure: a leftover alias *symlink* to the anchor is the exact
  163. crash shape, so callers must know when the alias set is incomplete.
  164. """
  165. tmp_path: Path | None = None
  166. try:
  167. tmp_path = _stage_copy(venv_bin, f".{name}.tcc-", anchor)
  168. os.replace(tmp_path, venv_bin / name)
  169. return True
  170. except OSError as exc:
  171. logger.warning("TCC anchor alias %s not materialized: %s", name, exc)
  172. _discard(tmp_path)
  173. return False
  174. def _materialize_aliases(venv_bin: Path, anchor: Path, *, refresh: bool = False) -> bool:
  175. """Materialize uv alias names as real-file copies; True only if every needed one succeeded."""
  176. names = set(_ALIAS_NAMES)
  177. try:
  178. names.update(
  179. p.name for p in venv_bin.glob("python3*") if re.fullmatch(r"python3(\.\d+)?", p.name)
  180. )
  181. except OSError:
  182. pass
  183. ok = True
  184. for name in sorted(names):
  185. alias = venv_bin / name
  186. try:
  187. if refresh or alias.is_symlink() or not alias.exists():
  188. ok = _copy_alias(venv_bin, name, anchor) and ok
  189. except OSError:
  190. ok = False
  191. return ok
  192. def _passes_boot_gate(staged: Path, venv_dir: Path) -> bool:
  193. """Launch *staged* and demand encodings + the venv prefix.
  194. Runs with ``PYTHONHOME``/``PYTHONPATH`` scrubbed: an inherited PYTHONHOME papers over the very
  195. prefix failure this gate exists to catch. ``ENOENT``/``ENOEXEC`` (fixture binaries, foreign
  196. arch) mean the binary can't run here at all, so the symlinked venv was equally dead: skip.
  197. Anything else (notably ``EACCES`` after our own chmod) is a broken install going live: refuse.
  198. """
  199. env = {
  200. k: v
  201. for k, v in os.environ.items()
  202. if k not in ("PYTHONHOME", "PYTHONPATH", "PYTHONSTARTUP", "__PYVENV_LAUNCHER__")
  203. }
  204. try:
  205. proc = subprocess.run(
  206. [str(staged), "-c", "import encodings, sys; print(sys.prefix)"],
  207. capture_output=True,
  208. text=True, encoding="utf-8", errors="replace",
  209. timeout=30,
  210. env=env,
  211. check=False,
  212. )
  213. except OSError as exc:
  214. if exc.errno in (errno.ENOENT, errno.ENOEXEC):
  215. logger.debug("boot gate skipped: cannot execute %s (%s)", staged, exc)
  216. return True
  217. logger.warning("boot gate: staged copy not executable: %s", exc)
  218. return False
  219. except subprocess.TimeoutExpired:
  220. return False
  221. if proc.returncode != 0:
  222. return False
  223. printed = (proc.stdout or "").strip().splitlines()
  224. if not printed:
  225. return False
  226. try:
  227. return Path(printed[-1]).resolve() == venv_dir.resolve()
  228. except OSError:
  229. return str(venv_dir) in printed[-1]
  230. def _install_anchor(venv_dir: Path, source_file: Path) -> None:
  231. """Replace ``bin/python`` with a signed copy, gated on a real boot."""
  232. from hermes_cli.macos_signing import sign_managed_python
  233. venv_py = venv_python(venv_dir)
  234. venv_bin = venv_py.parent
  235. venv_bin.mkdir(parents=True, exist_ok=True)
  236. _provision_libpython(venv_dir, source_file, refresh=True)
  237. tmp_path = _stage_copy(venv_bin, ".python-tcc-", source_file)
  238. try:
  239. try:
  240. sign_managed_python(tmp_path)
  241. except Exception: # pragma: no cover - never block the anchor
  242. logger.debug("anchor copy signing skipped", exc_info=True)
  243. if not _passes_boot_gate(tmp_path, venv_dir):
  244. raise _BootGateFailed(f"staged copy at {tmp_path} failed encodings/prefix probe")
  245. os.replace(tmp_path, venv_py)
  246. if _materialize_aliases(venv_bin, venv_py, refresh=True):
  247. # Marker last, atomically: it asserts the WHOLE layout (anchor + aliases) is complete.
  248. # A partial alias set must not read "active" in doctor; an absent marker makes the
  249. # next ensure retry the install.
  250. _write_marker(venv_bin, source_file)
  251. else:
  252. logger.warning(
  253. "TCC anchor installed but alias materialization was "
  254. "incomplete; leaving anchor unmarked so the next run retries"
  255. )
  256. except Exception:
  257. _discard(tmp_path)
  258. raise
  259. def ensure_tcc_anchor(project_root: Path | None = None) -> Path | None:
  260. """Pin a dylib-complete interpreter anchor for macOS TCC.
  261. No-op (None) on non-macOS, without a venv interpreter, or when the interpreter is not
  262. uv-managed. Idempotent. Best-effort — None (and logs) if the copy or boot-gate fails; callers
  263. must never depend on success.
  264. See #95596.
  265. """
  266. found = _managed_venv(project_root)
  267. if isinstance(found, str):
  268. return None
  269. venv_dir, venv_py, source = found
  270. source_file = _interpreter_file(source)
  271. if source_file is None:
  272. return None
  273. if not venv_py.is_symlink() and _marker_matches(venv_py.parent, _marker_value(source_file)):
  274. try:
  275. _provision_libpython(venv_dir, source_file, refresh=False)
  276. if _passes_boot_gate(venv_py, venv_dir):
  277. _materialize_aliases(venv_py.parent, venv_py)
  278. return venv_py
  279. except OSError:
  280. pass
  281. try:
  282. _install_anchor(venv_dir, source_file)
  283. except _BootGateFailed as exc:
  284. logger.warning("macOS TCC anchor boot-gate refused install: %s", exc)
  285. return None
  286. except Exception as exc: # best-effort: never break update/doctor
  287. logger.warning("macOS TCC anchor install failed: %s", exc)
  288. return None
  289. return venv_py
  290. def tcc_anchor_state(project_root: Path | None = None) -> tuple[str, str]:
  291. """Report the anchor state for ``hermes doctor`` as ``(status, detail)``.
  292. ``skip`` = not applicable; ``active`` = pinned at a stable real-file anchor; ``stale`` = pinned
  293. but the interpreter changed since the last copy; ``missing`` = uv-managed with no anchor.
  294. """
  295. found = _managed_venv(project_root)
  296. if isinstance(found, str):
  297. return "skip", found
  298. _venv, venv_py, source = found
  299. if venv_py.is_symlink():
  300. return "missing", str(venv_py)
  301. source_file = _interpreter_file(source)
  302. expected = _marker_value(source_file) if source_file is not None else source
  303. status = "active" if _marker_matches(venv_py.parent, expected) else "stale"
  304. return status, str(venv_py)