frugal-iot-server 0.3.9 → 2.0.1

package/scripts/install-pi.sh

@@ -468,14 +468,93 @@ ok "mosquitto $(mosquitto -h 2>&1 | head -1 | awk '{print $3}' || true)"
 step "Configuring the broker"
 # Two listeners: 1883 for the sensor nodes, 9012 websockets for the browser. Shipped with the
 # server, so it is copied rather than written here.
-SRC_CONF="${INSTALL_DIR}/extras/mosquitto.conf"
-[[ -f "$SRC_CONF" ]] || { echo "Expected ${SRC_CONF} to exist after frugal-iot-init" >&2; exit 1; }
-if cmp -s "$SRC_CONF" /etc/mosquitto/conf.d/frugal-iot.conf 2>/dev/null; then
+# Read the broker configuration from the INSTALLED PACKAGE, not from ${INSTALL_DIR}/extras.
+#
+# frugal-iot-init copies extras/ into the install directory but never overwrites what is already
+# there - it prints "kept ... (DIFFERS from this release)" and leaves it. That is right for a file
+# somebody may have edited, and wrong for this one: it means a security-relevant change to the
+# shipped broker configuration does not reach /etc on an upgrade, however many times this script is
+# re-run. That is how a broker with no acl_file survived several releases.
+#
+# The package's own copy is authoritative, so an upgrade followed by a re-run of this script applies
+# the current configuration. ${INSTALL_DIR}/extras stays as the fallback for an installation whose
+# layout predates this.
+PKG_DIR="${INSTALL_DIR}/node_modules/frugal-iot-server"
+SRC_CONF="${PKG_DIR}/extras/mosquitto.conf"
+[[ -f "$SRC_CONF" ]] || SRC_CONF="${INSTALL_DIR}/extras/mosquitto.conf"
+[[ -f "$SRC_CONF" ]] || { echo "Expected extras/mosquitto.conf in ${PKG_DIR} or ${INSTALL_DIR}" >&2; exit 1; }
+
+# The ACL file goes in FIRST, because the configuration copied below names it and mosquitto will not
+# start if it is missing. Owned by mosquitto, mode 600: the broker reads it after dropping
+# privileges, and 2.0.21 warns that a file it does not own, or one that is world readable, will be
+# refused by a future version. Same rule as the password file below.
+SRC_ACL="${PKG_DIR}/extras/aclfile"
+[[ -f "$SRC_ACL" ]] || SRC_ACL="${INSTALL_DIR}/extras/aclfile"
+if [[ -f "$SRC_ACL" ]]; then
+  if cmp -s "$SRC_ACL" /etc/mosquitto/aclfile 2>/dev/null; then
+    skip "/etc/mosquitto/aclfile already current"
+  else
+    sudo_ install -o mosquitto -g mosquitto -m 600 "$SRC_ACL" /etc/mosquitto/aclfile
+    ok "access control list installed at /etc/mosquitto/aclfile"
+  fi
+else
+  echo "Expected extras/aclfile in ${PKG_DIR} or ${INSTALL_DIR}" >&2; exit 1
+fi
+
+# The dynamic security plugin. Its state file has to exist before the configuration naming it is
+# installed, or the broker will not start - same ordering as the ACL above.
+#
+# The plugin path varies by distribution, so it is found rather than assumed: Debian and Raspberry Pi
+# OS ship it as /usr/lib/<arch>/mosquitto_dynamic_security.so, others use a mosquitto/ subdirectory.
+DYNSEC_SO=""
+for cand in /usr/lib/*/mosquitto_dynamic_security.so /usr/lib/mosquitto_dynamic_security.so             /usr/lib/*/mosquitto/mosquitto_dynamic_security.so /usr/lib/mosquitto/mosquitto_dynamic_security.so; do
+  [[ -f "$cand" ]] && { DYNSEC_SO="$cand"; break; }
+done
+DYNSEC_JSON=/var/lib/mosquitto/dynamic-security.json
+if [[ -z "$DYNSEC_SO" ]]; then
+  warn "mosquitto's dynamic security plugin was not found - per-user broker accounts will not work."
+  warn "  Looked in /usr/lib. The broker will still run on the organization passwords."
+elif [[ -f "$DYNSEC_JSON" ]]; then
+  skip "dynamic security already initialised at ${DYNSEC_JSON}"
+else
+  # dynsec init asks for the admin password twice on stdin. The password is generated here and kept
+  # in the server's own config.d/secrets.yaml, which is never served to a browser.
+  DYNSEC_PW="$(randpw)"
+  if printf '%s\n%s\n' "$DYNSEC_PW" "$DYNSEC_PW"        | sudo_ mosquitto_ctrl dynsec init "$DYNSEC_JSON" frugal-admin >/dev/null 2>&1      && [[ -s "$DYNSEC_JSON" ]]; then
+    # Written after dropping privileges, so owned by mosquitto like the password and ACL files
+    sudo_ chown mosquitto:mosquitto "$DYNSEC_JSON"
+    sudo_ chmod 600 "$DYNSEC_JSON"
+    {
+      echo ""
+      echo "# The broker account the server uses to create and remove other accounts, over"
+      echo "# \$CONTROL/dynamic-security/v1. Created by install-pi.sh."
+      echo "dynsec_admin_user: \"frugal-admin\""
+      echo "dynsec_admin_password: \"${DYNSEC_PW}\""
+    } >> "${INSTALL_DIR}/config.d/secrets.yaml"
+    chmod 600 "${INSTALL_DIR}/config.d/secrets.yaml"
+    ok "dynamic security initialised; admin credential saved to config.d/secrets.yaml"
+  else
+    warn "mosquitto_ctrl dynsec init failed - continuing without it"
+    sudo_ rm -f "$DYNSEC_JSON"
+    DYNSEC_SO=""
+  fi
+fi
+
+# The shipped configuration carries a placeholder for the plugin path, because it differs per
+# distribution. Substitute it here - or comment the plugin out entirely if there is no plugin.
+TMP_CONF="$(mktemp)"
+if [[ -n "$DYNSEC_SO" ]]; then
+  sed "s|^plugin PLUGIN_PATH_SET_BY_INSTALLER|plugin ${DYNSEC_SO}|" "$SRC_CONF" > "$TMP_CONF"
+else
+  sed -e "s|^plugin PLUGIN_PATH_SET_BY_INSTALLER|#plugin (not installed)|"       -e "s|^plugin_opt_config_file|#plugin_opt_config_file|" "$SRC_CONF" > "$TMP_CONF"
+fi
+if cmp -s "$TMP_CONF" /etc/mosquitto/conf.d/frugal-iot.conf 2>/dev/null; then
   skip "/etc/mosquitto/conf.d/frugal-iot.conf already current"
 else
