@switchbot/openapi-cli 2.7.2 → 3.0.0

package/dist/credentials/backends/macos.js

@@ -0,0 +1,129 @@
+/**
+ * macOS Keychain backend.
+ *
+ * Wraps the built-in `security(1)` CLI so `npm install` stays free of
+ * native compile steps. Service name is shared with the Linux and
+ * Windows backends (`com.openclaw.switchbot`), so a user migrating a
+ * config between machines sees the same lookup shape.
+ *
+ * Errors never leak credential material — `add-generic-password`
+ * receives the password via `-w <value>` on argv, which is visible in
+ * `ps` to the current user but not persisted anywhere, and any stderr
+ * we surface back up is bounded to the library's own messages
+ * (`password not found`, `could not be added`, etc.) rather than our
+ * input values.
+ */
+import { spawn } from 'node:child_process';
+import { accountFor, CREDENTIAL_SERVICE, KeychainError, } from '../keychain.js';
+function run(cmd, args, stdin) {
+    return new Promise((resolve) => {
+        const proc = spawn(cmd, args, { stdio: ['pipe', 'pipe', 'pipe'] });
+        let stdout = '';
+        let stderr = '';
+        proc.stdout.on('data', (buf) => {
+            stdout += buf.toString('utf-8');
+        });
+        proc.stderr.on('data', (buf) => {
+            stderr += buf.toString('utf-8');
+        });
+        proc.on('error', () => resolve({ code: 127, stdout, stderr }));
+        proc.on('close', (code) => resolve({ code: code ?? 0, stdout, stderr }));
+        if (stdin !== undefined) {
+            proc.stdin.write(stdin);
+        }
+        proc.stdin.end();
+    });
+}
+export async function macOsAvailable() {
+    if (process.platform !== 'darwin')
+        return false;
+    const res = await run('which', ['security']);
+    return res.code === 0 && res.stdout.trim().length > 0;
+}
+async function readField(profile, field) {
+    const account = accountFor(profile, field);
+    const res = await run('security', [
+        'find-generic-password',
+        '-s', CREDENTIAL_SERVICE,
+        '-a', account,
+        '-w',
+    ]);
+    if (res.code !== 0)
+        return null;
+    const value = res.stdout.replace(/\n$/, '');
+    return value.length > 0 ? value : null;
+}
+async function writeField(profile, field, value) {
+    const account = accountFor(profile, field);
+    const res = await run('security', [
+        'add-generic-password',
+        '-U', // update if exists
+        '-s', CREDENTIAL_SERVICE,
+        '-a', account,
+        '-w', value,
+    ]);
+    if (res.code !== 0) {
+        throw new KeychainError('keychain', 'set', `security(1) exit ${res.code}`);
+    }
+}
+async function deleteField(profile, field) {
+    const account = accountFor(profile, field);
+    const res = await run('security', [
+        'delete-generic-password',
+        '-s', CREDENTIAL_SERVICE,
+        '-a', account,
+    ]);
+    // exit 44 = "The specified item could not be found" — tolerate as idempotent delete.
+    if (res.code !== 0 && res.code !== 44) {
+        throw new KeychainError('keychain', 'delete', `security(1) exit ${res.code}`);
+    }
+}
+async function restoreField(profile, field, value) {
+    try {
+        if (value === null) {
+            await deleteField(profile, field);
+            return;
+        }
+        await writeField(profile, field, value);
+    }
+    catch {
+        // Best effort only. Preserve the original write failure.
+    }
+}
+export function createMacOsBackend() {
+    return {
+        name: 'keychain',
+        async get(profile) {
+            const token = await readField(profile, 'token');
+            const secret = await readField(profile, 'secret');
+            if (!token || !secret)
+                return null;
+            return { token, secret };
+        },
+        async set(profile, creds) {
+            const previousToken = await readField(profile, 'token');
+            const previousSecret = await readField(profile, 'secret');
+            try {
+                await writeField(profile, 'token', creds.token);
+                await writeField(profile, 'secret', creds.secret);
+            }
+            catch (err) {
+                await restoreField(profile, 'token', previousToken);
+                await restoreField(profile, 'secret', previousSecret);
+                throw err;
+            }
+        },
+        async delete(profile) {
+            await deleteField(profile, 'token');
+            await deleteField(profile, 'secret');
+        },
+        describe() {
+            return {
+                backend: 'macOS Keychain',
+                tag: 'keychain',
+                writable: true,
+                notes: `Stored under service "${CREDENTIAL_SERVICE}" via security(1).`,
+            };
+        },
+    };
+}

