@kortix/agent-tunnel 0.1.0

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@kortix/agent-tunnel",
+  "version": "0.1.0",
+  "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": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./shared": "./src/shared/index.ts",
+    "./server": "./src/server/index.ts",
+    "./client": "./src/client/index.ts",
+    "./agent": "./src/agent/index.ts"
+  },
+  "bin": {
+    "agent-tunnel": "src/agent/cli.ts"
+  },
+  "files": [
+    "src/"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "hono": "^4.4.0"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.9",
+    "typescript": "^5.4.0"
+  },
+  "keywords": ["tunnel", "relay", "websocket", "json-rpc", "hmac", "agent", "sdk"],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/agent/agent.ts

@@ -0,0 +1,331 @@
+import { hostname, platform, arch, release } from 'os';
+import type { TunnelConfig } from './config';
+import { CapabilityRegistry, type RpcHandler } from './capabilities/index';
+import { PermissionGuard } from './security/permission-guard';
+import type { LocalPermission } from './security/permission-guard';
+import { deriveSigningKey, verifyMessageSignature } from '../shared/crypto';
+
+interface JsonRpcRequest {
+  jsonrpc: '2.0';
+  id: string;
+  method: string;
+  params?: Record<string, unknown>;
+  _sig?: string;
+  _nonce?: number;
+}
+
+interface JsonRpcNotification {
+  jsonrpc: '2.0';
+  method: string;
+  params?: Record<string, unknown>;
+  _sig?: string;
+  _nonce?: number;
+}
+
+type IncomingMessage = JsonRpcRequest | JsonRpcNotification;
+
+const c = {
+  reset:   '\x1b[0m',
+  bold:    '\x1b[1m',
+  dim:     '\x1b[2m',
+  cyan:    '\x1b[36m',
+  green:   '\x1b[32m',
+  yellow:  '\x1b[33m',
+  red:     '\x1b[31m',
+  white:   '\x1b[97m',
+  gray:    '\x1b[90m',
+};
+
+function log(icon: string, msg: string) {
+  console.log(`  ${icon} ${c.dim}${msg}${c.reset}`);
+}
+
+export class TunnelAgent {
+  private ws: WebSocket | null = null;
+  private registry: CapabilityRegistry;
+  private permissionGuard: PermissionGuard;
+  private config: TunnelConfig;
+  private reconnectAttempts = 0;
+  private maxReconnectDelay = 30_000;
+  private baseReconnectDelay = 1_000;
+  private reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+  private isShuttingDown = false;
+  private uptime = 0;
+  private uptimeInterval: ReturnType<typeof setInterval> | null = null;
+
+  // HMAC signature verification
+  private signingKey: string;
+  private lastNonce = 0;
+
+  constructor(config: TunnelConfig, registry: CapabilityRegistry) {
+    this.config = config;
+    this.registry = registry;
+    this.permissionGuard = new PermissionGuard();
+    this.signingKey = deriveSigningKey(config.token);
+  }
+
+  connect(): void {
+    if (this.ws) {
+      this.ws.close();
+    }
+
+    const wsUrl = this.buildWsUrl();
+    log(`${c.cyan}◆${c.reset}`, `Connecting…`);
+
+    try {
+      this.ws = new WebSocket(wsUrl);
+      this.setupWsHandlers();
+    } catch (err) {
+      log(`${c.red}✗${c.reset}`, `Connection failed`);
+      this.scheduleReconnect();
+    }
+  }
+
+  disconnect(): void {
+    this.isShuttingDown = true;
+
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+
+    if (this.uptimeInterval) {
+      clearInterval(this.uptimeInterval);
+      this.uptimeInterval = null;
+    }
+
+    if (this.ws) {
+      try { this.ws.close(1000, 'client shutdown'); } catch {}
+      this.ws = null;
+    }
+
+    this.permissionGuard.clear();
+    log(`${c.gray}○${c.reset}`, `Disconnected`);
+  }
+
+  isConnected(): boolean {
+    return this.ws?.readyState === WebSocket.OPEN;
+  }
+
+  private setupWsHandlers(): void {
+    if (!this.ws) return;
+
+    this.ws.addEventListener('open', () => {
+      this.reconnectAttempts = 0;
+      this.uptime = 0;
+      this.lastNonce = 0; // Reset nonce on each new connection
+      this.uptimeInterval = setInterval(() => { this.uptime++; }, 1000);
+
+      log(`${c.green}●${c.reset}`, `Connected ${c.reset}${c.gray}(${this.registry.getCapabilityNames().join(', ')})${c.reset}`);
+    });
+
+    this.ws.addEventListener('message', (event) => {
+      this.handleMessage(event.data as string);
+    });
+
+    this.ws.addEventListener('close', (event) => {
+      if (this.uptimeInterval) {
+        clearInterval(this.uptimeInterval);
+        this.uptimeInterval = null;
+      }
+
+      if (!this.isShuttingDown) {
+        log(`${c.yellow}○${c.reset}`, `Disconnected ${c.gray}(code: ${event.code})${c.reset}`);
+        this.scheduleReconnect();
+      }
+    });
+
+    this.ws.addEventListener('error', (event) => {
+      log(`${c.red}✗${c.reset}`, `WebSocket error`);
+    });
+  }
+
+  private async handleMessage(raw: string): Promise<void> {
+    let msg: IncomingMessage;
+    try {
+      msg = JSON.parse(raw);
+    } catch {
+      log(`${c.yellow}!${c.reset}`, `Received invalid JSON`);
+      return;
+    }
+
+    // ── Heartbeat ping — no signature required ──────────────────────
+    if ('method' in msg && msg.method === 'tunnel.ping') {
+      this.sendPong();
+      return;
+    }
+
+    // ── Verify HMAC signature on all other messages ─────────────────
+    if (!this.verifyIncomingSignature(msg, raw)) {
+      if ('id' in msg && msg.id) {
+        this.sendError(msg.id, -32000, 'Invalid message signature');
+      }
+      return;
+    }
+
+    // ── Permission sync notification ────────────────────────────────
+    if ('method' in msg && msg.method === 'tunnel.permissions.sync') {
+      const permissions = (msg.params?.permissions || []) as LocalPermission[];
+      this.permissionGuard.syncPermissions(permissions);
+      log(`${c.green}●${c.reset}`, `Synced ${c.reset}${c.white}${permissions.length}${c.dim} permissions`);
+      return;
+    }
+
+    // ── Permission granted notification ────────────────────────────
+    if ('method' in msg && msg.method === 'tunnel.permission.granted') {
+      const p = msg.params as LocalPermission | undefined;
+      if (p?.permissionId) {
+        this.permissionGuard.addPermission(p);
+        log(`${c.green}+${c.reset}`, `Permission granted: ${p.capability} (${p.permissionId.slice(0, 12)}…)`);
+      }
+      return;
+    }
+
+    // ── Permission revocation notification ──────────────────────────
+    if ('method' in msg && msg.method === 'tunnel.permission.revoked') {
+      const permissionId = msg.params?.permissionId as string;
+      if (permissionId) {
+        this.permissionGuard.revokePermission(permissionId);
+        log(`${c.yellow}○${c.reset}`, `Permission revoked: ${permissionId.slice(0, 12)}…`);
+      }
+      return;
+    }
+
+    // ── Token rotation notification ─────────────────────────────────
+    if ('method' in msg && msg.method === 'tunnel.token.rotated') {
+      log(`${c.yellow}!${c.reset}`, `Token rotated — reconnecting with new token`);
+      // The server will close the WS shortly; the reconnect logic handles the rest.
+      // Caller must update config.token before reconnect succeeds.
+      return;
+    }
+
+    // ── RPC request dispatch ────────────────────────────────────────
+    if ('id' in msg && msg.id) {
+      await this.handleRpcRequest(msg as JsonRpcRequest);
+      return;
+    }
+  }
+
+  /**
+   * Verify HMAC signature on incoming messages (excluding pings).
+   * Returns true if valid, false if signature check fails.
+   */
+  private verifyIncomingSignature(msg: IncomingMessage, _raw: string): boolean {
+    const sig = (msg as any)._sig as string | undefined;
+    const nonce = (msg as any)._nonce as number | undefined;
+
+    if (sig === undefined || nonce === undefined) {
+      log(`${c.yellow}!${c.reset}`, `Message missing signature fields`);
+      return false;
+    }
+
+    // Replay protection: nonce must be strictly increasing
+    if (nonce <= this.lastNonce) {
+      log(`${c.red}✗${c.reset}`, `Replay detected: nonce ${nonce} <= ${this.lastNonce}`);
+      return false;
+    }
+
+    // Build the payload to verify (message without _sig and _nonce)
+    const { _sig, _nonce, ...payloadObj } = msg as any;
+    const payload = JSON.stringify(payloadObj);
+
+    if (!verifyMessageSignature(this.signingKey, payload, nonce, sig)) {
+      log(`${c.red}✗${c.reset}`, `Invalid HMAC signature`);
+      return false;
+    }
+
+    this.lastNonce = nonce;
+    return true;
+  }
+
+  private async handleRpcRequest(request: JsonRpcRequest): Promise<void> {
+    const { id, method, params = {} } = request;
+
+    // ── Permission enforcement (defense-in-depth) ───────────────────
+    const permissionId = params.permissionId as string | undefined;
+    if (!this.permissionGuard.checkPermission(permissionId)) {
+      this.sendError(id, -32000, `Permission denied: ${permissionId ? 'invalid or expired permission' : 'no permissionId provided'}`);
+      return;
+    }
+
+    const handler = this.registry.getHandler(method);
+    if (!handler) {
+      this.sendError(id, -32001, `Capability not registered for method: ${method}`);
+      return;
+    }
+
+    try {
+      const result = await handler(params);
+      this.sendResult(id, result);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      this.sendError(id, -32003, message);
+    }
+  }
+
+  private sendResult(id: string, result: unknown): void {
+    this.send({ jsonrpc: '2.0', id, result });
+  }
+
+  private sendError(id: string, code: number, message: string): void {
+    this.send({ jsonrpc: '2.0', id, error: { code, message } });
+  }
+
+  private sendPong(): void {
+    this.send({
+      jsonrpc: '2.0',
+      method: 'tunnel.pong',
+      params: {
+        uptime: this.uptime,
+        capabilities: this.registry.getCapabilityNames(),
+        machineInfo: {
+          hostname: hostname(),
+          platform: platform(),
+          arch: arch(),
+          osVersion: release(),
+          agentVersion: '0.1.0',
+        },
+      },
+    });
+  }
+
+  private send(data: unknown): void {
+    if (this.ws?.readyState === WebSocket.OPEN) {
+      try {
+        this.ws.send(JSON.stringify(data));
+      } catch (err) {
+        log(`${c.red}✗${c.reset}`, `Send failed`);
+      }
+    }
+  }
+
+  private scheduleReconnect(): void {
+    if (this.isShuttingDown) return;
+
+    this.reconnectAttempts++;
+    const delay = Math.min(
+      this.baseReconnectDelay * Math.pow(2, this.reconnectAttempts - 1),
+      this.maxReconnectDelay,
+    );
+
+    log(`${c.cyan}◆${c.reset}`, `Reconnecting in ${c.reset}${c.white}${(delay / 1000).toFixed(1)}s${c.dim} (attempt ${this.reconnectAttempts})`);
+
+    this.reconnectTimer = setTimeout(() => {
+      this.connect();
+    }, delay);
+  }
+
+  private buildWsUrl(): string {
+    const base = this.config.apiUrl
+      .replace(/^http:/, 'ws:')
+      .replace(/^https:/, 'wss:');
+
+    const wsPath = this.config.wsPath || '/ws';
+    const params = new URLSearchParams({
+      token: this.config.token,
+      tunnelId: this.config.tunnelId,
+    });
+
+    return `${base}${wsPath}?${params.toString()}`;
+  }
+}

