frugal-iot-server 0.3.8 → 2.0.0

package/package.json

@@ -12,12 +12,14 @@
     "cookie-parser": "^1.4.7",
     "express": "^5.2.1",
     "express-session": "^1.19.0",
-    "frugal-iot-client": "^1.3.14",
-    "frugal-iot-logger": "^1.1.20",
+    "frugal-iot-client": "^2.0.0",
+    "frugal-iot-logger": "^2.0.0",
     "hash-wasm": "^4.12.0",
     "js-yaml": "^4.2.0",
     "morgan": "^1.11.0",
+    "mqtt": "^5.15.2",
     "multer": "^2.1.1",
+    "nodemailer": "^9.0.6",
     "passport": "^0.7.0",
     "passport-local": "^1.0.0",
     "sqlite3": "^5.1.7"
@@ -28,9 +30,12 @@
     "frugal-iot-addorganization": "scripts/addorganization.zsh",
     "frugal-iot-setpassword": "scripts/setpassword.zsh",
     "frugal-iot-diagnostic": "scripts/diagnostic.zsh",
-    "frugal-iot-clearretained": "scripts/clearretained.zsh",
+    "frugal-iot-clearretained": "scripts/clearretained.js",
     "frugal-iot-addbridge-prod": "scripts/addbridge-prod.zsh",
-    "frugal-iot-addbridge-pi": "scripts/addbridge-pi.zsh"
+    "frugal-iot-addbridge-pi": "scripts/addbridge-pi.zsh",
+    "frugal-iot-rebuild-dynsec": "scripts/rebuild-dynsec.js",
+    "frugal-iot-dynsec-init": "scripts/dynsec-init.js",
+    "frugal-iot-resetnode": "scripts/resetnode.js"
   },
   "description": "Frugal IoT client and server",
   "//files": "An allowlist, not an ignore list - anything not named here is never published, so a stray file (a database backup, a credential) cannot leak by default. Check with: npm pack --dry-run",
@@ -38,6 +43,7 @@
     "frugal-iot-server.js",
     "frugal-iot-createdb.sql",
     "config.yaml",
+    "config.d/email.yaml",
     "config.d/logger.yaml",
     "config.d/mqtt.yaml",
     "config.d/server.yaml",
@@ -47,6 +53,7 @@
     "private/",
     "scripts/",
     "extras/mosquitto.conf",
+    "extras/aclfile",
     "extras/mosquitto-bridge.conf.example",
     "extras/frugaliot.service",
     "API.md",
@@ -76,5 +83,5 @@
     "check-files": "node scripts/check-published-files.js"
   },
   "type": "module",
-  "version": "0.3.8"
+  "version": "2.0.0"
 }

package/public/index.html

@@ -167,14 +167,6 @@
 <div class="nav-section">
     <h2>Other examples</h2>
     <div class="box-grid">
-        <!-- The display the Dashboard used before the cards. Kept reachable while people get used
-             to the new one; it will go once nothing needs it. -->
-        <div class="nav-box">
-            <div class="nav-box-background" style="background-image: url('/images/icon-dashboard.png')"></div>
-            <div class="nav-box-content">
-                <a href="/dashboard/index-old.html">Previous dashboard</a>
-            </div>
-        </div>
         <div class="nav-box">
             <div class="nav-box-background" style="background-image: url('/images/icon-dashboard.png')"></div>
             <div class="nav-box-content">
@@ -197,6 +189,14 @@
 </div>
     <script>
       if (typeof navigator !== 'undefined' && 'serviceWorker' in navigator) {
+            // The worker calls skipWaiting(), so a new one can take over a page whose scripts came
+            // from the old one. Reload once to get a consistent set - but not on a first install,
+            // where there was no previous controller and nothing is stale.
+            const hadController = !!navigator.serviceWorker.controller;
+            let reloading = false;
+            navigator.serviceWorker.addEventListener('controllerchange', () => {
+                if (hadController && !reloading) { reloading = true; location.reload(); }
+            });
             navigator.serviceWorker.register('/service-worker.js')
                 .then(reg => console.log('Service Worker registered'))
                 .catch(err => console.log('Service Worker registration failed', err));

package/public/service-worker.js

@@ -1,18 +1,68 @@
 // Changing this version is what makes an already installed PWA fetch the app again instead of
 // serving what it cached. It follows the version of frugal-iot-client this release installs, and
 // "npm run prerelease" sets it - so there is normally no reason to edit it by hand.
-const CACHE_NAME = 'frugal-iot-cache-1.3.14';
+//
+// The suffix is here because urlsToCache below CHANGED without the client version changing. Without
+// it, an installed browser keeps serving the files it already cached - and since the list now covers
+// the dashboard's own code, that means old JS behind freshly fetched HTML. Any edit to the list
+// needs this bumped, or it does not reach anyone who already has the old one.
+const CACHE_NAME = 'frugal-iot-cache-2.0.0';
+/*
+ * Everything the app needs, so that a phone on a poor or expensive link fetches it once.
+ *
+ * The dashboard's OWN code was missing from this list, which was most of the point of having one:
+ * eight files - the entry point, five modules and the stylesheet - were fetched from the network on
+ * every visit while the libraries beside them came from the cache.
+ *
+ * Two rules for anything added here:
+ *
+ * 1. It must return 200 WITHOUT a session. install() rejects the whole cache if any single entry
+ *    fails, so one 404 or one redirect-to-login means this PWA has no cache at all - and the app
+ *    goes on working online, so nothing announces it. /dashboard/*.js and the stylesheet do serve
+ *    unauthenticated; /dashboard/index.html does NOT (it 307s to the login page).
+ * 2. It must not be a session-gated PAGE. Beyond breaking install, a cached /dashboard/index.html
+ *    would be served to a logged-out visitor - which is the "accessing from service worker which
+ *    has /dashboard cached" case admin.js already had to handle.
+ *
+ * Deliberately absent:
+ *   /dashboard/index.html          session-gated, see above
+ *   /node_modules/esptool-js/*     ~1MB, wanted on one screen, and not by the phone users this list
+ *                                  exists for
+ *
+ * Every URL below was checked against a running server. Two entries in index.html's importmap were
+ * not, and are dead: "chart.js" points at dist/Chart.js, which does not exist (the file is
+ * lowercase, and graph.js imports the full path anyway), and "chartjs-adapter-luxon" points into a
+ * package that is not installed at all - its code was copied into core.js instead. Neither is
+ * reachable today; both would 404 the moment somebody used the bare specifier.
+ */
 const urlsToCache = [
+    // The public landing page and the PWA's own furniture
     '/',
     '/index.html',
+    '/manifest.json',
+    '/favicon.ico',
     '/images/icon-192x192.png',
     '/images/icon-512x512.png',
+    // The dashboard: its stylesheet, its entry point, and the modules dashboard.js imports
+    '/dashboard/frugaliot.css',
+    '/dashboard/dashboard.js',
+    '/dashboard/core.js',
+    '/dashboard/widgets.js',
+    '/dashboard/graph.js',
+    '/dashboard/admin.js',
+    '/dashboard/flash.js',
+    '/dashboard/cards.js',
+    // Logging in - the page a visitor lands on when the session has gone
+    '/dashboard/login.html',
+    '/dashboard/login.js',
+    // Libraries, at the paths index.html's importmap and the modules actually use
     '/node_modules/html-element-extended/htmlelementextended.js',
     '/node_modules/mqtt/dist/mqtt.esm.js',
     '/node_modules/js-yaml/dist/js-yaml.mjs',
     '/node_modules/async/dist/async.mjs',
     '/node_modules/csv-parse/dist/esm/index.js',
     '/node_modules/chart.js/dist/chart.js',
+    '/node_modules/@kurkle/color/dist/color.esm.js',   // chart.js needs it; was missing
     '/node_modules/dial-gauge/dial-gauge.js',
     '/node_modules/luxon/src/luxon.js'
 ];
@@ -20,37 +70,36 @@ const urlsToCache = [
 self.addEventListener('install', event => {
     event.waitUntil(
         caches.open(CACHE_NAME)
-            .then(cache => {
-                console.log('Opened cache');
-                return cache.addAll(urlsToCache);
-            })
-    );
-});
-
-self.addEventListener('fetch', event => {
-    event.respondWith(
-        caches.match(event.request)
-            .then(response => {
-                if (response) {
-                    return response;
-                }
-                return fetch(event.request);
-            })
+            .then(cache => Promise.all(urlsToCache.map(url =>
+                // 'reload' bypasses the HTTP cache, which serves /node_modules immutable for a day -
+                // without it a same-day release caches the library it was meant to replace
+                fetch(new Request(url, {cache: 'reload'}))
+                    .then(response => response.ok
+                        ? cache.put(url, response)
+                        : Promise.reject(new Error(url + ' -> ' + response.status))))))
+            // Without this the new worker waits until every tab of the origin is closed at once.
+            // Reloading does not release the old one, so a release can stay invisible for days.
+            .then(() => self.skipWaiting())
     );
 });
 
 // Delete old caches during activation
 self.addEventListener('activate', event => {
-    const cacheWhitelist = [CACHE_NAME];
     event.waitUntil(
-        caches.keys().then(cacheNames => {
-            return Promise.all(
-                cacheNames.map(cacheName => {
-                    if (cacheWhitelist.indexOf(cacheName) === -1) {
-                        return caches.delete(cacheName);
-                    }
-                })
-            );
-        })
+        caches.keys()
+            .then(cacheNames => Promise.all(
+                cacheNames.filter(cacheName => cacheName !== CACHE_NAME)
+                    .map(cacheName => caches.delete(cacheName))))
+            // Take over the pages that are already open, rather than only ones opened from now on
+            .then(() => self.clients.claim())
+    );
+});
+
+self.addEventListener('fetch', event => {
+    event.respondWith(
+        // Scoped to CACHE_NAME: a bare caches.match searches every cache in the origin, so a
+        // leftover older cache answers first and the version bump achieves nothing
+        caches.match(event.request, {cacheName: CACHE_NAME})
+            .then(response => response || fetch(event.request))
     );
 });

package/scripts/addbridge-pi.zsh

@@ -15,9 +15,14 @@
 # Run from the server's own directory, the one holding frugal-iot.db.
 #
 # Usage:
-#   npx --no frugal-iot-addbridge-pi --org <org-id> --host <prod-host> --account <account> [--replace]
+#   npx --no frugal-iot-addbridge-pi <org-id> <prod-host> <account>
 #   scripts/addbridge-pi.zsh --org myfarm --host prod.example.org --account bridge-northfield
 #
+# Both forms work. The positional one is the one to use with npx, because npm swallows any --flag
+# it does not recognise ("Unknown cli config") and passes only the values through, so
+# "npx ... --org myfarm" reaches this script as just "myfarm". Putting "--" before the flags also
+# works, but the positional form is harder to get wrong.
+#
 # The password is asked for rather than passed on the command line, so it does not end up in your
 # shell history. Give it with --password only for an unattended run.
 
@@ -26,12 +31,17 @@ set -euo pipefail
 SCRIPT_NAME=$0
 
 usage() {
-  echo "Usage: ${SCRIPT_NAME} --org <org-id> --host <prod-host> --account <account> [--port N] [--password PW] [--replace]" >&2
-  echo "Example: ${SCRIPT_NAME} --org myfarm --host prod.example.org --account bridge-northfield" >&2
+  echo "Usage: ${SCRIPT_NAME} <org-id> <prod-host> <account> [password]" >&2
+  echo "   or: ${SCRIPT_NAME} --org <org-id> --host <prod-host> --account <account> [--port N] [--password PW] [--replica-token T] [--replace]" >&2
+  echo "Example: ${SCRIPT_NAME} myfarm prod.example.org bridge-northfield" >&2
+  echo "" >&2
+  echo "Through npx, use the positional form: npm swallows unrecognised --flags and passes only" >&2
+  echo "their values on, so '--org myfarm' arrives here as just 'myfarm'." >&2
   exit 1
 }
 
-ORG_ID=""; PROD_HOST=""; ACCOUNT=""; PASSWORD=""; PROD_PORT=8883; REPLACE=false
+ORG_ID=""; PROD_HOST=""; ACCOUNT=""; PASSWORD=""; PROD_PORT=8883; REPLACE=false; REPLICA_TOKEN=""
+POSITIONAL=()
 
 while [[ $# -gt 0 ]]; do
   case "$1" in
@@ -39,13 +49,33 @@ while [[ $# -gt 0 ]]; do
     --host)     PROD_HOST=${2:-}; shift 2 ;;
     --account)  ACCOUNT=${2:-}; shift 2 ;;
     --password) PASSWORD=${2:-}; shift 2 ;;
+    --replica-token) REPLICA_TOKEN=${2:-}; shift 2 ;;
     --port)     PROD_PORT=${2:-}; shift 2 ;;
     --replace)  REPLACE=true; shift ;;
