Skip to content
Merged
7 changes: 6 additions & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -40,6 +40,10 @@ Planned. Each v1 issue adds its part.
section 10).
- `internal/grantkey/` - the token of a standing grant: make, parse,
hash, and hide it in every format (DESIGN.md section 8).
- `internal/totp/` - TOTP codes made on the broker (RFC 6238) from the
`login.totp` field of a Bitwarden item (DESIGN.md section 21).
- `internal/loginmatch/` - the page URL of a website login and
Bitwarden's URI match types (DESIGN.md section 21).
- `internal/doctor/` - the checks of `nodkey doctor` (client) and
`nodkey doctor broker`: read only, with the text and JSON form of
the result (DESIGN.md section 15).
Expand Down Expand Up @@ -116,7 +120,8 @@ that it makes.
request. If it changes the config, the example unit, a command, or a
line that `docs/setup.md` or a `docs/manual-*-test.md` guide shows,
update these guides too.
- **Dependencies:** the standard library, `golang.org/x/crypto` and
- **Dependencies:** the standard library, `golang.org/x/crypto`,
`golang.org/x/net` (only `publicsuffix`, for website logins) and
`github.com/BurntSushi/toml`. Anything else needs a reason in the pull
request. The `1password` and `infisical` stores also link the official
1Password and Infisical Go SDKs (DESIGN.md section 4).
Expand Down
272 changes: 270 additions & 2 deletions DESIGN.md

Large diffs are not rendered by default.

100 changes: 100 additions & 0 deletions THREAT-MODEL.md
Original file line number Diff line number Diff line change
Expand Up @@ -1008,6 +1008,22 @@ What to do:
a security key. A code by email does not help if you read that email on
an agent machine.

**Website logins (DESIGN.md section 21, owner 2026-11-11).** The logins
that agents may use are in a collection of an organization that the
owner's main account owns. So the main account can read them, and the
rule above needs other words for it. These are the owner's own logins,
and the owner uses them every day. The rule is:
- The separate account of the `bw` store stays off agent machines, in
every app, as above.
- The owner's main vault is never unlocked in a browser or an app that
an agent can drive: not in agent-browser, not in a browser that the
agent reaches over the Chrome DevTools Protocol, and not in a browser
profile that such a browser uses. An agent that drives a browser with
the unlocked extension can open the extension's own page in a tab and
read every item (T46).
- The owner may keep the main vault unlocked in a browser that only the
owner uses, on a machine with no agent.

Risk that remains: real. nodkey cannot see a read in Bitwarden's own
apps, and it cannot check where an account is logged in.

Expand Down Expand Up @@ -1507,6 +1523,90 @@ is in neither list. The short form never drops a line that widens: when
they do not all fit, it says how many there are. It reads no credential.
It is no control of the broker: it only helps a person to decide.

**T43. A website login goes to a page that the client claims.**
The client sends the page URL of a login (DESIGN.md section 21). The
broker cannot check that the browser is on that page: the agent can
claim `https://example.com` and paste the password into another site.
What nodkey does:
- The message shows the page origin as claimed, and the item name and
the username as read from Bitwarden. The tap is for that login, from
that client.
- The page must be `https`, and it must match a URI of the item, by
Bitwarden's match type of that URI. So a login for one site is never
handed out for a page of another site, by mistake or by a prompt
injection that names a wrong site.
- "Starts with" and "exact" also need the same host and port as the
page, which is stricter than in Bitwarden.
- A URI with no match type uses the base domain, the loosest type
(DESIGN.md section 21.4). Where other people run other hosts of the
same domain, set the URI's match type to "Host".
- The page URL is checked strictly and is never in an error.
What nodkey does not do: it cannot stop an agent that has the password
from using it anywhere. This is the same as for every secret (section 5).
Risk that remains: real, and the same as for a secret.

**T44. A list of logins shows item names and usernames on the agent
machine.**
A list needs no tap (DESIGN.md section 21.3). It shows the item ID, the
item name and the username of each item of the collection that matches
the page. These are not secrets, but they tell the agent which accounts
the owner has on a site.
What nodkey does: a list shows only items that match an `https` page,
never a password or a TOTP seed. Each list is in the audit log, even an
empty or refused one, and lists have a rate limit per client. The owner puts into the collection only
the logins that agents may use.
Risk that remains: low.

**T45. The broker reads TOTP seeds.**
The broker makes TOTP codes itself, so it reads the seed of each login
it hands out. Anyone who controls the broker can make codes. And a login
with its seed in the same item is one factor, not two, for anyone who
can read the item.
What nodkey does:
- The seed never leaves the broker: not in an answer, an error, a log or
the audit log. Its type hides it in every format, and its buffer is
cleared after use.
- A code is handed out only after an approved login, for one code within
2 minutes, or during a `window` grant.
- `bw list items` returns every seed of the collection: the broker checks
the field and keeps none of it, and clears the whole answer.
- Only base32 secrets and `otpauth://totp` are read; `steam://` and other
forms are refused.
Risk that remains: the broker host is trusted (section 3). Put a login
whose second factor matters more into the collection with no seed, and
type the code yourself.

