vault_store.py 30 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685
  1. """Local encrypted vault for browser autofill secrets.
  2. Profile-scoped, model-blind credential store. Metadata (kind, label, origin,
  3. timestamps) lives alongside an encrypted secret payload; the payload is
  4. encrypted at rest with a locally generated Fernet key. The model only ever
  5. sees opaque handles + metadata — secret values are resolved server-side by
  6. the browser fill path and never enter tool results, logs, or the session DB.
  7. Design notes:
  8. - Follows the repo's "default frictionless, 0600 files OK" policy: the key
  9. file and vault file are created 0600 under ``<HERMES_HOME>/vault/``.
  10. ``vault.key_storage: keychain`` (opt-in) keeps the key in the OS keychain
  11. instead (agent/vault_keychain.py); ``hermes vault key migrate`` moves it.
  12. - Ported design (opaque-handle vault fill) from Merit-Systems/OpenInstinct
  13. (MIT): lib/manager/server/secret-store.ts + vault services.
  14. - Three item kinds: ``login`` (password-only secret), ``payment`` (card fields) and
  15. ``address``; ``PAYMENT_FIELDS`` / ``ADDRESS_FIELDS`` are the canonical payload names.
  16. """
  17. from __future__ import annotations
  18. import json
  19. import logging
  20. import os
  21. import re
  22. import threading
  23. import uuid
  24. from contextlib import contextmanager, suppress
  25. from dataclasses import dataclass
  26. from datetime import datetime, timezone, UTC
  27. from pathlib import Path
  28. from typing import Any, Dict, List, Optional
  29. from urllib.parse import urlsplit
  30. from hermes_dir_acl import make_user_dir
  31. from hermes_constants import get_hermes_home
  32. from utils import atomic_write_bytes
  33. logger = logging.getLogger(__name__)
  34. VAULT_KINDS = ("login", "payment", "address")
  35. LOGIN_IDENTIFIER_TYPES = ("email", "phone", "username")
  36. # Canonical secret-payload fields per non-login kind. Each maps to the WHATWG autocomplete token the
  37. # browser fill targets (agent/vault_login_classifier.py); the Desktop Add dialog and `hermes vault add`
  38. # both write these names, so the fill never has to guess a user's ad-hoc field naming.
  39. PAYMENT_FIELDS = {
  40. "card_number": "cc-number", "cardholder_name": "cc-name", "exp_month": "cc-exp-month",
  41. "exp_year": "cc-exp-year", "cvc": "cc-csc", "billing_postal_code": "postal-code",
  42. }
  43. ADDRESS_FIELDS = {
  44. "address_line1": "address-line1", "address_line2": "address-line2", "city": "address-level2",
  45. "state": "address-level1", "postal_code": "postal-code", "country": "country-name",
  46. }
  47. REQUIRED_FIELDS = {"payment": ("card_number", "exp_month", "exp_year", "cvc"),
  48. "address": ("address_line1", "city", "postal_code", "country")}
  49. _DEFAULT_PORTS = {"http": 80, "https": 443}
  50. _LOCK = threading.Lock()
  51. # fcntl is Unix-only; Windows locks a byte range with msvcrt (same shape as tools/skill_usage.py).
  52. msvcrt = None
  53. try:
  54. import fcntl
  55. except ImportError: # pragma: no cover - platform-specific fallback
  56. fcntl = None
  57. with suppress(ImportError):
  58. import msvcrt
  59. def configured_key_storage() -> str:
  60. """``vault.key_storage``: where a NEW vault's key goes (``file`` default, or ``keychain``)."""
  61. from hermes_cli.config import load_config_readonly
  62. section = load_config_readonly().get("vault") or {}
  63. value = section.get("key_storage") if isinstance(section, dict) else None
  64. return str(value or "file").strip().lower()
  65. class VaultError(Exception):
  66. """Vault failure that is safe to surface (never contains secret values)."""
  67. _OTP_ALGOS = {"SHA1": "sha1", "SHA256": "sha256", "SHA512": "sha512"}
  68. def normalize_otp_secret(value: str) -> str:
  69. """Accept a raw base32 seed or an ``otpauth://totp/...`` URI. Returns the canonical stored form:
  70. the bare uppercase base32 seed, followed by ``|digits|period|algo`` ONLY when the URI departs from
  71. the RFC 6238 defaults (6 / 30 / SHA1), so a plain seed stays a plain seed. Non-default parameters
  72. are honoured, not dropped: an 8-digit or 60-second authenticator would otherwise get wrong codes."""
  73. value = (value or "").strip()
  74. if not value:
  75. return ""
  76. digits, period, algo = 6, 30, "SHA1"
  77. if value.lower().startswith("otpauth://"):
  78. from urllib.parse import parse_qs, urlparse
  79. parsed = urlparse(value)
  80. if parsed.netloc.lower() != "totp":
  81. raise VaultError("only otpauth://totp links are supported (counter-based HOTP is not)")
  82. qs = {k.lower(): v[0] for k, v in parse_qs(parsed.query).items()}
  83. value = qs.get("secret", "")
  84. try:
  85. digits = int(qs.get("digits", digits))
  86. period = int(qs.get("period", period))
  87. except ValueError:
  88. raise VaultError("otpauth:// digits/period must be integers")
  89. algo = qs.get("algorithm", algo).upper().replace("-", "")
  90. if digits not in (6, 7, 8) or period <= 0 or algo not in _OTP_ALGOS:
  91. raise VaultError("unsupported otpauth:// parameters (digits 6-8, period > 0, SHA1/SHA256/SHA512)")
  92. seed = re.sub(r"[\s-]", "", value).upper().rstrip("=")
  93. if not seed or re.search(r"[^A-Z2-7]", seed):
  94. raise VaultError("authenticator key must be a base32 secret or an otpauth:// URI")
  95. if (digits, period, algo) == (6, 30, "SHA1"):
  96. return seed
  97. return f"{seed}|{digits}|{period}|{algo}"
  98. def totp_now(seed: str, *, digits: int = 6, period: int = 30, at: Optional[float] = None) -> str:
  99. """RFC 6238 TOTP for a stored seed (see normalize_otp_secret for the ``seed|digits|period|algo``
  100. form). Stdlib only."""
  101. import base64
  102. import hashlib
  103. import hmac
  104. import struct
  105. import time as _time
  106. algo = "sha1"
  107. if "|" in seed:
  108. seed, d, p, a = seed.split("|", 3)
  109. digits, period, algo = int(d), int(p), _OTP_ALGOS.get(a.upper(), "sha1")
  110. key = base64.b32decode(seed + "=" * (-len(seed) % 8), casefold=True)
  111. counter = int((at if at is not None else _time.time()) // period)
  112. digest = hmac.new(key, struct.pack(">Q", counter), getattr(hashlib, algo)).digest()
  113. offset = digest[-1] & 0x0F
  114. code = (struct.unpack(">I", digest[offset:offset + 4])[0] & 0x7FFFFFFF) % (10 ** digits)
  115. return str(code).zfill(digits)
  116. def normalize_origin(url_or_origin: str) -> str:
  117. """Normalize a URL or origin to ``scheme://host[:port]``.
  118. Default ports (80 for http, 443 for https) are stripped so that
  119. ``https://example.com`` and ``https://example.com:443`` compare equal.
  120. Raises :class:`VaultError` for values without a scheme + host.
  121. """
  122. value = (url_or_origin or "").strip()
  123. if not value:
  124. raise VaultError("origin is required")
  125. if "://" not in value:
  126. raise VaultError(f"origin must include a scheme (got {value!r})")
  127. parts = urlsplit(value)
  128. scheme = (parts.scheme or "").lower()
  129. host = (parts.hostname or "").lower()
  130. if not scheme or not host:
  131. raise VaultError(f"could not parse origin from {value!r}")
  132. try:
  133. port = parts.port
  134. except ValueError as exc:
  135. raise VaultError(f"invalid port in origin {value!r}") from exc
  136. if port is None or port == _DEFAULT_PORTS.get(scheme):
  137. return f"{scheme}://{host}"
  138. return f"{scheme}://{host}:{port}"
  139. @dataclass(frozen=True)
  140. class VaultItemMeta:
  141. """Metadata-only view of a vault item. Never contains secret values.
  142. For ``kind='login'`` the identifier (email/username/phone) is metadata,
  143. not a secret: the agent may see it and type it itself. Only the password
  144. is vault-secret.
  145. """
  146. id: str
  147. kind: str
  148. label: str
  149. origin: Optional[str]
  150. created_at: str
  151. identifier_type: Optional[str] = None
  152. identifier: Optional[str] = None
  153. has_otp: bool = False # a TOTP seed is stored: 2FA codes can be minted without asking the user
  154. # Every origin the password manager bound to this item (manager backends only;
  155. # ``origin`` is the first/primary one). Fill matching stays exact-origin against
  156. # this list — no wildcard or subdomain inference is ever derived from it.
  157. allowed_origins: tuple = ()
  158. def to_dict(self) -> dict[str, Any]:
  159. out = {
  160. "id": self.id,
  161. "kind": self.kind,
  162. "label": self.label,
  163. "origin": self.origin,
  164. "created_at": self.created_at,
  165. }
  166. if self.identifier is not None:
  167. out["identifier"] = self.identifier
  168. out["identifier_type"] = self.identifier_type
  169. if self.has_otp:
  170. out["has_otp"] = True
  171. if len(self.allowed_origins) > 1:
  172. out["allowed_origins"] = list(self.allowed_origins)
  173. return out
  174. class VaultStore:
  175. """Encrypted, profile-scoped vault under ``<HERMES_HOME>/vault/``."""
  176. def __init__(self, base_dir: Optional[Path] = None):
  177. self._base = Path(base_dir) if base_dir is not None else (
  178. Path(get_hermes_home()) / "vault"
  179. )
  180. self._vault_path = self._base / "vault.json.enc"
  181. self._key_path = self._base / "vault.key"
  182. # Keychain mode (vault.key_storage: keychain) keeps only this non-secret pointer beside the
  183. # ciphertext; agent/vault_keychain.py owns the entry it names.
  184. self._keyref_path = self._base / "vault.keyref"
  185. # -- key / crypto ------------------------------------------------------
  186. def _ensure_dir(self) -> None:
  187. make_user_dir(self._base, mode=0o700, parents=True, exist_ok=True)
  188. # Route through the canonical securer (honors managed/NixOS
  189. # group-share mode and HERMES_UID/GID ownership) rather than a
  190. # bespoke chmod — same requirement as the browser-profile snapshot
  191. # dir (f1d05c review).
  192. try:
  193. from hermes_cli.config import _secure_dir
  194. _secure_dir(self._base)
  195. except Exception:
  196. try:
  197. os.chmod(self._base, 0o700)
  198. except OSError:
  199. pass
  200. @contextmanager
  201. def _locked(self):
  202. """Serialize read-modify-write cycles across threads AND processes: the Desktop gateway, a CLI
  203. `hermes vault add` and a TUI slash worker all write the same ``vault.json.enc``; two unlocked
  204. writers would drop each other's items."""
  205. with _LOCK:
  206. self._ensure_dir()
  207. lock_path = self._base / ".vault.lock"
  208. if msvcrt and (not lock_path.exists() or lock_path.stat().st_size == 0):
  209. lock_path.write_text(" ", encoding="utf-8") # msvcrt needs a non-empty byte range to lock
  210. with open(lock_path, "r+" if msvcrt else "a+", encoding="utf-8") as fd:
  211. if fcntl:
  212. fcntl.flock(fd, fcntl.LOCK_EX)
  213. elif msvcrt:
  214. fd.seek(0)
  215. msvcrt.locking(fd.fileno(), msvcrt.LK_LOCK, 1)
  216. try:
  217. yield
  218. finally:
  219. with suppress(OSError):
  220. if fcntl:
  221. fcntl.flock(fd, fcntl.LOCK_UN)
  222. elif msvcrt:
  223. fd.seek(0)
  224. msvcrt.locking(fd.fileno(), msvcrt.LK_UNLCK, 1)
  225. def _fernet(self):
  226. from cryptography.fernet import Fernet
  227. return Fernet(self._key())
  228. def _has_ciphertext(self) -> bool:
  229. return self._vault_path.exists() and self._vault_path.stat().st_size > 0
  230. def _key(self) -> bytes:
  231. """``vault.key`` when present (the legacy layout wins), else the keychain entry ``vault.keyref``
  232. names, else a new key for a vault that has no items yet. Never mints a key over ciphertext:
  233. that would make the saved items unrecoverable for good."""
  234. from agent import vault_keychain as kc
  235. self._ensure_dir()
  236. if self._key_path.exists():
  237. with suppress(OSError):
  238. os.chmod(self._key_path, 0o600)
  239. return self._key_path.read_bytes().strip()
  240. ref = kc.read_ref(self._keyref_path)
  241. if ref is not None:
  242. try:
  243. ref = self._adopt(ref)
  244. key = kc.load_key(ref)
  245. except kc.KeychainUnavailable as exc:
  246. key, why = None, f"the OS keychain is not reachable here: {exc}"
  247. else:
  248. why = f"the keychain entry {ref.get('service')!r} / {ref['account']!r} is gone"
  249. if key:
  250. return key
  251. else:
  252. why = f"{self._key_path.name} is missing"
  253. if self._has_ciphertext():
  254. raise VaultError(self._missing_key_message(why))
  255. return self._create_key()
  256. def _missing_key_message(self, why: str) -> str:
  257. return (f"The vault key could not be found ({why}). vault.json.enc in {self._base} was left untouched. "
  258. "If this profile came from another machine, run `hermes vault key migrate --to file` there and "
  259. "copy its vault.key next to vault.json.enc; if the keychain entry was deleted, restore it from a "
  260. "keychain backup. `hermes vault key` shows where the key is expected. To start over instead, "
  261. "delete vault.json.enc (its saved items are lost).")
  262. def _conflicting_key_message(self) -> str:
  263. # Never overwrite or delete the other copy here: it may be the only key that opens the vault.
  264. return (f"{self._key_path} does not decrypt vault.json.enc, so the key was not moved and nothing "
  265. "was deleted. If the vault's key is in the OS keychain, move this vault.key aside and run "
  266. "`hermes vault key` again.")
  267. def _create_key(self) -> bytes:
  268. from cryptography.fernet import Fernet
  269. from agent import vault_keychain as kc
  270. key = Fernet.generate_key()
  271. if configured_key_storage() == "keychain":
  272. ref = kc.new_ref(self._base)
  273. try:
  274. kc.store_key(ref, key)
  275. except kc.KeychainUnavailable as exc:
  276. # Headless boxes (no Secret Service), and installs without the keychain extra, keep
  277. # working: the key goes to the 0600 file exactly as it always has.
  278. logger.warning("vault.key_storage is keychain, but %s; using %s instead", exc, self._key_path)
  279. else:
  280. kc.save_new_ref(self._keyref_path, ref)
  281. return key
  282. kc.remove_file(self._keyref_path)
  283. self._write_key_file(key)
  284. return key
  285. def _write_key_file(self, key: bytes) -> None:
  286. # Atomic + directory fsync: an interrupted write must never leave a partial vault.key, which
  287. # reads would prefer over a working keychain entry. Callers hold the vault lock.
  288. atomic_write_bytes(self._key_path, key, mode=0o600, fsync_dir=True)
  289. def own_copied_key(self, published_base: Path) -> Optional[dict]:
  290. """A ``--clone-all`` copy carries the source's ``vault.keyref``, which names the SOURCE's entry;
  291. the source moving its key to a file deletes that entry. Before the clone is published at
  292. ``published_base``, give it an entry of its own, so it never depends on another profile.
  293. Returns the new entry's ref (the caller deletes exactly that entry if publication fails), or
  294. None when nothing was shared. Raises VaultError when the keychain cannot be read or written:
  295. the clone must not be published sharing the source's entry."""
  296. from agent import vault_keychain as kc
  297. ref = kc.read_ref(self._keyref_path)
  298. if ref is None or self._key_path.exists():
  299. return None # key file layout (a vault.key always wins on read): nothing is shared
  300. try:
  301. key = kc.load_key(ref)
  302. if not self._decrypts(key):
  303. return None # the source's own entry is already gone: the copy is no worse off than it
  304. mine = kc.new_ref(published_base)
  305. kc.store_key(mine, key)
  306. except kc.KeychainUnavailable as exc:
  307. raise VaultError(
  308. f"its key is in the OS keychain, which this session cannot use ({exc}). Clone from a session "
  309. "that can reach the keychain, or run `hermes vault key migrate --to file` on the source first.") from exc
  310. try:
  311. kc.write_ref(self._keyref_path, mine)
  312. except OSError:
  313. kc.delete_key(mine) # the staged clone is discarded with this error, a landed pointer included
  314. raise
  315. return mine
  316. def _adopt(self, ref: dict) -> dict:
  317. """Give a moved vault (profile rename, or a clone made before clones got their own entry at
  318. creation) its own keychain entry. Never deletes the entry it came from: another copy may still
  319. depend on it. Raises KeychainUnavailable only when the shared entry cannot be read; if the new
  320. entry cannot be written, the shared one keeps serving."""
  321. from agent import vault_keychain as kc
  322. if kc.owns(ref, self._base):
  323. return ref
  324. key = kc.load_key(ref)
  325. if not self._decrypts(key):
  326. return ref
  327. mine = kc.new_ref(self._base)
  328. try:
  329. kc.store_key(mine, key)
  330. kc.write_ref(self._keyref_path, mine)
  331. except (kc.KeychainUnavailable, OSError):
  332. # The replace can land before the error (e.g. a temp-file cleanup failing on Windows): then
  333. # the saved pointer already names the new entry, which must survive.
  334. with suppress(VaultError):
  335. if (kc.read_ref(self._keyref_path) or {}).get("account") == mine["account"]:
  336. return mine
  337. kc.delete_key(mine) # no orphan per retry; the shared entry keeps serving reads
  338. logger.warning("could not give the copied vault in %s its own keychain entry", self._base, exc_info=True)
  339. return ref
  340. return mine
  341. def _decrypts(self, key: Optional[bytes]) -> bool:
  342. from cryptography.fernet import Fernet, InvalidToken
  343. if not key:
  344. return False
  345. if not self._has_ciphertext():
  346. return True
  347. try:
  348. Fernet(key).decrypt(self._vault_path.read_bytes())
  349. except (InvalidToken, ValueError):
  350. return False
  351. return True
  352. # -- key storage ---------------------------------------------------------
  353. def key_location(self) -> dict[str, Any]:
  354. """Where this vault's key lives (never the key itself), for ``hermes vault key``."""
  355. from agent import vault_keychain as kc
  356. ref = kc.read_ref(self._keyref_path)
  357. if self._key_path.exists():
  358. where = {"storage": "file", "path": str(self._key_path)}
  359. if ref is not None: # a keychain copy that could not be removed yet
  360. where["keychain_entry_left"] = ref["account"]
  361. return where
  362. return dict(ref) if ref else {"storage": "none", "path": str(self._key_path)}
  363. def migrate_key(self, target: str) -> str:
  364. """Move the key between ``vault.key`` and the OS keychain. The destination is written and proven
  365. to decrypt the vault before the source is removed, so an interrupted move leaves a working vault
  366. and re-running it finishes the job."""
  367. if target not in ("file", "keychain"):
  368. raise VaultError("key storage must be 'file' or 'keychain'")
  369. with self._locked():
  370. self._ensure_dir()
  371. return self._migrate_to_keychain() if target == "keychain" else self._migrate_to_file()
  372. def _migrate_to_keychain(self) -> str:
  373. from agent import vault_keychain as kc
  374. existing = kc.read_ref(self._keyref_path)
  375. if not self._key_path.exists():
  376. if existing is not None: # already moved: prove the entry still opens the vault
  377. try:
  378. key = kc.load_key(self._adopt(existing))
  379. except kc.KeychainUnavailable as exc:
  380. raise VaultError(f"cannot read the vault key from the OS keychain: {exc}") from exc
  381. if not self._decrypts(key):
  382. raise VaultError(self._missing_key_message(f"the keychain entry {existing['account']!r} does not open the vault"))
  383. return "keychain"
  384. if self._has_ciphertext():
  385. raise VaultError(self._missing_key_message(f"{self._key_path.name} is missing"))
  386. try:
  387. kc.os_keyring() # nothing to move yet, but the new vault's key must have somewhere to go
  388. except kc.KeychainUnavailable as exc:
  389. raise VaultError(f"cannot use the OS keychain: {exc}") from exc
  390. return "keychain"
  391. key = self._key_path.read_bytes().strip()
  392. if not self._decrypts(key):
  393. raise VaultError(self._conflicting_key_message())
  394. # Resume into our own entry from an interrupted move; a copied pointer's entry is not ours to overwrite.
  395. ref = existing if existing is not None and kc.owns(existing, self._base) else kc.new_ref(self._base)
  396. try:
  397. kc.store_key(ref, key)
  398. if not self._decrypts(kc.load_key(ref)):
  399. raise kc.KeychainUnavailable("the key read back from the keychain does not decrypt the vault")
  400. except kc.KeychainUnavailable as exc:
  401. if ref is not existing:
  402. kc.delete_key(ref)
  403. raise VaultError(f"could not move the vault key to the OS keychain ({exc}); "
  404. f"it stays in {self._key_path}") from exc
  405. if ref is not existing:
  406. try:
  407. kc.save_new_ref(self._keyref_path, ref)
  408. except OSError as exc:
  409. raise VaultError(f"could not save {self._keyref_path.name} ({exc}); the key stays in {self._key_path}") from exc
  410. kc.remove_file(self._key_path)
  411. return "keychain"
  412. def _migrate_to_file(self) -> str:
  413. from agent import vault_keychain as kc
  414. ref = kc.read_ref(self._keyref_path)
  415. if self._key_path.exists():
  416. if ref is not None: # a move stopped with both copies present; the file is the one in use
  417. if not self._decrypts(self._key_path.read_bytes().strip()):
  418. raise VaultError(self._conflicting_key_message())
  419. self._release_ref(ref)
  420. return "file"
  421. if ref is None:
  422. if self._has_ciphertext():
  423. raise VaultError(self._missing_key_message(f"{self._key_path.name} is missing"))
  424. return "file"
  425. try:
  426. key = kc.load_key(ref)
  427. except kc.KeychainUnavailable as exc:
  428. raise VaultError(f"cannot read the vault key from the OS keychain: {exc}") from exc
  429. if not key or not self._decrypts(key):
  430. raise VaultError(self._missing_key_message(f"the keychain entry {ref['account']!r} does not hold this vault's key"))
  431. self._write_key_file(key)
  432. if self._key_path.read_bytes().strip() != key:
  433. kc.remove_file(self._key_path)
  434. raise VaultError(f"could not write {self._key_path}; the key stays in the OS keychain")
  435. self._release_ref(ref)
  436. return "file"
  437. def _release_ref(self, ref: dict) -> None:
  438. """The file holds the key now: drop the keychain copy. An entry this vault does not own (copied
  439. pointer) is left alone; if deleting ours fails, the pointer stays so a rerun can finish."""
  440. from agent import vault_keychain as kc
  441. if kc.owns(ref, self._base) and not kc.delete_key(ref):
  442. return
  443. kc.remove_file(self._keyref_path)
  444. # -- persistence -------------------------------------------------------
  445. def _read_all(self) -> list[dict[str, Any]]:
  446. if not self._vault_path.exists():
  447. return []
  448. blob = self._vault_path.read_bytes()
  449. if not blob:
  450. return []
  451. from cryptography.fernet import InvalidToken
  452. try:
  453. raw = self._fernet().decrypt(blob)
  454. except InvalidToken as exc:
  455. raise VaultError(
  456. "vault file could not be decrypted (key mismatch or corruption)"
  457. ) from exc
  458. try:
  459. data = json.loads(raw.decode("utf-8"))
  460. except (json.JSONDecodeError, UnicodeDecodeError) as exc:
  461. raise VaultError(
  462. "vault file is corrupted (invalid JSON)"
  463. ) from exc
  464. if not isinstance(data, dict):
  465. raise VaultError("vault file is corrupted (unexpected shape)")
  466. items = data.get("items", [])
  467. return items if isinstance(items, list) else []
  468. def _write_all(self, items: list[dict[str, Any]]) -> None:
  469. self._ensure_dir()
  470. payload = json.dumps({"version": 1, "items": items}).encode("utf-8")
  471. blob = self._fernet().encrypt(payload)
  472. # fsync_dir: the directory entry must be durable too (power loss between rename and next sync).
  473. atomic_write_bytes(self._vault_path, blob, mode=0o600, fsync_dir=True)
  474. # -- public API ----------------------------------------------------------
  475. def add_item(
  476. self,
  477. kind: str,
  478. label: str,
  479. secret: dict[str, Any],
  480. origin: Optional[str] = None,
  481. ) -> VaultItemMeta:
  482. """Add an item. ``secret`` is the sensitive payload (encrypted at rest).
  483. For ``kind='login'``, ``origin`` is required and the payload must
  484. contain ``identifier_type``, ``identifier`` and ``password``. The
  485. identifier fields are NOT secret — they are moved into item metadata
  486. (the agent may see and type the identifier itself); only
  487. ``password`` stays in the encrypted secret payload. ``payment`` and
  488. ``address`` payloads remain fully secret.
  489. """
  490. if kind not in VAULT_KINDS:
  491. raise VaultError(f"unknown vault kind {kind!r} (expected one of {VAULT_KINDS})")
  492. label = (label or "").strip()
  493. if not label:
  494. raise VaultError("label is required")
  495. norm_origin: Optional[str] = None
  496. identifier: Optional[str] = None
  497. identifier_type: Optional[str] = None
  498. secret = dict(secret)
  499. if kind == "login":
  500. if not origin:
  501. raise VaultError("origin is required for login items")
  502. norm_origin = normalize_origin(origin)
  503. id_type = secret.pop("identifier_type", None)
  504. if id_type not in LOGIN_IDENTIFIER_TYPES:
  505. raise VaultError(
  506. f"identifier_type must be one of {LOGIN_IDENTIFIER_TYPES}"
  507. )
  508. identifier = str(secret.pop("identifier", "") or "").strip()
  509. if not identifier or not secret.get("password"):
  510. raise VaultError("login items require identifier and password")
  511. identifier_type = str(id_type)
  512. # Login secret payload is password (+ optional TOTP seed); identifier lives in
  513. # metadata and any stray origin echo is dropped.
  514. otp_secret = normalize_otp_secret(str(secret.get("otp_secret") or ""))
  515. secret = {"password": secret["password"], **({"otp_secret": otp_secret} if otp_secret else {})}
  516. else:
  517. allowed = PAYMENT_FIELDS if kind == "payment" else ADDRESS_FIELDS
  518. secret = {k: str(v) for k, v in secret.items() if k in allowed and str(v or "").strip()}
  519. missing = [f for f in REQUIRED_FIELDS[kind] if f not in secret]
  520. if missing:
  521. raise VaultError(f"{kind} items require {', '.join(missing)}")
  522. if origin:
  523. norm_origin = normalize_origin(origin)
  524. item_id = f"vault_{uuid.uuid4().hex[:12]}"
  525. record = {
  526. "id": item_id,
  527. "kind": kind,
  528. "label": label,
  529. "origin": norm_origin,
  530. "created_at": datetime.now(UTC).isoformat(),
  531. "identifier_type": identifier_type,
  532. "identifier": identifier,
  533. "secret": dict(secret),
  534. }
  535. with self._locked():
  536. items = self._read_all()
  537. items.append(record)
  538. self._write_all(items)
  539. return self._meta(record)
  540. def list_items(self) -> list[VaultItemMeta]:
  541. """Metadata-only listing. Secret payloads are never included."""
  542. with self._locked():
  543. return [self._meta(rec) for rec in self._read_all()]
  544. def has_items(self) -> bool:
  545. try:
  546. with self._locked():
  547. return bool(self._read_all())
  548. except Exception:
  549. return False
  550. def remove_item(self, item_id: str) -> bool:
  551. with self._locked():
  552. items = self._read_all()
  553. remaining = [rec for rec in items if rec.get("id") != item_id]
  554. if len(remaining) == len(items):
  555. return False
  556. self._write_all(remaining)
  557. return True
  558. def get_meta(self, item_id: str) -> Optional[VaultItemMeta]:
  559. with self._locked():
  560. for rec in self._read_all():
  561. if rec.get("id") == item_id:
  562. return self._meta(rec)
  563. return None
  564. def resolve_secret(self, item_id: str) -> dict[str, Any]:
  565. """Resolve the decrypted secret payload for server-side use ONLY.
  566. Callers must never place the returned values into tool results,
  567. logs, exceptions, or any string that reaches the session DB.
  568. """
  569. with self._locked():
  570. for rec in self._read_all():
  571. if rec.get("id") == item_id:
  572. return dict(rec.get("secret") or {})
  573. raise VaultError(f"no vault item with id {item_id!r}")
  574. @staticmethod
  575. def _meta(rec: dict[str, Any]) -> VaultItemMeta:
  576. identifier = rec.get("identifier")
  577. return VaultItemMeta(
  578. id=str(rec.get("id", "")),
  579. kind=str(rec.get("kind", "")),
  580. label=str(rec.get("label", "")),
  581. origin=rec.get("origin"),
  582. created_at=str(rec.get("created_at", "")),
  583. identifier_type=rec.get("identifier_type") if identifier else None,
  584. identifier=identifier or None,
  585. has_otp=bool((rec.get("secret") or {}).get("otp_secret")),
  586. )
  587. def get_vault_store() -> VaultStore:
  588. """Default profile-scoped vault store."""
  589. return VaultStore()
  590. def scrub_secret_from_text(text: str, secret: dict[str, Any]) -> str:
  591. """Defensively strip any secret values from a string (e.g. an exception
  592. message) before it can be surfaced. Case-sensitive exact substring scrub."""
  593. scrubbed = text
  594. for value in secret.values():
  595. if isinstance(value, str) and len(value) >= 3 and value in scrubbed:
  596. scrubbed = scrubbed.replace(value, "[REDACTED]")
  597. # Also collapse anything that looks like a leaked password-ish token in
  598. # common key=value echoes.
  599. scrubbed = re.sub(r"(password['\"]?\s*[:=]\s*)\S+", r"\1[REDACTED]", scrubbed)
  600. return scrubbed