_cache.py 7.5 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193
  1. """Shared cache substrate for external secret-source backends.
  2. Two-layer fetch cache (in-process + on-disk); the disk half writes atomically
  3. with ``0600`` permissions and honours a TTL, so that logic is audited in exactly
  4. one place. Each backend supplies only its cache-key shape and a serializer.
  5. The disk layer is strictly best-effort: a miss just triggers a refetch, because
  6. a cache problem must never block Hermes startup.
  7. """
  8. from __future__ import annotations
  9. import hashlib
  10. import json
  11. import time
  12. from contextlib import suppress
  13. from dataclasses import dataclass
  14. from pathlib import Path
  15. from typing import Callable, Dict, Generic, Optional, TypeVar
  16. from hermes_constants import secure_parent_dir
  17. from utils import atomic_json_write
  18. __all__ = [
  19. "CachedFetch",
  20. "DiskCache",
  21. "SecretCache",
  22. "atomic_write_json",
  23. "current_cache_path",
  24. "entry_from_payload",
  25. "fingerprint",
  26. "remove_cache_file",
  27. "resolve_cache_home",
  28. ]
  29. def fingerprint(material: str) -> str:
  30. """SHA-256 prefix used as a cache key — never logged, never displayed."""
  31. return hashlib.sha256(material.encode("utf-8")).hexdigest()[:16]
  32. @dataclass
  33. class CachedFetch:
  34. """A set of fetched secret values plus when they were fetched."""
  35. secrets: dict[str, str]
  36. fetched_at: float
  37. def is_fresh(self, ttl_seconds: float) -> bool:
  38. return ttl_seconds > 0 and (time.time() - self.fetched_at) < ttl_seconds
  39. def resolve_cache_home(home_path: Optional[Path] = None) -> Path:
  40. """``home_path`` as resolved by ``load_hermes_dotenv()``, else ``$HERMES_HOME``/``~/.hermes``."""
  41. if home_path is None:
  42. from hermes_constants import get_hermes_home
  43. home_path = get_hermes_home()
  44. return home_path
  45. def current_cache_path(home: Path, name: str) -> Path:
  46. """``<home>/<name>``. A copy at ``<home>/cache/<name>``, where earlier releases kept the secret
  47. caches, is deleted first without being read: the agent can write that folder."""
  48. with suppress(OSError):
  49. (home / "cache" / name).unlink()
  50. return home / name
  51. def remove_cache_file(home: Path, name: str) -> None:
  52. """Delete ``<home>/<name>`` and an old ``<home>/cache/<name>`` copy if present (idempotent)."""
  53. for path in (home / name, home / "cache" / name):
  54. try:
  55. path.unlink()
  56. except OSError:
  57. pass
  58. def entry_from_payload(payload: object) -> Optional[CachedFetch]:
  59. """``{"secrets": {...}, "fetched_at": n}`` → :class:`CachedFetch`, or None if malformed.
  60. Only str→str pairs survive (JSON permits other types; env vars need strings).
  61. """
  62. if not isinstance(payload, dict):
  63. return None
  64. secrets, fetched_at = payload.get("secrets"), payload.get("fetched_at")
  65. if not isinstance(secrets, dict) or not isinstance(fetched_at, (int, float)):
  66. return None
  67. typed = {k: v for k, v in secrets.items() if isinstance(k, str) and isinstance(v, str)}
  68. return CachedFetch(secrets=typed, fetched_at=float(fetched_at))
  69. def atomic_write_json(path: Path, payload: dict) -> None:
  70. """Secret cache entry at 0600 from creation; the containing dir is tightened to 0700
  71. (``secure_parent_dir`` refuses ``/``, top-level dirs and the install tree). Raises ``OSError``
  72. on failure; callers decide whether that is best-effort."""
  73. from hermes_constants import mkdir_under_hermes_home
  74. mkdir_under_hermes_home(path.parent)
  75. secure_parent_dir(path)
  76. atomic_json_write(path, payload, indent=None, mode=0o600)
  77. K = TypeVar("K")
  78. class DiskCache(Generic[K]):
  79. """Best-effort, profile-aware on-disk cache for fetched secret values.
  80. One JSON object per backend at ``<hermes_home>/<basename>``::
  81. {"key": "<serialized cache key>", "secrets": {...}, "fetched_at": 1.0}
  82. The file sits at the top of the home, where a sandbox can hide it by path: a folder the
  83. agent writes (``cache/``) can be renamed to expose a hidden file below it.
  84. The file holds only secret *values*, never raw auth material — backends
  85. fingerprint tokens/sessions before they reach ``key_serializer``. Both
  86. ``read`` and ``write`` short-circuit when ``ttl_seconds <= 0``, so a TTL of
  87. zero disables both layers symmetrically: an opted-out user never gets
  88. secret values written to disk at all.
  89. """
  90. def __init__(self, basename: str, *, key_serializer: Callable[[K], str]) -> None:
  91. self._basename = basename
  92. self._key_serializer = key_serializer
  93. def path(self, home_path: Optional[Path] = None) -> Path:
  94. return resolve_cache_home(home_path) / self._basename
  95. def _current_path(self, home_path: Optional[Path]) -> Path:
  96. return current_cache_path(resolve_cache_home(home_path), self._basename)
  97. def read(self, key: K, ttl_seconds: float, home_path: Optional[Path] = None) -> Optional[CachedFetch]:
  98. """Fresh cached entry for ``key``, or None (I/O error, mismatch, stale)."""
  99. if ttl_seconds <= 0:
  100. return None
  101. try:
  102. with open(self._current_path(home_path), "r", encoding="utf-8-sig") as f:
  103. payload = json.load(f)
  104. except (OSError, json.JSONDecodeError):
  105. return None
  106. if not isinstance(payload, dict) or payload.get("key") != self._key_serializer(key):
  107. return None
  108. entry = entry_from_payload(payload)
  109. return entry if entry is not None and entry.is_fresh(ttl_seconds) else None
  110. def write(self, key: K, entry: CachedFetch, ttl_seconds: float, home_path: Optional[Path] = None) -> None:
  111. """Persist ``entry`` atomically at mode 0600; no-op when ``ttl_seconds <= 0`` or on I/O error."""
  112. if ttl_seconds <= 0:
  113. return
  114. payload = {"key": self._key_serializer(key), "secrets": entry.secrets, "fetched_at": entry.fetched_at}
  115. try:
  116. atomic_write_json(self._current_path(home_path), payload)
  117. except OSError:
  118. pass # best-effort — a disk-cache miss next invocation is fine
  119. def clear(self, home_path: Optional[Path] = None) -> None:
  120. """Delete the on-disk cache file if present (idempotent)."""
  121. remove_cache_file(resolve_cache_home(home_path), self._basename)
  122. class SecretCache(Generic[K]):
  123. """Two-layer cache: in-process dict (L1) over a :class:`DiskCache` (L2).
  124. L1 saves repeated fetches WITHIN one process (CLI startup, gateway
  125. hot-reload); L2 saves them ACROSS back-to-back short-lived processes.
  126. """
  127. def __init__(self, basename: str, *, key_serializer: Callable[[K], str]) -> None:
  128. self.memory: dict[K, CachedFetch] = {}
  129. self.disk: DiskCache[K] = DiskCache(basename, key_serializer=key_serializer)
  130. def lookup(self, key: K, ttl_seconds: float, home_path: Optional[Path] = None,
  131. read_disk: Optional[Callable[[], Optional[CachedFetch]]] = None) -> Optional[CachedFetch]:
  132. """Fresh entry from L1, else from L2 (promoted into L1), else None.
  133. ``read_disk`` swaps in an alternative L2 reader (e.g. an encrypted file).
  134. """
  135. cached = self.memory.get(key)
  136. if cached and cached.is_fresh(ttl_seconds):
  137. return cached
  138. disk_cached = read_disk() if read_disk else self.disk.read(key, ttl_seconds, home_path)
  139. if disk_cached is not None:
  140. self.memory[key] = disk_cached
  141. return disk_cached
  142. def store(self, key: K, entry: CachedFetch, ttl_seconds: float, home_path: Optional[Path] = None) -> None:
  143. self.memory[key] = entry
  144. self.disk.write(key, entry, ttl_seconds, home_path)
  145. def clear(self, home_path: Optional[Path] = None) -> None:
  146. self.memory.clear()
  147. self.disk.clear(home_path)