frugal-iot-server 0.3.8 → 2.0.0

package/lib/mailer.js

@@ -0,0 +1,43 @@
+/*
+ * Sending mail, configured in config.d/email.yaml.
+ *
+ * Absent or incomplete configuration means this server does not send mail. That is a supported
+ * state - most installations are a Pi in a shed - so mailConfigured() lets a caller say so plainly
+ * instead of accepting a request and dropping it.
+ */
+import nodemailer from 'nodemailer';
+
+let transport = null;
+let mailFrom = null;
+
+// emailConfig is config.email, i.e. config.d/email.yaml. Returns a line for the startup log.
+function mailInit(emailConfig) {
+  transport = null;
+  mailFrom = null;
+  if (!emailConfig || !emailConfig.host || !emailConfig.from) {
+    return "Not sending mail (no host/from in config.d/email.yaml) - password reset is unavailable";
+  }
+  const port = emailConfig.port || 587;
+  transport = nodemailer.createTransport({
+    host: emailConfig.host,
+    port,
+    // 465 is TLS from the first byte; 587 and 25 start plain and STARTTLS. Wrong either way is a
+    // connection that hangs rather than an error that says what is wrong, so derive it.
+    secure: (emailConfig.secure !== undefined) ? emailConfig.secure : (port === 465),
+    auth: emailConfig.user ? { user: emailConfig.user, pass: emailConfig.pass } : undefined,
+  });
+  mailFrom = emailConfig.from;
+  return `Sending mail via ${emailConfig.host}:${port} as ${mailFrom}`;
+}
+
+function mailConfigured() { return !!transport; }
+
+// cb(err) - nodemailer is promise-based, wrapped here because the rest of this codebase is callbacks
+function sendMail({ to, subject, text, html }, cb) {
+  if (!transport) { return cb(new Error("Mail is not configured on this server")); }
+  transport.sendMail({ from: mailFrom, to, subject, text, html })
+    .then(() => cb(null))
+    .catch((err) => cb(err));
+}
+
+export { mailInit, mailConfigured, sendMail };

package/lib/replica.js

