Repository navigation
Closed
Labels
enhancementNew feature or requestNew feature or request
Description
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
andknown_hosts(as--filesin 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: "clientlaptop: 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
askmoved from "always" to "window"; - a longer
window, widerhours, a highermax_per_day, or
notifyturned off; - more hosts or users for a key;
preapprove = trueorstanding = trueon 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_logorknown_hostspath; - 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 Ncharacters, 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.
Metadata
Metadata
Assignees
Labels
enhancementNew feature or requestNew feature or request
Activity
groupsky commentedon Nov 11, 2026
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,SameKeyandKeyHost(internal/config/reload.go), and aSumfield (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.groupsky commentedon Nov 11, 2026
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-revieweragent had no open finding at the end.Evidence for each "Done when" box:
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 theknown_hostsnext to it) or a directory withbroker.tomlandknown_hosts. Both are read with the parser of the start, throughconfig.ReadBrokerFilesfrom 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 missingknown_hostsand an invalid config.TestConfigDiffUsage: 64 on wrong usage, one line.TestDiffMarksWideninghas one subtest per kind (37 cases, from "a new client" to "a new host key"), andTestDiffNtfycovers the[ntfy]settings and the channel switch. Unknown kinds: a reflection catch-all compares every field that is not compared by name.TestDiffUnknownIsMarkedshows that such a change is marked "a change that config-diff does not know", andTestDiffComparesEveryFieldfails when a new field is in neither list.TestDiffNarrowingshows that narrowing changes are plain lines.TestDiffSameMeaning(comments, spaces, the order of sections, of clients and ofknown_hostslines), and the first step ofTestConfigDifffor the command.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.TestConfigDiffruns 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 theirknown_hosts, and has no network code.Section 7, "See what a config change means", with an example. DESIGN.md section 15 and THREAT-MODEL.md (after T42) describe it too.