The agent that grows with you
Python aiai-agentai-agentsanthropicchatgptclaudeclaude-codecodexhermeshermes-agentllmnous-researchopenai
"""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)