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
93 changes: 91 additions & 2 deletions DESIGN.md
Original file line number Diff line number Diff line change
Expand Up @@ -510,6 +510,85 @@ The list has limits:
sees. It does not stop a hostile agent (THREAT-MODEL.md section 5,
item 1).

### TOTP codes

Issue #212 (owner, 2026-11-19). Some CLI tools need a 2FA code for a
write, for example `npm publish` of a new package and `npm trust`: they
fail with `EOTP` without one. nodkey hands such a tool one TOTP code, as
a `run` secret:

```sh
nodkey run --totp NPM_OTP=npm-otp \
-- sh -c 'npm publish pkg.tgz --otp "$NPM_OTP"'
```

- **The config allows it** (closed by default). A `[secret.*]` section
with `totp = true` is the TOTP code of a Bitwarden login item, not its
password:

```toml
[secret.npm-otp]
store = "vault" # a store of type bw
id = "11111111-1111-1111-1111-111111111111" # the login item
totp = true
clients = ["laptop"]
ask = "always"
preapprove = true # optional; a batch with one tap
```

`totp` is allowed only with a store of type `bw`. A secret with
`totp = true` needs `ask = "always"` and no `standing = true`: one tap
gives one code, and a window grant or a standing grant would hand out
codes without one. `preapprove = true` is allowed (see below). An item
in a `[logins.*]` collection is not a CLI code for that: only a
`[secret.*]` section with `totp = true` makes one. A change of `totp`
in a reload ends the grants of the secret, and `config-diff` marks it
as a change that widens.
- **The client asks for a code with `--totp VAR=NAME`.** NAME is a
`[secret.*]` section, never `PROJECT/KEY`. The request carries the
variable with `"kind": "totp"` (`api.KindTOTP`); a `--secret` has no
`kind` field, as before. At most one `--totp` in a request; it counts
as one of the 32 secrets. An older broker refuses the field: its
decoding is strict, so it fails closed.
- **The broker checks the kind against the config** in step 3, as for
any other check: a secret with `totp = true` only with `--totp`, and
`--totp` only for such a secret, at most once. A request that fails
gets 403 with no message, and the entries `request` and `denied` with
cause `not_allowed`.
- **The message is the message of a run secret** (section 7): it names
the secret, as in `✅ secrets: npm-otp`, and shows the variable, the
command line, the directory and the reason as claimed text. Give the
section a name that says what the code is for, such as `npm-otp`.
- **After the tap, the broker makes the code.** It runs
`bw sync --force` and `bw get item ID`, as for a password (section
21.9), and checks that the item is the item of `id`, a login item, not
in the trash and not archived. It reads `login.totp` and clears the
password at once; a login with no password is fine. It reads the seed
with `internal/totp` (section 21.5), makes the code of the broker's
clock of now, and clears the seed and the key. **The seed never leaves
the broker**; the client gets only the code, as the value of VAR. An
item with no seed, a seed in a form that nodkey does not read, or a
store failure denies the request with `error` code `store_failed`
(status 503). The journal says what is wrong and how to fix it, with
no seed and no code.
- **The code is fresh at each use.** The broker fetches the item and
makes the code for each approved request; it keeps no code and no
seed. Two uses in the same time step (30 s for most sites) get the
same code. Some sites take a code only once; then wait for the next
step between two uses.
- **A batch with one tap** is a scheduled grant: `nodkey preapprove
--secret npm-otp --until TIME --uses N` (section 8). As for any
scheduled grant, it must name every secret of the command, for example
`--secret npm-token` too. Each `nodkey run
--totp` in its time span takes one use and gets its own code of that
moment, with a silent notice, up to N uses. The grant ends at its last
use; the next request asks for a tap again.
- **Audit**: one `secret_sent` entry per code, as for any run secret
(section 9). It names the secret, never the code or the seed.
- **The risks** are in THREAT-MODEL.md, T54: a code works for any write
of that account in its time step (about 30 s), not only for the
command in the message, and the command line is claimed by the client.

## 6. Flow: an SSH login

```
Expand Down Expand Up @@ -2954,6 +3033,14 @@ name = "CI_TOKEN" # the name of the secret
clients = ["laptop"]
ask = "always"

[secret.npm-otp] # the TOTP code of a bw login item (section 5, "TOTP codes")
store = "vault"
id = "11111111-1111-1111-1111-111111111111"
totp = true # optional; default false; only for a store of type bw
clients = ["laptop"]
ask = "always" # needed with totp = true
preapprove = true

[key.deploy]
file = "${CREDENTIALS_DIRECTORY}/ssh-deploy"
clients = ["laptop"]
Expand Down Expand Up @@ -3338,7 +3425,7 @@ nodkey broker [--config FILE]
nodkey broker reload [--config FILE] [--timeout DURATION]
nodkey broker check [--config FILE] [--files DIR] [--credentials DIR]
nodkey broker config-diff [--short] [--max-chars N] OLD NEW
nodkey run [--secret VAR=NAME]... [--grant-token FILE] [--reason TEXT] [--mask | --no-mask] -- COMMAND [ARGS...]
nodkey run [--secret VAR=NAME]... [--totp VAR=NAME] [--grant-token FILE] [--reason TEXT] [--mask | --no-mask] -- COMMAND [ARGS...]
nodkey ssh-agent [--socket PATH]
nodkey ssh-grant --key NAME --user USER --host NAME... --for DURATION [--reason TEXT]
nodkey preapprove (--secret NAME... | --key NAME --user USER --host NAME...) --until TIME --uses N [--from TIME] [--reason TEXT]
Expand Down Expand Up @@ -4953,7 +5040,9 @@ broker cannot check that the browser is on that page.
and no standing grant hands it out. A pre-approval is a tap for that
one login, so it works.
3. **TOTP code.** When the item has `login.totp`, the broker makes the
current code itself (*built*: `internal/totp`). The seed never leaves
current code itself (*built*: `internal/totp`). This code is only for
the login on the page; a code for a CLI tool is a `run` secret with
`totp = true` (section 5, "TOTP codes"). The seed never leaves
the broker. The client asks for the code after the password step,
when the site shows its code page. It sends the same page origin and
item ID.
Expand Down
18 changes: 18 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -283,6 +283,24 @@ root on the broker host on the agent machine
`GH_TOKEN`, and prints only its length, so the agent's screen shows
only that length.

**A 2FA code for a CLI tool.** Some tools need a one-time code for a
write, such as `npm publish` and `npm trust` (they fail with `EOTP`).
nodkey can make the code from the TOTP seed of a Bitwarden login item,
on the broker, after a tap. The seed never leaves the broker; the
command gets only the code:

```sh
nodkey run --secret NPM_TOKEN=npm-token --totp NPM_OTP=npm-otp -- \
sh -c 'npm publish pkg.tgz --otp "$NPM_OTP"'
```

The broker hands out a code only for a `[secret.*]` section with
`totp = true`. For many packages with one tap, use
`nodkey preapprove --secret npm-token --secret npm-otp --uses 8 ...`
(both secrets need `preapprove = true`): each run gets its own fresh
code. See
[docs/setup.md](docs/setup.md#a-2fa-code-for-a-cli-tool-nodkey-run---totp).

Before real use, read
[docs/setup.md](docs/setup.md): above all the safety of your Telegram
and Bitwarden accounts and of the broker host
Expand Down
35 changes: 35 additions & 0 deletions THREAT-MODEL.md
Original file line number Diff line number Diff line change
Expand Up @@ -1911,6 +1911,41 @@ What nodkey does not do:
makes that run restart it.
Risk that remains: low, when the role comes from a checked release file.

**T54. A TOTP code for a CLI command is used for another write.**
`nodkey run --totp` (DESIGN.md section 5, "TOTP codes") hands the
current TOTP code of a Bitwarden login item to one command, for example
`npm publish --otp`. A code is a second factor for **any** write of that
account, not only for the command in the message, for as long as the
site takes it: its time step (about 30 s), often one step more. The
command line in the message is claimed by the client: an agent can show
`npm publish pkg.tgz` and run something else with the code, or read it
from the command's environment, and the agent's session with the site
then has both factors (section 5, item 1).
What nodkey does:
- **Closed by default.** Only a `[secret.*]` section with `totp = true`
hands out a code, for the clients in its list. An item that is allowed
for website logins (`[logins.*]`) is not allowed for CLI codes.
- **One tap per code.** Such a secret needs `ask = "always"`: no window
grant and no standing grant. A scheduled grant (`nodkey preapprove`)
has a time span and a number of uses that the owner approved with one
tap, and each use has a silent notice.
- **The seed never leaves the broker.** The broker makes the code and
clears the seed; the client gets the code only, so a leak of it ends
with its time step. A leaked seed would give codes for ever.
- **The kind is checked.** The broker refuses `--totp` for a secret that
is not a TOTP code, and `--secret` for one that is, before any
message. At most one code per request.
- **One `secret_sent` entry per code**, with no code and no seed.
What nodkey does not do:
- It cannot bind a code to the command in the message, or to one write.
The approver reads the command as a claim and taps only when the agent
should have one write with that account in the next 30 s.
- The password or the token of the account is a separate matter: a code
alone does not log in. Keep the token (such as `NPM_TOKEN`) as its own
`[secret.*]`, with its own rule.
Risk that remains: medium for one approved code (any write of that
account for about 30 s), and the number of uses for a scheduled grant.

## 7. Assumptions

- The broker host is patched, has no agent on it, and only the owner has
Expand Down
63 changes: 63 additions & 0 deletions docs/setup.md
Original file line number Diff line number Diff line change
Expand Up @@ -2361,6 +2361,69 @@ check that fails before a message, such as a host that is not in
sent`. Plain `denied` comes after the `waiting for approval` line: the
person denied it, or nobody answered in time.

