base.py 11 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256
  1. """Secret-source contract: the ABC every secret backend implements.
  2. A *secret source* resolves credentials from an external secret manager into
  3. env-var-shaped values at process startup, AFTER ``~/.hermes/.env`` has loaded
  4. and BEFORE the rest of Hermes reads ``os.environ``. The contract is deliberately
  5. narrow: read-only; startup-time and synchronous (one ``fetch()`` per process per
  6. HERMES_HOME, under a registry-enforced wall-clock timeout, no background
  7. refreshers); never raises, never prompts (errors go in ``FetchResult.error``
  8. with an :class:`ErrorKind`; interactive auth belongs in the CLI ``setup`` flow);
  9. sources fetch, the orchestrator (``registry.apply_all``) applies.
  10. ``SECRET_SOURCE_API_VERSION`` gates plugin compatibility: additive optional
  11. hooks with defaults do NOT bump it; required-signature changes do.
  12. """
  13. from __future__ import annotations
  14. import os
  15. import re
  16. import subprocess
  17. from abc import ABC, abstractmethod
  18. from contextvars import ContextVar, Token
  19. from dataclasses import dataclass, field
  20. from enum import Enum
  21. from pathlib import Path
  22. from typing import Any, Dict, FrozenSet, List, MutableMapping, Optional, Sequence, Tuple
  23. SECRET_SOURCE_API_VERSION = 1
  24. # Generous: a first run may include a one-time CLI auto-install (bws download).
  25. DEFAULT_FETCH_TIMEOUT_SECONDS = 120.0
  26. DEFAULT_CLI_TIMEOUT_SECONDS = 30.0
  27. _SOURCE_ENVIRONMENT: ContextVar[Optional[MutableMapping[str, str]]]
  28. _SOURCE_ENVIRONMENT = ContextVar("hermes_secret_source_environment", default=None)
  29. def set_source_environment(environ: MutableMapping[str, str]) -> Token:
  30. """Install a per-fetch environment view without changing ``os.environ``."""
  31. return _SOURCE_ENVIRONMENT.set(environ)
  32. def reset_source_environment(token: Token) -> None:
  33. _SOURCE_ENVIRONMENT.reset(token)
  34. def get_source_environment() -> MutableMapping[str, str]:
  35. """Return the active per-fetch environment, or the process environment."""
  36. environ = _SOURCE_ENVIRONMENT.get()
  37. return environ if environ is not None else os.environ
  38. def source_child_env() -> dict[str, str]:
  39. """Environment for a helper child that legitimately needs the caller's env:
  40. full process env (minus the terminal blocklist) in single-profile startup;
  41. ONLY the per-fetch view under multiplex, so no sibling profile's secrets leak."""
  42. source_env = get_source_environment()
  43. if source_env is os.environ:
  44. from tools.environments.local import build_subprocess_env
  45. return build_subprocess_env(scrub_secrets=False, inherit_profile_home=False)
  46. return dict(source_env)
  47. class ErrorKind(str, Enum):
  48. """Failure taxonomy for :class:`FetchResult.error`; lets the orchestrator apply
  49. kind-dependent policy once (stale-cache fallback on NETWORK/TIMEOUT, never AUTH_FAILED)."""
  50. NOT_CONFIGURED = "not_configured" # enabled but missing token/project/map
  51. BINARY_MISSING = "binary_missing" # helper CLI not found / not installed
  52. AUTH_FAILED = "auth_failed" # bad credentials
  53. AUTH_EXPIRED = "auth_expired" # credentials were valid, aren't now
  54. REF_INVALID = "ref_invalid" # a secret reference failed validation
  55. NETWORK = "network" # transport-level failure
  56. EMPTY_VALUE = "empty_value" # backend returned nothing for a ref
  57. TIMEOUT = "timeout" # fetch exceeded its wall-clock budget
  58. INTERNAL = "internal" # anything else (bug, unexpected shape)
  59. # Ordered (kind, substrings) rules for mapping CLI failure text onto ErrorKind;
  60. # first rule whose substring appears (case-insensitive) wins.
  61. ErrorRules = Sequence[tuple[ErrorKind, Sequence[str]]]
  62. def classify_cli_error(message: str, rules: ErrorRules) -> ErrorKind:
  63. """Best-effort mapping of helper-CLI failure text onto the taxonomy."""
  64. lowered = message.lower()
  65. for kind, tokens in rules:
  66. if any(tok in lowered for tok in tokens):
  67. return kind
  68. return ErrorKind.INTERNAL
  69. def coerce_float(value: Any, default: float) -> float:
  70. """``float(value)`` with ``default`` for malformed config values."""
  71. try:
  72. return float(value)
  73. except (TypeError, ValueError):
  74. return default
  75. @dataclass
  76. class FetchResult:
  77. """Outcome of one source's fetch. ``secrets`` is what the source *would*
  78. contribute; ``applied``/``skipped`` serve the legacy fetch-and-apply entry
  79. points and stay empty in ``fetch()``."""
  80. secrets: dict[str, str] = field(default_factory=dict)
  81. applied: list[str] = field(default_factory=list)
  82. skipped: list[str] = field(default_factory=list)
  83. warnings: list[str] = field(default_factory=list)
  84. error: Optional[str] = None
  85. error_kind: Optional[ErrorKind] = None
  86. # Helper binary used (CLI-driven sources); surfaced by status commands.
  87. binary_path: Optional[Path] = None
  88. @property
  89. def ok(self) -> bool:
  90. return self.error is None
  91. def fail(self, error: str, kind: ErrorKind) -> FetchResult:
  92. self.error, self.error_kind = error, kind
  93. return self
  94. _GENERIC_REMEDIATION = {
  95. ErrorKind.NOT_CONFIGURED: "Run `hermes secrets {name} setup` to finish configuration.",
  96. ErrorKind.BINARY_MISSING: "Run `hermes secrets {name} setup` to install the helper CLI.",
  97. ErrorKind.AUTH_FAILED: "Credentials rejected — run `hermes secrets {name} setup` to re-authenticate.",
  98. ErrorKind.AUTH_EXPIRED: "Credentials expired — run `hermes secrets {name} setup` to re-authenticate.",
  99. ErrorKind.NETWORK: "Network problem reaching the secrets backend — check connectivity and retry.",
  100. ErrorKind.TIMEOUT: "Backend was slow — raise secrets.{name}.timeout_seconds if this recurs.",
  101. }
  102. class SecretSource(ABC):
  103. """One external secret backend. Subclasses set attributes + ``fetch``.
  104. ``name``: config-section key under ``secrets:`` (``[a-z0-9_]+``) and the
  105. provenance label. ``shape``: ``"mapped"`` (user binds env-var names to refs)
  106. or ``"bulk"`` (backend injects whole projects); mapped beats bulk because an
  107. explicit binding is stronger intent. ``scheme``: URI scheme this source owns
  108. for refs, unique across sources. ``token_env_key`` / ``default_token_env``:
  109. config key naming the bootstrap-auth env var and its default; drives
  110. :meth:`protected_env_vars` so a vault holding its own access token can't
  111. clobber the credential used to reach it. ``remediation_hints``: per-kind
  112. overrides of the generic remediation text (``{name}`` / ``{token_env}``).
  113. """
  114. api_version: int = SECRET_SOURCE_API_VERSION
  115. name: str = ""
  116. label: str = ""
  117. shape: str = "mapped" # "mapped" | "bulk"
  118. scheme: Optional[str] = None
  119. token_env_key: Optional[str] = None
  120. default_token_env: str = ""
  121. override_existing_default: bool = False
  122. remediation_hints: dict[ErrorKind, str] = {}
  123. @abstractmethod
  124. def fetch(self, cfg: dict, home_path: Path) -> FetchResult:
  125. """Resolve this source's secrets. MUST NOT raise or prompt; ``cfg`` is the
  126. raw ``secrets.<name>`` section and may be malformed."""
  127. def is_enabled(self, cfg: dict) -> bool:
  128. return bool(isinstance(cfg, dict) and cfg.get("enabled"))
  129. def override_existing(self, cfg: dict) -> bool:
  130. """May this source overwrite vars .env / the shell already set? Never extends
  131. to vars claimed by another source (a config error the orchestrator warns about)."""
  132. return bool(isinstance(cfg, dict)
  133. and cfg.get("override_existing", self.override_existing_default))
  134. def token_env(self, cfg: dict) -> str:
  135. """Name of the env var holding this source's bootstrap credential."""
  136. if isinstance(cfg, dict) and self.token_env_key:
  137. return str(cfg.get(self.token_env_key) or self.default_token_env)
  138. return self.default_token_env
  139. def protected_env_vars(self, cfg: dict) -> frozenset[str]:
  140. """Env vars the orchestrator must never let ANY source overwrite."""
  141. return frozenset({self.token_env(cfg)}) if self.token_env_key else frozenset()
  142. def fetch_timeout_seconds(self, cfg: dict) -> float:
  143. """Wall-clock budget the orchestrator enforces around fetch()."""
  144. val = coerce_float((cfg or {}).get("timeout_seconds", DEFAULT_FETCH_TIMEOUT_SECONDS),
  145. DEFAULT_FETCH_TIMEOUT_SECONDS)
  146. return val if val > 0 else DEFAULT_FETCH_TIMEOUT_SECONDS
  147. def config_schema(self) -> dict:
  148. """Informational ``{key: {"description": str, "default": Any}}`` for setup UIs."""
  149. return {}
  150. def remediation(self, kind: Optional[ErrorKind], cfg: dict) -> str:
  151. """One-line actionable next step for a failed fetch (pure); "" suppresses the hint."""
  152. if kind is None:
  153. return ""
  154. template = self.remediation_hints.get(kind) or _GENERIC_REMEDIATION.get(kind, "")
  155. return template.format(name=self.name, token_env=self.token_env(cfg))
  156. # --- Shared helpers — use these instead of hand-rolling per backend ---------
  157. _ENV_NAME_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
  158. # Deliberately NOT tools.ansi_strip.strip_ansi: the optional terminator here
  159. # also strips *unterminated* OSC sequences (a CLI killed mid-write), which
  160. # strip_ansi leaves untouched.
  161. _ANSI_RE = re.compile(r"\x1b(?:\[[0-9;?]*[ -/]*[@-~]|\][^\x07\x1b]*(?:\x07|\x1b\\)?)")
  162. def is_valid_env_name(name: str) -> bool:
  163. """True when ``name`` is a legal environment-variable name."""
  164. return bool(name) and bool(_ENV_NAME_RE.match(name))
  165. def scrub_ansi(text: str) -> str:
  166. """Strip ANSI escape sequences (whole CSI/OSC sequences, not just ESC)."""
  167. return _ANSI_RE.sub("", text or "")
  168. def run_cli(argv: Sequence[str], *, env: dict[str, str], timeout: float, label: str,
  169. timeout_message: str, stdin: Any = subprocess.DEVNULL) -> subprocess.CompletedProcess:
  170. """``subprocess.run`` an argv list (never a shell), capturing utf-8 text; timeout
  171. and spawn failure become ``RuntimeError``. Callers own returncode interpretation."""
  172. try:
  173. return subprocess.run(
  174. list(argv), env=env, capture_output=True, text=True, encoding="utf-8", errors="replace",
  175. timeout=timeout, stdin=stdin,
  176. check=False,
  177. )
  178. except subprocess.TimeoutExpired as exc:
  179. raise RuntimeError(timeout_message) from exc
  180. except OSError as exc:
  181. raise RuntimeError(f"failed to invoke {label}: {exc}") from exc
  182. def run_secret_cli(argv: Sequence[str], *, allow_env: Sequence[str] = (), extra_env: Optional[dict[str, str]] = None,
  183. timeout: float = DEFAULT_CLI_TIMEOUT_SECONDS) -> subprocess.CompletedProcess:
  184. """Run a secret-manager helper CLI with a minimal, allowlisted env (never the
  185. full post-dotenv ``os.environ``): PATH/HOME/locale basics plus ``allow_env``
  186. and ``extra_env``. ``NO_COLOR=1`` + ANSI-scrubbed stderr; stdin is /dev/null so
  187. a prompting helper fails fast. Pass user refs AFTER a ``--`` terminator."""
  188. base_keep = ("PATH", "HOME", "USERPROFILE", "SYSTEMROOT", "TMPDIR", "TEMP",
  189. "LANG", "LC_ALL", "XDG_CONFIG_HOME", "XDG_DATA_HOME")
  190. env = {k: os.environ[k] for k in (*base_keep, *allow_env) if k in os.environ}
  191. if extra_env:
  192. env.update(extra_env)
  193. env.setdefault("NO_COLOR", "1")
  194. name = Path(str(argv[0])).name
  195. proc = run_cli(argv, env=env, timeout=timeout, label=name,
  196. timeout_message=f"{name} timed out after {timeout:.0f}s")
  197. proc.stdout = proc.stdout or ""
  198. proc.stderr = scrub_ansi(proc.stderr or "")
  199. return proc