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.
nodered: the sidecar dials the port it was given
2026-09-30 13:01:14 +02:00 · 2026-09-29 23:50:11 +02:00 · 2026-09-29 23:41:18 +02:00 · 2026-09-29 20:45:13 +00:00 · 2026-09-29 22:41:56 +02:00 · 2026-09-29 22:33:38 +02:00
59 changed files with 904 additions and 70 deletions
@@ -14,7 +14,7 @@
    },
    "route": {
      "label": "baserow",
-      "port": 80
+      "endpoint": "web"
    }
  },
  "binds": {
@@ -30,6 +30,7 @@
  },
  "listens": [
    {
+      "name": "web",
      "port": 80,
      "protocol": "tcp",
      "from": "mesh",
@@ -13,6 +13,7 @@
  },
  "listens": [
    {
+      "name": "web",
      "port": 6767,
      "protocol": "tcp",
      "from": "mesh",
@@ -110,7 +111,7 @@
  "contributes": {
    "route": {
      "label": "subs",
-      "port": 6767
+      "endpoint": "web"
    }
  },
  "binds": {
@@ -15,6 +15,7 @@
  },
  "listens": [
    {
+      "name": "web",
      "port": 8787,
      "protocol": "tcp",
      "from": "mesh",
@@ -87,7 +88,7 @@
  "contributes": {
    "route": {
      "label": "books",
-      "port": 8787
+      "endpoint": "web"
    }
  },
  "binds": {
@@ -0,0 +1,56 @@
+{
+  "module": "ca-trust",
+  "version": "1",
+  "slug": "catrust",
+  "capabilities": [
+    "service-manager"
+  ],
+  "requires": [
+    "internal-acme-ca"
+  ],
+  "seats": [
+    {
+      "name": "the-mesh-trust-anchor",
+      "scope": "node"
+    }
+  ],
+  "claims": [
+    {
+      "name": "the-mesh-trust-anchor",
+      "scope": "node"
+    }
+  ],
+  "resources": [
+    {
+      "id": "state",
+      "type": "directory",
+      "mode": "0700",
+      "place": "."
+    },
+    {
+      "id": "anchor",
+      "type": "file",
+      "path": "${dir:state}/anchor",
+      "mode": "0755",
+      "content": "#!/bin/sh\n# The mesh's internal certificate authority, trusted by this machine.\n#\n# Written by the mesh from the ca-trust module's manifest (novox/hq ADR 0147).\n# Editing it here lasts until the next apply.\n#\n# There is no prior trust to verify the fetch against \u2014 this is the thing that\n# establishes it \u2014 so it is made over the mesh's own private network, which is\n# what authenticates it (novox/hq ADR 0098, the same reasoning that lets the\n# route proxy fetch this root for itself). What comes back is checked here: a\n# body that is not a certificate is refused now, rather than believed and then\n# failed by whatever reads the trust store next.\nset -eu\n\nROOTS='https://${bound:internal-acme-ca:at}:${bound:internal-acme-ca:port}${bound:internal-acme-ca:roots}'\nANCHORS=/etc/ca-certificates/trust-source/anchors\nANCHOR=\"$ANCHORS/mesh-internal-ca.crt\"\n\n# Arch's layout, said out loud rather than assumed: a machine that keeps its\n# anchors elsewhere fails here, visibly, instead of writing a file nothing\n# reads. That failure is the signal that this belongs in the host, where one\n# operating system's difference lives (novox/hq ADR 0147, option 2).\n[ -d \"$ANCHORS\" ] || {\n\techo \"this machine keeps no trust anchors in $ANCHORS; ca-trust is written for that layout\" >&2\n\texit 1\n}\n\ncase \"${1:-}\" in\ninstall)\n\ttmp=$(mktemp)\n\ttrap 'rm -f \"$tmp\"' EXIT\n\t# The authority may still be starting, or this machine may have come up\n\t# before it: two minutes of asking, then an honest failure.\n\tn=0\n\twhile [ \"$n\" -lt 60 ]; do\n\t\tif curl --fail --silent --show-error --insecure --max-time 10 \\\n\t\t\t--output \"$tmp\" \"$ROOTS\" &&\n\t\t\tgrep -q 'BEGIN CERTIFICATE' \"$tmp\"; then\n\t\t\tinstall -m 0644 \"$tmp\" \"$ANCHOR\"\n\t\t\tupdate-ca-trust\n\t\t\texit 0\n\t\tfi\n\t\tn=$((n + 1))\n\t\tsleep 2\n\tdone\n\techo \"the authority at $ROOTS did not serve a certificate within two minutes\" >&2\n\texit 1\n\t;;\nremove)\n\t# What stopping the unit does, and therefore what being unassigned does.\n\trm -f \"$ANCHOR\"\n\tupdate-ca-trust\n\t;;\n*)\n\techo \"usage: $(basename \"$0\") install|remove\" >&2\n\texit 2\n\t;;\nesac\n"
+    },
+    {
+      "id": "unit",
+      "type": "file",
+      "path": "/etc/systemd/system/mesh-ca-trust.service",
+      "mode": "0644",
+      "content": "[Unit]\nDescription=The mesh's internal certificate authority, trusted by this machine\n# novox/hq ADR 0147. Starting this unit places the mesh's root among this\n# machine's trust anchors; stopping it takes the root away again, which is what\n# the host does when the module is no longer assigned here.\nWants=network-online.target\nAfter=network-online.target\n\n[Service]\nType=oneshot\nRemainAfterExit=yes\nExecStart=${dir:state}/anchor install\nExecStop=${dir:state}/anchor remove\n\n[Install]\nWantedBy=multi-user.target\n"
+    },
+    {
+      "id": "trust",
+      "type": "service",
+      "unit": "mesh-ca-trust.service",
+      "state": "running",
+      "boot": "enabled",
+      "restart-on": [
+        "anchor",
+        "unit"
+      ]
+    }
+  ]
+}
@@ -11,7 +11,7 @@
  "contributes": {
    "route": {
      "label": "de-spiegel",
-      "port": 35621
+      "endpoint": "web"
    }
  },
  "binds": {
@@ -23,6 +23,7 @@
  },
  "listens": [
    {
+      "name": "web",
      "port": 35621,
      "protocol": "tcp",
      "from": "mesh",
@@ -29,6 +29,7 @@
  },
  "listens": [
    {
+      "name": "registry",
      "port": 5000,
      "protocol": "tcp",
      "from": "mesh",
@@ -22,6 +22,7 @@
  ],
  "listens": [
    {
+      "name": "dns-udp",
      "port": 53,
      "protocol": "udp",
      "from": "mesh",
@@ -29,6 +30,7 @@
      "fixed": true
    },
    {
+      "name": "dns-tcp",
      "port": 53,
      "protocol": "tcp",
      "from": "mesh",
@@ -13,7 +13,7 @@
    "route": {
      "web": {
        "label": "git",
-        "port": 3000
+        "endpoint": "web"
      },
      "internal-api-refused": {
        "label": "git",
@@ -44,12 +44,14 @@
  ],
  "listens": [
    {
+      "name": "web",
      "port": 3000,
      "protocol": "tcp",
      "from": "mesh",
      "why": "the forge, over http"
    },
    {
+      "name": "ssh",
      "port": 22,
      "protocol": "tcp",
      "from": "mesh",
@@ -13,6 +13,7 @@
  ],
  "listens": [
    {
+      "name": "web",
      "port": 3000,
      "protocol": "tcp",
      "from": "mesh",
@@ -96,7 +97,7 @@
  "contributes": {
    "route": {
      "label": "grafana",
-      "port": 3000
+      "endpoint": "web"
    }
  },
  "binds": {
@@ -11,7 +11,7 @@
  "contributes": {
    "route": {
      "label": "hello",
-      "port": 8080
+      "endpoint": "web"
    }
  },
  "binds": {
@@ -19,6 +19,7 @@
  },
  "listens": [
    {
+      "name": "web",
      "port": 8080,
      "protocol": "tcp",
      "from": "mesh",
@@ -14,6 +14,7 @@
  },
  "listens": [
    {
+      "name": "web",
      "port": 8123,
      "protocol": "tcp",
      "from": "mesh",
@@ -85,7 +86,7 @@
  "contributes": {
    "route": {
      "label": "home-assistant",
-      "port": 8123
+      "endpoint": "web"
    }
  },
  "binds": {
@@ -13,6 +13,7 @@
  },
  "listens": [
    {
+      "name": "stream",
      "port": 8000,
      "protocol": "tcp",
      "from": "mesh",
@@ -9,6 +9,7 @@
  },
  "listens": [
    {
+      "name": "api",
      "port": 8086,
      "protocol": "tcp",
      "from": "mesh",
@@ -17,11 +17,11 @@
    "route": {
      "site": {
        "label": "invoicing",
-        "port": 80
+        "endpoint": "web"
      },
      "api": {
        "label": "invoicing-api",
-        "port": 9000
+        "endpoint": "api"
      }
    }
  },
@@ -36,12 +36,14 @@
  },
  "listens": [
    {
+      "name": "web",
      "port": 80,
      "protocol": "tcp",
      "from": "mesh",
      "why": "the invoicing web frontend; a public name is a route grant later"
    },
    {
+      "name": "api",
      "port": 9000,
      "protocol": "tcp",
      "from": "mesh",
@@ -6,6 +6,7 @@
  ],
  "listens": [
    {
+      "name": "web",
      "port": 9117,
      "protocol": "tcp",
      "from": "mesh",
@@ -82,7 +83,7 @@
  "contributes": {
    "route": {
      "label": "indexers",
-      "port": 9117
+      "endpoint": "web"
    }
  },
  "binds": {
@@ -11,7 +11,7 @@
    },
    "route": {
      "label": "keycloak",
-      "port": 8080
+      "endpoint": "web"
    }
  },
  "binds": {
@@ -34,6 +34,7 @@
  ],
  "listens": [
    {
+      "name": "web",
      "port": 8080,
      "protocol": "tcp",
      "from": "mesh",
@@ -24,6 +24,7 @@
  },
  "listens": [
    {
+      "name": "web",
      "port": 8283,
      "protocol": "tcp",
      "from": "mesh",
@@ -14,6 +14,7 @@
  },
  "listens": [
    {
+      "name": "web",
      "port": 8686,
      "protocol": "tcp",
      "from": "mesh",
@@ -86,7 +87,7 @@
  "contributes": {
    "route": {
      "label": "lidarr",
-      "port": 8686
+      "endpoint": "web"
    }
  },
  "binds": {
@@ -16,27 +16,27 @@
    "route": {
      "web": {
        "label": "mail",
-        "port": 7443,
+        "endpoint": "web-tls",
        "scheme": "https",
        "insecure": true
      },
      "acme": {
        "label": "mail",
        "path": "/.well-known/acme-challenge",
-        "port": 7080,
+        "endpoint": "web",
        "priority": 100
      },
      "autoconfig": {
        "label": "autoconfig",
-        "port": 4243
+        "endpoint": "autoconfig"
      },
      "autodiscover": {
        "label": "autodiscover",
-        "port": 4243
+        "endpoint": "autoconfig"
      },
      "automx": {
        "label": "automx",
-        "port": 4243
+        "endpoint": "autoconfig"
      }
    }
  },
@@ -60,6 +60,7 @@
  ],
  "listens": [
    {
+      "name": "smtp",
      "port": 25,
      "protocol": "tcp",
      "from": "anywhere",
@@ -67,6 +68,7 @@
      "fixed": true
    },
    {
+      "name": "pop3",
      "port": 110,
      "protocol": "tcp",
      "from": "anywhere",
@@ -74,6 +76,7 @@
      "fixed": true
    },
    {
+      "name": "imap",
      "port": 143,
      "protocol": "tcp",
      "from": "anywhere",
@@ -81,6 +84,7 @@
      "fixed": true
    },
    {
+      "name": "smtps",
      "port": 465,
      "protocol": "tcp",
      "from": "anywhere",
@@ -88,6 +92,7 @@
      "fixed": true
    },
    {
+      "name": "submission",
      "port": 587,
      "protocol": "tcp",
      "from": "anywhere",
@@ -95,6 +100,7 @@
      "fixed": true
    },
    {
+      "name": "imaps",
      "port": 993,
      "protocol": "tcp",
      "from": "anywhere",
@@ -102,6 +108,7 @@
      "fixed": true
    },
    {
+      "name": "pop3s",
      "port": 995,
      "protocol": "tcp",
      "from": "anywhere",
@@ -109,18 +116,21 @@
      "fixed": true
    },
    {
+      "name": "web",
      "port": 7080,
      "protocol": "tcp",
      "from": "mesh",
      "why": "the web front over http; only the ACME HTTP-01 passthrough is routed here \u2014 everything else 301s to https and would loop a proxy"
    },
    {
+      "name": "web-tls",
      "port": 7443,
      "protocol": "tcp",
      "from": "mesh",
      "why": "the web front over its own TLS (admin, webmail, API); the public name mail.novox.be is a route grant reaching it here"
    },
    {
+      "name": "autoconfig",
      "port": 4243,
      "protocol": "tcp",
      "from": "mesh",
@@ -6,6 +6,7 @@
  ],
  "listens": [
    {
+      "name": "api",
      "port": 59125,
      "protocol": "tcp",
      "from": "mesh",
@@ -14,11 +14,11 @@
    "route": {
      "api": {
        "label": "files-api",
-        "port": 9000
+        "endpoint": "s3"
      },
      "console": {
        "label": "files",
-        "port": 9001
+        "endpoint": "console"
      }
    }
  },
@@ -31,12 +31,14 @@
  ],
  "listens": [
    {
+      "name": "s3",
      "port": 9000,
      "protocol": "tcp",
      "from": "mesh",
      "why": "the S3 endpoint"
    },
    {
+      "name": "console",
      "port": 9001,
      "protocol": "tcp",
      "from": "mesh",
@@ -20,6 +20,7 @@
  ],
  "listens": [
    {
+      "name": "database",
      "port": 27017,
      "protocol": "tcp",
      "from": "mesh",
@@ -34,12 +34,14 @@
  },
  "listens": [
    {
+      "name": "mqtt",
      "port": 1883,
      "protocol": "tcp",
      "from": "mesh",
      "why": "modules on any machine that were granted a topic namespace"
    },
    {
+      "name": "mqtt-websockets",
      "port": 8081,
      "protocol": "tcp",
      "from": "mesh",
@@ -20,6 +20,7 @@
  ],
  "listens": [
    {
+      "name": "database",
      "port": 4848,
      "protocol": "tcp",
      "from": "mesh",
@@ -14,7 +14,7 @@
    },
    "route": {
      "label": "n8n",
-      "port": 5682
+      "endpoint": "web"
    }
  },
  "binds": {
@@ -29,6 +29,7 @@
  },
  "listens": [
    {
+      "name": "web",
      "port": 5682,
      "protocol": "tcp",
      "from": "mesh",
@@ -21,6 +21,7 @@
  "consumes": [],
  "listens": [
    {
+      "name": "bus",
      "port": 4222,
      "protocol": "tcp",
      "from": "mesh",
@@ -13,7 +13,7 @@
    },
    "route": {
      "label": "drive",
-      "port": 80
+      "endpoint": "web"
    }
  },
  "binds": {
@@ -38,6 +38,7 @@
  ],
  "listens": [
    {
+      "name": "web",
      "port": 80,
      "protocol": "tcp",
      "from": "mesh",
@@ -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.
@@ -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 }),
-      body: JSON.stringify(config),
+      // v2 answers { rev }; v1 answers 204 with no body, which req() cannot parse.
+      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 };
  }
@@ -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": [
@@ -12,6 +14,7 @@
  ],
  "listens": [
    {
+      "name": "web",
      "port": 1880,
      "protocol": "tcp",
      "from": "mesh",
@@ -25,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"
      ]
    },
    {
@@ -52,8 +92,7 @@
      "type": "file",
      "path": "/var/lib/mesh/nodered/config.json",
      "mode": "0600",
-      "content": "{}\n",
-      "merge": "json"
+      "content": "{\n  \"token\": \"${secret:api-token}\"\n}\n"
    },
    {
      "id": "runtime",
@@ -66,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",
-      "port": 1880
+      "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": [
@@ -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;
+}
@@ -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;
@@ -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`));
+      }
+    });
+  });
+};
@@ -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"
  },
@@ -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), []);
+});
@@ -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"
+  ]
 }
@@ -10,7 +10,7 @@
  "contributes": {
    "route": {
      "label": "@",
-      "port": 4000
+      "endpoint": "web"
    }
  },
  "binds": {
@@ -18,6 +18,7 @@
  },
  "listens": [
    {
+      "name": "web",
      "port": 4000,
      "protocol": "tcp",
      "from": "mesh",
@@ -15,6 +15,7 @@
  },
  "listens": [
    {
+      "name": "web",
      "port": 6789,
      "protocol": "tcp",
      "from": "mesh",
@@ -12,6 +12,7 @@
  ],
  "listens": [
    {
+      "name": "api",
      "port": 11434,
      "protocol": "tcp",
      "from": "machine",
@@ -14,6 +14,7 @@
  },
  "listens": [
    {
+      "name": "web",
      "port": 3579,
      "protocol": "tcp",
      "from": "mesh",
@@ -89,7 +90,7 @@
  "contributes": {
    "route": {
      "label": "ombi",
-      "port": 3579
+      "endpoint": "web"
    }
  },
  "binds": {
@@ -11,7 +11,7 @@
  "contributes": {
    "route": {
      "label": "office",
-      "port": 9070
+      "endpoint": "web"
    }
  },
  "binds": {
@@ -22,6 +22,7 @@
  },
  "listens": [
    {
+      "name": "web",
      "port": 9070,
      "protocol": "tcp",
      "from": "mesh",
@@ -11,7 +11,7 @@
  "contributes": {
    "route": {
      "label": "eef",
-      "port": 4012
+      "endpoint": "web"
    }
  },
  "binds": {
@@ -19,6 +19,7 @@
  },
  "listens": [
    {
+      "name": "web",
      "port": 4012,
      "protocol": "tcp",
      "from": "mesh",
@@ -11,7 +11,7 @@
  "contributes": {
    "route": {
      "label": "filip",
-      "port": 4013
+      "endpoint": "web"
    }
  },
  "binds": {
@@ -19,6 +19,7 @@
  },
  "listens": [
    {
+      "name": "web",
      "port": 4013,
      "protocol": "tcp",
      "from": "mesh",
@@ -18,7 +18,7 @@
    },
    "route": {
      "label": "photos",
-      "port": 4001
+      "endpoint": "web"
    }
  },
  "binds": {
@@ -32,12 +32,14 @@
  },
  "listens": [
    {
+      "name": "api",
      "port": 9000,
      "protocol": "tcp",
      "from": "mesh",
      "why": "the photos backend API; the client sites on the module network call it"
    },
    {
+      "name": "web",
      "port": 4001,
      "protocol": "tcp",
      "from": "mesh",
@@ -18,6 +18,7 @@
  },
  "listens": [
    {
+      "name": "stream",
      "port": 32400,
      "protocol": "tcp",
      "from": "mesh",
@@ -7,12 +7,14 @@
  ],
  "listens": [
    {
+      "name": "web",
      "port": 9090,
      "protocol": "tcp",
      "from": "mesh",
      "why": "the dashboard over http; portainer.novox.be is a route grant and the proxy reaches it here \u2014 the machine side of 9090:9000, the predecessor's number"
    },
    {
+      "name": "web-tls",
      "port": 9443,
      "protocol": "tcp",
      "from": "mesh",
@@ -103,7 +105,7 @@
  "contributes": {
    "route": {
      "label": "portainer",
-      "port": 9090
+      "endpoint": "web"
    }
  },
  "binds": {
@@ -26,6 +26,7 @@
  ],
  "listens": [
    {
+      "name": "database",
      "port": 5432,
      "protocol": "tcp",
      "from": "mesh",
@@ -16,6 +16,7 @@
  },
  "listens": [
    {
+      "name": "web",
      "port": 8080,
      "protocol": "tcp",
      "from": "mesh",
@@ -14,6 +14,7 @@
  },
  "listens": [
    {
+      "name": "web",
      "port": 7878,
      "protocol": "tcp",
      "from": "mesh",
@@ -86,7 +87,7 @@
  "contributes": {
    "route": {
      "label": "movies",
-      "port": 7878
+      "endpoint": "web"
    }
  },
  "binds": {
@@ -40,6 +40,7 @@
  },
  "listens": [
    {
+      "name": "cache",
      "port": 6379,
      "protocol": "tcp",
      "from": "mesh",
@@ -27,12 +27,14 @@
  },
  "listens": [
    {
+      "name": "http",
      "port": 80,
      "protocol": "tcp",
      "from": "anywhere",
      "why": "public HTTP, and the ACME HTTP-01 challenge answered at the name being certified"
    },
    {
+      "name": "https",
      "port": 443,
      "protocol": "tcp",
      "from": "anywhere",
@@ -5,11 +5,12 @@
    "container-runtime"
  ],
  "own-secrets": {
-    "secret": "/var/lib/searxng-module/secret.secret",
+    "secret": "/var/lib/mesh/searxng/secret",
    "broker": "/var/lib/mesh/searxng/broker"
  },
  "listens": [
    {
+      "name": "web",
      "port": 8080,
      "protocol": "tcp",
      "from": "mesh",
@@ -26,22 +27,14 @@
    {
      "id": "state",
      "type": "directory",
-      "path": "/var/lib/searxng-module",
-      "mode": "0700"
+      "mode": "0700",
+      "place": "."
    },
    {
      "id": "valkey-data",
      "type": "directory",
-      "path": "/var/lib/searxng-module/valkey-data",
      "mode": "0700"
    },
-    {
-      "id": "server-env",
-      "type": "file",
-      "path": "/var/lib/searxng-module/server.env",
-      "mode": "0600",
-      "content": "SEARXNG_SECRET=${secret:secret}\nSEARXNG_VALKEY_URL=valkey://valkey:6379/0\n"
-    },
    {
      "id": "net",
      "type": "network",
@@ -62,30 +55,39 @@
        "warning"
      ],
      "volumes": [
-        "/var/lib/searxng-module/valkey-data:/data"
+        "${dir:valkey-data}:/data"
      ]
    },
+    {
+      "id": "settings",
+      "type": "file",
+      "path": "${dir:state}/settings.yml",
+      "mode": "0600",
+      "merge": "json",
+      "content": "{\n  \"use_default_settings\": true,\n  \"server\": {\n    \"secret_key\": \"${secret:secret}\",\n    \"base_url\": false,\n    \"limiter\": false,\n    \"image_proxy\": false,\n    \"public_instance\": false\n  },\n  \"search\": {\n    \"formats\": [\"html\", \"json\"]\n  },\n  \"valkey\": {\n    \"url\": \"valkey://valkey:6379/0\"\n  }\n}\n"
+    },
    {
      "id": "server",
      "type": "container",
      "name": "searxng",
-      "image": "searxng/searxng@sha256:c7cc75852051bf6254afda6ed1b920dd1677d8efe4ab141bf558f02e582f4371",
+      "image": "searxng/searxng@sha256:cd8812607ab73730a0b1a0dc4990223fe1b9e383f6f35947114d0bef7f8bb441",
      "network": "searxng",
-      "env-file": [
-        "/var/lib/searxng-module/server.env"
-      ],
      "ports": [
        "8080"
      ],
-      "secrets-in-environment": "SEARXNG_SECRET is env-only, but settings.yml carries server.secret_key; convertible by mounting a generated settings.yml, not yet done"
+      "volumes": [
+        "${dir:state}/settings.yml:/etc/searxng/settings.yml:ro"
+      ],
+      "restart-on": [
+        "settings"
+      ]
    },
    {
      "id": "runtime-config",
      "type": "file",
      "path": "/var/lib/mesh/searxng/config.json",
      "mode": "0600",
-      "content": "{}\n",
-      "merge": "json"
+      "content": "{}\n"
    },
    {
      "id": "runtime",
@@ -113,11 +115,11 @@
  "contributes": {
    "route": {
      "label": "searxng",
-      "port": 8080
+      "endpoint": "web"
    }
  },
  "binds": {
-    "route": "/var/lib/searxng-module/route.json"
+    "route": "${dir:state}/route.json"
  },
  "build": {
    "on": [
@@ -43,6 +43,7 @@
  ],
  "listens": [
    {
+      "name": "web",
      "port": 8080,
      "protocol": "tcp",
      "from": "mesh",
@@ -14,6 +14,7 @@
  },
  "listens": [
    {
+      "name": "web",
      "port": 8989,
      "protocol": "tcp",
      "from": "mesh",
@@ -91,7 +92,7 @@
  "contributes": {
    "route": {
      "label": "series",
-      "port": 8989
+      "endpoint": "web"
    }
  },
  "binds": {
@@ -7,6 +7,7 @@
  ],
  "listens": [
    {
+      "name": "ssh",
      "port": 22,
      "protocol": "tcp",
      "from": "anywhere",
@@ -26,6 +26,7 @@
  },
  "listens": [
    {
+      "name": "acme",
      "port": 9000,
      "protocol": "tcp",
      "from": "mesh",
@@ -12,6 +12,7 @@
  ],
  "listens": [
    {
+      "name": "web",
      "port": 8181,
      "protocol": "tcp",
      "from": "mesh",
@@ -85,7 +86,7 @@
  "contributes": {
    "route": {
      "label": "tautulli",
-      "port": 8181
+      "endpoint": "web"
    }
  },
  "binds": {
@@ -15,7 +15,7 @@
    },
    "route": {
      "label": "umami",
-      "port": 3000
+      "endpoint": "web"
    }
  },
  "binds": {
@@ -49,10 +49,11 @@
  },
  "listens": [
    {
+      "name": "web",
      "port": 3000,
      "protocol": "tcp",
-      "from": "anywhere",
-      "why": "one port serves two surfaces: the dashboard (the proxy gates it to the mesh) and the public collection endpoint that the browsers of every tracked site POST to \u2014 so the port itself must be reachable from anywhere"
+      "from": "mesh",
+      "why": "one port serves two surfaces \u2014 the dashboard and the collection endpoint that the browsers of every tracked site POST to. Both are reached through the proxy, by name, so the port is how the proxy reaches this module and nothing else (novox/hq ADR 0045). It said \"anywhere\" and gave the reason that the collection endpoint must be public, which is true of the name and not of the port: opened, the machine-side port served the dashboard over plain HTTP to the internet, bypassing every rule the proxy applies by path"
    }
  ],
  "resources": [
@@ -6,54 +6,63 @@
  ],
  "listens": [
    {
+      "name": "web",
      "port": 8443,
      "protocol": "tcp",
      "from": "mesh",
      "why": "the controller web UI, over its own self-signed tls; reaching it from outside is a route grant later"
    },
    {
+      "name": "inform",
      "port": 8080,
      "protocol": "tcp",
      "from": "mesh",
      "why": "device inform \u2014 how APs and switches check in and are adopted"
    },
    {
+      "name": "stun",
      "port": 3478,
      "protocol": "udp",
      "from": "mesh",
      "why": "STUN, so managed devices can find the controller through NAT"
    },
    {
+      "name": "discovery",
      "port": 10001,
      "protocol": "udp",
      "from": "mesh",
      "why": "device discovery \u2014 the controller finds unadopted devices on the network"
    },
    {
+      "name": "discovery-l2",
      "port": 1902,
      "protocol": "udp",
      "from": "mesh",
      "why": "layer-2 (UBNT) discovery broadcasts; published on 1902, the container listens on 1900"
    },
    {
+      "name": "portal-tls",
      "port": 8843,
      "protocol": "tcp",
      "from": "mesh",
      "why": "the guest captive portal over https"
    },
    {
+      "name": "portal",
      "port": 8880,
      "protocol": "tcp",
      "from": "mesh",
      "why": "the guest captive portal over http"
    },
    {
+      "name": "speedtest",
      "port": 6789,
      "protocol": "tcp",
      "from": "mesh",
      "why": "mobile-app speed-test throughput measurement"
    },
    {
+      "name": "syslog",
      "port": 5514,
      "protocol": "udp",
      "from": "mesh",
Author	SHA1	Message	Date
jschoubben	3c7aafdc21	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.	2026-09-30 13:01:14 +02:00
jschoubben	c1a65e2354	nodered: the sidecar dials the port it was given The sidecar runs on the host network and dialled 127.0.0.1:1880, the software's port; the mesh publishes nodered on a machine port it assigns, so the tools reached whatever else holds 1880, or nothing (hq 088).	2026-09-29 23:50:11 +02:00
jschoubben	0c91e08bad	nodered: its settings are files the mesh writes, and its editor is locked The catalogue ran the image's defaults: no adminAuth, so a routed Node-RED editor (which runs arbitrary code) was open to anyone who reached it, and the module's own tools had no token to present to an install that was locked. - settings.js (fixed, 0600, uid 1000) carries adminAuth: user admin checked against the admin secret -- a minted password, or the bcrypt hash an existing install held (accepted), so current logins keep working -- and a static bearer token (api-token) the sidecar presents. It loads settings.json beside it, the one mergeable file; endpoints is dropped there, and an optional timeZone sets process.env.TZ (assignments cannot set env). - The sidecar's runtime config is no longer merged; it carries the token. - Directories are placed (state, data), the route binds into state. - Image pinned to 5.0.7 (a649dd71), what ace runs; the old pin was 5.0.6. - deployFlows asks for API v2: v1 answers 204 with no body, which the client tried to parse as JSON. Verified: catalogue tests pass against this tree. A throwaway 5.0.7 container started with the generated files: anonymous /flows 401, bearer api-token 200, bad token 401, password grant 200/403 with a minted password and with a bcrypt-hash-accepted one; endpoints and timeZone do not reach /settings; timeZone Europe/Brussels overrides TZ=Etc/UTC; v1 deploy 204, v2 deploy answers {rev}.	2026-09-29 23:41:18 +02:00
mesh-admin	8064e5da8f	Merge pull request 'searxng: its settings are a file the mesh writes, not the image's defaults' (#143 ) from feat/searxng-settings-as-a-file into main	2026-09-29 20:45:13 +00:00
jschoubben	63a255c5cb	searxng: bind its route where its state now lives The route binding still named /var/lib/searxng-module, the directory the previous commit placed elsewhere — the host would have written it into a directory nothing declares. Same shape as gitea and nextcloud.	2026-09-29 22:41:56 +02:00
jschoubben	7ad1fbd5c6	searxng: its settings are a file the mesh writes, not the image's defaults The module ran searxng on the image's built-in settings, which serve html only — so the module's own search tool (format=json) was refused by the software it fronts. And there was no way to configure it per machine: the only file settings reach was the sidecar's. settings.yml is now the module's one mergeable file (JSON is YAML): generic defaults in the manifest (json format on, limiter and image proxy off, valkey wired), and whatever differs per machine — base_url, method, autocomplete, suspended times — set as the assignment's settings. The secret key is filled on the machine through ${secret:secret}, so the secrets-in-environment exception and the env file go. Directories are placed. Image pinned to 2026.9.20, what ace runs today (the old pin was older, 2026.9.1). The sidecar's config.json is no longer mergeable: settings merge into every mergeable file of a module, and the sidecar would have received searxng's keys. It only ever read an optional url, which its env already carries. Verified on ace: the pinned image serves html and json from a read-only, root-owned 0600 JSON settings.yml.	2026-09-29 22:33:38 +02:00
jschoubben	67f5f4cffd	Merge pull request 'ca-trust: a machine trusts the mesh's authority because a module put its root there' (#142 ) from feat/ca-trust into main	2026-09-29 14:06:36 +00:00
jschoubben	8797335fbc	ca-trust: a machine trusts the mesh's authority because a module put its root there novox/hq ADR 0147, issue 129. Every internal HTTPS name fails verification on every machine: the certificates are genuine and nothing on a machine has ever been told what issued them. The proxy's fetch answers for the proxy and for nothing else — a browser, git over HTTPS and every module calling another by an internal name read the machine's own trust store. The module requires internal-acme-ca, fetches the root over the mesh's own network (no prior trust to have; that is what this establishes), installs it among the machine's anchors and refreshes the extracted bundles. Being unassigned stops the unit, and stopping it takes the anchor away and refreshes them again. Arch's layout is named out loud: a machine that keeps anchors elsewhere fails visibly rather than writing a file nothing reads.	2026-09-29 15:07:40 +02:00
mesh-admin	53dc108603	Merge pull request 'Remove the network-checker module: it does not do what was decided' (#141 ) from chore/remove-the-network-checker-module into main	2026-09-29 12:43:34 +00:00
jschoubben	ebf5ba2d4c	Remove the network-checker module: it does not do what was decided What was in the catalogue was the first thing I built, not the thing ADR 0146 describes. It dialled raw ports on machine addresses from one hosting form and emitted nothing, so findings would have sat in a file on the machine — the exact thing issue 145 is about. It was never registered, never assigned, and never ran. 0146 says names per hosting form, fetched over TLS with the certificate verified, and machines discovered over the bus. That shares nothing with this but the word checker, so it goes rather than being bent into shape. Recorded as work to be analysed and built deliberately. Connectivity is checked by hand in the meantime, against the services the mesh already runs.	2026-09-29 14:43:25 +02:00
mesh-admin	bbac08a7d2	Merge pull request 'A network-checker module: dial what the mesh claims, from where the callers are' (#140 ) from feat/a-network-checker-module into main	2026-09-29 11:44:37 +00:00
jschoubben	784a5a6514	A network-checker module: dial what the mesh claims, from where the callers are The mesh asserts three things are callable (ADR 0144) — what runs on the same machine, another machine's service exposed to the private network, and another machine's service exposed publicly — and has never checked any of them. The first was broken for eleven hours while the mesh reported every machine healthy. This runs on every machine, on the cadence the mesh already has, in its own container: the same position every other module calls from. Not the host and not the control plane, both of which reach these addresses by paths no ordinary caller uses and would have passed throughout that outage. Its probe is its own endpoint, and that is the point. Declared reachable over the private network like any other service, so it is admitted by exactly the rule that governs every internally-exposed service and fails when that rule is wrong. The tempting target is a service every machine has, and those are the ones never closed — ssh above all — which would have passed while the thing that actually broke was a service exposed to the private network. It resolves before it dials and says which failed, because a name that does not resolve and a port that does not answer have different owners. One failure is not a fault: a machine rebooting is ordinary, so a path is broken after consecutive runs and the count travels with the result. It reports and repairs nothing. novox/hq ADR 0145. Eight tests; the consecutive-failure logic proved by reverting it once. Not yet registered or assigned.	2026-09-29 13:44:16 +02:00
mesh-admin	0c31499fb0	Merge pull request 'Every module names its endpoints, and every route names the one it serves' (#139 ) from feat/modules-name-their-endpoints into main	2026-09-29 09:51:56 +00:00
jschoubben	f118344246	Every module names its endpoints, and every route names the one it serves 75 endpoints across 50 modules, named from what each one is for rather than by a rule: mail's seven protocol ports are smtp, imaps, submission and the rest; unifi's nine are inform, stun, discovery, the two portal ports and syslog; minio's two are s3 and console; the resolver's two are dns-udp and dns-tcp. And 35 route contributions name the endpoint they serve instead of repeating its port. A route and a listen both carried a port and nothing said they were the same thing; now one of them does. gitea's path-level deny rule names neither, because it is a rule about a name rather than an endpoint. novox/hq ADR 0138. The words shipped a release ahead in mesh-controller #138 and #139, and the control plane running today is built from that merge — checked before this was written, because an unknown manifest key is refused and a catalogue using one against an older control plane would stop resolving.	2026-09-29 11:51:39 +02:00
mesh-admin	822df220ab	Merge pull request 'A routed module listens from the mesh, not from anywhere' (#138 ) from fix/a-routed-module-listens-from-the-mesh into main	2026-09-29 00:58:39 +00:00
jschoubben	9eb1265bc8	A routed module listens from the mesh, not from anywhere umami declared its port reachable from anywhere, reasoning that the collection endpoint tracked browsers POST to must be public. That is true of the name and not of the port: both its surfaces are served through the proxy by name, so the port is how the proxy reaches it and nothing else (ADR 0045). Measured, which is how this was found: with the port open to the internet, the dashboard's login page was served over plain HTTP directly on the machine's port, bypassing every rule the proxy applies by path. The route stays exactly as it was, so the collection endpoint keeps working.	2026-09-29 02:54:10 +02:00
mesh-admin	41cfc70b53	Merge pull request 'The resolver declares both protocols it answers on' (#137 ) from fix/the-resolver-declares-both-protocols into main	2026-09-28 22:04:19 +00:00