### A 2FA code for a CLI tool: nodkey run --totp

Some CLI tools ask for a 2FA code on a write. For example `npm publish`
of a new package and `npm trust` fail with `EOTP` without `--otp CODE`.
nodkey can hand one code to such a command, after a tap. The broker
makes the code from the TOTP seed of a Bitwarden login item. The seed
never leaves the broker: the command gets only the code.

1. **Put the seed into the item.** In Bitwarden, the login item of the
account has the TOTP seed in its "Authenticator key" field
(`login.totp`): a base32 secret or an `otpauth://totp/` URI. The item
must be in a collection that the `bw` store can read (see "bw: a
separate Bitwarden account" in section 5).
2. **Allow it in `broker.toml`.** It is off by default. A `[logins.*]`
collection does not allow it.

```toml
[secret.npm-otp]
store = "vault" # a store of type bw
id = "11111111-1111-1111-1111-111111111111" # the ID of the login item
totp = true
clients = ["laptop"]
ask = "always" # needed: one tap per code
preapprove = true # optional: a batch with one tap
```

`totp = true` works only with a `bw` store, and needs
`ask = "always"` and no `standing = true`. Name the section after what
the code is for: the message shows the name.
3. **Use it**, on the agent machine:

```sh
nodkey run --secret NPM_TOKEN=npm-token --totp NPM_OTP=npm-otp -- \
sh -c 'npm publish pkg.tgz --otp "$NPM_OTP"'
```

The message shows `npm-otp` and the command. After **Approve once**,
the broker runs `bw sync --force` and `bw get item`, makes the code
of now, and the command gets it in `NPM_OTP`. At most one `--totp` in
one command.
4. **Many packages with one tap:** a scheduled grant with one use per
package. Each `nodkey run` in its time takes one use and gets its own
fresh code. The grant must name every secret of the command, so here
`npm-token` too, and both need `preapprove = true` (see "A job that
runs later" below):

```sh
nodkey preapprove --secret npm-token --secret npm-otp \
--until 2026-11-19T18:00 --uses 8 \
--reason "publish the 8 new packages"
```

Things to know:

- A code works for **any** write of that account, for its time step
(about 30 s), not only for the command in the message. The command
line is what the agent claims (THREAT-MODEL.md T54). Tap only when the
agent should make a write with that account now.
- Two runs in the same 30 s get the same code. Some sites take a code
only once: then wait 30 s between two runs.
- An item with no seed, or a seed in a form that nodkey does not read,
denies the request. The journal says which secret and what to fix.

### A job that runs later: nodkey preapprove

New in 0.3.0: nodkey 0.2.0 does not have it.
Expand Down
27 changes: 27 additions & 0 deletions internal/api/api_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -945,3 +945,30 @@ func TestKeyWindow(t *testing.T) {
}
}
}

