Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
129 changes: 124 additions & 5 deletions DESIGN.md
Original file line number Diff line number Diff line change
Expand Up @@ -1974,7 +1974,9 @@ The fields of each event, after `seq`, `time`, `event` and `prev`:
The request fields are `request_id`, `client`, `kind` (`secrets`,
`ssh_login`, `ssh_grant`, `preapprove`, `standing` or `web_login`), `secrets`, `key`, `hosts`,
`host_key` (a SHA256 fingerprint), `remote_user`, and the claimed
`command` and `reason`. A website login (section 21.8) has `logins` (the
`command` and `reason`. A secret of a project is `SECTION/KEY` in
`secrets`, and `project_secrets` lists its `name` and `id` (section 14,
"Projects"). A website login (section 21.8) has `logins` (the
`[logins.NAME]` section), `item` (the item ID) and the claimed `origin`,
never a username. `login_list` and `login_totp` are its other entries. A `preapprove` request that was approved also has
`grant_id`, `uses`, `not_before` and `not_after` (UTC, RFC 3339). A
Expand Down Expand Up @@ -2426,8 +2428,9 @@ a path, a query, `OPTIONS *` or `PRI *` gets 404. The types are in
gets `503` too, also when the audit log says `cancelled`: the client
did not get a deny.
- More caps, besides those above: at most 32 variables in a request; each
name (of a variable, a secret, a key, a host or a remote user) at most 64
bytes; a public key at most 4 KiB; the data to sign and each
name (of a variable, a key, a host or a remote user) at most 64
bytes; a secret name at most 129 bytes, for `SECTION/KEY` of a project
(section 14, "Projects"); a public key at most 4 KiB; the data to sign and each
session-bind at most 8 KiB; at most 2 session-binds; at most 20 hosts in
an SSH grant (a host listed twice counts twice here). The answer is at
most 2 MiB: each value is at most 64 KiB, and the values of one request
Expand Down Expand Up @@ -3122,6 +3125,108 @@ write to, below directories that pass the same checks. It may be a
symbolic link. `broker_pin` is the client's only trust in the broker, so
other users must not be able to change it.

### Projects

*(issue 177; built: `internal/config/project.go`,
`internal/broker/projects.go`, `internal/store/bwsproject.go`)*

A `[project.NAME]` section allows every secret of one Bitwarden Secrets
Manager project, with one rule. Putting a secret into the project is then
the "allow" step, with no config edit and no reload.

```toml
[project.ci]
store = "main" # a store of type "bws"
project = "00000000-0000-0000-0000-000000000000"
clients = ["laptop"]
ask = "window" # "always" or "window"
window = "15m"
# preapprove and standing as for [secret.*]
```

- `store` must name a store of type `bws`. `project` is the project's
UUID; the broker keeps it in lower case.
- `ask = "never"` is an error. It would make every secret of the project
tap-free, also secrets added later, and the "one `never` per `id`" check
cannot run for secrets the broker has not seen.
- One project may be in one `[project.*]` section only, in one store or
in two. Project UUIDs are compared in lower case. A second section is an
error at the start and at a reload: one secret would get two rules.

**Names.** A client asks for a project secret as `SECTION/KEY`, where
`KEY` is the secret's `key` in Bitwarden, for example
`nodkey run --secret GH_TOKEN=ci/GITHUB_TOKEN -- ...`. A name without `/`
is always a `[secret.*]` section, so the two kinds cannot clash. A name
with two or more `/` is refused. Each part follows the name rule, so it
has at most 64 bytes, and `SECTION/KEY` at most 129 (`api.MaxSecretName`).
The key is matched exactly, also in upper and lower case. Only a key that
follows the name rule can be asked for; other secrets of the project are
skipped, and their key is never shown.

**Lookup.** The broker first checks the name, that the section exists,
and that the client is in its `clients` or in the `clients` of a
`[secret.*]` entry of a `bws` store. Then, before the core decides, it
runs `bws secret list PROJECT` once for each project of the request
(section 16) and finds the secret by its key:

- no secret has the key: denied (`not_allowed`); the audit entry does not
name the key, which the client chose;
- two or more secrets have the key: denied (`not_allowed`). Bitwarden does
not keep keys unique, even in one project, and the broker cannot tell
which one is meant. The denied entry names `SECTION/KEY`, and a line in
the journal says why; never a value;
- one secret: the broker has its ID.

The request keeps its place for a request body (section 8) while the
lists run. A `SECTION/KEY` goes into the audit subject only once it is
found, so a key that the client made up is never in the audit log. Two
names of one request that are the same secret, such as an entry's name
and `SECTION/KEY` with its ID, deny the request.

After the tap, the broker gets the secret by its ID with `bws secret
get`, from the store of the project, and checks that the `key` and the
`projectId` of that answer are those of the list. If not, such as for a
rename between the two runs, the request is denied.

**Which rule wins.** With the ID, the broker looks for a `[secret.*]`
entry with that ID in any store of type `bws`. Two stores can use the
same machine account, so the store is not part of the match.

- One entry: **the entry wins, completely.** Its `clients`, `ask`,
`window`, `preapprove` and `standing` apply, and the project's rule is
not used. Nothing is merged. A client in the project's `clients` but not
in the entry's is refused. The entry may be looser than the project
(`window` when the project says `always`): the owner wrote it for that
one secret. The entry's own grants are used, as for its own name.
- Two or more entries: denied. There is no clear winner.
- No entry: the project's rule applies.

The broker applies this on each request, after it has found the secret.
The approval core checks it again with the config that it decides with
(`config.Broker.RuleFor`).

**Grants are for one secret ID, not for a name.** A grant, a pre-approval
and a standing grant of a project secret are kept per (client, project
section, secret ID). The key becomes an ID when the grant is made, and
each use is checked against that ID. So when someone gives the key of a
granted secret to another secret, a request for `SECTION/KEY` finds the
other ID, and the grant does not cover it: the broker asks again. A
grant covers its secret under a new key too. A secret that leaves the
project is not found by `SECTION/KEY` any more; a `[secret.*]` entry for
it still works while the machine account can read it.

**Message.** The verified part shows the secret as
`ci/GITHUB_TOKEN (project rule, ID …1a2b3c4d)`: the name, that the
project's rule applies, and the last 8 characters of the ID. When an entry
wins, it shows `ci/GITHUB_TOKEN (rule of secret NAME, ID …1a2b3c4d)`. The
key in it was read from Bitwarden; the client sent the same key, and only
a key that follows the name rule gets here. A list of standing grants
shows a project grant as `ci (project rule, ID …1a2b3c4d)`.

**Audit.** The entries name the secret as `SECTION/KEY` in `secrets`,
and `project_secrets` holds its ID: `[{"name": "ci/GITHUB_TOKEN", "id":
"…"}]`.

### Reload

A change of the config needs no restart (issue 29). `SIGHUP` asks the
Expand All @@ -3132,8 +3237,10 @@ the grants that the new config takes away.
1. The broker loads the config file, `known_hosts` and the SSH keys with
the same code and the same checks as a start (`config.LoadBroker`, then
the keys). A config that fails any check is refused.
2. A reload may change only `[client.*]`, `[secret.*]`, `[key.*]`, the
`known_hosts` path and its hosts. Every other part must be equal, also
2. A reload may change only `[client.*]`, `[secret.*]`, `[key.*]`,
`[project.*]`, the `known_hosts` path and its hosts. It runs the checks
of `[project.*]` again: `ask = "never"` and one project in two
sections refuse the reload. Every other part must be equal, also
a part that a later version adds, until it is decided otherwise. A change of `listen`, `tls_key`,
`audit_log`, `[telegram]`, `[ntfy]`, `[updates]`, `[preapprove]`,
`[standing]` or any `[store.*]` is refused with "needs a restart".
Expand All @@ -3150,6 +3257,10 @@ the grants that the new config takes away.
- its client is still there, with the same pin;
- each of its secrets is still there, still lists the client, and has
the same store, item and rule (other clients in the list may change);
- a grant of a project secret: the section is still there, with the
same store and project, and the same rule applies to the secret ID,
with the client in its `clients`. A project grant for a secret that
now has its own `[secret.*]` entry ends;
- its key is still there, still lists the client, has the same file,
the same public key in it and the same rule, and each host of the
grant is still in `known_hosts` and still allowed by `hosts`.
Expand Down Expand Up @@ -4101,6 +4212,8 @@ bws 2.1.0 and bw 2026.9.1 on 2026-10-14
| when | command | what the broker reads |
|---|---|---|
| a `bws` fetch | `bws secret get ID --output json --color no` | stdout: one JSON object with `id`, `organizationId`, `projectId`, `key`, `value`, `note`, `creationDate` and `revisionDate`. The broker reads only `id` and `value`. |
| a project secret, first (section 14, "Projects") | `bws secret list PROJECT --output json --color no` | stdout: one JSON array of such objects, with the values of all secrets of the project. The broker reads only `id`, `key` and `projectId` of each, and clears the whole answer. `PROJECT` must be a UUID. |
| a project secret, then | `bws secret get ID --output json --color no` | as a `bws` fetch, and also `key` and `projectId`: they must be the key and the project of the list, else the request is denied. |
| a `bw` unlock | `bw unlock --passwordfile FILE --raw --nointeraction` | stdout: only the session key, in base64. |
| a `bw` fetch, first | `bw sync --force --nointeraction` | only the exit code. |
| a `bw` fetch, then | `bw get item ID --nointeraction` | stdout: one JSON object, the item. The broker reads only `id`, `login.password`, `deletedDate` and `archivedDate`. |
Expand All @@ -4118,6 +4231,12 @@ bws 2.1.0 and bw 2026.9.1 on 2026-10-14
still works. Any other answer is refused, and the request is denied.
- `id` must be the asked ID, in upper or lower case. An answer without
it, or for another item, is refused.
- The answer of `bws secret list` is one JSON array, not one object, with
the same rules for each element. Each must have a UUID `id`, a `key`
and the `projectId` of the asked project, else the whole answer is
refused. A secret whose `key` breaks the name rule is skipped, and its
key is never kept or shown. The answer is capped at 1 MiB, as every
answer: a project too big for that is refused.
- A value that is missing, `null` or empty is refused. So is a value with
a NUL byte: the environment of a command cannot hold it. So is an item
that is not a login item, an item in the trash (`deletedDate` is not
Expand Down
70 changes: 70 additions & 0 deletions THREAT-MODEL.md
Original file line number Diff line number Diff line change
Expand Up @@ -1649,6 +1649,76 @@ What nodkey does not do:
Risk that remains: medium, as for every value that an agent gets (section
5).

**T49. Anyone who can write to a Secrets Manager project changes what
agents can get.**
A `[project.*]` section allows every secret of one project (DESIGN.md
section 14, "Projects"). A person or a machine account that can write to
the project can add a secret, or give the key of a secret to another
secret, with no change of the config.
What nodkey does:
- `ask = "never"` is an error in a `[project.*]` section, so a secret that
is added to the project always needs a tap or a grant from one.
- Grants, pre-approvals and standing grants of a project secret are kept
per secret ID, not per name. When a key moves to another secret, a
grant for `SECTION/KEY` does not hand out the other secret: the broker
asks again.
- The tap message shows the name, that a project rule applies, and the
last 8 characters of the secret's ID, so the person can see that it is
another secret.
- Two secrets with the same key in the project are refused, with an audit
entry: the broker never guesses which one is meant.
- After the tap, the answer of `bws secret get` must have the key and the
project of the list; a rename or a move in between denies the request.
- One project may be in one section only, and a `[secret.*]` entry with
the same ID wins completely, so one secret never has two rules that
could both apply.
- docs/setup.md says: the broker's machine account gets "Can read" on the
project and nothing more, and only the owner may write to the project.
What nodkey does not do:
- It cannot see who wrote to the project. A person with write access to
the project can put any secret there, and a client of the section can
then ask for it with a tap.
Risk that remains: medium while others can write to the project; low when
only the owner can.

**T50. A key from Bitwarden is shown in the tap message.**
The key of a project secret is typed by whoever can write to the project,
and the message shows it.
What nodkey does:
- Only a key that follows the name rule (letters, digits, `.`, `_` and
`-`, at most 64) can be asked for or shown. The broker skips other
secrets of the project, and never keeps or shows their keys.
- The key is matched exactly; a client cannot reach another secret with
another case.
- Telegram and ntfy check the form of the secret text again before they
send a message.
Risk that remains: low. A key can still be a misleading word, such as
the name of another secret; the end of the ID in the message helps here.

**T51. `bws secret list` brings every value of the project into the
broker's memory.**
The answer of `bws secret list` holds the values of all secrets of the
project, also secrets that no request asks for.
What nodkey does:
- The broker reads only `id`, `key` and `projectId` of each secret, never
keeps a value or a note from the list, and clears the whole answer
right after reading it.
- The answer is capped at 1 MiB, as every answer of a store. A project
too big for that is refused; the setup guide says to keep a project
small, or to split it.
- The list runs only for a client that the section, or an entry of a
`bws` store, lists, and only once for each project of a request. The
request keeps its place for a request body while the list runs, so the
cap per client of bodies in progress also caps its lists.
What nodkey does not do:
- A client that a section lists can make the broker list the project
without a tap, as often as its caps allow. Each list is denied if the
key is wrong, but it uses the machine account's API limits.
- Go keeps copies that nodkey cannot clear, such as in the buffers of
the pipe from bws (section 5). For a short time, more values are in the
broker's memory than for one `bws secret get`.
Risk that remains: low, for a broker host that is safe (section 7).

## 7. Assumptions

- The broker host is patched, has no agent on it, and only the owner has
Expand Down
62 changes: 61 additions & 1 deletion docs/setup.md
Original file line number Diff line number Diff line change
Expand Up @@ -698,6 +698,66 @@ in the example config, `[store.backup-job]` with the credential
another secret through that store. Its token can read only that one
project.

### bws: allow a whole project

A `[project.NAME]` section allows every secret of one Secrets Manager
project, with one rule
([DESIGN.md section 14, "Projects"](../DESIGN.md#projects)). To let agents
use a new secret, you then put it into the project. You do not edit the
config, and you do not reload the broker.

So anyone who can write to the project decides what agents can get
([THREAT-MODEL.md T49](../THREAT-MODEL.md#6-threats-and-answers)). In the
web app of Secrets Manager:

1. Make a project only for the secrets that agents may get. Keep it
small: the broker reads the list of the whole project, with all
values, for each request, and it refuses a list of more than 1 MiB.
Split a big project into two.
2. Give the broker's machine account **"Can read"** on this project, and
nothing more. Never "Can read, write".
3. Only you may write to the project. Do not give another person or
machine account write access to it.
4. Give each secret a **key** of letters, digits, `.`, `_` and `-`, at
most 64 characters, such as `GITHUB_TOKEN`. A secret with another key
cannot be asked for. Give each secret its own key: when two secrets of
the project have one key, the broker refuses both.
5. Copy the ID of the project, a UUID. It goes into `project` in the
config.

In the config:

```toml
[project.ci]
store = "main"
project = "00000000-0000-0000-0000-000000000000"
clients = ["laptop"]
ask = "window"
window = "15m"
```

- `store` must be a store of type `bws`.
- `ask = "never"` is not allowed here. For a job without a tap, use a
`[secret.*]` section for that one secret.
- One project may be in one `[project.*]` section only.

A client asks for a secret of the project as `SECTION/KEY`:

```sh
nodkey run --secret GH_TOKEN=ci/GITHUB_TOKEN -- gh pr list
```

The key must be written exactly as in Bitwarden, also in upper and lower
case. The tap message shows `ci/GITHUB_TOKEN (project rule, ID …1a2b3c4d)`:
the end of the secret's ID tells you which secret it is.

**A different rule for one secret.** Give the secret a `[secret.*]`
section with its ID, in any store of type `bws`. That section's rule then
applies to the secret completely, also when a client asks for
`ci/GITHUB_TOKEN`. It may be stricter or looser than the project's rule.
Do not give one secret two `[secret.*]` sections: the broker then refuses
it.

### 1password: a vault only for nodkey

The `1password` store uses the official 1Password SDK inside the broker.
Expand Down Expand Up @@ -1806,7 +1866,7 @@ To check a config before you use it, run `nodkey broker check`
The command prints why, and exits with 1. The journal says why too. Fix
the config, and run the command again.

A reload can change `[client.*]`, `[secret.*]`, `[key.*]` and
A reload can change `[client.*]`, `[secret.*]`, `[key.*]`, `[project.*]` and
`known_hosts`. A change of `listen`, `tls_key`, `audit_log`,
`[telegram]`, `[ntfy]`, `[updates]`, `[preapprove]`, `[standing]` or a
`[store.*]` section needs a restart: the reload refuses it, and says so.
Expand Down
4 changes: 4 additions & 0 deletions internal/api/api.go
Original file line number Diff line number Diff line change
Expand Up @@ -163,6 +163,10 @@ const (
// MaxName is the most bytes of a name: a variable, a secret, a key, a
// host or a remote user. Valid names are shorter.
MaxName = 64
// MaxSecretName is the most bytes of a secret name: a name, or
// SECTION/KEY of a project, two names and a "/" (DESIGN.md section
// 14, "Projects"). Each part is at most MaxName.
MaxSecretName = 2*MaxName + 1
// MaxKey is the most bytes of an SSH public key in SSH wire form. An
// RSA key of 16384 bits, the largest that OpenSSH accepts, has about
// 2 KiB.
Expand Down
Loading
Loading