smart-home-engine 1.0.10 → 1.1.0

package/src/lib/dynsec.js

@@ -0,0 +1,295 @@
+'use strict';
+
+/**
+ * dynsec — Dynamic Security plugin client for Mosquitto.
+ *
+ * Creates a dedicated MQTT connection using the she-admin credentials from
+ * config.broker.dynsec.{adminUsername, adminPassword}. All dynsec commands
+ * are serialised through a single-inflight request queue so concurrent calls
+ * do not confuse the response-correlation logic (the dynsec protocol has no
+ * request IDs).
+ *
+ * Usage:
+ *   const dynsec = require('./dynsec');
+ *   dynsec.init(config, log);
+ *
+ *   const { connected } = dynsec.getStatus();
+ *   const users = await dynsec.listClients(true);
+ */
+
+const mqtt = require('mqtt');
+
+const CONTROL_TOPIC = '$CONTROL/dynamic-security/v1';
+const RESPONSE_TOPIC = '$CONTROL/dynamic-security/v1/response';
+
+let _client = null;
+let _connected = false;
+let _configured = false;
+let _timeout = 5000;
+let _log = null;
+
+// Serial request queue — one in-flight request at a time
+const _queue = [];
+let _inflight = false;
+let _inflightResolve = null;
+
+function _drain() {
+    if (_inflight || _queue.length === 0 || !_connected) return;
+
+    const { command, payload, resolve, reject } = _queue.shift();
+    _inflight = true;
+
+    const timer = setTimeout(() => {
+        _inflight = false;
+        _inflightResolve = null;
+        reject(new Error(`dynsec timeout waiting for response to "${command}"`));
+        _drain();
+    }, _timeout);
+
+    _inflightResolve = (responses) => {
+        clearTimeout(timer);
+        _inflight = false;
+        _inflightResolve = null;
+        const r = responses.find((resp) => resp.command === command);
+        if (r && r.error) {
+            reject(new Error(r.error));
+        } else {
+            resolve(r || {});
+        }
+        _drain();
+    };
+
+    _client.publish(CONTROL_TOPIC, JSON.stringify({ commands: [{ command, ...payload }] }));
+}
+
+function _request(command, payload = {}) {
+    if (!_configured) {
+        return Promise.reject(new Error('she.broker: dynsec not configured — set broker.dynsec in config.json'));
+    }
+    if (!_connected) {
+        return Promise.reject(new Error('she.broker: dynsec not connected'));
+    }
+    return new Promise((resolve, reject) => {
+        _queue.push({ command, payload, resolve, reject });
+        _drain();
+    });
+}
+
+/**
+ * Initialise the dynsec client. No-op if broker.dynsec is not set in config.
+ * @param {object} config   - she config object
+ * @param {object} log      - she log object
+ */
+function init(config, log) {
+    _log = log;
+    _timeout = (config.broker && config.broker.apiTimeout) || 5000;
+
+    const dynsecCfg = config.broker && config.broker.dynsec;
+    if (!dynsecCfg || !dynsecCfg.adminUsername || !dynsecCfg.adminPassword) {
+        _log.debug('dynsec: not configured, she.broker API disabled');
+        return;
+    }
+    if (!config.url) {
+        _log.warn('dynsec: no broker URL configured, she.broker API disabled');
+        return;
+    }
+
+    _configured = true;
+
+    const opts = {
+        username: dynsecCfg.adminUsername,
+        password: dynsecCfg.adminPassword,
+        clientId: 'she-dynsec-' + Math.random().toString(16).slice(2, 10),
+        clean: true,
+    };
+    // Inherit TLS options from main config so dynsec works over TLS-secured brokers
+    if (config.mqttCa) opts.ca = config.mqttCa;
+    if (config.mqttCert) opts.cert = config.mqttCert;
+    if (config.mqttKey) opts.key = config.mqttKey;
+    if (config.mqttVersion === '5') opts.protocolVersion = 5;
+
+    _client = mqtt.connect(config.url, opts);
+
+    _client.on('connect', () => {
+        _connected = true;
+        _log.info('dynsec: connected as', dynsecCfg.adminUsername);
+        _client.subscribe(RESPONSE_TOPIC, (err) => {
+            if (err) _log.error('dynsec: failed to subscribe to response topic:', err.message);
+            else _drain(); // flush any requests queued before connection
+        });
+    });
+
+    _client.on('close', () => {
+        if (_connected) {
+            _connected = false;
+            _log.warn('dynsec: disconnected');
+        }
+    });
+
+    _client.on('error', (err) => {
+        _log.error('dynsec: MQTT error:', err.message);
+    });
+
+    _client.on('message', (topic, payload) => {
+        if (topic !== RESPONSE_TOPIC) return;
+        let msg;
+        try {
+            msg = JSON.parse(payload.toString());
+        } catch {
+            _log.error('dynsec: invalid JSON on response topic');
+            return;
+        }
+        if (_inflightResolve && Array.isArray(msg.responses)) {
+            _inflightResolve(msg.responses);
+        }
+    });
+}
+
+/** @returns {{ connected: boolean, configured: boolean }} */
+function getStatus() {
+    return { connected: _connected, configured: _configured };
+}
+
+// ── User management ────────────────────────────────────────────────────────────
+
+function createClient(username, password, options = {}) {
+    return _request('createClient', { username, password, ...options });
+}
+
+function deleteClient(username) {
+    return _request('deleteClient', { username });
+}
+
+function setClientPassword(username, password) {
+    return _request('modifyClient', { username, password });
+}
+
+function listClients(verbose = false) {
+    return _request('listClients', { verbose }).then((r) => r.clients || []);
+}
+
+function getClient(username) {
+    return _request('getClient', { username }).then((r) => r.client);
+}
+
+// ── Role management ────────────────────────────────────────────────────────────
+
+function createRole(rolename, options = {}) {
+    return _request('createRole', { rolename, ...options });
+}
+
+function deleteRole(rolename) {
+    return _request('deleteRole', { rolename });
+}
+
+function listRoles(verbose = false) {
+    return _request('listRoles', { verbose }).then((r) => r.roles || []);
+}
+
+function getRole(rolename) {
+    return _request('getRole', { rolename }).then((r) => r.role);
+}
+
+/**
+ * @param {string} rolename
+ * @param {string} acltype  'publishClientSend'|'publishClientReceive'|
+ *                          'subscribeLiteral'|'subscribePattern'|
+ *                          'unsubscribeLiteral'|'unsubscribePattern'
+ * @param {string}  topic
+ * @param {boolean} allow
+ * @param {number}  [priority=-1]
+ */
+function addRoleACL(rolename, acltype, topic, allow, priority = -1) {
+    return _request('addRoleACL', { rolename, acltype, topic, allow, priority });
+}
+
+function removeRoleACL(rolename, acltype, topic) {
+    return _request('removeRoleACL', { rolename, acltype, topic });
+}
+
+// ── Role ↔ client assignment ───────────────────────────────────────────────────
+
+function addClientRole(username, rolename, priority = -1) {
+    return _request('addClientRole', { username, rolename, priority });
+}
+
+function removeClientRole(username, rolename) {
+    return _request('removeClientRole', { username, rolename });
+}
+
+// ── Group management ───────────────────────────────────────────────────────────
+
+function createGroup(groupname) {
+    return _request('createGroup', { groupname });
+}
+
+function deleteGroup(groupname) {
+    return _request('deleteGroup', { groupname });
+}
+
+function listGroups(verbose = false) {
+    return _request('listGroups', { verbose }).then((r) => r.groups || []);
+}
+
+function getGroup(groupname) {
+    return _request('getGroup', { groupname }).then((r) => r.group);
+}
+
+function addGroupClient(groupname, username, priority = -1) {
+    return _request('addGroupClient', { groupname, username, priority });
+}
+
+function removeGroupClient(groupname, username) {
+    return _request('removeGroupClient', { groupname, username });
+}
+
+function addGroupRole(groupname, rolename, priority = -1) {
+    return _request('addGroupRole', { groupname, rolename, priority });
+}
+
+function removeGroupRole(groupname, rolename) {
+    return _request('removeGroupRole', { groupname, rolename });
+}
+
+// ── Default ACL access ─────────────────────────────────────────────────────────
+
+function getDefaultACLAccess() {
+    return _request('getDefaultACLAccess').then((r) => r.acls || []);
+}
+
+function setDefaultACLAccess(acls) {
+    return _request('setDefaultACLAccess', { acls });
+}
+
+module.exports = {
+    init,
+    getStatus,
+    // Users
+    createClient,
+    deleteClient,
+    setClientPassword,
+    listClients,
+    getClient,
+    // Roles
+    createRole,
+    deleteRole,
+    listRoles,
+    getRole,
+    addRoleACL,
+    removeRoleACL,
+    // Role assignments
+    addClientRole,
+    removeClientRole,
+    // Groups
+    createGroup,
+    deleteGroup,
+    listGroups,
+    getGroup,
+    addGroupClient,
+    removeGroupClient,
+    addGroupRole,
+    removeGroupRole,
+    // Default ACLs
+    getDefaultACLAccess,
+    setDefaultACLAccess,
+};

package/src/lib/mosquitto-conf.js

@@ -0,0 +1,287 @@
+'use strict';
+
+/**
+ * mosquitto-conf — parser, writer and reload helper for mosquitto.conf.
+ *
+ * she "owns" a single managed config file (path configured at
+ * config.broker.configDir + '/mosquitto.conf'). It reads the file, merges
+ * managed sections, and writes it back with a timestamped backup.
+ *
+ * Managed keys handled via structured API:
+ *   - listener blocks (each keyed by port)
+ *   - plugin (dynsec)
+ *   - log_dest / log_type
+ *   - persistence / persistence_location
+ *   - allow_anonymous
+ *
+ * Everything else is preserved verbatim in the "advanced" passthrough block.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const { execFile } = require('child_process');
+const { promisify } = require('util');
+
+const execFileAsync = promisify(execFile);
+
+// Keys that she manages — all others are treated as passthrough
+const MANAGED_SINGLE_KEYS = new Set(['allow_anonymous', 'persistence', 'persistence_location', 'log_dest', 'log_type', 'plugin', 'plugin_opt_dynsec_config_file']);
+
+/**
+ * Parse a mosquitto.conf file into a structured object.
+ *
+ * @param {string} filePath
+ * @returns {{ listeners: object[], managed: object, passthrough: string[], raw: string }}
+ */
+function parse(filePath) {
+    let raw = '';
+    try {
+        raw = fs.readFileSync(filePath, 'utf8');
+    } catch (err) {
+        if (err.code !== 'ENOENT') throw err;
+        return { listeners: [], managed: {}, passthrough: [], raw: '' };
+    }
+
+    const lines = raw.split('\n');
+    const managed = {};
+    const listeners = [];
+    const passthrough = [];
+    let currentListener = null;
+
+    for (const line of lines) {
+        const trimmed = line.trim();
+        // blank lines and comments go to passthrough
+        if (!trimmed || trimmed.startsWith('#')) {
+            passthrough.push(line);
+            continue;
+        }
+
+        const spaceIdx = trimmed.indexOf(' ');
+        if (spaceIdx === -1) {
+            passthrough.push(line);
+            continue;
+        }
+
+        const key = trimmed.slice(0, spaceIdx).trim();
+        const value = trimmed.slice(spaceIdx + 1).trim();
+
+        if (key === 'listener') {
+            const parts = value.split(/\s+/);
+            currentListener = {
+                port: parseInt(parts[0], 10),
+                bindAddress: parts[1] || '',
+                protocol: 'mqtt',
+                tls: {},
+            };
+            listeners.push(currentListener);
+        } else if (currentListener && isListenerSubkey(key)) {
+            applyListenerKey(currentListener, key, value);
+        } else if (MANAGED_SINGLE_KEYS.has(key)) {
+            if (managed[key] !== undefined) {
+                // multi-value key (e.g. log_type) — convert to array
+                managed[key] = [].concat(managed[key]).concat(value);
+            } else {
+                managed[key] = value;
+            }
+            currentListener = null;
+        } else {
+            passthrough.push(line);
+            currentListener = null;
+        }
+    }
+
+    return { listeners, managed, passthrough, raw };
+}
+
+/** Keys that belong to a listener block */
+function isListenerSubkey(key) {
+    return [
+        'protocol',
+        'socket_domain',
+        'certfile',
+        'keyfile',
+        'cafile',
+        'capath',
+        'crlfile',
+        'require_certificate',
+        'use_identity_as_username',
+        'tls_version',
+        'websockets_log_level',
+    ].includes(key);
+}
+
+function applyListenerKey(listener, key, value) {
+    switch (key) {
+        case 'protocol':
+            listener.protocol = value;
+            break;
+        case 'certfile':
+        case 'keyfile':
+        case 'cafile':
+        case 'capath':
+        case 'crlfile':
+        case 'tls_version':
+            listener.tls[key] = value;
+            break;
+        case 'require_certificate':
+            listener.tls.require_certificate = value === 'true';
+            break;
+        case 'use_identity_as_username':
+            listener.tls.use_identity_as_username = value === 'true';
+            break;
+        default:
+            break;
+    }
+}
+
+/**
+ * Serialise the structured config back to mosquitto.conf text.
+ *
+ * @param {{ listeners: object[], managed: object, passthrough: string[] }} conf
+ * @returns {string}
+ */
+function serialise(conf) {
+    const lines = [];
+
+    // Managed single-key entries first
+    const { managed = {}, listeners = [], passthrough = [] } = conf;
+
+    const keyOrder = ['allow_anonymous', 'persistence', 'persistence_location', 'log_dest', 'log_type', 'plugin', 'plugin_opt_dynsec_config_file'];
+    for (const key of keyOrder) {
+        if (managed[key] === undefined) continue;
+        const val = managed[key];
+        if (Array.isArray(val)) {
+            for (const v of val) lines.push(`${key} ${v}`);
+        } else {
+            lines.push(`${key} ${val}`);
+        }
+    }
+
+    if (lines.length > 0) lines.push('');
+
+    // Listener blocks
+    for (const l of listeners) {
+        const addr = l.bindAddress ? ` ${l.bindAddress}` : '';
+        lines.push(`listener ${l.port}${addr}`);
+        if (l.protocol && l.protocol !== 'mqtt') lines.push(`protocol ${l.protocol}`);
+        const tls = l.tls || {};
+        for (const tlsKey of ['certfile', 'keyfile', 'cafile', 'capath', 'crlfile', 'tls_version']) {
+            if (tls[tlsKey]) lines.push(`${tlsKey} ${tls[tlsKey]}`);
+        }
+        if (tls.require_certificate !== undefined) {
+            lines.push(`require_certificate ${tls.require_certificate ? 'true' : 'false'}`);
+        }
+        if (tls.use_identity_as_username !== undefined) {
+            lines.push(`use_identity_as_username ${tls.use_identity_as_username ? 'true' : 'false'}`);
+        }
+        lines.push('');
+    }
+
+    // Passthrough (comments, blanks, unmanaged keys)
+    for (const l of passthrough) lines.push(l);
+
+    return lines.join('\n');
+}
+
+/**
+ * SHA-256 checksum of a file path. Returns null if file does not exist.
+ */
+function checksum(filePath) {
+    try {
+        const data = fs.readFileSync(filePath);
+        return crypto.createHash('sha256').update(data).digest('hex');
+    } catch (err) {
+        if (err.code === 'ENOENT') return null;
+        throw err;
+    }
+}
+
+/**
+ * Write config to disk with a timestamped backup.
+ * If knownChecksum is provided and the file has been modified externally,
+ * returns { ok: false, reason: 'external_modify' } instead of writing.
+ *
+ * @param {string} filePath
+ * @param {string} content
+ * @param {string|null} [knownChecksum]
+ * @returns {{ ok: boolean, backupPath?: string, reason?: string }}
+ */
+function write(filePath, content, knownChecksum = null) {
+    if (knownChecksum !== null) {
+        const current = checksum(filePath);
+        if (current !== null && current !== knownChecksum) {
+            return { ok: false, reason: 'external_modify' };
+        }
+    }
+
+    // Create backup
+    let backupPath = null;
+    if (fs.existsSync(filePath)) {
+        const ts = new Date().toISOString().replace(/[:.]/g, '-');
+        backupPath = `${filePath}.bak-${ts}`;
+        fs.copyFileSync(filePath, backupPath);
+    }
+
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, content, 'utf8');
+
+    return { ok: true, backupPath };
+}
+
+/**
+ * List backup files for a given config path.
+ * @param {string} filePath
+ * @returns {string[]} sorted newest-first
+ */
+function listBackups(filePath) {
+    const dir = path.dirname(filePath);
+    const base = path.basename(filePath);
+    let entries;
+    try {
+        entries = fs.readdirSync(dir);
+    } catch {
+        return [];
+    }
+    return entries
+        .filter((e) => e.startsWith(`${base}.bak-`))
+        .sort()
+        .reverse()
+        .map((e) => path.join(dir, e));
+}
+
+/**
+ * Restore a backup file over the live config.
+ * @param {string} backupPath
+ * @param {string} destPath
+ */
+function restoreBackup(backupPath, destPath) {
+    fs.copyFileSync(backupPath, destPath);
+}
+
+/**
+ * Send SIGHUP to mosquitto (for local mode where she can signal the process).
+ * Falls back to running the configured reloadCmd.
+ *
+ * @param {object} brokerConfig  - config.broker
+ * @returns {Promise<{stdout: string, stderr: string}>}
+ */
+async function reload(brokerConfig) {
+    const cmd = brokerConfig.reloadCmd || 'sudo systemctl reload mosquitto';
+    const [bin, ...args] = cmd.split(/\s+/);
+    const result = await execFileAsync(bin, args, { timeout: 10000 });
+    return result;
+}
+
+/**
+ * Full restart of the mosquitto service.
+ * @param {object} brokerConfig
+ */
+async function restart(brokerConfig) {
+    const cmd = brokerConfig.restartCmd || 'sudo systemctl restart mosquitto';
+    const [bin, ...args] = cmd.split(/\s+/);
+    const result = await execFileAsync(bin, args, { timeout: 15000 });
+    return result;
+}
+
+module.exports = { parse, serialise, checksum, write, listBackups, restoreBackup, reload, restart };