frugal-iot-server 0.3.9 → 2.0.0

package/lib/api-routes.js

@@ -26,7 +26,7 @@ import {
   createSuccessResponse
 } from './api-errors.js';
 // Reused directly from the main server rather than reimplemented - see frugal-iot-server.js
-import { loggedInOrFail, can_ADMIN_JSON, can_ADMIN_SOME, can_READ, add_project } from '../frugal-iot-server.js';
+import { loggedInOrFail, can_ADMIN_JSON, can_ADMIN_SOME, can_READ, can_WRITE, add_project } from '../frugal-iot-server.js';
 
 /**
  * Create API router for farm-platform endpoints
@@ -330,7 +330,7 @@ export function createAPIRouter(db, dataDir, loggerClient, pushManager = null) {
    */
   router.post('/devices/action',
     (req, res, next) => {
-      // can_READ (reused from frugal-iot-server.js) reads the org from res.locals.org, so set it first.
+      // can_WRITE (reused from frugal-iot-server.js) reads the org from res.locals.org, so set it first.
       const deviceId = req.body && req.body['device-id'];
       if (!deviceId) {
         return next(new APIError('invalid_request', 'Missing required field: device-id'));
@@ -339,7 +339,7 @@ export function createAPIRouter(db, dataDir, loggerClient, pushManager = null) {
       next();
     },
     loggedInOrFail,
-    can_READ,
+    can_WRITE,
     async (req, res, next) => {
       try {
         const {
@@ -376,7 +376,7 @@ export function createAPIRouter(db, dataDir, loggerClient, pushManager = null) {
    */
   router.get('/devices/action',
     (req, res, next) => {
-      // can_READ (reused from frugal-iot-server.js) reads the org from res.locals.org, so set it first.
+      // can_WRITE (reused from frugal-iot-server.js) reads the org from res.locals.org, so set it first.
       const { deviceId } = req.query;
       if (!deviceId) {
         return next(new APIError('invalid_request', 'Missing required parameter: deviceId'));
@@ -385,7 +385,7 @@ export function createAPIRouter(db, dataDir, loggerClient, pushManager = null) {
       next();
     },
     loggedInOrFail,
-    can_READ,
+    can_WRITE,
     async (req, res, next) => {
       try {
         const {deviceId, action, value} = req.query;
@@ -479,7 +479,7 @@ export function createAPIRouter(db, dataDir, loggerClient, pushManager = null) {
    */
   router.put('/devices/property',
     (req, res, next) => {
-      // can_READ (reused from frugal-iot-server.js) reads the org from res.locals.org, so set it first.
+      // can_WRITE (reused from frugal-iot-server.js) reads the org from res.locals.org, so set it first.
       const { deviceId } = req.query;
       if (!deviceId) {
         return next(new APIError('invalid_request', 'Missing required parameter: deviceId'));
@@ -488,7 +488,7 @@ export function createAPIRouter(db, dataDir, loggerClient, pushManager = null) {
       next();
     },
     loggedInOrFail,
-    can_READ,
+    can_WRITE,
     async (req, res, next) => {
       try {
         const { deviceId, property } = req.query;

package/lib/config-for-user.js

@@ -0,0 +1,115 @@
+/*
+ * What of the configuration a given user is allowed to see.
+ *
+ * Kept out of frugal-iot-server.js so it can be tested without starting a server: importing that
+ * file reads config.yaml, connects to the broker and starts listening, none of which a unit test
+ * wants. These two functions are pure - given a config and a user they return an object - which is
+ * what makes the "no secret ever reaches a browser" test in test/unit/config-for-user.test.js
+ * possible.
+ */
+
+// Sections of the configuration that are never sent to a browser, whatever permissions the user has.
+// config.d itself is not served - the static mounts are publicdir, htmldir, datadir, privatedir and
+// node_modules, so config.d/schema/devices.yaml is a 404 - and buildConfigFor is the only route by
+// which anything under it reaches a browser. So this is the one place the decision belongs.
+//
+// A deny list rather than an allowlist on purpose: nearly every setting here is public (the schema,
+// the broker URL, the logger URL), so an allowlist would be mostly bookkeeping and would break new
+// public fields by forgetting them. The risk that comes with that choice - a future secret field
+// being served because nobody remembered to deny it - is caught by the test suite instead, which
+// asserts that nothing secret-looking appears anywhere in the result.
+export const configSectionsNeverServed = [
+  'secrets',   // config.d/secrets.yaml - session_secret, user_secret
+  // config.d/email.yaml holds "pass", the SMTP (typically Gmail app) password. It was being served
+  // to every logged-in user, which on a server with mail configured is a working credential to send
+  // mail as that account - and registration is open, so "logged in" is not much of a bar. Nothing in
+  // the client reads any of it: whether password reset is available is decided server-side by
+  // mailConfigured(). Found by the "nothing secret-looking" test below, on its first run.
+  'email',
+];
+
+// Fields within an organization's own config that are not sent.
+//
+// mqtt_password is the organization's shared broker credential - readwrite over its whole topic
+// tree, the same one compiled into every node. Serving it to every user with READ was SEC-1: it
+// made "may read" mean "may publish anything", and there was no way to revoke it. Browsers now get
+// their own derived credential in user.mqtt_password instead (S4), so this can finally go.
+//
+// Still in config.d/organizations/<org>.yaml, because the nodes and the logger use it until S8
+// retires it - it just never leaves the server.
+export const orgFieldsNeverServed = [
+  'mqtt_password',
+  // The logger's own derived credential, put into the in-memory config at startup so the logger can
+  // pick it up. It can read the whole organization, so it is at least as sensitive as the shared
+  // password was.
+  'logger_password',
+];
+
+/*
+ * Does this user hold this capability? Two different questions, depending on whether a project is
+ * named, and they are both wanted:
+ *
+ *   hasPermissions(u, 'dev', 'READ')            "anywhere in dev?"  - one project is enough. This
+ *                                               is what decides whether dev is shown at all.
+ *   hasPermissions(u, 'dev', 'READ', 'lotus')   "on dev/lotus?"     - satisfied by a row for lotus
+ *                                               or by an organization-wide row.
+ *
+ * A row's project is '' for organization-wide (see frugal-iot-createdb.sql for why empty string
+ * rather than NULL), and an organization-wide row answers yes to both questions.
+ */
+export function hasPermissions(user, org, permission, project) {
+  if (!user || !user.permissions) return false;
+  return user.permissions.some((x) =>
+    (x.capability === permission) && (x.org === org)
+    && (!project || !x.project || (x.project === project)));
+}
+
+/*
+ * Produce a copy of config holding only what this user may see. A subset of config that points at
+ * the same objects where it can, rather than copying them - do not change the result.
+ *
+ * Two levels of filtering, because a permission can name a project:
+ *   - an organization appears if the user may read it anywhere (any project is enough)
+ *   - within it, only the projects they may actually read
+ * So a user with READ on dev/lotus alone sees organization dev containing lotus, and is not even
+ * told the other projects exist.
+ */
+export function buildConfigFor(config, user) {
+  let oo = {
+    organizations: {},
+    user: user, // All data in user and permissions is visible to the user
+  };
+  Object.entries(config).forEach(([key, value]) => {
+    if (configSectionsNeverServed.includes(key)) {
+      // Deliberately absent from the result
+    } else if (key === 'organizations') {
+      Object.entries(value).forEach(([orgid, org]) => {
+        if (hasPermissions(user, orgid, 'READ')) {
+          oo.organizations[orgid] = orgForUser(user, orgid, org);
+        }
+      });
+    } else {
+      oo[key] = value;
+    }
+  });
+  return oo;
+}
+
+// One organization, with the withheld fields gone and its projects narrowed to those this user may
+// read. An organization-wide READ satisfies every project, so the common case keeps everything.
+function orgForUser(user, orgid, org) {
+  const out = {};
+  for (const [k, v] of Object.entries(org)) {
+    if (orgFieldsNeverServed.includes(k)) continue;
+    if (k === 'projects' && v && typeof v === 'object') {
+      const projects = {};
+      for (const [projectid, project] of Object.entries(v)) {
+        if (hasPermissions(user, orgid, 'READ', projectid)) projects[projectid] = project;
+      }
+      out[k] = projects;
+    } else {
+      out[k] = v;
+    }
+  }
+  return out;
+}

package/lib/dynsec-plan.js

@@ -0,0 +1,246 @@
+/*
+ * What the broker's dynamic-security state should look like, given the database.
+ *
+ * Pure: no MQTT, no sqlite, no clock. Given rows it returns the objects that should exist and the
+ * commands to make it so - which is what lets the whole mapping be tested without a broker, and
+ * what makes "rebuild dynsec from the database" and "report what differs" the same code path.
+ *
+ * The shapes here follow what was measured on mosquitto 2.0.21 - see SECURITY-REVIEW.md section 8:
+ *  - %u expands in a dynsec role ACL, so one rule covers every node
+ *  - a client can be in several groups and gets the union
+ *  - a role can be attached straight to a client, which is how public read is done without
+ *    adding every user to a group
+ */
+
+import { createHmac } from 'crypto';
+
+// A permission row's project is '' for organization-wide - see frugal-iot-createdb.sql.
+const ORGWIDE = '';
+
+// Names. Kept in one place because both the plan and the diff have to agree on them.
+export const names = {
+  readRole:    (org, project) => (project ? `${org}-${project}-read`  : `${org}-read`),
+  writeRole:   (org, project) => (project ? `${org}-${project}-write` : `${org}-write`),
+  readGroup:   (org, project) => (project ? `${org}-${project}-read`  : `${org}-read`),
+  writeGroup:  (org, project) => (project ? `${org}-${project}-write` : `${org}-write`),
+  nodesGroup:  (org) => `${org}-nodes`,
+  gatewayGroup:(org) => `${org}-gateways`,
+  gatewayRole: (org) => `${org}-gateway`,
+  discoverRole:(org) => `${org}-discover`,
+  ownSubtreeRole: 'own-subtree',      // one for the whole broker: publishClientSend %u/#
+  publicRole:     'public-read',      // one for the whole broker: the id-0 "everyone" rows
+  publicGroup:    'public',           // what setAnonymousGroup points at
+  nodeClient:  (org, project, nodeid) => `${org}/${project}/${nodeid}`,
+
+  /*
+   * A user's broker account name. Prefixed, and it has to be.
+   *
+   * addorganization.zsh creates a LOGIN USER named after the organization ("myfarm"), and the
+   * organization's own broker account in the password file has that same name. A dynsec client
+   * called "myfarm" would therefore take over that name - and because a dynsec answer is final for
+   * a client it knows (SECURITY-REVIEW.md section 8, Q4), the organization's shared password would
+   * stop working, taking every node, browser and the logger with it. Namespacing the user keeps the
+   * two apart until S8 retires the shared account deliberately.
+   *
+   * "user/" also cannot collide with a node, which is "org/project/nodeid" - no organization id may
+   * be "user", because addorganization allows only lower-case letters and digits... which "user"
+   * satisfies. So an organization literally called "user" would collide; rejected in
+   * add_permission's caller rather than here, where it would be invisible.
+   */
+  userClient: (username) => `user/${username}`,
+
+  // The logger's own account, one per organization. Cannot collide with anything: an organization
+  // id is 1-10 lower-case letters and digits (addorganization.zsh enforces it), so no org is called
+  // "<org>-logger", and clients and groups are separate namespaces in dynsec anyway.
+  loggerClient: (org) => `${org}-logger`,
+
+  /*
+   * The server's own account for administrative publishes into an organization - at present just
+   * clearing retained messages.
+   *
+   * It can publish anywhere in the organization, which is to say it can forge a reading. That is
+   * unavoidable for clearing: "forget this topic" IS a publish (an empty retained payload), and the
+   * broker cannot tell one from the other. The point is WHO holds it - only the server, never a
+   * browser. Before this, clearing was done by the browser with the organization's shared
+   * credential, which is exactly the capability S4 took away.
+   */
+  orgAdminClient: (org) => `${org}-admin`,
+  clearRole: (org) => `${org}-clear`,
+};
+
+// Topic filters, in one place for the same reason.
+const topics = {
+  orgTree:     (org, project) => (project ? `${org}/${project}/#` : `${org}/#`),
+  // A browser may command a device but must not forge a reading, so write is set/ only. The extra
+  // "+" for an organization-wide rule is the project level: org/project/node/set/...
+  setOnly:     (org, project) => (project ? `${org}/${project}/+/set/#` : `${org}/+/+/set/#`),
+  ownSubtree:  '%u/#',
+  // How a node announces itself: System_Discovery::quickAdvertise publishes its own node id to the
+  // two-level "<org>/<project>" topic, and that is how the dashboard learns the node exists at all.
+  //
+  // It is NOT covered by ownSubtree. In MQTT "a/b/#" matches "a/b" but not "a", so a node whose
+  // rule is "myfarm/lotus/esp32-abc/#" cannot publish to "myfarm/lotus" - which silently left the
+  // dashboard showing no devices while the readings themselves went through perfectly.
+  discovery:   (org, project) => `${org}/${project}`,
+  bridgeState: '$SYS/broker/connection/+/state',
+};
+
+/*
+ * The password a user's browser gets. Derived rather than stored or random - see SECURITY-REVIEW.md
+ * section 9: derived from the STORED HASH, so the server can recompute it at any time (a session
+ * restored from a cookie has no plaintext), it is the same for two concurrent logins, and a leak
+ * tells an attacker nothing about the login password.
+ */
+export function derivePassword(userSecret, username, hashedPassword) {
+  if (!userSecret) throw new Error('No user_secret - run frugal-iot-init');
+  const hp = Buffer.isBuffer(hashedPassword) ? hashedPassword : Buffer.from(String(hashedPassword || ''));
+  return createHmac('sha256', userSecret)
+    .update(String(username)).update(':').update(hp)
+    .digest('base64url').slice(0, 22);            // 22 base64url chars = 132 bits
+}
+
+/*
+ * Which groups a user should be in, and which roles attached directly, from their permission rows.
+ * Rows are {capability, org, project}; id-0 rows must already be merged in by the caller, exactly as
+ * the session's own query does (WHERE id = ? or id = 0).
+ */
+export function groupsForUser(rows) {
+  const groups = new Set();
+  const roles = new Set();
+  for (const r of rows || []) {
+    const project = r.project || ORGWIDE;
+    if (r.capability === 'READ')  groups.add(names.readGroup(r.org, project));
+    if (r.capability === 'WRITE') groups.add(names.writeGroup(r.org, project));
+  }
+  // Every user also gets whatever is public, as one role rather than per-organization membership.
+  roles.add(names.publicRole);
+  return { groups: [...groups].sort(), roles: [...roles].sort() };
+}
+
+/*
+ * The roles and groups that should exist, given every organization/project in use and which
+ * organizations are publicly readable.
+ *
+ *   scopes    [{org, project}]  - '' project meaning organization-wide
+ *   publics   [{org, project}]  - the id-0 READ rows, as ACLs on the one shared public role
+ */
+export function desiredRolesAndGroups(scopes, publics, projects) {
+  const roles = {};
+  const groups = {};
+
+  // One rule for every node on the broker: publish only your own subtree.
+  roles[names.ownSubtreeRole] = [
+    { acltype: 'publishClientSend', topic: topics.ownSubtree, allow: true },
+  ];
+
+  // Public read, as ACL pairs on a single role - so withdrawing it is one removeRoleACL, for
+  // everybody, rather than removing every user from a group.
+  roles[names.publicRole] = [];
+  for (const { org, project } of publics || []) {
+    const t = topics.orgTree(org, project || ORGWIDE);
+    roles[names.publicRole].push({ acltype: 'subscribePattern', topic: t, allow: true });
+    roles[names.publicRole].push({ acltype: 'publishClientReceive', topic: t, allow: true });
+  }
+  groups[names.publicGroup] = { roles: [names.publicRole] };
+
+  const orgs = new Set();
+  for (const { org, project } of scopes || []) {
+    const p = project || ORGWIDE;
+    orgs.add(org);
+
+    roles[names.readRole(org, p)] = [
+      { acltype: 'subscribePattern', topic: topics.orgTree(org, p), allow: true },
+      { acltype: 'publishClientReceive', topic: topics.orgTree(org, p), allow: true },
+    ];
+    roles[names.writeRole(org, p)] = [
+      { acltype: 'publishClientSend', topic: topics.setOnly(org, p), allow: true },
+    ];
+    groups[names.readGroup(org, p)] = { roles: [names.readRole(org, p)] };
+    groups[names.writeGroup(org, p)] = { roles: [names.writeRole(org, p)] };
+  }
+
+  // Per organization: nodes read the whole organization (cross-node controls) and publish only
+  // their own subtree; gateways additionally publish anywhere in the organization, because a
+  // gateway republishes other nodes' readings under its own account and MQTT cannot delegate.
+  /*
+   * Announcing on the project topic, one ACL per REGISTERED project.
+   *
+   * Deliberately not "<org>/+", which would let a node announce a project that does not exist - a
+   * name mistyped into a captive portal would then appear in the dashboard as a project, with a
+   * node in it. Enumerating the real projects means growth per project (not per node) and no way
+   * to invent one. Enrolment checks the same list, so the two cannot disagree.
+   */
+  for (const { org, project } of projects || []) {
+    if (!project) continue;
+    const role = names.discoverRole(org);
+    roles[role] = roles[role] || [];
+    roles[role].push({ acltype: 'publishClientSend', topic: topics.discovery(org, project), allow: true });
+  }
+
+  for (const org of orgs) {
+    if (!roles[names.readRole(org, ORGWIDE)]) {
+      roles[names.readRole(org, ORGWIDE)] = [
+        { acltype: 'subscribePattern', topic: topics.orgTree(org, ORGWIDE), allow: true },
+        { acltype: 'publishClientReceive', topic: topics.orgTree(org, ORGWIDE), allow: true },
+      ];
+    }
+    // Publishing anywhere in the organization, for clearing retained messages. Held by the server
+    // alone - there is no group for it, so nothing else can be put in it by accident.
+    roles[names.clearRole(org)] = [
+      { acltype: 'publishClientSend', topic: topics.orgTree(org, ORGWIDE), allow: true },
+    ];
+    roles[names.gatewayRole(org)] = [
+      { acltype: 'publishClientSend', topic: topics.orgTree(org, ORGWIDE), allow: true },
+    ];
+    // A node that never announces is invisible, so the discover role is part of being a node - but
+    // the role exists only if the organization has at least one registered project.
+    roles[names.discoverRole(org)] = roles[names.discoverRole(org)] || [];
+    groups[names.nodesGroup(org)] = {
+      roles: [names.readRole(org, ORGWIDE), names.ownSubtreeRole, names.discoverRole(org)] };
+    groups[names.gatewayGroup(org)] = { roles: [names.gatewayRole(org)] };
+  }
+  return { roles, groups };
+}
+
+/*
+ * The logger's password for one organization. Derived, like a user's, so nothing has to be stored
+ * and the server can recompute it whenever it starts - which is when it hands it to the logger.
+ *
+ * A separate label in the HMAC input from a user's, so a logger account and a user account can
+ * never derive the same password even if the names lined up.
+ */
+export function deriveLoggerPassword(userSecret, org) {
+  if (!userSecret) throw new Error('No user_secret - run frugal-iot-init');
+  return createHmac('sha256', userSecret)
+    .update('logger:').update(String(org))
+    .digest('base64url').slice(0, 22);
+}
+
+/*
+ * The logger reads everything in its organization and publishes ONLY set/ topics.
+ *
+ * It does need write: it is what publishes the platform API's device commands
+ * (frugal-iot-logger/index.js:1384). What it must not be able to do is publish a reading, because
+ * then a confused or compromised logger could invent sensor data - and the readings are the whole
+ * point of the system. The <org>-write role is set/-only, which is exactly that.
+ */
+// The server's administrative account for one organization. Derived, like the logger's, with its
+// own label so the two can never collide.
+export function deriveOrgAdminPassword(userSecret, org) {
+  if (!userSecret) throw new Error('No user_secret - run frugal-iot-init');
+  return createHmac('sha256', userSecret)
+    .update('orgadmin:').update(String(org))
+    .digest('base64url').slice(0, 22);
+}
+
+export function groupsForLogger(org) {
+  return [names.readGroup(org, ORGWIDE), names.writeGroup(org, ORGWIDE)].sort();
+}
+
+// Whether a node should be a gateway - declared by the firmware at enrolment, not by what it is
+// doing at the time, because any node that sees WiFi can promote itself (see S7).
+export function groupsForNode(org, project, { lora = false } = {}) {
+  const groups = [names.nodesGroup(org)];
+  if (lora) groups.push(names.gatewayGroup(org));
+  return groups.sort();
+}

package/lib/dynsec-server.js

@@ -0,0 +1,204 @@
+/*
+ * The server's own use of dynamic security: keeping one user's broker account in step with the
+ * database, at the moments the database changes.
+ *
+ * Every function here is best-effort and never fatal. A broker with no plugin, or one that is
+ * briefly unreachable, must not stop somebody logging in or an administrator granting a permission -
+ * the dashboard is more useful with live data missing than not at all. Failures are logged with
+ * enough context to act on, and scripts/diagnostic.zsh reports the resulting drift.
+ */
+
+import { dynsecConnect } from './dynsec.js';
+import { readUserRows, applyUser, applyLogger, applyNode, removeUser } from './dynsec-sync.js';
+import { derivePassword, deriveLoggerPassword, names } from './dynsec-plan.js';
+
+let unavailableReported = false;
+
+/*
+ * Has this server ever been set up to drive the plugin?
+ *
+ * The distinction matters when handing out a DERIVED credential. A derived password is correct
+ * whether or not the broker has been told about it *this second* - so when the plugin is merely
+ * unreachable for a moment, the account almost certainly exists from an earlier run and the
+ * credential works. But when this server has no admin credential at all, the account has never
+ * existed, and handing one out gives the holder something that cannot work: a logger authenticating
+ * as an account the broker has never heard of records nothing, and a browser shows an empty
+ * dashboard - both silently, and both worse than falling back to the shared credential that still
+ * works until S8 retires it.
+ *
+ * This is the state a server is in for the minutes between installing a release that expects the
+ * plugin and enabling the plugin, and that window is exactly when it must not break.
+ */
+function dynsecConfigured(config) {
+  const s = (config && config.secrets) || {};
+  return !!(s.dynsec_admin_user && s.dynsec_admin_password);
+}
+
+// A connection per operation rather than one held open. These happen at login and at permission
+// changes - rare, and never in a hot path - and a short-lived connection cannot go stale, which on
+// a Pi that sleeps or loses its network it otherwise would.
+function withDynsec(config, cb) {
+  dynsecConnect(config, (err, dynsec) => {
+    if (err) return cb(err);
+    cb(null, dynsec, () => dynsec.end(() => {}));
+  });
+}
+
+function reportUnavailable(what, err) {
+  // Once per process for the ordinary "this broker has no plugin" case, so a server without one
+  // does not fill its journal - and on an SD card, its card. Everything else is worth a line.
+  const ordinary = /No dynsec_admin_user|did not answer|No answer from the broker/.test(err.message);
+  if (ordinary && unavailableReported) return;
+  if (ordinary) unavailableReported = true;
+  console.log(`Broker accounts not updated (${what}): ${err.message}`);
+}
+
+/*
+ * Make the broker match the database for one user, and return the password their browser should
+ * use. Call this whenever what the database says about them changes: at login, when a permission is
+ * granted or revoked, and when they change their password (which changes the derived credential).
+ *
+ * cb(err, {username, password}) - err only for a caller that wants to know; callers here log and
+ * carry on.
+ */
+export function syncUser(db, config, user, cb) {
+  cb = cb || (() => {});
+  const userSecret = config.secrets && config.secrets.user_secret;
+  if (!userSecret) {
+    const err = new Error('No user_secret in config.d/secrets.yaml - run frugal-iot-init');
+    reportUnavailable(`user ${user.username}`, err);
+    return cb(err);
+  }
+  // Nothing to hand a browser on a server that has never driven the plugin: the account cannot
+  // exist, so the dashboard says live data is unavailable rather than failing to connect with a
+  // credential that was never real. See dynsecConfigured.
+  if (!dynsecConfigured(config)) {
+    reportUnavailable(`user ${user.username}`,
+      new Error('No dynsec_admin_user in config.d/secrets.yaml'));
+    return cb(null, null);
+  }
+  readUserRows(db, user.id, (err, rows) => {
+    if (err) return cb(err);
+    withDynsec(config, (cerr, dynsec, done) => {
+      if (cerr) {
+        reportUnavailable(`user ${user.username}`, cerr);
+        // Still hand back the credential: it is derived, so it is correct whether or not the broker
+        // has been told about it yet, and a later rebuild will make the broker agree.
+        return cb(null, {
+          username: `user/${user.username}`,
+          password: derivePassword(userSecret, user.username, user.hashed_password),
+          brokerUpdated: false,
+        });
+      }
+      applyUser(dynsec, {
+        username: user.username, hashedPassword: user.hashed_password, rows, userSecret,
+      }, (aerr, res) => {
+        done();
+        if (aerr) {
+          console.error(`Could not update the broker account for ${user.username}: ${aerr.message}`);
+          return cb(aerr);
+        }
+        cb(null, { ...res, brokerUpdated: true });
+      });
+    });
+  });
+}
+
+// Same, by id - for the permission routes, which have an id and no user object.
+export function syncUserById(db, config, id, cb) {
+  cb = cb || (() => {});
+  db.get('SELECT id, username, hashed_password FROM users WHERE id = ?', [id], (err, user) => {
+    if (err) return cb(err);
+    // id 0 is "everyone" and is not an account anybody logs in as, so there is nothing to sync -
+    // but a change to its rows affects EVERY user, which only a rebuild can put right. Say so.
+    if (!user || !user.username) {
+      if (Number(id) === 0) {
+        console.log('A permission for "everyone" changed. Every user\'s broker account is affected:');
+        console.log('  run  npx --no frugal-iot-rebuild-dynsec  to apply it to all of them.');
+      }
+      return cb(null, null);
+    }
+    syncUser(db, config, user, cb);
+  });
+}
+
+/*
+ * The logger's own account for every organization, and the credentials it should use.
+ *
+ * Called once at startup, BEFORE the logger connects - it cannot authenticate as an account that
+ * does not exist yet. Returns what to hand it either way: the password is derived, so it is correct
+ * whether or not the broker has been told, and a broker that is unreachable leaves the logger
+ * falling back to the organization's shared password, which still works until S8 retires it.
+ */
+export function syncLoggers(config, orgs, cb) {
+  cb = cb || (() => {});
+  const userSecret = config.secrets && config.secrets.user_secret;
+  const creds = {};
+  // No credentials at all means the logger falls back to the organization's shared password, which
+  // works until S8. That is the right answer whenever an account of its own could not exist.
+  if (!userSecret || !dynsecConfigured(config)) {
+    reportUnavailable('logger accounts',
+      new Error(userSecret ? 'No dynsec_admin_user in config.d/secrets.yaml'
+                           : 'No user_secret in config.d/secrets.yaml'));
+    return cb(null, creds);
+  }
+  for (const org of orgs) {
+    creds[org] = { username: names.loggerClient(org), password: deriveLoggerPassword(userSecret, org) };
+  }
+  withDynsec(config, (cerr, dynsec, done) => {
+    // Configured but not answering: the accounts are almost certainly there from an earlier run,
+    // so the derived credentials are handed over and the logger reconnects when the broker returns.
+    if (cerr) { reportUnavailable('logger accounts', cerr); return cb(null, creds); }
+    let i = 0;
+    const next = () => {
+      if (i >= orgs.length) { done(); return cb(null, creds); }
+      const org = orgs[i++];
+      applyLogger(dynsec, { org, userSecret }, (err) => {
+        if (err) {
+          console.error(`Could not set up the logger account for ${org}: ${err.message}`);
+          // Same reasoning one organization down: do not hand over a credential this run failed to
+          // create, or that organization records nothing at all.
+          delete creds[org];
+        }
+        next();
+      });
+    };
+    next();
+  });
+}
+
+/*
+ * One node's broker account, at enrolment. Unlike a user's, this is NOT best effort: a node stores
+ * whatever it is given and has no way to notice the broker was never told, so it would be left
+ * unable to connect and unable to re-enrol. enrol() refuses rather than issue such a credential,
+ * and the node retries.
+ */
+export function syncNode(config, node, cb) {
+  withDynsec(config, (cerr, dynsec, done) => {
+    if (cerr) { reportUnavailable(`node ${node.nodeid}`, cerr); return cb(cerr); }
+    applyNode(dynsec, node, (err) => { done(); cb(err); });
+  });
+}
+
+// Remove a node's broker account, for frugal-iot-resetnode. Best effort: the point of resetting is
+// that the node will enrol again, which recreates it.
+export function dropNode(config, org, project, nodeid, cb) {
+  cb = cb || (() => {});
+  withDynsec(config, (cerr, dynsec, done) => {
+    if (cerr) { reportUnavailable(`removing node ${nodeid}`, cerr); return cb(cerr); }
+    dynsec.raw([{ command: 'deleteClient', username: names.nodeClient(org, project, nodeid) }], (err) => {
+      done();
+      cb(err && !/not found/i.test(err.message) ? err : null);
+    });
+  });
+}
+
+// When an account goes away. Not wired up yet - nothing deletes users - but the rebuild tool cannot
+// notice a user that is no longer in the database, so this is what the deletion path will need.
+export function dropUser(config, username, cb) {
+  cb = cb || (() => {});
+  withDynsec(config, (cerr, dynsec, done) => {
+    if (cerr) { reportUnavailable(`removing ${username}`, cerr); return cb(cerr); }
+    removeUser(dynsec, username, (err) => { done(); cb(err); });
+  });
+}