browser_vault_tool.py 37 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712
  1. #!/usr/bin/env python3
  2. """Vault-backed model-blind browser autofill tools.
  3. One model-facing tool, ``browser_vault``, deferred behind tool_search (only its catalog line is
  4. paid per request) and available wherever a browser is. Its actions:
  5. - ``list`` → handles + metadata (for logins this includes the
  6. identifier — it is NOT a secret; the agent types it itself). Passwords are
  7. never returned.
  8. - ``fill`` → server-side fill of the CURRENT page from a vault
  9. handle: the password field for logins, card fields for payment items (after
  10. the user confirms), address fields for address items. The secret is
  11. resolved locally, the page origin must EXACTLY match the item's bound
  12. origin (pre-checked AND re-asserted synchronously inside the fill script),
  13. the field is chosen by the ported login-control classifier, injection runs
  14. exclusively over the supervisor CDP WebSocket (never argv) — or, for a plugin browser with no CDP
  15. endpoint, through its registered ``BrowserPageBackend`` (Camofox's REST evaluate) — and the tool
  16. result reports only ``{filled_fields, kind, origin, success}`` — the
  17. password never appears in tool results, logs, or the session DB, and its
  18. exact bytes are registered with the browser-result redaction boundary so
  19. no later browser tool call can echo them back to the model.
  20. - ``enter_code`` → a one-time code for the current page: minted from a saved
  21. login's authenticator key (same origin binding as ``fill``, checked before
  22. the code is generated) or typed by the user into their surface's prompt.
  23. Ported design from Merit-Systems/OpenInstinct (MIT): opaque-handle vault
  24. autofill (kernel-login-autofill.ts / fill_from_vault.ts).
  25. """
  26. from __future__ import annotations
  27. import json
  28. import secrets
  29. import logging
  30. from typing import Any, Dict, Optional
  31. from tools.browser_vault_context import plugin_errors_as_refusal, saved_origins, snapshot_refusal, write_backend_code
  32. logger = logging.getLogger(__name__)
  33. # ---------------------------------------------------------------------------
  34. # Availability check
  35. # ---------------------------------------------------------------------------
  36. def _check_vault_available() -> bool:
  37. """Schema-gate: the vault rides with the browser. An empty vault still needs save_login so the
  38. agent can offer to remember a login the first time it meets a form; hiding the tool until an item
  39. exists meant nobody ever discovered the feature. Deferral keeps that presence nearly free."""
  40. from agent.browser_page_registry import list_providers
  41. from tools.browser_session_cdp import get_cdp_override_raw
  42. from tools.browser_use_cli import browser_exec_available
  43. return bool(browser_exec_available() or get_cdp_override_raw() or list_providers())
  44. # ---------------------------------------------------------------------------
  45. # JS evaluation plumbing (server-side; results never carry secret values)
  46. # ---------------------------------------------------------------------------
  47. # A secret-bearing script runs inside this wrapper on a page backend, so a page exception is answered
  48. # in-page and its message (which may quote the script) never reaches the backend's error path or logs.
  49. _PAGE_FILL_FAILED = {"hermes_vault_eval_failed": True}
  50. def _page_backend(task_id: str):
  51. """The plugin browser holding this task's live page (e.g. Camofox), or None for the CDP session."""
  52. from agent.browser_page_registry import backend_for_task
  53. return backend_for_task(task_id)
  54. def _page_eval(backend: Any, task_id: str, expression: str, *, secret: bool) -> dict[str, Any]:
  55. """Evaluate on a plugin page backend. On the secret path every failure gets fixed text."""
  56. if secret:
  57. expression = ("(() => { try { return (" + expression + "); } catch (_) { return "
  58. + json.dumps(_PAGE_FILL_FAILED) + "; } })()")
  59. try:
  60. result = backend.evaluate(task_id, expression, secret=secret)
  61. except Exception as exc: # health: allow BLE001 -- plugin failure becomes a typed refusal
  62. detail = "" if secret else f": {str(exc)[:200]}"
  63. return {"success": False, "error_type": "eval_failed",
  64. "error": f"The {backend.name} browser could not run the vault script{detail}"}
  65. if secret and _parse_json_result(result) == _PAGE_FILL_FAILED:
  66. return {"success": False, "error_type": "eval_failed",
  67. "error": f"The {backend.name} browser could not run the vault script"}
  68. return {"success": True, "result": result}
  69. def _eval_js(task_id: str, expression: str) -> dict[str, Any]:
  70. """Evaluate NON-SECRET JS on the current page (inspection, origin reads): on the plugin browser
  71. holding the task's page, else over the task's CDP supervisor. Without either the call reports it."""
  72. page = _page_backend(task_id)
  73. if page is not None:
  74. return _page_eval(page, task_id, expression, secret=False)
  75. supervisor = _ensure_supervisor(task_id)
  76. if supervisor is None:
  77. return {"success": False, "error": "no supervised browser session for this task; open the page with "
  78. "browser_exec first"}
  79. sup = supervisor.evaluate_runtime(expression)
  80. if sup.get("ok"):
  81. return {"success": True, "result": sup.get("result")}
  82. return {"success": False, "error": str(sup.get("error") or "evaluate failed")}
  83. def _ensure_supervisor(task_id: str):
  84. """The supervisor for ``task_id`` (browser_exec attaches one on every call), attaching one on demand to
  85. the task's session CDP endpoint when none is running. None when no endpoint is known; a fill then
  86. refuses rather than touching argv."""
  87. from tools.browser_supervisor import SUPERVISOR_REGISTRY
  88. supervisor = SUPERVISOR_REGISTRY.get(task_id)
  89. if supervisor is not None:
  90. return supervisor
  91. from tools.browser_session import session_for_task
  92. from tools.browser_session_cdp import get_dialog_policy_config, resolve_cdp_override
  93. cdp_url = str(session_for_task(task_id).get("cdp_url") or "")
  94. if not cdp_url:
  95. return None
  96. policy, timeout_s = get_dialog_policy_config()
  97. try:
  98. return SUPERVISOR_REGISTRY.get_or_start(task_id=task_id, cdp_url=resolve_cdp_override(cdp_url),
  99. dialog_policy=policy, dialog_timeout_s=timeout_s)
  100. except Exception as exc: # health: allow BLE001 -- a failed attach is reported as supervisor_required
  101. logger.debug("vault fill: supervisor attach to the task's session failed (%s)", exc)
  102. return None
  103. def _eval_js_secret(task_id: str, expression: str) -> dict[str, Any]:
  104. """Evaluate a SECRET-BEARING JS expression. Supervisor CDP-WS only.
  105. Fails closed: there is deliberately NO subprocess path, because that would
  106. place the expression — and therefore the credential bytes — in argv,
  107. visible to any process listing. When no supervisor session is available
  108. the caller gets a typed refusal (``error_type='supervisor_required'``) and
  109. nothing is written. A plugin browser holding the task's page (no CDP endpoint) carries the
  110. expression over its own transport instead; see ``agent.browser_page_backend``.
  111. """
  112. page = _page_backend(task_id)
  113. supervisor = None
  114. if page is None:
  115. try:
  116. supervisor = _ensure_supervisor(task_id)
  117. except Exception as exc:
  118. logger.debug("vault fill: supervisor unavailable (%s)", exc)
  119. if page is None and supervisor is None:
  120. return {
  121. "success": False,
  122. "error_type": "supervisor_required",
  123. "error": (
  124. "Vault fill requires the supervised browser session (direct "
  125. "CDP WebSocket), and this task has none. Open the page with "
  126. "browser_exec and retry."
  127. ),
  128. }
  129. # Re-admit at the WRITE. The handler-level fence (_fenced_page_op) admitted before a possibly
  130. # human-length prompt (enter_code waits for the user's code); a takeover during that wait must
  131. # refuse here, before the credential lands in a page the human is now typing into. The outer
  132. # epoch check only discards the result, and a fill is a side effect, not a result.
  133. if _bot_desktop_browser_session(task_id):
  134. from tools.bot_desktop import lease as _bd_lease
  135. try:
  136. _bd_lease.assert_agent_may_act()
  137. except _bd_lease.HumanHasControl as exc:
  138. return {"success": False, "error_type": "human_has_control", "error": str(exc)}
  139. if page is not None:
  140. return _page_eval(page, task_id, expression, secret=True)
  141. sup = supervisor.evaluate_runtime(expression)
  142. if sup.get("ok"):
  143. return {"success": True, "result": sup.get("result")}
  144. return {
  145. "success": False,
  146. "error_type": "supervisor_required"
  147. if "supervisor" in str(sup.get("error") or "").lower()
  148. else "eval_failed",
  149. "error": str(sup.get("error") or "eval failed"),
  150. }
  151. def _parse_json_result(raw: Any) -> Any:
  152. if isinstance(raw, str):
  153. try:
  154. return json.loads(raw)
  155. except (json.JSONDecodeError, ValueError):
  156. return raw
  157. return raw
  158. def _current_page_origin(task_id: str) -> Optional[str]:
  159. res = _eval_js(task_id, "window.location.href")
  160. if not res.get("success"):
  161. return None
  162. href = str(res.get("result") or "").strip().strip('"').strip("'")
  163. if not href or href == "about:blank":
  164. return None
  165. try:
  166. from agent.vault_store import normalize_origin
  167. return normalize_origin(href)
  168. except Exception:
  169. return None
  170. def _deep_probe(selector: str) -> str:
  171. """A JS expression truthy when ``selector`` matches in the document or any open shadow root (the
  172. inspection and fill scripts reach shadow-root forms, so tab selection must too)."""
  173. return ("((s) => { const w = (r) => r.querySelector(s) || Array.from(r.querySelectorAll('*'))"
  174. ".some((e) => e.shadowRoot && w(e.shadowRoot)); return !!w(document); })(" + json.dumps(selector) + ")")
  175. # Per kind: a JS probe that is truthy on a tab holding the form this kind fills.
  176. _TAB_PROBES = {
  177. "login": _deep_probe("input[type=password]"),
  178. "payment": _deep_probe("input[autocomplete^=cc-], [name*=card i], [placeholder*=card i], [name*=cvc i], [name*=cvv i]"),
  179. "address": _deep_probe("input[autocomplete^=address-], [autocomplete=postal-code], [name*=address i], [name*=zip i], [name*=postal i]"),
  180. }
  181. def _focus_bound_origin(task_id: str, origin: str, kind: str) -> Optional[str]:
  182. """Point the supervisor's page session at the open tab on ``origin`` that holds a ``kind`` form
  183. (browser_exec sessions open their own tabs, so the tab the supervisor attached to first is rarely the
  184. login page). Returns the origin when a tab was focused, else None (caller falls back to the current page).
  185. A plugin page backend's current page IS the tab the agent drove, so there is nothing to focus."""
  186. if _page_backend(task_id) is not None:
  187. return None
  188. try:
  189. supervisor = _ensure_supervisor(task_id)
  190. except Exception:
  191. supervisor = None
  192. if supervisor is None:
  193. return None
  194. focused = supervisor.focus_page(origin, accept=_TAB_PROBES.get(kind))
  195. return (origin or focused.get("url")) if focused.get("ok") else None
  196. def _bound_page_origin(task_id: str, meta: Any, probe_kind: str) -> str | dict[str, Any]:
  197. """The origin guard every fill of a stored secret (password, one-time code, card, address) passes
  198. BEFORE the backend resolves any value: the page origin when it is one of the item's saved origins,
  199. else the refusal to return. Manager items may bind several websites; matching is exact and
  200. nothing wildcard or parent-domain is inferred. The caller hands the returned origin to ``build_fill_js``,
  201. which re-asserts it inside the page immediately before the write (navigation between check and fill)."""
  202. allowed = saved_origins(meta)
  203. if not allowed:
  204. return {"success": False, "error_type": "no_origin",
  205. "error": f"Vault item {meta.id!r} has no bound origin; {meta.kind} items are filled only on "
  206. "the site they were saved for."}
  207. page_origin = next((o for o in (_focus_bound_origin(task_id, c, probe_kind) for c in allowed) if o), None)
  208. page_origin = page_origin or _current_page_origin(task_id)
  209. if not page_origin:
  210. return {"success": False,
  211. "error": "Could not determine the current page origin. Navigate to the login page first."}
  212. if page_origin not in allowed:
  213. return {"success": False, "error_type": "origin_mismatch",
  214. "error": (f"Refused: current page origin ({page_origin}) does not match the vault item's bound "
  215. f"origin(s) ({', '.join(allowed)}). Vault fills only run on the exact origin(s) the "
  216. "credential was saved for.")}
  217. return page_origin
  218. # ---------------------------------------------------------------------------
  219. # Handlers
  220. # ---------------------------------------------------------------------------
  221. def browser_vault_list() -> str:
  222. """List login handles + metadata across every enabled backend. Passwords are never included.
  223. A locked external manager contributes no items; instead it is reported under ``locked`` so the
  224. agent knows to call fill (which prompts the user to unlock) or tell the user.
  225. """
  226. from agent.vault_backends import enabled_backends
  227. from agent.vault_backends.unlock import can_prompt_here
  228. items, locked, errors = [], [], []
  229. for backend in enabled_backends():
  230. if backend.needs_unlock and not backend.is_unlocked():
  231. locked.append({"backend": backend.name, "display_name": backend.display_name,
  232. "unlock": "browser_vault action=unlock" if can_prompt_here() else "unavailable_in_this_session"})
  233. continue
  234. try:
  235. metas = backend.list_items()
  236. except Exception as exc:
  237. errors.append({"backend": backend.name, "error": str(exc)[:200]})
  238. continue
  239. for meta in metas:
  240. entry = {"handle": meta.id, "backend": backend.name, "label": meta.label, "kind": meta.kind,
  241. "origin": meta.origin, "available": meta.kind == "login" or bool(meta.origin)}
  242. if len(meta.allowed_origins) > 1:
  243. entry["allowed_origins"] = list(meta.allowed_origins)
  244. if meta.has_otp or backend.needs_unlock:
  245. entry["two_factor"] = "automatic" if meta.has_otp else "automatic if the manager stores a TOTP seed, else the user is asked"
  246. if meta.identifier:
  247. entry["identifier"] = meta.identifier
  248. entry["identifier_type"] = meta.identifier_type
  249. items.append(entry)
  250. out: dict[str, Any] = {"success": True, "items": items}
  251. if not items:
  252. out["hint"] = ("No saved logins. On a login page, call browser_vault action=save_login to ask the user to save one. "
  253. "Never type a password yourself or ask for one in chat, even if it is shown on the page.")
  254. if locked:
  255. out["locked"] = locked
  256. if errors:
  257. out["errors"] = errors
  258. return json.dumps(out, ensure_ascii=False)
  259. def browser_vault_unlock(backend_name: str) -> str:
  260. """Ask the user (via the surface's masked prompt) to unlock an external manager for this session."""
  261. from agent.vault_backends import enabled_backends
  262. from agent.vault_backends.unlock import can_prompt_here, get_unlock_prompt_callback
  263. backend = next((b for b in enabled_backends() if b.name == backend_name and b.needs_unlock), None)
  264. if backend is None:
  265. return json.dumps({"success": False, "error": f"No unlockable vault backend named {backend_name!r}."})
  266. if backend.is_unlocked():
  267. return json.dumps({"success": True, "backend": backend.name, "already_unlocked": True})
  268. if not can_prompt_here():
  269. return json.dumps({"success": False, "error_type": "unlock_unavailable",
  270. "error": (f"{backend.display_name} is locked and this session cannot prompt for the "
  271. "master password (headless/cron/API). Unlock it from an interactive Hermes "
  272. "session or the Desktop app first.")})
  273. prompt = get_unlock_prompt_callback()
  274. master = prompt(backend.name, backend.display_name) if prompt else ""
  275. if not master:
  276. return json.dumps({"success": False, "error_type": "unlock_cancelled",
  277. "error": f"The user declined to unlock {backend.display_name}."})
  278. try:
  279. backend.unlock(master) # type: ignore[attr-defined]
  280. except Exception as exc:
  281. return json.dumps({"success": False, "error_type": "unlock_failed", "error": str(exc)[:300]})
  282. finally:
  283. del master
  284. return json.dumps({"success": True, "backend": backend.name})
  285. def browser_vault_save_login(label: str = "", task_id: Optional[str] = None) -> str:
  286. """Ask the user (masked prompt on their surface) for the login of the CURRENT page, store it in the local
  287. vault bound to that origin, and fill the password at once. The values never enter the conversation."""
  288. from agent.vault_backends.unlock import can_prompt_here, get_save_login_prompt_callback
  289. from agent.vault_store import get_vault_store
  290. effective_task_id = task_id or "default"
  291. # The supervisor's default page session is whatever tab it attached to first (on Browser Use that is
  292. # the daemon's blank tab); the login form lives in the tab with a password field, so focus that one.
  293. _focus_bound_origin(effective_task_id, "", "login")
  294. origin = _current_page_origin(effective_task_id)
  295. if not origin:
  296. return json.dumps({"success": False, "error": "Open the site's login page first; the login is saved for that page's origin."})
  297. prompt = get_save_login_prompt_callback()
  298. if prompt is None or not can_prompt_here():
  299. return json.dumps({"success": False, "error_type": "prompt_unavailable",
  300. "error": (f"This session cannot ask the user for a login (headless/cron/API). Tell them to run "
  301. f"`hermes vault add` or use Desktop → Settings → Passwords & Logins for {origin}.")})
  302. host = origin.split("://", 1)[-1]
  303. site = label.strip() or host
  304. answer = prompt(origin, host) # the prompt names the site by host: the user recognises URLs, not agent labels
  305. if not answer or not answer.get("password") or not answer.get("identifier"):
  306. return json.dumps({"success": False, "error_type": "save_declined",
  307. "error": "The user chose not to save a login for this site. Do not ask again this turn."})
  308. identifier = str(answer["identifier"]).strip()
  309. id_type = "email" if "@" in identifier else ("phone" if identifier.lstrip("+").isdigit() else "username")
  310. try:
  311. meta = get_vault_store().add_item("login", site, {"identifier_type": id_type, "identifier": identifier,
  312. "password": str(answer["password"])}, origin=origin)
  313. except Exception as exc:
  314. return json.dumps({"success": False, "error_type": "save_failed", "error": str(exc)[:200]})
  315. finally:
  316. answer.clear()
  317. filled = json.loads(browser_vault_fill(meta.id, task_id=effective_task_id))
  318. return json.dumps({"success": True, "handle": meta.id, "origin": origin, "identifier": identifier,
  319. "identifier_type": id_type, "fill": filled,
  320. "next": "Type the identifier into the username field if the form has one, then submit."},
  321. ensure_ascii=False)
  322. _TAB_PROBES["otp"] = _deep_probe("input[autocomplete=one-time-code], input[name*=otp i], input[name*=code i], "
  323. "input[id*=otp i], input[id*=code i], input[name*=totp i], input[aria-label*=code i]")
  324. def _saved_login(handle: str) -> tuple[Any, Any]:
  325. """(backend, meta) for a vault handle, or (None, None) when nothing is saved under it (or its manager is
  326. locked): enter_code then asks the user instead of minting a code."""
  327. from agent.vault_backends import UnlockRequired, backend_for_handle
  328. backend = backend_for_handle(handle) if handle else None
  329. if backend is None:
  330. return None, None
  331. try:
  332. return backend, backend.get_meta(handle)
  333. except UnlockRequired:
  334. return backend, None
  335. @plugin_errors_as_refusal
  336. def browser_vault_enter_code(handle: str = "", task_id: Optional[str] = None) -> str:
  337. """Second factor: fill the one-time code the CURRENT page asks for. If the saved login (``handle``) has an
  338. authenticator seed, the code is minted server-side and nobody is asked; otherwise the user is prompted on
  339. their surface for the code their phone/email/app shows. The code goes into the page over the supervisor
  340. socket and never enters the conversation. A saved login's code is only minted on its saved origin(s)."""
  341. from agent.redact import register_vault_redaction_value
  342. from agent.vault_backends.unlock import can_prompt_here, get_code_prompt_callback
  343. from agent.vault_login_classifier import LoginControl, build_fill_js, build_inspection_js, build_otp_fills, classify_otp_controls
  344. effective_task_id = task_id or "default"
  345. backend, meta = _saved_login(handle)
  346. if meta is not None:
  347. bound = _bound_page_origin(effective_task_id, meta, "otp")
  348. if isinstance(bound, dict):
  349. if bound.get("error_type") == "origin_mismatch":
  350. bound["next"] = ("If this page asks for the code of a different account, call enter_code without a "
  351. "handle so the user is asked.")
  352. return json.dumps(bound)
  353. origin = bound
  354. else:
  355. _focus_bound_origin(effective_task_id, "", "otp")
  356. origin = _current_page_origin(effective_task_id)
  357. if not origin:
  358. return json.dumps({"success": False, "error": "No page with a code field is open."})
  359. site = origin.split("://", 1)[-1]
  360. nonce = secrets.token_hex(8)
  361. inspect = _eval_js(effective_task_id, build_inspection_js(nonce))
  362. raw_controls = _parse_json_result(inspect.get("result")) if inspect.get("success") else None
  363. if isinstance(raw_controls, str):
  364. raw_controls = _parse_json_result(raw_controls)
  365. otp_controls = classify_otp_controls([LoginControl.from_dict(r) for r in (raw_controls or []) if isinstance(r, dict)])
  366. if not otp_controls:
  367. return json.dumps({"success": False, "error_type": "no_code_field",
  368. "error": ("No one-time-code field on the current page. If the site wants a passkey, hardware key or "
  369. "an approval tap in an app, tell the user to complete it on their device and wait for the page to move on.")})
  370. def write(code: str, source: str) -> str:
  371. register_vault_redaction_value(code)
  372. fills = build_otp_fills(otp_controls, code)
  373. result = _eval_js_secret(effective_task_id, build_fill_js(fills, expected_origin=origin, nonce=nonce))
  374. del code
  375. if not result.get("success"):
  376. return json.dumps({"success": False, "error": str(result.get("error") or "fill failed")[:200]})
  377. parsed = _parse_json_result(result.get("result"))
  378. if isinstance(parsed, str):
  379. parsed = _parse_json_result(parsed)
  380. if isinstance(parsed, dict) and parsed.get("refused") == "origin_changed":
  381. return json.dumps({"success": False, "error_type": "origin_changed", "error": "The page navigated before the code could be entered. Nothing was written."})
  382. filled = int(parsed.get("filled", 0)) if isinstance(parsed, dict) else 0
  383. return json.dumps({"success": bool(filled), "filled_fields": filled, "origin": origin, "source": source,
  384. "next": "Submit the form (many sites auto-submit when the last digit lands)."})
  385. if meta is not None: # a saved login on its bound origin: mint + write inside the backend's fill_context
  386. written = write_backend_code(backend, handle, meta, origin, lambda code: write(code, backend.name))
  387. if written is not None:
  388. return written
  389. prompt = get_code_prompt_callback()
  390. if prompt is None or not can_prompt_here():
  391. return json.dumps({"success": False, "error_type": "prompt_unavailable",
  392. "error": (f"{site} asks for a one-time code and this session cannot ask the user (headless/cron/API). "
  393. "Save an authenticator key for this login so codes can be generated automatically.")})
  394. code = (prompt(site, "") or "").strip().replace(" ", "").replace("-", "")
  395. if not code:
  396. return json.dumps({"success": False, "error_type": "code_declined",
  397. "error": "The user did not enter a code. Do not ask again this turn."})
  398. return write(code, "user")
  399. @plugin_errors_as_refusal
  400. def browser_vault_fill(handle: str, task_id: Optional[str] = None) -> str:
  401. """Fill the current page's password field from a vault handle.
  402. Password-only: the identifier is agent-visible metadata (see
  403. browser_vault_list) and is typed by the agent via normal input tools.
  404. The password is resolved server-side and injected via in-page JS over
  405. the supervisor CDP WebSocket; the result reports only counts/metadata.
  406. """
  407. from agent.vault_backends import UnlockRequired, backend_for_handle
  408. effective_task_id = task_id or "default"
  409. backend = backend_for_handle(handle)
  410. if backend is not None and backend.needs_unlock and not backend.is_unlocked():
  411. unlocked = json.loads(browser_vault_unlock(backend.name))
  412. if not unlocked.get("success"):
  413. return json.dumps(unlocked)
  414. try:
  415. meta = backend.get_meta(handle) if backend is not None else None
  416. except UnlockRequired:
  417. return json.dumps({"success": False, "error_type": "unlock_required",
  418. "error": f"{backend.display_name} locked again; call browser_vault action=unlock."})
  419. if meta is None:
  420. return json.dumps(
  421. {
  422. "success": False,
  423. "error": (
  424. f"No vault item with handle {handle!r}. Use browser_vault action=list. "
  425. "To save a credential: run `hermes vault add` in a terminal, or "
  426. "in the desktop app open Settings → Credential Vault."
  427. ),
  428. }
  429. )
  430. # Origin binding pre-check (the authoritative re-check runs inside the fill script), before the user is
  431. # asked to confirm a card, before the backend's fill_context is entered and before any value is resolved.
  432. page_origin = _bound_page_origin(effective_task_id, meta, meta.kind)
  433. if isinstance(page_origin, dict):
  434. return json.dumps(page_origin)
  435. if meta.kind == "payment" and not _confirm_payment_fill(meta.label, page_origin):
  436. return json.dumps({"success": False, "error_type": "payment_declined",
  437. "error": "The user did not confirm filling this payment card. Do not retry; ask them instead."})
  438. with backend.fill_context():
  439. refusal = snapshot_refusal(backend, handle, meta, page_origin)
  440. if refusal is not None:
  441. return json.dumps(refusal)
  442. return _fill_bound_page(backend, handle, meta, page_origin, effective_task_id)
  443. def _fill_bound_page(backend: Any, handle: str, meta: Any, page_origin: str, effective_task_id: str) -> str:
  444. """Inspect the page, resolve the item's secret and write it; runs inside the backend's fill_context
  445. after the origin guard passed."""
  446. from agent.redact import register_vault_redaction_value
  447. from agent.vault_login_classifier import (
  448. ClassifiedLoginControl,
  449. LoginControl,
  450. build_fill_js,
  451. build_inspection_js,
  452. classify_checkout_control,
  453. classify_login_control,
  454. select_checkout_fills,
  455. select_password_fill,
  456. )
  457. from agent.vault_backends import UnlockRequired
  458. from agent.vault_store import ADDRESS_FIELDS, PAYMENT_FIELDS, scrub_secret_from_text
  459. # ── Inspect + classify page controls ────────────────────────────────────
  460. nonce = secrets.token_hex(8) # binds this fill to THIS inspection's stamps
  461. inspect = _eval_js(effective_task_id, build_inspection_js(nonce))
  462. if not inspect.get("success"):
  463. return json.dumps(
  464. {"success": False, "error": f"Could not inspect page inputs: {inspect.get('error', 'eval failed')}"}
  465. )
  466. raw_controls = _parse_json_result(inspect.get("result"))
  467. if isinstance(raw_controls, str):
  468. raw_controls = _parse_json_result(raw_controls)
  469. if not isinstance(raw_controls, list):
  470. return json.dumps({"success": False, "error": "Page input inspection returned no usable controls."})
  471. classify = classify_login_control if meta.kind == "login" else classify_checkout_control
  472. classified: list[ClassifiedLoginControl] = []
  473. for raw in raw_controls:
  474. if not isinstance(raw, dict):
  475. continue
  476. result = classify(LoginControl.from_dict(raw))
  477. if result is not None:
  478. classified.append(result)
  479. if not classified:
  480. return json.dumps({"success": False, "error": f"No {meta.kind} form fields were found on the current page."})
  481. # ── Resolve secret and fill (secret never enters any logged string) ─────
  482. try:
  483. if meta.kind == "login":
  484. secret = {"password": backend.resolve_password(handle)}
  485. fills = select_password_fill(classified, secret["password"])
  486. else:
  487. secret = backend.resolve_secret(handle)
  488. fills = select_checkout_fills(classified, secret, PAYMENT_FIELDS if meta.kind == "payment" else ADDRESS_FIELDS)
  489. except UnlockRequired:
  490. return json.dumps({"success": False, "error_type": "unlock_required",
  491. "error": f"{backend.display_name} locked again; call browser_vault action=unlock."})
  492. if not fills:
  493. return json.dumps(
  494. {"success": False, "error": f"No fillable {meta.kind} field matched the saved item on this page."}
  495. )
  496. # Register the secret bytes with the model-egress redaction boundary
  497. # BEFORE they touch the page: any later browser_* result (including
  498. # browser_cdp Runtime.evaluate reads) that echoes them is scrubbed.
  499. # Address values are not secrets but the card fields are: register every payment value.
  500. for value in (secret.values() if meta.kind == "payment" else [secret.get("password", "")]):
  501. register_vault_redaction_value(value)
  502. try:
  503. fill_result = _eval_js_secret(
  504. effective_task_id, build_fill_js(fills, expected_origin=page_origin, nonce=nonce)
  505. )
  506. except Exception as exc: # health: allow BLE001 -- any CDP failure becomes a typed result; its text is scrubbed of the secret
  507. return json.dumps(
  508. {"success": False, "error": scrub_secret_from_text(str(exc), secret)}
  509. )
  510. if not fill_result.get("success"):
  511. err = scrub_secret_from_text(str(fill_result.get("error") or "fill failed"), secret)
  512. out = {"success": False, "error": err}
  513. if fill_result.get("error_type"):
  514. out["error_type"] = fill_result["error_type"]
  515. return json.dumps(out)
  516. parsed = _parse_json_result(fill_result.get("result"))
  517. if isinstance(parsed, str):
  518. parsed = _parse_json_result(parsed)
  519. if isinstance(parsed, dict) and parsed.get("refused") == "origin_changed":
  520. return json.dumps(
  521. {
  522. "success": False,
  523. "error_type": "origin_changed",
  524. "error": (
  525. "Refused: the page navigated away from the bound origin "
  526. f"({page_origin}) before the fill could run "
  527. f"(now on {parsed.get('found') or 'unknown'}). "
  528. "Nothing was written."
  529. ),
  530. }
  531. )
  532. filled = parsed.get("filled", 0) if isinstance(parsed, dict) else 0
  533. out = {"success": bool(filled), "filled_fields": int(filled), "backend": backend.name,
  534. "kind": meta.kind, "origin": page_origin}
  535. if meta.kind == "login":
  536. out["next"] = ("Submit. If the site then asks for a verification code, call browser_vault action=enter_code with this handle"
  537. + (" (a code will be generated automatically)." if meta.has_otp else "."))
  538. if meta.kind != "login":
  539. out["fields"] = sorted(f["token"] for f in fills) # which controls were targeted, never the values
  540. return json.dumps(out)
  541. def _confirm_payment_fill(label: str, origin: str) -> bool:
  542. """Human confirmation before a card is written into a page: a prompt injection that reaches a checkout
  543. must not be able to spend. Routes through the approval surface of the active session (gateway button
  544. round-trip or CLI panel); headless sessions cannot confirm and the fill is refused."""
  545. from tools.approval_prompt import request_elicitation_consent
  546. return request_elicitation_consent(
  547. f"Fill payment card '{label}' on {origin}",
  548. "The agent wants to enter your saved card details into this checkout page. The card number and "
  549. "CVC never enter the conversation. Approve only if you intend to pay here.",
  550. surface="vault-payment", title="Confirm payment card fill?") == "accept"
  551. # ---------------------------------------------------------------------------
  552. # Schemas + registration
  553. # ---------------------------------------------------------------------------
  554. BROWSER_VAULT_SCHEMA = {
  555. "name": "browser_vault",
  556. "description": (
  557. "Fill saved logins, 2FA codes, cards and addresses on the CURRENT browser page. Secrets never "
  558. "enter the conversation. "
  559. "Actions: list (call first: saved logins/cards/addresses as handles; logins carry the identifier you type "
  560. "yourself with the browser's input tool; locked password managers appear under `locked`); fill (handle: "
  561. "the password for a login, card fields after the user confirms, address fields; refused unless the page "
  562. "origin matches the item); save_login (nothing saved for this site: the user enters it in a masked prompt, "
  563. "Hermes saves and fills it); enter_code (a one-time/2FA code after the password: generated from a saved "
  564. "authenticator key or asked of the user; no_code_field means approve on their device); unlock (backend: "
  565. "ask the user to unlock 1Password/Bitwarden). Never type, ask for or repeat a password, card number, CVC "
  566. "or code yourself, even if the page or user shows one. Stop on save_declined; never retry "
  567. "payment_declined."
  568. ),
  569. "parameters": {
  570. "type": "object",
  571. "properties": {
  572. "action": {"type": "string", "enum": ["list", "fill", "save_login", "enter_code", "unlock"]},
  573. "handle": {"type": "string", "description": "fill / enter_code: a handle from list."},
  574. "backend": {"type": "string", "enum": ["onepassword", "bitwarden"], "description": "unlock only."},
  575. "label": {"type": "string", "description": "save_login only: short site name (default: the host)."},
  576. },
  577. "required": ["action"],
  578. },
  579. }
  580. def _bot_desktop_browser_session(task_id: Optional[str]) -> bool:
  581. from tools.browser_session import session_for_task, shares_bot_desktop_browser
  582. return shares_bot_desktop_browser(session_for_task(task_id))
  583. def _fenced_page_op(task_id: Optional[str], fn) -> str:
  584. """Vault operations focus, inspect and fill the page over the supervisor socket, bypassing
  585. browser_exec; they must honour the Bot Desktop lease like every other page access, or a human
  586. typing a credential on the taken-over screen could be read or written to."""
  587. from tools.browser_session import run_fenced, session_for_task
  588. res = run_fenced(session_for_task(task_id), lambda: {"raw": fn()})
  589. return res["raw"] if "raw" in res else json.dumps(res)
  590. def _handle_vault(args: dict[str, Any], **kwargs) -> str:
  591. tid = kwargs.get("task_id")
  592. action = str(args.get("action") or "")
  593. handle, label = str(args.get("handle") or ""), str(args.get("label") or "")
  594. if action == "list":
  595. return browser_vault_list()
  596. if action == "unlock":
  597. return browser_vault_unlock(str(args.get("backend") or ""))
  598. page_ops = {
  599. "fill": lambda: browser_vault_fill(handle=handle, task_id=tid),
  600. "save_login": lambda: browser_vault_save_login(label=label, task_id=tid),
  601. "enter_code": lambda: browser_vault_enter_code(handle=handle, task_id=tid),
  602. }
  603. if action not in page_ops:
  604. return json.dumps({"success": False, "error": f"Unknown action {action!r}; use list, fill, save_login, "
  605. "enter_code or unlock."})
  606. return _fenced_page_op(tid, page_ops[action])
  607. from tools.registry import no_cache_check_fn, registry
  608. _check_vault_available = no_cache_check_fn(_check_vault_available)
  609. registry.register(
  610. name="browser_vault",
  611. toolset="browser",
  612. schema=BROWSER_VAULT_SCHEMA,
  613. handler=_handle_vault,
  614. check_fn=_check_vault_available,
  615. emoji="🔐",
  616. )