Skip to content

feat(run): hand out a TOTP code to a command with --totp - #223

Merged
groupsky merged 1 commit into
mainfrom
hq-job/nodkey-212-build/r-20261119-130020-3c58
Nov 19, 2026
Merged

groupsky merged 1 commit into
mainfrom
hq-job/nodkey-212-build/r-20261119-130020-3c58

Conversation

@groupsky

@groupsky groupsky commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

What and why

Fixes #212. nodkey run --totp VAR=NAME hands one TOTP code to one command, after a tap. Example: npm publish --otp and npm trust, which fail with EOTP without a code.

nodkey run --secret NPM_TOKEN=npm-token --totp NPM_OTP=npm-otp -- \
  sh -c 'npm publish pkg.tgz --otp "$NPM_OTP"'
  • Config (closed by default): a [secret.*] section with totp = true, only for a store of type bw. It needs ask = "always" and no standing = true; preapprove = true is allowed. A [logins.*] item is not a CLI code.
  • Client: --totp VAR=NAME (at most one) sends the variable with "kind": "totp". A --secret sends no kind field, as before.
  • Broker: checks the kind against the config both ways, before any message (403 not_allowed). After the tap it runs bw sync --force and bw get item, reads login.totp, clears the password at once, makes the code of now with internal/totp, and clears the seed and the key. The seed never leaves the broker.
  • Grants: a scheduled grant (nodkey preapprove) gives one fresh code per use, up to its uses. No window and no standing grants.
  • Message and audit: as for any run secret (secret name, command). One secret_sent entry per code, with no code and no seed.
  • Docs: DESIGN.md section 5 "TOTP codes" and section 14, THREAT-MODEL.md T54, README, docs/setup.md "A 2FA code for a CLI tool".

Behavior for callers

Changes behavior for existing callers: no

A request without --totp is the same on the wire. An old broker refuses the new kind field (strict decoding): it fails closed, and the client adds a hint to update the broker.

Tests

  • broker: TestTOTPCode, TestTOTPRefused (totp secret as --secret, --totp for a plain secret, two codes, another client, unknown name), TestTOTPNoSeed (no seed, steam seed, bad base32, store failure), TestTOTPPreapprove (2 uses, 2 fresh codes, then a tap), TestTOTPGrantToken, TestTOTPReloadEndsGrant
  • store (fake bw): TestBWFetchTOTP, TestBWFetchTOTPRefused, TestOnlyBWHandsOutTOTP
  • config: TestLoadBrokerTOTP, TestDiffTOTP
  • api: TestSecretRefKind; client: TestParseArgsTOTP, TestTOTPHint, new cases in TestRunUsage
  • go test -race ./..., go vet ./..., golangci-lint run --build-tags e2e: pass.

Security review

Done with .claude/agents/security-reviewer.md: no critical, high or medium findings. Low findings fixed: the batch example in the docs, more deny-path tests, the fix text of a bad seed, a hint for an old broker. Not fixed, on purpose: the code is a Go string (from totp.Key.Code) and cannot be cleared. It is a 6 to 8 digit code that lasts about 30 s, and the website-login path does the same; a change of internal/totp for both paths can be a follow-up.

Progress

  • Design (DESIGN.md, THREAT-MODEL.md T54)
  • Config, store, broker, client, api
  • Tests for the deny paths
  • README and setup guide
  • Security review
  • CI green, merge

Checklist

  • The title follows Conventional Commits (feat:, fix:, docs: ...).
  • Tests cover the deny paths, not only the happy path.
  • The docs are updated: DESIGN.md and THREAT-MODEL.md if a message, a check or the path of a value changes; docs/ if a command or the config changes.
  • The security review is done (AGENTS.md).
  • No private data: no real host name, address, token, key or private name.

🤖 Generated with Claude Code

nodkey run --totp VAR=NAME gives the current TOTP code of a Bitwarden
login item to one command, after a tap. Only a [secret.*] section with
totp = true (bw store, ask = "always", no standing grants) hands one
out. The broker makes the code; the seed never leaves it. A scheduled
grant gives one fresh code per use.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@groupsky
groupsky merged commit bf0d37d into main Nov 19, 2026
8 checks passed
@groupsky
groupsky deleted the hq-job/nodkey-212-build/r-20261119-130020-3c58 branch November 19, 2026 11:24
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

run: hand out a TOTP code to a CLI command (e.g. npm publish --otp), with a tap

1 participant