| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154 |
- """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
|