"""OS-keychain storage for the local vault key (opt-in: ``vault.key_storage: keychain``). The vault key normally sits in ``vault.key`` next to the ciphertext. In keychain mode it lives in the OS credential store instead (macOS Keychain, Windows Credential Manager, Secret Service / KWallet on Linux, via the ``keyring`` package from the ``keychain`` extra), and the vault directory keeps only a non-secret pointer, ``vault.keyref``, naming the entry. A backup, a synced folder or a copied home directory then holds ciphertext without its key. This does not isolate the key from code running as the same OS user: any such process (including an in-process plugin) can ask the keychain for it, or simply call the vault API. """ from __future__ import annotations import json import os import uuid from contextlib import suppress from pathlib import Path from typing import Optional SERVICE = "Hermes Agent vault key" # keyring backends that are not an OS credential store: ``fail``/``null`` are what keyring picks on # a headless Linux box with no Secret Service, and keyrings.alt's plaintext/encrypted-file keyrings # would only move the key into another file under the same home. _NOT_A_KEYCHAIN = ("keyring.backends.fail", "keyring.backends.null", "keyrings.alt") class KeychainUnavailable(Exception): """No OS keychain is reachable from this process (headless, no keyring extra, plaintext backend).""" def _is_os_keychain(backend) -> bool: children = getattr(backend, "backends", None) if children is not None: # keyring's ChainerBackend writes to its highest-priority child return bool(children) and _is_os_keychain(children[0]) return not type(backend).__module__.startswith(_NOT_A_KEYCHAIN) def os_keyring(): """The OS credential store keyring resolves to, or raise :class:`KeychainUnavailable`.""" try: import keyring except ImportError as exc: raise KeychainUnavailable( "the keychain feature is not installed (`hermes pm install --extra keychain`)") from exc try: backend = keyring.get_keyring() except Exception as exc: # health: allow BLE001 -- backend discovery runs third-party entry points raise KeychainUnavailable(f"keyring could not pick a backend ({type(exc).__name__})") from exc if not _is_os_keychain(backend): raise KeychainUnavailable( f"no OS keychain is reachable from this session (keyring backend: {type(backend).__module__}.{type(backend).__name__})") return backend def backend_label() -> str: """Human name of the keychain this process would use, for ``hermes vault key``.""" try: backend = os_keyring() except KeychainUnavailable as exc: return f"unavailable: {exc}" return str(getattr(backend, "name", "") or type(backend).__name__) def new_ref(vault_dir: Path) -> dict: """Keychain coordinates for a new entry. The account is random, never derived from the path: a renamed profile keeps its pointer, and a new profile reusing the old name must not land on (and overwrite) the renamed vault's entry. ``vault_dir`` records which directory owns the entry.""" return {"storage": "keychain", "service": SERVICE, "account": f"vault-{uuid.uuid4().hex}", "vault_dir": str(Path(vault_dir).resolve())} def owns(ref: dict, vault_dir: Path) -> bool: """False for a pointer copied or moved from another directory (profile clone/rename): the entry it names may still be another vault's only key, so this vault must not overwrite or delete it.""" return ref.get("vault_dir") == str(Path(vault_dir).resolve()) def read_ref(path: Path) -> Optional[dict]: try: data = json.loads(path.read_text(encoding="utf-8-sig")) except FileNotFoundError: return None except (OSError, ValueError) as exc: from agent.vault_store import VaultError raise VaultError(f"{path.name} is unreadable ({type(exc).__name__}); see `hermes vault key`") from exc if not isinstance(data, dict) or data.get("storage") != "keychain" or not data.get("account"): from agent.vault_store import VaultError raise VaultError(f"{path.name} does not describe a keychain entry; see `hermes vault key`") return data def write_ref(path: Path, ref: dict) -> None: from utils import atomic_write_bytes atomic_write_bytes(path, json.dumps(ref, indent=2).encode("utf-8"), mode=0o600, fsync_dir=True) def save_new_ref(path: Path, ref: dict) -> None: """Save the pointer to an entry just created. If saving fails, delete the entry unless the pointer did land (a replace can succeed before a later step errors): every account is random, so an entry no pointer names is a key Hermes would never find or remove again.""" try: write_ref(path, ref) except OSError: from agent.vault_store import VaultError with suppress(VaultError): if (read_ref(path) or {}).get("account") == ref["account"]: raise delete_key(ref) raise def load_key(ref: dict) -> Optional[bytes]: """The stored key, or None when the entry is gone. Raises KeychainUnavailable.""" backend = os_keyring() try: value = backend.get_password(str(ref.get("service") or SERVICE), str(ref["account"])) except Exception as exc: # health: allow BLE001 -- a locked or dismissed keychain raises backend-specific types raise KeychainUnavailable(f"the OS keychain did not answer ({type(exc).__name__})") from exc return value.encode("ascii") if value else None def store_key(ref: dict, key: bytes) -> None: """Write the key and read it back: a store that accepts a write it cannot return is unusable.""" backend = os_keyring() service, account = str(ref.get("service") or SERVICE), str(ref["account"]) try: backend.set_password(service, account, key.decode("ascii")) readback = backend.get_password(service, account) except Exception as exc: # health: allow BLE001 -- every keyring backend raises its own types raise KeychainUnavailable(f"the OS keychain refused the key ({type(exc).__name__})") from exc if readback != key.decode("ascii"): raise KeychainUnavailable("the OS keychain did not return the key it was given") def delete_key(ref: dict) -> bool: """True once the entry is gone, including when an earlier, interrupted cleanup already removed it.""" service, account = str(ref.get("service") or SERVICE), str(ref["account"]) try: backend = os_keyring() with suppress(Exception): # a missing entry raises PasswordDeleteError; the read below decides backend.delete_password(service, account) return backend.get_password(service, account) is None except Exception: # health: allow BLE001 -- unreachable keychain: the caller keeps the pointer to retry return False def remove_file(path: Path) -> None: try: os.remove(path) except FileNotFoundError: pass