@switchbot/openapi-cli 2.7.2 → 3.1.0

package/dist/rules/webhook-listener.js

@@ -0,0 +1,223 @@
+/**
+ * Local HTTP listener that delivers webhook events to the rules engine.
+ *
+ * Scope (E2):
+ *   - Binds to `127.0.0.1` only — the loopback interface keeps the
+ *     listener off the network by default. The plan's integration story
+ *     is that an agent or local script POSTs to this endpoint.
+ *   - Default port is 18790 (phase-3 design doc choice); override with
+ *     `--webhook-port <n>` in `switchbot rules run`. `--webhook-port 0`
+ *     asks the OS for an ephemeral port — useful in tests.
+ *   - Bearer-token auth on every request: `Authorization: Bearer <t>`.
+ *     The expected token comes from `WebhookTokenStore`; unauthorized
+ *     requests get a 401 with no body, no hint about which header
+ *     failed, and an audit entry (`rule-webhook-rejected`).
+ *   - Matches request path against registered webhook rules: only
+ *     `POST /path/exactly/as/declared`. Unknown paths return 404.
+ *
+ * Non-goals:
+ *   - No TLS; operators who expose this outside loopback are expected
+ *     to sit behind a reverse proxy that terminates TLS.
+ *   - No payload parsing beyond reading the body as a string — the
+ *     engine passes the raw body through in the event payload.
+ */
+import http from 'node:http';
+import { timingSafeEqual } from 'node:crypto';
+import { writeAudit } from '../utils/audit.js';
+import { isWebhookTrigger } from './types.js';
+export const DEFAULT_WEBHOOK_PORT = 18790;
+const MAX_BODY_BYTES = 16 * 1024; // guard against huge POSTs from misbehaving callers
+export class WebhookListener {
+    opts;
+    server = null;
+    pathIndex = new Map();
+    actualPort = null;
+    constructor(opts) {
+        this.opts = opts;
+        for (const rule of opts.rules) {
+            if (!isWebhookTrigger(rule.when))
+                continue;
+            const normalised = normalisePath(rule.when.path);
+            if (this.pathIndex.has(normalised)) {
+                throw new Error(`WebhookListener: duplicate webhook path "${normalised}" — every webhook rule needs a unique path`);
+            }
+            this.pathIndex.set(normalised, rule);
+        }
+    }
+    /** Start listening. Resolves once the server has bound a port. */
+    async start() {
+        if (this.server)
+            return;
+        const server = http.createServer((req, res) => {
+            this.handle(req, res).catch((err) => {
+                // The dispatch chain should never reject — but if it does,
+                // make sure we close the socket so the caller doesn't hang.
+                if (!res.headersSent) {
+                    res.writeHead(500);
+                    res.end();
+                }
+                // eslint-disable-next-line no-console
+                console.error(`webhook-listener: unhandled dispatch error: ${err instanceof Error ? err.message : String(err)}`);
+            });
+        });
+        const host = this.opts.host ?? '127.0.0.1';
+        const port = this.opts.port ?? DEFAULT_WEBHOOK_PORT;
+        await new Promise((resolve, reject) => {
+            const onError = (err) => {
+                server.off('listening', onListening);
+                reject(err);
+            };
+            const onListening = () => {
+                server.off('error', onError);
+                resolve();
+            };
+            server.once('error', onError);
+            server.once('listening', onListening);
+            server.listen(port, host);
+        });
+        const address = server.address();
+        this.actualPort = typeof address === 'object' && address ? address.port : port;
+        this.server = server;
+    }
+    async stop() {
+        if (!this.server)
+            return;
+        const server = this.server;
+        this.server = null;
+        this.actualPort = null;
+        await new Promise((resolve) => server.close(() => resolve()));
+    }
+    getPort() {
+        return this.actualPort;
+    }
+    listPaths() {
+        return [...this.pathIndex.keys()].sort();
+    }
+    /**
+     * Replace the current rule → path index. Used by `engine.reload`: the
+     * listener keeps its open port and accepted connections, but routes
+     * subsequent requests against the fresh policy.
+     */
+    updateRules(rules) {
+        const next = new Map();
+        for (const rule of rules) {
+            if (!isWebhookTrigger(rule.when))
+                continue;
+            const normalised = normalisePath(rule.when.path);
+            if (next.has(normalised)) {
+                throw new Error(`WebhookListener.updateRules: duplicate webhook path "${normalised}"`);
+            }
+            next.set(normalised, rule);
+        }
+        this.pathIndex.clear();
+        for (const [k, v] of next)
+            this.pathIndex.set(k, v);
+    }
+    async handle(req, res) {
+        // Auth gate first — reject everything else so a wrong token never
+        // reveals which paths exist.
+        if (!this.isAuthorized(req)) {
+            writeAudit({
+                t: this.now().toISOString(),
+                kind: 'rule-webhook-rejected',
+                deviceId: 'unknown',
+                command: req.url ?? '',
+                parameter: null,
+                commandType: 'command',
+                dryRun: true,
+                result: 'error',
+                error: 'unauthorized',
+            });
+            res.writeHead(401);
+            res.end();
+            return;
+        }
+        if (req.method !== 'POST') {
+            res.writeHead(405, { Allow: 'POST' });
+            res.end();
+            return;
+        }
+        const reqUrl = req.url ?? '/';
+        const questionMarkIdx = reqUrl.indexOf('?');
+        const rawPath = questionMarkIdx === -1 ? reqUrl : reqUrl.slice(0, questionMarkIdx);
+        const normalised = normalisePath(rawPath);
+        const rule = this.pathIndex.get(normalised);
+        if (!rule) {
+            writeAudit({
+                t: this.now().toISOString(),
+                kind: 'rule-webhook-rejected',
+                deviceId: 'unknown',
+                command: rawPath,
+                parameter: null,
+                commandType: 'command',
+                dryRun: true,
+                result: 'error',
+                error: 'unknown-path',
+            });
+            res.writeHead(404);
+            res.end();
+            return;
+        }
+        const body = await readLimitedBody(req, MAX_BODY_BYTES);
+        if (body === null) {
+            res.writeHead(413);
+            res.end();
+            return;
+        }
+        const event = {
+            source: 'webhook',
+            event: normalised,
+            t: this.now(),
+            payload: { path: normalised, body },
+        };
+        // Accept the request before dispatch so callers aren't held waiting
+        // on rule actions (which can include SwitchBot API calls).
+        res.writeHead(202, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ status: 'accepted', path: normalised }));
+        this.opts.dispatch(rule, event).catch(() => undefined);
+    }
+    isAuthorized(req) {
+        const h = req.headers['authorization'];
+        if (typeof h !== 'string')
+            return false;
+        const match = /^Bearer\s+(.+)$/i.exec(h.trim());
+        if (!match)
+            return false;
+        const provided = Buffer.from(match[1].trim(), 'utf-8');
+        const expected = Buffer.from(this.opts.bearerToken, 'utf-8');
+        if (provided.length !== expected.length)
+            return false;
+        return timingSafeEqual(provided, expected);
+    }
+    now() {
+        return this.opts.now ? this.opts.now() : new Date();
+    }
+}
+function normalisePath(p) {
+    if (!p)
+        return '/';
+    let out = p.trim();
+    if (!out.startsWith('/'))
+        out = `/${out}`;
+    // Collapse a trailing slash (but leave the root '/').
+    if (out.length > 1 && out.endsWith('/'))
+        out = out.slice(0, -1);
+    return out;
+}
+function readLimitedBody(req, max) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        let total = 0;
+        req.on('data', (chunk) => {
+            total += chunk.length;
+            if (total > max) {
+                req.destroy();
+                resolve(null);
+                return;
+            }
+            chunks.push(chunk);
+        });
+        req.on('end', () => resolve(Buffer.concat(chunks).toString('utf-8')));
+        req.on('error', reject);
+    });
+}

