@kortix/agent-tunnel 0.1.4 → 0.12.7

package/src/agent/capabilities/desktop.ts

@@ -1,193 +1,126 @@
-import { platform } from 'os';
 import type { Capability, RpcHandler } from './index';
-import type { DesktopDriver } from './desktop/types';
-
-function createDriver(): DesktopDriver {
-  switch (platform()) {
-    case 'darwin': {
-      const { MacOSDriver } = require('./desktop/macos-driver');
-      return new MacOSDriver();
-    }
-    case 'win32': {
-      const { WindowsDriver } = require('./desktop/windows-driver');
-      return new WindowsDriver();
-    }
-    default: {
-      const { LinuxDriver } = require('./desktop/linux-driver');
-      return new LinuxDriver();
-    }
+import { CuaDriver } from './desktop/cua-driver';
+import { desktopFeatureForMethod } from '../../shared/permissions';
+import type { LocalPermission } from '../security/permission-guard';
+
+const CUA_TOOLS = [
+  'bring_to_front',
+  'check_for_update',
+  'check_permissions',
+  'click',
+  'double_click',
+  'drag',
+  'end_session',
+  'get_accessibility_tree',
+  'get_agent_cursor_state',
+  'get_config',
+  'get_cursor_position',
+  'get_recording_state',
+  'get_screen_size',
+  'get_window_state',
+  'hotkey',
+  'kill_app',
+  'launch_app',
+  'list_apps',
+  'list_windows',
+  'move_cursor',
+  'page',
+  'press_key',
+  'replay_trajectory',
+  'right_click',
+  'scroll',
+  'set_agent_cursor_enabled',
+  'set_agent_cursor_motion',
+  'set_agent_cursor_style',
+  'set_config',
+  'set_value',
+  'start_recording',
+  'install_ffmpeg',
+  'start_session',
+  'stop_recording',
+  'type_text',
+  'zoom',
+];
+
+const LOCAL_ONLY_CUA_TOOLS = new Set(['check_for_update', 'install_ffmpeg']);
+
+function assertRemotelyCallableTool(tool: unknown): asserts tool is string {
+  if (typeof tool !== 'string' || tool.length === 0) {
+    throw new Error('CUA tool name is required');
+  }
+  if (LOCAL_ONLY_CUA_TOOLS.has(tool)) {
+    throw new Error(`CUA tool "${tool}" is local-only and cannot run through Agent Tunnel`);
   }
 }
 
 export function createDesktopCapability(): Capability {
-  const driver = createDriver();
+  const cua = new CuaDriver();
   const methods = new Map<string, RpcHandler>();
 
-  methods.set('desktop.screenshot', async (params) => {
-    return driver.screenshot({
-      region: params.region as any,
-      windowId: params.windowId as number | undefined,
-    });
-  });
-
-  methods.set('desktop.mouse.click', async (params) => {
-    await driver.mouseClick({
-      x: params.x as number,
-      y: params.y as number,
-      button: params.button as any,
-      clicks: params.clicks as number | undefined,
-      modifiers: params.modifiers as string[] | undefined,
-    });
-    return { ok: true };
-  });
-
-  methods.set('desktop.mouse.move', async (params) => {
-    await driver.mouseMove({
-      x: params.x as number,
-      y: params.y as number,
-    });
-    return { ok: true };
-  });
-
-  methods.set('desktop.mouse.drag', async (params) => {
-    await driver.mouseDrag({
-      fromX: params.fromX as number,
-      fromY: params.fromY as number,
-      toX: params.toX as number,
-      toY: params.toY as number,
-      button: params.button as any,
-    });
-    return { ok: true };
-  });
-
-  methods.set('desktop.mouse.scroll', async (params) => {
-    await driver.mouseScroll({
-      x: params.x as number,
-      y: params.y as number,
-      deltaX: params.deltaX as number | undefined,
-      deltaY: params.deltaY as number | undefined,
-    });
-    return { ok: true };
-  });
-
-  methods.set('desktop.mouse.position', async () => {
-    return driver.mousePosition();
-  });
-
-  methods.set('desktop.keyboard.type', async (params) => {
-    await driver.keyboardType({
-      text: params.text as string,
-      delay: params.delay as number | undefined,
-    });
-    return { ok: true };
-  });
-
-  methods.set('desktop.keyboard.key', async (params) => {
-    await driver.keyboardKey({
-      keys: params.keys as string[],
-    });
-    return { ok: true };
-  });
-
-  methods.set('desktop.window.list', async () => {
-    return { windows: await driver.windowList() };
-  });
-
-  methods.set('desktop.window.focus', async (params) => {
-    await driver.windowFocus(params.windowId as number);
-    return { ok: true };
-  });
-
-  methods.set('desktop.window.resize', async (params) => {
-    await driver.windowResize(params.windowId as number, {
-      x: params.x as number | undefined,
-      y: params.y as number | undefined,
-      width: params.width as number | undefined,
-      height: params.height as number | undefined,
-    });
-    return { ok: true };
-  });
-
-  methods.set('desktop.window.close', async (params) => {
-    await driver.windowClose(params.windowId as number);
-    return { ok: true };
-  });
-
-  methods.set('desktop.window.minimize', async (params) => {
-    await driver.windowMinimize(params.windowId as number);
-    return { ok: true };
-  });
-
-  methods.set('desktop.app.launch', async (params) => {
-    await driver.appLaunch(params.app as string);
-    return { ok: true };
-  });
-
-  methods.set('desktop.app.quit', async (params) => {
-    await driver.appQuit(params.app as string);
-    return { ok: true };
-  });
+  const assertDesktopPermission = (params: Record<string, unknown>, method: string): void => {
+    const permission = params.__permission as LocalPermission | undefined;
+    if (permission?.capability !== 'desktop') {
+      throw new Error('Permission denied: desktop permission required');
+    }
+    const features = Array.isArray(permission.scope?.features)
+      ? permission.scope.features.filter((value): value is string => typeof value === 'string')
+      : [];
+    if (features.length === 0) return;
+    const feature = desktopFeatureForMethod(method, params);
+    if (!feature || !features.includes(feature)) {
+      throw new Error(
+        `Permission denied: desktop feature "${feature ?? 'unknown'}" is not allowed`,
+      );
+    }
+  };
 
-  methods.set('desktop.app.list', async () => {
-    return { apps: await driver.appList() };
+  methods.set('desktop.cua.ensure', async (params) => {
+    assertDesktopPermission(params, 'desktop.cua.ensure');
+    const binary = await cua.ensureInstalled();
+    const version = await cua.version().catch(() => undefined);
+    return { ok: true, binary, version };
   });
 
-  methods.set('desktop.clipboard.read', async () => {
-    return { text: await driver.clipboardRead() };
+  methods.set('desktop.cua.start_daemon', async (params) => {
+    assertDesktopPermission(params, 'desktop.cua.start_daemon');
+    return cua.startDaemon();
   });
 
-  methods.set('desktop.clipboard.write', async (params) => {
-    await driver.clipboardWrite(params.text as string);
-    return { ok: true };
+  methods.set('desktop.cua.status', async (params) => {
+    assertDesktopPermission(params, 'desktop.cua.status');
+    return { status: await cua.status() };
   });
 
-  methods.set('desktop.screen.info', async () => {
-    return driver.screenInfo();
+  methods.set('desktop.cua.version', async (params) => {
+    assertDesktopPermission(params, 'desktop.cua.version');
+    return { version: await cua.version() };
   });
 
-  methods.set('desktop.cursor.image', async (params) => {
-    return driver.cursorImage(params.radius as number | undefined);
+  methods.set('desktop.cua.list_tools', async (params) => {
+    assertDesktopPermission(params, 'desktop.cua.list_tools');
+    return { tools: await cua.listTools() };
   });
 
-  methods.set('desktop.ax.tree', async (params) => {
-    return driver.axTree({
-      pid: params.pid as number | undefined,
-      maxDepth: params.maxDepth as number | undefined,
-      roles: params.roles as string[] | undefined,
-    });
+  methods.set('desktop.cua.describe', async (params) => {
+    assertDesktopPermission(params, 'desktop.cua.describe');
+    return { description: await cua.describe(params.tool as string) };
   });
 
-  methods.set('desktop.ax.action', async (params) => {
-    return driver.axAction({
-      elementId: params.elementId as string,
-      action: params.action as string,
-      pid: params.pid as number | undefined,
-    });
+  methods.set('desktop.cua.call', async (params) => {
+    assertDesktopPermission(params, 'desktop.cua.call');
+    const tool = params.tool;
+    assertRemotelyCallableTool(tool);
+    const args = (params.args || {}) as Record<string, unknown>;
+    return cua.call(tool, args);
   });
 
-  methods.set('desktop.ax.set_value', async (params) => {
-    return driver.axSetValue({
-      elementId: params.elementId as string,
-      value: params.value as string,
-      pid: params.pid as number | undefined,
+  for (const tool of CUA_TOOLS) {
+    if (LOCAL_ONLY_CUA_TOOLS.has(tool)) continue;
+    methods.set(`desktop.cua.${tool}`, async (params) => {
+      assertDesktopPermission(params, `desktop.cua.${tool}`);
+      return cua.call(tool, params);
     });
-  });
-
-  methods.set('desktop.ax.focus', async (params) => {
-    return driver.axFocus({
-      elementId: params.elementId as string,
-      pid: params.pid as number | undefined,
-    });
-  });
-
-  methods.set('desktop.ax.search', async (params) => {
-    return driver.axSearch({
-      query: params.query as string,
-      role: params.role as string | undefined,
-      pid: params.pid as number | undefined,
-      maxResults: params.maxResults as number | undefined,
-    });
-  });
+  }
 
   return {
     name: 'desktop',

package/src/agent/capabilities/enabled-registry.ts

@@ -0,0 +1,24 @@
+import type { TunnelConfig } from '../config';
+import { CapabilityRegistry } from './index';
+import { createDesktopCapability } from './desktop';
+import { findCuaDriverBinary } from './desktop/cua-driver';
+import { createFilesystemCapability } from './filesystem';
+import { createShellCapability } from './shell';
+
+/** Build the local RPC surface from the browser-approved capability ceiling. */
+export function createEnabledCapabilityRegistry(
+  config: TunnelConfig,
+  findDesktopDriver: () => string | null = findCuaDriverBinary,
+): CapabilityRegistry {
+  const registry = new CapabilityRegistry();
+  const enabled = new Set(config.enabledCapabilities ?? ['filesystem', 'shell', 'desktop']);
+  if (enabled.has('filesystem')) registry.register(createFilesystemCapability(config));
+  if (enabled.has('shell')) registry.register(createShellCapability(config));
+  // Do not advertise Computer Use unless this process can execute the trusted
+  // local driver. The server must see the real handler surface, not the user's
+  // desired capability list.
+  if (enabled.has('desktop') && findDesktopDriver()) {
+    registry.register(createDesktopCapability());
+  }
+  return registry;
+}

package/src/agent/capabilities/filesystem.ts

@@ -5,50 +5,154 @@
  * even though the server already validates permissions.
  */
 
-import { readFile, writeFile, readdir, stat, unlink, mkdir } from 'fs/promises';
+import { open, writeFile, readdir, stat, unlink, mkdir } from 'fs/promises';
 import { join, dirname } from 'path';
 import type { Capability, RpcHandler } from './index';
-import { validatePath } from '../security/path-validator';
+import { validatePath, validateWritePath } from '../security/path-validator';
 import type { TunnelConfig } from '../config';
+import type { LocalPermission } from '../security/permission-guard';
+import { operationForMethod } from '../../shared/permissions';
+
+function permissionFilesystemScope(params: Record<string, unknown>): {
+  paths?: string[];
+  allowedPaths?: string[];
+  blockedPaths?: string[];
+  excludePatterns?: string[];
+  operations?: string[];
+  maxFileSize?: number;
+} {
+  const permission = params.__permission as LocalPermission | undefined;
+  if (permission?.capability !== 'filesystem') {
+    throw new Error('Permission denied: filesystem permission required');
+  }
+  return (permission.scope ?? {}) as {
+    paths?: string[];
+    blockedPaths?: string[];
+    excludePatterns?: string[];
+    operations?: string[];
+    maxFileSize?: number;
+  };
+}
+
+function scopedAllowedPaths(params: Record<string, unknown>): string[] {
+  const scope = permissionFilesystemScope(params);
+  return Array.isArray(scope.paths)
+    ? scope.paths.filter((p: unknown): p is string => typeof p === 'string' && p.trim().length > 0)
+    : [];
+}
+
+function effectiveBlockedPaths(config: TunnelConfig, params: Record<string, unknown>): string[] {
+  const scope = permissionFilesystemScope(params);
+  const scoped = Array.isArray(scope.blockedPaths)
+    ? scope.blockedPaths.filter((p): p is string => typeof p === 'string' && p.trim().length > 0)
+    : [];
+  return [...config.blockedPaths, ...scoped];
+}
+
+function validateFilesystemPath(
+  path: string,
+  config: TunnelConfig,
+  params: Record<string, unknown>,
+  write = false,
+): string {
+  const blocked = effectiveBlockedPaths(config, params);
+  const validator = write ? validateWritePath : validatePath;
+  const resolved = validator(path, config.allowedPaths, blocked);
+  const scoped = scopedAllowedPaths(params);
+  if (scoped.length > 0) validator(path, scoped, blocked);
+
+  const scope = permissionFilesystemScope(params);
+  const patterns = Array.isArray(scope.excludePatterns)
+    ? scope.excludePatterns.filter((value): value is string => typeof value === 'string')
+    : [];
+  if (patterns.some((pattern) => matchGlob(path, pattern) || matchGlob(resolved, pattern))) {
+    throw new Error(`Permission denied: path "${path}" matches an excluded pattern`);
+  }
+  return resolved;
+}
+
+function matchGlob(path: string, pattern: string): boolean {
+  const regex = pattern
+    .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+    .replace(/\*\*/g, '{{GLOBSTAR}}')
+    .replace(/\*/g, '[^/\\\\]*')
+    .replace(/\{\{GLOBSTAR\}\}/g, '.*');
+  return new RegExp(`^${regex}$`).test(path);
+}
+
+function parseEncoding(value: unknown): 'utf8' | 'base64' {
+  if (value === undefined || value === 'utf-8' || value === 'utf8') return 'utf8';
+  if (value === 'base64') return 'base64';
+  throw new Error('Encoding must be "utf-8" or "base64"');
+}
+
+function assertFilesystemOperation(params: Record<string, unknown>, method: string): void {
+  const scope = permissionFilesystemScope(params);
+  const operations = Array.isArray(scope.operations)
+    ? scope.operations.filter((value): value is string => typeof value === 'string')
+    : [];
+  const operation = operationForMethod(method);
+  if (operations.length > 0 && !operations.includes(operation)) {
+    throw new Error(`Permission denied: filesystem operation "${operation}" is not allowed`);
+  }
+}
 
 export function createFilesystemCapability(config: TunnelConfig): Capability {
   const methods = new Map<string, RpcHandler>();
 
   methods.set('fs.read', async (params) => {
+    assertFilesystemOperation(params, 'fs.read');
     const path = params.path as string;
-    const encoding = (params.encoding as BufferEncoding) || 'utf-8';
-
-    validatePath(path, config.allowedPaths, config.blockedPaths);
-
-    const stats = await stat(path);
-    if (stats.size > config.maxFileSize) {
-      throw new Error(`File exceeds max size (${stats.size} > ${config.maxFileSize})`);
+    const encoding = parseEncoding(params.encoding);
+
+    validateFilesystemPath(path, config, params);
+
+    const handle = await open(path, 'r');
+    try {
+      const stats = await handle.stat();
+      const scope = permissionFilesystemScope(params);
+      const maxFileSize = Math.min(
+        config.maxFileSize,
+        typeof scope.maxFileSize === 'number' ? scope.maxFileSize : config.maxFileSize,
+      );
+      if (stats.size > maxFileSize) {
+        throw new Error(`File exceeds max size (${stats.size} > ${maxFileSize})`);
+      }
+      const content = await handle.readFile({ encoding });
+      return {
+        content,
+        size: stats.size,
+        encoding,
+      };
+    } finally {
+      await handle.close();
     }
-
-    const content = await readFile(path, { encoding });
-
-    return {
-      content,
-      size: stats.size,
-      encoding,
-    };
   });
 
-
   methods.set('fs.write', async (params) => {
+    assertFilesystemOperation(params, 'fs.write');
     const path = params.path as string;
     const content = params.content as string;
-    const encoding = (params.encoding as BufferEncoding) || 'utf-8';
-
-    validatePath(path, config.allowedPaths, config.blockedPaths);
-
-    if (content.length > config.maxFileSize) {
-      throw new Error(`Content exceeds max size (${content.length} > ${config.maxFileSize})`);
+    const encoding = parseEncoding(params.encoding);
+
+    validateFilesystemPath(path, config, params, true);
+
+    const scope = permissionFilesystemScope(params);
+    const maxFileSize = Math.min(
+      config.maxFileSize,
+      typeof scope.maxFileSize === 'number' ? scope.maxFileSize : config.maxFileSize,
+    );
+    if (typeof content !== 'string') throw new Error('Content must be a string');
+    const contentBytes = Buffer.byteLength(content, encoding);
+    if (contentBytes > maxFileSize) {
+      throw new Error(`Content exceeds max size (${contentBytes} > ${maxFileSize})`);
     }
 
     await mkdir(dirname(path), { recursive: true });
+    validateFilesystemPath(path, config, params, true);
 
     await writeFile(path, content, { encoding });
+    validateFilesystemPath(path, config, params);
     const stats = await stat(path);
 
     return {
@@ -57,12 +161,12 @@ export function createFilesystemCapability(config: TunnelConfig): Capability {
     };
   });
 
-
   methods.set('fs.list', async (params) => {
+    assertFilesystemOperation(params, 'fs.list');
     const path = params.path as string;
-    const recursive = params.recursive as boolean || false;
+    const recursive = (params.recursive as boolean) || false;
 
-    validatePath(path, config.allowedPaths, config.blockedPaths);
+    validateFilesystemPath(path, config, params);
 
     const entries = await readdir(path, { withFileTypes: true });
 
@@ -88,19 +192,18 @@ export function createFilesystemCapability(config: TunnelConfig): Capability {
               isSymlink: sub.isSymbolicLink(),
             });
           }
-        } catch {
-        }
+        } catch {}
       }
     }
 
     return { entries: result, count: result.length };
   });
 
-
   methods.set('fs.stat', async (params) => {
+    assertFilesystemOperation(params, 'fs.stat');
     const path = params.path as string;
 
-    validatePath(path, config.allowedPaths, config.blockedPaths);
+    validateFilesystemPath(path, config, params);
 
     const stats = await stat(path);
 
@@ -117,9 +220,10 @@ export function createFilesystemCapability(config: TunnelConfig): Capability {
   });
 
   methods.set('fs.delete', async (params) => {
+    assertFilesystemOperation(params, 'fs.delete');
     const path = params.path as string;
 
-    validatePath(path, config.allowedPaths, config.blockedPaths);
+    validateFilesystemPath(path, config, params);
 
     await unlink(path);
 

package/src/agent/capabilities/index.ts

@@ -1,7 +1,7 @@
 /**
  * Capability Registry — extensible registry for tunnel capabilities.
  *
- * Each capability (filesystem, shell, network, etc.) registers its
+ * Each capability (filesystem, shell, CUA-backed desktop, etc.) registers its
  * RPC method handlers here. The TunnelAgent dispatches incoming
  * JSON-RPC requests to the matching handler.
  */