smart-home-engine 1.21.0 → 1.34.3

package/src/lib/services-host.js

@@ -0,0 +1,275 @@
+'use strict';
+
+/**
+ * Host drivers for xyz2mqtt service management (roadmap I4/I5).
+ *
+ * A driver runs the privileged helper `she-servicectl` on one host and is the
+ * only thing that differs between the she host itself (local: sudo + execFile)
+ * and remote hosts (ssh, I5). Everything above this layer — the API, the
+ * inventory correlation — only sees:
+ *
+ *   driver.name                       host label
+ *   driver.exec(args, {stdin})        → {stdout, stderr, code}   (rejects HostError)
+ *   driver.spawn(args)                → ChildProcess              (long-running: logs --follow)
+ *
+ * Errors carry `code`:
+ *   HELPER_MISSING  the helper is not installed on the host
+ *   SUDO_DENIED     sudoers does not allow the helper for this user
+ *   HELPER_FAILED   the helper rejected the call (exit 2, message in stderr)
+ *   SSH_FAILED      the ssh connection itself failed (exit 255: auth, host key, unreachable)
+ *   EXEC_FAILED     the underlying command failed (non-zero exit)
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execFile, spawn } = require('child_process');
+const sshDeploy = require('./ssh-deploy');
+
+const HELPER = '/usr/local/bin/she-servicectl';
+const HELPER_VERSION = 8; // must match VERSION in service/she-servicectl
+/** Default identity for services.hosts[].ssh — one key for all managed hosts (I5). */
+const DEFAULT_SERVICES_IDENTITY = '~/.she/ssh/services_id_ed25519';
+/** The helper as shipped with this she version (copied to remote hosts by the deploy route). */
+const HELPER_SOURCE = path.join(__dirname, '..', '..', 'service', 'she-servicectl');
+
+class HostError extends Error {
+    constructor(code, message, extra = {}) {
+        super(message);
+        this.code = code;
+        Object.assign(this, extra);
+    }
+}
+
+function classify(err, stdout, stderr, code, { ssh = false } = {}) {
+    const text = String(stderr || '').trim();
+    if (ssh && code === 255) return new HostError('SSH_FAILED', text || 'ssh connection failed');
+    if ((err && err.code === 'ENOENT') || code === 127 || /she-servicectl: (command )?not found|she-servicectl: No such file/i.test(text)) {
+        return new HostError('HELPER_MISSING', 'she-servicectl is not installed on this host');
+    }
+    if (/a password is required|not allowed to execute|not in the sudoers/i.test(text)) {
+        return new HostError('SUDO_DENIED', 'sudo does not allow she-servicectl for this user: ' + text);
+    }
+    if (/^she-servicectl: /.test(text) || code === 2) {
+        return new HostError('HELPER_FAILED', text.replace(/^she-servicectl: /, '') || 'helper rejected the call', { stdout, stderr: text, exitCode: code });
+    }
+    return new HostError('EXEC_FAILED', text || (err && err.message) || `exit ${code}`, { stdout, stderr: text, exitCode: code });
+}
+
+/**
+ * Driver for the host she runs on: `sudo -n she-servicectl …`.
+ * @param {{helper?: string, sudo?: boolean, name?: string, env?: object}} [opts]
+ */
+function createLocalDriver(opts = {}) {
+    const helper = opts.helper || HELPER;
+    const useSudo = opts.sudo !== false;
+    const name = opts.name || 'local';
+    // LC_ALL=C keeps systemctl/journalctl output parseable; sudo keeps only a few variables anyway
+    const env = { ...(opts.env || process.env), LC_ALL: 'C' };
+
+    function command(args) {
+        return useSudo ? ['sudo', ['-n', helper, ...args]] : [helper, [...args]];
+    }
+
+    function exec(args, { stdin, timeout = 30000 } = {}) {
+        if (!fs.existsSync(helper)) return Promise.reject(new HostError('HELPER_MISSING', 'she-servicectl is not installed on this host'));
+        const [cmd, argv] = command(args);
+        return new Promise((resolve, reject) => {
+            const child = execFile(cmd, argv, { timeout, env, maxBuffer: 16 * 1024 * 1024 }, (err, stdout, stderr) => {
+                const code = err && typeof err.code === 'number' ? err.code : err ? null : 0;
+                if (err) return reject(classify(err, stdout, stderr, code));
+                resolve({ stdout, stderr, code: 0 });
+            });
+            if (stdin !== undefined) {
+                child.stdin.on('error', () => {});
+                child.stdin.end(stdin);
+            } else {
+                child.stdin.end();
+            }
+        });
+    }
+
+    function spawnHelper(args) {
+        const [cmd, argv] = command(args);
+        return spawn(cmd, argv, { env, stdio: ['ignore', 'pipe', 'pipe'] });
+    }
+
+    return { name, local: true, helperPath: helper, exec, spawn: spawnHelper };
+}
+
+/** Quote a word for a POSIX shell (the remote side runs the helper through the login shell). */
+function shellQuote(s) {
+    return "'" + String(s).replace(/'/g, "'\\''") + "'";
+}
+
+/**
+ * Driver for a remote host: `ssh <host> sudo -n she-servicectl …` with the system ssh/scp
+ * clients (BatchMode, accept-new — like the broker deploy). stdin is passed through.
+ * @param {{name: string, ssh: {host: string, port?: number, user?: string, identityFile?: string}}} hostCfg
+ * @param {{helper?: string, sudo?: boolean, defaultIdentity?: string, sshBin?: string, scpBin?: string, env?: object}} [opts]
+ */
+function createSshDriver(hostCfg, opts = {}) {
+    const helper = opts.helper || HELPER;
+    const useSudo = opts.sudo !== false;
+    const sshCfg = hostCfg.ssh || {};
+    const defaultIdentity = opts.defaultIdentity || DEFAULT_SERVICES_IDENTITY;
+    const sshBin = opts.sshBin || 'ssh';
+    const scpBin = opts.scpBin || 'scp';
+    const env = { ...(opts.env || process.env), LC_ALL: 'C' };
+    const name = hostCfg.name;
+
+    function remoteCommand(args) {
+        return [...(useSudo ? ['sudo', '-n'] : []), helper, ...args].map(shellQuote).join(' ');
+    }
+    function sshArgv(command) {
+        return [...sshDeploy.sshArgs(sshCfg, defaultIdentity), sshDeploy.sshTarget(sshCfg), command];
+    }
+    function runSsh(command, { stdin, timeout = 45000, maxBuffer = 16 * 1024 * 1024 } = {}) {
+        return new Promise((resolve, reject) => {
+            const child = execFile(sshBin, sshArgv(command), { timeout, env, maxBuffer }, (err, stdout, stderr) => {
+                const code = err && typeof err.code === 'number' ? err.code : err ? null : 0;
+                if (err) return reject(classify(err, stdout, stderr, code, { ssh: true }));
+                resolve({ stdout, stderr, code: 0 });
+            });
+            child.stdin.on('error', () => {});
+            child.stdin.end(stdin === undefined ? '' : stdin);
+        });
+    }
+
+    /** helper call */
+    function exec(args, options) {
+        return runSsh(remoteCommand(args), options);
+    }
+    /** long-running helper call (logs --follow) */
+    function spawnHelper(args) {
+        return spawn(sshBin, sshArgv(remoteCommand(args)), { env, stdio: ['ignore', 'pipe', 'pipe'] });
+    }
+    /** arbitrary command on the host — only used by the helper deploy */
+    function run(command, options) {
+        return runSsh(command, options);
+    }
+    /** scp a local file to `remotePath` (relative to the SSH user's home unless absolute) */
+    function upload(localPath, remotePath) {
+        return new Promise((resolve, reject) => {
+            // scp needs IPv6 literals in brackets: user@[fe80::1]:path
+            const target = sshDeploy.sshTarget(sshCfg);
+            const at = target.indexOf('@');
+            const hostPart = target.slice(at + 1);
+            const bracketed = hostPart.includes(':') && !hostPart.startsWith('[') ? target.slice(0, at + 1) + '[' + hostPart + ']' : target;
+            const argv = [...sshDeploy.scpArgs(sshCfg, defaultIdentity), localPath, bracketed + ':' + remotePath];
+            execFile(scpBin, argv, { timeout: 60000, env }, (err, stdout, stderr) => {
+                if (err) return reject(new HostError('SSH_FAILED', String(stderr || err.message).trim()));
+                resolve();
+            });
+        });
+    }
+
+    return { name, local: false, helperPath: helper, target: sshDeploy.sshTarget(sshCfg), exec, spawn: spawnHelper, run, upload };
+}
+
+/** Parse the JSON of `she-servicectl list`. */
+function parseList(stdout) {
+    let data;
+    try {
+        data = JSON.parse(stdout);
+    } catch {
+        throw new HostError('EXEC_FAILED', 'unexpected helper output: ' + String(stdout).slice(0, 200));
+    }
+    return {
+        helper: Number(data.helper) || 0,
+        helperOutdated: (Number(data.helper) || 0) < HELPER_VERSION,
+        hostname: data.hostname || null,
+        node: data.node || null,
+        brokerEnv: data.brokerEnv === true,
+        adapters: Array.isArray(data.adapters) ? data.adapters : [],
+        instances: Array.isArray(data.instances) ? data.instances : [],
+        /** pre-core single-instance units (<adapter>.service), helper v5+ */
+        legacy: Array.isArray(data.legacy) ? data.legacy : [],
+    };
+}
+
+/** Parse `journalctl -o json` lines into {ts, level, msg, pid}. */
+function parseJournal(text) {
+    const out = [];
+    for (const line of String(text).split('\n')) {
+        if (!line.trim()) continue;
+        let j;
+        try {
+            j = JSON.parse(line);
+        } catch {
+            continue;
+        }
+        const usec = Number(j.__REALTIME_TIMESTAMP);
+        const prio = Number(j.PRIORITY);
+        let msg = j.MESSAGE;
+        if (Array.isArray(msg)) msg = Buffer.from(msg).toString('utf8'); // journald encodes non-UTF8 as byte arrays
+        out.push({
+            ts: Number.isFinite(usec) ? Math.round(usec / 1000) : Date.now(),
+            level: prio <= 3 ? 'error' : prio === 4 ? 'warn' : prio <= 6 ? 'info' : 'debug',
+            msg: typeof msg === 'string' ? msg : String(msg ?? ''),
+            pid: j._PID ? Number(j._PID) : null,
+        });
+    }
+    return out;
+}
+
+/**
+ * Parse an env file into {entries: [{key, value, line}], comments} keeping order.
+ * @param {string} text
+ */
+function parseEnvFile(text) {
+    const env = {};
+    for (const line of String(text).split('\n')) {
+        const m = line.match(/^([A-Z][A-Z0-9_]*)=(.*)$/);
+        if (m) env[m[1]] = m[2];
+    }
+    return env;
+}
+
+/** Serialize an env object to the file format the core writes (header comments + KEY=VALUE). */
+function formatEnvFile(env, header = []) {
+    const lines = header.map((h) => (h.startsWith('#') ? h : '# ' + h));
+    for (const [k, v] of Object.entries(env)) {
+        if (!/^[A-Z][A-Z0-9_]*$/.test(k)) throw new HostError('HELPER_FAILED', 'invalid env variable name: ' + k);
+        if (v === undefined || v === null || v === '') continue;
+        lines.push(`${k}=${String(v).replace(/[\r\n]+/g, ' ')}`);
+    }
+    return lines.join('\n') + '\n';
+}
+
+const SECRET_NAME_RE = /(password|passwd|token|secret|cookie|api[-_]?key|private[-_]?key)/i;
+
+/**
+ * Environment variable names whose values must be masked: `x-secret` properties
+ * of the schema plus the name heuristic (SV-10).
+ * @param {object|null} schema `--config-schema` output
+ * @param {string[]} [envNames] additional names to test with the heuristic
+ * @returns {Set<string>}
+ */
+function secretEnvVars(schema, envNames = []) {
+    const set = new Set();
+    const props = schema && schema.properties ? schema.properties : {};
+    for (const [key, p] of Object.entries(props)) {
+        const envName = p && typeof p['x-env'] === 'string' ? p['x-env'] : null;
+        if (!envName) continue;
+        if ((p && p['x-secret'] === true) || SECRET_NAME_RE.test(key)) set.add(envName);
+    }
+    for (const n of envNames) if (SECRET_NAME_RE.test(n)) set.add(n);
+    return set;
+}
+
+module.exports = {
+    HELPER,
+    HELPER_VERSION,
+    HELPER_SOURCE,
+    DEFAULT_SERVICES_IDENTITY,
+    HostError,
+    createLocalDriver,
+    createSshDriver,
+    shellQuote,
+    parseList,
+    parseJournal,
+    parseEnvFile,
+    formatEnvFile,
+    secretEnvVars,
+    SECRET_NAME_RE,
+};

package/src/lib/services-inventory.js

@@ -0,0 +1,180 @@
+'use strict';
+
+/**
+ * xyz2mqtt service inventory (roadmap I4, Tier 0).
+ *
+ * Pure functions over the daemon's state store. Adapters built on
+ * mqtt-interfaces-core publish two retained topics per instance:
+ *
+ *   <name>/connected   0 (LWT / shut down) · 1 (mqtt only) · 2 (mqtt + device)
+ *   <name>/info        {name: <npm package>, version, spec, node, host, pid, started, maintenance, …}
+ *
+ * An instance is "core" when it has an info payload with `name` and `version`;
+ * a `connected` topic without info is a *legacy* instance (pre-core adapters
+ * such as hm2mqtt, hue2mqtt) which only supports the connected state.
+ *
+ * Nothing here talks to MQTT — the API layer publishes to the maintenance
+ * topics and clears retained messages; this module only derives the picture
+ * and the list of topics a wipe would clear.
+ */
+
+const { analyzeDiscovery, DEFAULT_PREFIX } = require('./ha-discovery');
+
+const LOG_LEVELS = ['error', 'warn', 'info', 'debug'];
+
+/**
+ * Parse a `<name>/connected` payload to 0 | 1 | 2, or null when unusable.
+ * @param {*} val
+ * @returns {0|1|2|null}
+ */
+function parseConnected(val) {
+    if (val === null || val === undefined) return null;
+    // adapters running with --json-payloads still publish connected as a plain number,
+    // but tolerate {val} objects and JSON strings in case somebody wraps it
+    let v = val;
+    if (typeof v === 'string') {
+        const t = v.trim();
+        if (t.startsWith('{')) {
+            try {
+                v = JSON.parse(t);
+            } catch {
+                return null;
+            }
+        } else {
+            v = t;
+        }
+    }
+    if (v && typeof v === 'object' && 'val' in v) v = v.val;
+    const n = Number(v);
+    return n === 0 || n === 1 || n === 2 ? n : null;
+}
+
+/**
+ * Parse a `<name>/info` payload into an object, or null.
+ * @param {*} val
+ * @returns {object|null}
+ */
+function parseInfo(val) {
+    let v = val;
+    if (typeof v === 'string') {
+        try {
+            v = JSON.parse(v);
+        } catch {
+            return null;
+        }
+    }
+    if (!v || typeof v !== 'object' || Array.isArray(v)) return null;
+    // adapters publish info as a plain object; a {val: {...}} wrapper is tolerated
+    if (v.val && typeof v.val === 'object' && !('name' in v) && 'name' in v.val) v = v.val;
+    return v;
+}
+
+/**
+ * Derive the service inventory from the retained MQTT state.
+ *
+ * @param {Iterable<[string, {val:*, ts:number, lc?:number}]>} entries  `store.mqttEntries()`
+ * @param {{now?: number}} [opts]
+ * @returns {{instances: Array<object>, coreCount: number, legacyCount: number}}
+ */
+function analyzeServices(entries, opts = {}) {
+    const now = opts.now ?? Date.now();
+    const infos = new Map(); // instance → {info, ts}
+    const conns = new Map(); // instance → {connected, ts, lc}
+    const topics = new Set();
+
+    for (const [topic, obj] of entries) {
+        topics.add(topic);
+        const slash = topic.indexOf('/');
+        if (slash <= 0 || topic.indexOf('/', slash + 1) !== -1) continue; // exactly two levels
+        const instance = topic.slice(0, slash);
+        const leaf = topic.slice(slash + 1);
+        if (instance.startsWith('$')) continue;
+        if (leaf === 'info') {
+            const info = parseInfo(obj && obj.val);
+            if (info && typeof info.name === 'string' && info.name) infos.set(instance, { info, ts: obj.ts });
+        } else if (leaf === 'connected') {
+            const connected = parseConnected(obj && obj.val);
+            if (connected !== null) conns.set(instance, { connected, ts: obj.ts, lc: obj.lc });
+        }
+    }
+
+    const names = new Set([...infos.keys(), ...conns.keys()]);
+    const instances = [];
+    for (const instance of names) {
+        const i = infos.get(instance);
+        const c = conns.get(instance);
+        const info = i ? i.info : null;
+        const connected = c ? c.connected : null;
+        let started = null;
+        if (info && typeof info.started === 'string') {
+            const t = Date.parse(info.started);
+            if (!Number.isNaN(t)) started = t;
+        }
+        const statusTopics = [...topics].filter((t) => t.startsWith(instance + '/status/')).length;
+        instances.push({
+            instance,
+            legacy: !info,
+            adapter: info ? info.name : null,
+            version: info && typeof info.version === 'string' ? info.version : null,
+            spec: info && typeof info.spec === 'string' ? info.spec : null,
+            host: info && typeof info.host === 'string' ? info.host : null,
+            node: info && typeof info.node === 'string' ? info.node : null,
+            pid: info && Number.isInteger(info.pid) ? info.pid : null,
+            started,
+            // uptime only means something while the process is up; a `started` of a
+            // retained info from a dead instance would just grow forever
+            uptime: started !== null && connected !== null && connected > 0 ? Math.max(0, now - started) : null,
+            maintenance: info ? info.maintenance === true : false,
+            connected,
+            connectedTs: c ? c.ts : null,
+            connectedLc: c ? (c.lc ?? c.ts) : null,
+            infoTs: i ? i.ts : null,
+            statusTopics,
+            info,
+        });
+    }
+    instances.sort((a, b) => a.instance.localeCompare(b.instance));
+    return {
+        instances,
+        coreCount: instances.filter((x) => !x.legacy).length,
+        legacyCount: instances.filter((x) => x.legacy).length,
+    };
+}
+
+/**
+ * Retained topics that belong to an instance and can be cleared when it is gone:
+ * `<name>/info`, `<name>/connected`, everything below `<name>/status/` and
+ * `<name>/maintenance/`, plus the Home Assistant discovery announcements whose
+ * availability or state topics point at the instance (never announcements that
+ * also belong to another device — `analyzeDiscovery` already excludes shared ones).
+ *
+ * @param {Iterable<[string, {val:*, ts:number}]>} entries `store.mqttEntries()`
+ * @param {string} instance topic prefix
+ * @param {{haPrefix?: string}} [opts]
+ * @returns {{own: string[], discovery: string[]}}
+ */
+function wipeTopics(entries, instance, opts = {}) {
+    const list = Array.isArray(entries) ? entries : [...entries];
+    const own = [];
+    for (const [topic] of list) {
+        if (topic === instance + '/info' || topic === instance + '/connected' || topic.startsWith(instance + '/status/') || topic.startsWith(instance + '/maintenance/')) {
+            own.push(topic);
+        }
+    }
+    own.sort();
+
+    const haPrefix = opts.haPrefix || DEFAULT_PREFIX;
+    const discovery = new Set();
+    const { devices } = analyzeDiscovery(list, { prefix: haPrefix });
+    const isOurs = (t) => t === instance + '/connected' || t.startsWith(instance + '/');
+    for (const d of devices) {
+        // a device is the instance's when every topic it references lives under the instance
+        // prefix — the core builds availability from <name>/connected and state from <name>/status/…
+        if (d.refTopics.length > 0 && d.refTopics.every(isOurs)) {
+            for (const t of d.configTopics) discovery.add(t);
+        }
+    }
+    return { own, discovery: [...discovery].sort() };
+}
+
+module.exports = { analyzeServices, wipeTopics, parseConnected, parseInfo, LOG_LEVELS };

package/src/lib/ssh-deploy.js

@@ -28,13 +28,16 @@ function expandHome(p) {
     return p;
 }
 
+const DEFAULT_IDENTITY = '~/.she/ssh/broker_id_ed25519';
+
 /**
  * Build the common ssh argument list (flags only, no target/command).
- * @param {object} sshConfig - config.broker.ssh
+ * @param {object} sshConfig - config.broker.ssh (or services.hosts[].ssh)
+ * @param {string} [defaultIdentity] identity file used when sshConfig has none
  * @returns {string[]}
  */
-function sshArgs(sshConfig) {
-    const identityFile = expandHome(sshConfig.identityFile || '~/.she/ssh/broker_id_ed25519');
+function sshArgs(sshConfig, defaultIdentity = DEFAULT_IDENTITY) {
+    const identityFile = expandHome(sshConfig.identityFile || defaultIdentity);
     return ['-i', identityFile, '-o', 'BatchMode=yes', '-o', 'StrictHostKeyChecking=accept-new', '-p', String(sshConfig.port || 22)];
 }
 
@@ -42,10 +45,11 @@ function sshArgs(sshConfig) {
  * Build the scp argument list prefix.
  * scp uses -P (capital) for port, unlike ssh which uses -p.
  * @param {object} sshConfig
+ * @param {string} [defaultIdentity]
  * @returns {string[]}
  */
-function scpArgs(sshConfig) {
-    const identityFile = expandHome(sshConfig.identityFile || '~/.she/ssh/broker_id_ed25519');
+function scpArgs(sshConfig, defaultIdentity = DEFAULT_IDENTITY) {
+    const identityFile = expandHome(sshConfig.identityFile || defaultIdentity);
     return ['-i', identityFile, '-o', 'BatchMode=yes', '-o', 'StrictHostKeyChecking=accept-new', '-P', String(sshConfig.port || 22)];
 }
 
@@ -131,9 +135,10 @@ async function testConnection(sshConfig) {
 /**
  * Generate an Ed25519 SSH keypair using the system ssh-keygen binary.
  * @param {string} identityFile - path for the private key (e.g. ~/.she/broker_id_ed25519)
+ * @param {string} [comment] key comment (default she-broker)
  * @returns {Promise<string>} the public key text
  */
-async function generateKeypair(identityFile) {
+async function generateKeypair(identityFile, comment = 'she-broker') {
     const expandedPath = expandHome(identityFile || '~/.she/ssh/broker_id_ed25519');
     const dir = path.dirname(expandedPath);
     fs.mkdirSync(dir, { recursive: true });
@@ -149,7 +154,7 @@ async function generateKeypair(identityFile) {
         /* ok */
     }
 
-    await execFileAsync('ssh-keygen', ['-t', 'ed25519', '-f', expandedPath, '-N', '', '-C', 'she-broker'], { timeout: 15000 });
+    await execFileAsync('ssh-keygen', ['-t', 'ed25519', '-f', expandedPath, '-N', '', '-C', comment], { timeout: 15000 });
 
     try {
         fs.chmodSync(expandedPath, 0o600);
@@ -160,4 +165,4 @@ async function generateKeypair(identityFile) {
     return fs.readFileSync(expandedPath + '.pub', 'utf8').trim();
 }
 
-module.exports = { expandHome, runCommand, readRemoteFile, uploadFile, uploadContent, testConnection, generateKeypair };
+module.exports = { expandHome, sshArgs, scpArgs, sshTarget, runCommand, readRemoteFile, uploadFile, uploadContent, testConnection, generateKeypair };

package/src/web/scripts-api.js

@@ -1,4 +1,4 @@
-'use strict';
+'use strict';
 
 const express = require('express');
 const fs = require('fs');

package/src/web/secrets-api.js

@@ -0,0 +1,61 @@
+'use strict';
+
+/**
+ * Secrets HTTP API (roadmap A5/A9) — write-only for secret fields: names and change times come back,
+ * values only for fields marked plain (a username, a host).
+ *
+ *   GET    /she/secrets                  { status, error, keySource, groups: [{ name, changed, fields: [{ name, changed }] }] }
+ *   PUT    /she/secrets/:group/:field    { value, secret? }  → { ok, group, field, changed, secret }   (secret: kind of a new field, default true; never downgrades)
+ *   POST   /she/secrets/:group/:field/secret                → { ok }   mark a plain field secret (one-way)
+ *   DELETE /she/secrets/:group           → { ok }
+ *   DELETE /she/secrets/:group/:field    → { ok }
+ */
+
+const express = require('express');
+const secrets = require('../lib/secrets');
+
+const router = express.Router();
+router.use(express.json({ limit: '128kb' }));
+
+function fail(res, err) {
+    if (err.code === 'LOCKED') return res.status(409).json({ error: err.message, code: 'LOCKED' });
+    if (err.code === 'INVALID_NAME' || err.code === 'INVALID_VALUE') return res.status(400).json({ error: err.message, code: err.code });
+    return res.status(500).json({ error: err.message });
+}
+
+router.get('/', (req, res) => {
+    const st = secrets.status();
+    res.json({ status: st.status, error: st.error, keySource: st.keySource, file: st.file, keyFile: st.keyFile, groups: secrets.list() });
+});
+
+router.put('/:group/:field', (req, res) => {
+    const value = req.body && req.body.value;
+    try {
+        const r = secrets.set(req.params.group, req.params.field, value, { secret: !(req.body && req.body.secret === false) });
+        res.json({ ok: true, ...r });
+    } catch (err) {
+        fail(res, err);
+    }
+});
+
+router.post('/:group/:field/secret', (req, res) => {
+    try {
+        if (!secrets.mark(req.params.group, req.params.field)) return res.status(404).json({ error: 'no such secret' });
+        res.json({ ok: true });
+    } catch (err) {
+        fail(res, err);
+    }
+});
+
+function del(req, res) {
+    try {
+        if (!secrets.remove(req.params.group, req.params.field)) return res.status(404).json({ error: 'no such secret' });
+        res.json({ ok: true });
+    } catch (err) {
+        fail(res, err);
+    }
+}
+router.delete('/:group', del);
+router.delete('/:group/:field', del);
+
+module.exports = { router };

package/src/web/server.js

@@ -14,6 +14,8 @@ const { router: depsRouter } = require('./deps-api');
 const { router: gitRouter } = require('./git-api');
 const { router: aiRouter } = require('./ai-api');
 const { router: brokerRouter } = require('./broker-api');
+const { router: servicesRouter } = require('./services-api');
+const { router: secretsRouter } = require('./secrets-api');
 const { attachWss, closeWss } = require('./log-ws');
 const { init: initAuth, authMiddleware, checkAuth, router: authRouter } = require('./auth');
 
@@ -28,7 +30,9 @@ app.use('/she/auth', authRouter);
 
 // Auth middleware for all /she/* routes except the public auth endpoints above.
 // /api/* is intentionally excluded — user scripts control their own auth.
-const OPEN_SHE_PATHS = new Set(['/she/auth/mode', '/she/auth/login', '/she/auth/logout']);
+// The remote-host bootstrap script and its callback are fetched by curl on the target host: no
+// session, but useless without the one-time token they carry (services-api validates it).
+const OPEN_SHE_PATHS = new Set(['/she/auth/mode', '/she/auth/login', '/she/auth/logout', '/she/services/setup.sh', '/she/services/setup/done']);
 app.use('/she', (req, res, next) => {
     if (OPEN_SHE_PATHS.has(req.originalUrl.split('?')[0])) return next();
     authMiddleware(req, res, next);
@@ -61,6 +65,12 @@ app.use('/she/ai', aiRouter);
 // Broker management: /she/broker/*
 app.use('/she/broker', brokerRouter);
 
+// xyz2mqtt service management: /she/services/*
+app.use('/she/services', servicesRouter);
+
+// Secrets (roadmap A5): write-only, values never leave the daemon
+app.use('/she/secrets', secretsRouter);
+
 // Graceful daemon restart
 // When running under systemd, delegate to `sudo systemctl restart` so the
 // service actually comes back up. Otherwise fall back to exit(0) and let
@@ -119,6 +129,7 @@ app.get('/she/status', (req, res) => {
     const s = _getStats ? _getStats() : { scripts: 0, topics: 0 };
     if (_latestNpmVersion) s.latestVersion = _latestNpmVersion;
     s.dataDir = require('../lib/storage').STORAGE_ROOT;
+    s.user = require('os').userInfo().username; // the OS user the daemon runs as (default SSH user for managed hosts)
     s.startedAt = SERVER_START_TIME;
     if (_isDocker) s.docker = true;
     res.json(s);