frugal-iot-server 0.3.9 → 2.0.0

package/lib/dynsec-sync.js

@@ -0,0 +1,209 @@
+/*
+ * Making the broker match the database, and reporting where it does not.
+ *
+ * Both directions come from lib/dynsec-plan.js, so "apply" and "check" cannot disagree about what
+ * the answer should be - which is what makes "the database is the source of truth and dynsec can be
+ * rebuilt from it" a fact rather than a claim.
+ */
+
+import { desiredRolesAndGroups, groupsForUser, groupsForNode, groupsForLogger,
+         derivePassword, deriveLoggerPassword, deriveOrgAdminPassword, names } from './dynsec-plan.js';
+
+// ---- reading the database -------------------------------------------------------------------
+// Every (org, project) any permission row mentions, plus every organization in the config, so an
+// organization with no permissions yet still gets its groups.
+export function readScopes(db, configOrgs, cb) {
+  db.all('SELECT DISTINCT org, project FROM permissions', [], (err, rows) => {
+    if (err) return cb(err);
+    const seen = new Set();
+    const scopes = [];
+    const add = (org, project) => {
+      const k = `${org} ${project || ''}`;
+      if (!seen.has(k)) { seen.add(k); scopes.push({ org, project: project || '' }); }
+    };
+    for (const org of configOrgs || []) add(org, '');
+    for (const r of rows) add(r.org, r.project);
+    cb(null, scopes);
+  });
+}
+
+// The id-0 "everyone" rows: what anybody, logged in or not, may read.
+export function readPublics(db, cb) {
+  db.all("SELECT org, project FROM permissions WHERE id = 0 AND capability = 'READ'", [], (err, rows) =>
+    err ? cb(err) : cb(null, rows.map((r) => ({ org: r.org, project: r.project || '' }))));
+}
+
+// The organization's registered projects. Used for two things that must agree: which project topics
+// a node may announce on, and which projects enrolment will accept.
+export function readProjects(db, cb) {
+  db.all('SELECT org, id AS project FROM projects', [], (err, rows) =>
+    err ? cb(err) : cb(null, rows.map((r) => ({ org: r.org, project: r.project }))));
+}
+
+// A user's effective rows - the same "or id = 0" the session itself uses, so the broker and the web
+// side can never disagree about what somebody has.
+export function readUserRows(db, id, cb) {
+  db.all('SELECT capability, org, project FROM permissions WHERE id = ? or id = 0', [id], cb);
+}
+
+// ---- applying -------------------------------------------------------------------------------
+/*
+ * Create every role and group the plan calls for, and set their ACLs. Idempotent: re-running is how
+ * the rebuild tool works, and how a release that adds a rule delivers it.
+ */
+export function applyRolesAndGroups(dynsec, scopes, publics, projects, cb) {
+  const { roles, groups } = desiredRolesAndGroups(scopes, publics, projects);
+  const create = [];
+  const acls = [];
+  for (const [rolename, list] of Object.entries(roles)) {
+    create.push({ command: 'createRole', rolename });
+    for (const a of list) {
+      acls.push({ command: 'addRoleACL', rolename, acltype: a.acltype, topic: a.topic,
+                  priority: 0, allow: !!a.allow });
+    }
+  }
+  for (const groupname of Object.keys(groups)) create.push({ command: 'createGroup', groupname });
+
+  const links = [];
+  for (const [groupname, g] of Object.entries(groups)) {
+    for (const rolename of g.roles) links.push({ command: 'addGroupRole', groupname, rolename });
+  }
+  // Unauthenticated connections land in the public group, so an embedded page needs no credential.
+  links.push({ command: 'setAnonymousGroup', groupname: names.publicGroup });
+
+  dynsec.idempotent(create, (err) => {
+    if (err) return cb(err);
+    dynsec.idempotent(acls, (err2) => {
+      if (err2) return cb(err2);
+      dynsec.idempotent(links, cb);
+    });
+  });
+}
+
+/*
+ * One user: make sure the client exists, its password is the derived one, and its group membership
+ * matches its permissions - adding and REMOVING, because a revoked permission has to take effect.
+ */
+export function applyUser(dynsec, { username, hashedPassword, rows, userSecret }, cb) {
+  const want = groupsForUser(rows);
+  const password = derivePassword(userSecret, username, hashedPassword);
+  // The broker account is "user/<login>", never the bare login - see names.userClient for why.
+  const client_id = names.userClient(username);
+  dynsec.idempotent([{ command: 'createClient', username: client_id, password }], (err) => {
+    if (err) return cb(err);
+    dynsec.getClient(client_id, (err2, client) => {
+      if (err2) return cb(err2);
+      const haveGroups = ((client && client.groups) || []).map((g) => g.groupname || g);
+      const haveRoles = ((client && client.roles) || []).map((r) => r.rolename || r);
+      const cmds = [{ command: 'setClientPassword', username: client_id, password }];
+      for (const g of want.groups) {
+        if (!haveGroups.includes(g)) cmds.push({ command: 'addGroupClient', groupname: g, username: client_id });
+      }
+      for (const g of haveGroups) {
+        if (!want.groups.includes(g) && g !== names.publicGroup) {
+          cmds.push({ command: 'removeGroupClient', groupname: g, username: client_id });
+        }
+      }
+      // Only roles the client does not already have. Re-adding one answers "Internal error", which
+      // says nothing about what is wrong and is not distinguishable from a real failure - the same
+      // wording mosquitto_ctrl gets, so it is the plugin's, not ours. Reading the client first and
+      // sending only what is missing avoids having to interpret it at all.
+      for (const r of want.roles) {
+        if (!haveRoles.includes(r)) cmds.push({ command: 'addClientRole', username: client_id, rolename: r });
+      }
+      dynsec.idempotent(cmds, (err3) => cb(err3, { username: client_id, password, groups: want.groups }));
+    });
+  });
+}
+
+// One node. Its password is random and stored in the database, not derived - a node keeps its copy
+// in LittleFS and cannot recompute anything (SECURITY-REVIEW.md section 9).
+export function applyNode(dynsec, { org, project, nodeid, password, lora }, cb) {
+  const username = names.nodeClient(org, project, nodeid);
+  const groups = groupsForNode(org, project, { lora });
+  dynsec.idempotent([{ command: 'createClient', username, password }], (err) => {
+    if (err) return cb(err);
+    const cmds = [{ command: 'setClientPassword', username, password }];
+    for (const g of groups) cmds.push({ command: 'addGroupClient', groupname: g, username });
+    dynsec.idempotent(cmds, (err2) => cb(err2, { username, groups }));
+  });
+}
+
+/*
+ * The logger's account for one organization. Its password is derived, so this is safe to re-run and
+ * the server can compute the same value to hand the logger at startup.
+ */
+export function applyLogger(dynsec, { org, userSecret }, cb) {
+  const username = names.loggerClient(org);
+  const password = deriveLoggerPassword(userSecret, org);
+  const groups = groupsForLogger(org);
+  dynsec.idempotent([{ command: 'createClient', username, password }], (err) => {
+    if (err) return cb(err);
+    dynsec.getClient(username, (err2, client) => {
+      if (err2) return cb(err2);
+      const have = ((client && client.groups) || []).map((g) => g.groupname || g);
+      const cmds = [{ command: 'setClientPassword', username, password }];
+      for (const g of groups) {
+        if (!have.includes(g)) cmds.push({ command: 'addGroupClient', groupname: g, username });
+      }
+      dynsec.idempotent(cmds, (err3) => cb(err3, { username, password, groups }));
+    });
+  });
+}
+
+/*
+ * The server's administrative account for one organization. Given the clear role DIRECTLY rather
+ * than through a group, so there is no group anything else could be added to by mistake.
+ */
+export function applyOrgAdmin(dynsec, { org, userSecret }, cb) {
+  const username = names.orgAdminClient(org);
+  const password = deriveOrgAdminPassword(userSecret, org);
+  const role = names.clearRole(org);
+  dynsec.idempotent([{ command: 'createClient', username, password }], (err) => {
+    if (err) return cb(err);
+    dynsec.getClient(username, (err2, client) => {
+      if (err2) return cb(err2);
+      const haveRoles = ((client && client.roles) || []).map((r) => r.rolename || r);
+      const cmds = [{ command: 'setClientPassword', username, password }];
+      if (!haveRoles.includes(role)) cmds.push({ command: 'addClientRole', username, rolename: role });
+      dynsec.idempotent(cmds, (err3) => cb(err3, { username, password }));
+    });
+  });
+}
+
+export function removeUser(dynsec, username, cb) {
+  dynsec.raw([{ command: 'deleteClient', username: names.userClient(username) }], (err) => {
+    if (err && /not found/i.test(err.message)) return cb(null);
+    cb(err);
+  });
+}
+
+// ---- checking -------------------------------------------------------------------------------
+/*
+ * What differs between the database and the broker, changing nothing. This is what
+ * frugal-iot-rebuild-dynsec --check reports and what scripts/diagnostic.zsh calls: reporting drift
+ * is useful more often than repairing it.
+ */
+export function checkRolesAndGroups(dynsec, scopes, publics, projects, cb) {
+  const { roles, groups } = desiredRolesAndGroups(scopes, publics, projects);
+  const differences = [];
+  dynsec.listRoles((err, haveRoles) => {
+    if (err) return cb(err);
+    for (const r of Object.keys(roles)) {
+      if (!haveRoles.includes(r)) differences.push(`role missing: ${r}`);
+    }
+    dynsec.listGroups((err2, haveGroups) => {
+      if (err2) return cb(err2);
+      for (const g of Object.keys(groups)) {
+        if (!haveGroups.includes(g)) differences.push(`group missing: ${g}`);
+      }
+      dynsec.getAnonymousGroup((err3, anon) => {
+        // Not an error if the plugin will not say - only report a definite mismatch
+        if (!err3 && anon !== names.publicGroup) {
+          differences.push(`anonymous group is ${anon || '(unset)'}, expected ${names.publicGroup}`);
+        }
+        cb(null, differences);
+      });
+    });
+  });
+}

