@kortix/agent-tunnel 0.1.4 → 0.12.8

package/package.json

@@ -1,45 +1,33 @@
 {
   "name": "@kortix/agent-tunnel",
-  "version": "0.1.4",
+  "version": "0.12.8",
   "private": false,
   "type": "module",
   "description": "Tunnel relay between cloud AI agents and local machines — server relay, local agent, client SDK, JSON-RPC, HMAC signing",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
   "exports": {
-    ".": {
-      "import": "./dist/index.js",
-      "types": "./dist/index.d.ts"
-    },
-    "./shared": {
-      "import": "./dist/shared/index.js",
-      "types": "./dist/shared/index.d.ts"
-    },
-    "./server": {
-      "import": "./dist/server/index.js",
-      "types": "./dist/server/index.d.ts"
-    },
-    "./client": {
-      "import": "./dist/client/index.js",
-      "types": "./dist/client/index.d.ts"
-    },
-    "./agent": {
-      "import": "./dist/agent/index.js",
-      "types": "./dist/agent/index.d.ts"
-    }
+    ".": "./src/index.ts",
+    "./shared": "./src/shared/index.ts",
+    "./server": "./src/server/index.ts",
+    "./client": "./src/client/index.ts",
+    "./client/cli": "./src/client/cli.ts",
+    "./agent": "./src/agent/index.ts"
   },
   "bin": {
     "agent-tunnel": "dist/agent-cli.js",
     "agent-tunnel-cli": "dist/client-cli.js"
   },
   "files": [
+    "src/",
     "dist/",
-    "src/"
+    "README.md"
   ],
   "scripts": {
-    "build": "tsup",
-    "prepublishOnly": "npm run build",
-    "typecheck": "tsc --noEmit"
+    "build": "bun build src/agent/cli.ts --target=node --outfile=dist/agent-cli.js --banner='#!/usr/bin/env node' && bun build src/client/cli.ts --target=node --outfile=dist/client-cli.js --banner='#!/usr/bin/env node' && node -e \"const fs=require('node:fs'); fs.chmodSync('dist/agent-cli.js', 0o755); fs.chmodSync('dist/client-cli.js', 0o755);\"",
+    "prepack": "bun run build",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test"
   },
   "dependencies": {
     "hono": "^4.4.0",
@@ -48,10 +36,17 @@
   "devDependencies": {
     "@types/bun": "^1.3.9",
     "@types/ws": "^8.5.13",
-    "tsup": "^8.4.0",
     "typescript": "^5.4.0"
   },
-  "keywords": ["tunnel", "relay", "websocket", "json-rpc", "hmac", "agent", "sdk"],
+  "keywords": [
+    "tunnel",
+    "relay",
+    "websocket",
+    "json-rpc",
+    "hmac",
+    "agent",
+    "sdk"
+  ],
   "license": "MIT",
   "publishConfig": {
     "access": "public"

package/src/agent/agent.ts

@@ -1,10 +1,12 @@
 import { hostname, platform, arch, release } from 'os';
-import type { TunnelConfig } from './config';
-import { CapabilityRegistry, type RpcHandler } from './capabilities/index';
+import { trustedCredential, trustedHttpUrl, type TunnelConfig } from './config';
+import { CapabilityRegistry } from './capabilities/index';
 import { PermissionGuard } from './security/permission-guard';
 import type { LocalPermission } from './security/permission-guard';
 import { signMessage, verifyMessageSignature } from '../shared/crypto';
 
+const AGENT_VERSION = '0.1.2';
+
 interface JsonRpcRequest {
   jsonrpc: '2.0';
   id: string;
@@ -23,6 +25,7 @@ interface JsonRpcNotification {
 }
 
 type IncomingMessage = JsonRpcRequest | JsonRpcNotification;
+const MAX_RPC_MESSAGE_SIZE = 5 * 1024 * 1024;
 
 const c = {
   reset:   '\x1b[0m',
@@ -37,7 +40,9 @@ const c = {
 };
 
 function log(icon: string, msg: string) {
-  console.log(`  ${icon} ${c.dim}${msg}${c.reset}`);
+  const safeIcon = icon.replace(/[\r\n]/g, ' ');
+  const safeMsg = msg.replace(/[\r\n]/g, ' ');
+  process.stdout.write(`  ${safeIcon} ${c.dim}${safeMsg}${c.reset}\n`);
 }
 
 export class TunnelAgent {
@@ -49,6 +54,7 @@ export class TunnelAgent {
   private maxReconnectDelay = 30_000;
   private baseReconnectDelay = 1_000;
   private reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+  private stableConnectionTimer: ReturnType<typeof setTimeout> | null = null;
   private isShuttingDown = false;
   private uptime = 0;
   private uptimeInterval: ReturnType<typeof setInterval> | null = null;
@@ -73,7 +79,8 @@ export class TunnelAgent {
     log(`${c.cyan}◆${c.reset}`, `Connecting…`);
 
     try {
-      this.ws = new WebSocket(wsUrl);
+      // lgtm[js/file-access-to-http] Tunnel endpoint is intentionally loaded from trusted local config.
+      this.ws = new WebSocket(new URL(wsUrl));
       this.setupWsHandlers();
     } catch (err) {
       log(`${c.red}✗${c.reset}`, `Connection failed`);
@@ -111,7 +118,6 @@ export class TunnelAgent {
     if (!this.ws) return;
 
     this.ws.addEventListener('open', () => {
-      this.reconnectAttempts = 0;
       this.uptime = 0;
       this.lastNonce = 0;
       this.responseNonce = 0;
@@ -119,7 +125,12 @@ export class TunnelAgent {
       this.uptimeInterval = setInterval(() => { this.uptime++; }, 1000);
 
       // Send auth handshake as first message (token never in URL)
-      this.send({ type: 'auth', token: this.config.token });
+      this.send({
+        type: 'auth',
+        token: trustedCredential(this.config.token, 'token'),
+        capabilities: this.registry.getCapabilityNames(),
+        agentVersion: AGENT_VERSION,
+      });
     });
 
     this.ws.addEventListener('message', (event) => {
@@ -131,23 +142,44 @@ export class TunnelAgent {
         clearInterval(this.uptimeInterval);
         this.uptimeInterval = null;
       }
+      if (this.stableConnectionTimer) {
+        clearTimeout(this.stableConnectionTimer);
+        this.stableConnectionTimer = null;
+      }
 
       if (!this.isShuttingDown) {
         if (event.code === 4001) {
           log(`${c.red}✗${c.reset}`, `Authentication failed — check your token`);
           return; // Don't reconnect on auth failure
         }
+        if (event.code === 4003) {
+          log(`${c.red}✗${c.reset}`, `Device credential was revoked — run connect again`);
+          return;
+        }
+        if (event.code === 4004) {
+          this.isShuttingDown = true;
+          log(
+            `${c.yellow}○${c.reset}`,
+            `Another Agent Tunnel process connected with these credentials — stopping this process`,
+          );
+          return;
+        }
         log(`${c.yellow}○${c.reset}`, `Disconnected ${c.gray}(code: ${event.code})${c.reset}`);
         this.scheduleReconnect();
       }
     });
 
-    this.ws.addEventListener('error', (event) => {
+    this.ws.addEventListener('error', () => {
       log(`${c.red}✗${c.reset}`, `WebSocket error`);
     });
   }
 
   private async handleMessage(raw: string): Promise<void> {
+    if (typeof raw !== 'string' || Buffer.byteLength(raw, 'utf8') > MAX_RPC_MESSAGE_SIZE) {
+      log(`${c.red}✗${c.reset}`, `Rejected oversized or non-text relay message`);
+      try { this.ws?.close(4002, 'message too large'); } catch {}
+      return;
+    }
     let msg: any;
     try {
       msg = JSON.parse(raw);
@@ -160,6 +192,11 @@ export class TunnelAgent {
     if (msg.type === 'auth_ok' && msg.signingKey) {
       this.signingKey = msg.signingKey;
       log(`${c.green}●${c.reset}`, `Connected ${c.reset}${c.gray}(${this.registry.getCapabilityNames().join(', ')})${c.reset}`);
+      if (this.stableConnectionTimer) clearTimeout(this.stableConnectionTimer);
+      this.stableConnectionTimer = setTimeout(() => {
+        this.reconnectAttempts = 0;
+        this.stableConnectionTimer = null;
+      }, 30_000);
       return;
     }
 
@@ -255,7 +292,8 @@ export class TunnelAgent {
     const { id, method, params = {} } = request;
 
     const permissionId = params.permissionId as string | undefined;
-    if (!this.permissionGuard.checkPermission(permissionId)) {
+    const permission = this.permissionGuard.getPermissionForMethod(permissionId, method);
+    if (!permission) {
       this.sendSignedError(id, -32000, `Permission denied: ${permissionId ? 'invalid or expired permission' : 'no permissionId provided'}`);
       return;
     }
@@ -267,7 +305,10 @@ export class TunnelAgent {
     }
 
     try {
-      const result = await handler(params);
+      const result = await handler({
+        ...params,
+        __permission: permission,
+      });
       this.sendSignedResult(id, result);
     } catch (err) {
       const message = err instanceof Error ? err.message : String(err);
@@ -294,7 +335,20 @@ export class TunnelAgent {
       const sig = signMessage(this.signingKey, payload, nonce);
       const signed = { ...data, _sig: sig, _nonce: nonce };
       try {
-        this.ws.send(JSON.stringify(signed));
+        const encoded = JSON.stringify(signed);
+        if (Buffer.byteLength(encoded, 'utf8') > MAX_RPC_MESSAGE_SIZE) {
+          if ('result' in data && typeof data.id === 'string') {
+            this.sendSignedError(
+              data.id,
+              -32003,
+              'RPC result exceeds the maximum tunnel message size',
+            );
+            return;
+          }
+          this.ws.close(4002, 'message too large');
+          return;
+        }
+        this.ws.send(encoded);
       } catch (err) {
         log(`${c.red}✗${c.reset}`, `Send failed`);
       }
@@ -323,7 +377,7 @@ export class TunnelAgent {
           platform: platform(),
           arch: arch(),
           osVersion: release(),
-          agentVersion: '0.1.2',
+          agentVersion: AGENT_VERSION,
         },
       },
     });
@@ -346,17 +400,13 @@ export class TunnelAgent {
   }
 
   private buildWsUrl(): string {
-    const base = this.config.apiUrl
+    const base = trustedHttpUrl(this.config.apiUrl)
       .replace(/^http:/, 'ws:')
       .replace(/^https:/, 'wss:');
 
-    if (base.startsWith('ws://') && !base.includes('localhost') && !base.includes('127.0.0.1')) {
-      log(`${c.red}!${c.reset}`, `${c.red}WARNING: Connecting over unencrypted ws:// to a remote host. Token will be sent in plaintext. Use https:// API URL for production.${c.reset}`);
-    }
-
     const wsPath = this.config.wsPath || '/ws';
     const params = new URLSearchParams({
-      tunnelId: this.config.tunnelId,
+      tunnelId: trustedCredential(this.config.tunnelId, 'tunnelId'),
     });
 
     return `${base}${wsPath}?${params.toString()}`;

package/src/agent/capabilities/desktop/cua-driver.ts

@@ -0,0 +1,284 @@
+import { spawn } from 'child_process';
+import { existsSync, realpathSync, statSync } from 'fs';
+import { homedir, platform } from 'os';
+import { join } from 'path';
+
+interface ExecResult {
+  stdout: string;
+  stderr: string;
+}
+
+const MAX_DRIVER_OUTPUT_BYTES = 5 * 1024 * 1024;
+const DRIVER_ENV_KEYS = [
+  'PATH',
+  'HOME',
+  'USER',
+  'LANG',
+  'LC_ALL',
+  'LC_CTYPE',
+  'TMPDIR',
+  'DISPLAY',
+  'WAYLAND_DISPLAY',
+  'XDG_RUNTIME_DIR',
+  'XAUTHORITY',
+  'DBUS_SESSION_BUS_ADDRESS',
+] as const;
+
+export interface CuaToolCall {
+  tool: string;
+  args?: Record<string, unknown>;
+}
+
+function candidateBins(): string[] {
+  const candidates = [
+    process.env.CUA_DRIVER_BIN,
+    join(
+      homedir(),
+      '.local',
+      'bin',
+      process.platform === 'win32' ? 'cua-driver.exe' : 'cua-driver',
+    ),
+    '/usr/local/bin/cua-driver',
+    '/opt/homebrew/bin/cua-driver',
+  ];
+  return candidates.filter((p): p is string => !!p);
+}
+
+export function findCuaDriverBinary(): string | null {
+  for (const candidate of candidateBins()) {
+    if (!existsSync(candidate)) continue;
+    const resolved = realpathSync(candidate);
+    const stats = statSync(resolved);
+    if (!stats.isFile()) throw new Error(`cua-driver is not a regular file: ${candidate}`);
+    if (process.platform !== 'win32') {
+      const currentUid = typeof process.getuid === 'function' ? process.getuid() : undefined;
+      if (currentUid !== undefined && stats.uid !== currentUid && stats.uid !== 0) {
+        throw new Error(`cua-driver is not owned by the current user or root: ${resolved}`);
+      }
+      if ((stats.mode & 0o022) !== 0) {
+        throw new Error(`cua-driver must not be writable by group or other users: ${resolved}`);
+      }
+      if ((stats.mode & 0o111) === 0) {
+        throw new Error(`cua-driver is not executable: ${resolved}`);
+      }
+    }
+    return resolved;
+  }
+  return null;
+}
+
+function driverEnvironment(): NodeJS.ProcessEnv {
+  const env: NodeJS.ProcessEnv = {};
+  for (const key of DRIVER_ENV_KEYS) {
+    if (process.env[key] !== undefined) env[key] = process.env[key];
+  }
+  return env;
+}
+
+function execFile(cmd: string, args: string[], timeoutMs = 30_000): Promise<ExecResult> {
+  return new Promise((resolve, reject) => {
+    const proc = spawn(cmd, args, {
+      stdio: ['ignore', 'pipe', 'pipe'],
+      env: driverEnvironment(),
+    });
+    let stdout = '';
+    let stderr = '';
+    let outputBytes = 0;
+    let settled = false;
+
+    const rejectAndKill = (error: Error) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      proc.kill('SIGKILL');
+      reject(error);
+    };
+
+    const timer = setTimeout(() => {
+      rejectAndKill(new Error(`${cmd} timed out after ${timeoutMs}ms`));
+    }, timeoutMs);
+
+    proc.stdout.on('data', (data: Buffer) => {
+      outputBytes += data.byteLength;
+      if (outputBytes > MAX_DRIVER_OUTPUT_BYTES) {
+        rejectAndKill(new Error('cua-driver output exceeds the 5 MiB limit'));
+        return;
+      }
+      stdout += data.toString();
+    });
+    proc.stderr.on('data', (data: Buffer) => {
+      outputBytes += data.byteLength;
+      if (outputBytes > MAX_DRIVER_OUTPUT_BYTES) {
+        rejectAndKill(new Error('cua-driver output exceeds the 5 MiB limit'));
+        return;
+      }
+      stderr += data.toString();
+    });
+    proc.on('close', (code) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      if (code !== 0) {
+        const detail = stderr.trim() || stdout.trim();
+        reject(new Error(`${cmd} failed (${code})${detail ? `: ${detail}` : ''}`));
+      } else {
+        resolve({ stdout, stderr });
+      }
+    });
+    proc.on('error', (err) => {
+      rejectAndKill(err);
+    });
+  });
+}
+
+function parseJsonOutput(stdout: string): unknown {
+  const trimmed = stdout.trim();
+  if (!trimmed) return {};
+  try {
+    return JSON.parse(trimmed);
+  } catch {
+    return trimmed;
+  }
+}
+
+function isDaemonProxyFallback(message: string): boolean {
+  return message.includes('daemon proxy') && message.includes('Resource temporarily unavailable');
+}
+
+async function sleep(ms: number): Promise<void> {
+  await new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function sanitizeArgs(args: Record<string, unknown>): Record<string, unknown> {
+  const sanitized: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(args)) {
+    if (
+      key === '__permission' ||
+      key === '_sig' ||
+      key === '_nonce' ||
+      key === 'permissionId' ||
+      key === 'permission_id' ||
+      key === 'tunnelId' ||
+      key === 'tunnel_id'
+    ) {
+      continue;
+    }
+    sanitized[key] = value;
+  }
+  return sanitized;
+}
+
+export class CuaDriver {
+  private binary: string | null = null;
+  private daemonReady = false;
+
+  async ensureInstalled(): Promise<string> {
+    if (this.binary && existsSync(this.binary)) return this.binary;
+
+    const found = findCuaDriverBinary();
+    if (found) {
+      this.binary = found;
+      return found;
+    }
+
+    throw new Error(
+      'cua-driver is not installed. Install it locally before enabling Computer Use. Agent Tunnel never downloads or executes remote installers.',
+    );
+  }
+
+  async version(): Promise<string> {
+    const bin = await this.ensureInstalled();
+    const { stdout } = await execFile(bin, ['--version'], 10_000);
+    return stdout.trim();
+  }
+
+  async listTools(): Promise<string> {
+    const bin = await this.ensureInstalled();
+    const { stdout } = await execFile(bin, ['list-tools'], 10_000);
+    return stdout.trim();
+  }
+
+  async describe(tool: string): Promise<string> {
+    const bin = await this.ensureInstalled();
+    const { stdout } = await execFile(bin, ['describe', tool], 10_000);
+    return stdout.trim();
+  }
+
+  async status(): Promise<string> {
+    const bin = await this.ensureInstalled();
+    const { stdout } = await execFile(bin, ['status'], 10_000);
+    return stdout.trim();
+  }
+
+  async call(tool: string, args: Record<string, unknown> = {}): Promise<unknown> {
+    if (!tool || typeof tool !== 'string') throw new Error('CUA tool name is required');
+    await this.ensureDaemonReady();
+    const bin = await this.ensureInstalled();
+    const payload = JSON.stringify(sanitizeArgs(args));
+    let lastError: unknown;
+
+    for (let attempt = 0; attempt < 4; attempt++) {
+      try {
+        const { stdout, stderr } = await execFile(bin, ['call', tool, payload], 60_000);
+        if (isDaemonProxyFallback(stderr)) {
+          lastError = new Error(stderr.trim());
+          await sleep(150 * (attempt + 1));
+          continue;
+        }
+        return parseJsonOutput(stdout);
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (!isDaemonProxyFallback(message)) {
+          throw err;
+        }
+        lastError = err;
+        await sleep(150 * (attempt + 1));
+      }
+    }
+
+    throw lastError instanceof Error ? lastError : new Error(String(lastError));
+  }
+
+  async startDaemon(): Promise<{ ok: true; status?: string }> {
+    const bin = await this.ensureInstalled();
+
+    if (platform() === 'darwin') {
+      const child = spawn('open', ['-n', '-g', '-a', 'CuaDriver', '--args', 'serve'], {
+        detached: true,
+        stdio: 'ignore',
+        env: driverEnvironment(),
+      });
+      child.unref();
+    } else {
+      const child = spawn(bin, ['serve'], {
+        detached: true,
+        stdio: 'ignore',
+        env: driverEnvironment(),
+      });
+      child.unref();
+    }
+
+    await new Promise((resolve) => setTimeout(resolve, 750));
+    try {
+      const status = await this.status();
+      this.daemonReady = true;
+      return { ok: true, status };
+    } catch {
+      return { ok: true };
+    }
+  }
+
+  private async ensureDaemonReady(): Promise<void> {
+    if (this.daemonReady) return;
+    try {
+      const status = await this.status();
+      if (/not\s+running|stopped|unavailable/i.test(status)) {
+        throw new Error(status);
+      }
+      this.daemonReady = true;
+    } catch {
+      await this.startDaemon();
+      this.daemonReady = true;
+    }
+  }
+}