Skip to content

feat: nodkey try, a trial on one machine with fake secrets #125

Open

Description

@groupsky

Why

To see nodkey work today, a person needs a second Linux host that is always on, a Telegram bot, a Bitwarden account, and the steps of docs/setup.md sections 3 to 11. Many people stop before the first tap. They need a way to see the flow first, in a few minutes, with nothing to set up.

What

Decided by the owner (2026-10-29): a one-machine trial with fake secrets.

  • nodkey try, run as a normal user: no root, no systemd, no store account, no config file.
  • It makes a temporary directory (mode 0700) with a broker key, a client key, both configs and an audit log. It runs the real broker parts on 127.0.0.1 with a random port: mutual TLS with pins, the approval core and the audit log. It skips only what needs systemd or root.
  • A test store with 3 fake secrets, such as demo-token. Their values are random, made at start, and start with TRY-.
  • Approval in the terminal by default: the nodkey try terminal shows the message and asks Approve once, Approve N min, or Deny.
  • Telegram, guided (--telegram, stage 2: a second pull request after the terminal trial works): the person makes a new bot in BotFather and pastes its token (hidden input, kept only in memory). nodkey prints the link https://t.me/BOT?start=CODE. It takes the approver's user ID only from the /start CODE message, shows the name, and asks to confirm. No curl getUpdates step. feat: guided broker setup (nodkey setup broker) #98 step 5 can reuse this.
  • It prints commands for a second terminal, such as nodkey try run --secret DEMO_TOKEN=demo-token -- sh -c 'echo "got ${#DEMO_TOKEN} characters"'. nodkey try run is nodkey run with the trial's client config; it never reads ~/.config/nodkey/client.toml.
  • Every message and every client line says TRY MODE.
  • On Ctrl-C it stops, removes the directory, and says what a real setup adds: a separate broker host, a store, the rules (with links to docs/setup.md).

Security points.

  • Approval in the terminal exists only in try mode. nodkey broker must have no way to turn it on: a terminal on the agent machine is a place where the agent can type.
  • The trial reads no config file and has only the test store. So it can never hand out a real secret.
  • The bot token is typed on this machine, which may be an agent machine (docs/setup.md, "Where you do the setup"). So the guide says: use a new bot for the trial, never the broker's bot. With the broker's bot, both would poll, and the real broker stops with exit code 76 (T6). On a conflict from Telegram, nodkey try stops and says this.

Must change: DESIGN.md sections 4 and 15 (the command); THREAT-MODEL.md (what try mode is, and why it cannot reach a real secret); README.md (a "Try it" part before the setup guide).

Open questions

  1. macOS: the broker parts may run without systemd, but nodkey run is Linux only today (Clients for macOS and Windows #35). Proposed: Linux first.
  2. One terminal: nodkey try could also send the demo request itself, after a key press. Is that clearer than two terminals?
  3. SSH logins in the trial (a throwaway key and a local sshd)? Proposed: later.

Done when

  • As a new Linux user with no root and no config, nodkey try and nodkey try run ... work end to end with approval in the terminal: Approve once, Approve N min, Deny, and an expiry.
  • Stage 2: --telegram works with a new bot: a manual test, with the results in the docs.
  • Nothing is written outside the temporary directory, and the directory is removed on exit, also on SIGINT and SIGTERM. Tests.
  • Tests show that try mode reads no config file and no real store, and that nodkey broker has no terminal approval.
  • README.md and the sections above are updated. It gets the security review, as every change does.

Related: #98 (guided broker setup), #30 (pairing), #35 (macOS client), #124.

Activity

  1. groupsky commented on Oct 31, 2026

    @groupsky
    ContributorAuthor

    Stage 1 (nodkey try, approval in the terminal) is merged in #143.

    Stage 2 (nodkey try --telegram) is ready in #144, with green CI. Its tests use a fake Telegram. The last box of "Done when" needs a manual test with a real new bot on your phone.

    @groupsky, could you run check 16 of docs/manual-telegram-test.md on the branch feat/125-try-telegram? In short:

    1. Make a new bot in BotFather (not the bot of a real broker).
    2. nodkey try --telegram, paste the token (it should not show), open the link on the phone, tap Start, type yes.
    3. In a second terminal, the nodkey try run command it prints: tap Approve once, then run it again and tap Deny.
    4. Optional: the bot of a running test broker, to see the conflict.
    5. Ctrl-C, then delete the bot.

    Please post the 4 rows of check 16 of the results table here (no token, no user ID, no bot name), then remove the label question. A later session adds the results to the docs, merges #144 and closes this issue.

  2. groupsky commented on Nov 18, 2026

    @groupsky
    ContributorAuthor

    hq-jobs nodkey-166-144-1118 (run r-20261118-072516-15ff)

    Stage 2 (#144) is rebased onto main at 0b97ca2 (after #166), and CI is green.

    • Stage 1 (nodkey try) is as on main.
    • After the rebase, a correctness review and two security reviews ran. Their findings are fixed: a second trial checks for a running one before it polls the bot; a signal during the setup ends with exit code 0; every new error says how to fix it; Options.Prefix has a cap and every message keeps room for it; T38 says what a pasted broker token gives the agent. Details are in the PR description.
    • Main added checks 16 and 17 (1Password, Infisical), so the trial with Telegram is now check 18 of docs/manual-telegram-test.md. It is the same test as the "check 16" of my comment of 2026-10-31.

    Ready for the manual check 18 with a new bot. Please post its 4 rows here (no token, no user ID, no bot name), then remove the label question. #144 stays a draft until then.

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

    enhancementNew feature or requestquestionFurther information is requested

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions