Skip to content

feat: nodkey broker check checks a config without a start - #178

Merged
groupsky merged 1 commit into
mainfrom
feat/173-broker-check
Nov 11, 2026
Merged

groupsky merged 1 commit into
mainfrom
feat/173-broker-check

Conversation

@groupsky

@groupsky groupsky commented Nov 11, 2026 •

Copy link
Copy Markdown
Contributor

Closes #173.

What

nodkey broker check [--config FILE] [--files DIR] [--credentials DIR] checks a broker config without a start.

  • It parses the config with the same code as the start and a reload: config.loadBroker now takes a files directory, and config.ReadBrokerFiles is its entry. nodkey doctor broker uses the same parser (ReadBroker) and the same file checks (CheckFilesAs).
  • It then checks the files that the config names with CheckFilesAs, for the user that runs it. The list of private files is now one function, (*Broker).PrivateFiles, used by CheckFilesAs and by the check. The checks of the start do not change.
  • It starts nothing, opens no port, uses no network, and needs no root.
  • A ${CREDENTIALS_DIRECTORY}/ file is skipped, and the output says so. With --credentials DIR, it only looks for NAME or NAME.cred in DIR. It opens none of them.
  • With --files DIR, known_hosts is read from DIR by its base name, not from its path. The files of the broker host (TLS key, token and key files, store programs, audit log) are then not checked. Without --config, the config is DIR/broker.toml.
  • Exit codes: 0 good, 1 not good (one line with the reason and the docs section), 64 wrong usage.
  • Every output line is cleaned with claim.Line, so text in a config from a pull request cannot add lines to a CI log.

What it cannot find: problems that only the content of a credential shows, such as a key that does not parse. The start and a reload still check these. DESIGN.md says so.

Tests

  • TestBrokerCheckRefusesWhatTheStartRefuses: for 5 bad configs (bad pin, unknown host, store program that others can change, known_hosts that others can change, audit log that is another file of the broker), the real nodkey broker start in a child process exits 1, and the check exits 1 with the same reason. A good config passes.
  • TestBrokerCheckFiles: with --files, the known_hosts at the config's path is removed and the check passes; then a good file at the path and a bad one in DIR: the check refuses.
  • TestBrokerCheckNeedsNoCredentials: runs as a user that is not root, with the listen address held by the test. Skips each credential without --credentials; finds NAME and NAME.cred files with mode 0 (not read); refuses a missing one, a directory, a directory it cannot enter (with its own error), and a path with ...
  • TestBrokerCheckCleansConfigText, TestBrokerCheckUsage.

Security review

The security-reviewer agent found 1 medium and 4 low points, then 2 more low points. All are fixed. One note is left for a follow-up issue: the start accepts ${CREDENTIALS_DIRECTORY}/../x (the check refuses it). This is a change of the start, outside this issue.

Progress

  • Command and exit codes
  • Shared code with the start and doctor
  • --files, --credentials
  • Tests, lint, security review
  • DESIGN.md section 15, THREAT-MODEL.md, docs/setup.md section 7
  • CI green

🤖 Generated with Claude Code

nodkey broker check --config FILE [--files DIR] [--credentials DIR]
parses the config with the parser of the start and a reload, and checks
the files it names with CheckFilesAs. It starts nothing, opens no port,
uses no network, needs no root, and reads no credential.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
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.

feat: nodkey broker check — check a config without starting the broker

1 participant