@instaclaw/dispatch 0.2.0 → 0.3.1

package/dist/auth.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Generate auth params for WebSocket handshake (client-side).
+ */
+export declare function generateHandshake(gatewayToken: string): {
+    hmac: string;
+    ts: string;
+    nonce: string;
+};
+/**
+ * Build the WebSocket URL with auth query params.
+ */
+export declare function buildAuthUrl(vmAddress: string, port: number, gatewayToken: string): string;
+/**
+ * Verify auth params from WebSocket handshake (server-side).
+ * Returns null on success, error string on failure.
+ */
+export declare function verifyHandshake(hmac: string, ts: string, nonce: string, gatewayToken: string, seenNonces: Map<string, number>): string | null;
+/**
+ * Clean up expired nonces (call periodically).
+ */
+export declare function cleanupNonces(seenNonces: Map<string, number>, maxAgeMs?: number): void;

package/dist/auth.js

@@ -0,0 +1,64 @@
+/**
+ * Auth — HMAC-based authentication for the dispatch WebSocket handshake.
+ *
+ * Protocol:
+ *   Client sends: ?hmac=<hex>&ts=<unix_ms>&nonce=<random_hex>
+ *   Server computes: HMAC-SHA256(gateway_token, ts + ":" + nonce)
+ *   Server verifies: hmac matches, ts within 30s, nonce not seen before
+ */
+import crypto from "crypto";
+const HANDSHAKE_MAX_AGE_MS = 30_000; // 30 seconds
+/**
+ * Generate auth params for WebSocket handshake (client-side).
+ */
+export function generateHandshake(gatewayToken) {
+    const ts = String(Date.now());
+    const nonce = crypto.randomBytes(16).toString("hex");
+    const hmac = crypto.createHmac("sha256", gatewayToken)
+        .update(ts + ":" + nonce)
+        .digest("hex");
+    return { hmac, ts, nonce };
+}
+/**
+ * Build the WebSocket URL with auth query params.
+ */
+export function buildAuthUrl(vmAddress, port, gatewayToken) {
+    const { hmac, ts, nonce } = generateHandshake(gatewayToken);
+    return `wss://${vmAddress}:${port}?hmac=${hmac}&ts=${ts}&nonce=${nonce}`;
+}
+/**
+ * Verify auth params from WebSocket handshake (server-side).
+ * Returns null on success, error string on failure.
+ */
+export function verifyHandshake(hmac, ts, nonce, gatewayToken, seenNonces) {
+    // Timestamp check
+    const tsMs = parseInt(ts, 10);
+    if (isNaN(tsMs) || Math.abs(Date.now() - tsMs) > HANDSHAKE_MAX_AGE_MS) {
+        return "Handshake expired (timestamp > 30s old)";
+    }
+    // Nonce replay check
+    if (seenNonces.has(nonce)) {
+        return "Nonce already used (replay attack)";
+    }
+    // HMAC verification
+    const expected = crypto.createHmac("sha256", gatewayToken)
+        .update(ts + ":" + nonce)
+        .digest("hex");
+    if (!crypto.timingSafeEqual(Buffer.from(hmac, "hex"), Buffer.from(expected, "hex"))) {
+        return "HMAC verification failed";
+    }
+    // Record nonce (clean up old ones)
+    seenNonces.set(nonce, Date.now());
+    return null;
+}
+/**
+ * Clean up expired nonces (call periodically).
+ */
+export function cleanupNonces(seenNonces, maxAgeMs = 60_000) {
+    const cutoff = Date.now() - maxAgeMs;
+    for (const [nonce, ts] of seenNonces) {
+        if (ts < cutoff)
+            seenNonces.delete(nonce);
+    }
+}
+//# sourceMappingURL=auth.js.map

package/dist/connection.js

@@ -5,13 +5,14 @@
 import WebSocket from "ws";
 import { executeCommand } from "./executor.js";
 import { requestApproval } from "./supervisor.js";
+import { buildAuthUrl } from "./auth.js";
 let ws = null;
 let reconnectDelay = 1000;
 let shouldReconnect = true;
 let commandsExecuted = 0;
 export function connect(opts) {
-    const proto = "wss";
-    const url = `${proto}://${opts.vmAddress}:${opts.port}?token=${opts.gatewayToken}`;
+    // HMAC-authenticated URL (token + timestamp + nonce)
+    const url = buildAuthUrl(opts.vmAddress, opts.port, opts.gatewayToken);
     console.log(`  Connecting to ${opts.vmAddress}:${opts.port}...`);
     ws = new WebSocket(url, {
         rejectUnauthorized: false, // Accept self-signed certs (TOFU model)
@@ -26,13 +27,11 @@ export function connect(opts) {
             return; // We don't expect binary from the server
         try {
             const command = JSON.parse(data.toString());
-            // Supervised mode: ask user for approval
-            if (opts.mode === "supervised") {
-                const approved = await requestApproval(command);
-                if (!approved) {
-                    sendResult(command.id, { success: false, error: "User denied the action" });
-                    return;
-                }
+            // Check approval (supervisor handles mode logic — prompts in supervised, auto-approves in autonomous, blocks dangerous)
+            const approved = await requestApproval(command);
+            if (!approved) {
+                sendResult(command.id, { success: false, error: "User denied the action" });
+                return;
             }
             // Execute the command
             const result = await executeCommand(command);

package/dist/executor.js

@@ -3,10 +3,11 @@
  * Returns results (action confirmations or screenshot data).
  */
 import { execSync } from "child_process";
-import fs from "fs";
-import path from "path";
+import { captureScreenshot } from "./screenshot.js";
 // Dynamic import for usecomputer (ESM)
 let uc = null;
+// Track the most recent coordMap from screenshots for click mapping
+let lastCoordMap = null;
 async function getUC() {
     if (!uc) {
         uc = await import("usecomputer");
@@ -27,6 +28,8 @@ export async function executeCommand(command) {
                 return await doPress(params);
             case "scroll":
                 return await doScroll(params);
+            case "drag":
+                return await doDrag(params);
             case "windows":
                 return await listWindows();
             default:
@@ -38,45 +41,44 @@ export async function executeCommand(command) {
     }
 }
 async function takeScreenshot(params) {
+    const capture = await captureScreenshot({
+        format: params.format || "jpeg",
+        quality: Number(params.quality) || 80,
+    });
+    // Cache coordMap for subsequent click/hover/drag commands
+    lastCoordMap = capture.coordMap;
+    return {
+        success: true,
+        screenshotBuffer: capture.buffer,
+        screenshotMeta: {
+            width: capture.width,
+            height: capture.height,
+            format: capture.format,
+            coordMap: capture.coordMap,
+        },
+    };
+}
+async function doClick(params) {
     const usecomputer = await getUC();
-    const tmpPath = path.join("/tmp", `dispatch-ss-${Date.now()}.png`);
-    try {
-        const result = await usecomputer.screenshot({ path: tmpPath, display: null, window: null, region: null, annotate: null });
-        // Read the PNG and convert to JPEG via sharp
-        const pngBuffer = fs.readFileSync(tmpPath);
-        let jpegBuffer;
+    const x = Number(params.x);
+    const y = Number(params.y);
+    if (isNaN(x) || isNaN(y) || x < 0 || y < 0) {
+        return { success: false, error: `Invalid coordinates: (${params.x}, ${params.y}). Must be non-negative numbers.` };
+    }
+    const coordMap = params.coordMap ? String(params.coordMap) : lastCoordMap;
+    let point = { x, y };
+    if (coordMap) {
+        // Map screenshot-space coordinates to desktop-space (critical for Retina/HiDPI)
         try {
-            const sharp = (await import("sharp")).default;
-            jpegBuffer = await sharp(pngBuffer).jpeg({ quality: 80 }).toBuffer();
+            const parsed = usecomputer.parseCoordMapOrThrow(coordMap);
+            point = usecomputer.mapPointFromCoordMap({ point: { x, y }, coordMap: parsed });
         }
         catch {
-            // sharp not available — send PNG
-            jpegBuffer = pngBuffer;
+            // If mapping fails, fall back to raw coords
         }
-        return {
-            success: true,
-            screenshotBuffer: jpegBuffer,
-            screenshotMeta: {
-                width: result.imageWidth,
-                height: result.imageHeight,
-                format: "jpeg",
-                coordMap: result.coordMap,
-            },
-        };
-    }
-    finally {
-        try {
-            fs.unlinkSync(tmpPath);
-        }
-        catch { }
     }
-}
-async function doClick(params) {
-    const usecomputer = await getUC();
-    const x = Number(params.x);
-    const y = Number(params.y);
-    await usecomputer.click({ point: { x, y }, button: "left", count: 1 });
-    return { success: true, data: { action: "click", x, y } };
+    await usecomputer.click({ point, button: "left", count: 1 });
+    return { success: true, data: { action: "click", x, y, mappedX: point.x, mappedY: point.y, coordMap: coordMap || "none" } };
 }
 async function doType(params) {
     const usecomputer = await getUC();
@@ -108,6 +110,22 @@ async function doScroll(params) {
     await usecomputer.scroll({ direction, amount, at: null });
     return { success: true, data: { action: "scroll", direction, amount } };
 }
+async function doDrag(params) {
+    const usecomputer = await getUC();
+    const coordMap = params.coordMap ? String(params.coordMap) : lastCoordMap;
+    let from = { x: Number(params.fromX), y: Number(params.fromY) };
+    let to = { x: Number(params.toX), y: Number(params.toY) };
+    if (coordMap) {
+        try {
+            const parsed = usecomputer.parseCoordMapOrThrow(coordMap);
+            from = usecomputer.mapPointFromCoordMap({ point: from, coordMap: parsed });
+            to = usecomputer.mapPointFromCoordMap({ point: to, coordMap: parsed });
+        }
+        catch { }
+    }
+    await usecomputer.drag({ from, to, durationMs: null, button: null });
+    return { success: true, data: { action: "drag" } };
+}
 async function listWindows() {
     const usecomputer = await getUC();
     const windows = await usecomputer.windowList();

package/dist/index.js

@@ -10,12 +10,13 @@ import { loadConfig, saveConfig, getConfigPath } from "./config.js";
 import { checkPermissions, printPermissionGuide, runPermissionTest } from "./permissions.js";
 import { connect, disconnect } from "./connection.js";
 import { closeSupervisor, setMode } from "./supervisor.js";
+import chalk from "chalk";
 import readline from "readline";
 import os from "os";
 async function main() {
     console.log(`
-  InstaClaw Dispatch — Remote Computer Control
-  ─────────────────────────────────────────────
+  ${chalk.bold("InstaClaw Dispatch")} ${chalk.dim("— Remote Computer Control")}
+  ${chalk.dim("─────────────────────────────────────────────")}
   `);
     // 1. Check permissions (macOS only)
     if (os.platform() === "darwin") {
@@ -89,7 +90,21 @@ async function main() {
                 console.log(`\n  Dispatch mode: SUPERVISED`);
                 console.log(`  Screenshots auto-approved. Actions require [Enter] to confirm.`);
             }
-            console.log(`  Press Ctrl+C to disconnect.\n`);
+            console.log(`  Press 'a' to toggle autonomous mode. Press Ctrl+C to disconnect.\n`);
+            // Runtime mode switching via keypress
+            if (process.stdin.isTTY) {
+                process.stdin.setRawMode?.(false); // Ensure line mode for supervisor readline
+                process.stdin.on("data", (chunk) => {
+                    const key = chunk.toString().trim().toLowerCase();
+                    if (key === "a") {
+                        const newMode = config.mode === "supervised" ? "autonomous" : "supervised";
+                        config.mode = newMode;
+                        setMode(newMode);
+                        saveConfig(config);
+                        console.log(`\n  Mode switched to: ${newMode.toUpperCase()}\n`);
+                    }
+                });
+            }
         },
         onDisconnect: () => {
             // Will auto-reconnect
@@ -118,8 +133,29 @@ async function interactiveSetup(existing) {
         rl.question(`  ${prompt}`, (ans) => resolve(ans.trim() || def || ""));
     });
     console.log("  First-time setup:\n");
-    const token = await ask("Gateway token", existing?.gatewayToken);
-    const vm = await ask("VM address (IP or hostname)", existing?.vmAddress);
+    let token = await ask("Gateway token", existing?.gatewayToken);
+    let vm = await ask("VM address (IP or hostname)", existing?.vmAddress);
+    // Input validation: detect swapped fields
+    const isHexLong = (s) => /^[0-9a-f]{32,}$/i.test(s);
+    const isIPish = (s) => /^\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(s);
+    if (isHexLong(vm)) {
+        console.log(chalk.yellow("\n  That VM address looks like a gateway token (long hex string)."));
+        console.log(chalk.yellow("  The VM address should be an IP like 104.237.145.128"));
+        const swap = await ask("Did you swap the fields? Enter your VM IP now");
+        if (swap) {
+            token = vm;
+            vm = swap;
+        }
+    }
+    else if (isIPish(token)) {
+        console.log(chalk.yellow("\n  That gateway token looks like an IP address."));
+        console.log(chalk.yellow("  The gateway token should be a long hex string."));
+        const swap = await ask("Did you swap the fields? Enter your gateway token now");
+        if (swap) {
+            vm = token;
+            token = swap;
+        }
+    }
     const portStr = await ask("Port", String(existing?.port || 8765));
     rl.close();
     return {

package/dist/screenshot.d.ts

@@ -0,0 +1,15 @@
+export interface ScreenshotOptions {
+    format?: "jpeg" | "png";
+    quality?: number;
+}
+export interface ScreenshotCapture {
+    buffer: Buffer;
+    width: number;
+    height: number;
+    format: string;
+    coordMap: string;
+}
+/**
+ * Capture a screenshot and return it as a buffer with metadata.
+ */
+export declare function captureScreenshot(opts?: ScreenshotOptions): Promise<ScreenshotCapture>;

package/dist/screenshot.js

@@ -0,0 +1,47 @@
+/**
+ * Screenshot — captures screen via usecomputer, converts PNG→JPEG via sharp.
+ * Separated per PRD Section 5.1 package structure.
+ */
+import fs from "fs";
+import path from "path";
+/**
+ * Capture a screenshot and return it as a buffer with metadata.
+ */
+export async function captureScreenshot(opts = {}) {
+    const uc = await import("usecomputer");
+    const tmpPath = path.join("/tmp", `dispatch-ss-${Date.now()}.png`);
+    const format = opts.format || "jpeg";
+    const quality = opts.quality || 80;
+    try {
+        const result = await uc.screenshot({ path: tmpPath, display: null, window: null, region: null, annotate: null });
+        const pngBuffer = fs.readFileSync(tmpPath);
+        let outputBuffer;
+        if (format === "jpeg") {
+            try {
+                const sharp = (await import("sharp")).default;
+                outputBuffer = await sharp(pngBuffer).jpeg({ quality }).toBuffer();
+            }
+            catch {
+                // sharp not available — fall back to PNG
+                outputBuffer = pngBuffer;
+            }
+        }
+        else {
+            outputBuffer = pngBuffer;
+        }
+        return {
+            buffer: outputBuffer,
+            width: result.imageWidth,
+            height: result.imageHeight,
+            format,
+            coordMap: result.coordMap,
+        };
+    }
+    finally {
+        try {
+            fs.unlinkSync(tmpPath);
+        }
+        catch { }
+    }
+}
+//# sourceMappingURL=screenshot.js.map

package/dist/supervisor.js

@@ -9,15 +9,22 @@ import readline from "readline";
 const AUTO_APPROVE_TYPES = new Set(["screenshot", "windows", "status"]);
 // Patterns that indicate dangerous actions — always require confirmation even in autonomous mode
 const DANGEROUS_TEXT_PATTERNS = [
+    // Authentication
     /password/i, /passwd/i, /secret/i, /credential/i,
-    /delete/i, /remove/i, /destroy/i, /format/i, /erase/i,
+    /\b2fa\b/i, /\bmfa\b/i, /authenticat/i, /verification.?code/i, /one.?time.?pass/i,
+    // Destructive
+    /delete/i, /remove/i, /destroy/i, /format/i, /erase/i, /empty.?trash/i,
+    // Financial
     /purchase/i, /submit.*order/i, /confirm.*payment/i, /buy\s/i,
     /transfer.*fund/i, /send.*money/i, /withdraw/i,
-    /sudo\s/i, /rm\s+-rf/i, /shutdown/i, /reboot/i,
+    // System
+    /sudo\s/i, /rm\s+-rf/i, /shutdown/i, /reboot/i, /restart/i,
+    /\binstall\b/i, /\bapt\b/i, /\bbrew\b/i, /\bnpm\s+i/i, /pip\s+install/i,
 ];
 const DANGEROUS_KEY_COMBOS = new Set([
     "cmd+delete", "cmd+shift+delete", "ctrl+delete",
     "cmd+q", "alt+f4",
+    "cmd+shift+backspace", // Empty Trash on macOS
 ]);
 let mode = "supervised";
 const isTTY = process.stdin.isTTY ?? false;

package/dist/types.d.ts

@@ -31,4 +31,10 @@ export interface DispatchConfig {
     mode: "supervised" | "autonomous";
     /** TLS cert fingerprint for TOFU (trust on first use) */
     certFingerprint?: string;
+    /** Screenshot format: "jpeg" or "png" */
+    screenshotFormat?: "jpeg" | "png";
+    /** Screenshot quality (1-100, JPEG only) */
+    screenshotQuality?: number;
+    /** Max actions per minute before rate limiting */
+    maxActionsPerMinute?: number;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@instaclaw/dispatch",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Let your InstaClaw AI agent control your computer — screenshots, clicks, typing, and more via a secure WebSocket relay",
   "bin": {
     "instaclaw-dispatch": "./dist/index.js"
@@ -30,13 +30,15 @@
   },
   "homepage": "https://instaclaw.io",
   "dependencies": {
+    "chalk": "^5.6.2",
+    "inquirer": "^9.3.8",
+    "sharp": "^0.33.0",
     "usecomputer": "^0.1.4",
-    "ws": "^8.18.0",
-    "sharp": "^0.33.0"
+    "ws": "^8.18.0"
   },
   "devDependencies": {
-    "@types/ws": "^8.5.0",
     "@types/node": "^22.0.0",
+    "@types/ws": "^8.5.0",
     "typescript": "^5.7.0"
   },
   "engines": {