Skip to content

feat: nodkey broker config-diff — list config changes by meaning, mark the ones that widen access #174

Closed

Description

@groupsky

Why

When the broker config changes, the owner must see what the change
means
: who gets which secret, and with or without a tap. A text diff of
TOML does not show that well. A change that widens access must stand out.
This is the summary that #102's confirmation shows.

Wanted

nodkey broker config-diff OLD NEW:

  • OLD and NEW are each a config file, or a directory with broker.toml
    and known_hosts (as --files in feat: nodkey broker check — check a config without starting the broker #173);
  • reads both with the normal config parser, and compares them by
    meaning, not by text;
  • prints one line per change, grouped by client, secret, SSH key and
    rule. For example: "client laptop: new rule: never ask for
    backup-token";
  • marks every change that widens access or weakens a control with a
    warning sign at the start of the line. These include:
    • a new client;
    • a new secret or key for a client;
    • a new "never ask" rule, or ask moved from "always" to "window";
    • a longer window, wider hours, a higher max_per_day, or
      notify turned off;
    • more hosts or users for a key;
    • preapprove = true or standing = true on a secret or key, or a
      longer or wider [preapprove] or [standing] limit;
    • a changed approver or notice setting, or a longer timeout;
    • a changed client pin;
    • a changed store: its program, server, token or password file, or
      a secret that now points to another store, item or field;
    • a changed listen, tls_key, audit_log or known_hosts path;
    • a new host, or a changed host key, in known_hosts.
      Any change that the command does not know as narrowing is marked too.
      So a new config key is never shown as harmless. A change that narrows
      access is a plain line;
  • has a short form (--short, at most --max-chars N characters, 3500
    by default) that fits one Telegram message next to the caller's own
    text. It puts the widening changes first, and cuts the rest with "and N
    more". If the widening lines alone do not fit, it says how many there
    are and that the full list must be read;
  • exits 0 when the two configs mean the same, 1 when they differ, and 2
    when a file cannot be read.

Done when

  • The command exists, with the output and exit codes above.
  • Every kind of widening change listed above has a test that it is
    marked. A change of a kind the command does not know is marked. A
    test.
  • A change in comments, order or spacing alone gives "no change". A
    test.
  • The short form keeps every widening line when it cuts, or says
    that they do not fit. A test.
  • It needs no root, no credentials and no network.
  • docs/setup.md shows it.

Related: #102, #29, and #173 (config check).

Activity

  1. groupsky commented on Nov 11, 2026

    @groupsky
    ContributorAuthor

    Not started yet. The job run on 2026-11-11 built #29 first (merged in #175), and the budget of that run was not enough for this issue too. Nothing is done here yet; everything in "Done when" is still open.

    Note for this work: #175 added config.Broker.ReloadFixed, SameClient, SameSecret, SameKey and KeyHost (internal/config/reload.go), and a Sum field (the SHA-256 of the config file). They may help here, so the check and the diff can share the config code with the start and the reload.

  2. groupsky commented on Nov 11, 2026

    @groupsky
    ContributorAuthor

    Done in #180, squash merged as c6d8d6d. CI was green (tests on go.mod and stable Go, lint, vuln, end-to-end test, title check). The security-reviewer agent had no open finding at the end.

    Evidence for each "Done when" box:

    • The command exists, with the output and exit codes above.
      nodkey broker config-diff [--short] [--max-chars N] OLD NEW (cmd/nodkey/configdiff.go, internal/config/diff.go). OLD and NEW are a config file (with the known_hosts next to it) or a directory with broker.toml and known_hosts. Both are read with the parser of the start, through config.ReadBrokerFiles from feat: nodkey broker check checks a config without a start #178. One line per change, sorted by group and name; widening lines start with ⚠. TestConfigDiff: exit 0 ("no change"), 1, and 2 for a missing path, a missing known_hosts and an invalid config. TestConfigDiffUsage: 64 on wrong usage, one line.
    • Every kind of widening change listed above has a test that it is marked. A change of a kind the command does not know is marked. A test.
      TestDiffMarksWidening has one subtest per kind (37 cases, from "a new client" to "a new host key"), and TestDiffNtfy covers the [ntfy] settings and the channel switch. Unknown kinds: a reflection catch-all compares every field that is not compared by name. TestDiffUnknownIsMarked shows that such a change is marked "a change that config-diff does not know", and TestDiffComparesEveryField fails when a new field is in neither list. TestDiffNarrowing shows that narrowing changes are plain lines.
    • A change in comments, order or spacing alone gives "no change". A test.
      TestDiffSameMeaning (comments, spaces, the order of sections, of clients and of known_hosts lines), and the first step of TestConfigDiff for the command.
    • The short form keeps every widening line when it cuts, or says that they do not fit. A test.
      TestConfigDiffShort: the widening lines come first and all stay, the cut ends with "and N more", the size never passes --max-chars (counted in UTF-16 units, as Telegram counts), and when the widening lines do not fit, one line says how many there are and that the full list must be read.
    • It needs no root, no credentials and no network.
      TestConfigDiff runs as a user that is not root, with configs whose key and token files are in ${CREDENTIALS_DIRECTORY}, and without them. The command reads only the two configs and their known_hosts, and has no network code.
    • docs/setup.md shows it.
      Section 7, "See what a config change means", with an example. DESIGN.md section 15 and THREAT-MODEL.md (after T42) describe it too.
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 request

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions