nodered: its MQTT broker comes from the mesh

Node-RED's one broker node pointed at zurag.be:1884, where nothing listens. nodered now requires
mqtt-topic (asking for every topic: flows follow the devices' own) and a run-once `mqtt` step —
declared last, restarted when the binding, credential or settings change — points the mesh's broker
nodes at the bound broker through Node-RED's admin API with the module's api-token: the node the
step makes itself when none is named, or the ones an assignment names in `mqtt.brokers`. Only host,
port, TLS and the login change; the broker is asked first whether it takes the login; the deploy is
against the revision read ("nodes", so only that node restarts) and a digest makes a rerun a no-op.
A broker node nobody named is never touched. settings.js keeps `mqtt` and `topics` out of Node-RED.

modules/mosquitto/Dockerfile

@@ -13,7 +13,7 @@ ARG RUNTIME_BASE
 FROM ${BUILD_BASE} AS build
 WORKDIR /app/modules/mosquitto
 COPY . .
-RUN node /app/node_modules/typescript/bin/tsc topics.ts client.ts index.ts tools/index.ts provisioner/index.ts bootstrap/index.ts \
+RUN node /app/node_modules/typescript/bin/tsc client.ts index.ts tools/index.ts provisioner/index.ts bootstrap/index.ts \
       --module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist
 
 FROM ${RUNTIME_BASE}

modules/mosquitto/client.ts

@@ -20,8 +20,6 @@ import { readFileSync } from "node:fs";
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 
-import { missingAcls, parseRoleAcls, staleAcls, wantedAcls } from "./topics.js";
-
 const run = promisify(execFile);
 
 export interface MqttConn {
@@ -143,19 +141,14 @@ export class MosquittoClient {
   }
 
   /**
-   * Create (or reset to a known state) a client granted exactly these topic filters, idempotently.
+   * Create (or reset to a known state) a client scoped to one topic namespace, idempotently. The
-   * The grant is a same-named role carrying, for every filter, publish, receive and subscribe — and
+   * client is confined to `<prefix>/#` by a same-named role: it may publish to, subscribe to and
-   * nothing else: an ACL the role carries that the filters no longer name is removed, so narrowing a
+   * receive on exactly its own subtree and nothing else — the MQTT analog of redis's keyspace-scoped
-   * consumer's `topics` narrows what it may do. By default the filters are the consumer's own
+   * ACL user. Called again for an existing client, it resets the password and re-asserts the ACLs.
-   * subtree, `<as>/#` (see topics.ts). Called again for an existing client, it resets the password
-   * and re-asserts the ACLs.
-   *
-   * Only the role named for this client is ever changed. A client or role the mesh did not make —
-   * a device carried from the predecessor's password file, its `legacy-full-access` role — is never
-   * read, changed or removed here.
    */
-  async createScopedClient(username: string, password: string, filters: readonly string[]): Promise<void> {
+  async createScopedClient(username: string, password: string, topicPrefix: string): Promise<void> {
     const role = username; // one role per client, named for it
+    const pattern = `${topicPrefix}/#`;
 
     if (await this.clientExists(username)) {
       await this.ctl("setClientPassword", username, password);
@@ -168,18 +161,17 @@ export class MosquittoClient {
       await this.ctl("createClient", username, "-p", password);
     }
 
-    // createRole and addRoleACL are one-shot: each rejects with an "already exists" when re-run
+    // A role carrying exactly this client's topic ACLs. createRole, addRoleACL and addClientRole are
-    // against a role/ACL it created on a previous reconcile. That rejection is the intended terminal
+    // all one-shot: each rejects with an "already exists" when re-run against a role/ACL/binding it
-    // state, so it is swallowed.
+    // created on a previous reconcile. That rejection is the intended terminal state — the ACL is
+    // deterministic (`<prefix>/#`, allow), so re-adding the identical entry is a no-op — so it is
+    // swallowed. (Until the exit code was fixed this was invisible: the tool returned 0 and the
+    // rejection was lost; now it surfaces, and each of these adds must tolerate its own idempotent
+    // re-run explicitly.)
     await ignoreExisting(this.ctl("createRole", role));
-    const wanted = wantedAcls(filters);
+    for (const acl of ["publishClientSend", "publishClientReceive", "subscribePattern"]) {
-    const current = parseRoleAcls(await this.ctl("getRole", role));
+      // allow (1) this client to send to, receive on, and subscribe under its own subtree.
-    for (const acl of missingAcls(current, wanted)) {
+      await ignoreExisting(this.ctl("addRoleACL", role, acl, pattern, "allow"));
-      await ignoreExisting(this.ctl("addRoleACL", role, acl.type, acl.topic, "allow"));
-    }
-    // What the consumer no longer asks for — added before it narrowed its topics — is taken away.
-    for (const acl of staleAcls(current, wanted)) {
-      await ignoreMissing(this.ctl("removeRoleACL", role, acl.type, acl.topic));
     }
     // Bind the role only when it is not already bound — addClientRole is the one call whose
     // idempotent re-run cannot be recognised by message (see clientHasRole).
@@ -189,31 +181,25 @@ export class MosquittoClient {
   }
 
   /**
-   * Whether a consumer's client accepts exactly this password, still carries its own role, and that
+   * Whether a consumer's client accepts exactly this password and still carries its own role.
-   * role grants exactly these filters. Read-only. The password is checked the way the consumer is
+   * Read-only. The password is checked the way the consumer is checked, by an MQTT CONNECT as it,
-   * checked, by an MQTT CONNECT as it, and the broker's CONNACK code is the answer: 0 accepted,
+   * and the broker's CONNACK code is the answer: 0 accepted, 4 bad credentials, 5 not authorised.
-   * 4 bad credentials, 5 not authorised. Nothing rides on argv. An unreachable broker rejects
+   * Nothing rides on argv. An unreachable broker rejects (novox/hq issue 120).
-   * (novox/hq issue 120).
    */
-  async holdsClient(username: string, password: string, filters: readonly string[]): Promise<boolean> {
+  async holdsClient(username: string, password: string): Promise<boolean> {
     const code = await mqttConnack(this.conn.host, this.conn.port, username, password);
     if (code === 4 || code === 5) return false;
     if (code !== 0) throw new Error(`mosquitto refused ${username} with CONNACK ${code}`);
     // The role, asked directly: only "not found" means absent. Any other failure to ask rejects,
     // unlike clientHasRole, which reads every failure as "no role".
-    let client: string;
+    let out: string;
-    let role: string;
     try {
-      client = await this.ctl("getClient", username);
+      out = await this.ctl("getClient", username);
-      role = await this.ctl("getRole", username);
     } catch (err) {
       if (/not\s*found|does not exist|no such/i.test(String(err))) return false;
       throw err;
     }
-    if (!new RegExp(`(^|\\s)${escapeRegExp(username)}\\s+\\(priority`, "m").test(client)) return false;
+    return new RegExp(`(^|\\s)${escapeRegExp(username)}\\s+\\(priority`, "m").test(out);
-    const current = parseRoleAcls(role);
-    const wanted = wantedAcls(filters);
-    return missingAcls(current, wanted).length === 0 && staleAcls(current, wanted).length === 0;
   }
 
   /** Remove a client and the per-client role created for it, idempotently. */

modules/mosquitto/module.json

@@ -20,19 +20,16 @@
     "mosquitto.topic.deprovisioned"
   ],
   "serves": {
-    "mqtt-topic": {
+    "mqtt-topic": {}
-      "scheme": "mqtt",
-      "port": 1883
-    }
   },
   "receives": {
-    "mqtt-topic": "${dir:grants}/mesh.json"
+    "mqtt-topic": "/var/lib/mosquitto-module/grants/mesh.json"
   },
   "grants": {
-    "mqtt-topic": "${dir:grants}"
+    "mqtt-topic": "/var/lib/mosquitto-module/grants"
   },
   "own-secrets": {
-    "admin": "/var/lib/mesh/mosquitto/admin",
+    "admin": "/var/lib/mosquitto-module/admin.secret",
     "broker": "/var/lib/mesh/mosquitto/broker"
   },
   "listens": [
@@ -61,24 +58,26 @@
     {
       "id": "state",
       "type": "directory",
-      "mode": "0700",
+      "path": "/var/lib/mosquitto-module",
-      "place": "."
+      "mode": "0700"
     },
     {
-      "id": "grants",
+      "id": "grants-dir",
       "type": "directory",
+      "path": "/var/lib/mosquitto-module/grants",
       "mode": "0700"
     },
     {
       "id": "data",
       "type": "directory",
+      "path": "/services/mosquitto/data",
       "mode": "0700",
       "owner": "1883:1883"
     },
     {
       "id": "server-conf",
       "type": "file",
-      "path": "${dir:state}/mosquitto.conf",
+      "path": "/var/lib/mosquitto-module/mosquitto.conf",
       "mode": "0600",
       "owner": "1883:1883",
       "content": "persistence true\npersistence_location /mosquitto/data\n\nlog_dest stdout\nlog_type warning\nlog_type error\nlog_type notice\n\n# Every client authenticates; identities and their per-topic ACLs are managed\n# at runtime by the dynamic security plugin, whose store the plugin itself owns.\nallow_anonymous false\nplugin /usr/lib/mosquitto_dynamic_security.so\nplugin_opt_config_file /mosquitto/data/dynamic-security.json\n\n# MQTT listener\nlistener 1883\n\n# MQTT-over-WebSockets listener\nlistener 8081\nprotocol websockets\n"
@@ -94,8 +93,8 @@
       "name": "mosquitto-bootstrap",
       "run-once": true,
       "volumes": [
-        "${dir:data}:/mosquitto/data",
+        "/services/mosquitto/data:/mosquitto/data",
-        "/var/lib/mesh/mosquitto/admin:/run/secrets/admin:ro"
+        "/var/lib/mosquitto-module/admin.secret:/run/secrets/admin:ro"
       ],
       "env": {
         "MESH_PROVISION_MQTT": "mosquitto:1883",
@@ -113,15 +112,15 @@
       "id": "server",
       "type": "container",
       "name": "mosquitto",
-      "image": "eclipse-mosquitto@sha256:38c0da4f2ef84284d47b3b3eeea1cb3bdeabe81ee10caf0cd5c5ff61ee3ea408",
+      "image": "eclipse-mosquitto@sha256:6f8d8a947c506f8a2290ec65cd4bd2bc7cb4d43fb5f6271f861cb013e2ef9797",
       "network": "mosquitto",
       "ports": [
         "1883",
         "8081"
       ],
       "volumes": [
-        "${dir:data}:/mosquitto/data",
+        "/services/mosquitto/data:/mosquitto/data",
-        "${dir:state}/mosquitto.conf:/mosquitto/config/mosquitto.conf:ro"
+        "/var/lib/mosquitto-module/mosquitto.conf:/mosquitto/config/mosquitto.conf:ro"
       ]
     },
     {
@@ -131,8 +130,8 @@
       "network": "mosquitto",
       "volumes": [
         "/var/lib/mesh/mosquitto/broker:/run/secrets/broker:ro",
-        "${dir:grants}:/var/lib/mosquitto-module/grants:ro",
+        "/var/lib/mosquitto-module/grants:/var/lib/mosquitto-module/grants:ro",
-        "/var/lib/mesh/mosquitto/admin:/run/secrets/admin:ro"
+        "/var/lib/mosquitto-module/admin.secret:/run/secrets/admin:ro"
       ],
       "env": {
         "MESH_BROKER_FILE": "/run/secrets/broker",

modules/mosquitto/package.json

@@ -1,14 +1,9 @@
 {
   "name": "@novox/module-mosquitto",
   "version": "0.1.0",
-  "description": "mosquitto \u2014 provides the mesh mqtt-topic interface. Its admin client, provisioner, tools and events live here (novox/hq ADR 0039).",
+  "description": "mosquitto — provides the mesh mqtt-topic interface. Its admin client, provisioner, tools and events live here (novox/hq ADR 0039).",
   "type": "module",
   "private": true,
-  "scripts": {
-    "build": "tsc topics.ts client.ts index.ts tools/index.ts provisioner/index.ts bootstrap/index.ts --module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist",
-    "typecheck": "tsc -p tsconfig.json",
-    "test": "node --test --experimental-strip-types 'test/*.test.ts'"
-  },
   "dependencies": {
     "@novox/mesh-sdk": "^0.1.1"
   },

modules/mosquitto/provisioner/index.ts

@@ -5,14 +5,7 @@
 //
 // The `mqtt-topic` interface: a consumer connects as `as` with the password the mesh minted, and
 // publishes and subscribes under `<as>/#`, isolated from every other consumer by a Dynamic Security
-// role scoped to exactly that subtree — unless it contributed `topics`, the MQTT topic filters its
+// role scoped to exactly that subtree.
-// work needs (a home-automation hub needs the devices' topics); then the role grants exactly those
-// (topics.ts). A list that is not valid topic filters is refused, and the consumer is not created
-// or changed until it is fixed.
-//
-// What a consumer is told (its binding): `at` — the broker's machine — and `port`, the machine port
-// of the MQTT listener (the manifest's `serves`); `as` is its login, and its copy of the password is
-// the pair credential the mesh delivers to it.
 //
 // **The login and password are the mesh's, not the provisioner's (ADR 0048).** The mesh derives the
 // login and hands it to both ends so they agree, and mints the password and delivers a copy to each.
@@ -22,7 +15,6 @@
 import { runProvisioner, type Provision } from "@novox/mesh-sdk/provisioner";
 import { emit } from "@novox/mesh-sdk/events";
 import { MosquittoClient } from "../client.js";
-import { topicFilters } from "../topics.js";
 
 const mosquitto = MosquittoClient.fromEnv();
 
@@ -37,20 +29,13 @@ async function announce(type: string, body: Record<string, string>): Promise<voi
 
 runProvisioner("mqtt-topic", {
   async create(p: Provision): Promise<void> {
-    // By default the consumer's own subtree, so one cannot read another's topics; what it
+    // The topic subtree is scoped to the consumer's own login, so one cannot read another's topics.
-    // contributed as `topics` otherwise.
+    const topicPrefix = p.as;
-    const granted = topicFilters(p.values, p.as);
+    await mosquitto.createScopedClient(p.as, p.password, topicPrefix);
-    if ("problem" in granted) {
-      // Thrown, so the harness logs it and retries: the consumer stays as it was (or absent) until
-      // its contribution is valid, rather than being given a grant it did not ask for.
-      throw new Error(`${p.as}: ${granted.problem}`);
-    }
-    await mosquitto.createScopedClient(p.as, p.password, granted.filters);
     await announce("topic.provisioned", {
       consumer: p.consumer ?? "",
       username: p.as,
-      topicPrefix: granted.own ? p.as : "",
+      topicPrefix,
-      topics: granted.filters.join(" "),
     });
   },
 
@@ -61,9 +46,6 @@ runProvisioner("mqtt-topic", {
   // Asked every minute by the harness: whether the backend still holds this consumer exactly as
   // the mesh gave it, so a login lost behind the provisioner's back is made again (novox/hq issue 120).
   async holds(p: Provision): Promise<boolean> {
-    const granted = topicFilters(p.values, p.as);
+    return mosquitto.holdsClient(p.as, p.password);
-    // An invalid list was never applied; create refuses it again, loudly, on every pass.
-    if ("problem" in granted) return false;
-    return mosquitto.holdsClient(p.as, p.password, granted.filters);
   },
 });

modules/mosquitto/test/topics.test.ts

@@ -1,72 +0,0 @@
-// What a consumer of mqtt-topic is granted (topics.ts): its own subtree unless it contributed
-// `topics`; a contributed list is granted exactly, refused whole when it is not topic filters; and
-// the role is brought to exactly the wanted ACLs — missing ones added, stale ones removed — read from
-// `mosquitto_ctrl dynsec getRole` as eclipse-mosquitto 2.1.2 prints it.
-
-import { test } from "node:test";
-import assert from "node:assert/strict";
-
-import { filterProblem, missingAcls, parseRoleAcls, staleAcls, topicFilters, wantedAcls } from "../topics.ts";
-
-test("a consumer that contributed nothing gets its own subtree", () => {
-  assert.deepEqual(topicFilters({}, "mesh_ace_hass"), { ok: true, filters: ["mesh_ace_hass/#"], own: true });
-  assert.deepEqual(topicFilters(undefined, "x"), { ok: true, filters: ["x/#"], own: true });
-  // Settings merge into every contribution: keys that are not `topics` change nothing.
-  assert.deepEqual(topicFilters({ endpoints: { web: {} } }, "x"), { ok: true, filters: ["x/#"], own: true });
-});
-
-test("a contributed list is granted exactly, duplicates once", () => {
-  assert.deepEqual(topicFilters({ topics: ["#"] }, "x"), { ok: true, filters: ["#"], own: false });
-  assert.deepEqual(topicFilters({ topics: ["stat/+/POWER", "tele/#", "tele/#", "/octoprint/x"] }, "x"), {
-    ok: true,
-    filters: ["stat/+/POWER", "tele/#", "/octoprint/x"],
-    own: false,
-  });
-});
-
-test("a list that is not topic filters is refused whole", () => {
-  for (const topics of [[], "#", [""], ["a/#/b"], ["a#"], ["a/b+"], [42], ["a\u0000b"], {}]) {
-    const out = topicFilters({ topics } as Record<string, unknown>, "x");
-    assert.equal(out.ok, false, JSON.stringify(topics));
-  }
-  assert.equal(filterProblem("+/+/#"), undefined);
-  assert.equal(filterProblem("#"), undefined);
-});
-
-const GET_ROLE = `Warning: You are running mosquitto_ctrl without encryption.
-This means all of the configuration changes you are making are visible on the network, including passwords.
-
-Rolename: u1
-ACLs:     publishClientSend    : allow : # (priority: 0)
-          subscribePattern     : allow : u1/# (priority: 0)
-          publishClientReceive : deny : secret topic/with space (priority: -1)
-`;
-
-test("getRole's ACL lines are read, the warning and headings are not", () => {
-  assert.deepEqual(parseRoleAcls(GET_ROLE), [
-    { type: "publishClientSend", allow: true, topic: "#" },
-    { type: "subscribePattern", allow: true, topic: "u1/#" },
-    { type: "publishClientReceive", allow: false, topic: "secret topic/with space" },
-  ]);
-  assert.deepEqual(parseRoleAcls("Rolename: empty\nACLs:\n"), []);
-});
-
-test("the role is brought to exactly the wanted ACLs", () => {
-  const current = parseRoleAcls(GET_ROLE);
-  const wanted = wantedAcls(["u1/#"]);
-  assert.deepEqual(wanted, [
-    { type: "publishClientSend", allow: true, topic: "u1/#" },
-    { type: "publishClientReceive", allow: true, topic: "u1/#" },
-    { type: "subscribePattern", allow: true, topic: "u1/#" },
-  ]);
-  assert.deepEqual(missingAcls(current, wanted), [
-    { type: "publishClientSend", allow: true, topic: "u1/#" },
-    { type: "publishClientReceive", allow: true, topic: "u1/#" },
-  ]);
-  assert.deepEqual(staleAcls(current, wanted), [
-    { type: "publishClientSend", allow: true, topic: "#" },
-    { type: "publishClientReceive", allow: false, topic: "secret topic/with space" },
-  ]);
-  assert.deepEqual(staleAcls(wanted, wanted), []);
-  assert.deepEqual(missingAcls(wanted, wanted), []);
-});

modules/mosquitto/topics.ts

@@ -1,107 +0,0 @@
-// Which topics a consumer of `mqtt-topic` may use — the one choice a consumer makes about its grant.
-//
-// **By default, its own subtree and nothing else.** A consumer connects as the login the mesh derived
-// (`as`) and may publish, receive and subscribe under `<as>/#` — isolated from every other consumer,
-// which is the point of a per-consumer client (novox/hq ADR 0039/0048).
-//
-// **A consumer whose work IS the shared topic space says so.** Home Assistant discovers devices
-// under `homeassistant/#` and `tasmota/discovery/#` and follows whatever state topics they announce;
-// Node-RED's flows subscribe to the topics devices publish on (`stat/<device>/POWER`, …). Confined
-// to `<as>/#` neither could do its job. So a consumer contributes `topics` to its `mqtt-topic`
-// requirement — a list of MQTT topic filters — and the provisioner grants exactly those, both ways.
-// Because assignment settings merge into every contribution, an operator narrows (or widens) the
-// list per machine with the same key, without editing a manifest.
-//
-// Pure, so it is tested without a broker (test/topics.test.ts).
-
-/** The dynsec ACL types a granted filter carries: send to it, receive from it, subscribe to it. */
-export const GRANTED_ACL_TYPES = ["publishClientSend", "publishClientReceive", "subscribePattern"] as const;
-
-/** One ACL on a role, as `mosquitto_ctrl dynsec getRole` reports it. */
-export interface Acl {
-  type: string;
-  allow: boolean;
-  topic: string;
-}
-
-export type Filters = { ok: true; filters: string[]; own: boolean } | { ok: false; problem: string };
-
-/**
- * The topic filters a consumer is granted: what it contributed as `topics`, or its own subtree when
- * it contributed nothing. Refused — never silently narrowed or widened — when the list is not a
- * list of valid MQTT topic filters: a grant that quietly differs from what was asked is a consumer
- * that fails somewhere far from the cause.
- */
-export function topicFilters(values: Readonly<Record<string, unknown>> | undefined, as: string): Filters {
-  const given = values?.topics;
-  if (given === undefined || given === null) {
-    return { ok: true, filters: [`${as}/#`], own: true };
-  }
-  if (!Array.isArray(given) || given.length === 0) {
-    return { ok: false, problem: `topics must be a non-empty list of MQTT topic filters, not ${JSON.stringify(given)}` };
-  }
-  const out: string[] = [];
-  for (const f of given) {
-    if (typeof f !== "string") {
-      return { ok: false, problem: `topics holds ${JSON.stringify(f)}, which is not a topic filter` };
-    }
-    const problem = filterProblem(f);
-    if (problem) return { ok: false, problem: `topic filter ${JSON.stringify(f)}: ${problem}` };
-    if (!out.includes(f)) out.push(f);
-  }
-  return { ok: true, filters: out, own: out.length === 1 && out[0] === `${as}/#` };
-}
-
-/** Why a string is not a valid MQTT topic filter (MQTT 3.1.1 §4.7), or undefined when it is one. */
-export function filterProblem(filter: string): string | undefined {
-  if (filter.length === 0) return "it is empty";
-  if (Buffer.byteLength(filter, "utf8") > 65535) return "it is longer than MQTT allows";
-  if (filter.includes("\u0000")) return "it contains a NUL character";
-  const levels = filter.split("/");
-  for (let i = 0; i < levels.length; i++) {
-    const level = levels[i];
-    if (level.includes("#") && (level !== "#" || i !== levels.length - 1)) {
-      return "'#' must be a whole level, and the last one";
-    }
-    if (level.includes("+") && level !== "+") return "'+' must be a whole level";
-  }
-  return undefined;
-}
-
-/** The ACLs a role must carry to grant these filters: every granted type, allowed, on every filter. */
-export function wantedAcls(filters: readonly string[]): Acl[] {
-  const out: Acl[] = [];
-  for (const topic of filters) {
-    for (const type of GRANTED_ACL_TYPES) out.push({ type, allow: true, topic });
-  }
-  return out;
-}
-
-/**
- * The ACLs `mosquitto_ctrl dynsec getRole` lists, one per line under its "ACLs:" heading:
- *   `ACLs:     publishClientSend    : allow : # (priority: 0)`
- *   `          subscribePattern     : allow : u1/# (priority: 0)`
- */
-export function parseRoleAcls(output: string): Acl[] {
-  const out: Acl[] = [];
-  const line = /^(?:ACLs:)?\s*([A-Za-z]+)\s*:\s*(allow|deny)\s*:\s*(.*?)\s+\(priority:\s*-?\d+\)\s*$/;
-  for (const raw of output.split(/\r?\n/)) {
-    const m = raw.match(line);
-    if (m) out.push({ type: m[1], allow: m[2] === "allow", topic: m[3] });
-  }
-  return out;
-}
-
-const key = (a: Acl): string => `${a.type}\u0000${a.allow ? "allow" : "deny"}\u0000${a.topic}`;
-
-/** ACLs a role carries that it should not: in `current` and not in `wanted`. */
-export function staleAcls(current: readonly Acl[], wanted: readonly Acl[]): Acl[] {
-  const want = new Set(wanted.map(key));
-  return current.filter((a) => !want.has(key(a)));
-}
-
-/** ACLs a role should carry and does not. */
-export function missingAcls(current: readonly Acl[], wanted: readonly Acl[]): Acl[] {
-  const have = new Set(current.map(key));
-  return wanted.filter((a) => !have.has(key(a)));
-}

modules/mosquitto/tsconfig.json

@@ -8,5 +8,5 @@
     "skipLibCheck": true,
     "noEmit": true
   },
-  "include": ["topics.ts", "client.ts", "index.ts", "provisioner/index.ts", "tools/index.ts", "bootstrap/index.ts"]
+  "include": ["client.ts", "index.ts", "provisioner/index.ts", "tools/index.ts", "bootstrap/index.ts"]
 }

modules/nodered/Dockerfile

@@ -13,7 +13,7 @@ ARG RUNTIME_BASE
 FROM ${BUILD_BASE} AS build
 WORKDIR /app/modules/nodered
 COPY . .
-RUN node /app/node_modules/typescript/bin/tsc client.ts tools/index.ts \
+RUN node /app/node_modules/typescript/bin/tsc client.ts tools/index.ts mqtt/probe.ts mqtt/connection.ts mqtt/index.ts \
       --module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist
 
 FROM ${RUNTIME_BASE}
@@ -22,3 +22,6 @@ COPY --from=build /app/modules/nodered/dist /app/modules/nodered/dist
 # provider's provisioner runs its reconcile loop in the same process, with the broker connected —
 # the convention novox/hq issues 060/061 settled.
 ENV MESH_TOOL_MODULES=/app/modules/nodered/dist/tools/index.js
+# NOT dist/mqtt/index.js: that is a step the host runs to completion, named by the `mqtt`
+# container's args as `mesh-tools run …` (novox/hq ADR 0052). Listed here it would run inside the
+# serving sidecar too, and exit it.

modules/nodered/client.ts

@@ -3,7 +3,8 @@
 //
 // Node-RED exposes a runtime admin API under its base URL: GET/POST /flows for the whole flow
 // configuration, GET /nodes for installed node modules. A default install has no auth; when
-// adminAuth is on, a bearer token (minted at /auth/token) is required.
+// adminAuth is on, a bearer token is required — the module's settings accept the mesh-minted
+// api-token, which the runtime config file carries as `token`.
 
 import { readFileSync } from "node:fs";
 
@@ -81,6 +82,35 @@ export class NodeRedClient {
     return modules.map((m) => ({ name: m.name, version: m.version, types: m.types ?? [] }));
   }
 
+  /** The whole flow configuration with its revision (API v2), for a deploy that must not clobber
+   *  a change made meanwhile. */
+  async flowsWithRev(): Promise<{ rev: string; flows: any[] }> {
+    const body = await this.req("/flows", { headers: this.headers({ "Node-RED-API-Version": "v2" }) });
+    return { rev: String(body?.rev ?? ""), flows: Array.isArray(body?.flows) ? body.flows : [] };
+  }
+
+  /** A node's stored credentials as Node-RED shows them: plain fields, and `has_<field>` for secret ones. */
+  async credentials(type: string, id: string): Promise<{ user?: string; has_password?: boolean }> {
+    return (await this.req(`/credentials/${encodeURIComponent(type)}/${encodeURIComponent(id)}`, { headers: this.headers() })) ?? {};
+  }
+
+  /**
+   * Deploy the flow configuration read at `rev`. Node-RED answers 409 when the flows changed since,
+   * rather than overwriting what someone deployed in between. A node carrying `credentials` has them
+   * stored (encrypted) and counts as changed, so a "nodes" deploy restarts it and nothing else.
+   */
+  async deployFlowsAt(rev: string, config: any[], type = "nodes"): Promise<void> {
+    await this.req("/flows", {
+      method: "POST",
+      headers: this.headers({
+        "Content-Type": "application/json",
+        "Node-RED-API-Version": "v2",
+        "Node-RED-Deployment-Type": type,
+      }),
+      body: JSON.stringify({ rev, flows: config }),
+    });
+  }
+
   /**
    * Replace the whole flow configuration and deploy. Returns the new revision. `type` maps to
    * Node-RED's deployment types — "full" (default), "nodes", or "flows".
@@ -88,8 +118,13 @@ export class NodeRedClient {
   async deployFlows(config: any[], type = "full"): Promise<{ rev?: string; nodeCount: number }> {
     const body = await this.req("/flows", {
       method: "POST",
-      headers: this.headers({ "Content-Type": "application/json", "Node-RED-Deployment-Type": type }),
+      // v2 answers { rev }; v1 answers 204 with no body, which req() cannot parse.
-      body: JSON.stringify(config),
+      headers: this.headers({
+        "Content-Type": "application/json",
+        "Node-RED-API-Version": "v2",
+        "Node-RED-Deployment-Type": type,
+      }),
+      body: JSON.stringify({ flows: config }),
     });
     return { rev: body?.rev, nodeCount: config.length };
   }

modules/nodered/module.json

@@ -5,6 +5,8 @@
     "flows.deployed"
   ],
   "own-secrets": {
+    "admin": "/var/lib/mesh/nodered/admin",
+    "api-token": "/var/lib/mesh/nodered/api-token",
     "broker": "/var/lib/mesh/nodered/broker"
   },
   "capabilities": [
@@ -26,26 +28,63 @@
       "path": "/var/lib/mesh/nodered",
       "mode": "0700"
     },
+    {
+      "id": "state",
+      "type": "directory",
+      "mode": "0700",
+      "place": "."
+    },
     {
       "id": "data",
       "type": "directory",
-      "path": "/services/nodered/data",
       "mode": "0700",
       "owner": "1000:1000"
     },
+    {
+      "id": "written",
+      "type": "directory",
+      "mode": "0700"
+    },
+    {
+      "id": "settings-code",
+      "type": "file",
+      "path": "${dir:state}/settings.js",
+      "mode": "0600",
+      "owner": "1000:1000",
+      "content": "// Node-RED's settings, written by the mesh from the nodered module. What an assignment may change\n// is settings.json beside this file (merged key by key); the credentials are the mesh's secrets and\n// reach Node-RED only through this file. The flows' own credentials stay encrypted in the user\n// directory under the key Node-RED keeps there (.config.runtime.json), which is data, not this.\nconst fs = require(\"fs\");\nconst path = require(\"path\");\nconst crypto = require(\"crypto\");\n\nconst ADMIN_PASSWORD = \"${secret:admin}\";\nconst API_TOKEN = \"${secret:api-token}\";\nconst ADMIN = { username: \"admin\", permissions: \"*\" };\n\nconst settings = JSON.parse(fs.readFileSync(path.join(__dirname, \"settings.json\"), \"utf8\"));\n// The mesh's keys, not Node-RED's: endpoints lands in every merged file; timeZone is the\n// assignment's way to set the zone flows schedule and format in; mqtt names the broker nodes the\n// module's MQTT step keeps pointed at the mesh's broker; topics is what nodered asks the broker for.\nif (settings.timeZone) process.env.TZ = settings.timeZone;\ndelete settings.timeZone;\ndelete settings.endpoints;\ndelete settings.mqtt;\ndelete settings.topics;\n\nfunction same(a, b) {\n  const x = crypto.createHash(\"sha256\").update(String(a)).digest();\n  const y = crypto.createHash(\"sha256\").update(String(b)).digest();\n  return crypto.timingSafeEqual(x, y);\n}\n\n// The admin secret is a password, or, accepted from an existing install, the bcrypt hash its\n// settings held, so the password people already use keeps working.\nfunction passwordMatches(given) {\n  if (/^\\$2[aby]\\$\\d\\d\\$/.test(ADMIN_PASSWORD)) return require(\"bcryptjs\").compare(String(given), ADMIN_PASSWORD);\n  return Promise.resolve(same(given, ADMIN_PASSWORD));\n}\n\nmodule.exports = Object.assign(settings, {\n  uiPort: 1880,\n  adminAuth: {\n    type: \"credentials\",\n    users: (username) => Promise.resolve(username === ADMIN.username ? ADMIN : null),\n    authenticate: (username, password) =>\n      username === ADMIN.username\n        ? passwordMatches(password).then((ok) => (ok ? ADMIN : null))\n        : Promise.resolve(null),\n    // The module's own tools call the admin API with this bearer token.\n    tokens: (token) => Promise.resolve(same(token, API_TOKEN) ? { username: \"mesh\", permissions: \"*\" } : null),\n  },\n});\n"
+    },
+    {
+      "id": "settings",
+      "type": "file",
+      "path": "${dir:state}/settings.json",
+      "mode": "0600",
+      "owner": "1000:1000",
+      "merge": "json",
+      "content": "{\n  \"flowFile\": \"flows.json\",\n  \"flowFilePretty\": true,\n  \"diagnostics\": { \"enabled\": true, \"ui\": true },\n  \"runtimeState\": { \"enabled\": false, \"ui\": false },\n  \"logging\": { \"console\": { \"level\": \"info\", \"metrics\": false, \"audit\": false } },\n  \"exportGlobalContextKeys\": false,\n  \"externalModules\": {},\n  \"editorTheme\": { \"projects\": { \"enabled\": false } },\n  \"functionExternalModules\": true,\n  \"debugMaxLength\": 1000,\n  \"mqttReconnectTime\": 15000,\n  \"serialReconnectTime\": 15000\n}\n"
+    },
     {
       "id": "server",
       "type": "container",
       "name": "nodered",
-      "image": "nodered/node-red@sha256:02a2b92a41b73d2bc388238b86e4fcaab7fb5466373adb24e1df6aa5845265ff",
+      "image": "nodered/node-red@sha256:a649dd711d55490151a2c39a8e48ad0c44325488fbc0e66315f2d2e19e5e1ace",
       "env": {
         "TZ": "Etc/UTC"
       },
       "ports": [
         "1880"
       ],
+      "args": [
+        "--settings",
+        "/config/settings.js"
+      ],
       "volumes": [
-        "/services/nodered/data:/data"
+        "${dir:data}:/data",
+        "${dir:state}/settings.js:/config/settings.js:ro",
+        "${dir:state}/settings.json:/config/settings.json:ro"
+      ],
+      "restart-on": [
+        "settings-code",
+        "settings"
       ]
     },
     {
@@ -53,8 +92,7 @@
       "type": "file",
       "path": "/var/lib/mesh/nodered/config.json",
       "mode": "0600",
-      "content": "{}\n",
+      "content": "{\n  \"token\": \"${secret:api-token}\"\n}\n"
-      "merge": "json"
     },
     {
       "id": "runtime",
@@ -67,26 +105,66 @@
       ],
       "env": {
         "MESH_BROKER_FILE": "/run/secrets/broker",
-        "MESH_NODERED_URL": "http://127.0.0.1:1880",
+        "MESH_NODERED_URL": "http://127.0.0.1:${port:1880}",
         "MESH_NODERED_CONFIG_FILE": "/run/config/config.json"
       },
       "restart-on": [
         "runtime-config"
       ],
       "artifact": "runtime"
+    },
+    {
+      "id": "mqtt",
+      "type": "container",
+      "name": "mesh-nodered-mqtt",
+      "network": "host",
+      "run-once": true,
+      "volumes": [
+        "/var/lib/mesh/nodered/config.json:/run/config/config.json:ro",
+        "${dir:written}:/var/lib/nodered-provisions",
+        "${dir:state}/mqtt-topic.json:/run/provisions/mqtt-topic.json:ro",
+        "${dir:state}/mqtt-topic.secret:/run/provisions/mqtt-topic.secret:ro",
+        "${dir:state}/settings.json:/run/provisions/settings.json:ro"
+      ],
+      "env": {
+        "MESH_NODERED_URL": "http://127.0.0.1:${port:1880}",
+        "MESH_NODERED_CONFIG_FILE": "/run/config/config.json",
+        "MESH_PROVISIONS_DIR": "/run/provisions",
+        "MESH_WRITTEN_DIR": "/var/lib/nodered-provisions"
+      },
+      "args": [
+        "run",
+        "/app/modules/nodered/dist/mqtt/index.js"
+      ],
+      "restart-on": [
+        "bound-mqtt-topic",
+        "secret-mqtt-topic",
+        "settings"
+      ],
+      "artifact": "runtime"
     }
   ],
   "requires": [
+    "mqtt-topic",
     "route"
   ],
   "contributes": {
+    "mqtt-topic": {
+      "topics": [
+        "#"
+      ]
+    },
     "route": {
       "label": "nodered",
       "endpoint": "web"
     }
   },
   "binds": {
-    "route": "/var/lib/mesh/nodered/route.json"
+    "route": "${dir:state}/route.json",
+    "mqtt-topic": "${dir:state}/mqtt-topic.json"
+  },
+  "secrets": {
+    "mqtt-topic": "${dir:state}/mqtt-topic.secret"
   },
   "build": {
     "on": [

modules/nodered/mqtt/connection.ts

@@ -0,0 +1,232 @@
+// Node-RED's MQTT broker config node, pointed at the broker the mesh bound — `mqtt-topic`.
+//
+// **Why a step.** Node-RED keeps a broker as a config node in its flows (`flows.json`) and the login
+// and password in its encrypted credentials file, both of them Node-RED's to write. So this reads the
+// binding and the pair credential and makes the broker node say the same thing through Node-RED's
+// admin API — `GET /flows`, then `POST /flows` with the changed node and its `credentials`, deployed
+// as "nodes" so only what changed restarts — with the module's own `api-token`.
+//
+// **Which broker nodes are the mesh's.** Never guessed: a flow may talk to a broker that has nothing
+// to do with this mesh. The step owns the node it creates itself (id `mesh-mqtt-topic`, "mesh:
+// mqtt-topic") and the ones an assignment names in settings (`mqtt.brokers`: node ids — how ace's
+// existing broker node, which every one of its MQTT flows uses, is handed over). With none named and
+// none made yet, it makes one, so a fresh Node-RED has a broker the flows can pick.
+//
+// **Only the connection, and only when it differs.** Host, port, TLS off (the broker serves plain
+// MQTT), login, password. Every other field of the node — client id, keepalive, birth/close/will
+// messages — is left as it is. Node-RED never hands a stored password back, so the step keeps a
+// digest of what it last wrote: equal host/port/login and an equal digest is "already as the mesh
+// says".
+//
+// **Nothing loses its connection without someone seeing it.** The broker is asked first whether it
+// takes the delivered login; if not, nothing is written and the step fails saying why.
+//
+// Pure logic over two seams (Node-RED, the broker), tested against fakes (test/mqtt.test.ts).
+
+import { createHash } from "node:crypto";
+
+import type { Probe } from "./probe.js";
+
+export const PROVISION = "mqtt-topic";
+/** The id and name of the broker node the step makes when none is named. */
+export const MESH_BROKER_ID = "mesh-mqtt-topic";
+export const MESH_BROKER_NAME = "mesh: mqtt-topic";
+
+/** What the mesh wrote at `binds.mqtt-topic`. */
+export interface Binding {
+  provision?: string;
+  from?: string;
+  at?: string;
+  as?: string;
+  serves?: Record<string, unknown>;
+}
+
+export type Outcome =
+  | { what: string; result: "unchanged"; note?: string }
+  | { what: string; result: "written"; fields: string[]; note?: string }
+  | { what: string; result: "refused"; problem: string };
+
+/** A flow node; a broker config node carries `broker`, `port`, `usetls`. */
+export interface FlowNode {
+  id: string;
+  type: string;
+  [key: string]: unknown;
+}
+
+/** Node-RED's admin API, as the step uses it. */
+export interface NodeRed {
+  /** The whole flow configuration and its revision (API v2). */
+  flows(): Promise<{ rev: string; flows: FlowNode[] }>;
+  /** A node's stored credentials as Node-RED shows them: the user, and only whether a password is set. */
+  credentials(type: string, id: string): Promise<{ user?: string; has_password?: boolean }>;
+  /** Deploy the configuration against the revision it was read at; "nodes" restarts only what changed. */
+  deploy(rev: string, flows: FlowNode[]): Promise<void>;
+}
+
+export interface Marks {
+  get(name: string): Promise<string | undefined>;
+  set(name: string, digest: string): Promise<void>;
+}
+
+export interface Deps {
+  nodered: NodeRed;
+  probe: Probe;
+  marks: Marks;
+}
+
+export interface Wanted {
+  host: string;
+  port: number;
+  user: string;
+  password: string;
+}
+
+export function digest(...parts: (string | number)[]): string {
+  return createHash("sha256").update(parts.map(String).join("\u0000")).digest("hex");
+}
+
+function isLoopback(host: string): boolean {
+  const h = host.toLowerCase();
+  return h === "localhost" || h === "::1" || h === "[::1]" || /^127\./.test(h);
+}
+
+/**
+ * The broker and login the mesh says Node-RED uses. A loopback `at` — what the mesh hands a machine
+ * that is not on the private network — is refused: from Node-RED's own container it is Node-RED.
+ */
+export function wanted(binding: Binding | undefined, credential: string | undefined): { ok: true; want: Wanted } | { ok: false; problem: string } {
+  if (!binding) return { ok: false, problem: `no binding for ${PROVISION} was delivered — the mesh writes it before this step runs` };
+  const host = typeof binding.at === "string" ? binding.at.trim() : "";
+  if (!host) return { ok: false, problem: `the ${PROVISION} binding names no host (at)` };
+  if (isLoopback(host)) {
+    return {
+      ok: false,
+      problem:
+        `the ${PROVISION} binding says the broker is at ${host}, which from Node-RED's own container is Node-RED ` +
+        `itself; put the machine on the private network so the broker has an address Node-RED can dial`,
+    };
+  }
+  const port = Number(binding.serves?.port);
+  if (!Number.isInteger(port) || port <= 0 || port > 65535) {
+    return { ok: false, problem: `the ${PROVISION} binding serves no usable port (${String(binding.serves?.port)})` };
+  }
+  const scheme = binding.serves?.scheme;
+  if (scheme !== undefined && scheme !== "mqtt") return { ok: false, problem: `the ${PROVISION} binding serves scheme ${String(scheme)}; this step writes plain MQTT` };
+  const user = typeof binding.as === "string" ? binding.as.trim() : "";
+  if (!user) return { ok: false, problem: `the ${PROVISION} binding names no login (as)` };
+  const password = (credential ?? "").replace(/\n$/, "");
+  if (!password) return { ok: false, problem: `the ${PROVISION} credential is empty or was not delivered` };
+  return { ok: true, want: { host, port, user, password } };
+}
+
+/** The broker node ids an assignment named in settings (`mqtt.brokers`), or none. */
+export function namedBrokers(settings: unknown): string[] {
+  const brokers = (settings as { mqtt?: { brokers?: unknown } } | undefined)?.mqtt?.brokers;
+  return Array.isArray(brokers) ? brokers.filter((b): b is string => typeof b === "string" && b.length > 0) : [];
+}
+
+/** A new broker node, Node-RED 5's defaults, pointed at the broker. */
+export function newBrokerNode(want: Wanted): FlowNode {
+  return {
+    id: MESH_BROKER_ID, type: "mqtt-broker", name: MESH_BROKER_NAME,
+    broker: want.host, port: String(want.port), clientid: "", autoConnect: true, usetls: false,
+    protocolVersion: "4", keepalive: "60", cleansession: true, autoUnsubscribe: true,
+    birthTopic: "", birthQos: "0", birthRetain: "false", birthPayload: "", birthMsg: {},
+    closeTopic: "", closeQos: "0", closeRetain: "false", closePayload: "", closeMsg: {},
+    willTopic: "", willQos: "0", willRetain: "false", willPayload: "", willMsg: {},
+    userProps: "", sessionExpiry: "",
+  };
+}
+
+const markFor = (id: string, w: Wanted): string => digest("nodered-mqtt", id, w.host, w.port, w.user, w.password);
+
+function scrub(err: unknown, secret: string): string {
+  let text = err instanceof Error ? err.message : String(err);
+  for (const form of new Set([secret, encodeURIComponent(secret)])) text = text.split(form).join("***");
+  return text;
+}
+
+/**
+ * Bring the mesh's broker nodes in line with the binding: one outcome per node. Never throws. A node
+ * the settings name that is not in the flows is refused (the others are still put right).
+ */
+export async function reconcileBrokers(deps: Deps, binding: Binding | undefined, credential: string | undefined, named: readonly string[]): Promise<Outcome[]> {
+  const w = wanted(binding, credential);
+  if ("problem" in w) return [{ what: "mqtt", result: "refused", problem: w.problem }];
+  const want = w.want;
+
+  let note: string | undefined;
+  try {
+    const probe = await deps.probe(want.host, want.port, want.user, want.password, "#");
+    if (probe.connack === 4 || probe.connack === 5) {
+      return [{
+        what: "mqtt",
+        result: "refused",
+        problem:
+          `the broker at ${want.host}:${want.port} does not (yet) take the login ${want.user} with the delivered password ` +
+          `(CONNACK ${probe.connack}); mosquitto's provisioner creates it from the grant — nothing was written`,
+      }];
+    }
+    if (probe.connack !== 0) return [{ what: "mqtt", result: "refused", problem: `the broker at ${want.host}:${want.port} answered CONNACK ${probe.connack}; nothing was written` }];
+    if (probe.suback === 0x80) note = `warning: ${want.user} may not subscribe to every topic; flows subscribing outside its grant will get nothing`;
+  } catch (err) {
+    return [{ what: "mqtt", result: "refused", problem: `the broker at ${want.host}:${want.port} could not be asked: ${scrub(err, want.password)}; nothing was written` }];
+  }
+
+  const outcomes: Outcome[] = [];
+  for (let attempt = 0; attempt < 2; attempt++) {
+    outcomes.length = 0;
+    try {
+      const { rev, flows } = await deps.nodered.flows();
+      const targets = named.length > 0 ? [...named] : [MESH_BROKER_ID];
+      const changed: { id: string; fields: string[] }[] = [];
+      for (const id of targets) {
+        let node = flows.find((n) => n.id === id);
+        if (node && node.type !== "mqtt-broker") {
+          outcomes.push({ what: `broker ${id}`, result: "refused", problem: `node ${id} is a ${node.type}, not an mqtt-broker` });
+          continue;
+        }
+        if (!node) {
+          if (id !== MESH_BROKER_ID) {
+            outcomes.push({ what: `broker ${id}`, result: "refused", problem: `the settings name broker node ${id}, and Node-RED's flows have no such node` });
+            continue;
+          }
+          node = newBrokerNode(want);
+          flows.push(node);
+          node.credentials = { user: want.user, password: want.password };
+          changed.push({ id, fields: ["node"] });
+          continue;
+        }
+        const fields: string[] = [];
+        if (String(node.broker ?? "") !== want.host) fields.push("broker");
+        if (Number(node.port ?? 0) !== want.port) fields.push("port");
+        if (node.usetls === true) fields.push("usetls");
+        const creds = await deps.nodered.credentials("mqtt-broker", id);
+        if ((creds.user ?? "") !== want.user) fields.push("user");
+        if (!creds.has_password || (await deps.marks.get(`broker-${id}`)) !== markFor(id, want)) fields.push("password");
+        if (fields.length === 0) {
+          outcomes.push(note ? { what: `broker ${id}`, result: "unchanged", note } : { what: `broker ${id}`, result: "unchanged" });
+          continue;
+        }
+        node.broker = want.host;
+        node.port = String(want.port);
+        node.usetls = false;
+        node.credentials = { user: want.user, password: want.password };
+        changed.push({ id, fields });
+      }
+      if (changed.length > 0) {
+        await deps.nodered.deploy(rev, flows);
+        for (const c of changed) {
+          await deps.marks.set(`broker-${c.id}`, markFor(c.id, want));
+          outcomes.push({ what: `broker ${c.id}`, result: "written", fields: c.fields, ...(note ? { note } : {}) });
+        }
+      }
+      return outcomes;
+    } catch (err) {
+      // A deploy against a revision someone else changed meanwhile (409) is read again once.
+      if (attempt === 0 && /\b409\b/.test(String(err))) continue;
+      return [...outcomes, { what: "mqtt", result: "refused", problem: scrub(err, want.password) }];
+    }
+  }
+  return outcomes;
+}

modules/nodered/mqtt/index.ts

@@ -0,0 +1,102 @@
+// nodered's MQTT step — run once by the host after Node-RED starts, and again whenever the
+// `mqtt-topic` binding, its pair credential or the settings change (the container's `restart-on`,
+// novox/hq ADR 0099). It points the mesh's broker config nodes at the broker the mesh bound, through
+// Node-RED's admin API (connection.ts). It connects to no mesh broker.
+//
+// Exits non-zero when anything could not be put right, so the node reports the step failed and the
+// host runs it again on the next apply. Declared last in the manifest, so its failing gates nothing
+// else of nodered's (novox/hq ADR 0136). Never prints a password.
+
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
+import { NodeRedClient } from "../client.js";
+import { namedBrokers, reconcileBrokers, type Binding, type Marks } from "./connection.js";
+import { probeBroker } from "./probe.js";
+
+const dir = process.env.MESH_PROVISIONS_DIR ?? "/run/provisions";
+const writtenDir = process.env.MESH_WRITTEN_DIR ?? "/var/lib/nodered-provisions";
+const waitSeconds = Number(process.env.MESH_NODERED_WAIT_SECONDS ?? "180");
+
+const readIfThere = (path: string): Promise<string | undefined> => readFile(path, "utf8").catch(() => undefined);
+const parse = <T>(raw: string | undefined): T | undefined => {
+  if (raw === undefined) return undefined;
+  try {
+    return JSON.parse(raw) as T;
+  } catch {
+    return undefined;
+  }
+};
+
+const marks: Marks = {
+  async get(name) {
+    return (await readIfThere(join(writtenDir, `${name}.digest`)))?.trim() || undefined;
+  },
+  async set(name, value) {
+    await mkdir(writtenDir, { recursive: true, mode: 0o700 });
+    const path = join(writtenDir, `${name}.digest`);
+    await writeFile(`${path}.tmp`, `${value}\n`, { mode: 0o600 });
+    await rename(`${path}.tmp`, path);
+  },
+};
+
+let client: NodeRedClient;
+try {
+  client = NodeRedClient.fromEnv();
+} catch (err) {
+  console.error(`[nodered-mqtt] ${err instanceof Error ? err.message : String(err)}`);
+  process.exit(1);
+}
+
+/** Node-RED answers the admin API once its flows are loaded and the token is good. */
+async function ready(): Promise<boolean> {
+  const until = Date.now() + waitSeconds * 1000;
+  for (;;) {
+    try {
+      await client.flowsWithRev();
+      return true;
+    } catch (err) {
+      if (/\b(401|403)\b/.test(String(err))) {
+        console.error("[nodered-mqtt] Node-RED refuses the api-token — settings.js and this step disagree");
+        return false;
+      }
+    }
+    if (Date.now() >= until) return false;
+    await new Promise((r) => setTimeout(r, 2000));
+  }
+}
+
+if (!(await ready())) {
+  console.error(`[nodered-mqtt] Node-RED's admin API did not answer at ${client.baseUrl} within ${waitSeconds}s`);
+  process.exit(1);
+}
+
+const binding = parse<Binding>(await readIfThere(join(dir, "mqtt-topic.json")));
+const secret = await readIfThere(join(dir, "mqtt-topic.secret"));
+const settings = parse<unknown>(await readIfThere(join(dir, "settings.json")));
+
+const outcomes = await reconcileBrokers(
+  {
+    nodered: {
+      flows: () => client.flowsWithRev(),
+      credentials: (type, id) => client.credentials(type, id),
+      deploy: (rev, flows) => client.deployFlowsAt(rev, flows, "nodes"),
+    },
+    probe: probeBroker,
+    marks,
+  },
+  binding,
+  secret,
+  namedBrokers(settings),
+);
+
+let failed = 0;
+for (const o of outcomes) {
+  if (o.result === "unchanged") console.log(`[nodered-mqtt] ${o.what}: already as the mesh says${o.note ? ` — ${o.note}` : ""}`);
+  else if (o.result === "written") console.log(`[nodered-mqtt] ${o.what}: wrote ${o.fields.join(", ")}${o.note ? ` — ${o.note}` : ""}`);
+  else {
+    failed++;
+    console.error(`[nodered-mqtt] ${o.what}: ${o.problem}`);
+  }
+}
+process.exitCode = failed > 0 ? 1 : 0;

modules/nodered/mqtt/probe.ts

@@ -0,0 +1,117 @@
+// Ask the broker, before Node-RED is told anything, whether it takes the login and password the
+// mesh delivered — and whether that login may subscribe to every topic, as flows expect.
+//
+// One MQTT 3.1.1 session: CONNECT (clean, a throwaway client id, so no flow's session is taken
+// over), read the CONNACK, optionally SUBSCRIBE once and read the SUBACK, DISCONNECT. No dependency:
+// the handful of bytes MQTT needs for this are written here.
+
+import { randomBytes } from "node:crypto";
+import { connect } from "node:net";
+
+export interface ProbeResult {
+  /** 0 accepted; 4 bad username or password; 5 not authorised. */
+  connack: number;
+  /** The SUBACK return code for the filter asked about: 0–2 granted, 0x80 refused. */
+  suback?: number;
+}
+
+export type Probe = (host: string, port: number, username: string, password: string, subscribe?: string) => Promise<ProbeResult>;
+
+function str(v: string): Buffer {
+  const b = Buffer.from(v, "utf8");
+  const len = Buffer.alloc(2);
+  len.writeUInt16BE(b.length);
+  return Buffer.concat([len, b]);
+}
+
+function packet(type: number, body: Buffer): Buffer {
+  let remaining = body.length;
+  const lenBytes: number[] = [];
+  do {
+    let byte = remaining % 128;
+    remaining = Math.floor(remaining / 128);
+    if (remaining > 0) byte |= 0x80;
+    lenBytes.push(byte);
+  } while (remaining > 0);
+  return Buffer.concat([Buffer.from([type, ...lenBytes]), body]);
+}
+
+/** The first complete packet in `buf`: its type byte, its body, and how many bytes it took. */
+export function firstPacket(buf: Buffer): { type: number; body: Buffer; used: number } | undefined {
+  if (buf.length < 2) return undefined;
+  let length = 0;
+  let multiplier = 1;
+  let i = 1;
+  for (;;) {
+    if (i >= buf.length) return undefined;
+    const byte = buf[i++];
+    length += (byte & 0x7f) * multiplier;
+    if ((byte & 0x80) === 0) break;
+    multiplier *= 128;
+    if (i > 4) throw new Error("malformed MQTT remaining length");
+  }
+  if (buf.length < i + length) return undefined;
+  return { type: buf[0], body: buf.subarray(i, i + length), used: i + length };
+}
+
+export const probeBroker: Probe = (host, port, username, password, subscribe) => {
+  const connectBody = Buffer.concat([
+    str("MQTT"),
+    Buffer.from([4, 0xc2, 0, 10]), // level 4 (3.1.1); username + password + clean session; keepalive 10s
+    str(`mesh-probe-${randomBytes(6).toString("hex")}`),
+    str(username),
+    str(password),
+  ]);
+  return new Promise((resolve, reject) => {
+    const socket = connect({ host, port });
+    let buf = Buffer.alloc(0);
+    const result: ProbeResult = { connack: -1 };
+    const timer = setTimeout(() => {
+      socket.destroy();
+      reject(new Error(`no answer from the broker at ${host}:${port} within 10s`));
+    }, 10_000);
+    const finish = (): void => {
+      clearTimeout(timer);
+      if (result.connack === 0) socket.end(Buffer.from([0xe0, 0]));
+      else socket.destroy();
+      resolve(result);
+    };
+    socket.on("connect", () => socket.write(packet(0x10, connectBody)));
+    socket.on("data", (chunk) => {
+      buf = Buffer.concat([buf, chunk]);
+      for (;;) {
+        let p;
+        try {
+          p = firstPacket(buf);
+        } catch (err) {
+          clearTimeout(timer);
+          socket.destroy();
+          reject(err);
+          return;
+        }
+        if (!p) return;
+        buf = buf.subarray(p.used);
+        const kind = p.type >> 4;
+        if (kind === 2) {
+          result.connack = p.body[1] ?? -1;
+          if (result.connack !== 0 || !subscribe) return finish();
+          // SUBSCRIBE, packet id 1, one filter at QoS 0.
+          socket.write(packet(0x82, Buffer.concat([Buffer.from([0, 1]), str(subscribe), Buffer.from([0])])));
+        } else if (kind === 9) {
+          result.suback = p.body[2];
+          return finish();
+        }
+      }
+    });
+    socket.on("error", (err) => {
+      clearTimeout(timer);
+      reject(err);
+    });
+    socket.on("close", () => {
+      if (result.connack === -1) {
+        clearTimeout(timer);
+        reject(new Error(`the broker at ${host}:${port} closed the connection without answering`));
+      }
+    });
+  });
+};

modules/nodered/package.json

@@ -1,9 +1,14 @@
 {
   "name": "@novox/module-nodered",
   "version": "0.1.0",
-  "description": "nodered — flow-based automation. Its client and tools live here (novox/hq ADR 0039).",
+  "description": "nodered \u2014 flow-based automation. Its client and tools live here (novox/hq ADR 0039).",
   "type": "module",
   "private": true,
+  "scripts": {
+    "build": "tsc client.ts tools/index.ts mqtt/probe.ts mqtt/connection.ts mqtt/index.ts --module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist",
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "node --test --experimental-strip-types 'test/*.test.ts'"
+  },
   "dependencies": {
     "@novox/mesh-sdk": "^0.1.0"
   },

modules/nodered/test/mqtt.test.ts

@@ -0,0 +1,124 @@
+// What holds nodered's MQTT step (mqtt/connection.ts): the broker nodes the mesh owns — the one it
+// makes, or the ones settings name — are made to use the broker and login the mesh bound, only after
+// the broker takes that login; every other field of a node is kept; nothing is deployed when nothing
+// differs; a node that is not named is never touched; a loopback broker address is refused.
+//
+// Node-RED and the broker are fakes answering as the real ones do (admin API v2 of nodered/node-red
+// 5.0.7, the build ace runs).
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+import { MESH_BROKER_ID, namedBrokers, reconcileBrokers, type Binding, type FlowNode, type Marks, type NodeRed } from "../mqtt/connection.ts";
+import type { Probe } from "../mqtt/probe.ts";
+
+const MINTED = "mesh-minted-password";
+const binding = (at = "ace.internal"): Binding => ({ provision: "mqtt-topic", from: "ace", at, as: "mesh_ace_nodered", serves: { scheme: "mqtt", port: 1883 } });
+
+/** ace's flows, reduced: its one broker node (dead, zurag.be:1884) and a node that uses it. */
+function aceFlows(): FlowNode[] {
+  return [
+    { id: "2b0aece9c5f3b307", type: "mqtt-broker", name: "MQTT Broker", broker: "zurag.be", port: "1884", clientid: "", usetls: false, protocolVersion: "4", keepalive: "60" },
+    { id: "fe0cae96f1e3ae4d", type: "mqtt in", topic: "stat/sonoff_office_light_switch/RESULT", broker: "2b0aece9c5f3b307", z: "t" },
+    { id: "other-broker", type: "mqtt-broker", name: "someone else's", broker: "test.mosquitto.org", port: "1883" },
+  ];
+}
+
+function fakeNodeRed(flows: FlowNode[], creds: Record<string, { user?: string; password?: string }> = {}) {
+  let rev = "r1";
+  const deploys: FlowNode[][] = [];
+  const nodered: NodeRed = {
+    async flows() {
+      return { rev, flows: structuredClone(flows) };
+    },
+    async credentials(_type, id) {
+      const c = creds[id] ?? {};
+      return { user: c.user, has_password: Boolean(c.password) };
+    },
+    async deploy(at, next) {
+      if (at !== rev) throw new Error("Node-RED /flows: 409 version_mismatch");
+      for (const n of next) {
+        if (n.credentials) creds[n.id] = { ...(creds[n.id] ?? {}), ...(n.credentials as object) };
+      }
+      flows.splice(0, flows.length, ...next.map(({ credentials: _c, ...n }) => n as FlowNode));
+      deploys.push(next);
+      rev = `r${deploys.length + 1}`;
+    },
+  };
+  return { nodered, deploys, flows, creds };
+}
+
+const marks = (): Marks & { store: Map<string, string> } => {
+  const store = new Map<string, string>();
+  return { store, get: async (k) => store.get(k), set: async (k, v) => void store.set(k, v) };
+};
+const takes: Probe = async (_h, _p, user, pass) => ({ connack: user === "mesh_ace_nodered" && pass === MINTED ? 0 : 5, suback: 0 });
+
+test("ace: the named broker node is moved to the bound broker and login; the other broker is not touched", async () => {
+  const f = fakeNodeRed(aceFlows(), { "2b0aece9c5f3b307": { user: "luffy", password: "old" }, "other-broker": { user: "x", password: "y" } });
+  const m = marks();
+  const out = await reconcileBrokers({ nodered: f.nodered, probe: takes, marks: m }, binding(), `${MINTED}\n`, ["2b0aece9c5f3b307"]);
+  assert.deepEqual(out, [{ what: "broker 2b0aece9c5f3b307", result: "written", fields: ["broker", "port", "user", "password"] }]);
+  const node = f.flows.find((n) => n.id === "2b0aece9c5f3b307");
+  assert.deepEqual(node, { ...aceFlows()[0], broker: "ace.internal", port: "1883", usetls: false });
+  assert.deepEqual(f.creds["2b0aece9c5f3b307"], { user: "mesh_ace_nodered", password: MINTED });
+  assert.deepEqual(f.flows.find((n) => n.id === "other-broker"), aceFlows()[2]);
+  assert.deepEqual(f.creds["other-broker"], { user: "x", password: "y" });
+  // Only the changed node carried credentials in the deploy.
+  assert.deepEqual(f.deploys[0].filter((n) => n.credentials).map((n) => n.id), ["2b0aece9c5f3b307"]);
+
+  // Again: nothing differs, nothing is deployed.
+  const again = await reconcileBrokers({ nodered: f.nodered, probe: takes, marks: m }, binding(), MINTED, ["2b0aece9c5f3b307"]);
+  assert.deepEqual(again, [{ what: "broker 2b0aece9c5f3b307", result: "unchanged" }]);
+  assert.equal(f.deploys.length, 1);
+});
+
+test("fresh: with nothing named, the step makes its own broker node", async () => {
+  const f = fakeNodeRed([]);
+  const out = await reconcileBrokers({ nodered: f.nodered, probe: takes, marks: marks() }, binding(), MINTED, []);
+  assert.deepEqual(out, [{ what: `broker ${MESH_BROKER_ID}`, result: "written", fields: ["node"] }]);
+  assert.equal(f.flows[0].type, "mqtt-broker");
+  assert.equal(f.flows[0].broker, "ace.internal");
+  assert.deepEqual(f.creds[MESH_BROKER_ID], { user: "mesh_ace_nodered", password: MINTED });
+});
+
+test("a login the broker does not take is never written", async () => {
+  const f = fakeNodeRed(aceFlows());
+  const out = await reconcileBrokers({ nodered: f.nodered, probe: async () => ({ connack: 5 }), marks: marks() }, binding(), MINTED, ["2b0aece9c5f3b307"]);
+  assert.equal(out[0].result, "refused");
+  assert.equal(f.deploys.length, 0);
+});
+
+test("a named node that is not there, or a loopback broker, is refused", async () => {
+  const f = fakeNodeRed(aceFlows());
+  const out = await reconcileBrokers({ nodered: f.nodered, probe: takes, marks: marks() }, binding(), MINTED, ["gone"]);
+  assert.match((out[0] as { problem: string }).problem, /no such node/);
+  const lo = await reconcileBrokers({ nodered: f.nodered, probe: takes, marks: marks() }, binding("127.0.0.1"), MINTED, []);
+  assert.match((lo[0] as { problem: string }).problem, /Node-RED itself/);
+  assert.equal(f.deploys.length, 0);
+});
+
+test("a deploy that raced another is read again once", async () => {
+  const f = fakeNodeRed(aceFlows());
+  let first = true;
+  const racing: NodeRed = {
+    ...f.nodered,
+    async flows() {
+      const got = await f.nodered.flows();
+      if (first) {
+        first = false;
+        return { ...got, rev: "stale" };
+      }
+      return got;
+    },
+  };
+  const out = await reconcileBrokers({ nodered: racing, probe: takes, marks: marks() }, binding(), MINTED, ["2b0aece9c5f3b307"]);
+  assert.equal(out[0].result, "written");
+  assert.equal(f.deploys.length, 1);
+});
+
+test("settings name broker nodes under mqtt.brokers", () => {
+  assert.deepEqual(namedBrokers({ mqtt: { brokers: ["a", "", 3, "b"] } }), ["a", "b"]);
+  assert.deepEqual(namedBrokers({ endpoints: {} }), []);
+  assert.deepEqual(namedBrokers(undefined), []);
+});

modules/nodered/tsconfig.json

@@ -8,5 +8,11 @@
     "skipLibCheck": true,
     "noEmit": true
   },
-  "include": ["client.ts", "tools/index.ts"]
+  "include": [
+    "client.ts",
+    "tools/index.ts",
+    "mqtt/probe.ts",
+    "mqtt/connection.ts",
+    "mqtt/index.ts"
+  ]
 }