| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193 |
- """Shared cache substrate for external secret-source backends.
- Two-layer fetch cache (in-process + on-disk); the disk half writes atomically
- with ``0600`` permissions and honours a TTL, so that logic is audited in exactly
- one place. Each backend supplies only its cache-key shape and a serializer.
- The disk layer is strictly best-effort: a miss just triggers a refetch, because
- a cache problem must never block Hermes startup.
- """
- from __future__ import annotations
- import hashlib
- import json
- import time
- from contextlib import suppress
- from dataclasses import dataclass
- from pathlib import Path
- from typing import Callable, Dict, Generic, Optional, TypeVar
- from hermes_constants import secure_parent_dir
- from utils import atomic_json_write
- __all__ = [
- "CachedFetch",
- "DiskCache",
- "SecretCache",
- "atomic_write_json",
- "current_cache_path",
- "entry_from_payload",
- "fingerprint",
- "remove_cache_file",
- "resolve_cache_home",
- ]
- def fingerprint(material: str) -> str:
- """SHA-256 prefix used as a cache key — never logged, never displayed."""
- return hashlib.sha256(material.encode("utf-8")).hexdigest()[:16]
- @dataclass
- class CachedFetch:
- """A set of fetched secret values plus when they were fetched."""
- secrets: dict[str, str]
- fetched_at: float
- def is_fresh(self, ttl_seconds: float) -> bool:
- return ttl_seconds > 0 and (time.time() - self.fetched_at) < ttl_seconds
- def resolve_cache_home(home_path: Optional[Path] = None) -> Path:
- """``home_path`` as resolved by ``load_hermes_dotenv()``, else ``$HERMES_HOME``/``~/.hermes``."""
- if home_path is None:
- from hermes_constants import get_hermes_home
- home_path = get_hermes_home()
- return home_path
- def current_cache_path(home: Path, name: str) -> Path:
- """``<home>/<name>``. A copy at ``<home>/cache/<name>``, where earlier releases kept the secret
- caches, is deleted first without being read: the agent can write that folder."""
- with suppress(OSError):
- (home / "cache" / name).unlink()
- return home / name
- def remove_cache_file(home: Path, name: str) -> None:
- """Delete ``<home>/<name>`` and an old ``<home>/cache/<name>`` copy if present (idempotent)."""
- for path in (home / name, home / "cache" / name):
- try:
- path.unlink()
- except OSError:
- pass
- def entry_from_payload(payload: object) -> Optional[CachedFetch]:
- """``{"secrets": {...}, "fetched_at": n}`` → :class:`CachedFetch`, or None if malformed.
- Only str→str pairs survive (JSON permits other types; env vars need strings).
- """
- if not isinstance(payload, dict):
- return None
- secrets, fetched_at = payload.get("secrets"), payload.get("fetched_at")
- if not isinstance(secrets, dict) or not isinstance(fetched_at, (int, float)):
- return None
- typed = {k: v for k, v in secrets.items() if isinstance(k, str) and isinstance(v, str)}
- return CachedFetch(secrets=typed, fetched_at=float(fetched_at))
- def atomic_write_json(path: Path, payload: dict) -> None:
- """Secret cache entry at 0600 from creation; the containing dir is tightened to 0700
- (``secure_parent_dir`` refuses ``/``, top-level dirs and the install tree). Raises ``OSError``
- on failure; callers decide whether that is best-effort."""
- from hermes_constants import mkdir_under_hermes_home
- mkdir_under_hermes_home(path.parent)
- secure_parent_dir(path)
- atomic_json_write(path, payload, indent=None, mode=0o600)
- K = TypeVar("K")
- class DiskCache(Generic[K]):
- """Best-effort, profile-aware on-disk cache for fetched secret values.
- One JSON object per backend at ``<hermes_home>/<basename>``::
- {"key": "<serialized cache key>", "secrets": {...}, "fetched_at": 1.0}
- The file sits at the top of the home, where a sandbox can hide it by path: a folder the
- agent writes (``cache/``) can be renamed to expose a hidden file below it.
- The file holds only secret *values*, never raw auth material — backends
- fingerprint tokens/sessions before they reach ``key_serializer``. Both
- ``read`` and ``write`` short-circuit when ``ttl_seconds <= 0``, so a TTL of
- zero disables both layers symmetrically: an opted-out user never gets
- secret values written to disk at all.
- """
- def __init__(self, basename: str, *, key_serializer: Callable[[K], str]) -> None:
- self._basename = basename
- self._key_serializer = key_serializer
- def path(self, home_path: Optional[Path] = None) -> Path:
- return resolve_cache_home(home_path) / self._basename
- def _current_path(self, home_path: Optional[Path]) -> Path:
- return current_cache_path(resolve_cache_home(home_path), self._basename)
- def read(self, key: K, ttl_seconds: float, home_path: Optional[Path] = None) -> Optional[CachedFetch]:
- """Fresh cached entry for ``key``, or None (I/O error, mismatch, stale)."""
- if ttl_seconds <= 0:
- return None
- try:
- with open(self._current_path(home_path), "r", encoding="utf-8-sig") as f:
- payload = json.load(f)
- except (OSError, json.JSONDecodeError):
- return None
- if not isinstance(payload, dict) or payload.get("key") != self._key_serializer(key):
- return None
- entry = entry_from_payload(payload)
- return entry if entry is not None and entry.is_fresh(ttl_seconds) else None
- def write(self, key: K, entry: CachedFetch, ttl_seconds: float, home_path: Optional[Path] = None) -> None:
- """Persist ``entry`` atomically at mode 0600; no-op when ``ttl_seconds <= 0`` or on I/O error."""
- if ttl_seconds <= 0:
- return
- payload = {"key": self._key_serializer(key), "secrets": entry.secrets, "fetched_at": entry.fetched_at}
- try:
- atomic_write_json(self._current_path(home_path), payload)
- except OSError:
- pass # best-effort — a disk-cache miss next invocation is fine
- def clear(self, home_path: Optional[Path] = None) -> None:
- """Delete the on-disk cache file if present (idempotent)."""
- remove_cache_file(resolve_cache_home(home_path), self._basename)
- class SecretCache(Generic[K]):
- """Two-layer cache: in-process dict (L1) over a :class:`DiskCache` (L2).
- L1 saves repeated fetches WITHIN one process (CLI startup, gateway
- hot-reload); L2 saves them ACROSS back-to-back short-lived processes.
- """
- def __init__(self, basename: str, *, key_serializer: Callable[[K], str]) -> None:
- self.memory: dict[K, CachedFetch] = {}
- self.disk: DiskCache[K] = DiskCache(basename, key_serializer=key_serializer)
- def lookup(self, key: K, ttl_seconds: float, home_path: Optional[Path] = None,
- read_disk: Optional[Callable[[], Optional[CachedFetch]]] = None) -> Optional[CachedFetch]:
- """Fresh entry from L1, else from L2 (promoted into L1), else None.
- ``read_disk`` swaps in an alternative L2 reader (e.g. an encrypted file).
- """
- cached = self.memory.get(key)
- if cached and cached.is_fresh(ttl_seconds):
- return cached
- disk_cached = read_disk() if read_disk else self.disk.read(key, ttl_seconds, home_path)
- if disk_cached is not None:
- self.memory[key] = disk_cached
- return disk_cached
- def store(self, key: K, entry: CachedFetch, ttl_seconds: float, home_path: Optional[Path] = None) -> None:
- self.memory[key] = entry
- self.disk.write(key, entry, ttl_seconds, home_path)
- def clear(self, home_path: Optional[Path] = None) -> None:
- self.memory.clear()
- self.disk.clear(home_path)
|