package/dist/credentials/backends/windows.js

@@ -0,0 +1,215 @@
+/**
+ * Windows Credential Manager backend.
+ *
+ * Uses PowerShell + Win32 P/Invoke (`CredReadW` / `CredWriteW` /
+ * `CredDeleteW`) instead of a native binding so `npm install` stays
+ * toolchain-free on Windows runners. `cmdkey.exe` could create and
+ * delete credentials but can't read the password back — reading is the
+ * whole point, so PowerShell is mandatory.
+ *
+ * Target-name shape is `com.openclaw.switchbot:<profile>:<field>` so
+ * `rundll32.exe keymgr.dll,KRShowKeyMgr` displays our entries in a
+ * clear, groupable list.
+ *
+ * Credential values are passed to the child process via environment
+ * variables, not argv — this keeps them out of any process listing
+ * and out of the PowerShell command history. Env blocks on Windows
+ * are only visible to the current user (and admins), so this is a
+ * reasonable trade versus the alternatives (stdin requires a second
+ * round-trip; temp files leave disk residue).
+ */
+import { spawn } from 'node:child_process';
+import { accountFor, CREDENTIAL_SERVICE, KeychainError, } from '../keychain.js';
+const PS_HEADER = `$ErrorActionPreference = 'Stop'
+Add-Type -MemberDefinition @'
+[DllImport("Advapi32.dll", SetLastError=true, CharSet=CharSet.Unicode)]
+public static extern bool CredReadW(string target, int type, int flags, out System.IntPtr credentialPtr);
+
+[DllImport("Advapi32.dll", SetLastError=true, CharSet=CharSet.Unicode)]
+public static extern bool CredWriteW(ref CREDENTIAL cred, int flags);
+
+[DllImport("Advapi32.dll", SetLastError=true, CharSet=CharSet.Unicode)]
+public static extern bool CredDeleteW(string target, int type, int flags);
+
+[DllImport("Advapi32.dll", SetLastError=true)]
+public static extern void CredFree(System.IntPtr buffer);
+
+[System.Runtime.InteropServices.StructLayout(System.Runtime.InteropServices.LayoutKind.Sequential)]
+public struct CREDENTIAL {
+    public int Flags;
+    public int Type;
+    public System.IntPtr TargetName;
+    public System.IntPtr Comment;
+    public System.Runtime.InteropServices.ComTypes.FILETIME LastWritten;
+    public int CredentialBlobSize;
+    public System.IntPtr CredentialBlob;
+    public int Persist;
+    public int AttributeCount;
+    public System.IntPtr Attributes;
+    public System.IntPtr TargetAlias;
+    public System.IntPtr UserName;
+}
+'@ -Name CredApi -Namespace Win32 | Out-Null
+`;
+const PS_GET = `${PS_HEADER}
+$target = $env:SWITCHBOT_CRED_TARGET
+$ptr = [System.IntPtr]::Zero
+$ok = [Win32.CredApi]::CredReadW($target, 1, 0, [ref]$ptr)
+if (-not $ok) { exit 2 }
+$cred = [System.Runtime.InteropServices.Marshal]::PtrToStructure($ptr, [type][Win32.CredApi+CREDENTIAL])
+$bytes = New-Object byte[] $cred.CredentialBlobSize
+[System.Runtime.InteropServices.Marshal]::Copy($cred.CredentialBlob, $bytes, 0, $cred.CredentialBlobSize)
+[Win32.CredApi]::CredFree($ptr) | Out-Null
+$password = [System.Text.Encoding]::Unicode.GetString($bytes)
+[Console]::Out.Write([Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes($password)))
+`;
+const PS_SET = `${PS_HEADER}
+$target = $env:SWITCHBOT_CRED_TARGET
+$user = $env:SWITCHBOT_CRED_USER
+$value = $env:SWITCHBOT_CRED_VALUE
+$bytes = [System.Text.Encoding]::Unicode.GetBytes($value)
+$blob = [System.Runtime.InteropServices.Marshal]::AllocHGlobal($bytes.Length)
+[System.Runtime.InteropServices.Marshal]::Copy($bytes, 0, $blob, $bytes.Length)
+$cred = New-Object Win32.CredApi+CREDENTIAL
+$cred.Flags = 0
+$cred.Type = 1
+$cred.TargetName = [System.Runtime.InteropServices.Marshal]::StringToCoTaskMemUni($target)
+$cred.UserName = [System.Runtime.InteropServices.Marshal]::StringToCoTaskMemUni($user)
+$cred.CredentialBlob = $blob
+$cred.CredentialBlobSize = $bytes.Length
+$cred.Persist = 2
+$cred.AttributeCount = 0
+$ok = [Win32.CredApi]::CredWriteW([ref]$cred, 0)
+[System.Runtime.InteropServices.Marshal]::FreeCoTaskMem($cred.TargetName)
+[System.Runtime.InteropServices.Marshal]::FreeCoTaskMem($cred.UserName)
+[System.Runtime.InteropServices.Marshal]::FreeHGlobal($blob)
+if (-not $ok) { exit 3 }
+`;
+const PS_DELETE = `${PS_HEADER}
+$target = $env:SWITCHBOT_CRED_TARGET
+$ok = [Win32.CredApi]::CredDeleteW($target, 1, 0)
+if (-not $ok) {
+  $errno = [System.Runtime.InteropServices.Marshal]::GetLastWin32Error()
+  # 1168 = ERROR_NOT_FOUND — tolerate as idempotent delete.
+  if ($errno -ne 1168) { exit 4 }
+}
+`;
+function encodePs(script) {
+    return Buffer.from(script, 'utf16le').toString('base64');
+}
+function runPowerShell(script, env) {
+    return new Promise((resolve) => {
+        const proc = spawn('powershell.exe', ['-NoProfile', '-NonInteractive', '-EncodedCommand', encodePs(script)], {
+            stdio: ['ignore', 'pipe', 'pipe'],
+            env: { ...process.env, ...env },
+        });
+        let stdout = '';
+        let stderr = '';
+        proc.stdout.on('data', (buf) => {
+            stdout += buf.toString('utf-8');
+        });
+        proc.stderr.on('data', (buf) => {
+            stderr += buf.toString('utf-8');
+        });
+        proc.on('error', () => resolve({ code: 127, stdout, stderr }));
+        proc.on('close', (code) => resolve({ code: code ?? 0, stdout, stderr }));
+    });
+}
+function targetFor(profile, field) {
+    return `${CREDENTIAL_SERVICE}:${accountFor(profile, field)}`;
+}
+export async function windowsAvailable() {
+    if (process.platform !== 'win32')
+        return false;
+    return new Promise((resolve) => {
+        const proc = spawn('where', ['powershell.exe'], { stdio: ['ignore', 'pipe', 'pipe'] });
+        let ok = false;
+        proc.stdout.on('data', (buf) => {
+            if (buf.toString().trim().length > 0)
+                ok = true;
+        });
+        proc.on('error', () => resolve(false));
+        proc.on('close', (code) => resolve(ok && (code ?? 0) === 0));
+    });
+}
+async function readField(profile, field) {
+    const res = await runPowerShell(PS_GET, {
+        SWITCHBOT_CRED_TARGET: targetFor(profile, field),
+    });
+    if (res.code !== 0)
+        return null;
+    try {
+        const decoded = Buffer.from(res.stdout, 'base64').toString('utf-8');
+        return decoded.length > 0 ? decoded : null;
+    }
+    catch {
+        return null;
+    }
+}
+async function writeField(profile, field, value) {
+    const res = await runPowerShell(PS_SET, {
+        SWITCHBOT_CRED_TARGET: targetFor(profile, field),
+        SWITCHBOT_CRED_USER: accountFor(profile, field),
+        SWITCHBOT_CRED_VALUE: value,
+    });
+    if (res.code !== 0) {
+        throw new KeychainError('credman', 'set', `CredWrite exit ${res.code}`);
+    }
+}
+async function deleteField(profile, field) {
+    const res = await runPowerShell(PS_DELETE, {
+        SWITCHBOT_CRED_TARGET: targetFor(profile, field),
+    });
+    if (res.code !== 0) {
+        throw new KeychainError('credman', 'delete', `CredDelete exit ${res.code}`);
+    }
+}
+async function restoreField(profile, field, value) {
+    try {
+        if (value === null) {
+            await deleteField(profile, field);
+            return;
+        }
+        await writeField(profile, field, value);
+    }
+    catch {
+        // Best effort only. Preserve the original write failure.
+    }
+}
+export function createWindowsBackend() {
+    return {
+        name: 'credman',
+        async get(profile) {
+            const token = await readField(profile, 'token');
+            const secret = await readField(profile, 'secret');
+            if (!token || !secret)
+                return null;
+            return { token, secret };
+        },
+        async set(profile, creds) {
+            const previousToken = await readField(profile, 'token');
+            const previousSecret = await readField(profile, 'secret');
+            try {
+                await writeField(profile, 'token', creds.token);
+                await writeField(profile, 'secret', creds.secret);
+            }
+            catch (err) {
+                await restoreField(profile, 'token', previousToken);
+                await restoreField(profile, 'secret', previousSecret);
+                throw err;
+            }
+        },
+        async delete(profile) {
+            await deleteField(profile, 'token');
+            await deleteField(profile, 'secret');
+        },
+        describe() {
+            return {
+                backend: 'Credential Manager (Windows)',
+                tag: 'credman',
+                writable: true,
+                notes: `Stored under target "${CREDENTIAL_SERVICE}:*" via Win32 CredRead/CredWrite.`,
+            };
+        },
+    };
+}