-  sudo_ cp "$SRC_CONF" /etc/mosquitto/conf.d/frugal-iot.conf
+  sudo_ cp "$TMP_CONF" /etc/mosquitto/conf.d/frugal-iot.conf
   ok "configuration copied to /etc/mosquitto/conf.d/frugal-iot.conf"
 fi
+rm -f "$TMP_CONF"
 # The broker refuses to start if the password file it is told about does not exist. It has to belong
 # to the mosquitto user, because both the broker and mosquitto_passwd warn unless the file belongs to
 # whoever opened it - and mosquitto_passwd writes a temporary file beside it, so the directory has to

package/scripts/migrate-permissions-project.sql

@@ -0,0 +1,21 @@
+-- Add permissions.project to a database created before it existed.
+--
+-- Run only when the column is absent - scripts/init.zsh checks. Rebuilding the table rather than
+-- ALTER TABLE ADD COLUMN because the UNIQUE constraint has to change too, and SQLite cannot alter a
+-- constraint. Wrapped in a transaction so a failure leaves the old table in place.
+--
+-- Existing rows get project = '', meaning organization-wide, so every permission keeps behaving
+-- exactly as it did and nothing needs re-granting.
+BEGIN;
+CREATE TABLE `permissions_new` (
+  `id` INTEGER NOT NULL,
+  `capability` TEXT NOT NULL,
+  `org` TEXT NOT NULL,
+  `project` TEXT NOT NULL DEFAULT '',
+  UNIQUE(`id`, `capability`, `org`, `project`)
+);
+INSERT INTO `permissions_new` (`id`, `capability`, `org`, `project`)
+  SELECT `id`, `capability`, `org`, '' FROM `permissions`;
+DROP TABLE `permissions`;
+ALTER TABLE `permissions_new` RENAME TO `permissions`;
+COMMIT;