@@ -0,0 +1,246 @@
+/*
+ * Sharing a production server's logins with a bridged Pi (SECURITY.md S11).
+ *
+ * The problem: a bridge relays TOPICS, not accounts. A person who logs into production therefore has
+ * no account on the Pi's broker, and the Pi is often the only thing reachable - it goes on working
+ * when the link is down, which is why it is there.
+ *
+ * What travels: username, the stored password hash, its salt, and the permission rows for one
+ * organization. Nothing derived from a password, and no secret shared - the Pi authenticates the
+ * login itself against that hash (the same pbkdf2 comparison production does) and derives its own
+ * broker credential from its OWN user_secret. So the two brokers hand out different passwords for
+ * the same person, and neither could compute the other's.
+ *
+ * Direction: the Pi PULLS. It sits behind a home router that production cannot reach, and its
+ * broker bridge is already an outbound connection for the same reason.
+ *
+ * Revocation: each pull REPLACES that organization's replicated rows. A permission that stops being
+ * sent stops existing, with nothing to diff and no way for a stale row to survive.
+ */
+
+import { randomBytes } from 'crypto';
+
+/*
+ * Replicated users take local id OFFSET + their production id.
+ *
+ * They cannot use production's ids directly: addorganization creates a login on the Pi too, and
+ * both machines allocate from AUTOINCREMENT starting at 2, so the ids would collide. The offset
+ * holds only while no installation has OFFSET-2 local users of its own, which is a safe bet for a
+ * farm and is asserted below rather than assumed.
+ */
+export const REPLICA_ID_OFFSET = 1000;
+
+export function isReplicatedId(id) { return Number(id) >= REPLICA_ID_OFFSET; }
+
+export function newBridgeToken() { return randomBytes(32).toString('base64url'); }
+
+// ---- production side ---------------------------------------------------------------------------
+/*
+ * What one organization's bridge is allowed to know: its people and what they may do.
+ *
+ * Deliberately not the whole users table - a Pi hosting one organization has no business knowing
+ * about anyone else's. id 0 ("everyone") is included, because the Pi's own permission checks read
+ * "id = ? or id = 0" and would otherwise disagree with production about what is public.
+ */
+export function replicaFor(db, org, cb) {
+  db.all(`SELECT DISTINCT id FROM permissions WHERE org = ? AND id > 0`, [org], (err, ids) => {
+    if (err) return cb(err);
+    const list = ids.map((r) => r.id);
+    const marks = list.map(() => '?').join(',') || 'NULL';
+    db.all(`SELECT id, username, hashed_password, salt, name, email
+            FROM users WHERE id IN (${marks}) AND username IS NOT NULL`, list, (uerr, users) => {
+      if (uerr) return cb(uerr);
+      db.all('SELECT id, capability, org, project FROM permissions WHERE org = ? AND (id > 0 OR id = 0)',
+        [org], (perr, permissions) => {
+          if (perr) return cb(perr);
+          cb(null, {
+            org,
+            at: Date.now(),
+            // Buffers do not survive JSON, and the Pi needs them back as BLOBs or its
+            // timingSafeEqual comparison throws instead of failing
+            users: users.map((u) => ({
+              id: u.id,
+              username: u.username,
+              hashed_password: u.hashed_password ? Buffer.from(u.hashed_password).toString('base64') : null,
+              salt: u.salt ? Buffer.from(u.salt).toString('base64') : null,
+              name: u.name,
+              email: u.email,
+            })),
+            permissions,
+          });
+        });
+    });
+  });
+}
+
+// Which bridge a token belongs to, or nothing. Constant-timeish is not the concern here: a token is
+// 32 random bytes, and the lookup is by exact match.
+export function bridgeForToken(db, token, cb) {
+  if (!token) return cb(null, null);
+  db.get('SELECT org, site FROM bridges WHERE token = ?', [token], cb);
+}
+
+export function noteBridgePull(db, org, site, cb) {
+  cb = cb || (() => {});
+  db.run('UPDATE bridges SET last_pull = ? WHERE org = ? AND site = ?', [Date.now(), org, site], cb);
+}
+
+// ---- the Pi's side -----------------------------------------------------------------------------
+/*
+ * Apply one organization's replica, replacing whatever was there.
+ *
+ * cb(err, {users, permissions, skipped}) - skipped names logins that could not be taken because a
+ * LOCAL account already uses that name. Overwriting one would silently change who can log in as
+ * whom, so it is refused and reported.
+ */
+export function applyReplica(db, org, payload, cb) {
+  if (!payload || payload.org !== org || !Array.isArray(payload.users) || !Array.isArray(payload.permissions)) {
+    return cb(new Error('Not a replica for this organization'));
+  }
+  // A feed that named other organizations would be granting permissions the Pi does not host
+  const foreign = payload.permissions.find((p) => p.org !== org);
+  if (foreign) return cb(new Error(`Replica for ${org} carried a permission for ${foreign.org}`));
+
+  const skipped = [];
+  db.serialize(() => {
+    db.run('BEGIN IMMEDIATE');
+    // Everything replicated for THIS organization goes; other organizations, and local rows, stay.
+    db.run('DELETE FROM permissions WHERE org = ? AND id >= ?', [org, REPLICA_ID_OFFSET]);
+
+    let pending = payload.users.length;
+    const afterUsers = () => {
+      let left = payload.permissions.length;
+      const done = (err) => {
+        if (err) { return db.run('ROLLBACK', () => cb(err)); }
+        // A replicated user with no permissions left anywhere is nobody on this machine
+        db.run(`DELETE FROM users WHERE id >= ? AND id NOT IN (SELECT id FROM permissions)`,
+          [REPLICA_ID_OFFSET], (derr) => {
+            if (derr) { return db.run('ROLLBACK', () => cb(derr)); }
+            db.run('COMMIT', (cerr) => cb(cerr, {
+              users: payload.users.length - skipped.length,
+              permissions: payload.permissions.length,
+              skipped,
+            }));
+          });
+      };
+      if (!left) return done(null);
+      for (const p of payload.permissions) {
+        // id 0 is "everyone" and is local on every machine - never replicated over the top of it
+        const id = Number(p.id) === 0 ? 0 : REPLICA_ID_OFFSET + Number(p.id);
+        db.run(`INSERT OR IGNORE INTO permissions (id, capability, org, project)
+                VALUES (?, ?, ?, ?)`,
+          [id, p.capability, p.org, p.project || ''], (err) => {
+            if (err && left > 0) { left = -1; return done(err); }
+            if (--left === 0) done(null);
+          });
+      }
+    };
+    if (!pending) return afterUsers();
+    for (const u of payload.users) {
+      const id = REPLICA_ID_OFFSET + Number(u.id);
+      if (!Number.isFinite(Number(u.id)) || Number(u.id) <= 0) {
+        skipped.push(u.username); if (--pending === 0) afterUsers(); continue;
+      }
+      const hash = u.hashed_password ? Buffer.from(u.hashed_password, 'base64') : null;
+      const salt = u.salt ? Buffer.from(u.salt, 'base64') : null;
+      // Take the row only if this name is free or already replicated. A local account of the same
+      // name is left alone: replacing it would change who can log in as that person.
+      db.get('SELECT id FROM users WHERE username = ?', [u.username], (gerr, existing) => {
+        if (gerr) { skipped.push(u.username); if (--pending === 0) afterUsers(); return; }
+        if (existing && !isReplicatedId(existing.id)) {
+          skipped.push(u.username);
+          if (--pending === 0) afterUsers();
+          return;
+        }
+        db.run(`INSERT INTO users (id, username, hashed_password, salt, organization, name, email)
+                VALUES (?, ?, ?, ?, ?, ?, ?)
+                ON CONFLICT(id) DO UPDATE SET username = excluded.username,
+                  hashed_password = excluded.hashed_password, salt = excluded.salt,
+                  name = excluded.name, email = excluded.email`,
+          [id, u.username, hash, salt, org, u.name || u.username, u.email || null], () => {
+            if (--pending === 0) afterUsers();
+          });
+      });
+    }
+  });
+}
+
+/*
+ * Fetch one organization's replica from production and apply it.
+ *
+ * Configured in config.d/replica.yaml on the Pi:
+ *
+ *   url: https://frugaliot.example.org      the production server
+ *   organizations: [myfarm]                 the ones this Pi hosts
+ *   intervalSeconds: 900                    how often to re-pull
+ *
+ * with the token in config.d/secrets.yaml as replica_token - a secret, and so not in config.d
+ * anywhere a browser could reach it (lib/config-for-user.js withholds that whole section).
+ *
+ * Never fatal. A Pi whose link is down keeps the replica it already has, and people go on logging
+ * in against it: working without the internet is the reason the Pi exists, so a failed pull is an
+ * expected state rather than an error.
+ */
+export function pullReplica(config, db, { onUser } = {}, cb) {
+  cb = cb || (() => {});
+  const settings = (config && config.replica) || {};
+  const token = config && config.secrets && config.secrets.replica_token;
+  const orgs = settings.organizations || [];
+  if (!settings.url || !token || !orgs.length) {
+    return cb(null, { skipped: 'not configured' });
+  }
+  const base = String(settings.url).replace(/\/+$/, '');
+  let i = 0;
+  const results = [];
+  const next = () => {
+    if (i >= orgs.length) return cb(null, { orgs: results });
+    const org = orgs[i++];
+    fetch(`${base}/replica/${encodeURIComponent(org)}`, {
+      headers: { Authorization: `Bearer ${token}` },
+      signal: AbortSignal.timeout(30000),
+    })
+      .then((r) => (r.ok ? r.json() : Promise.reject(new Error(`${r.status} ${r.statusText}`))))
+      .then((payload) => new Promise((res, rej) =>
+        applyReplica(db, org, payload, (err, result) => (err ? rej(err) : res(result)))))
+      .then((result) => {
+        results.push({ org, ...result });
+        console.log(`Replica ${org}: ${result.users} user(s), ${result.permissions} permission(s)` +
+          (result.skipped.length ? `, skipped ${result.skipped.join(', ')} (a local account has that name)` : ''));
+        // Each replicated user's broker account, so they can connect here as well as on production
+        if (onUser) {
+          db.all('SELECT DISTINCT id FROM permissions WHERE org = ? AND id >= ?',
+            [org, REPLICA_ID_OFFSET], (err, ids) => {
+              for (const r of (ids || [])) onUser(r.id);
+              next();
+            });
+        } else {
+          next();
+        }
+      })
+      .catch((err) => {
+        // Expected whenever the link is down; the existing replica stays in place
+        console.log(`Replica ${org} not refreshed: ${err.message}`);
+        results.push({ org, error: err.message });
+        next();
+      });
+  };
+  next();
+}
+
+/*
+ * Pull now, and then on a timer.
+ *
+ * The timer lives in the server rather than in cron: it is part of being a bridge, so it should
+ * start and stop with the server rather than being a separate thing to install and remember.
+ */
+export function startReplica(config, db, deps) {
+  const settings = (config && config.replica) || {};
+  if (!settings.url) return null;
+  const seconds = Number(settings.intervalSeconds) || 900;
+  console.log(`Replicating users from ${settings.url} every ${seconds}s:`,
+    (settings.organizations || []).join(', ') || '(no organizations listed)');
+  pullReplica(config, db, deps);
+  const timer = setInterval(() => pullReplica(config, db, deps), seconds * 1000);
+  timer.unref();      // a pending timer should not hold the process open at shutdown
+  return timer;
+}

