smart-home-engine 0.0.1 → 0.11.0

package/src/web/ai-api.js

@@ -0,0 +1,443 @@
+'use strict';
+
+/**
+ * AI Assistant REST API — Express router mounted at /she/ai
+ *
+ * Proxies chat requests to a configured LLM provider (Ollama, LM Studio,
+ * OpenAI, or Anthropic), assembling context (MQTT state, sheDB doc IDs,
+ * Matter devices, she API reference) server-side based on per-request flags.
+ *
+ * Routes:
+ *   GET  /she/ai/config        → { configured, provider, model, baseUrl }
+ *   POST /she/ai/chat          → { message, usage? }           (non-streaming)
+ *   POST /she/ai/chat/stream   → SSE  data: {"token":"..."}    (streaming)
+ *                                     data: [DONE]
+ *
+ * Call init(store) once after the state store is created.
+ */
+
+const express = require('express');
+const fs = require('fs');
+
+const router = express.Router();
+let _store = null;
+
+/**
+ * @param {import('../lib/state-store')} store
+ */
+function init(store) {
+    _store = store;
+}
+
+// ---------------------------------------------------------------------------
+// she API reference — injected into the system prompt when requested
+// ---------------------------------------------------------------------------
+const SHE_API_REF = `## she sandbox API
+
+Scripts run in a sandboxed VM. The \`she\` object is injected automatically.
+
+### Script conventions
+- First lines: /* global she */ then 'use strict';
+- No require() — the module system is not available
+- All subscriptions and schedules persist across reconnects
+
+### MQTT
+she.mqtt.sub(topic, [opts], cb)        Subscribe; wildcards: + (1 level) # (multi)
+                                         +//sensor  →  +/status/sensor shorthand
+                                         opts.change: true = only fire when value changes
+she.mqtt.pub(topic, payload, [opts])   Publish; opts: { qos, retain }
+she.mqtt.get(topic)                    Current retained value (sync)
+she.mqtt.set(topic, val)               Publish as retained
+she.mqtt.link(src, target, [fn])       Forward src changes to target; optional transform
+she.mqtt.age(topic)                    Seconds since topic last received a message
+she.mqtt.on('connect'|'disconnect', cb) MQTT lifecycle events
+
+### Scheduling
+she.schedule(pattern, [opts], cb)
+  pattern: cron string | Date | suncalc event name
+  suncalc events: 'sunrise' 'sunset' 'dawn' 'dusk'
+                  'nauticalDawn' 'nauticalDusk' 'solarNoon' 'night'
+  opts.shift:  seconds offset (e.g. -1800 = 30 min before event)
+  opts.random: max random delay in seconds added to the trigger time
+
+### Universal key-value API
+she.on(key, cb)        Subscribe. Key prefixes: mqtt::  var::  matter::
+she.set(key, val)      Set value (mqtt:: or var:: namespaces)
+she.get(key)           Current value
+she.getObject(key)     Current { val, ts, lc } state object
+
+### Variable system (var:: namespace)
+Topics prefixed with "var" (default) are persisted as retained MQTT messages
+and available across scripts via she.get('var::name') / she.set('var::name', v).
+
+### sheDB
+she.db.get(id)                      Get document (undefined if not found)
+she.db.set(id, doc)                 Create or overwrite document
+she.db.extend(id, partial)          Deep-merge partial into existing document
+she.db.delete(id)                   Delete document
+she.db.sub(pattern, cb)             Subscribe to document changes (MQTT wildcard)
+she.db.query(filter, mapFn, [reduceFn])  Synchronous ad-hoc query → Array
+
+### Matter
+she.matter.sub(nodeId, endpointId, cluster, attr, cb)    Subscribe to attribute
+she.matter.unsub(listenerId)
+she.matter.get(nodeId, endpointId, cluster, attr)         → Promise<value>
+she.matter.send(nodeId, endpointId, cluster, cmd, [args]) → Promise<result>
+
+### Helpers
+she.timer(src, target, ms)           Pulse target=1 for ms after src goes truthy
+she.combineBool(srcs[], target)      Publish OR of source values to target
+she.combineMax(srcs[], target)       Publish maximum of source values to target
+she.link(src, target, [fn])          Alias for she.mqtt.link
+she.age(topic)                       Alias for she.mqtt.age
+she.now()                            Current timestamp in ms
+she.debug / .info / .warn / .error   Structured logging (prefixed with script name)
+she.global                           Shared mutable object across all scripts`;
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Read the ai config section from config.json.
+ * Returns null if unavailable.
+ * @param {string|undefined} configPath
+ * @returns {{ provider?: string, baseUrl?: string, model?: string, apiKey?: string }|null}
+ */
+function readAiConfig(configPath) {
+    if (!configPath) return null;
+    try {
+        const cfg = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+        return cfg.ai || null;
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * Build the full system prompt, including optional context sections.
+ *
+ * @param {object} requestCtx   { apiref, mqtt, shedb, matter }
+ * @param {{ path?: string, content?: string }|null} currentScript
+ * @param {import('../lib/state-store')|null} store
+ * @returns {string}
+ */
+function buildSystemPrompt(requestCtx, currentScript, store) {
+    const parts = [
+        `You are SHE Assistant, an expert AI pair programmer for she (smart-home-engine).
+she is a Node.js daemon that runs user JavaScript scripts in a sandboxed VM for home automation.
+When proposing changes to a script, always output the COMPLETE new file content in a single fenced \`\`\`javascript code block. Never output partial diffs or fragments — the user applies the full file at once.
+Keep any existing header comments and the 'use strict'; directive.`,
+    ];
+
+    if (requestCtx.apiref) {
+        parts.push(SHE_API_REF);
+    }
+
+    if (currentScript?.path && typeof currentScript.content === 'string') {
+        parts.push(`## Current script: ${currentScript.path}\n\`\`\`javascript\n${currentScript.content}\n\`\`\``);
+    }
+
+    if (requestCtx.mqtt && store) {
+        const topics = [];
+        for (const [topic, obj] of store.mqttEntries()) {
+            topics.push(`${topic}: ${JSON.stringify(obj.val)}`);
+            if (topics.length >= 100) {
+                topics.push('… (truncated)');
+                break;
+            }
+        }
+        if (topics.length > 0) {
+            parts.push(`## Current MQTT state\n${topics.join('\n')}`);
+        }
+    }
+
+    if (requestCtx.shedb) {
+        try {
+            const core = require('./shedb').getCore();
+            if (core) {
+                const ids = typeof core.listIds === 'function' ? core.listIds() : [];
+                if (ids.length > 0) {
+                    parts.push(`## sheDB document IDs (${ids.length} total)\n${ids.slice(0, 200).join('\n')}`);
+                }
+            }
+        } catch {
+            // shedb not initialised — skip silently
+        }
+    }
+
+    if (requestCtx.matter) {
+        try {
+            const controller = require('../matter/controller');
+            if (typeof controller.listPaired === 'function') {
+                const nodes = controller.listPaired();
+                if (nodes.length > 0) {
+                    const list = nodes.map((n) => `  nodeId ${n.nodeId}: ${n.label || 'unnamed'}`).join('\n');
+                    parts.push(`## Paired Matter devices\n${list}`);
+                }
+            }
+        } catch {
+            // matter not initialised — skip silently
+        }
+    }
+
+    return parts.join('\n\n');
+}
+
+// ---------------------------------------------------------------------------
+// Provider adapters — non-streaming
+// ---------------------------------------------------------------------------
+
+/**
+ * @param {{ baseUrl?: string, model: string, apiKey?: string }} config
+ * @param {Array<{role:string,content:string}>} messages
+ */
+async function callOpenAICompat(config, messages) {
+    const base = (config.baseUrl || 'http://localhost:11434').replace(/\/$/, '');
+    const url = `${base}/v1/chat/completions`;
+    const headers = { 'Content-Type': 'application/json' };
+    if (config.apiKey) headers['Authorization'] = `Bearer ${config.apiKey}`;
+
+    const res = await fetch(url, {
+        method: 'POST',
+        headers,
+        body: JSON.stringify({ model: config.model, messages, stream: false }),
+    });
+
+    if (!res.ok) {
+        const text = await res.text().catch(() => '');
+        throw new Error(`LLM API error ${res.status}: ${text.slice(0, 300)}`);
+    }
+
+    const json = await res.json();
+    const choice = json.choices?.[0];
+    const message = choice?.message?.content ?? choice?.text ?? '';
+    const usage = json.usage
+        ? {
+              prompt_tokens: json.usage.prompt_tokens,
+              completion_tokens: json.usage.completion_tokens,
+          }
+        : undefined;
+    return { message, usage };
+}
+
+/**
+ * @param {{ model: string, apiKey?: string }} config
+ * @param {Array<{role:string,content:string}>} messages  — first may be role:'system'
+ */
+async function callAnthropic(config, messages) {
+    const systemMsg = messages.find((m) => m.role === 'system');
+    const userMessages = messages.filter((m) => m.role !== 'system');
+
+    const headers = {
+        'Content-Type': 'application/json',
+        'x-api-key': config.apiKey || '',
+        'anthropic-version': '2023-06-01',
+    };
+
+    const res = await fetch('https://api.anthropic.com/v1/messages', {
+        method: 'POST',
+        headers,
+        body: JSON.stringify({
+            model: config.model,
+            system: systemMsg?.content || '',
+            messages: userMessages,
+            max_tokens: 4096,
+        }),
+    });
+
+    if (!res.ok) {
+        const text = await res.text().catch(() => '');
+        throw new Error(`Anthropic API error ${res.status}: ${text.slice(0, 300)}`);
+    }
+
+    const json = await res.json();
+    const message = json.content?.[0]?.text ?? '';
+    const usage = json.usage
+        ? {
+              prompt_tokens: json.usage.input_tokens,
+              completion_tokens: json.usage.output_tokens,
+          }
+        : undefined;
+    return { message, usage };
+}
+
+// ---------------------------------------------------------------------------
+// Provider adapters — streaming
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse an SSE ReadableStream, calling onToken for each non-null extracted value.
+ * @param {ReadableStream} body
+ * @param {(json:object)=>string|null|undefined} tokenExtractor
+ * @param {(token:string)=>void} onToken
+ */
+async function parseSseStream(body, tokenExtractor, onToken) {
+    const reader = body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = '';
+
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done) break;
+            buffer += decoder.decode(value, { stream: true });
+            const lines = buffer.split('\n');
+            buffer = lines.pop() ?? '';
+
+            for (const line of lines) {
+                if (!line.startsWith('data: ')) continue;
+                const data = line.slice(6).trim();
+                if (data === '[DONE]') return;
+                try {
+                    const json = JSON.parse(data);
+                    const token = tokenExtractor(json);
+                    if (token) onToken(token);
+                } catch {
+                    // skip malformed JSON lines
+                }
+            }
+        }
+    } finally {
+        reader.releaseLock();
+    }
+}
+
+/**
+ * Stream tokens from an OpenAI-compatible endpoint.
+ * Calls onToken(str) for each chunk, resolves when stream ends.
+ */
+async function streamOpenAICompat(config, messages, onToken) {
+    const base = (config.baseUrl || 'http://localhost:11434').replace(/\/$/, '');
+    const url = `${base}/v1/chat/completions`;
+    const headers = { 'Content-Type': 'application/json' };
+    if (config.apiKey) headers['Authorization'] = `Bearer ${config.apiKey}`;
+
+    const res = await fetch(url, {
+        method: 'POST',
+        headers,
+        body: JSON.stringify({ model: config.model, messages, stream: true }),
+    });
+
+    if (!res.ok) {
+        const text = await res.text().catch(() => '');
+        throw new Error(`LLM API error ${res.status}: ${text.slice(0, 300)}`);
+    }
+
+    await parseSseStream(res.body, (json) => json.choices?.[0]?.delta?.content, onToken);
+}
+
+/**
+ * Stream tokens from Anthropic Messages API.
+ */
+async function streamAnthropic(config, messages, onToken) {
+    const systemMsg = messages.find((m) => m.role === 'system');
+    const userMessages = messages.filter((m) => m.role !== 'system');
+
+    const headers = {
+        'Content-Type': 'application/json',
+        'x-api-key': config.apiKey || '',
+        'anthropic-version': '2023-06-01',
+    };
+
+    const res = await fetch('https://api.anthropic.com/v1/messages', {
+        method: 'POST',
+        headers,
+        body: JSON.stringify({
+            model: config.model,
+            system: systemMsg?.content || '',
+            messages: userMessages,
+            max_tokens: 4096,
+            stream: true,
+        }),
+    });
+
+    if (!res.ok) {
+        const text = await res.text().catch(() => '');
+        throw new Error(`Anthropic API error ${res.status}: ${text.slice(0, 300)}`);
+    }
+
+    await parseSseStream(res.body, (json) => json.delta?.text, onToken);
+}
+
+// ---------------------------------------------------------------------------
+// Routes
+// ---------------------------------------------------------------------------
+
+// GET /she/ai/config
+router.get('/config', (req, res) => {
+    const ai = readAiConfig(req.app.locals.configPath);
+    res.json({
+        configured: !!(ai?.provider && ai?.model),
+        provider: ai?.provider || '',
+        model: ai?.model || '',
+        baseUrl: ai?.baseUrl || '',
+    });
+});
+
+// POST /she/ai/chat — non-streaming
+router.post('/chat', async (req, res) => {
+    const ai = readAiConfig(req.app.locals.configPath);
+    if (!ai?.provider || !ai?.model) {
+        return res.status(400).json({ error: 'AI provider not configured. Set ai.provider and ai.model in Config.' });
+    }
+
+    const { messages = [], currentScript, context = {} } = req.body || {};
+    if (!Array.isArray(messages)) return res.status(400).json({ error: 'messages must be an array' });
+
+    const systemPrompt = buildSystemPrompt(context, currentScript ?? null, _store);
+    const fullMessages = [{ role: 'system', content: systemPrompt }, ...messages];
+
+    try {
+        let result;
+        if (ai.provider === 'anthropic') {
+            result = await callAnthropic(ai, fullMessages);
+        } else {
+            result = await callOpenAICompat(ai, fullMessages);
+        }
+        res.json(result);
+    } catch (e) {
+        res.status(500).json({ error: e.message });
+    }
+});
+
+// POST /she/ai/chat/stream — SSE streaming
+router.post('/chat/stream', async (req, res) => {
+    const ai = readAiConfig(req.app.locals.configPath);
+    if (!ai?.provider || !ai?.model) {
+        return res.status(400).json({ error: 'AI provider not configured. Set ai.provider and ai.model in Config.' });
+    }
+
+    const { messages = [], currentScript, context = {} } = req.body || {};
+    if (!Array.isArray(messages)) return res.status(400).json({ error: 'messages must be an array' });
+
+    res.set({
+        'Content-Type': 'text/event-stream',
+        'Cache-Control': 'no-cache',
+        'Connection': 'keep-alive',
+    });
+    res.flushHeaders();
+
+    const send = (data) => res.write(`data: ${JSON.stringify(data)}\n\n`);
+
+    const systemPrompt = buildSystemPrompt(context, currentScript ?? null, _store);
+    const fullMessages = [{ role: 'system', content: systemPrompt }, ...messages];
+
+    try {
+        const onToken = (t) => send({ token: t });
+
+        if (ai.provider === 'anthropic') {
+            await streamAnthropic(ai, fullMessages, onToken);
+        } else {
+            await streamOpenAICompat(ai, fullMessages, onToken);
+        }
+
+        res.write('data: [DONE]\n\n');
+        res.end();
+    } catch (e) {
+        send({ error: e.message });
+        res.end();
+    }
+});
+
+module.exports = { router, init };