// TestSecretRefKind: "kind" is optional. "totp" is the only kind; any
// other value, a null, a number and two kinds are refused. A SecretRef
// with no kind is written with no "kind" field, as before.
func TestSecretRefKind(t *testing.T) {
var r SecretRef
if err := json.Unmarshal([]byte(`{"var":"A","name":"a","kind":"totp"}`), &r); err != nil || r.Kind != KindTOTP {
t.Errorf("kind totp: %+v, %v", r, err)
}
for _, bad := range []string{
`{"var":"A","name":"a","kind":"TOTP"}`,
`{"var":"A","name":"a","kind":""}`,
`{"var":"A","name":"a","kind":"password"}`,
`{"var":"A","name":"a","kind":null}`,
`{"var":"A","name":"a","kind":1}`,
`{"var":"A","name":"a","kind":"totp","kind":"totp"}`,
} {
var r SecretRef
if err := json.Unmarshal([]byte(bad), &r); err == nil {
t.Errorf("%s was accepted", bad)
}
}
b, err := json.Marshal(SecretRef{Var: "A", Name: "a"})
if err != nil || string(b) != `{"var":"A","name":"a"}` {
t.Errorf("a plain secret is written as %s, %v", b, err)
}
}
29 changes: 15 additions & 14 deletions internal/api/decode.go
Original file line number Diff line number Diff line change
Expand Up @@ -10,20 +10,21 @@ import (
// Errors of the strict decoding and of the caps. They never hold text from
// the data, so they are safe to log.
var (
errNotObject = errors.New("api: the value is not a JSON object")
errSyntax = errors.New("api: the data is not valid JSON")
errUnknown = errors.New("api: an object has an unknown field")
errDuplicate = errors.New("api: a field appears twice in one object")
errMissing = errors.New("api: an object misses a field")
errNull = errors.New("api: a field or a list item is null")
errType = errors.New("api: a value has the wrong type")
errTrailing = errors.New("api: more data after the JSON value")
errTooMany = errors.New("api: a list has more items than its cap")
errTooLong = errors.New("api: a value is longer than its cap")
errBadWindow = errors.New("api: a window is not valid")
errBadVar = errors.New("api: a variable name is not valid")
errRead = errors.New("api: the answer could not be read")
errTooLarge = errors.New("api: the answer is larger than api.MaxAnswer")
errNotObject = errors.New("api: the value is not a JSON object")
errSyntax = errors.New("api: the data is not valid JSON")
errUnknown = errors.New("api: an object has an unknown field")
errDuplicate = errors.New("api: a field appears twice in one object")
errMissing = errors.New("api: an object misses a field")
errNull = errors.New("api: a field or a list item is null")
errType = errors.New("api: a value has the wrong type")
errTrailing = errors.New("api: more data after the JSON value")
errTooMany = errors.New("api: a list has more items than its cap")
errTooLong = errors.New("api: a value is longer than its cap")
errBadWindow = errors.New("api: a window is not valid")
errBadVar = errors.New("api: a variable name is not valid")
errUnknownKind = errors.New("api: a secret has an unknown kind")
errRead = errors.New("api: the answer could not be read")
errTooLarge = errors.New("api: the answer is larger than api.MaxAnswer")
)

// field decodes the value of one field of an object. The value is not
Expand Down
37 changes: 34 additions & 3 deletions internal/api/types.go
Original file line number Diff line number Diff line change
Expand Up @@ -142,15 +142,46 @@ type SecretRef struct {
Var string `json:"var"`
// Name is the name of a [secret.*] section, such as "github-token".
Name string `json:"name"`
// Kind is "" for a secret value (--secret), or KindTOTP for a TOTP
// code (--totp). The broker checks it against the config: a secret
// with totp = true is handed out only as KindTOTP, and KindTOTP only
// for such a secret (DESIGN.md section 5, "TOTP codes"). A request
// with no TOTP code has no "kind" field, as before.
Kind string `json:"kind"`
}

// UnmarshalJSON decodes strictly.
// MarshalJSON writes no field "kind" for a secret value, so such a
// request is the same as before TOTP codes.
func (s SecretRef) MarshalJSON() ([]byte, error) {
type plain SecretRef
if s.Kind == "" {
return json.Marshal(struct {
plain
Kind *struct{} `json:"kind,omitempty"`
}{plain: plain(s)})
}
return json.Marshal(plain(s))
}

// KindTOTP is the Kind of a SecretRef that asks for a TOTP code.
const KindTOTP = "totp"

// UnmarshalJSON decodes strictly. "kind" is optional; when it is there,
// it must be KindTOTP.
func (s *SecretRef) UnmarshalJSON(data []byte) error {
var v SecretRef
err := decodeObject(data, map[string]field{
hasKind := false
err := decodeObjectOptional(data, map[string]field{
"var": text(&v.Var),
"name": text(&v.Name),
})
"kind": func(raw json.RawMessage) error {
hasKind = true
return decodeText(raw, &v.Kind)
},
}, map[string]bool{"kind": true})
if err == nil && hasKind && v.Kind != KindTOTP {
err = errUnknownKind
}
if err != nil {
return err
}
Expand Down
Loading