frugal-iot-server 0.3.9 → 2.0.0

package/scripts/addbridge-pi.zsh

@@ -32,7 +32,7 @@ SCRIPT_NAME=$0
 
 usage() {
   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] [--replace]" >&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
@@ -40,7 +40,7 @@ usage() {
   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
@@ -49,6 +49,7 @@ 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: unknown option '$1'" >&2; usage ;;
@@ -190,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,6 +196,46 @@ 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 ""
@@ -214,6 +254,14 @@ 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
+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"

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/diagnostic.zsh

@@ -217,8 +217,19 @@ BROKER_URL=$(grep -h '^broker:' config.d/mqtt.yaml 2>/dev/null | awk '{print $2}
 BROKER_HOST=${${${BROKER_URL#*://}%%/*}%%:*}
 if [[ -n "$BROKER_HOST" ]]; then
   item "broker host: $BROKER_HOST"
-  if have getent && BROKER_IP=$(getent hosts "$BROKER_HOST" 2>/dev/null | head -1 | awk '{print $1}') && [[ -n "$BROKER_IP" ]]; then
-    item "  resolves to $BROKER_IP from this machine"
+  # EVERY address, both families. A name that also offers an IPv6 address is the one way this has
+  # actually bitten: a client may prefer the AAAA, and if that address is transient - a global
+  # prefix from the router coming and going - connections stall while the name still resolves and
+  # nothing is wrong at either end. Seen on the test Pi, where avahi registered and withdrew a
+  # global IPv6 address every few minutes; `journalctl -u avahi-daemon` is where that shows.
+  BROKER_ADDRS=""
+  have getent && BROKER_ADDRS=$(getent ahosts "$BROKER_HOST" 2>/dev/null | awk '{print $1}' | sort -u | tr '\n' ' ')
+  if [[ -n "$BROKER_ADDRS" ]]; then
+    item "  resolves to $BROKER_ADDRS from this machine"
+    if print -r -- "$BROKER_ADDRS" | grep -q ':'; then
+      item "  it offers an IPv6 address as well: a client that picks that one fails on its own if"
+      item "  the address is transient. Check 'journalctl -u avahi-daemon' for it being withdrawn."
+    fi
   elif have ping && ping -c1 -W2 "$BROKER_HOST" >/dev/null 2>&1; then
     item "  answers ping from this machine"
   else
@@ -230,6 +241,110 @@ fi
 MYADDRS=$( (have ip && ip -4 -o addr show scope global | awk '{print $2"="$4}') 2>/dev/null | tr '\n' ' ')
 item "this machine's addresses: ${MYADDRS:-(could not determine)}"
 
+section "Who is connected to the broker"
+# The single most useful line when a node or a browser says it cannot connect: if the server's own
+# logger is connected, the broker is up, listening and authenticating, and the problem is at the
+# other end. That is what settled it on 7 Sep 2026, when a node reporting a failed TCP connect and a
+# browser reporting a failed WebSocket handshake both turned out to have been asleep.
+BROKER_CONNS=""
+if have ss; then
+  # Only the sockets whose LOCAL port is the broker's. A connection with both ends on this machine -
+  # which is what the server's own logger is - otherwise appears twice, once from each side, and the
+  # count comes out too high. With "state established" ss prints no State column, so the local
+  # address is $3 and the peer $4.
+  BROKER_CONNS=$(ss -tn state established 2>/dev/null |
+    awk '$3 ~ /:(1883|9012)$/ {print $4 " -> " $3}' || true)
+  CONN_COUNT=$(print -r -- "$BROKER_CONNS" | grep -c . || true)
+  item "clients connected to 1883/9012: ${CONN_COUNT:-0}"
+  if [[ -n "$BROKER_CONNS" ]]; then
+    print -r -- "$BROKER_CONNS" | sed 's/^/      /'
+  else
+    item "  nothing is connected - not even this server's own logger"
+    problem "No client is connected to the broker. If the frugaliot service is running, its logger should be - check its journal above for 'mqtt <org> connect'"
+  fi
+else
+  item "ss not available - cannot list connections"
+fi
+
+section "Broker access control"
+# An acl_file confines each account to its own organization's topics; without one, every account
+# that can log in reaches every topic on the broker. Reported here because a broker installed before
+# the ACL shipped will not have one, and nothing else says so.
+BROKER_CONF_FILES=(/etc/mosquitto/mosquitto.conf /etc/mosquitto/conf.d/*.conf(N))
+BROKER_SETTING=""
+broker_setting() {  # name -> value from the broker's own configuration, sudo only if needed
+  local v
+  v=$(grep -hE "^[[:space:]]*$1[[:space:]]" "${BROKER_CONF_FILES[@]}" 2>/dev/null | tail -1 | awk '{print $2}') || true
+  if [[ -z "$v" ]] && have sudo; then
+    v=$(sudo -n grep -hE "^[[:space:]]*$1[[:space:]]" "${BROKER_CONF_FILES[@]}" 2>/dev/null | tail -1 | awk '{print $2}') || true
+  fi
+  BROKER_SETTING="$v"
+}
+broker_setting acl_file; ACLFILE="$BROKER_SETTING"
+if [[ -z "$ACLFILE" ]]; then
+  item "acl_file: NOT SET - every account that can log in can reach every topic, across all organizations"
+  problem "The broker has no acl_file. Re-run the install script, or see INSTALLATION.md 'Turn on access control'"
+else
+  item "acl_file: $ACLFILE"
+  if [[ -r "$ACLFILE" ]] || { have sudo && sudo -n test -r "$ACLFILE" 2>/dev/null; }; then
+    ACLOWNER=$( (stat -c '%U:%G %a' "$ACLFILE" 2>/dev/null || sudo -n stat -c '%U:%G %a' "$ACLFILE" 2>/dev/null) || true)
+    item "  owner/mode: ${ACLOWNER:-unknown} (mosquitto reads it after dropping privileges, so it wants mosquitto:mosquitto 600)"
+  fi
+fi
+
+# The dynamic security plugin. install-pi.sh comments it out and carries on if the plugin is not
+# installed, so a broker can be working correctly and still not support per-user accounts - which is
+# worth saying plainly rather than leaving somebody to wonder why they cannot be created.
+broker_setting plugin; DYNPLUGIN="$BROKER_SETTING"
+broker_setting plugin_opt_config_file; DYNSTATE="$BROKER_SETTING"
+if [[ -z "$DYNPLUGIN" ]]; then
+  item "dynamic security: not configured - running on shared organization passwords (the fallback)"
+  item "  per-user and per-node broker accounts are unavailable until the plugin is enabled"
+  if [[ -n "$(print -rl -- /usr/lib/*/mosquitto_dynamic_security.so /usr/lib/mosquitto_dynamic_security.so(N) 2>/dev/null)" ]]; then
+    item "  the plugin IS installed on this machine, so re-running the install script would enable it"
+    problem "mosquitto's dynamic security plugin is installed but not configured - re-run install-pi.sh"
+  else
+    item "  the plugin is not installed on this machine either (mosquitto package does not ship it here)"
+  fi
+else
+  item "dynamic security: $DYNPLUGIN"
+  if [[ -n "$DYNSTATE" ]]; then
+    if [[ -e "$DYNSTATE" ]] || { have sudo && sudo -n test -e "$DYNSTATE" 2>/dev/null; }; then
+      item "  state file: $DYNSTATE"
+    else
+      item "  state file: $DYNSTATE MISSING - the broker will not start"
+      problem "The broker names a dynamic-security state file that does not exist: $DYNSTATE"
+    fi
+  fi
+  # Can the server actually drive it? That needs the admin credential frugal-iot-init recorded.
+  DYNUSER=$(sed -n 's/^dynsec_admin_user:[[:space:]]*//p' config.d/secrets.yaml 2>/dev/null | tr -d '"'"'"'' | head -1)
+  DYNPW=$(sed -n 's/^dynsec_admin_password:[[:space:]]*//p' config.d/secrets.yaml 2>/dev/null | tr -d '"'"'"'' | head -1)
+  if [[ -z "$DYNUSER" || -z "$DYNPW" ]]; then
+    item "  admin credential: not in config.d/secrets.yaml - the server cannot create accounts"
+    problem "dynamic security is enabled but config.d/secrets.yaml has no dynsec_admin_user/password"
+  elif have mosquitto_ctrl; then
+    if DYNOUT=$(mosquitto_ctrl -h localhost -u "$DYNUSER" -P "$DYNPW" dynsec listClients 2>&1 | grep -viE 'without encryption|visible on the network'); then
+      item "  admin credential works ($(print -r -- $DYNOUT | tr '\n' ' ' | cut -c1-60))"
+    else
+      item "  admin credential REJECTED by the broker"
+      problem "The dynsec admin credential in config.d/secrets.yaml does not work - the server cannot create accounts"
+    fi
+  else
+    item "  mosquitto_ctrl not installed - cannot test the admin credential"
+  fi
+  # Does the broker's state still match the database? Reporting drift is useful far more often than
+  # repairing it, which is why this runs "check" and never applies anything.
+  if [[ -f node_modules/frugal-iot-server/scripts/rebuild-dynsec.js ]]; then
+    DYNCHECK=$(node node_modules/frugal-iot-server/scripts/rebuild-dynsec.js check 2>&1) || true
+    if print -r -- "$DYNCHECK" | grep -q "matches the database"; then
+      item "  broker state matches the database"
+    else
+      print -r -- "$DYNCHECK" | sed 's/^/    /'
+      problem "The broker's accounts do not match the database - run: npx --no frugal-iot-rebuild-dynsec"
+    fi
+  fi
+fi
+
 section "Broker authentication (steps 5, 6)"
 if have mosquitto_sub; then
   # A wrong password must be refused - that is the check in step 5
@@ -245,6 +360,10 @@ if have mosquitto_sub; then
   fi
   # Then each configured organization should be able to connect with its own credentials.
   # The password is read from the config and used, never printed.
+  #
+  # This is the SHARED organization account, which every node and dashboard used to use. Each of
+  # them now has its own (see SECURITY.md), and this account is removed by S8 - after which "no
+  # mqtt_password" below is the right answer rather than a fault.
   for f in config.d/organizations/*.yaml(N); do
     ORG=${f:t:r}
     ORG_PW=$(sed -n 's/^mqtt_password:[[:space:]]*//p' "$f" 2>/dev/null | head -1 | tr -d '"'"'"'')

package/scripts/dynsec-init.js

@@ -0,0 +1,142 @@
+#!/usr/bin/env node
+/*
+ * Create the broker's initial dynamic-security state, without mosquitto_ctrl.
+ *
+ *   npx --no frugal-iot-dynsec-init [output-path]
+ *
+ * Run from the server's own directory, the one holding frugal-iot.db.
+ *
+ * Why this exists. `mosquitto_ctrl dynsec init` does the same job and is what install-pi.sh uses,
+ * but it comes from the mosquitto-clients package, and on the production server that package cannot
+ * be installed: its broker was built for an older Ubuntu from the mosquitto PPA, and the
+ * mosquitto-clients in the distribution demands an exactly-matching libmosquitto1 - so apt would
+ * downgrade the library out from under the running broker. Without this, per-user broker accounts
+ * could be set up on a Pi and not on production.
+ *
+ * What it writes is the file the plugin keeps its state in: one admin client, the admin role that
+ * lets it drive $CONTROL, and the defaults mosquitto_ctrl sets. Everything else - every user, node,
+ * logger, group and role - is created by the server from the database afterwards, so this file is a
+ * starting point rather than something to maintain (npx --no frugal-iot-rebuild-dynsec).
+ *
+ * It does NOT install the file: writing to /var/lib/mosquitto needs root, and running this whole
+ * script under sudo would leave config.d/secrets.yaml owned by root, which the server then could
+ * not rewrite. So it writes here, as you, and prints the one command that moves it into place.
+ */
+
+import { pbkdf2Sync, randomBytes } from 'crypto';
+import { existsSync, writeFileSync, appendFileSync, chmodSync, readFileSync } from 'fs';
+
+const SECRETS = './config.d/secrets.yaml';
+const ADMIN = 'frugal-admin';
+const TARGET = '/var/lib/mosquitto/dynamic-security.json';
+const out = process.argv[2] || './dynamic-security.json';
+
+/*
+ * How mosquitto stores a dynsec password, confirmed by reproducing a file mosquitto_ctrl wrote:
+ * PBKDF2-HMAC-SHA512, the iteration count from the file, a 12-byte salt, 64 bytes out, both salt
+ * and hash base64. The 101 iterations are mosquitto's own default and are not a typo - this file is
+ * read only at startup and by the plugin itself, so it is not a password-store hash in the usual
+ * sense; changing the number here would be harmless but pointless.
+ */
+function hash(password, iterations = 101) {
+  const salt = randomBytes(12);
+  return {
+    salt: salt.toString('base64'),
+    password: pbkdf2Sync(password, salt, iterations, 64, 'sha512').toString('base64'),
+    iterations,
+  };
+}
+
+function fail(message, ...rest) {
+  console.error(message);
+  for (const line of rest) console.error(line);
+  process.exit(1);
+}
+
+if (existsSync(out)) {
+  fail(`${out} already exists - not overwriting it.`,
+    'If the broker is using it, replacing it would delete every account it knows about and',
+    'every node would stop connecting. Move it aside first if you really mean to start again.');
+}
+if (!existsSync(SECRETS)) {
+  fail(`No ${SECRETS}.`,
+    "If you are in the server's own directory - the one holding frugal-iot.db - then this",
+    'installation predates that file. It is created by:  npx --no frugal-iot-init',
+    '',
+    'Run that first. Do not create the file by hand and run this before upgrading the server:',
+    'a release that predates config-for-user.js serves the whole configuration to any logged-in',
+    'browser, so the admin credential this writes would go out with it.');
+}
+if (/^dynsec_admin_user:/m.test(readFileSync(SECRETS, 'utf8'))) {
+  fail(`${SECRETS} already has a dynsec_admin_user.`,
+    'This server already has an admin credential, so the broker most likely already has its',
+    'state file. Check with: npx --no frugal-iot-diagnostic');
+}
+
+const password = randomBytes(24).toString('base64url');
+const { salt, password: hashed, iterations } = hash(password);
+
+// The shape mosquitto_ctrl produces. Only the admin client and its role: the server creates
+// everything else from the database.
+const state = {
+  defaultACLAccess: {
+    publishClientSend: false,
+    publishClientReceive: true,
+    subscribe: false,
+    unsubscribe: true,
+  },
+  clients: [{
+    username: ADMIN,
+    textname: 'Dynsec admin user',
+    roles: [{ rolename: 'admin' }],
+    password: hashed,
+    salt,
+    iterations,
+  }],
+  groups: [],
+  roles: [{
+    rolename: 'admin',
+    acls: [
+      { acltype: 'publishClientSend', topic: '$CONTROL/dynamic-security/#', priority: 0, allow: true },
+      { acltype: 'publishClientReceive', topic: '$CONTROL/dynamic-security/#', priority: 0, allow: true },
+      { acltype: 'publishClientReceive', topic: '$SYS/#', priority: 0, allow: true },
+      { acltype: 'subscribePattern', topic: '$CONTROL/dynamic-security/#', priority: 0, allow: true },
+      { acltype: 'subscribePattern', topic: '$SYS/#', priority: 0, allow: true },
+    ],
+  }],
+};
+
+writeFileSync(out, JSON.stringify(state, null, 2) + '\n');
+chmodSync(out, 0o600);
+
+appendFileSync(SECRETS, [
+  '',
+  '# The broker account the server uses to create and remove other accounts, over',
+  '# $CONTROL/dynamic-security/v1. Created by frugal-iot-dynsec-init.',
+  `dynsec_admin_user: "${ADMIN}"`,
+  `dynsec_admin_password: "${password}"`,
+  '',
+].join('\n'));
+chmodSync(SECRETS, 0o600);
+
+console.log(`Wrote ${out}, and the admin credential to ${SECRETS}.`);
+console.log('');
+console.log('The password is not printed: it is in that file, which is never served to a browser.');
+console.log('');
+console.log('Next, as root - the broker reads this file AFTER dropping privileges, so it has to');
+console.log('belong to the mosquitto user or the broker will not start:');
+console.log('');
+console.log(`  sudo install -o mosquitto -g mosquitto -m 600 ${out} ${TARGET}`);
+console.log('');
+console.log('Then add these two lines to the broker configuration - the plugin path differs by');
+console.log('distribution, so find yours with:  ls /usr/lib/*/mosquitto_dynamic_security.so');
+console.log('');
+console.log('  plugin /usr/lib/<arch>/mosquitto_dynamic_security.so');
+console.log(`  plugin_opt_config_file ${TARGET}`);
+console.log('');
+console.log('and restart the broker, then build the accounts from the database:');
+console.log('');
+console.log('  sudo systemctl restart mosquitto');
+console.log('  sudo systemctl restart frugaliot');
+console.log('  npx --no frugal-iot-rebuild-dynsec');
+console.log('  npx --no frugal-iot-rebuild-dynsec check');

package/scripts/init.zsh

@@ -69,6 +69,48 @@ for f in "${PKG}"/extras/*(N); do
   copy_if_missing "$f" "./extras/${f:t}" compare
 done
 
+# ---- 1b. Secrets this server generates for itself ----
+# Kept in config.d like everything else - that directory is not served (the static mounts are
+# publicdir, htmldir, datadir, privatedir and node_modules), and what does reach a browser goes
+# through unsafeCopyConfigFor, which withholds this section. Mode 600 because these are secrets
+# whatever else is true.
+#
+# Never regenerated: rotating session_secret logs everyone out, and rotating user_secret invalidates
+# every browser's broker credential until its next login. Both are recoverable, neither should
+# happen because somebody re-ran init.
+#
+# Written here as well as by the server (lib/secrets.js fills in anything missing at startup) so
+# that a permissions problem with this directory shows up now, while somebody is watching the
+# install, rather than in the journal at first boot. The server appends only what it does not find,
+# so the two cannot fight, and a release adding a new secret needs no change here.
+if [[ ! -e ./config.d/secrets.yaml ]]; then
+  # ( set +o pipefail ) because head closing the pipe makes tr fail, which under pipefail would
+  # end the script - see the note in claude.md about this exact trap.
+  randsecret() { ( set +o pipefail; LC_ALL=C tr -dc 'A-Za-z0-9' < /dev/urandom | head -c 43 ); }
+  mkdir -p ./config.d
+  # No "secrets:" wrapper inside the file: readConfigFromDir keys each config.d file by its own
+  # name, so this file's contents land at config.secrets - the same way server.yaml's contents land
+  # at config.server. A wrapper here would give config.secrets.secrets.
+  cat > ./config.d/secrets.yaml <<YAML
+# Secrets belonging to this server. Generated by frugal-iot-init; never served to a browser
+# (unsafeCopyConfigFor withholds this whole file's section). Not in git, and worth backing up
+# alongside frugal-iot.db.
+
+# Signs the session cookie. Changing it ends every session.
+session_secret: "$(randsecret)"
+
+# Mixed into each user's derived MQTT password. Changing it invalidates every browser's broker
+# credential until its next login, and nothing else.
+user_secret: "$(randsecret)"
+YAML
+  chmod 600 ./config.d/secrets.yaml
+  COPIED+=("./config.d/secrets.yaml")
+  echo "  created ./config.d/secrets.yaml (generated secrets, mode 600)"
+else
+  chmod 600 ./config.d/secrets.yaml
+  echo "  kept    ./config.d/secrets.yaml (already present)"
+fi
+
 # ---- 1a. Point server.yaml at the web client this instance actually has ----
 # The packaged server.yaml may have been published from a development checkout, where the client is
 # a sibling directory (../frugal-iot-client). When installed with npm the client is a dependency,
@@ -119,6 +161,27 @@ else
   echo "  created ${DB}"
 fi
 
+# ---- 3a. Schema changes that CREATE TABLE IF NOT EXISTS cannot make ----
+# Adding permissions.project needs the UNIQUE constraint changed as well, and SQLite cannot alter a
+# constraint - so the table is rebuilt. Guarded on the column being absent, because init runs on
+# every upgrade. See scripts/migrate-permissions-project.sql for what it does and why.
+PERM_COLS=$(sqlite3 "$DB" "pragma table_info(permissions);" | cut -d'|' -f2) || true
+if ! print -r -- "$PERM_COLS" | grep -qx project; then
+  # A rebuild is the one change here that is not a no-op if it goes wrong, so keep a copy first.
+  DB_BACKUP="${DB}.bak-$(date +%Y%m%d%H%M%S)"
+  cp "$DB" "$DB_BACKUP"
+  if sqlite3 "$DB" < "${PKG}/scripts/migrate-permissions-project.sql"; then
+    echo "  updated ${DB} (added permissions.project; existing rows are organization-wide)"
+    echo "          previous copy kept at ${DB_BACKUP}"
+  else
+    echo "  ERROR: failed to add permissions.project to ${DB}" >&2
+    echo "         the database is unchanged; a copy from before the attempt is at ${DB_BACKUP}" >&2
+    exit 1
+  fi
+else
+  echo "  kept    ${DB} permissions.project (already present)"
+fi
+
 if (( ${#DIFFER_TO} )); then
   echo
   echo "These files were left as you have them, but this release ships a different version:"

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;