You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
run: hand out a TOTP code to a CLI command (e.g. npm publish --otp), with a tap #212
Some CLI tools ask for a 2FA code on a write. Example: npm publish of a new package, and npm trust (they fail with EOTP without a code). Today the owner reads the code from an authenticator app and types it, once per package (a code lasts 30 s).
nodkey already makes TOTP codes on the broker from the login.totp field of a Bitwarden item (DESIGN.md section 21, internal/totp). But it hands a code out only in the agent-browser login flow: after an approved login of the same item, for the same page origin. A CLI tool has no page and needs no password, so there is no way to get only a code.
Idea
A code as a run secret, for example:
nodkey run --totp OTP=ITEM -- sh -c 'npm publish pkg.tgz --otp "$OTP"'
The seed never leaves the broker; the client gets one code.
A tap per code, as for any other secret. A preapprove grant (time span, number of uses) covers a batch, for example 8 packages with one tap, each with its own fresh code.
Only items allowed for codes in the broker config (a new rule, closed by default).
The Telegram message names the item and the command, as for run secrets.
Audit entry per code, with no code and no seed in it.
Done when
DESIGN.md has the design: config rule, request path, grants, audit, threats (a code is short-lived but works for any write of that account in its 30 s window)
nodkey run --totp VAR=ITEM gives one code after a tap, and is refused for items not allowed
A preapprove grant gives one fresh code per use, up to its number of uses
Tests for the refusals (item not allowed, no seed, grant used up)
Not queued for a job yet: it widens what the broker hands out (a code that works for any write of that account for about 30 s). The design and its threat notes need the owner's OK before a session builds it.
Queued 2026-11-19: the owner approved the idea above. A build job starts today (design, code, tests, merge; no release). A real use comes after the next release and needs one setup step by the owner.
Owner side is ready (2026-11-19): the npm account uses an authenticator app (TOTP), and its seed is in a Bitwarden password manager item. After the release with this feature, a session adds the broker config rule that allows that item for CLI codes (and checks that the item is in a collection the broker reads), then does a first real npm publish --otp with one tap.
2026-11-19: the owner moved the npm login item into the collection the broker reads. Left after the release: the broker config rule for that item, then one real publish.
Built and merged in #223 (squash commit bf0d37d), 2026-11-19. No release was made.
Evidence for each "Done when" box:
DESIGN.md has the design: DESIGN.md section 5, "TOTP codes" (config rule, request path, kind check, grants, audit), and the [secret.npm-otp] example in section 14. The risk is THREAT-MODEL.md T54: a code works for any write of that account in its time step (about 30 s), and the command line is claimed by the client.
nodkey run --totp VAR=NAME gives one code after a tap, and is refused for items not allowed: TestTOTPCode (tap, then the RFC 6238 code; no seed or code in the entries, the log or the message; the seed is cleared). TestTOTPRefused (a totp secret with --secret, --totp for a plain secret, two codes, another client, an unknown name: all 403 before any message). TestLoadBrokerTOTP (only bw stores, only ask = "always", no standing grants). TestParseArgsTOTP, TestSecretRefKind.
A preapprove grant gives one fresh code per use, up to its number of uses: TestTOTPPreapprove (2 uses give 2 codes, each the code of its own moment, then the next request asks for a tap).
Tests for the refusals: item not allowed: TestTOTPRefused, TestTOTPGrantToken, TestTOTPReloadEndsGrant. No seed: TestTOTPNoSeed (no seed, steam seed, bad base32, store failure) and, with a fake bw, TestBWFetchTOTPRefused. Grant used up: TestTOTPPreapprove.
README shows the npm example: README, "A 2FA code for a CLI tool", and docs/setup.md, "A 2FA code for a CLI tool: nodkey run --totp".
One note on the name: --totp VAR=NAME names a [secret.*] section with totp = true, not a Bitwarden item ID, as for --secret. This is how the config allows it (closed by default).
Left for the owner, after the next release (not part of the boxes above):
Add the [secret.*] section with totp = true for the npm login item to the broker config (ask = "always", and preapprove = true for a batch). The npm token needs preapprove = true too if a batch uses both.
Activity
groupsky commentedon Nov 18, 2026
Not queued for a job yet: it widens what the broker hands out (a code that works for any write of that account for about 30 s). The design and its threat notes need the owner's OK before a session builds it.
groupsky commentedon Nov 19, 2026
Queued 2026-11-19: the owner approved the idea above. A build job starts today (design, code, tests, merge; no release). A real use comes after the next release and needs one setup step by the owner.
groupsky commentedon Nov 19, 2026
Owner side is ready (2026-11-19): the npm account uses an authenticator app (TOTP), and its seed is in a Bitwarden password manager item. After the release with this feature, a session adds the broker config rule that allows that item for CLI codes (and checks that the item is in a collection the broker reads), then does a first real
npm publish --otpwith one tap.groupsky commentedon Nov 19, 2026
2026-11-19: the owner moved the npm login item into the collection the broker reads. Left after the release: the broker config rule for that item, then one real publish.
groupsky commentedon Nov 19, 2026
hq-jobs
nodkey-212-build(runr-20261119-130020-3c58)Built and merged in #223 (squash commit bf0d37d), 2026-11-19. No release was made.
Evidence for each "Done when" box:
[secret.npm-otp]example in section 14. The risk is THREAT-MODEL.md T54: a code works for any write of that account in its time step (about 30 s), and the command line is claimed by the client.nodkey run --totp VAR=NAMEgives one code after a tap, and is refused for items not allowed:TestTOTPCode(tap, then the RFC 6238 code; no seed or code in the entries, the log or the message; the seed is cleared).TestTOTPRefused(a totp secret with--secret,--totpfor a plain secret, two codes, another client, an unknown name: all 403 before any message).TestLoadBrokerTOTP(onlybwstores, onlyask = "always", no standing grants).TestParseArgsTOTP,TestSecretRefKind.preapprovegrant gives one fresh code per use, up to its number of uses:TestTOTPPreapprove(2 uses give 2 codes, each the code of its own moment, then the next request asks for a tap).TestTOTPRefused,TestTOTPGrantToken,TestTOTPReloadEndsGrant. No seed:TestTOTPNoSeed(no seed, steam seed, bad base32, store failure) and, with a fakebw,TestBWFetchTOTPRefused. Grant used up:TestTOTPPreapprove.One note on the name:
--totp VAR=NAMEnames a[secret.*]section withtotp = true, not a Bitwarden item ID, as for--secret. This is how the config allows it (closed by default).Left for the owner, after the next release (not part of the boxes above):
[secret.*]section withtotp = truefor the npm login item to the broker config (ask = "always", andpreapprove = truefor a batch). The npm token needspreapprove = truetoo if a batch uses both.npm publish --otpwith one tap.