package/dist/credentials/keychain.js

@@ -0,0 +1,88 @@
+/**
+ * OS-keychain credential store abstraction.
+ *
+ * F1 scope (plan: `feat/v2.8-policy-tooling`):
+ *   - Defines the `CredentialStore` contract the rest of the CLI can
+ *     depend on (token/secret per profile, auditable describe(), best-
+ *     effort delete()).
+ *   - Ships four backends: `macos` (security(1)), `linux`
+ *     (secret-tool), `windows` (PowerShell + Win32 CredRead/CredWrite)
+ *     and `file` (the existing `~/.switchbot/config.json` shape as
+ *     last-resort fallback).
+ *   - `selectCredentialStore()` picks the OS-native backend first and
+ *     silently degrades to `file` whenever a backend is absent or
+ *     non-writable — so a fresh Linux box without libsecret installed
+ *     still Just Works.
+ *
+ * Out of scope here: migrating existing users off `~/.switchbot/config.json`
+ * into the keychain. F3's `switchbot auth keychain migrate` subcommand
+ * handles the explicit opt-in; F2 only wires the *read* path.
+ *
+ * Design choices:
+ *   - No native bindings. Every native backend shells out to an
+ *     OS-provided CLI / interpreter, which keeps `npm install` free of
+ *     compile steps on CI machines.
+ *   - Errors never leak credential material to logs or stderr. On any
+ *     subprocess failure backends return `null` (read) or throw a
+ *     `KeychainError` without the input token/secret in the message.
+ *   - Service / account namespacing is identical across backends
+ *     (`com.openclaw.switchbot` / `<profile>:<field>`) so a user can
+ *     move between machines and expect `switchbot auth keychain get`
+ *     to produce the same lookup shape.
+ */
+export const CREDENTIAL_SERVICE = 'com.openclaw.switchbot';
+export const CREDENTIAL_FIELDS = ['token', 'secret'];
+/**
+ * Thrown when a backend cannot service a `set`/`delete` request even
+ * though it reported itself as writable. Never includes the
+ * credential material in the message.
+ */
+export class KeychainError extends Error {
+    backend;
+    operation;
+    constructor(backend, operation, message) {
+        super(`[${backend}] ${operation} failed: ${message}`);
+        this.backend = backend;
+        this.operation = operation;
+        this.name = 'KeychainError';
+    }
+}
+/** Encode the account string used by every native backend. Kept public
+ * so F3's CLI can show what the underlying keychain will see. */
+export function accountFor(profile, field) {
+    return `${profile}:${field}`;
+}
+/**
+ * Select the best backend for the current platform. The caller does
+ * not need to handle "no keychain available" — this function always
+ * returns a store, falling back to the file backend if necessary.
+ *
+ * Detection is done eagerly at call time (cheap `which` probe) so a
+ * long-running process reflects environment changes (e.g. user
+ * installs secret-tool after first run). Selection does NOT mutate
+ * any state; calling it twice returns fresh instances.
+ */
+export async function selectCredentialStore(opts = {}) {
+    if (opts.preferFile) {
+        const { createFileBackend } = await import('./backends/file.js');
+        return createFileBackend();
+    }
+    const platform = process.platform;
+    if (platform === 'darwin') {
+        const { createMacOsBackend, macOsAvailable } = await import('./backends/macos.js');
+        if (await macOsAvailable())
+            return createMacOsBackend();
+    }
+    else if (platform === 'linux') {
+        const { createLinuxBackend, linuxAvailable } = await import('./backends/linux.js');
+        if (await linuxAvailable())
+            return createLinuxBackend();
+    }
+    else if (platform === 'win32') {
+        const { createWindowsBackend, windowsAvailable } = await import('./backends/windows.js');
+        if (await windowsAvailable())
+            return createWindowsBackend();
+    }
+    const { createFileBackend } = await import('./backends/file.js');
+    return createFileBackend();
+}

