Skip to content

The agent that grows with you

7.5 KB
Raw Blame
"""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)