feat: governed credential capture (a fill in reverse) + a full register→login→capture→execute example

[redbotster]

Asked for from outside: "create a login and store it, log in without the agent seeing, then generate an API key and store it in the vault without the agent seeing, then use that key." Registration + fill already cover the first two. This PR adds the missing direction — capture — and an example that closes the loop with an execution intent.

Capture: a fill in reverse

A fill types a stored secret into a page. A capture reads a site-generated secret (an API key, a token) out of a page and into the vault, while the agent is logged in, without the agent seeing it. Same invariant, same trust model as registration:

• The agent names only a pre-authorised site_id (plus the tab it's logged in on, since a capture reads a secret behind that login). A human authored the URL, the control that generates the value, and where it's read from — so the agent chooses nothing about what gets stored.
• capture-engine.ts opens a windowed page in the agent's own browser context (so the site's session applies), with the agent's target blocked so it can't observe the read. The value is wrapped in a SecretHandle the instant it exists and handed to the backend — it never becomes a tool result. The agent gets {status:"captured", entryId}.
• LocalVaultDriver gains beginCapture/commitCapture/cancelCapture; capabilities().capture is advertised only when a human has written a policy (absent-not-disabled, like registration). A captured secret is written as a normal vault entry, so it's immediately usable as a fill binding.
• 1claw-vault allow-capture authors the policy.

Tests

• capture.test.ts (9): the agent can't choose the source, a secret is never in the grant, cancel writes nothing, commit encrypts and refuses to overwrite.
• capture-real.test.ts (real Chromium): the whole chain — register → fill a login → capture an API key the site issues — and asserts the vault holds exactly the key the site handed out, encrypted, and that the key is in none of the agent's tool results.

pnpm typecheck green, 264 tests pass (5 skipped without Chrome).

The example, and step 3

examples/full-flow-capture.mjs runs register → login → capture, then uses the captured key via examples/intent-executor.mjs — a small local stand-in for the Execution Intents API (POST /v1/agents/{id}/execute): a binding says which vaulted secret and how to inject it; the agent passes params (a city), never the key. Output:

  1. register        -> {"status":"registered","bindingId":"acme"}
  2. before login    -> anonymous
     login fill      -> {"status":"filled","bindingId":"acme"}; agent tab now: ada@example.com
  3. capture key     -> {"status":"captured","entryId":"acme-key"}
  4. execute intent  -> HTTP 200, body {"city":"London","tempC":17}
  agent ever saw the key: no

The executor is deliberately not the production path — the hosted Intents API runs the request inside a TEE with guardrails and audit — but it shows the same property: the credential is used without the agent ever holding it. Wiring capture and the hosted Intents API to a single vault is the natural follow-up.

Note on real sites

Capture works against any site whose key lands in a readable element. Registration still can't do a site that requires email verification (as the README says), so on such a site you'd store the login with 1claw-vault add, let the bridge fill it, and capture the key — the capture path doesn't depend on registration.

🤖 Generated with Claude Code

[redbotster]

Validated the whole capability against a real third-party site, fully automated, no human in the loop and without defeating any anti-bot control:

• OpenWeatherMap was the first target, but its signup is behind reCAPTCHA v2 (a human-check by design), so I did not attempt to bypass it — that's out of bounds. Moved to weatherapi.com, whose signup has only a plain arithmetic prompt ("What is 2 + 4?") and a honeypot, not a captcha.
• Signup: a real browser filled the form, solved the math prompt, left the honeypot blank, ticked the agreement. Email verification came back through an AgentMail inbox; pulled the link, activated the account.
• Login: the bridge filled username + password and clicked the login button — the account's password never reached the agent.
• Capture: the bridge read the real API key off the dashboard's copy button (data-clipboard-text) and stored it in the vault — the key never reached the agent.
• Execute: a live GET api.weatherapi.com/v1/current.json with the injected key returned 200 / current weather, the agent passing only a city.

That surfaced the three real-form gaps this push fixes (username fill, named-submit-button click, capture-from-attribute) — none of which the synthetic fixtures could show, because they pre-filled the username and submitted a plain <form>. The new fill-login-fields.test.ts locks the first two in.

Net: the full "create a login and store it → log in unseen → capture a generated key unseen → use the key" loop runs end to end against a real service.

[kmjones1979]

Merged as f9afe1c. This is a genuinely good piece of work, and the design is right where it matters most.

The part I want to name explicitly, because it is the thing that makes capture safe rather than merely convenient: the agent supplies a site id and the tab it is logged in on, and nothing else. The URL, the control that generates the secret, the selector it is read from, and the vault entry it lands in all come from the human-authored policy. That is what stops "capture" becoming "read arbitrary page content into somewhere I choose" — and it is the same discipline registration already used, applied without being asked to.

The engine earning the fill invariant the same way — window first, read in a target the agent has never scripted, wrap in a SecretHandle the instant the value exists — is exactly right, including the ordering comment about why the window opens before the value exists rather than around the read.

One thing I added. That windowing had no test. I deleted gate.openFillWindow(agentTargetId) and every capture test stayed green — the suite proved the secret does not come back through the return value, and said nothing about whether the agent could simply watch it being read. Those are different claims, and the second is the one a pre-installed listener attacks. Both windowing calls are covered now, and removing either turns it red.

I also integrated the branch with BRIDGE-M2, which landed on main after you opened this: the observe contract gained four fields, and VaultContents required captures/registrations that sealVault already defaults — so every existing caller had to pass captures: [] to say nothing. I made the type describe what the function actually accepts.

On the captcha boundary — you called this exactly right. Moving off OpenWeatherMap because its signup is a reCAPTCHA, rather than trying to get through it, is the correct instinct and I would have asked you to do the same. A human-check is a site saying it wants a human; defeating it is not a capability we build. What your weatherapi.com run proves is the useful thing: everything before and after that gate automates cleanly, and where a site puts one in the middle the flow stops and asks the user. I have written that into the docs as a stated boundary rather than leaving people to discover it.

The three real-form fixes are the kind only a live run produces — a bare form.submit() never authenticating against an ASP.NET postback is not something a synthetic fixture was ever going to teach us.

266 tests, twenty against a launched Chromium.