**T46. The owner's vault is open in a browser that an agent drives.**
An agent that drives a browser with an unlocked Bitwarden extension can
open the extension's own page in a tab and read every item. Then nodkey
gives no protection. See the rule for website logins in T32.
What nodkey does: the setup guide says it, and the agent-browser how-to
(#104) uses a separate browser profile with no password manager.
Risk that remains: real; it depends on the owner.

**T47. A login grant or a pre-approval hands out another login.**
A `window` grant or a one-use pre-approval (DESIGN.md section 21.7)
lets a login go out without a new tap. An agent could try to use it for
another item of the same site, from another client, for another page, or
later than the person meant.
What nodkey does:
- A `window` grant covers (client, item ID), never a config section or a
site. A pre-approval covers (client, item ID, page origin).
- A pre-approval is used at most once, in one atomic step, and ends
`LoginPreapproveTime` (60 seconds) after the tap. The message says
this. It names no time limit for the tap itself.
- An item with "Master password re-prompt" needs a tap for each login;
no `window` grant hands it out.
- The broker does not keep the password while the request waits for the
tap. After the tap it reads the item again and runs every check again;
the username, the item name, the rule and the re-prompt flag must be
unchanged.
- Logins and pre-approvals have a rate limit per client, before the
store runs.
- A reload keeps a login grant only when the item has the same rule.
Risk that remains: low. In its 60 seconds, a pre-approval can be used by
any process of that client that asks for that item and origin (as T35).

## 7. Assumptions

- The broker host is patched, has no agent on it, and only the owner has
Expand Down
96 changes: 96 additions & 0 deletions docs/setup.md
Original file line number Diff line number Diff line change
Expand Up @@ -940,6 +940,102 @@ access to it: such an account could read them too.
not start, and the error has `bw unlock` and `took too long`, the
unlock took more than 30 seconds: lower the KDF settings (step 3).

### Website logins: a shared collection

> **The browser part is not ready yet.** The broker hands out logins
> (issue #103). The plugin for agent-browser is issue #104. Until then,
> only `nodkey preapprove --login` uses logins from the command line.

Agents can log in to websites with logins from your own Bitwarden vault.
You choose the logins: you put them into one shared collection. The
separate account of the `bw` store (above) can read only that
collection. You still see, fill and change these logins in your normal
vault. A password that you change there is used on the next request.

The Free plan of Bitwarden allows an organization with 2 users and 2
collections ([organizations](https://bitwarden.com/help/what-is-an-organization/),
seen 2026-10-21). That is enough: your main account and the separate
account.

1. **Make the organization.** Log in to the web app with your main
account. Choose **New organization**, give it a name, and choose the
Free plan.
2. **Make the collection.** In the organization, open **Collections**
and make one named, for example, `agents`.
3. **Invite the separate account.** In **Members**, invite the email
address of the separate account of the `bw` store, with the role
**User**. Give it access to the `agents` collection only, with the
permission **Can view**. It must not be able to change items. Do not
give it "Can view, except passwords": then the broker cannot read the
password. Accept the invitation as the separate account, and confirm
the member with your main account.
4. **Move the logins.** In your main vault, open each login that agents
may use, and choose **Assign to collections** (or **Move to
organization**) and `agents`. Only these logins. Check the URIs of
each item: the broker hands out a login only for an `https` page that
matches a URI of the item, with Bitwarden's match type of that URI.
A URI with no match type is read as **Base domain**, the loosest
type. When other people run other hosts of the same domain, set the
match type to **Host**. Regular expressions never match.
5. **The TOTP seed, if any.** When a login has an "Authenticator key",
the broker makes the codes itself. It reads a base32 secret, or an
`otpauth://totp` URI with SHA1, SHA256 or SHA512, 6 to 8 digits and
any period. It refuses `steam://` and other forms. For a site whose
second factor matters more, leave the key out of the item and type
the code yourself.
6. **Find the ID of the collection.** On the broker host, as the user of
the store, after a sync:

```sh
bw list collections --nointeraction
```

The config names the collection by its `id`, never by its name.
7. **Add the collection to `broker.toml`** (DESIGN.md section 21.2):

```toml
[logins.web]
store = "vault"
collection = "00000000-0000-0000-0000-000000000000"
clients = ["laptop"]
ask = "window"
window = "15m"
preapprove = true

[[logins.web.items]]
id = "11111111-1111-1111-1111-111111111111"
clients = ["laptop"]
ask = "always"
preapprove = true
```

`store` is a store of type `bw`. `ask = "never"` is refused for
logins. An item's own rule replaces the rule of the collection
completely. A change of `[logins.*]` needs a restart of the broker:
a reload refuses it. Putting an item into the collection needs no
change of the config.

8. **One login after one tap, for a browser that waits only a short
time.** On the client:

```sh
nodkey preapprove --login 11111111-1111-1111-1111-111111111111 --url https://example.com/sign-in
```

It waits for your tap as long as any other request (the `timeout`
of the broker). After the tap, the next login to that item, from that
machine, for that origin, gets the login without a new tap. It works
once, and only in the 60 seconds after the tap. The rule of the item
needs `preapprove = true`.

**Never unlock your main vault in a browser or an app that an agent can
drive**: not in agent-browser, not in a browser that an agent reaches
over the Chrome DevTools Protocol, and not in a browser profile that
such a browser uses. With the unlocked extension, the agent can open the
extension's own page in a tab and read every item
(THREAT-MODEL.md T32 and T46). Keep the separate account off agent
machines, as above.

## 6. SSH keys and the broker's known_hosts

Skip this section if you use nodkey only for secrets. The broker still
Expand Down
2 changes: 1 addition & 1 deletion go.mod
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@ require (
github.com/go-resty/resty/v2 v2.17.2
github.com/infisical/go-sdk v0.9.1
golang.org/x/crypto v0.58.0
golang.org/x/net v0.60.0
)

require (
Expand Down Expand Up @@ -50,7 +51,6 @@ require (
go.opentelemetry.io/otel/metric v1.44.0 // indirect
go.opentelemetry.io/otel/trace v1.44.0 // indirect
go.opentelemetry.io/proto/otlp v1.9.0 // indirect
golang.org/x/net v0.60.0 // indirect
golang.org/x/oauth2 v0.36.0 // indirect
golang.org/x/sync v0.24.0 // indirect
golang.org/x/sys v0.49.0 // indirect
Expand Down
Loading
Loading