package/lib/resetcode.js

@@ -0,0 +1,103 @@
+/*
+ * Password reset codes, held nowhere.
+ *
+ * A code is an HMAC over (user id, email, current password hash, five-minute slot), keyed by a
+ * secret this process made at startup. Nothing is written to the database and nothing expires by
+ * being deleted - a code stops verifying because the slot has moved on, the password has changed,
+ * or the server has restarted. Two slots are accepted, so a code lasts between 5 and 10 minutes.
+ *
+ * Including the current hashed_password is what makes a code single-use: resetting the password
+ * changes the hash, and every code derived from the old one stops matching immediately.
+ *
+ * Two forms come out of the same digest:
+ *   code  - six digits, short enough to read off a phone and type in
+ *   token - 32 hex characters, put in the emailed link, where length costs nothing
+ * Six digits is only a million guesses, so the six-digit form is worth having only alongside the
+ * rate limiting below; the link form does not depend on it.
+ */
+import crypto from 'crypto';
+
+const SLOT_MS = 5 * 60 * 1000;   // a code is valid for its own slot and the one before it
+const SLOTS_ACCEPTED = 2;
+// Regenerated every start: a restart invalidates outstanding codes, which is the right way round.
+const secret = crypto.randomBytes(32);
+
+// Rate limits, per identifier, in memory. Lost on restart, which also invalidates every code, so
+// there is nothing to carry over. Not a defence against a distributed attacker - it is here so that
+// a million guesses at a six-digit code cannot be made in the ten minutes one is alive.
+const SEND_LIMIT = 3;            // reset emails per identifier
+const CHECK_LIMIT = 10;          // verification attempts per identifier
+const LIMIT_WINDOW_MS = 15 * 60 * 1000;
+const buckets = { send: new Map(), check: new Map() };
+
+function slotNow() { return Math.floor(Date.now() / SLOT_MS); }
+
+function digestFor(user, slot) {
+  // The password hash is a BLOB from sqlite; a user with no password yet has none.
+  const hashed = user.hashed_password ? Buffer.from(user.hashed_password).toString('hex') : '';
+  return crypto.createHmac('sha256', secret)
+    .update([user.id, user.email || '', hashed, slot].join('\n'))
+    .digest();
+}
+function formsFor(user, slot) {
+  const d = digestFor(user, slot);
+  return {
+    code: String(d.readUInt32BE(0) % 1000000).padStart(6, '0'),
+    token: d.toString('hex').slice(0, 32),
+  };
+}
+// Constant-time, and safe on differing lengths - timingSafeEqual throws on those rather than
+// returning false.
+function sameSecret(a, b) {
+  const ba = Buffer.from(String(a));
+  const bb = Buffer.from(String(b));
+  if (ba.length !== bb.length) { return false; }
+  return crypto.timingSafeEqual(ba, bb);
+}
+
+// { code, token } for the current slot - what goes in the email
+function resetCodeMake(user) {
+  return formsFor(user, slotNow());
+}
+// True if "supplied" is either form, for this slot or the one before
+function resetCodeCheck(user, supplied) {
+  if (!supplied) { return false; }
+  const now = slotNow();
+  let ok = false;
+  for (let i = 0; i < SLOTS_ACCEPTED; i++) {
+    const { code, token } = formsFor(user, now - i);
+    // No early return: keep the work the same whichever slot matches
+    ok = sameSecret(supplied, code) || sameSecret(supplied, token) || ok;
+  }
+  return ok;
+}
+
+// True if this identifier may make another attempt of this kind, and counts it if so.
+// bucket is 'send' (asking for an email) or 'check' (trying a code).
+function resetRateOk(bucket, key) {
+  const limit = (bucket === 'send') ? SEND_LIMIT : CHECK_LIMIT;
+  const map = buckets[bucket];
+  const now = Date.now();
+  const hits = (map.get(key) || []).filter((t) => (now - t) < LIMIT_WINDOW_MS);
+  if (hits.length >= limit) {
+    map.set(key, hits);
+    return false;
+  }
+  hits.push(now);
+  map.set(key, hits);
+  // Nothing else prunes this, and an attacker can name any identifier they like, so drop entries
+  // whose window has passed whenever the map gets big rather than growing without bound.
+  if (map.size > 1000) {
+    for (const [k, v] of map) {
+      if (!v.some((t) => (now - t) < LIMIT_WINDOW_MS)) { map.delete(k); }
+    }
+  }
+  return true;
+}
+// So a test can start from a clean slate without waiting out the window
+function resetRateClear() {
+  buckets.send.clear();
+  buckets.check.clear();
+}
+
+export { resetCodeMake, resetCodeCheck, resetRateOk, resetRateClear, SLOT_MS, SLOTS_ACCEPTED };