-    *) echo "Error: unexpected argument '$1'" >&2; usage ;;
+    -*) echo "Error: unknown option '$1'" >&2; usage ;;
+    *)  POSITIONAL+=("$1"); shift ;;
   esac
 done
 
-[[ -z "$ORG_ID" || -z "$PROD_HOST" || -z "$ACCOUNT" ]] && usage
+# Fill anything not given as a flag from the positional arguments, in the order the usage line
+# shows. This is what makes the npx form work: npm eats "--org" and hands us a bare "myfarm".
+# Written as "if" rather than "[[ ... ]] && X=Y", whose false case is a non-zero last command and
+# would end the script under "set -e".
+# Fill whichever are still empty, in the order the usage line shows them, consuming the
+# positionals in turn rather than by fixed position - so a half-and-half command line still lands
+# correctly. Done inline, not through a function returning its value: a command substitution runs
+# in a subshell, where the counter would advance and then be thrown away, giving every field the
+# same first positional.
+POS_N=1
+for _field in ORG_ID PROD_HOST ACCOUNT PASSWORD; do
+  if [[ -z "${(P)_field}" ]] && (( POS_N <= ${#POSITIONAL} )); then
+    typeset -g "${_field}"="${POSITIONAL[POS_N]}"
+    POS_N=$((POS_N + 1))
+  fi
+done
+unset _field
+
+if [[ -z "$ORG_ID" || -z "$PROD_HOST" || -z "$ACCOUNT" ]]; then usage; fi
 
 BRIDGE_CONF=/etc/mosquitto/conf.d/frugal-iot-bridge.conf
 
@@ -60,7 +90,8 @@ fi
 
 if [[ -e "$BRIDGE_CONF" && "$REPLACE" != true ]]; then
   echo "Error: ${BRIDGE_CONF} already exists - this Pi is already bridged." >&2
-  echo "Add --replace to overwrite it, or edit it by hand." >&2
+  echo "Add --replace to overwrite it, or edit it by hand. Through npx that flag needs a '--'" >&2
+  echo "ahead of it - 'npx --no frugal-iot-addbridge-pi -- --org ... --replace' - or npm eats it." >&2
   exit 1
 fi
 
@@ -160,5 +191,58 @@ else
   echo "  sudo tail -20 /var/log/mosquitto/mosquitto.log"
   echo "and the state is reported by:  npx --no frugal-iot-diagnostic"
 fi
+# ---------------------------------------------------------------------------------------------
+# Sharing production's logins (SECURITY.md S11).
+#
+# The bridge above relays topics, not accounts, so without this a person registered on production
+# has no account on this Pi's broker - and this Pi is what goes on working when the link is down.
+# With it, the server pulls their logins and permissions on a timer and issues its OWN broker
+# credentials from its own user_secret; nothing derived from a password travels either way.
+#
+# Optional: a bridge is useful without it, so a missing token is not an error.
+if [[ -z "$REPLICA_TOKEN" ]]; then
+  echo -n "Replica token from the production server (blank to skip): "
+  read -r REPLICA_TOKEN
+fi
+
+if [[ -n "$REPLICA_TOKEN" ]]; then
+  # https, and deliberately not asked about: the token is a bearer credential, and over http it
+  # would be readable by anything between here and production.
+  cat > config.d/replica.yaml <<YAML
+# Which production server this Pi takes its logins from, and how often (SECURITY.md S11).
+# Written by frugal-iot-addbridge-pi. The token itself lives in config.d/secrets.yaml, which is
+# never served to a browser - nothing secret may go in this file.
+url: https://${PROD_HOST}
+organizations:
+  - ${ORG_ID}
+intervalSeconds: 900
+YAML
+  # Appended, or the one line replaced: that file holds this server's own secrets too.
+  if grep -q '^replica_token:' config.d/secrets.yaml 2>/dev/null; then
+    python3 - "$REPLICA_TOKEN" <<'PYEOF'
+import io, re, sys
+p = 'config.d/secrets.yaml'
+s = io.open(p, encoding='utf-8').read()
+io.open(p, 'w', encoding='utf-8').write(
+    re.sub(r'^replica_token:.*$', 'replica_token: "%s"' % sys.argv[1], s, count=1, flags=re.M))
+PYEOF
+  else
+    {
+      echo ""
+      echo "# Pulls this Pi's users from the production server named in config.d/replica.yaml."
+      echo "# Issued by frugal-iot-addbridge-prod; re-running that command revokes this one."
+      echo "replica_token: \"${REPLICA_TOKEN}\""
+    } >> config.d/secrets.yaml
+  fi
+  chmod 600 config.d/secrets.yaml
+  echo ""
+  echo "Wrote config.d/replica.yaml and stored the token in config.d/secrets.yaml."
+  echo "Restart the server to start pulling:  sudo systemctl restart frugaliot"
+else
+  echo ""
+  echo "No replica token given - the bridge relays readings, but people registered on production"
+  echo "will not be able to log in on this Pi. Re-run this script with the token to add it."
+fi
+
 echo ""
 echo "The readings this Pi has already recorded stay here - only new ones are relayed."

package/scripts/addbridge-prod.zsh

@@ -196,10 +196,53 @@ sudo systemctl reload mosquitto || {
   echo "  Try: sudo systemctl restart mosquitto" >&2
 }
 
+# ---------------------------------------------------------------------------------------------
+# A token for the Pi to pull this organization's logins with (SECURITY.md S11).
+#
+# The bridge relays topics, not accounts, so without this a person who logs in here has no account
+# on the Pi's broker - and the Pi is the machine that goes on working when the link is down.
+#
+# It reads logins, hashes and permissions for THIS organization and nothing else. Nothing derived
+# from a password travels: the Pi checks logins against the replicated hash and derives its own
+# broker credentials from its own user_secret, so the two brokers issue different passwords for the
+# same person.
+#
+# Done in node rather than sqlite3, because the sqlite3 command-line tool is not installed
+# everywhere the server runs - the same reason scripts/clearretained.js talks MQTT through a library.
+REPLICA_TOKEN=$(node -e '
+const { randomBytes } = require("crypto");
+const sqlite3 = require("sqlite3");
+const [org, site] = process.argv.slice(1);
+const token = randomBytes(32).toString("base64url");
+const db = new sqlite3.Database("./frugal-iot.db", (err) => {
+  if (err) { console.error(err.message); process.exit(1); }
+  db.run(`CREATE TABLE IF NOT EXISTS bridges (org TEXT NOT NULL, site TEXT NOT NULL,
+            token TEXT NOT NULL, created_at INTEGER NOT NULL, last_pull INTEGER,
+            UNIQUE(org, site))`, () => {
+    db.run(`INSERT INTO bridges (org, site, token, created_at) VALUES (?, ?, ?, ?)
+            ON CONFLICT(org, site) DO UPDATE SET token = excluded.token, created_at = excluded.created_at`,
+      [org, site, token, Date.now()], (e) => {
+        if (e) { console.error(e.message); process.exit(1); }
+        process.stdout.write(token);
+        db.close();
+      });
+  });
+});
+' "$ORG_ID" "$SITE") || true
+
+if [[ -z "$REPLICA_TOKEN" ]]; then
+  echo ""
+  echo "Note: could not create a replica token, so the Pi will not be able to share this server's"
+  echo "logins. The broker bridge above is unaffected. Re-run this script to try again."
+fi
+
 echo ""
 echo "Done. On the Pi at site '${SITE}', run:"
 echo ""
-echo "  npx --no frugal-iot-addbridge-pi --org ${ORG_ID} --host $(hostname -f 2>/dev/null || hostname) --account ${ACCOUNT}"
+echo "  npx --no frugal-iot-addbridge-pi ${ORG_ID} <this server's public name> ${ACCOUNT}"
+echo ""
+echo "Positional arguments on purpose: npm swallows any --flag it does not recognise and passes"
+echo "only the value on, so the --org form would arrive at that script as a bare word."
 echo ""
 echo "It will ask for this password:"
 echo ""
@@ -211,5 +254,16 @@ if [[ "$GENERATED" == true ]]; then
   echo "  sudo -u \"\$(stat -c '%U' ${PWFILE})\" mosquitto_passwd -b ${PWFILE} ${ACCOUNT} '<new password>'"
   echo "and use that on the Pi instead."
 fi
-echo "Check the host name above is one the Pi can reach, and that it is the name on the"
-echo "certificate - the Pi verifies it."
+if [[ -n "$REPLICA_TOKEN" ]]; then
+  echo "And this replica token, so people registered here can log in on the Pi as well:"
+  echo ""
+  echo "  ${REPLICA_TOKEN}"
+  echo ""
+  echo "A new one replaces the old, so re-running this script revokes the Pi's previous token."
+  echo ""
+fi
+echo "Fill in the public name yourself - it is deliberately not guessed here, because what this"
+echo "machine calls itself is usually not it. This host answers to \"$(hostname -f 2>/dev/null || hostname)\","
+echo "which is only the right answer if that is also the DNS name the Pi can reach and the name on"
+echo "the TLS certificate. The Pi verifies the certificate against whatever you put here, so a"
+echo "local hostname, or a domain the certificate does not cover, fails to connect."

package/scripts/addorganization.zsh

@@ -190,12 +190,17 @@ echo "Created user '${ORG_ID}' (id=${NEW_ID})"
 # OR IGNORE because permissions has a UNIQUE(id, capability, org) constraint, so a repeat of any of
 # these rows (e.g. on a database where id 1 is also the org's own account) would otherwise abort
 # the whole statement part-way through, leaving the organization with only some of its permissions.
+#
+# WRITE is deliberately NOT given to id 0 "everyone": that row would hand write access to every account
+# on the server, including a self-registered one, which is what can_WRITE exists to prevent.
 sqlite3 "$DB" "
 INSERT OR IGNORE INTO permissions (id, capability, org) VALUES (${NEW_ID}, 'ADMIN', '${ORG_ID}');
 INSERT OR IGNORE INTO permissions (id, capability, org) VALUES (${NEW_ID}, 'READ', '${ORG_ID}');
+INSERT OR IGNORE INTO permissions (id, capability, org) VALUES (${NEW_ID}, 'WRITE', '${ORG_ID}');
 INSERT OR IGNORE INTO permissions (id, capability, org) VALUES (0, 'READ', '${ORG_ID}');
 INSERT OR IGNORE INTO permissions (id, capability, org) VALUES (1, 'ADMIN', '${ORG_ID}');
 INSERT OR IGNORE INTO permissions (id, capability, org) VALUES (1, 'READ', '${ORG_ID}');
+INSERT OR IGNORE INTO permissions (id, capability, org) VALUES (1, 'WRITE', '${ORG_ID}');
 INSERT OR IGNORE INTO permissions (id, capability, org) VALUES (${NEW_ID}, 'OTAUPDATE', '${ORG_ID}');
 "
 echo "Added permissions for organization ${ORG_ID}"

package/scripts/clearretained.js

@@ -0,0 +1,185 @@
+#!/usr/bin/env node
+/*
+ * List, and optionally delete, retained MQTT messages.
+ *
+ * Nodes publish nearly everything retained, so the broker keeps the last value of every topic and
+ * hands it to each new subscriber - which is how a dashboard can show a reading straight away
+ * instead of waiting for the next one. The cost is that a topic published by mistake outlives the
+ * mistake: rename a module, misspell a field, test a node with the wrong id, and that topic stays
+ * on the broker for ever, appearing on every dashboard. Restarting the broker does not clear it and
+ * neither does fixing the node. The only way to remove one is to publish an empty message to that
+ * exact topic, which is what this does.
+ *
+ * Run from the server's own directory, the one holding frugal-iot.db, so that the organization's
+ * broker password can be read from config.d/organizations/.
+ *
+ * Usage:
+ *   npx --no frugal-iot-clearretained '<topic-pattern>'          # list what is retained
+ *   npx --no frugal-iot-clearretained '<topic-pattern>' delete   # delete it
+ *
+ * Quote the pattern, or the shell expands the wildcards before this ever sees them. In MQTT
+ * patterns "+" matches exactly one level and "#" matches the rest:
+ *   'myfarm/#'                          everything the organization holds - look before deleting
+ *   'myfarm/lotus/esp8266-fb94bb/#'     one node
+ *   'myfarm/lotus/+/sht/temperture/#'   a misspelled field, on every node in the project
+ *
+ * "delete" is a bare word rather than "--delete" because npm parses the whole command line of an
+ * "npx" invocation itself: it treats any --flag it does not recognise as an unknown config setting
+ * and passes only the values on, so "--delete" would silently never reach this script and it would
+ * quietly list instead of deleting. "--delete" is still accepted for running it directly.
+ *
+ * This talks to the broker through the "mqtt" library rather than mosquitto_sub and mosquitto_pub,
+ * so it works anywhere the server itself runs. On the production server those commands cannot be
+ * installed at all: its broker came from the mosquitto PPA built for an older Ubuntu, and the
+ * mosquitto-clients in the distribution demand an exactly-matching libmosquitto1, so apt would have
+ * to downgrade the library out from under the running broker.
+ */
+
+import { readFileSync } from 'node:fs';
+import yaml from 'js-yaml';
+import mqtt from 'mqtt';
+
+const SCRIPT = 'frugal-iot-clearretained';
+
+function usage(message) {
+  if (message) console.error(`Error: ${message}`);
+  console.error(`Usage: ${SCRIPT} '<topic-pattern>' [delete] [--host H] [--port N] [--user U] [--password P] [--wait S]`);
+  console.error(`Example: ${SCRIPT} 'myfarm/lotus/+/sht/temperture/#'`);
+  console.error(`         ${SCRIPT} 'myfarm/lotus/+/sht/temperture/#' delete`);
+  process.exit(1);
+}
+
+// ---- arguments ----
+const opts = { host: 'localhost', port: 1883, user: null, password: null, wait: 3 };
+let pattern = null;
+let doDelete = false;
+
+const argv = process.argv.slice(2);
+for (let i = 0; i < argv.length; i++) {
+  const a = argv[i];
+  switch (a) {
+    case '--delete': doDelete = true; break;
+    case '--host': opts.host = argv[++i]; break;
+    case '--port': opts.port = Number(argv[++i]); break;
+    case '--user': opts.user = argv[++i]; break;
+    case '--password': opts.password = argv[++i]; break;
+    case '--wait': opts.wait = Number(argv[++i]); break;
+    default:
+      if (a.startsWith('-')) usage(`unknown option '${a}'`);
+      else if (pattern === null) pattern = a;
+      else if (a === 'delete') doDelete = true;
+      else usage(`unexpected argument '${a}'`);
+  }
+}
+if (!pattern) usage('no topic pattern given');
+
+// A bare "#" would be every topic on the broker, across every organization. Almost always a
+// mistake, and the one case where a slip is unrecoverable, so it is not accepted at all.
+if (pattern === '#' || pattern === '+/#') {
+  console.error(`Error: refusing the pattern '${pattern}' - that is every topic on the broker.`);
+  console.error("Name the organization at least, as in 'myfarm/#'.");
+  process.exit(1);
+}
+
+// ---- credentials ----
+// The broker requires them, and the organization's are in its config file - the same place the
+// server reads them from. The first element of the topic pattern is the organization.
+if (!opts.user) {
+  opts.user = pattern.split('/')[0];
+  const configFile = `config.d/organizations/${opts.user}.yaml`;
+  let parsed;
+  try {
+    parsed = yaml.load(readFileSync(configFile, 'utf8'));
+  } catch (e) {
+    console.error(`Error: cannot read ${configFile} (${e.code || e.message}), so the broker password`);
+    console.error(`for '${opts.user}' cannot be found. Run this from the server's own directory, or`);
+    console.error('give credentials with --user and --password.');
+    process.exit(1);
+  }
+  opts.password = parsed && parsed.mqtt_password;
+  if (!opts.password) {
+    console.error(`Error: no mqtt_password in ${configFile}`);
+    process.exit(1);
+  }
+}
+
+// ---- collect what is retained ----
+console.log(`Looking for retained messages matching '${pattern}' on ${opts.host}:${opts.port} as ${opts.user} ...`);
+
+const client = mqtt.connect(`mqtt://${opts.host}:${opts.port}`, {
+  username: opts.user,
+  password: opts.password,
+  connectTimeout: 5000,
+  // A fresh session every time: we want the retained messages delivered on subscribe, not a
+  // continuation of some earlier one.
+  clean: true,
+});
+
+const topics = new Set();
+
+client.on('error', (err) => {
+  // ECONNREFUSED arrives with an empty message, so fall back to the code - otherwise this prints
+  // "Error:" and nothing, which says neither "wrong password" nor "nothing listening there".
+  console.error(`Error: could not talk to the broker: ${err.message || err.code || err}`);
+  client.end(true);
+  process.exit(1);
+});
+
+client.on('message', (topic, _payload, packet) => {
+  // Only messages the broker had already kept. A node reporting normally while we listen arrives
+  // with the retain flag clear, and clearing that would be removing something nobody asked us to.
+  if (packet.retain) topics.add(topic);
+});
+
+client.on('connect', () => {
+  client.subscribe(pattern, { qos: 0 }, (err) => {
+    if (err) {
+      console.error(`Error: could not subscribe to '${pattern}': ${err.message}`);
+      client.end(true);
+      process.exit(1);
+    }
+    // Retained messages arrive immediately on subscribing, so this only has to cover the round
+    // trip; a busy broker on a slow Pi may want more, hence --wait.
+    setTimeout(finish, opts.wait * 1000);
+  });
+});
+
+async function finish() {
+  const list = [...topics].sort();
+  if (list.length === 0) {
+    console.log('Nothing retained matches that pattern.');
+    client.end();
+    return;
+  }
+  for (const t of list) console.log(`  ${t}`);
+  console.log(`${list.length} retained topic(s).`);
+
+  if (!doDelete) {
+    console.log('');
+    console.log(`Nothing has been changed. To delete these, run the same command again with "delete"`);
+    console.log('as the last word.');
+    client.end();
+    return;
+  }
+
+  // Deleting one means publishing a zero-length retained message to it, which is how MQTT spells
+  // "forget this". At QoS 1 so the broker acknowledges each rather than dropping it under load.
+  console.log(`Deleting ${list.length} retained topic(s) ...`);
+  let failed = 0;
+  for (const t of list) {
+    try {
+      await new Promise((resolve, reject) => {
+        client.publish(t, '', { retain: true, qos: 1 }, (err) => (err ? reject(err) : resolve()));
+      });
+      console.log(`  cleared ${t}`);
+    } catch (e) {
+      console.error(`  FAILED  ${t}: ${e.message}`);
+      failed++;
+    }
+  }
+  console.log('');
+  console.log('Done. Run the same command without "delete" - it should report nothing.');
+  console.log('If a topic comes back, a node is still publishing it: fix or restart the node, then re-run.');
+  // A bridged broker forwards these deletions to the other end, so clearing here clears there too.
+  client.end(false, {}, () => process.exit(failed ? 1 : 0));
+}