managed_scope.py 7.5 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188
  1. """Managed scope — IT-pushed, user-immutable config & env layer.
  2. DISTINCT from ``hermes_cli.config.is_managed()`` / ``HERMES_MANAGED`` (a coarse package-manager
  3. write-lock that blocks all mutation); this layer injects specific immutable values. The two are
  4. independent and may coexist. v1 enforcement is filesystem permissions only (see
  5. ``docs/design/managed-scope.md`` §7); ``get_managed_dir()`` is the single seam for adding
  6. macOS / Windows native locations later.
  7. """
  8. from __future__ import annotations
  9. import copy
  10. import logging
  11. import os
  12. import threading
  13. from pathlib import Path
  14. from typing import Dict, Optional
  15. # Stale-module bridge: this module binds ``utils`` names at import time, so a fresh
  16. # import in a post-pull updater process (pre-handoff purge keeps root modules cached) dies
  17. # unless the stale ``utils`` is dropped first. See hermes_cli.stale_modules.
  18. from hermes_cli.stale_modules import drop_stale_root_modules
  19. drop_stale_root_modules()
  20. from utils import fast_safe_load, file_cache_version, file_signature # file_signature: bound for the bridge above
  21. logger = logging.getLogger(__name__)
  22. # POSIX default. Other-platform locations belong ONLY inside get_managed_dir().
  23. _DEFAULT_MANAGED_DIR = Path("/etc/hermes")
  24. _CACHE_LOCK = threading.Lock()
  25. # path_key -> (*file_cache_version, parsed)
  26. _CONFIG_CACHE: dict[str, tuple] = {}
  27. _ENV_CACHE: dict[str, tuple] = {}
  28. def _under_pytest() -> bool:
  29. """True inside the test suite: ignore the system ``/etc/hermes`` so a real managed scope on a
  30. dev/CI box can't leak policy into the suite. An explicit ``HERMES_MANAGED_DIR`` still wins."""
  31. return "PYTEST_CURRENT_TEST" in os.environ
  32. def get_managed_dir() -> Optional[Path]:
  33. """Resolve the managed-scope directory, or None when no scope is present.
  34. Priority: ``$HERMES_MANAGED_DIR`` (IT-only bootstrap override; never persisted to any .env;
  35. honored only when non-empty AND the directory exists), then ``/etc/hermes`` when it exists.
  36. A missing directory resolves to None — the common case, so it must be cheap + side-effect-free.
  37. """
  38. override = os.environ.get("HERMES_MANAGED_DIR", "").strip()
  39. if override:
  40. p = Path(override)
  41. elif _under_pytest():
  42. return None
  43. else:
  44. p = _DEFAULT_MANAGED_DIR
  45. return p if p.is_dir() else None
  46. def invalidate_managed_cache() -> None:
  47. """Drop cached managed config/env. For tests and post-edit reloads."""
  48. with _CACHE_LOCK:
  49. _CONFIG_CACHE.clear()
  50. _ENV_CACHE.clear()
  51. def _cached_read(path: Path, cache: dict[str, tuple], parse):
  52. """Shared stat-signature-keyed read; returns a deepcopy of the parsed value.
  53. ``None`` when the file is absent or fails to parse (fail-open). A parse failure is logged
  54. LOUDLY — the admin needs to know their policy isn't applied — but never raises, so a malformed
  55. managed file can't brick startup.
  56. """
  57. try:
  58. st = path.stat()
  59. except OSError:
  60. return None # absent
  61. key = file_cache_version(path, st)
  62. path_key = str(path)
  63. with _CACHE_LOCK:
  64. hit = cache.get(path_key)
  65. if hit is not None and hit[:len(key)] == key:
  66. return copy.deepcopy(hit[len(key)])
  67. try:
  68. parsed = parse(path)
  69. except Exception as exc:
  70. logger.warning(
  71. "managed scope: failed to parse %s: %s — IGNORING this managed file. "
  72. "Admin policy from this file is NOT being applied. Fix and restart.",
  73. path, exc)
  74. return None
  75. with _CACHE_LOCK:
  76. cache[path_key] = (*key, copy.deepcopy(parsed))
  77. return parsed
  78. def _load_managed_file(name: str, cache: dict[str, tuple], parse) -> dict:
  79. managed_dir = get_managed_dir()
  80. if managed_dir is None:
  81. return {}
  82. parsed = _cached_read(managed_dir / name, cache, parse)
  83. return parsed if isinstance(parsed, dict) else {}
  84. def load_managed_config() -> dict:
  85. """Parsed managed config.yaml, or {} when absent/malformed (fail-open). Always {} under a config
  86. backend that takes config and locks from elsewhere (remote mode, D18; boot warns about the file)."""
  87. from hermes_cli.config_backend import get_config_backend
  88. if not get_config_backend().honors_managed_config():
  89. return {}
  90. return _load_managed_file("config.yaml", _CONFIG_CACHE, lambda p: fast_safe_load(p.read_text(encoding="utf-8-sig")) or {})
  91. def load_managed_env() -> dict[str, str]:
  92. """Parsed managed .env (KEY=VALUE), or {} when absent (fail-open)."""
  93. return _load_managed_file(".env", _ENV_CACHE, _parse_managed_env)
  94. def _parse_managed_env(path: Path) -> dict[str, str]:
  95. from agent.secret_scope import load_env_file
  96. path.read_text(encoding="utf-8-sig") # load_env_file swallows decode errors; an admin file must fail LOUD
  97. return load_env_file(path)
  98. def apply_managed_overlay(config: dict) -> dict:
  99. """Overlay administrator-pinned config values on top of an already-built dict.
  100. ``${VAR}`` refs in the managed config expand against the PROCESS env only, so a user cannot
  101. shadow a managed literal via a ref they control; a bare root ``model: x/y`` string is promoted
  102. to ``model.default`` so it can't clobber the dict shape callers expect; managed values
  103. deep-merge ON TOP per leaf while sibling keys stay user-controlled. Fail-open: returns
  104. ``config`` unchanged when no scope is present or on any error. Mutates and returns ``config``.
  105. """
  106. try:
  107. managed = load_managed_config()
  108. if not managed:
  109. return config
  110. # Imported lazily to avoid an import cycle (config imports managed_scope).
  111. from hermes_cli.config import _deep_merge, _expand_env_vars, _normalize_root_model_keys
  112. managed_expanded = _normalize_root_model_keys(_expand_env_vars(managed))
  113. # _normalize_root_model_keys only promotes the string when root provider/base_url
  114. # keys exist to migrate; handle the bare case here (matches cli.py) so _deep_merge
  115. # never replaces the caller's ``model`` dict with a string.
  116. if isinstance(managed_expanded.get("model"), str):
  117. managed_expanded = dict(managed_expanded)
  118. managed_expanded["model"] = {"default": managed_expanded["model"]}
  119. return _deep_merge(config, managed_expanded)
  120. except Exception:
  121. logger.warning("managed scope: failed to apply config overlay", exc_info=True)
  122. return config
  123. def _flatten_keys(d: dict, prefix: str = "") -> set:
  124. keys: set = set()
  125. for k, v in d.items():
  126. dotted = f"{prefix}.{k}" if prefix else str(k)
  127. if isinstance(v, dict) and v:
  128. keys |= _flatten_keys(v, dotted)
  129. else:
  130. keys.add(dotted)
  131. return keys
  132. def managed_config_keys() -> set:
  133. """Dotted leaf keys pinned by the managed config (e.g. {'model.default'})."""
  134. return _flatten_keys(load_managed_config())
  135. def is_key_managed(dotted_key: str) -> bool:
  136. """True if the exact dotted config key is pinned by the managed layer."""
  137. return dotted_key in managed_config_keys()
  138. def is_env_managed(name: str) -> bool:
  139. """True if the env var name is pinned by the managed .env layer."""
  140. return name in load_managed_env()
  141. def pinned_terminal_backend() -> Optional[str]:
  142. """The non-empty ``terminal.backend`` the managed config pins, or None. An empty or null value
  143. names no backend to run, so it pins nothing."""
  144. terminal = apply_managed_overlay({}).get("terminal")
  145. backend = terminal.get("backend") if isinstance(terminal, dict) else None
  146. return (backend.strip() or None) if isinstance(backend, str) else None