package/dist/rules/webhook-token.js

@@ -0,0 +1,90 @@
+/**
+ * Webhook bearer-token management for the rules engine.
+ *
+ * Responsibilities:
+ *   - Resolve the bearer token the listener will accept. The order is
+ *     env var (SWITCHBOT_WEBHOOK_TOKEN) → on-disk cache
+ *     (~/.switchbot/webhook-token, chmod 0600) → generate a fresh
+ *     32-byte hex token and persist it.
+ *   - Rotate the token on demand (`rules webhook-rotate-token` cli).
+ *
+ * Why not the OS keychain (F1 abstraction)? The webhook bearer is a
+ * single opaque string, whereas `CredentialStore` is shaped around the
+ * SwitchBot {token,secret} bundle. Fitting a one-field artifact into
+ * that contract bloats every profile; keeping it in a 0600 file gives
+ * the same protection the CLI has used for `~/.switchbot/config.json`.
+ * Promotion into the keychain is a future follow-up once the
+ * abstraction grows a generic single-value slot.
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { randomBytes } from 'node:crypto';
+const ENV_TOKEN = 'SWITCHBOT_WEBHOOK_TOKEN';
+const DEFAULT_FILE = '.switchbot/webhook-token';
+export class WebhookTokenStore {
+    filePath;
+    envLookup;
+    constructor(opts = {}) {
+        this.filePath = opts.filePath ?? path.join(os.homedir(), DEFAULT_FILE);
+        this.envLookup = opts.envLookup ?? (() => process.env[ENV_TOKEN]);
+    }
+    /**
+     * Return a bearer token, creating + persisting one if none exists yet.
+     * Env var wins when set; otherwise the on-disk token is read (and
+     * generated on first call).
+     */
+    getOrCreate() {
+        const fromEnv = this.envLookup();
+        if (fromEnv && fromEnv.trim().length > 0)
+            return fromEnv.trim();
+        const existing = this.readFromDisk();
+        if (existing)
+            return existing;
+        const fresh = generateToken();
+        this.writeToDisk(fresh);
+        return fresh;
+    }
+    /**
+     * Read the persisted token, returning null when the file is absent
+     * or empty. Does NOT consult the env var — callers that want the
+     * env-aware path should use `getOrCreate()`.
+     */
+    readFromDisk() {
+        try {
+            const raw = fs.readFileSync(this.filePath, 'utf-8').trim();
+            return raw.length > 0 ? raw : null;
+        }
+        catch (err) {
+            if (err.code === 'ENOENT')
+                return null;
+            throw err;
+        }
+    }
+    /** Write a new token, persisting with 0600 perms. */
+    rotate() {
+        const fresh = generateToken();
+        this.writeToDisk(fresh);
+        return fresh;
+    }
+    getFilePath() {
+        return this.filePath;
+    }
+    writeToDisk(token) {
+        const dir = path.dirname(this.filePath);
+        fs.mkdirSync(dir, { recursive: true });
+        fs.writeFileSync(this.filePath, `${token}\n`, { mode: 0o600 });
+        // mkdirSync + writeFileSync race can leave broader perms on Windows
+        // (perm bits are mostly advisory there anyway), but on POSIX we
+        // re-chmod to be explicit about intent.
+        try {
+            fs.chmodSync(this.filePath, 0o600);
+        }
+        catch {
+            // non-POSIX filesystems may reject chmod — intentional best effort.
+        }
+    }
+}
+export function generateToken() {
+    return randomBytes(32).toString('hex');
+}