package/lib/dynsec.js

@@ -0,0 +1,166 @@
+/*
+ * Talking to mosquitto's dynamic security plugin, over MQTT.
+ *
+ * The plugin is driven by publishing JSON to $CONTROL/dynamic-security/v1 and reading the reply on
+ * the same topic - so the server needs no file access to the broker and no sudo, which is most of
+ * why dynsec is worth having (SECURITY-REVIEW.md section 2, Tier 3).
+ *
+ * Callbacks rather than promises, per claude.md.
+ */
+
+import mqtt from 'mqtt';
+
+// Commands go to one topic and replies come back on ANOTHER - the command topic with "/response"
+// appended. Subscribing to the command topic (the obvious guess) gets no reply ever, while the
+// commands themselves still execute, so it fails in the most confusing possible way: things happen
+// and nothing answers. Confirmed from the broker's own log:
+//   Received PUBLISH from ... '$CONTROL/dynamic-security/v1'
+//   Sending  PUBLISH to   ... '$CONTROL/dynamic-security/v1/response'
+const CONTROL = '$CONTROL/dynamic-security/v1';
+const RESPONSE = '$CONTROL/dynamic-security/v1/response';
+
+/*
+ * Connect as the dynsec admin. config is the whole configuration; the credential comes from
+ * config.secrets, written by frugal-iot-init and never served to a browser.
+ *
+ * cb(err, dynsec). A failure here must not be fatal to the caller: the dashboard is more useful
+ * without live broker accounts than not at all, so callers log and carry on.
+ */
+// Nothing here may hang. A command that gets no reply - a broker without the plugin, an account
+// whose role does not permit $CONTROL, a dropped connection - would otherwise leave the caller
+// waiting for ever, which is what the first version of scripts/rebuild-dynsec.js did.
+const REPLY_TIMEOUT_MS = 10000;
+
+export function dynsecConnect(config, cb) {
+  const secrets = (config && config.secrets) || {};
+  const broker = config && config.mqtt && config.mqtt.broker;
+  if (!broker) return cb(new Error('No mqtt.broker in the configuration'));
+  if (!secrets.dynsec_admin_user || !secrets.dynsec_admin_password) {
+    return cb(new Error('No dynsec_admin_user/password in config.d/secrets.yaml - run frugal-iot-init'));
+  }
+
+  const client = mqtt.connect(broker, {
+    username: secrets.dynsec_admin_user,
+    password: secrets.dynsec_admin_password,
+    connectTimeout: 5000,
+    reconnectPeriod: 0,        // a one-shot: callers reconnect rather than queueing behind a retry
+  });
+
+  let settled = false;
+  const waiting = [];          // FIFO of {cb, timer}, one per command batch sent
+
+  const answer = (err, res) => {
+    const next = waiting.shift();
+    if (!next) return;         // unsolicited, or a reply that arrived after we gave up
+    clearTimeout(next.timer);
+    next.cb(err, res);
+  };
+
+  client.on('message', (topic, payload) => {
+    let parsed;
+    try { parsed = JSON.parse(payload.toString()); } catch (e) { parsed = null; }
+    if (!parsed || !parsed.responses) return answer(new Error('Unreadable reply from the plugin'));
+    // Every command in the batch has its own response; the first error is the useful one.
+    const bad = parsed.responses.find((r) => r.error);
+    if (bad) return answer(new Error(`${bad.command}: ${bad.error}`), parsed.responses);
+    answer(null, parsed.responses);
+  });
+
+  client.on('error', (err) => {
+    if (!settled) { settled = true; client.end(true); return cb(err); }
+    answer(err);               // in flight when the connection failed
+  });
+  client.on('close', () => { if (settled) answer(new Error('Connection to the broker closed')); });
+
+  // A connect that never completes has to fail too, not wait.
+  const connectTimer = setTimeout(() => {
+    if (!settled) {
+      settled = true;
+      client.end(true);
+      cb(new Error(`No answer from the broker at ${broker} within ${REPLY_TIMEOUT_MS}ms`));
+    }
+  }, REPLY_TIMEOUT_MS);
+
+  client.on('connect', () => {
+    client.subscribe(RESPONSE, { qos: 1 }, (err) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(connectTimer);
+      if (err) { client.end(true); return cb(err); }
+      cb(null, makeApi(client, waiting));
+    });
+  });
+}
+
+function makeApi(client, waiting) {
+  // Send a batch and call back once with its combined result. Batching matters: creating a role and
+  // its ACLs is several commands, and one round trip per batch keeps a rebuild quick.
+  function send(commands, cb) {
+    cb = cb || (() => {});
+    if (!commands.length) return cb(null, []);
+    let done = false;
+    const once = (err, res) => { if (!done) { done = true; cb(err, res); } };
+    const entry = {
+      cb: once,
+      timer: setTimeout(() => {
+        const i = waiting.indexOf(entry);
+        if (i >= 0) waiting.splice(i, 1);
+        once(new Error(`The plugin did not answer ${commands[0].command} within ${REPLY_TIMEOUT_MS}ms`));
+      }, REPLY_TIMEOUT_MS),
+    };
+    waiting.push(entry);
+    client.publish(CONTROL, JSON.stringify({ commands }), { qos: 1 }, (err) => {
+      if (err) {
+        const i = waiting.indexOf(entry);
+        if (i >= 0) waiting.splice(i, 1);
+        clearTimeout(entry.timer);
+        once(err);
+      }
+    });
+  }
+
+  /*
+   * For commands that create or add: succeeding and "it was already like that" are the same outcome,
+   * because every one of these is re-run - by the rebuild tool, at each login, and by a release that
+   * adds a rule.
+   *
+   * Matching on /already/ rather than a list of exact strings, because the plugin has a different
+   * wording for each command and getting one wrong makes a re-run FAIL rather than do nothing:
+   * "Role already exists", "Group already exists", "Client already exists", "Group is already in
+   * this role", "Client is already in this group"... The first version listed only the "already
+   * exists" ones, so the second apply aborted on addGroupRole before it reached the users, and a
+   * permission granted in the database never arrived at the broker.
+   *
+   * Safe to be broad here because this path is only ever given create/add commands - removals go
+   * through raw(), where an error is an error.
+   */
+  function sendIgnoringExists(commands, cb) {
+    send(commands, (err, res) => {
+      if (err && /already/i.test(err.message)) return cb(null, res);
+      cb(err, res);
+    });
+  }
+
+  return {
+    raw: send,
+    idempotent: sendIgnoringExists,
+    end: (cb) => client.end(false, {}, cb),
+
+    listClients: (cb) => send([{ command: 'listClients', count: -1 }],
+      (e, r) => cb(e, e ? null : ((r[0].data && r[0].data.clients) || []))),
+    getClient: (username, cb) => send([{ command: 'getClient', username }],
+      (e, r) => cb(e, e ? null : (r[0].data && r[0].data.client))),
+    listGroups: (cb) => send([{ command: 'listGroups', count: -1 }],
+      (e, r) => cb(e, e ? null : ((r[0].data && r[0].data.groups) || []))),
+    getGroup: (groupname, cb) => send([{ command: 'getGroup', groupname }],
+      (e, r) => cb(e, e ? null : (r[0].data && r[0].data.group))),
+    listRoles: (cb) => send([{ command: 'listRoles', count: -1 }],
+      (e, r) => cb(e, e ? null : ((r[0].data && r[0].data.roles) || []))),
+    getRole: (rolename, cb) => send([{ command: 'getRole', rolename }],
+      (e, r) => cb(e, e ? null : (r[0].data && r[0].data.role))),
+    getAnonymousGroup: (cb) => send([{ command: 'getAnonymousGroup' }],
+      (e, r) => cb(e, e ? null : (r[0].data && r[0].data.group && r[0].data.group.groupname))),
+  };
+}
+
+export { CONTROL, RESPONSE };