package/src/web/auth.js

@@ -0,0 +1,186 @@
+'use strict';
+
+/**
+ * Authentication module for the she web server.
+ *
+ * Supports three modes (configured via config.json `auth` field):
+ *   'none'     — no auth, all /she/* routes are open (default)
+ *   'password' — single-password session auth with an HttpOnly cookie
+ *   'proxy'    — trust a header set by nginx/authentik (e.g. X-Remote-User)
+ *
+ * Public endpoints (no auth required in any mode):
+ *   GET  /she/auth/mode    — returns current mode
+ *   POST /she/auth/login   — password mode only; sets session cookie
+ *   POST /she/auth/logout  — clears session cookie
+ *
+ * Protected endpoint (auth required):
+ *   POST /she/auth/setup   — change auth mode / password / proxyHeader
+ */
+
+const crypto = require('crypto');
+const bcrypt = require('bcryptjs');
+const express = require('express');
+const fs = require('fs');
+const path = require('path');
+
+const BCRYPT_ROUNDS = 10;
+const SESSION_TTL_MS = 7 * 24 * 60 * 60 * 1000; // 7 days
+
+// In-memory session store — intentionally cleared on restart
+const _sessions = new Map(); // token (hex64) → { createdAt: number }
+
+let _mode = 'none';
+let _passwordHash = null; // bcrypt hash, only used in 'password' mode
+let _proxyHeader = 'x-remote-user'; // lowercase for req.headers lookup
+let _configPath = null;
+
+/**
+ * Initialise auth state. Called once from startServer().
+ */
+function init({ auth = 'none', password = null, proxyHeader = 'X-Remote-User', configPath = null } = {}) {
+    _mode = auth;
+    _passwordHash = password || null;
+    _proxyHeader = proxyHeader.toLowerCase();
+    _configPath = configPath;
+}
+
+function getMode() {
+    return _mode;
+}
+
+// ── Session helpers ─────────────────────────────────────────────────────────
+
+function _getSessionToken(req) {
+    const cookie = req.headers.cookie || '';
+    const m = cookie.match(/(?:^|;\s*)she_session=([a-f0-9]{64})/);
+    return m ? m[1] : null;
+}
+
+function _validateSession(token) {
+    if (!token) return false;
+    const s = _sessions.get(token);
+    if (!s) return false;
+    if (Date.now() - s.createdAt > SESSION_TTL_MS) {
+        _sessions.delete(token);
+        return false;
+    }
+    return true;
+}
+
+// ── Auth check (used by middleware and WS gate) ─────────────────────────────
+
+/**
+ * Returns true if the request is authenticated according to the current mode.
+ * @param {import('http').IncomingMessage} req
+ */
+function checkAuth(req) {
+    if (_mode === 'none') return true;
+    if (_mode === 'proxy') return !!req.headers[_proxyHeader];
+    if (_mode === 'password') return _validateSession(_getSessionToken(req));
+    return true;
+}
+
+/**
+ * Express middleware that enforces auth on /she/* routes.
+ * Mount this AFTER the public auth router so login/mode/logout bypass it.
+ */
+function authMiddleware(req, res, next) {
+    if (checkAuth(req)) return next();
+    res.status(401).json({ error: 'Unauthorized' });
+}
+
+// ── Auth API router ─────────────────────────────────────────────────────────
+
+const router = express.Router();
+
+/** GET /she/auth/mode — always public */
+router.get('/mode', (req, res) => {
+    res.json({ mode: _mode });
+});
+
+/** POST /she/auth/login — always public; only meaningful in password mode */
+router.post('/login', async (req, res) => {
+    if (_mode !== 'password') return res.status(400).json({ error: 'Not in password mode' });
+    const { password } = req.body || {};
+    if (!password || !_passwordHash) return res.status(401).json({ error: 'Unauthorized' });
+    try {
+        const ok = await bcrypt.compare(password, _passwordHash);
+        if (!ok) return res.status(401).json({ error: 'Invalid password' });
+        const token = crypto.randomBytes(32).toString('hex');
+        _sessions.set(token, { createdAt: Date.now() });
+        res.setHeader('Set-Cookie', `she_session=${token}; HttpOnly; SameSite=Strict; Path=/`);
+        res.json({ ok: true });
+    } catch {
+        res.status(500).json({ error: 'Internal error' });
+    }
+});
+
+/** POST /she/auth/logout — always public; clears cookie */
+router.post('/logout', (req, res) => {
+    const token = _getSessionToken(req);
+    if (token) _sessions.delete(token);
+    res.setHeader('Set-Cookie', 'she_session=; HttpOnly; SameSite=Strict; Path=/; Max-Age=0');
+    res.json({ ok: true });
+});
+
+/**
+ * POST /she/auth/setup — protected; change auth mode / password / proxyHeader.
+ * Body: { mode: 'none'|'password'|'proxy', password?: string, proxyHeader?: string }
+ *
+ * Self-guards when in password mode (requires valid session).
+ */
+router.post('/setup', async (req, res) => {
+    // Self-guard: in password mode the caller must be authenticated
+    if (_mode === 'password' && !_validateSession(_getSessionToken(req))) {
+        return res.status(401).json({ error: 'Unauthorized' });
+    }
+
+    const { mode, password, proxyHeader } = req.body || {};
+
+    if (!['none', 'password', 'proxy'].includes(mode)) {
+        return res.status(400).json({ error: 'Invalid auth mode. Must be none, password, or proxy.' });
+    }
+    if (mode === 'password' && !password) {
+        return res.status(400).json({ error: 'A non-empty password is required for password mode.' });
+    }
+
+    try {
+        // Read existing config
+        let cfg = {};
+        try {
+            cfg = JSON.parse(fs.readFileSync(_configPath, 'utf8'));
+        } catch {
+            // config file does not exist yet — start from empty
+        }
+
+        // Update auth fields, remove stale ones
+        cfg.auth = mode;
+        delete cfg.password;
+        delete cfg.proxyHeader;
+
+        if (mode === 'password') {
+            cfg.password = await bcrypt.hash(password, BCRYPT_ROUNDS);
+        }
+        if (mode === 'proxy') {
+            cfg.proxyHeader = proxyHeader || 'X-Remote-User';
+        }
+
+        // Write back
+        fs.mkdirSync(path.dirname(_configPath), { recursive: true });
+        fs.writeFileSync(_configPath, JSON.stringify(cfg, null, 2), 'utf8');
+
+        // Apply in-memory (no restart needed)
+        _mode = mode;
+        _passwordHash = cfg.password || null;
+        _proxyHeader = (cfg.proxyHeader || 'X-Remote-User').toLowerCase();
+
+        // Invalidate all existing sessions when switching away from password mode
+        if (mode !== 'password') _sessions.clear();
+
+        res.json({ ok: true });
+    } catch (err) {
+        res.status(500).json({ error: err.message });
+    }
+});
+
+module.exports = { init, authMiddleware, checkAuth, getMode, router };

package/src/web/config-api.js

@@ -0,0 +1,34 @@
+'use strict';
+
+const express = require('express');
+const fs = require('fs');
+const path = require('path');
+const { getConfigPath } = require('../lib/storage');
+
+const DEFAULT_CONFIG_PATH = getConfigPath();
+
+const router = express.Router();
+
+router.get('/', (req, res) => {
+    const configPath = req.app.locals.configPath || DEFAULT_CONFIG_PATH;
+    let fileConfig = {};
+    try {
+        fileConfig = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+    } catch {
+        // config file does not exist yet — return empty object
+    }
+    res.json(fileConfig);
+});
+
+router.put('/', (req, res) => {
+    const configPath = req.app.locals.configPath || DEFAULT_CONFIG_PATH;
+    try {
+        fs.mkdirSync(path.dirname(configPath), { recursive: true });
+        fs.writeFileSync(configPath, JSON.stringify(req.body, null, 2), 'utf8');
+        res.json({ ok: true, restartRequired: true, configPath });
+    } catch (err) {
+        res.status(500).json({ error: err.message });
+    }
+});
+
+module.exports = { router, DEFAULT_CONFIG_PATH };