package/dist/credentials/prime.js

@@ -0,0 +1,52 @@
+/**
+ * Credential priming cache.
+ *
+ * `loadConfig()` runs synchronously, but every OS keychain backend is
+ * async (subprocess-based). We bridge the two by priming credentials
+ * once per command, early in the `preAction` hook, and keeping the
+ * result in a tiny in-process cache keyed by profile name.
+ *
+ * After priming, sync callers can consult `getPrimedCredentials()` to
+ * pick up keychain-stored token/secret without any await.
+ *
+ * This module intentionally swallows errors — a flaky keychain
+ * probe must never block the CLI from running. When the probe fails
+ * we behave as "nothing primed" and the existing file path is used.
+ */
+import { selectCredentialStore } from './keychain.js';
+let cache = null;
+/**
+ * Look up the given profile in the active credential store and cache
+ * the result. Safe to call multiple times — subsequent calls with the
+ * same profile short-circuit against the cache. Swallows all errors.
+ */
+export async function primeCredentials(profile) {
+    if (cache?.profile === profile)
+        return;
+    try {
+        const store = await selectCredentialStore();
+        const creds = await store.get(profile);
+        cache = { profile, creds };
+    }
+    catch {
+        cache = { profile, creds: null };
+    }
+}
+/**
+ * Sync accessor for code paths that cannot be made async. Returns
+ * null when the cache is empty or keyed against a different profile,
+ * so existing file-based fallback stays the authoritative source.
+ */
+export function getPrimedCredentials(profile) {
+    if (!cache)
+        return null;
+    if (cache.profile !== profile)
+        return null;
+    return cache.creds;
+}
+/**
+ * Test helper. Not used by production code.
+ */
+export function __resetPrimedCredentials() {
+    cache = null;
+}