package/scripts/not-published.txt

@@ -25,3 +25,8 @@ test/**
 # --- Placeholders ---
 # Keeps the ota directory present in a clone; a real installation gets one from frugal-iot-init
 ota/README.md
+
+# Describes how the security works, and would be useful in an installation - but it ends with an
+# open-issues section listing what is currently exploitable, which must not ship to everyone who
+# installs the package. Published by hand, without that section.
+SECURITY.md

package/scripts/prerelease.zsh

@@ -4,6 +4,18 @@
 # afterwards. Run it, read what it says, then publish:
 #
 #   npm run prerelease
+#   zsh scripts/prerelease.zsh --release-version 2.1.0
+#   zsh scripts/prerelease.zsh -q
+#
+# -q (--quiet) prints only findings and changes, so a clean run prints nothing at all. That is what
+# the release script uses; run it without -q to see each check confirm itself.
+#
+# --release-version says which version this release is about to publish everywhere, and is what the
+# release script in frugal-iot-demo passes. Without it, "requires a version nobody has published"
+# is a blocker, because that is what it means on an ordinary day. During a release it is the normal
+# state of affairs - the logger and client are about to be published at that version and have not
+# been yet - so with it, a range that only the version being released satisfies is reported and
+# allowed, and CACHE_NAME is set to that version rather than to whatever is on npm today.
 #
 # It checks the sensor schema and copies it into the examples that ship with frugal-iot-logger, sets
 # the service worker's cache version, and looks for the package being wired to a checkout on this
@@ -21,27 +33,52 @@
 
 set -euo pipefail
 
+RELEASE_VERSION=""
+QUIET=0
+while (( $# )); do
+  case "$1" in
+    --release-version) RELEASE_VERSION="${2:-}"; shift 2 || true ;;
+    --release-version=*) RELEASE_VERSION="${1#*=}"; shift ;;
+    -q|--quiet) QUIET=1; shift ;;
+    -h|--help) sed -n '2,34p' "$0" | sed 's/^# \?//'; exit 0 ;;
+    *) print -u2 "Unknown option: $1 (try --release-version <version>, -q, or -h)"; exit 2 ;;
+  esac
+done
+
+# A check confirming itself, as opposed to a finding or a change: silent under -q
+say() { (( QUIET )) || print -r -- "$@" }
+
+# Passed on to the scripts that take the same flag
+QARG=()
+(( QUIET )) && QARG=(-q)
+
 HERE="${0:A:h:h}"                     # The frugal-iot-server checkout this script is in
 SCHEMA="${HERE}/config.d/schema"
 
+# Does the version being released satisfy this range? Only asked when --release-version was given.
+satisfied_by_release() {
+  [[ -n "$RELEASE_VERSION" ]] || return 1
+  node -e "process.exit(require('semver').satisfies('${RELEASE_VERSION}', process.argv[1]) ? 0 : 1)" "$1" 2>/dev/null
+}
+
 cd "$HERE"
 
 BLOCKERS=()   # never right in a published package - this script exits non-zero for these
 WARNINGS=()   # probably worth doing something about, but yours to judge
 
-echo "=== Checking ${SCHEMA} ==="
-node scripts/check-schema.js config.d/schema || true
+say "=== Checking ${SCHEMA} ==="
+node scripts/check-schema.js "${QARG[@]}" config.d/schema || true
 
-echo
-echo "=== Copying the schema into the frugal-iot-logger examples ==="
-zsh scripts/copy-schema-to-examples.zsh
+say
+say "=== Copying the schema into the frugal-iot-logger examples ==="
+zsh scripts/copy-schema-to-examples.zsh "${QARG[@]}"
 
 # ---- Is this package wired to a checkout on this machine? ----
 # Developing the server, logger and client together means pointing the server at sibling checkouts,
 # and every way of doing that is invisible once you have got used to it. Published, each one either
 # breaks every install outright or ships code nobody else has.
-echo
-echo "=== Checking nothing is wired to a local checkout ==="
+say
+say "=== Checking nothing is wired to a local checkout ==="
 
 # 1. "file:" or "link:" dependencies - these would make "npm install frugal-iot-server" fail for
 #    everybody, because the path they name does not exist on anyone else's machine
@@ -59,7 +96,7 @@ if [[ -n "$LOCALDEPS" ]]; then
   print -r -- "$LOCALDEPS" | sed 's/^/  /'
   BLOCKERS+=("package.json names a dependency by path - publishing that breaks every install. Put the version range back.")
 else
-  echo "  package.json names no dependencies by path"
+  say "  package.json names no dependencies by path"
 fi
 
 # 2. npm link - node_modules/<pkg> being a symlink means what you have been testing is your
@@ -74,8 +111,9 @@ if (( ${#LINKED} )); then
   for l in $LINKED; do echo "  linked: $l"; done
   echo "  What you have been running is that checkout, not the published package."
   echo "  Publish the linked package first, then require the new version here."
+  WARNINGS+=("node_modules links to a checkout (${(j:, :)LINKED}) - what the tests exercised is that checkout, not the published package.")
 else
-  echo "  node_modules holds published packages, not links to checkouts"
+  say "  node_modules holds published packages, not links to checkouts"
 fi
 
 # 3. The development alternatives inside the source, which are switched by editing rather than by
@@ -83,12 +121,12 @@ fi
 if grep -qE '^\s*import .*from\s+"\.\./frugal-iot-logger' frugal-iot-server.js 2>/dev/null; then
   BLOCKERS+=("frugal-iot-server.js is importing the logger from ../frugal-iot-logger - comment that line out and uncomment the \"frugal-iot-logger\" one.")
 else
-  echo "  frugal-iot-server.js imports the logger as a package, not by path"
+  say "  frugal-iot-server.js imports the logger as a package, not by path"
 fi
 if grep -qE '^\s*(htmldir|nodemodulesdir):\s*\.\./' config.d/server.yaml 2>/dev/null; then
   BLOCKERS+=("config.d/server.yaml points htmldir or nodemodulesdir at ../frugal-iot-client - that is the development setting and ships to everyone who installs.")
 else
-  echo "  config.d/server.yaml points at ./node_modules, not at a sibling checkout"
+  say "  config.d/server.yaml points at ./node_modules, not at a sibling checkout"
 fi
 
 # ---- Are the versions this requires actually available? ----
@@ -96,8 +134,8 @@ fi
 # on a Pi as well as here, and nothing in the repo shows it. Asking for one that is published but
 # not the newest is a lesser problem - a fresh install resolves to the newest anyway, but an
 # existing one is free to stay where it is, so your changes reach nobody who already has it.
-echo
-echo "=== Checking the versions this requires have been published ==="
+say
+say "=== Checking the versions this requires have been published ==="
 
 # Highest published version of $1 satisfying range $2, or empty if none - and it prints nothing and
 # exits 1 when nothing matches, which is an answer rather than a failure, hence the "|| true"
@@ -110,15 +148,19 @@ for p in frugal-iot-logger frugal-iot-client; do
   RANGE=$(node -e "console.log(require('./package.json').dependencies['$p'] || '')")
   if [[ -z "$RANGE" ]]; then continue; fi
   if ! LATEST=$(npm view "$p" version 2>/dev/null); then
-    echo "  $p: could not ask npm (offline?) - requires ${RANGE}, check it yourself"
+    say "  $p: could not ask npm (offline?) - requires ${RANGE}, check it yourself"
     continue
   fi
   MATCH=$(published_match "$p" "$RANGE")
-  if [[ -z "$MATCH" ]]; then
-    echo "  $p: requires ${RANGE}, but the newest published is ${LATEST}"
+  if [[ -z "$MATCH" ]] && satisfied_by_release "$RANGE"; then
+    # Mid-release: this range was raised to the version being published, and $p has not been
+    # published at it yet. Expected, and the publishing step is about to deal with it.
+    say "  $p: requires ${RANGE}, awaiting the ${RELEASE_VERSION} publish (newest so far is ${LATEST})"
+  elif [[ -z "$MATCH" ]]; then
+    say "  $p: requires ${RANGE}, but the newest published is ${LATEST}"
     BLOCKERS+=("Nothing published satisfies ${p}@${RANGE} (newest is ${LATEST}) - publish ${p} first, or every \"npm install frugal-iot-server\" fails.")
   elif [[ "$MATCH" != "$LATEST" ]]; then
-    echo "  $p: requires ${RANGE} -> ${MATCH}, but ${LATEST} is published"
+    say "  $p: requires ${RANGE} -> ${MATCH}, but ${LATEST} is published"
     WARNINGS+=("${p}@${RANGE} resolves to ${MATCH}, not the newest published ${LATEST} - bump the range if you meant installs to pick up ${LATEST}.")
   else
     # The range allows the newest, but if its floor is older then an existing install can sit on
@@ -126,10 +168,10 @@ for p in frugal-iot-logger frugal-iot-client; do
     FLOOR=${RANGE#[\^~>=]}
     FLOOR=${FLOOR#=}
     if [[ -n "$FLOOR" && "$FLOOR" != "$LATEST" ]]; then
-      echo "  $p: requires ${RANGE}, newest published ${LATEST} (an existing install may stay on ${FLOOR})"
+      say "  $p: requires ${RANGE}, newest published ${LATEST} (an existing install may stay on ${FLOOR})"
       WARNINGS+=("${p} requires ${RANGE}, so an install that already has ${FLOOR} is not obliged to move to ${LATEST}. Raise the range to ^${LATEST} if this release needs it.")
     else
-      echo "  $p: requires ${RANGE}, newest published ${LATEST} - in step"
+      say "  $p: requires ${RANGE}, newest published ${LATEST} - in step"
     fi
   fi
 done
@@ -139,27 +181,33 @@ done
 # installed PWA fetch it again. Left behind, people keep running the client they already had, which
 # looks exactly like a release that did nothing. It tracks the client version, so set it from
 # whichever published client this release will actually resolve to.
-echo
-echo "=== Checking the service worker's cache version ==="
+say
+say "=== Checking the service worker's cache version ==="
 SW=public/service-worker.js
 CLIENT_RANGE=$(node -e "console.log(require('./package.json').dependencies['frugal-iot-client'] || '')")
 if [[ ! -f "$SW" ]]; then
-  echo "  no ${SW} here"
+  say "  no ${SW} here"
 elif [[ -z "$CLIENT_RANGE" ]]; then
-  echo "  package.json has no frugal-iot-client dependency to match against"
+  say "  package.json has no frugal-iot-client dependency to match against"
 else
   SW_VERSION=$(sed -n "s/^const CACHE_NAME = 'frugal-iot-cache-\([^']*\)'.*/\1/p" "$SW" | head -1)
   CLIENT_LATEST=$(npm view frugal-iot-client version 2>/dev/null || true)
   CLIENT_WANTED=$(published_match frugal-iot-client "$CLIENT_RANGE")
