@switchbot/openapi-cli 2.6.4 → 3.0.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/schema/field-aliases.js

@@ -1,5 +1,20 @@
 import { UsageError } from '../utils/output.js';
+/**
+ * User-facing aliases for canonical field names.
+ *
+ * Keys are canonical names (matching API response keys and CLI/schema output);
+ * values are lowercase alternatives a user may type for `--fields` or `--filter`.
+ *
+ * Conflict rules (do not add an alias that violates these — tests will fail):
+ * - `temp` is exclusive to `temperature` (NOT `colorTemperature`, `targetTemperature`).
+ * - `motion` is exclusive to `moveDetected`; `moving` uses `active` instead.
+ * - `mode` is exclusive to top-level `mode` (preset); device-specific modes go through `deviceMode`.
+ * - Reserved / too-generic words never appear as aliases: `auto`, `status`, `state`,
+ *   `switch`, `type`, `on`, `off`.
+ * - Device-type words are never aliases: `lock`, `fan`.
+ */
 export const FIELD_ALIASES = {
+    // Identification (shared with list/filter)
     deviceId: ['id'],
     deviceName: ['name'],
     deviceType: ['type'],
@@ -10,7 +25,71 @@ export const FIELD_ALIASES = {
     hubDeviceId: ['hub'],
     enableCloudService: ['cloud'],
     alias: ['alias'],
+    // Phase 1 — common status fields
+    battery: ['batt', 'bat'],
+    temperature: ['temp', 'ambient'],
+    colorTemperature: ['kelvin', 'colortemp'],
+    humidity: ['humid', 'rh'],
+    brightness: ['bright', 'bri'],
+    fanSpeed: ['speed'],
+    position: ['pos'],
+    moveDetected: ['motion'],
+    openState: ['open'],
+    doorState: ['door'],
+    CO2: ['co2'],
+    power: ['enabled'],
+    mode: ['preset'],
+    // Phase 2 — niche device fields
+    childLock: ['safe', 'childlock'],
+    targetTemperature: ['setpoint', 'target'],
+    electricCurrent: ['current', 'amps'],
+    voltage: ['volts'],
+    usedElectricity: ['energy', 'kwh'],
+    electricityOfDay: ['daily', 'today'],
+    weight: ['load'],
+    version: ['firmware', 'fw'],
+    lightLevel: ['light', 'lux'],
+    oscillation: ['swing', 'osc'],
+    verticalOscillation: ['vswing'],
+    nightStatus: ['night'],
+    chargingStatus: ['charging', 'charge'],
+    switch1Status: ['ch1', 'channel1'],
+    switch2Status: ['ch2', 'channel2'],
+    taskType: ['task'],
+    moving: ['active'],
+    onlineStatus: ['online_status'],
+    workingStatus: ['working'],
+    // Phase 3 — catalog statusFields coverage
+    group: ['cluster'],
+    calibrate: ['calibration', 'calib'],
+    direction: ['tilt'],
+    deviceMode: ['devmode'],
+    nebulizationEfficiency: ['mist', 'spray'],
+    sound: ['audio'],
+    lackWater: ['tank', 'water-low'],
+    filterElement: ['filter'],
+    color: ['rgb', 'hex'],
+    useTime: ['runtime', 'uptime'],
+    switchStatus: ['relay'],
+    lockState: ['locked'],
+    slidePosition: ['slide'],
+    // Phase 4 — ultra-niche sensor + webhook fields (~98% coverage target)
+    waterLeakDetect: ['leak', 'water'],
+    pressure: ['press', 'pa'],
+    moveCount: ['movecnt'],
+    errorCode: ['err'],
+    buttonName: ['btn', 'button'],
+    pressedAt: ['pressed'],
+    deviceMac: ['mac'],
+    detectionState: ['detected', 'detect'],
 };
+/**
+ * Resolve a user-typed field name to its canonical form against an allowed list.
+ *
+ * Matching is case-insensitive and trims surrounding whitespace. Direct matches
+ * win over alias matches. Throws UsageError if the input is empty or does not
+ * match any canonical / alias in the allowed list.
+ */
 export function resolveField(input, allowedCanonical) {
     const normalized = input.trim().toLowerCase();
     if (!normalized) {
@@ -19,12 +98,21 @@ export function resolveField(input, allowedCanonical) {
     for (const canonical of allowedCanonical) {
         if (canonical.toLowerCase() === normalized)
             return canonical;
+    }
+    for (const canonical of allowedCanonical) {
         const aliases = FIELD_ALIASES[canonical] ?? [];
         if (aliases.some((a) => a.toLowerCase() === normalized))
             return canonical;
     }
     throw new UsageError(`Unknown field "${input}". Supported: ${listSupportedFieldInputs(allowedCanonical).join(', ')}`);
 }
+/**
+ * Resolve every field in a list. Preserves order and the original UsageError
+ * from resolveField() on the first unknown input.
+ */
+export function resolveFieldList(inputs, allowedCanonical) {
+    return inputs.map((f) => resolveField(f, allowedCanonical));
+}
 export function listSupportedFieldInputs(allowedCanonical) {
     const out = new Set();
     for (const canonical of allowedCanonical) {
@@ -34,3 +122,10 @@ export function listSupportedFieldInputs(allowedCanonical) {
     }
     return [...out];
 }
+/**
+ * All canonical keys known to the alias registry. Use when no dynamic
+ * canonical list is available (e.g. `watch` before the first poll response).
+ */
+export function listAllCanonical() {
+    return Object.keys(FIELD_ALIASES);
+}