Repository navigation
Description
Rewritten on 2026-10-27. The first version planned a CDP command of our own (nodkey web list and nodkey web login); it is in the edit history, and in "Not now" below.
Why
Agents drive the browser with agent-browser. A login through nodkey (#103) should:
- keep the password out of the agent's commands and output;
- not fill a page whose origin does not match the login;
- need no person at the screen. The owner only taps Approve on the phone.
agent-browser already has a login command with credential plugins. Decided on 2026-10-27 (owner): support agent-browser only, through its plugin interface. We do not build our own CDP command now.
What agent-browser gives (0.38.1; source read at db57583, 2026-10-23)
agent-browser auth login NAME --credential-provider PLUGIN --item REF [--url URL] [--no-navigate]. It finds the form, fills the username and the password, and submits.--username-selector,--password-selectorand--submit-selectoroverride the guess.- Without
--no-navigate, it first opens the credential's URL. With--no-navigate, it uses the open page, and the page origin (scheme, host, port) must match the credential's URL. - A plugin is a program named in
~/.agent-browser/config.json. agent-browser sends it one JSON request on stdin and reads one JSON answer from stdout: theagent-browser.plugin.v1protocol (docs/content/docs/plugins.mdx). - A
credential.resolverequest hasprofileName,itemRefandurl. The answer hasusername,password,url, and optional selectors. The daemon gets the secret directly. The docs say it stays out of process arguments and normal output. agent-browser plugin run PLUGIN TYPE --payload JSONruns a custom command of the plugin and prints itsdata.- Time limits, fixed in the code (
cli/src/plugins.rs): 15 seconds forcredential.resolve, 60 seconds forplugin run. A tap on the phone often takes longer than 15 seconds, and nodkey waits up to 120 seconds. See open question 1.
Idea (decide the design when the work starts)
- The plugin. A program that answers
plugin.manifest(capabilitycredential.read, plus the custom commands below) andcredential.resolve. Forcredential.resolve, it sends a login request to the broker (feat: website logins from a shared Bitwarden collection, with TOTP codes made on the broker #103) with the item and theurlas the claimed origin. After the tap it answers with the username, the password and the item's matching URL. It writes nothing else to stdout, and never a value to stderr or a log. - TOTP: a custom command, for example
plugin run nodkey nodkey.totp --payload '{"itemRef": "...", "url": "..."}'. It returns the current code indata, and the agent fills it. The approval of the login covers it (feat: website logins from a shared Bitwarden collection, with TOTP codes made on the broker #103, open question 3). The agent sees the code; it is valid for about 30 seconds. - List: a custom command that returns the logins for a URL: item IDs, names and usernames (feat: website logins from a shared Bitwarden collection, with TOTP codes made on the broker #103, step 2). Never a password.
- A deny or a time-out answers
success: falsewith a short reason and no value. - The how-to covers the plugin entry in
~/.agent-browser/config.json, and Chrome's "Save password?" prompt (below).
Open questions
- The 15-second limit: decided on 2026-10-27 (owner): pre-approve first. The agent runs a nodkey command first:
nodkey preapprove --login ITEM --url URL(the grant core of feat: scheduled grants: approve now, use later, with an end time and a number of uses #108). It waits for the tap as long as any other request: the broker'stimeoutsetting (default 120 s, up to 10 min; the owner set 10 min). No extra limit for logins (owner, 2026-11-11). It hands out nothing. The broker then keeps a one-use approval for (client, item, URL) for a short time (feat: website logins from a shared Bitwarden collection, with TOTP codes made on the broker #103, step 9). Thenagent-browser auth login --credential-provider nodkeygets the login at once, well inside 15 seconds. It is a nodkey command and not aplugin runcommand, because agent-browser stopsplugin runafter 60 seconds. A configurable limit in agent-browser is not needed for this; it could still be asked for later. itemRef: the item ID from the list, or the item name (names can repeat). Proposed: the ID.- No
urlin the request: when the agent gives no--urland the profile has none. Proposed: refuse, so the broker always has an origin to check and show. - A separate small program or a
nodkeysubcommand. agent-browser runs thecommandfrom its config. - Protocol changes.
v1is young. Pin a tested agent-browser version in the docs, and add a contract test with recorded requests.
Chrome offers to save the password
A Google Chrome that an agent drives offers to save the filled password in Chrome's own password manager ("Save password?"). Tested on 2026-10-27 with Chrome 153 and agent-browser 0.38.1:
- The prompt shows after
agent-browser fill, and also afteragent-browser auth login --credential-provider(a test plugin with a fake password, on a local test page). A credential plugin does not stop it: Chrome looks at the submitted form, not at how the fields were filled. --disable-save-password-bubbleno longer works.- An extension that sets
chrome.privacy.services.passwordSavingEnabledtofalsecannot be used: Chrome 153 does not load unpacked extensions from the command line. - A profile with
"credentials_enable_service": falseand"profile": {"password_manager_enabled": false}in itsPreferencesworks: no prompt.
Why it matters: the prompt is browser UI, outside the page, so the agent does not see it and is not blocked by it. But a person at the screen can click Save, and with a lasting profile (--profile PATH) the password then stays on the agent machine's disk.
For the how-to: one agents Chrome profile (decided 2026-10-27, owner: document it in nodkey). agent-browser copies a named Chrome profile (--profile NAME, or "profile" in its config) to a temporary folder for each session, so every session starts from this profile. Make the profile in Chrome itself: agent-browser finds profile names in Chrome's Local State file, and a folder made by hand is not found. Once, on the agent machine:
- In Chrome: profile menu, then Add, then "Continue without an account". Name it
agents. - In that window, open
chrome://password-manager/settings. Turn off "Offer to save passwords" and "Sign in automatically". - Open
chrome://settings/addressesand turn off saving and filling of addresses. - Open
chrome://settings/paymentsand turn off saving and filling of payment methods. - Close the window. Do not use this profile by hand, do not sign in to Google in it, and do not add extensions to it: every agent session gets a copy of it.
- In
~/.agent-browser/config.json, set"profile": "agents". - Check: the profile folder's
Preferencesfile has the two settings above, and a test login shows no prompt.
Tested so far: a profile with these Preferences settings. Not yet tested: these steps from start to end.
What it does not protect (for THREAT-MODEL.md)
- The agent can read a filled field, and it gets the session cookies after the login. The tap is the guard; the password is not secret from the agent.
- The
urlin the request is the agent's claim. The broker checks it against the item's URLs and shows it on the phone. agent-browser then checks the real page against the URL in the answer. This protects an agent that is fooled (a fake login page). It does not stop an agent that attacks: it can run the plugin, or call the broker, itself. - A TOTP code passes through the agent's output.
Not now
- Our own CDP command with its own form finding and fill (the first version of this issue). Only if another browser tool must be supported, or agent-browser cannot cover a need.
- Passkeys (feat: passkey logins: the broker signs a WebAuthn assertion after a tap #105). agent-browser has no hook for them. Support enabling WebAuthn for passkey authentication with a virtual authenticator vercel-labs/agent-browser#688 and PR #689 (2026-03 to 2026-05) asked for Chrome's virtual authenticator; both were closed without a merge. That design puts the private key in the browser, which feat: passkey logins: the broker signs a WebAuthn assertion after a tap #105 rules out.
Done when
- DESIGN.md has the plugin, its requests, answers and errors. THREAT-MODEL.md has the points above.
-
agent-browser auth login --credential-provider nodkeylogs in to a test page after a tap, with a pinned agent-browser version, or in a contract test with recorded requests. - Pre-approve, then log in: works when the tap takes more than 60 seconds, and
auth loginthen needs no tap. - The TOTP command works against a test page with a code field.
- A test: the values are not in the plugin's stderr, in agent-browser's normal output, or in the audit log.
- docs: a how-to with agent-browser, with the
agentsprofile steps above, tested from start to end: no "Save password?" prompt afterauth login. - It gets the security review, as every change does.
Related: #103 (logins from a shared Bitwarden collection), #105 (passkeys).
Activity
groupsky commentedon Oct 27, 2026
Found on 2026-10-27: agent-browser already has a login command with credential plugins
agent-browser 0.38.1 has
auth login NAME --credential-provider PLUGIN --item REF(README, sections "Authentication" and "Plugin System"):agent-browser.plugin.v1JSON protocol on stdin and stdout, and the plugin declares the capabilitycredential.read. It is set in~/.agent-browser/config.jsonor./agent-browser.json.--username-selector,--password-selector,--submit-selector.--no-navigate, it first opens the credential's URL. With--no-navigate, it uses the open page and requires the page origin (scheme, host, port) to match the credential's URL.So a nodkey plugin for agent-browser could replace most of this issue for agent-browser users. It would answer
credential.readwith a login request to the broker (#103), and wait for the tap. This issue would then be needed only for other CDP clients, a TOTP page (not seen in agent-browser's docs), and passkeys (#105).To check before choosing:
credential.readrequest. Does agent-browser send the page origin to the plugin? The broker's origin check and the phone message (feat: website logins from a shared Bitwarden collection, with TOTP codes made on the broker #103) need it. If it does not, the broker can return the item's URL, and agent-browser checks the origin on the client side. That still protects an agent that is fooled, but the message on the phone cannot show the page.--itemis a free reference. It could be the item ID from the list (feat: website logins from a shared Bitwarden collection, with TOTP codes made on the broker #103, step 2).Also found: Chrome offers to save the password
A Google Chrome that an agent drives offers to save the filled password in Chrome's own password manager ("Save password?"). Tested with Chrome 153 through agent-browser:
--disable-save-password-bubbleno longer works.chrome.privacy.services.passwordSavingEnabledtofalsecannot be used: Chrome 153 does not load unpacked extensions from the command line."credentials_enable_service": falsein itsPreferencesworks: no prompt. With agent-browser, a named Chrome profile (--profile NAME) is copied to a temporary folder for each session, so a clean profile with this setting can serve as the start of every session.The how-to in this issue should say this.
[-]feat: nodkey web: log in to a website in a CDP browser after a tap[/-][+]feat: a nodkey credential plugin for agent-browser logins[/+]groupsky commentedon Oct 27, 2026
Grants (2026-10-27). The plugin does not change: it asks the broker for a login, and the broker decides if a tap, a pre-approval or a grant covers it.
Two small points for open question 1:
nodkey preapprove --login ITEM --url URL, shared with feat: scheduled grants: approve now, use later, with an end time and a number of uses #108 and feat: standing grants: one tap for a repeating job, built like an API key (end date, rotating token, alarms) #110 (see the comment on feat: website logins from a shared Bitwarden collection, with TOTP codes made on the broker #103).auth logingets its answer at once, inside the 15-second limit. Interactive sessions keep the one-use pre-approval.groupsky commentedon Nov 11, 2026
Wait time for the pre-approval (owner, 2026-11-11).
nodkey preapprove --loginwaits for the tap as long as any other request: the broker'stimeoutsetting (default 120 s, up to 10 min; the owner set 10 min). No lower limit only for logins. The client already waits up toRequestTimeout(10 min + 5 min), so nothing new is needed there.Only agent-browser has short fixed limits: 15 s for
credential.resolveand 60 s forplugin run. That is why the wait runs in a nodkey command and not inside the plugin.The time the one-use approval stays open after the tap (step 9 of #103) is a different thing. It stays short, because the agent uses it at once.
Scheduled: hq job
nodkey-logins-buildbuilds #103, then #104 (passkeys #105 are not a priority).feat: nodkey agent-browser-plugin, the credential plugin for agent-br…
groupsky commentedon Nov 13, 2026
hq-jobs
nodkey-logins-build-2(runr-20261113-180009-1831)Status 2026-11-13: the plugin is built (PR #182)
PR #182 is merged (squash, commit 7858003). No release is made. Evidence for each "Done when" box:
credential.resolve,nodkey.list,nodkey.totp,plugin.manifest), the errors, and the new no-tap header (Nodkey-No-Tap: 1, answer 428, audit causeno_tap, no message). THREAT-MODEL.md T48 has the points of "What it does not protect".auth loginlogs in, in a contract test with recorded requests. agent-browser 0.38.1 is pinned indocs/agent-browser.mdandPluginVersion. The requests ininternal/client/testdata/agent-browser-0.38.1/were written by agent-browser 0.38.1 to a recording plugin, with a local test page on 127.0.0.1.TestPluginContractsends them to the plugin, with a real test broker and a fakebwstore. I also ran agent-browser 0.38.1 with thenodkey agent-browser-pluginbinary, with no client config: it starts the plugin and shows its refusals. It never reached a broker.TestPluginContract:nodkey preapprove --loginwaits; the test broker's clock moves 100 s before the tap; then the recordedcredential.resolvegets the login with no new message. The next login gets "needs a tap" and sends no message.TestPluginContract: the recordednodkey.totpreturns the RFC 6238 code of the seed, once; the second ask is denied. The agent fills the code.TestPluginValuesOnlyInTheCredential(stderr, every answer, the audit log) andTestCredentialAnswer. agent-browser 0.38.1 printed only✓ Logged in as 'shop'after a login with a test plugin (seen on 2026-11-13).agentsprofile. Needs Geno. Steps are below.security-revieweragent found no critical, high or medium problems. It found 4 low ones and 2 small ones (nits). All are fixed in feat: nodkey agent-browser-plugin, the credential plugin for agent-browser (#104) #182.Open questions, as taken: Q1 pre-approve first; Q2 the item ID (a name is refused); Q3 no
urlis refused; Q4 anodkeysubcommand; Q5 the pinned version and the contract test.Found while recording with 0.38.1:
commandis not split at spaces, soagent-browser-plugingoes in"args".auth login, agent-browser shows only "returned success=false", not the error text.docs/agent-browser.mdhas a table of what to do.Steps for Geno: the end-to-end test
You need a release with #181 and #182 (no release is made by this job), on the broker and on the agent machine. The broker needs the setup of #103 (
docs/setup.md, "Website logins: a shared collection").docs/agent-browser.mdsection 1 (the plugin entry) and section 3 (theagentsChrome profile, steps 1 to 7).nodkey.list,nodkey preapprove --login, tap, thenagent-browser auth login ... --credential-provider nodkeywithin 60 s.nodkey.totp, and check that the code works.