+  # Mid-release the client this ships with is the one about to be published, not the newest on npm
+  # today, so follow that instead - otherwise CACHE_NAME would be set back to last month's version.
+  if satisfied_by_release "$CLIENT_RANGE"; then
+    CLIENT_WANTED="$RELEASE_VERSION"
+    CLIENT_LATEST="$RELEASE_VERSION"
+  fi
   if [[ -z "$SW_VERSION" ]]; then
-    echo "  could not find a CACHE_NAME line of the form frugal-iot-cache-<version> in ${SW}"
+    say "  could not find a CACHE_NAME line of the form frugal-iot-cache-<version> in ${SW}"
     WARNINGS+=("Could not read CACHE_NAME from ${SW} - check by hand that it changes when the client does.")
   elif [[ -z "$CLIENT_WANTED" ]]; then
-    echo "  CACHE_NAME says ${SW_VERSION}, and nothing published satisfies ${CLIENT_RANGE}"
+    say "  CACHE_NAME says ${SW_VERSION}, and nothing published satisfies ${CLIENT_RANGE}"
     BLOCKERS+=("Cannot set CACHE_NAME: no published frugal-iot-client satisfies ${CLIENT_RANGE}.")
   else
     if [[ "$SW_VERSION" == "$CLIENT_WANTED" ]]; then