package/lib/enrol.js

@@ -0,0 +1,288 @@
+/*
+ * Node enrolment: how a node gets its own broker credential.
+ *
+ * The problem this solves (SECURITY-REVIEW.md section 6): every node has the organization's shared
+ * broker password compiled into its firmware, so extracting one node's flash yields a credential
+ * for everything, and it cannot be rotated without reflashing the fleet. It has to be replaced by a
+ * per-node credential the node fetches for itself - because most nodes are flashed from PlatformIO
+ * or the Arduino IDE with no dashboard involved, and waiting for a human to approve each one does
+ * not work in practice.
+ *
+ * So: the firmware carries an ENROLMENT SECRET, which grants exactly one thing - "create a node in
+ * this organization". No read, no write, no broker access at all. It is rate limited, per
+ * organization, and revocable server-side without reflashing anything, none of which is true of the
+ * broker password it replaces.
+ *
+ * The one weakness, and why the 409 below exists: a node id is derived from the chip's MAC, so it is
+ * public and anyone can claim to be one. If the server re-issued a credential to any request quoting
+ * an existing node id, the enrolment secret would become "impersonate any node in the organization",
+ * which is the isolation this whole step exists to create. So a node that already exists must prove
+ * it holds the current password.
+ */
+
+import { randomBytes } from 'crypto';
+
+// How enrolment can fail, in a shape the route can turn into a status code. Deliberately vague to
+// the caller about WHY a secret was refused - a node has no use for the difference, and an attacker
+// probing organization names should not learn which ones exist.
+export const ENROL = {
+  BAD_REQUEST: 'bad_request',
+  REFUSED: 'refused',            // wrong or unknown secret, or unknown organization
+  RATE_LIMITED: 'rate_limited',
+  NEEDS_RESET: 'needs_reset',    // known node, no proof of its current password
+  NO_PROJECT: 'no_such_project',  // the organization has no project of that name
+  DENIED: 'denied',              // an admin has denied this node
+  BROKER: 'broker_unavailable',
+};
+
+class EnrolError extends Error {
+  constructor(code, message) { super(message); this.code = code; }
+}
+
+/*
+ * Which enrolment secrets an organization accepts.
+ *
+ * A LIST, not one secret, so a secret can be rotated without stranding nodes that were flashed with
+ * the old one and have not enrolled yet. Any secret in the list is accepted; a compromised one is
+ * deleted by hand. A node that has already enrolled never presents one again, so it is unaffected
+ * either way.
+ *
+ * Per organization, and that matters: an admin who shares their organization's secret, or leaks it
+ * in a firmware image, must not thereby let anyone enrol nodes into a different organization.
+ */
+export function enrolmentSecretsFor(config, org) {
+  const s = (config && config.secrets && config.secrets[`enrolment_${org}`]);
+  if (!s) return [];
+  return (Array.isArray(s) ? s : [s]).map(String).filter((x) => x.length);
+}
+
+// Constant-time-ish comparison. The secrets are long random strings, so a timing attack is not the
+// realistic threat here, but there is no reason to leak a prefix match either.
+function sameSecret(a, b) {
+  if (a.length !== b.length) return false;
+  let differing = 0;
+  for (let i = 0; i < a.length; i++) differing |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  return differing === 0;
+}
+
+/*
+ * Rate limiting, in memory.
+ *
+ * Two counters, because they answer different questions: per organization stops somebody with a
+ * leaked secret filling the database with invented nodes, and per node id stops repeated attempts
+ * against one real node. In memory is enough - it survives as long as the process, a restart is a
+ * fair reset, and persisting it would mean a disk write per attempt.
+ */
+export function makeRateLimiter({ perOrg = 20, perNode = 5, windowMs = 3600000, now = Date.now } = {}) {
+  const hits = new Map();   // key -> [timestamps]
+  const record = (key, limit) => {
+    const t = now();
+    const kept = (hits.get(key) || []).filter((x) => x > t - windowMs);
+    kept.push(t);
+    hits.set(key, kept);
+    return kept.length <= limit;
+  };
+  return {
+    allow(org, nodeid) {
+      // Both are recorded even if the first refuses, so a flood counts against the organization
+      const orgOk = record(`org:${org}`, perOrg);
+      const nodeOk = record(`node:${org}/${nodeid}`, perNode);
+      return orgOk && nodeOk;
+    },
+    // For tests and for a successful enrolment, which should not count against the limit
+    forget(org, nodeid) { hits.delete(`org:${org}`); hits.delete(`node:${org}/${nodeid}`); },
+  };
+}
+
+const NODEID = /^[A-Za-z0-9_-]{1,64}$/;
+const NAME = /^[a-z0-9]{1,32}$/;
+
+/*
+ * The record of nodes that asked and were refused, for the dashboard's Nodes card (SECURITY.md S12).
+ *
+ * This is how an admin learns a node's id at all: an id is not discoverable from the server, but a
+ * node that keeps asking puts itself in this list, and the admin approves it from there. The rows
+ * are therefore UNTRUSTED - anyone can make an id appear by attempting enrolment - so each keeps
+ * when it asked and from where, for the admin to recognise rather than to trust.
+ *
+ * In memory, and bounded. The nodes table deliberately has no last_seen column because that would
+ * be a database write per reading on an SD card; a write per enrolment attempt is the same mistake
+ * on a smaller scale. Losing the list on restart costs nothing: a node that is still retrying
+ * reappears within minutes.
+ */
+export function makeAttemptLog({ perOrg = 50, now = Date.now } = {}) {
+  const rows = new Map();   // "org/nodeid" -> {org, project, nodeid, at, from, reason, count}
+  return {
+    record({ org, project, nodeid, from, reason }) {
+      const key = `${org}/${nodeid}`;
+      const existing = rows.get(key);
+      rows.set(key, {
+        org, project, nodeid, from, reason,
+        at: now(),
+        count: existing ? existing.count + 1 : 1,
+      });
+      // Oldest out first, per organization, so one organization cannot crowd out another
+      const mine = [...rows.values()].filter((r) => r.org === org).sort((a, b) => a.at - b.at);
+      for (const r of mine.slice(0, Math.max(0, mine.length - perOrg))) rows.delete(`${r.org}/${r.nodeid}`);
+    },
+    forOrg(org) { return [...rows.values()].filter((r) => r.org === org); },
+    forget(org, nodeid) { rows.delete(`${org}/${nodeid}`); },
+  };
+}
+
+// An admin's decision about one node, from the node_grants table
+export function readGrant(db, org, nodeid, cb) {
+  db.get('SELECT state, project FROM node_grants WHERE org = ? AND nodeid = ?', [org, nodeid], cb);
+}
+export function setGrant(db, { org, project, nodeid, state, by }, cb) {
+  db.run(`INSERT INTO node_grants (org, project, nodeid, state, created_by, created_at)
+          VALUES (?, ?, ?, ?, ?, ?)
+          ON CONFLICT(org, nodeid)
+          DO UPDATE SET project = excluded.project, state = excluded.state,
+                        created_by = excluded.created_by, created_at = excluded.created_at`,
+    [org, project || '', nodeid, state, by || '', Date.now()], cb);
+}
+export function clearGrant(db, org, nodeid, cb) {
+  db.run('DELETE FROM node_grants WHERE org = ? AND nodeid = ?', [org, nodeid],
+    function (err) { cb(err, this && this.changes); });
+}
+export function readGrants(db, org, cb) {
+  db.all('SELECT project, nodeid, state, created_by, created_at FROM node_grants WHERE org = ?',
+    [org], cb);
+}
+
+/*
+ * Handle one enrolment request.
+ *
+ * deps: { db, config, limiter, syncNode, attempts?, from? }
+ *   syncNode(node, cb)  creates the broker account
+ *   attempts            makeAttemptLog(), so a refusal reaches the dashboard's Nodes card
+ *   from                the caller's address, recorded with a refusal
+ * body: { org, project, nodeid, enrolment_secret, current_password?, lora? }
+ *
+ * cb(err, { username, password }) - err.code is one of ENROL above.
+ */
+export function enrol(deps, body, cb) {
+  const { db, config, limiter, syncNode, attempts, from } = deps;
+  // Every refusal past the shape check is worth showing an admin: it is the only way they learn
+  // that a node exists and is asking. The shape check is not - a request that is not even
+  // org/project/nodeid tells them nothing they could act on.
+  const refuse = (code, message) => {
+    if (attempts) {
+      attempts.record({
+        org: String((body && body.org) || ''), project: String((body && body.project) || ''),
+        nodeid: String((body && body.nodeid) || ''), from, reason: code,
+      });
+    }
+    return cb(new EnrolError(code, message));
+  };
+  const org = String((body && body.org) || '');
+  const project = String((body && body.project) || '');
+  const nodeid = String((body && body.nodeid) || '');
+  const secret = String((body && body.enrolment_secret) || '');
+  const lora = !!(body && body.lora);
+
+  if (!NAME.test(org) || !NAME.test(project) || !NODEID.test(nodeid)) {
+    return cb(new EnrolError(ENROL.BAD_REQUEST, 'org, project and nodeid are required and must be plain names'));
+  }
+
+  if (limiter && !limiter.allow(org, nodeid)) {
+    return refuse(ENROL.RATE_LIMITED, 'Too many enrolment attempts - try later');
+  }
+
+  /*
+   * What the admin has decided about this node, before anything else is considered.
+   *
+   *   denied    refused whatever it presents, and the reason it is checked before the secret: a
+   *             denied node usually still holds a perfectly good secret.
+   *   approved  the secret is not required, and neither is proof of a current password - which is
+   *             the whole point, since this exists for a node that can prove nothing. Consumed on
+   *             success, so one approval admits one node once.
+   *
+   * The project must still be registered either way. An approval says "this node may enrol", not
+   * "invent whatever structure it asks for".
+   */
+  readGrant(db, org, nodeid, (gerr, grant) => {
+    if (gerr) return cb(gerr);
+    if (grant && grant.state === 'denied') {
+      return refuse(ENROL.DENIED, 'This node has been denied by an administrator');
+    }
+    const approved = !!(grant && grant.state === 'approved');
+
+    if (!approved) {
+      // A missing secret is a refusal, not a malformed request - a node flashed with none is
+      // precisely the node an admin may want to approve, so it has to reach the list above rather
+      // than being turned away as a bad request.
+      const accepted = enrolmentSecretsFor(config, org);
+      if (!secret || !accepted.some((x) => sameSecret(x, secret))) {
+        // Same answer whether the organization does not exist or the secret is wrong
+        return refuse(ENROL.REFUSED, 'Enrolment refused');
+      }
+    }
+
+  /*
+   * The project has to be one the organization has actually registered.
+   *
+   * Without this, a project name mistyped into a node's captive portal is accepted, gets its own
+   * broker account, and then appears in the dashboard as a project with a node in it - inventing
+   * organisation structure from a typo. The admin dashboard's Projects tab is where projects are
+   * added, so the fix is in the operator's hands and the error below says so.
+   */
+  db.get('SELECT 1 AS ok FROM projects WHERE org = ? AND id = ?', [org, project], (perr, known) => {
+    if (perr) return cb(perr);
+    if (!known) {
+      return refuse(ENROL.NO_PROJECT,
+        `Organization ${org} has no project "${project}". Check the spelling on the node, or add ` +
+        `the project on the dashboard's Projects tab, then let the node try again.`);
+    }
+    db.get('SELECT password FROM nodes WHERE org = ? AND project = ? AND nodeid = ?',
+    [org, project, nodeid], (err, existing) => {
+      if (err) return cb(err);
+
+      if (existing && !approved) {
+        const proof = String((body && body.current_password) || '');
+        if (!proof || !sameSecret(existing.password, proof)) {
+          // Trust on first use, and only on first use. See the note at the top of this file.
+          return refuse(ENROL.NEEDS_RESET,
+            'This node is already enrolled. Only the node itself can be issued a new credential; ' +
+            'if its filesystem was erased, an administrator can approve it on the dashboard, or ' +
+            'clear the binding with frugal-iot-resetnode.');
+        }
+      }
+
+      const password = randomBytes(24).toString('base64url');
+      const node = { org, project, nodeid, password, lora };
+      // The broker first: a node that stored a credential the broker does not know would be unable
+      // to connect AND unable to re-enrol, because it has one. Better to refuse and let it retry.
+      syncNode(node, (serr) => {
+        if (serr) {
+          return refuse(ENROL.BROKER,
+            'The broker could not be updated - not issuing a credential that would not work');
+        }
+        db.run(`INSERT INTO nodes (org, project, nodeid, password, lora, enrolled_at)
+                VALUES (?, ?, ?, ?, ?, ?)
+                ON CONFLICT(org, project, nodeid)
+                DO UPDATE SET password = excluded.password, lora = excluded.lora,
+                              enrolled_at = excluded.enrolled_at`,
+          [org, project, nodeid, password, lora ? 1 : 0, Date.now()], (ierr) => {
+            if (ierr) return cb(ierr);
+            if (limiter) limiter.forget(org, nodeid);   // success is not an attempt worth counting
+            if (attempts) attempts.forget(org, nodeid); // nor a failure still worth showing
+            const done = () => cb(null, { username: `${org}/${project}/${nodeid}`, password });
+            // An approval admits one node once. Left in place it would be a standing invitation to
+            // anyone quoting a public node id.
+            if (approved) return clearGrant(db, org, nodeid, done);
+            done();
+          });
+      });
+    });
+  });
+  });
+}
+
+// Forget a node, so it can enrol afresh - for a node whose filesystem was erased and which
+// therefore cannot prove anything. The one human step, and only in recovery.
+export function forgetNode(db, org, project, nodeid, cb) {
+  db.run('DELETE FROM nodes WHERE org = ? AND project = ? AND nodeid = ?',
+    [org, project, nodeid], function (err) { cb(err, this && this.changes); });
+}