Skip to content

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

Open

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.

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