-      echo "  CACHE_NAME is ${SW_VERSION}, matching the client this release installs"
+      say "  CACHE_NAME is ${SW_VERSION}, matching the client this release installs"
     else
       # An in-place edit rather than a warning: there is only one right answer, and a stale cache
       # name is invisible until somebody's browser keeps serving them last month's dashboard
@@ -174,16 +222,19 @@ else
 fi
 
 # ---- What would and would not be published ----
-echo
-echo "=== Checking what the package would contain ==="
-if ! node scripts/check-published-files.js; then
+say
+say "=== Checking what the package would contain ==="
+if ! FILESOUT=$(node scripts/check-published-files.js 2>&1); then
+  print -r -- "$FILESOUT"
   BLOCKERS+=("Something git ignores would be published - see above.")
+else
+  say "$FILESOUT"
 fi
 
-echo
-echo "=== Reminders ==="
-echo "  - Is the version in package.json the one you mean to publish?  $(node -e 'console.log(require("./package.json").version)')"
-echo "  - Nothing here is committed or published - do that yourself."
+say
+say "=== Reminders ==="
+say "  - Is the version in package.json the one you mean to publish?  $(node -e 'console.log(require("./package.json").version)')"
+say "  - Nothing here is committed or published - do that yourself."
 
 if (( ${#WARNINGS} )); then
   echo

package/scripts/rebuild-dynsec.js

@@ -0,0 +1,190 @@
+#!/usr/bin/env node
+/*
+ * Make the broker's dynamic-security state match this server's database, or just report where it
+ * differs.
+ *
+ *   npx --no frugal-iot-rebuild-dynsec          apply
+ *   npx --no frugal-iot-rebuild-dynsec check    report only, change nothing
+ *
+ * Run from the server's own directory. Everything it writes is either stored in the database or
+ * derivable from it, so it is safe to re-run: after restoring a database, after a release that adds
+ * a rule, or when something looks wrong. "check" is what scripts/diagnostic.zsh calls.
+ *
+ * "check", not "--check": npm parses the whole command line itself and swallows any --flag it does
+ * not recognise, so "npx --no frugal-iot-rebuild-dynsec --check" arrives here with no arguments and
+ * would silently APPLY instead of reporting. That is the npx trap in claude.md, and this command hit
+ * it - "--check" is still accepted for a direct "node scripts/rebuild-dynsec.js --check".
+ */
+
+import sqlite3 from 'sqlite3';
+import { MqttLogger } from 'frugal-iot-logger';
+import { dynsecConnect } from '../lib/dynsec.js';
+import {
+  readScopes, readPublics, readProjects, readUserRows,
+  applyRolesAndGroups, applyUser, applyNode, applyLogger, applyOrgAdmin, checkRolesAndGroups,
+} from '../lib/dynsec-sync.js';
+import { names } from '../lib/dynsec-plan.js';
+
+const userClientName = names.userClient;
+
+const ARGS = process.argv.slice(2);
+const CHECK = ARGS.includes('check') || ARGS.includes('--check');
+const DB = './frugal-iot.db';
+
+function fail(msg, code = 1) {
+  console.error(msg);
+  process.exit(code);
+}
+
+// The same reader the server uses, so this sees exactly the configuration the server sees -
+// config.yaml plus config.d, including config.d/secrets.yaml.
+//
+// It logs a line per file it reads, which is fine at server startup and noise in a command whose
+// output scripts/diagnostic.zsh includes - so it is quietened for the duration of the read only.
+const realLog = console.log;
+console.log = () => {};
+new MqttLogger().readYamlConfig('.', (err, config) => {
+  console.log = realLog;
+  if (err) return fail(`Could not read the configuration: ${err.message}`);
+  const orgs = Object.keys((config && config.organizations) || {});
+  const userSecret = config.secrets && config.secrets.user_secret;
+  if (!CHECK && !userSecret) {
+    return fail('No user_secret in config.d/secrets.yaml - run: npx --no frugal-iot-init');
+  }
+
+  const db = new sqlite3.Database(DB, sqlite3.OPEN_READONLY, (dberr) => {
+    if (dberr) return fail(`Could not open ${DB}: ${dberr.message}. Run this from the server's own directory.`);
+
+    dynsecConnect(config, (cerr, dynsec) => {
+      if (cerr) {
+        // Being unable to reach the plugin is a normal state on a broker that has none, so say what
+        // it means rather than only what failed.
+        console.error(`Cannot reach the dynamic security plugin: ${cerr.message}`);
+        console.error('If this broker has no plugin, per-user accounts are unavailable and that is');
+        console.error('all this means. frugal-iot-diagnostic reports which case you are in.');
+        process.exit(2);
+      }
+
+      readScopes(db, orgs, (e1, scopes) => {
+        if (e1) return fail(e1.message);
+        readPublics(db, (e2, publics) => {
+          if (e2) return fail(e2.message);
+         readProjects(db, (e2b, projects) => {
+          if (e2b) return fail(e2b.message);
+
+          if (CHECK) {
+            checkRolesAndGroups(dynsec, scopes, publics, projects, (e3, differences) => {
+              if (e3) return fail(e3.message);
+              db.all('SELECT id, username FROM users WHERE id > 0 AND username IS NOT NULL', [], (e4, users) => {
+                if (e4) return fail(e4.message);
+                dynsec.listClients((e5, clients) => {
+                  if (e5) return fail(e5.message);
+                  for (const u of users) {
+                    const want = userClientName(u.username);
+                    if (!clients.includes(want)) differences.push(`client missing: ${want}`);
+                  }
+                  for (const org of orgs) {
+                    const want = names.loggerClient(org);
+                    if (!clients.includes(want)) differences.push(`client missing: ${want}`);
+                  }
+                  report(differences);
+                  dynsec.end(() => process.exit(differences.length ? 3 : 0));
+                });
+              });
+            });
+            return;
+          }
+
+          applyRolesAndGroups(dynsec, scopes, publics, projects, (e3) => {
+            if (e3) return fail(`Setting up roles and groups: ${e3.message}`);
+            console.log(`Roles and groups for ${scopes.length} organization/project scope(s), ` +
+                        `${projects.length} project(s), ${publics.length} publicly readable`);
+            syncUsers(db, dynsec, userSecret, (e4, n) => {
+              if (e4) return fail(`Syncing users: ${e4.message}`);
+              console.log(`${n} user account(s)`);
+              syncNodes(db, dynsec, (e5, m) => {
+                if (e5) return fail(`Syncing nodes: ${e5.message}`);
+                console.log(`${m} node account(s)`);
+                syncLoggers(dynsec, orgs, userSecret, (e6, k) => {
+                  if (e6) return fail(`Syncing logger accounts: ${e6.message}`);
+                  console.log(`${k} logger account(s)`);
+                  syncOrgAdmins(dynsec, orgs, userSecret, (e7, j) => {
+                    if (e7) return fail(`Syncing admin accounts: ${e7.message}`);
+                    console.log(`${j} server admin account(s)`);
+                    dynsec.end(() => process.exit(0));
+                  });
+                });
+              });
+            });
+          });
+         });
+        });
+      });
+    });
+  });
+});
+
+function report(differences) {
+  if (!differences.length) {
+    console.log('The broker matches the database.');
+  } else {
+    console.log(`${differences.length} difference(s) between the database and the broker:`);
+    for (const d of differences) console.log(`  ${d}`);
+    console.log('Run without --check to correct them.');
+  }
+}
+
+// One at a time on purpose: a Pi Zero has one core, there is no hurry, and a batch that fails
+// half-way is harder to reason about than a sequence that stops.
+function syncUsers(db, dynsec, userSecret, cb) {
+  db.all('SELECT id, username, hashed_password FROM users WHERE id > 0 AND username IS NOT NULL', [], (err, users) => {
+    if (err) return cb(err);
+    let i = 0;
+    const next = () => {
+      if (i >= users.length) return cb(null, users.length);
+      const u = users[i++];
+      readUserRows(db, u.id, (e, rows) => {
+        if (e) return cb(e);
+        applyUser(dynsec, { username: u.username, hashedPassword: u.hashed_password, rows, userSecret },
+          (e2) => (e2 ? cb(e2) : next()));
+      });
+    };
+    next();
+  });
+}
+
+function syncLoggers(dynsec, orgs, userSecret, cb) {
+  let i = 0;
+  const next = () => {
+    if (i >= orgs.length) return cb(null, orgs.length);
+    applyLogger(dynsec, { org: orgs[i++], userSecret }, (e) => (e ? cb(e) : next()));
+  };
+  next();
+}
+
+function syncOrgAdmins(dynsec, orgs, userSecret, cb) {
+  let i = 0;
+  const next = () => {
+    if (i >= orgs.length) return cb(null, orgs.length);
+    applyOrgAdmin(dynsec, { org: orgs[i++], userSecret }, (e) => (e ? cb(e) : next()));
+  };
+  next();
+}
+
+function syncNodes(db, dynsec, cb) {
+  // The nodes table arrives with S6; until then there is nothing to do and that is not an error.
+  db.all("SELECT name FROM sqlite_master WHERE type='table' AND name='nodes'", [], (err, t) => {
+    if (err) return cb(err);
+    if (!t.length) return cb(null, 0);
+    db.all('SELECT org, project, nodeid, password, lora FROM nodes', [], (e, nodes) => {
+      if (e) return cb(e);
+      let i = 0;
+      const next = () => {
+        if (i >= nodes.length) return cb(null, nodes.length);
+        const n = nodes[i++];
+        applyNode(dynsec, { ...n, lora: !!n.lora }, (e2) => (e2 ? cb(e2) : next()));
+      };
+      next();
+    });
+  });
+}

package/scripts/resetnode.js

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+/*
+ * Forget a node, so it can enrol again.
+ *
+ *   npx --no frugal-iot-resetnode <org> <project> <nodeid>
+ *
+ * Run from the server's own directory.
+ *
+ * A node proves it is itself by presenting the credential it already holds, so only the node can be
+ * issued a new one - otherwise anyone with the organization's enrolment secret could take over any
+ * node by quoting its id, which is public (it comes from the chip's MAC). The cost of that is this
+ * command: a node whose filesystem has been erased can prove nothing, and somebody has to say "yes,
+ * that really is my node".
+ *
+ * Rare in the field. Common while developing, where erasing flash is routine - two ways to avoid it
+ * there are to keep using the older configure_mqtt(host, user, password) form, which does not enrol
+ * at all, or to give a development organization its own looser policy.
+ *
+ * Positional arguments, no flags: npm swallows any --flag it does not recognise, so a flag would
+ * arrive here as nothing at all. See the npx note in claude.md.
+ */
+
+import sqlite3 from 'sqlite3';
+import { MqttLogger } from 'frugal-iot-logger';
+import { forgetNode } from '../lib/enrol.js';
+import { dropNode } from '../lib/dynsec-server.js';
+
+const [org, project, nodeid] = process.argv.slice(2);
+if (!org || !project || !nodeid) {
+  console.error('Usage: npx --no frugal-iot-resetnode <org> <project> <nodeid>');
+  console.error('Example: npx --no frugal-iot-resetnode myfarm lotus esp32-abc123');
+  process.exit(1);
+}
+
+const realLog = console.log;
+console.log = () => {};                       // the config reader logs a line per file
+new MqttLogger().readYamlConfig('.', (err, config) => {
+  console.log = realLog;
+  if (err) {
+    console.error(`Could not read the configuration: ${err.message}`);
+    process.exit(1);
+  }
+  const db = new sqlite3.Database('./frugal-iot.db', (dberr) => {
+    if (dberr) {
+      console.error(`Could not open ./frugal-iot.db: ${dberr.message}`);
+      console.error("Run this from the server's own directory.");
+      process.exit(1);
+    }
+    forgetNode(db, org, project, nodeid, (ferr, changes) => {
+      if (ferr) { console.error(ferr.message); process.exit(1); }
+      if (!changes) {
+        console.log(`No enrolled node ${org}/${project}/${nodeid} - nothing to forget.`);
+        console.log('It can enrol as soon as it asks. Check the spelling if you expected one.');
+        process.exit(0);
+      }
+      console.log(`Forgot ${org}/${project}/${nodeid} - it will enrol again on its next attempt.`);
+      // Remove the broker account too, so nothing is left that the database no longer knows about.
+      // Best effort: enrolling recreates it, and a broker that cannot be reached now is reported by
+      // frugal-iot-diagnostic as drift.
+      dropNode(config, org, project, nodeid, (derr) => {
+        if (derr) {
+          console.log(`The broker account was not removed: ${derr.message}`);
+          console.log('Harmless - re-enrolling replaces it. frugal-iot-rebuild-dynsec tidies up.');
+        }
+        db.close(() => process.exit(0));
+      });
+    });
+  });
+});