package/dist/status-sync/manager.js

@@ -0,0 +1,268 @@
+import { spawn, spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { tryLoadConfig } from '../config.js';
+import { getActiveProfile } from '../lib/request-context.js';
+import { UsageError } from '../utils/output.js';
+import { getConfigPath } from '../utils/flags.js';
+const DEFAULT_OPENCLAW_URL = 'http://localhost:18789';
+function resolveStatusSyncRuntime(options) {
+    if (!tryLoadConfig()) {
+        throw new UsageError('No credentials found. Run \'switchbot config set-token\' or set SWITCHBOT_TOKEN and SWITCHBOT_SECRET.');
+    }
+    const openclawToken = options.openclawToken ?? process.env.OPENCLAW_TOKEN;
+    if (!openclawToken) {
+        throw new UsageError('--openclaw-token is required or set OPENCLAW_TOKEN in the environment.');
+    }
+    const openclawModel = options.openclawModel ?? process.env.OPENCLAW_MODEL;
+    if (!openclawModel) {
+        throw new UsageError('--openclaw-model is required or set OPENCLAW_MODEL in the environment.');
+    }
+    return {
+        openclawUrl: options.openclawUrl ?? process.env.OPENCLAW_URL ?? DEFAULT_OPENCLAW_URL,
+        openclawToken,
+        openclawModel,
+        ...(options.topic ? { topic: options.topic } : {}),
+    };
+}
+export function resolveStatusSyncPaths(explicitStateDir) {
+    const stateDir = path.resolve(explicitStateDir
+        ?? process.env.SWITCHBOT_STATUS_SYNC_HOME
+        ?? path.join(os.homedir(), '.switchbot', 'status-sync'));
+    return {
+        stateDir,
+        stateFile: path.join(stateDir, 'state.json'),
+        stdoutLog: path.join(stateDir, 'stdout.log'),
+        stderrLog: path.join(stateDir, 'stderr.log'),
+    };
+}
+export function buildStatusSyncChildArgs(options) {
+    const scriptPath = process.argv[1];
+    if (!scriptPath) {
+        throw new Error('Cannot determine the current CLI entrypoint path.');
+    }
+    const args = [path.resolve(scriptPath)];
+    const configPath = getConfigPath();
+    const profile = getActiveProfile();
+    if (configPath) {
+        args.push('--config', path.resolve(configPath));
+    }
+    else if (profile) {
+        args.push('--profile', profile);
+    }
+    args.push('events', 'mqtt-tail', '--sink', 'openclaw', '--openclaw-url', options.openclawUrl, '--openclaw-model', options.openclawModel);
+    if (options.topic) {
+        args.push('--topic', options.topic);
+    }
+    return args;
+}
+function safeUnlink(filePath) {
+    try {
+        fs.unlinkSync(filePath);
+    }
+    catch {
+        // best-effort cleanup
+    }
+}
+function isProcessRunning(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === 'EPERM')
+            return true;
+        return false;
+    }
+}
+function readStateFile(paths) {
+    if (!fs.existsSync(paths.stateFile))
+        return null;
+    try {
+        const raw = JSON.parse(fs.readFileSync(paths.stateFile, 'utf-8'));
+        if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+            safeUnlink(paths.stateFile);
+            return null;
+        }
+        const parsed = raw;
+        if (typeof parsed.pid !== 'number' ||
+            !Number.isInteger(parsed.pid) ||
+            parsed.pid < 1 ||
+            typeof parsed.startedAt !== 'string' ||
+            !Array.isArray(parsed.command) ||
+            typeof parsed.stdoutLog !== 'string' ||
+            typeof parsed.stderrLog !== 'string') {
+            safeUnlink(paths.stateFile);
+            return null;
+        }
+        return {
+            pid: parsed.pid,
+            startedAt: parsed.startedAt,
+            command: parsed.command.map(String),
+            openclawUrl: typeof parsed.openclawUrl === 'string' ? parsed.openclawUrl : DEFAULT_OPENCLAW_URL,
+            openclawModel: typeof parsed.openclawModel === 'string' ? parsed.openclawModel : '',
+            topic: typeof parsed.topic === 'string' ? parsed.topic : null,
+            configPath: typeof parsed.configPath === 'string' ? parsed.configPath : null,
+            profile: typeof parsed.profile === 'string' ? parsed.profile : null,
+            stdoutLog: parsed.stdoutLog,
+            stderrLog: parsed.stderrLog,
+        };
+    }
+    catch {
+        safeUnlink(paths.stateFile);
+        return null;
+    }
+}
+function toStatus(paths, state, running) {
+    return {
+        running,
+        pid: running && state ? state.pid : null,
+        startedAt: running && state ? state.startedAt : null,
+        stateDir: paths.stateDir,
+        stateFile: paths.stateFile,
+        stdoutLog: state?.stdoutLog ?? paths.stdoutLog,
+        stderrLog: state?.stderrLog ?? paths.stderrLog,
+        command: running && state ? state.command : null,
+        openclawUrl: running && state ? state.openclawUrl : null,
+        openclawModel: running && state ? state.openclawModel : null,
+        topic: running && state ? state.topic : null,
+        configPath: running && state ? state.configPath : null,
+        profile: running && state ? state.profile : null,
+    };
+}
+function killProcessTree(pid) {
+    if (process.platform === 'win32') {
+        const result = spawnSync('taskkill', ['/PID', String(pid), '/T', '/F'], { stdio: 'ignore' });
+        if (result.error)
+            throw result.error;
+        if (result.status !== 0 && isProcessRunning(pid)) {
+            throw new Error(`Failed to stop status-sync process tree (PID ${pid}).`);
+        }
+        return;
+    }
+    try {
+        process.kill(-pid, 'SIGTERM');
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === 'ESRCH') {
+            return;
+        }
+        process.kill(pid, 'SIGTERM');
+    }
+}
+export function getStatusSyncStatus(options = {}) {
+    const paths = resolveStatusSyncPaths(options.stateDir);
+    const state = readStateFile(paths);
+    if (!state) {
+        return toStatus(paths, null, false);
+    }
+    if (!isProcessRunning(state.pid)) {
+        safeUnlink(paths.stateFile);
+        return toStatus(paths, null, false);
+    }
+    return toStatus(paths, state, true);
+}
+export function stopStatusSync(options = {}) {
+    const paths = resolveStatusSyncPaths(options.stateDir);
+    const state = readStateFile(paths);
+    if (!state) {
+        return {
+            stopped: false,
+            stale: false,
+            pid: null,
+            status: toStatus(paths, null, false),
+        };
+    }
+    if (!isProcessRunning(state.pid)) {
+        safeUnlink(paths.stateFile);
+        return {
+            stopped: false,
+            stale: true,
+            pid: state.pid,
+            status: toStatus(paths, null, false),
+        };
+    }
+    killProcessTree(state.pid);
+    if (isProcessRunning(state.pid)) {
+        throw new Error(`Failed to stop status-sync process (PID ${state.pid}); process is still running.`);
+    }
+    safeUnlink(paths.stateFile);
+    return {
+        stopped: true,
+        stale: false,
+        pid: state.pid,
+        status: toStatus(paths, null, false),
+    };
+}
+export function startStatusSync(options = {}) {
+    const runtime = resolveStatusSyncRuntime(options);
+    const paths = resolveStatusSyncPaths(options.stateDir);
+    const existing = getStatusSyncStatus({ stateDir: paths.stateDir });
+    if (existing.running) {
+        if (!options.force) {
+            throw new UsageError(`status-sync is already running (PID ${existing.pid}). Run 'switchbot status-sync stop' first or re-run with --force.`);
+        }
+        stopStatusSync({ stateDir: paths.stateDir });
+    }
+    fs.mkdirSync(paths.stateDir, { recursive: true });
+    const configPath = getConfigPath();
+    const command = buildStatusSyncChildArgs(runtime);
+    let stdoutFd = null;
+    let stderrFd = null;
+    try {
+        stdoutFd = fs.openSync(paths.stdoutLog, 'a');
+        stderrFd = fs.openSync(paths.stderrLog, 'a');
+        const child = spawn(process.execPath, command, {
+            detached: true,
+            stdio: ['ignore', stdoutFd, stderrFd],
+            windowsHide: true,
+            env: { ...process.env, OPENCLAW_TOKEN: runtime.openclawToken },
+        });
+        if (!child.pid) {
+            throw new Error('Failed to start status-sync child process.');
+        }
+        child.unref();
+        const state = {
+            pid: child.pid,
+            startedAt: new Date().toISOString(),
+            command: [process.execPath, ...command],
+            openclawUrl: runtime.openclawUrl,
+            openclawModel: runtime.openclawModel,
+            topic: runtime.topic ?? null,
+            configPath: configPath ? path.resolve(configPath) : null,
+            profile: configPath ? null : (getActiveProfile() ?? null),
+            stdoutLog: paths.stdoutLog,
+            stderrLog: paths.stderrLog,
+        };
+        fs.writeFileSync(paths.stateFile, JSON.stringify(state, null, 2), { mode: 0o600 });
+        return toStatus(paths, state, true);
+    }
+    finally {
+        if (stdoutFd !== null)
+            fs.closeSync(stdoutFd);
+        if (stderrFd !== null)
+            fs.closeSync(stderrFd);
+    }
+}
+export async function runStatusSyncForeground(options = {}) {
+    const runtime = resolveStatusSyncRuntime(options);
+    const command = buildStatusSyncChildArgs(runtime);
+    return await new Promise((resolve, reject) => {
+        const child = spawn(process.execPath, command, {
+            stdio: 'inherit',
+            windowsHide: true,
+            env: { ...process.env, OPENCLAW_TOKEN: runtime.openclawToken },
+        });
+        child.once('error', reject);
+        child.once('exit', (code, signal) => {
+            if (signal) {
+                resolve(1);
+                return;
+            }
+            resolve(code ?? 0);
+        });
+    });
+}

package/dist/utils/audit.js

@@ -1,8 +1,18 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { getAuditLog } from './flags.js';
-/** Bump when breaking changes to the audit line shape land. */
-export const AUDIT_VERSION = 1;
+/**
+ * Bump when breaking changes to the audit line shape land.
+ *
+ * History:
+ *   1 — initial command audit (kind: 'command' only).
+ *   2 — adds rule-engine kinds ('rule-fire', 'rule-fire-dry',
+ *       'rule-throttled', 'rule-webhook-rejected') and a sibling `rule`
+ *       block describing which rule fired and why. Reader stays backwards
+ *       compatible: v1 lines parse as command entries with `rule`
+ *       undefined.
+ */
+export const AUDIT_VERSION = 2;
 function resolveAuditPath() {
     const flag = getAuditLog();
     if (flag === null)