Skip to content

feat: a nodkey credential plugin for agent-browser logins #104

Open

Description

@groupsky

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-selector and --submit-selector override 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: the agent-browser.plugin.v1 protocol (docs/content/docs/plugins.mdx).
  • A credential.resolve request has profileName, itemRef and url. The answer has username, 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 JSON runs a custom command of the plugin and prints its data.
  • Time limits, fixed in the code (cli/src/plugins.rs): 15 seconds for credential.resolve, 60 seconds for plugin 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)

  1. The plugin. A program that answers plugin.manifest (capability credential.read, plus the custom commands below) and credential.resolve. For credential.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 the url as 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.
  2. TOTP: a custom command, for example plugin run nodkey nodkey.totp --payload '{"itemRef": "...", "url": "..."}'. It returns the current code in data, 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.
  3. 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.
  4. A deny or a time-out answers success: false with a short reason and no value.
  5. The how-to covers the plugin entry in ~/.agent-browser/config.json, and Chrome's "Save password?" prompt (below).

Open questions

  1. 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's timeout setting (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). Then agent-browser auth login --credential-provider nodkey gets the login at once, well inside 15 seconds. It is a nodkey command and not a plugin run command, because agent-browser stops plugin run after 60 seconds. A configurable limit in agent-browser is not needed for this; it could still be asked for later.
  2. itemRef: the item ID from the list, or the item name (names can repeat). Proposed: the ID.
  3. No url in the request: when the agent gives no --url and the profile has none. Proposed: refuse, so the broker always has an origin to check and show.
  4. A separate small program or a nodkey subcommand. agent-browser runs the command from its config.
  5. Protocol changes. v1 is 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 after agent-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-bubble no longer works.
  • An extension that sets chrome.privacy.services.passwordSavingEnabled to false cannot be used: Chrome 153 does not load unpacked extensions from the command line.
  • A profile with "credentials_enable_service": false and "profile": {"password_manager_enabled": false} in its Preferences works: 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:

  1. In Chrome: profile menu, then Add, then "Continue without an account". Name it agents.
  2. In that window, open chrome://password-manager/settings. Turn off "Offer to save passwords" and "Sign in automatically".
  3. Open chrome://settings/addresses and turn off saving and filling of addresses.
  4. Open chrome://settings/payments and turn off saving and filling of payment methods.
  5. 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.
  6. In ~/.agent-browser/config.json, set "profile": "agents".
  7. Check: the profile folder's Preferences file 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 url in 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

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 nodkey logs 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 login then 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 agents profile steps above, tested from start to end: no "Save password?" prompt after auth login.
  • It gets the security review, as every change does.

Related: #103 (logins from a shared Bitwarden collection), #105 (passkeys).

Activity

  1. added this to the later milestone on Oct 21, 2026
  2. groupsky commented on Oct 27, 2026

    @groupsky
    ContributorAuthor

    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"):

    • A plugin is an external program. agent-browser talks to it over the agent-browser.plugin.v1 JSON protocol on stdin and stdout, and the plugin declares the capability credential.read. It is set in ~/.agent-browser/config.json or ./agent-browser.json.
    • agent-browser finds the form, fills the username and the password, and submits. Flags override the guess: --username-selector, --password-selector, --submit-selector.
    • Without --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.
    • The daemon gets the secret from the plugin directly. The README says it stays out of process arguments and normal output.

    So a nodkey plugin for agent-browser could replace most of this issue for agent-browser users. It would answer credential.read with 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:

    1. The fields of a credential.read request. 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.
    2. How the plugin learns the item: --item is 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).
    3. A TOTP step after the password.

    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-bubble no longer works.
    • An extension that sets chrome.privacy.services.passwordSavingEnabled to false cannot be used: Chrome 153 does not load unpacked extensions from the command line.
    • A profile with "credentials_enable_service": false in its Preferences works: 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.

  3. changed the title [-]feat: nodkey web: log in to a website in a CDP browser after a tap[/-] [+]feat: a nodkey credential plugin for agent-browser logins[/+] on Oct 27, 2026
  4. groupsky commented on Oct 27, 2026

    @groupsky
    ContributorAuthor

    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:

  5. groupsky commented on Nov 11, 2026

    @groupsky
    ContributorAuthor

    Wait time for the pre-approval (owner, 2026-11-11). nodkey preapprove --login waits for the tap as long as any other request: the broker's timeout setting (default 120 s, up to 10 min; the owner set 10 min). No lower limit only for logins. The client already waits up to RequestTimeout (10 min + 5 min), so nothing new is needed there.

    Only agent-browser has short fixed limits: 15 s for credential.resolve and 60 s for plugin 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-build builds #103, then #104 (passkeys #105 are not a priority).

  6. groupsky commented on Nov 13, 2026

    @groupsky
    ContributorAuthor

    hq-jobs nodkey-logins-build-2 (run r-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:

    • DESIGN.md and THREAT-MODEL.md. DESIGN.md section 21.10: the plugin, its config entry, the flow, the requests and answers (credential.resolve, nodkey.list, nodkey.totp, plugin.manifest), the errors, and the new no-tap header (Nodkey-No-Tap: 1, answer 428, audit cause no_tap, no message). THREAT-MODEL.md T48 has the points of "What it does not protect".
    • auth login logs in, in a contract test with recorded requests. agent-browser 0.38.1 is pinned in docs/agent-browser.md and PluginVersion. The requests in internal/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. TestPluginContract sends them to the plugin, with a real test broker and a fake bw store. I also ran agent-browser 0.38.1 with the nodkey agent-browser-plugin binary, with no client config: it starts the plugin and shows its refusals. It never reached a broker.
    • Pre-approve, then log in, with a tap after more than 60 s. TestPluginContract: nodkey preapprove --login waits; the test broker's clock moves 100 s before the tap; then the recorded credential.resolve gets the login with no new message. The next login gets "needs a tap" and sends no message.
    • The TOTP command. TestPluginContract: the recorded nodkey.totp returns the RFC 6238 code of the seed, once; the second ask is denied. The agent fills the code.
    • Values not in stderr, normal output or the audit log. TestPluginValuesOnlyInTheCredential (stderr, every answer, the audit log) and TestCredentialAnswer. agent-browser 0.38.1 printed only ✓ Logged in as 'shop' after a login with a test plugin (seen on 2026-11-13).
    • The how-to tested from start to end with the agents profile. Needs Geno. Steps are below.
    • Security review. The security-reviewer agent 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 url is refused; Q4 a nodkey subcommand; Q5 the pinned version and the contract test.

    Found while recording with 0.38.1:

    • agent-browser drops the answer of a plugin that exits with a code that is not 0. So the plugin exits with 0 whenever it wrote an answer.
    • command is not split at spaces, so agent-browser-plugin goes in "args".
    • For auth login, agent-browser shows only "returned success=false", not the error text. docs/agent-browser.md has 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").

    1. On the agent machine, install agent-browser 0.38.1.
    2. Follow docs/agent-browser.md section 1 (the plugin entry) and section 3 (the agents Chrome profile, steps 1 to 7).
    3. Follow section 2 with a test login of the collection: nodkey.list, nodkey preapprove --login, tap, then agent-browser auth login ... --credential-provider nodkey within 60 s.
    4. Check: you are logged in, and Chrome shows no "Save password?" prompt.
    5. If the site has TOTP: nodkey.totp, and check that the code works.
    6. Write the result here and tick the box. You can do the feat: website logins from a shared Bitwarden collection, with TOTP codes made on the broker #103 manual test (a changed password) in the same session.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Projects

    No projects

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions