Skip to content

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

Closed

Description

@groupsky

Why

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)
  • README shows the npm example

Activity

  1. groupsky commented on Nov 18, 2026

    @groupsky
    ContributorAuthor

    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.

  2. groupsky commented on Nov 19, 2026

    @groupsky
    ContributorAuthor

    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.

  3. groupsky commented on Nov 19, 2026

    @groupsky
    ContributorAuthor

    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.

  4. groupsky commented on Nov 19, 2026

    @groupsky
    ContributorAuthor

    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.

  5. groupsky commented on Nov 19, 2026

    @groupsky
    ContributorAuthor

    hq-jobs nodkey-212-build (run r-20261119-130020-3c58)

    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):

    1. 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.
    2. One real npm publish --otp with one tap.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions