Repository navigation
Description
Why
Agents log in to websites with a browser that they drive (agent-browser, or any browser over the Chrome DevTools Protocol). Today the easy way is to unlock the owner's password manager in that browser. Then the agent can read the whole vault: it can open the extension's own page in a tab and show every item.
The owner wants:
- one tap on the phone for each login;
- only the logins that the owner chose;
- the same items that the owner uses. A password changed in the owner's vault must reach nodkey with no second copy to update.
The bw store reads login items already, but only login.password, and only for an item ID written in broker.toml (DESIGN.md section 16, "Store programs").
Idea (decide the design when the work starts)
Owner setup, no nodkey code. The owner's main Bitwarden account makes an organization with a collection, for example agents. The separate account of the broker's bw store is the second member, with access to that collection only, and with "Can view" rights: it cannot change items. The Free plan allows 2 users and 2 collections (https://bitwarden.com/help/what-is-an-organization/, seen 2026-10-21). The owner moves the logins that agents may use into the collection. The owner still sees, autofills and edits them in the normal vault. The broker runs bw sync --force before each fetch (section 16), so a changed password is used on the next request.
The master password on the broker still opens only what the separate account can see (section 11): the collection, not the owner's vault.
Broker.
-
Config. A new section names a store and a collection, with clients and one rule for all items in it, and an optional rule per item. Putting an item into the collection is the "allow" step: no config edit, no restart. A sketch:
[logins.web] store = "vault" # a bw store collection = "00000000-0000-0000-0000-000000000000" clients = ["laptop"] ask = "window" window = "15m"
-
List. The client sends an origin. The broker returns the items of the collection that have a URI that matches it: item ID, item name and username. Never a password. Proposed: no tap (open question 1).
-
Login. The client sends an origin and one item ID from the list. The broker checks that the item is in the collection, is a login item, is not in the trash and not archived, and has a URI that matches the origin. The message shows the item name and the username as read from Bitwarden, and the origin as claimed by the client, for example: "log in to https://example.com as alice@example.com (Example shop), from laptop". On approval the broker returns the username and the password.
-
TOTP. When the item has
login.totp, the broker makes the current code itself. The seed never leaves the broker. The client asks for the code after the password step, when the site shows its code page. The approval of the login covers that one code for a short time (open question 3). -
URI match. Follow Bitwarden's match type of each URI: base domain (the default), host, starts with, exact. A regular expression and "never" do not match. Only
httpsorigins. -
Several logins for one site. The list shows them all; the client names one item ID. The origin must match that item.
-
Grants cover (client, item), not a whole site. A grant for one login does not hand out another login of the same site.
-
Audit log. New events for list, login and TOTP, with the origin, the item ID and the client.
-
Pre-approval (decided 2026-10-27, owner; needed by feat: a nodkey credential plugin for agent-browser logins #104). A request that asks for a tap and hands out nothing. The message says what the tap allows, for example: "approve one login to https://example.com as alice@example.com (Example shop), from laptop, in the next 60 s". After the tap, the broker keeps a one-use approval for (client, item, origin) for a short time. The next login request with the same three gets the login without a tap, and uses the approval up. It works for items with
ask = "always"too. Why: agent-browser waits only 15 seconds for a credential plugin, and a tap often takes longer.
Open questions
- A list without a tap? It shows item names and usernames to the agent machine. A tap just to see a list teaches the approver to tap without reading. Proposed: no tap, a rate limit, and an audit entry.
bw list items --collectionid IDreturns whole items, passwords too. The broker must read only the fields it needs and clear the rest, as section 16 says forbw get item. A list also runs a fullbw sync --force.- The TOTP step: how long it stays open after the login approval (for example 2 minutes, one code), and whether a
windowgrant also covers later codes. - Base domain needs the public suffix list (
example.co.uk). Which source:golang.org/x/net/publicsuffix(a new dependency) or another. - A URI with no match type uses the default of the Bitwarden app, which is a local setting the CLI cannot read. Proposed: base domain.
- TOTP forms: a plain base32 secret, an
otpauth://URI with other digits, period or algorithm, andsteam://. Which ones to support; refuse the rest. httporigins of devices on the local network (a router page, a home server). Refuse at first, or allow them per item?- THREAT-MODEL.md T32 says no account that can read the secrets may be logged in on an agent machine. The owner's main account owns the organization and can read the collection. These are the owner's own logins, so the rule needs new words: the separate account stays off agent machines, and the owner's vault is never unlocked in a browser or app that an agent can drive.
Done when
- DESIGN.md has the logins section, the list, login and TOTP requests, URI matching, the messages and the audit events. THREAT-MODEL.md has the new threats: an origin claimed by the client, usernames on the agent machine, TOTP seeds read by the broker, and the owner's vault open in a browser that an agent drives.
- docs/setup.md shows the organization and the collection step by step, with the Free plan limits and a link.
- The broker serves list and login for items of the collection. It refuses an item outside the collection, in the trash or archived, and an origin that no URI of the item matches. A test for each.
- A pre-approval is used at most once, only by the same client, item and origin, and ends after its time. Tests for each.
- TOTP codes are made on the broker and the seed is never sent. Tests use the RFC 6238 test vectors.
- A manual test: a password changed in the owner's vault is served on the next request.
- It gets the security review, as every change does.
Related: #104 (nodkey web), #105 (passkeys), #102 (change the broker config without SSH), #29 (reload the config without a restart).
Activity
groupsky commentedon Oct 27, 2026
2026-10-27: a one-use approval may be needed
agent-browser waits only 15 seconds for a credential plugin (fixed in
cli/src/plugins.rs), and a tap often takes longer. One way around it (#104, open question 1): the agent first runs a plugin command that waits up to 60 seconds for the tap. The broker then keeps a one-use approval for (client, item, URL) for about a minute, and the plugin'scredential.resolvegets the login at once. If #104 takes this way, this issue needs that approval, also for items withask = "always".groupsky commentedon Oct 27, 2026
One grant core (2026-10-27). The one-use pre-approval of step 9 is the same thing as a scheduled grant (#108) and a standing grant (#110), with other limits:
Proposed: build step 9 as the first part of one grant core: one store, one set of audit events, one revoke path. The scope is a secret, an SSH key (key, host key, remote user) or a login (item, origin). One command for all kinds:
nodkey preapprove --login ITEM --url URL(and--secret,--key), not a separatenodkey login approve.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).groupsky commentedon Nov 11, 2026
Which rule wins: the collection or the item (owner, 2026-11-11). Point 1 says a collection has one rule and an optional rule per item. When an item has its own rule:
clients,ask,window,preapproveandstandingreplace the collection's rule. Nothing is merged. A client that is in the collection'sclientsbut not in the item'sclientsis refused. The item's rule may be looser than the collection's: the owner wrote it for that one item. Two rules for one item are an error at start.[logins.*]sections: an error at start and at reload.collectionIdsshow it on each request, so section 16 addscollectionIdsto the fields the broker reads from an item. The broker refuses the item and writes an audit entry, because it would have two rules with no clear winner. An item with nocollectionIds, or whosecollectionIdsdo not hold the configured collection, is refused too.internal/approval/state.go). A grant must not move to another item through a rename or a new name.Please write this in DESIGN.md with the logins section, with tests for a stricter and a looser item rule, and for an item in two collections. #177 (allow a whole
bwsproject) uses the same rules.feat(config): [logins.*] sections with item rules, in config-diff (#103)
groupsky commentedon Nov 12, 2026
hq-jobs
nodkey-logins-build(runr-20261112-160509-22fd)Progress of the build job (2026-11-12)
The run ran out of budget before the broker part. The work so far is in the draft PR #181 (two commits, both checked by the security review). CI passes on the first commit. Nothing is merged.
Done in #181
internal/totp: TOTP codes made on the broker. It reads a base32 secret andotpauth://totp(SHA1, SHA256, SHA512; 6 to 8 digits; any period up to 3600 s), and refusessteam://and other forms. The seed is never in an error or a format, and its buffers are cleared. Tests:TestRFC6238Vectors(all 18 vectors of RFC 6238, appendix B),TestRefused,TestKeyHidesSeed,TestClear,TestInputNotKept,FuzzParse.internal/loginmatch: page URL checks (httpsonly) and Bitwarden's URI match types, withgolang.org/x/net/publicsuffixfor base domain (BSD-3-Clause; it was already an indirect dependency). "Starts with" and "exact" also need the same host and port. Tests:TestMatch,TestParsePageRefused,FuzzParsePage.bwstore:ListLogins(bw list items --collectionid) andFetchLogin. A list never keeps a password or a TOTP seed. Refused: an item in the trash, an archived item, an item that is not a login. Tests:TestBWListLogins,TestBWListLoginsRefused,TestBWFetchLogin,TestBWFetchLoginRefused,FuzzParseBWLogin.[logins.NAME]and[[logins.NAME.items]]: the item's rule wins completely. Refused: two sections with one collection, two rules for one item, andask = "never".config-difflists the changes. Tests:TestLoginsConfig(a stricter and a looser item rule),TestLoginsConfigRefused,TestDiffLogins,TestReloadRefusesLoginsChange.Choices I made that you may want to check
ask = "never"is refused for logins.[logins.*]. A restart is needed until the broker keeps login grants per item.Left to do (the next run, on the same branch)
nodkey preapprove --login ITEM --url URL: one use, for (client, item, origin), for 60 s (LoginPreapproveTime). Test it with a test broker that delays the approval for more than 60 s."Done when" boxes: none is fully met yet. The DESIGN/THREAT-MODEL box and the setup.md box are met in #181, but they get ticked only after the merge. The manual test (a changed password is served on the next request) needs the live broker and you, after the broker part is merged.
feat(approval): website login requests, one-use login pre-approval, a…
feat(broker): website login list, login, TOTP and one-use pre-approval (
feat(client): login list, login and TOTP requests; nodkey preapprove …
docs: website logins are built on the broker; T47 for login grants (#103
fix: security review of website logins (#103)
fix: cap bad TOTP requests; audit a cancelled list (#103)
feat: website logins from a shared Bitwarden collection (#103) (#181)
groupsky commentedon Nov 13, 2026
hq-jobs
nodkey-logins-build(runr-20261112-230011-6009)Status 2026-11-13: the broker part of #103 is built (PR #181)
PR #181 is merged (squash, commit 4ebffa8). No release is made. Evidence for each "Done when" box:
/v1/logins/list,/v1/logins/login,/v1/logins/totp), URI match, messages, grants, the one-use pre-approval (LoginPreapproveTime= 60 s) and the audit events (login_list,login_totp, kindweb_login). THREAT-MODEL.md: T32 (new words), T43 (claimed origin), T44 (usernames on the agent machine), T45 (TOTP seeds on the broker), T46 (owner's vault in a browser an agent drives), T47 (login grants and the pre-approval).[logins.*]config andnodkey preapprove --login.internal/broker/logins_test.go:TestLoginList,TestLoginByTap,TestLoginDeny(item outside the collection, in two configured collections, not a login, in the trash, archived, no password, origin that matches no URI,httppage, grant token, and more),TestLoginItemRuleDecidesTheClient(stricter item rule),TestLoginItemRuleLooser,TestLoginItemRuleInAnotherSection,TestLoginItemChangesAfterTheTap,TestLoginRuleChangesAfterTheTap,TestLoginReprompt,TestLoginListAudited,TestLoginListRate,TestLoginRequestRate.TestLoginPreapprove,TestLoginPreapproveUsedOnce(two uses at the same time, one wins),TestLoginPreapproveOtherClient,TestLoginPreapproveEndsAfterSixtySeconds,TestLoginPreapproveSlowTap(a test broker that delays the tap longer than 60 s),TestLoginPreapproveDeny; in the coreinternal/approval/login_test.goTestLoginPreapprove.internal/totp:TestRFC6238Vectors(RFC 6238 appendix B),TestErrorsHoldNoSeed,TestKeyHidesSeed,TestRefused(steam://,otpauth://hotp). Broker:TestLoginTOTPTicket,TestLoginTOTPTicketExpires,TestLoginTOTPWithWindowGrant,TestLoginTOTPNoSeedAndReprompt,TestLoginTOTPStoreFailure.security-revieweragent reviewed every commit. The broker part had 2 medium and 6 low findings, and the fix commit had 1 medium and 1 low finding; all are fixed (see the PR). One choice is left as it is: a URI with no match type uses base domain (the proposed answer to open question 5; the risk is in DESIGN.md 21.4 and T43).Not built yet, and refused for now: standing grants for logins, and a reload that changes
[logins.*](it needs a restart).Steps for Geno: the manual test
You need a release with this change, and the agent-browser plugin of #104: no
nodkeycommand hands out a login on its own. No release is made by this job.agentscollection, for a site you can use (anhttpspage that matches a URI of the item).[logins.NAME]section tobroker.toml, withpreapprove = true, and restart the broker (a reload refuses a change of[logins.*]).nodkey preapprove --login ITEM-ID --url https://SITE/and tap Approve. Then, in 60 s, let agent-browser log in with the nodkey plugin (feat: a nodkey credential plugin for agent-browser logins #104). Check that the password is the current one.#104 (the agent-browser plugin) is next. This run had no budget left for it, so the next run of the job starts it. This issue stays open until the manual test is done.
groupsky commentedon Nov 13, 2026
hq-jobs
nodkey-logins-build-2(runr-20261113-180009-1831)hq-jobs
nodkey-logins-build-2(runr-20261113-180009-1831)Status 2026-11-13: the agent-browser plugin of #104 is merged (PR #182)
The plugin that the manual test of this issue needs is now built:
nodkey agent-browser-plugin(commit 7858003). #182 also adds one broker change to the login request: the headerNodkey-No-Tap: 1. With it the broker never asks for a tap. When no pre-approval or window grant covers the login, it answers 428 with the audit causeno_tap, and sends no message. Every other check of this issue still runs. DESIGN.md 21.10 and THREAT-MODEL.md T48 describe it.The only box left here is the manual test: "a password changed in the owner's vault is served on the next request". It needs a release (no release is made by this job) and your phone. The steps of the earlier comment still hold. For step 3, use
docs/agent-browser.mdsection 2:nodkey preapprove --login ITEM-ID --url https://SITE/and tap Approve.agent-browser auth login test --credential-provider nodkey --item ITEM-ID --url https://SITE/.You can do it together with the end-to-end test of #104 (steps on #104).