package/lib/retained.js

@@ -0,0 +1,110 @@
+/*
+ * Deleting retained messages, on the server's behalf rather than the browser's.
+ *
+ * A retained topic is removed by publishing an empty payload to it, and there is no other way: the
+ * broker keeps the last value of every topic for ever, so a misspelled field or a node tested with
+ * the wrong id goes on appearing on every dashboard after the node is fixed (see
+ * scripts/clearretained.js, which does the same thing from the command line).
+ *
+ * This used to be done by the browser, using the organization's shared broker credential. S4 gave
+ * each user their own credential instead, which may publish to "set/" topics and nothing else - so
+ * the browser's delete stopped working, and worse, stopped working SILENTLY: an MQTT 3.1.1 broker
+ * acknowledges a QoS 1 publish it is about to discard, so the client saw success and the topics
+ * stayed. That is the regression this file exists to fix.
+ *
+ * The obvious repair - let a browser publish anywhere in its organization - would hand back exactly
+ * the capability S4 removed, because the broker cannot tell "forget this reading" from "here is a
+ * reading I invented". So the publishing is done here, by the server, with an account only the
+ * server holds (names.orgAdminClient), after checking that every topic named is inside the
+ * organization the user has ADMIN of.
+ */
+
+import mqtt from 'mqtt';
+import { deriveOrgAdminPassword, names } from './dynsec-plan.js';
+
+const NAME = /^[a-z0-9]{1,32}$/;
+// One topic per node module field, and a busy organization has a few thousand. Well above anything
+// legitimate, and low enough that a mistake cannot tie the broker up for minutes.
+const MAX_TOPICS = 5000;
+
+/*
+ * Which credential to publish as.
+ *
+ * The derived per-organization admin account when there is a user_secret and the broker has the
+ * plugin; otherwise the organization's own shared account, which still exists until S8 retires it.
+ * The fallback is what makes this work on a server whose broker has no dynamic security - the same
+ * arrangement the logger uses.
+ */
+export function adminCredentialFor(config, org) {
+  const userSecret = config && config.secrets && config.secrets.user_secret;
+  if (userSecret) {
+    return { username: names.orgAdminClient(org), password: deriveOrgAdminPassword(userSecret, org) };
+  }
+  const o = (config && config.organizations && config.organizations[org]) || {};
+  if (o.mqtt_password) return { username: org, password: o.mqtt_password };
+  return null;
+}
+
+/*
+ * Publish an empty retained message to each of `topics`.
+ *
+ * cb(err, {deleted}) - err.status is an HTTP status for the route to use, because every way this
+ * can be refused is a different one.
+ */
+export function deleteRetained(config, org, topics, cb) {
+  if (!NAME.test(String(org || ''))) return refuse(cb, 400, 'Not an organization name');
+  if (!Array.isArray(topics) || !topics.length) return refuse(cb, 400, 'No topics given');
+  if (topics.length > MAX_TOPICS) return refuse(cb, 400, `More than ${MAX_TOPICS} topics at once`);
+
+  const prefix = `${org}/`;
+  for (const t of topics) {
+    if (typeof t !== 'string' || !t.length) return refuse(cb, 400, 'A topic was not a string');
+    // Inside this organization, and one exact topic - a wildcard would let "delete these" mean
+    // "delete everything", and unlike the command-line tool there is nobody here to look first.
+    if (!t.startsWith(prefix)) return refuse(cb, 403, `${t} is not in ${org}`);
+    if (t.includes('+') || t.includes('#')) return refuse(cb, 400, `${t} contains a wildcard`);
+  }
+
+  const broker = config && config.mqtt && config.mqtt.broker;
+  if (!broker) return refuse(cb, 500, 'No mqtt.broker in the configuration');
+  const cred = adminCredentialFor(config, org);
+  if (!cred) return refuse(cb, 500, `No broker credential for ${org}`);
+
+  const client = mqtt.connect(broker, {
+    username: cred.username, password: cred.password,
+    connectTimeout: 5000,
+    reconnectPeriod: 0,      // one-shot: a retry would silently double every publish
+  });
+
+  let settled = false;
+  const finish = (err, res) => {
+    if (settled) return;
+    settled = true;
+    clearTimeout(timer);
+    client.end(!!err, () => cb(err, res));
+  };
+  // Long enough for a few thousand publishes on a Pi, short enough that a wedged broker answers.
+  const timer = setTimeout(() => finish(err500('The broker did not answer')), 30000);
+
+  client.on('error', (err) => finish(refusal(502, `Could not reach the broker: ${err.message}`)));
+  client.on('connect', () => {
+    let left = topics.length;
+    let failed = 0;
+    for (const t of topics) {
+      // An empty payload is how MQTT spells "forget this topic". QoS 1 so the broker acknowledges
+      // it - though see the file header: the acknowledgement says "received", not "allowed".
+      client.publish(t, '', { retain: true, qos: 1 }, (err) => {
+        if (err) failed++;
+        if (--left === 0) finish(null, { deleted: topics.length - failed, failed });
+      });
+    }
+  });
+}
+
+function refusal(status, message) {
+  const e = new Error(message);
+  e.status = status;
+  return e;
+}
+function err500(message) { return refusal(500, message); }
+function refuse(cb, status, message) { return cb(refusal(status, message)); }

package/lib/secrets.js

@@ -0,0 +1,148 @@
+/*
+ * Secrets this server generates for itself, in config.d/secrets.yaml.
+ *
+ * frugal-iot-init writes that file, but a server upgraded from a release that predates it has none,
+ * and telling the operator to go and run init is a poor answer: the symptom (everybody logged out
+ * on every restart) does not point at the cause, so it would be lived with rather than fixed. So
+ * generate what is missing and write it down, which fixes itself once and stays fixed.
+ *
+ * Synchronous on purpose. This runs once, before the server listens, and doing it with callbacks
+ * would mean restructuring the startup sequence around a single small file write.
+ */
+
+import { randomBytes } from 'crypto';
+import { appendFileSync, chmodSync, existsSync, readFileSync, writeFileSync } from 'fs';
+
+const HEADER = `# Secrets belonging to this server. Never served to a browser - lib/config-for-user.js
+# withholds this whole section. Not in git, and worth backing up alongside frugal-iot.db.
+`;
+
+// What each secret is for, written into the file beside it so whoever reads the file later knows
+// what rotating it would cost.
+const NOTES = {
+  session_secret: 'Signs the session cookie. Changing it ends every session.',
+  user_secret: "Mixed into each user's derived MQTT password. Changing it invalidates every browser's\n# broker credential until its next login, and nothing else.",
+};
+
+// An organization's enrolment secret is written as a LIST, because rotating it means adding a new
+// one while the old is still accepted - otherwise every node already flashed with the old value,
+// and not yet enrolled, is stranded. Delete a line to withdraw that secret.
+const LIST_NOTE = (name) => {
+  const org = name.replace(/^enrolment_/, '');
+  return `Enrolment secrets for organization "${org}" - any of them is accepted by POST /enrol.
+# A node presents one once, to be issued its own broker credential; it grants nothing else, no read
+# and no write. To rotate: add a new line above and leave the old one until every node flashed with
+# it has enrolled, then delete it. To withdraw one immediately, delete its line.`;
+};
+const isList = (name) => name.startsWith('enrolment_');
+
+function generate() {
+  return randomBytes(32).toString('base64url');
+}
+
+/*
+ * Make sure every name in `names` has a value, generating and persisting any that do not.
+ *
+ * Returns { secrets, generated, written, error }:
+ *   secrets   - name -> value, always complete, so the caller can use it unconditionally
+ *   generated - names that had to be made up on this run
+ *   written   - true if they reached the file, false if they exist only for this process
+ *   error     - why the write failed, when it did
+ *
+ * A failed write is not fatal: the server works, and its sessions simply end when it restarts.
+ * That can happen legitimately - a read-only install directory, or running as a user who does not
+ * own it - so it is reported rather than thrown.
+ */
+export function ensureSecrets(existing, configDir, names) {
+  const secrets = { ...(existing || {}) };
+  const generated = names.filter((n) => !secrets[n]);
+  if (!generated.length) return { secrets, generated, written: true };
+
+  for (const n of generated) secrets[n] = isList(n) ? [generate()] : generate();
+
+  const path = `${configDir}/secrets.yaml`;
+  const body = generated.map((n) => (isList(n)
+    ? `\n# ${LIST_NOTE(n)}\n${n}:\n  - "${secrets[n][0]}"\n`
+    : `\n# ${NOTES[n] || n}\n${n}: "${secrets[n]}"\n`)).join('');
+  try {
+    if (existsSync(path)) {
+      appendFileSync(path, body);
+    } else {
+      writeFileSync(path, HEADER + body);
+    }
+    chmodSync(path, 0o600);
+    return { secrets, generated, written: true };
+  } catch (e) {
+    return { secrets, generated, written: false, error: e.message };
+  }
+}
+
+/*
+ * Adding and withdrawing an organization's enrolment secrets, for the dashboard (SECURITY.md S10).
+ *
+ * Rewrites just that organization's block, leaving the rest of the file - and its comments, which
+ * say what each secret costs to rotate - untouched. Loading and re-emitting the whole file as YAML
+ * would be less code and would throw those comments away.
+ *
+ * Synchronous, like ensureSecrets: one small file, changed by hand at human speed.
+ */
+
+const ENROL_NAME = (org) => `enrolment_${org}`;
+
+// The organization's block, whether or not it is there: "enrolment_x:" and the indented list items
+// under it. Anything else - a comment, another secret - ends the match.
+const blockFor = (org) =>
+  new RegExp(`^${ENROL_NAME(org)}:[ \\t]*\\n(?:[ \\t]+-[^\\n]*\\n)*`, 'm');
+
+function renderBlock(org, list) {
+  const items = list.map((v) => `  - "${v}"`).join('\n');
+  return `${ENROL_NAME(org)}:\n${items}${items ? '\n' : ''}`;
+}
+
+/*
+ * Write `list` as the organization's enrolment secrets.
+ *
+ * cb(err) - callers report and carry on. An unwritable file means the change lasts only until the
+ * next restart, which is worth saying rather than pretending it was saved.
+ */
+function writeEnrolmentSecrets(configDir, org, list, cb) {
+  const path = `${configDir}/secrets.yaml`;
+  try {
+    const block = renderBlock(org, list);
+    if (!existsSync(path)) {
+      writeFileSync(path, HEADER + `\n# ${LIST_NOTE(ENROL_NAME(org))}\n${block}`);
+    } else {
+      const text = readFileSync(path, 'utf8');
+      const re = blockFor(org);
+      if (re.test(text)) {
+        writeFileSync(path, text.replace(re, block));
+      } else {
+        // No block of its own yet - an organization added since the file was written
+        appendFileSync(path, `\n# ${LIST_NOTE(ENROL_NAME(org))}\n${block}`);
+      }
+    }
+    chmodSync(path, 0o600);
+    cb(null);
+  } catch (e) {
+    cb(e);
+  }
+}
+
+/*
+ * Add a secret, keeping the existing ones.
+ *
+ * That is the whole point of a list: a node already flashed with the old value, and not yet
+ * enrolled, would be stranded if adding replaced it. cb(err, {secret, list}).
+ */
+export function addEnrolmentSecret(configDir, org, current, cb) {
+  const list = [generate(), ...(current || [])];
+  writeEnrolmentSecrets(configDir, org, list, (err) => cb(err, { secret: list[0], list }));
+}
+
+// Withdraw one secret, by value. cb(err, {list, removed}).
+export function removeEnrolmentSecret(configDir, org, secret, current, cb) {
+  const list = (current || []).filter((v) => v !== secret);
+  const removed = list.length !== (current || []).length;
+  if (!removed) return cb(null, { list, removed });
+  writeEnrolmentSecrets(configDir, org, list, (err) => cb(err, { list, removed }));
+}