package/dist/devices/catalog.js

@@ -10,9 +10,6 @@
  *   - CommandSpec.safetyTier: explicit action safety classification. See
  *     SafetyTier for the 5-tier enum. Built-in entries set this on the
  *     destructive tier; other tiers are derived (see deriveSafetyTier).
- *   - CommandSpec.destructive (deprecated, v3.0 removal): legacy boolean
- *     that maps to safetyTier === 'destructive'. Still accepted in
- *     ~/.switchbot/catalog.json overlays and derived into safetyTier.
  *   - DeviceCatalogEntry.role: functional grouping for filter/search
  *     ("all lighting", "all security"). Does not affect API behavior.
  *   - DeviceCatalogEntry.readOnly: the device has no control commands; it
@@ -629,25 +626,22 @@ export function findCatalogEntry(query) {
  *
  * The inference order is:
  *   1. Explicit `spec.safetyTier`.
- *   2. Legacy `spec.destructive: true` → `'destructive'` (overlay compat).
- *   3. IR context (customize command OR entry.category === 'ir')
+ *   2. IR context (customize command OR entry.category === 'ir')
  *      → `'ir-fire-forget'`.
- *   4. Default → `'mutation'`.
+ *   3. Default → `'mutation'`.
  */
 export function deriveSafetyTier(spec, entry) {
     if (spec.safetyTier)
         return spec.safetyTier;
-    if (spec.destructive)
-        return 'destructive';
     if (spec.commandType === 'customize')
         return 'ir-fire-forget';
     if (entry?.category === 'ir')
         return 'ir-fire-forget';
     return 'mutation';
 }
-/** Read the safety reason for a command, with fallback to the legacy field. */
+/** Read the safety reason for a command. */
 export function getCommandSafetyReason(spec) {
-    return spec.safetyReason ?? spec.destructiveReason ?? null;
+    return spec.safetyReason ?? null;
 }
 /**
  * Pick up to 3 non-destructive, idempotent commands an agent can safely invoke

package/dist/index.js

@@ -23,6 +23,14 @@ import { registerHistoryCommand } from './commands/history.js';
 import { registerPlanCommand } from './commands/plan.js';
 import { registerCapabilitiesCommand } from './commands/capabilities.js';
 import { registerAgentBootstrapCommand } from './commands/agent-bootstrap.js';
+import { registerPolicyCommand } from './commands/policy.js';
+import { registerRulesCommand } from './commands/rules.js';
+import { registerAuthCommand } from './commands/auth.js';
+import { registerInstallCommand } from './commands/install.js';
+import { registerUninstallCommand } from './commands/uninstall.js';
+import { registerStatusSyncCommand } from './commands/status-sync.js';
+import { primeCredentials } from './credentials/prime.js';
+import { getActiveProfile } from './lib/request-context.js';
 const require = createRequire(import.meta.url);
 const { version: pkgVersion } = require('../package.json');
 // Early initialization: check for --no-color flag or NO_COLOR env var and disable chalk.
@@ -41,7 +49,7 @@ if (isJsonMode()) {
 const TOP_LEVEL_COMMANDS = [
     'config', 'devices', 'scenes', 'webhook', 'completion', 'mcp',
     'quota', 'catalog', 'cache', 'events', 'doctor', 'schema',
-    'history', 'plan', 'capabilities', 'agent-bootstrap',
+    'history', 'plan', 'capabilities', 'agent-bootstrap', 'install', 'uninstall', 'status-sync',
 ];
 const cacheModeArg = (value) => {
     if (value.startsWith('-')) {
@@ -94,6 +102,19 @@ registerHistoryCommand(program);
 registerPlanCommand(program);
 registerCapabilitiesCommand(program);
 registerAgentBootstrapCommand(program);
+registerPolicyCommand(program);
+registerRulesCommand(program);
+registerAuthCommand(program);
+registerInstallCommand(program);
+registerUninstallCommand(program);
+registerStatusSyncCommand(program);
+// Prime keychain-stored credentials before any command runs. This is a
+// best-effort probe: failures are silently swallowed inside primeCredentials,
+// so the existing file-based path remains the safety net. We probe once per
+// invocation (even for --help and --version, which is harmless).
+program.hook('preAction', async () => {
+    await primeCredentials(getActiveProfile() ?? 'default');
+});
 program.addHelpText('after', `
 Credentials:
   Provide SwitchBot API v1.1 credentials via either:
@@ -122,6 +143,7 @@ Examples:
   $ switchbot devices command <deviceId> turnOn --dry-run
   $ switchbot scenes execute <sceneId> --verbose
   $ switchbot webhook setup https://your.host/hook
+  $ switchbot status-sync start --openclaw-model home-agent
 
 Discovery:
   Don't know a device ID / what it supports?