package/src/agent/capabilities/desktop/atspi-helper.ts

@@ -0,0 +1,345 @@
+import { spawn } from 'child_process';
+import { existsSync, mkdirSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+
+const HELPER_VERSION = 'v1';
+const BIN_DIR = join(homedir(), '.kortix-tunnel', 'bin');
+const HELPER_PATH = join(BIN_DIR, `atspi-helper-${HELPER_VERSION}.py`);
+
+const PYTHON_SOURCE = `#!/usr/bin/env python3
+"""AT-SPI2 accessibility helper for Linux."""
+import json
+import sys
+
+try:
+    import gi
+    gi.require_version('Atspi', '2.0')
+    from gi.repository import Atspi
+except ImportError:
+    print(json.dumps({"ok": False, "error": "python3-gi and gir1.2-atspi-2.0 required. Install: sudo apt install python3-gi gir1.2-atspi-2.0"}))
+    sys.exit(0)
+
+element_count = 0
+
+def get_role_name(accessible):
+    try:
+        return Atspi.Accessible.get_role_name(accessible)
+    except:
+        return ""
+
+def get_name(accessible):
+    try:
+        return Atspi.Accessible.get_name(accessible) or ""
+    except:
+        return ""
+
+def get_description(accessible):
+    try:
+        return Atspi.Accessible.get_description(accessible) or ""
+    except:
+        return ""
+
+def get_bounds(accessible):
+    try:
+        comp = accessible.get_component_iface()
+        if comp:
+            rect = comp.get_extents(Atspi.CoordType.SCREEN)
+            return {"x": rect.x, "y": rect.y, "width": rect.width, "height": rect.height}
+    except:
+        pass
+    return {"x": 0, "y": 0, "width": 0, "height": 0}
+
+def get_value(accessible):
+    try:
+        val = accessible.get_value_iface()
+        if val:
+            return str(val.get_current_value())
+    except:
+        pass
+    return ""
+
+def get_actions(accessible):
+    actions = []
+    try:
+        action_iface = accessible.get_action_iface()
+        if action_iface:
+            for i in range(action_iface.get_n_actions()):
+                name = action_iface.get_action_name(i)
+                if name:
+                    actions.append(name)
+    except:
+        pass
+    return actions
+
+def get_states(accessible):
+    enabled = True
+    focused = False
+    try:
+        state_set = accessible.get_state_set()
+        enabled = state_set.contains(Atspi.StateType.ENABLED) or state_set.contains(Atspi.StateType.SENSITIVE)
+        focused = state_set.contains(Atspi.StateType.FOCUSED)
+    except:
+        pass
+    return enabled, focused
+
+def walk_tree(accessible, depth, max_depth, roles, path_prefix):
+    global element_count
+    if accessible is None or depth > max_depth:
+        return None
+    element_count += 1
+
+    role = get_role_name(accessible)
+    name = get_name(accessible)
+    value = get_value(accessible)
+    desc = get_description(accessible)
+    bounds = get_bounds(accessible)
+    actions = get_actions(accessible)
+    enabled, focused = get_states(accessible)
+
+    children = []
+    if depth < max_depth:
+        try:
+            count = accessible.get_child_count()
+            for i in range(count):
+                child = accessible.get_child_at_index(i)
+                if child:
+                    child_path = f"{path_prefix}.{i}" if path_prefix else str(i)
+                    child_node = walk_tree(child, depth + 1, max_depth, roles, child_path)
+                    if child_node is not None:
+                        if isinstance(child_node, list):
+                            children.extend(child_node)
+                        else:
+                            children.append(child_node)
+        except:
+            pass
+
+    if roles and role.lower() not in [r.lower() for r in roles]:
+        return children if children else None
+
+    return {
+        "id": path_prefix,
+        "role": role,
+        "title": name,
+        "value": value,
+        "description": desc,
+        "bounds": bounds,
+        "children": children,
+        "actions": actions,
+        "enabled": enabled,
+        "focused": focused,
+    }
+
+def find_app_by_pid(pid):
+    desktop = Atspi.get_desktop(0)
+    count = desktop.get_child_count()
+    for i in range(count):
+        app = desktop.get_child_at_index(i)
+        if app:
+            try:
+                if app.get_process_id() == pid:
+                    return app
+            except:
+                pass
+    raise Exception(f"No AT-SPI application found for PID {pid}")
+
+def navigate_to_element(root, element_id):
+    parts = element_id.split(".")
+    current = root
+    for part in parts:
+        idx = int(part)
+        child = current.get_child_at_index(idx)
+        if child is None:
+            raise Exception(f"Element not found at path: {element_id}")
+        current = child
+    return current
+
+def search_tree(accessible, query, role_filter, max_results, results, path_prefix, depth, max_depth):
+    if accessible is None or len(results) >= max_results or depth > max_depth:
+        return
+
+    role = get_role_name(accessible)
+    name = get_name(accessible)
+    value = get_value(accessible)
+    desc = get_description(accessible)
+
+    query_lower = query.lower()
+    match = (query_lower in name.lower() or query_lower in value.lower() or query_lower in desc.lower())
+
+    if role_filter and role.lower() != role_filter.lower():
+        match = False
+
+    if match:
+        bounds = get_bounds(accessible)
+        actions = get_actions(accessible)
+        enabled, focused = get_states(accessible)
+        results.append({
+            "id": path_prefix,
+            "role": role,
+            "title": name,
+            "value": value,
+            "description": desc,
+            "bounds": bounds,
+            "children": [],
+            "actions": actions,
+            "enabled": enabled,
+            "focused": focused,
+        })
+
+    try:
+        count = accessible.get_child_count()
+        for i in range(count):
+            if len(results) >= max_results:
+                break
+            child = accessible.get_child_at_index(i)
+            if child:
+                child_path = f"{path_prefix}.{i}" if path_prefix else str(i)
+                search_tree(child, query, role_filter, max_results, results, child_path, depth + 1, max_depth)
+    except:
+        pass
+
+def main():
+    raw = sys.stdin.read().strip()
+    try:
+        req = json.loads(raw)
+    except:
+        print(json.dumps({"ok": False, "error": "Invalid JSON input"}))
+        return
+
+    action = req.get("action", "")
+
+    try:
+        if action == "ax_tree":
+            pid = req.get("pid", 0)
+            max_depth = req.get("maxDepth", 8)
+            roles = req.get("roles", [])
+
+            root = find_app_by_pid(pid) if pid > 0 else Atspi.get_desktop(0)
+
+            global element_count
+            element_count = 0
+            tree = walk_tree(root, 0, max_depth, roles, "0")
+            print(json.dumps({"ok": True, "root": tree, "elementCount": element_count}))
+
+        elif action == "ax_action":
+            element_id = req.get("elementId", "")
+            action_name = req.get("action_name", "")
+            pid = req.get("pid", 0)
+
+            root = find_app_by_pid(pid) if pid > 0 else Atspi.get_desktop(0)
+            el = navigate_to_element(root, element_id)
+
+            action_iface = el.get_action_iface()
+            if not action_iface:
+                raise Exception("Element does not support actions")
+
+            performed = False
+            for i in range(action_iface.get_n_actions()):
+                if action_iface.get_action_name(i).lower() == action_name.lower():
+                    action_iface.do_action(i)
+                    performed = True
+                    break
+
+            if not performed:
+                raise Exception(f"Action '{action_name}' not found on element")
+
+            print(json.dumps({"ok": True}))
+
+        elif action == "ax_search":
+            query = req.get("query", "")
+            role_filter = req.get("role", None)
+            pid = req.get("pid", 0)
+            max_results = req.get("maxResults", 20)
+
+            root = find_app_by_pid(pid) if pid > 0 else Atspi.get_desktop(0)
+            results = []
+            search_tree(root, query, role_filter, max_results, results, "0", 0, 20)
+            print(json.dumps({"ok": True, "elements": results}))
+
+        else:
+            print(json.dumps({"ok": False, "error": f"Unknown action: {action}"}))
+    except Exception as e:
+        print(json.dumps({"ok": False, "error": str(e)}))
+
+if __name__ == "__main__":
+    main()
+`;
+
+let written = false;
+
+export async function ensureHelper(): Promise<string> {
+  if (written && existsSync(HELPER_PATH)) return HELPER_PATH;
+
+  if (existsSync(HELPER_PATH)) {
+    written = true;
+    return HELPER_PATH;
+  }
+
+  mkdirSync(BIN_DIR, { recursive: true });
+  writeFileSync(HELPER_PATH, PYTHON_SOURCE, { mode: 0o755 });
+  written = true;
+
+  return HELPER_PATH;
+}
+
+export interface AtspiHelperRequest {
+  action: string;
+  pid?: number;
+  maxDepth?: number;
+  roles?: string[];
+  elementId?: string;
+  action_name?: string;
+  query?: string;
+  role?: string;
+  maxResults?: number;
+  value?: string;
+}
+
+export interface AtspiHelperResponse {
+  ok: boolean;
+  error?: string;
+  root?: any;
+  elementCount?: number;
+  elements?: any[];
+}
+
+export async function execAtspiHelper(request: AtspiHelperRequest): Promise<AtspiHelperResponse> {
+  const helperPath = await ensureHelper();
+
+  return new Promise((resolve, reject) => {
+    const proc = spawn('python3', [helperPath], {
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+
+    let stdout = '';
+    let stderr = '';
+
+    proc.stdout.on('data', (d: Buffer) => { stdout += d.toString(); });
+    proc.stderr.on('data', (d: Buffer) => { stderr += d.toString(); });
+
+    proc.on('close', (code) => {
+      if (code !== 0) {
+        reject(new Error(`AT-SPI helper failed (exit ${code}): ${stderr}`));
+        return;
+      }
+
+      try {
+        const response = JSON.parse(stdout.trim()) as AtspiHelperResponse;
+        if (!response.ok && response.error) {
+          reject(new Error(response.error));
+          return;
+        }
+        resolve(response);
+      } catch {
+        reject(new Error(`Invalid helper output: ${stdout}`));
+      }
+    });
+
+    proc.on('error', (err) => {
+      reject(new Error(`python3 not found: ${err.message}. Install: sudo apt install python3`));
+    });
+
+    proc.stdin.write(JSON.stringify(request));
+    proc.stdin.end();
+  });
+}