Skip to content

feat: warn when the client and the broker run different versions #89

Closed

Description

@groupsky

Nothing tells you today when a client and the broker run different versions. docs/setup.md section 2 asks for the same version everywhere. Requests and answers are strict JSON: no unknown field may be there, on both sides. So a mixed pair can fail with only "the answer of the broker is not valid".

Plan

  • Each client request carries a Nodkey-Version header with the client's version. Each broker answer carries a Nodkey-Version header with the broker's version: every status, errors too. It is a header, not a JSON field, so old and new versions still talk to each other.
  • Each side takes the other side's value only if it matches a strict pattern, like the one in the audit log (^[A-Za-z0-9][A-Za-z0-9.+_-]{0,63}$). Any other value counts as "no version" and is never printed.
  • Only release versions (X.Y.Z) are compared, as numbers. If either side is a build from the source, there is no warning and no notice.
  • Client: when the two versions differ, print one warning line on stderr, once per process. For nodkey ssh-agent, print it once per broker version. The line says which side is older, and to run sudo nodkey update there (feat: install script and nodkey update #88). A broker that sends no version is "an older nodkey that does not send its version".
  • Broker: the client's version is a claim. Anyone with the client's key can send any value, so it decides nothing. When it differs from the broker's version, or is missing, the broker writes one journal line. It also sends one silent Telegram notice per client per broker start, with the client's name from its [client.*] section, the two versions, and what to run.
  • Owner decision, 2026-10-17: both the client warning and the Telegram notice.
  • These notices must not use up the limits for notices of "never ask" uses (DESIGN.md sections 7 and 8), and must never deny or slow a request. A notice that cannot be sent is only logged.

Done when

  • Both headers are there, on every answer of the broker.
  • The client warning works as above. Tests cover: the same version, an older client, an older broker, a broker with no header, a bad header value (not printed), builds from the source, and ssh-agent with a broker that changes its version.
  • The broker writes the journal line and sends at most one notice per client per start, even when one client claims many different versions. Tests show that the answer to the request does not change, and that the limits for "never ask" notices are not used. (After the review: a client is marked only after a notice went out, and a failed try is tried again a minute later at the earliest. So rarely a second notice can come. DESIGN.md section 7 says so.)
  • The end-to-end test passes. Today it fails on any message without buttons; change that rule only as far as needed.
  • DESIGN.md (sections 7 and 15, and the part about the protocol) and THREAT-MODEL.md (the version is a claim; at most one notice per client) are updated. docs/setup.md says what the warning means.

Activity

  1. groupsky commented on Oct 17, 2026

    @groupsky
    ContributorAuthor

    Done in #93 (a79bf9a). The texts that say sudo nodkey update are part of #94.

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