@kortix/agent-tunnel 0.1.0

package/src/agent/capabilities/filesystem.ts

@@ -0,0 +1,133 @@
+/**
+ * Filesystem Capability — handles fs.read, fs.write, fs.list, fs.stat, fs.delete.
+ *
+ * All operations go through local-side path validation (defense in depth)
+ * even though the server already validates permissions.
+ */
+
+import { readFile, 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 type { TunnelConfig } from '../config';
+
+export function createFilesystemCapability(config: TunnelConfig): Capability {
+  const methods = new Map<string, RpcHandler>();
+
+  methods.set('fs.read', async (params) => {
+    const path = params.path as string;
+    const encoding = (params.encoding as BufferEncoding) || 'utf-8';
+
+    validatePath(path, config.allowedPaths);
+
+    const content = await readFile(path, { encoding });
+    const stats = await stat(path);
+
+    if (stats.size > config.maxFileSize) {
+      throw new Error(`File exceeds max size (${stats.size} > ${config.maxFileSize})`);
+    }
+
+    return {
+      content,
+      size: stats.size,
+      encoding,
+    };
+  });
+
+
+  methods.set('fs.write', async (params) => {
+    const path = params.path as string;
+    const content = params.content as string;
+    const encoding = (params.encoding as BufferEncoding) || 'utf-8';
+
+    validatePath(path, config.allowedPaths);
+
+    if (content.length > config.maxFileSize) {
+      throw new Error(`Content exceeds max size (${content.length} > ${config.maxFileSize})`);
+    }
+
+    await mkdir(dirname(path), { recursive: true });
+
+    await writeFile(path, content, { encoding });
+    const stats = await stat(path);
+
+    return {
+      size: stats.size,
+      path,
+    };
+  });
+
+
+  methods.set('fs.list', async (params) => {
+    const path = params.path as string;
+    const recursive = params.recursive as boolean || false;
+
+    validatePath(path, config.allowedPaths);
+
+    const entries = await readdir(path, { withFileTypes: true });
+
+    const result = entries.map((entry) => ({
+      name: entry.name,
+      path: join(path, entry.name),
+      isDirectory: entry.isDirectory(),
+      isFile: entry.isFile(),
+      isSymlink: entry.isSymbolicLink(),
+    }));
+
+    if (recursive) {
+      const dirs = result.filter((e) => e.isDirectory);
+      for (const dir of dirs) {
+        try {
+          const subEntries = await readdir(dir.path, { withFileTypes: true });
+          for (const sub of subEntries) {
+            result.push({
+              name: sub.name,
+              path: join(dir.path, sub.name),
+              isDirectory: sub.isDirectory(),
+              isFile: sub.isFile(),
+              isSymlink: sub.isSymbolicLink(),
+            });
+          }
+        } catch {
+        }
+      }
+    }
+
+    return { entries: result, count: result.length };
+  });
+
+
+  methods.set('fs.stat', async (params) => {
+    const path = params.path as string;
+
+    validatePath(path, config.allowedPaths);
+
+    const stats = await stat(path);
+
+    return {
+      size: stats.size,
+      isDirectory: stats.isDirectory(),
+      isFile: stats.isFile(),
+      isSymlink: stats.isSymbolicLink(),
+      mode: stats.mode,
+      mtime: stats.mtime.toISOString(),
+      ctime: stats.ctime.toISOString(),
+      atime: stats.atime.toISOString(),
+    };
+  });
+
+  methods.set('fs.delete', async (params) => {
+    const path = params.path as string;
+
+    validatePath(path, config.allowedPaths);
+
+    await unlink(path);
+
+    return { deleted: true, path };
+  });
+
+  return {
+    name: 'filesystem',
+    methods,
+  };
+}

package/src/agent/capabilities/index.ts

@@ -0,0 +1,42 @@
+/**
+ * Capability Registry — extensible registry for tunnel capabilities.
+ *
+ * Each capability (filesystem, shell, network, etc.) registers its
+ * RPC method handlers here. The TunnelAgent dispatches incoming
+ * JSON-RPC requests to the matching handler.
+ */
+
+export type RpcHandler = (params: Record<string, unknown>) => Promise<unknown>;
+
+export interface Capability {
+  name: string;
+  methods: Map<string, RpcHandler>;
+}
+
+export class CapabilityRegistry {
+  private capabilities = new Map<string, Capability>();
+
+  register(capability: Capability): void {
+    this.capabilities.set(capability.name, capability);
+  }
+
+  unregister(name: string): void {
+    this.capabilities.delete(name);
+  }
+
+  getHandler(method: string): RpcHandler | null {
+    for (const cap of this.capabilities.values()) {
+      const handler = cap.methods.get(method);
+      if (handler) return handler;
+    }
+    return null;
+  }
+
+  getCapabilityNames(): string[] {
+    return Array.from(this.capabilities.keys());
+  }
+
+  has(name: string): boolean {
+    return this.capabilities.has(name);
+  }
+}

package/src/agent/capabilities/shell.ts

@@ -0,0 +1,96 @@
+/**
+ * Shell Capability — handles shell.exec for running commands on the local machine.
+ *
+ * Security:
+ *   - Commands are executed as array args (no shell interpolation)
+ *   - First arg (executable) is validated against allowedCommands
+ *   - Working directory is validated against allowedPaths
+ *   - Timeout enforcement
+ */
+
+import { spawn } from 'child_process';
+import type { Capability, RpcHandler } from './index';
+import { validateCommand } from '../security/command-validator';
+import { validatePath } from '../security/path-validator';
+import type { TunnelConfig } from '../config';
+
+const DEFAULT_TIMEOUT_MS = 30_000;
+const MAX_OUTPUT_SIZE = 1024 * 1024;
+
+export function createShellCapability(config: TunnelConfig): Capability {
+  const methods = new Map<string, RpcHandler>();
+
+  methods.set('shell.exec', async (params) => {
+    const command = params.command as string;
+    const args = (params.args as string[]) || [];
+    const cwd = (params.cwd as string) || config.workingDir;
+    const timeout = Math.min(
+      (params.timeout as number) || DEFAULT_TIMEOUT_MS,
+      120_000,
+    );
+
+    validateCommand(command, config.allowedCommands);
+
+    if (cwd) {
+      validatePath(cwd, config.allowedPaths);
+    }
+
+    const SAFE_ENV_KEYS = ['PATH', 'HOME', 'USER', 'LANG', 'LC_ALL', 'LC_CTYPE', 'TMPDIR', 'NODE_ENV', 'HOSTNAME'];
+    const safeEnv: Record<string, string> = { TERM: 'dumb' };
+    for (const key of SAFE_ENV_KEYS) {
+      if (process.env[key]) {
+        safeEnv[key] = process.env[key]!;
+      }
+    }
+
+    return new Promise((resolve, reject) => {
+      const proc = spawn(command, args, {
+        cwd,
+        shell: false,
+        timeout,
+        env: safeEnv,
+      });
+
+      let stdout = '';
+      let stderr = '';
+      let stdoutTruncated = false;
+      let stderrTruncated = false;
+
+      proc.stdout?.on('data', (data: Buffer) => {
+        if (stdout.length < MAX_OUTPUT_SIZE) {
+          stdout += data.toString();
+        } else {
+          stdoutTruncated = true;
+        }
+      });
+
+      proc.stderr?.on('data', (data: Buffer) => {
+        if (stderr.length < MAX_OUTPUT_SIZE) {
+          stderr += data.toString();
+        } else {
+          stderrTruncated = true;
+        }
+      });
+
+      proc.on('error', (err) => {
+        reject(new Error(`Command failed to start: ${err.message}`));
+      });
+
+      proc.on('close', (code, signal) => {
+        resolve({
+          exitCode: code,
+          signal,
+          stdout: stdout.slice(0, MAX_OUTPUT_SIZE),
+          stderr: stderr.slice(0, MAX_OUTPUT_SIZE),
+          stdoutTruncated,
+          stderrTruncated,
+        });
+      });
+    });
+  });
+
+  return {
+    name: 'shell',
+    methods,
+  };
+}

package/src/agent/cli.ts

@@ -0,0 +1,222 @@
+#!/usr/bin/env bun
+import { loadConfig } from './config';
+import { TunnelAgent } from './agent';
+import { CapabilityRegistry } from './capabilities/index';
+import { createFilesystemCapability } from './capabilities/filesystem';
+import { createShellCapability } from './capabilities/shell';
+import { createDesktopCapability } from './capabilities/desktop';
+import { hostname, platform, arch, release } from 'os';
+
+const c = {
+  reset:   '\x1b[0m',
+  bold:    '\x1b[1m',
+  dim:     '\x1b[2m',
+  italic:  '\x1b[3m',
+  cyan:    '\x1b[36m',
+  blue:    '\x1b[34m',
+  green:   '\x1b[32m',
+  yellow:  '\x1b[33m',
+  red:     '\x1b[31m',
+  magenta: '\x1b[35m',
+  white:   '\x1b[97m',
+  gray:    '\x1b[90m',
+  bgCyan:  '\x1b[46m',
+  bgBlue:  '\x1b[44m',
+};
+
+function parseArgs(argv: string[]): { command: string; flags: Record<string, string> } {
+  const command = argv[2] || 'help';
+  const flags: Record<string, string> = {};
+
+  for (let i = 3; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg.startsWith('--')) {
+      const key = arg.slice(2);
+      const value = argv[i + 1] && !argv[i + 1].startsWith('--') ? argv[++i] : 'true';
+      flags[key] = value;
+    }
+  }
+
+  return { command, flags };
+}
+
+function clearScreen(): void {
+  process.stdout.write('\x1b[2J\x1b[3J\x1b[H');
+}
+
+const sleep = (ms: number) => new Promise<void>(r => setTimeout(r, ms));
+
+async function printStartup(config: { tunnelId: string; apiUrl: string }, capabilities: string[], version: string): Promise<void> {
+  const machine = hostname();
+  const plat = `${platform()} ${arch()}`;
+
+  const truncate = (s: string, max: number) => s.length > max ? s.slice(0, max) + '…' : s;
+  const tunnelDisplay = truncate(config.tunnelId, 40);
+  const apiDisplay = truncate(config.apiUrl, 40);
+  const machineDisplay = truncate(machine, 28);
+
+  // ── ASCII art ───────────────────────────────────────────
+  console.log('');
+  console.log(`      ${c.cyan}▄▀█ █▀▀ █▀▀ █▄ █ ▀█▀${c.reset}   ${c.cyan}▀█▀ █ █ █▄ █ █▄ █ █▀▀ █  ${c.reset}`);
+  console.log(`      ${c.cyan}█▀█ █▄█ ██▄ █ ▀█  █${c.reset}    ${c.cyan} █  █▄█ █ ▀█ █ ▀█ ██▄ █▄▄${c.reset}`);
+  console.log('');
+
+  // ── Tunnel connection animation ─────────────────────────
+  const barW = 50;
+  const frames = 14;
+
+  for (let i = 0; i <= frames; i++) {
+    const filled = Math.round((i / frames) * barW);
+    const empty = barW - filled;
+    process.stdout.write(
+      `\r      ${c.cyan}◇${c.reset} ${c.cyan}${'═'.repeat(filled)}${c.reset}${c.gray}${'─'.repeat(empty)}${c.reset}  `,
+    );
+    await sleep(20);
+  }
+  process.stdout.write(`\r      ${c.cyan}◇ ${'═'.repeat(barW)} ◆${c.reset}  \n`);
+  await sleep(120);
+
+  // ── Info box ────────────────────────────────────────────
+  const W = 60;
+  const vLen = (s: string) => s.replace(/\x1b\[[0-9;]*m/g, '').length;
+
+  const row = (content: string) => {
+    const pad = Math.max(0, W - vLen(content));
+    console.log(`  ${c.gray}│${c.reset}${content}${' '.repeat(pad)}${c.gray}│${c.reset}`);
+  };
+
+  const blank = () => console.log(`  ${c.gray}│${c.reset}${' '.repeat(W)}${c.gray}│${c.reset}`);
+
+  const titleL = `   ${c.cyan}◆${c.reset}  ${c.bold}${c.white}Agent Tunnel${c.reset}`;
+  const titleR = `${c.dim}v${version}${c.reset}   `;
+  const titleLLen = 18;
+  const titleRLen = 1 + version.length + 3;
+  const titlePad = Math.max(1, W - titleLLen - titleRLen);
+
+  const capStr = capabilities
+    .map(name => `${c.green}●${c.reset} ${c.white}${name}${c.reset}`)
+    .join('   ');
+
+  const brand = 'created by kortix';
+  const brandFill = W - brand.length - 3;
+
+  console.log('');
+  console.log(`  ${c.gray}╭${'─'.repeat(W)}╮${c.reset}`);
+  blank();
+  row(`${titleL}${' '.repeat(titlePad)}${titleR}`);
+  row(`   ${c.dim}Bridge between AI agents & local machines${c.reset}`);
+  blank();
+  row(`   ${c.dim}tunnel${c.reset}    ${c.white}${tunnelDisplay}${c.reset}`);
+  row(`   ${c.dim}relay${c.reset}     ${c.white}${apiDisplay}${c.reset}`);
+  row(`   ${c.dim}machine${c.reset}   ${c.white}${machineDisplay}${c.reset} ${c.dim}(${plat})${c.reset}`);
+  blank();
+  console.log(`  ${c.gray}╰${'─'.repeat(brandFill)} ${c.dim}created by ${c.cyan}kortix${c.reset} ${c.gray}─╯${c.reset}`);
+  console.log('');
+}
+
+async function commandConnect(flags: Record<string, string>): Promise<void> {
+  const config = loadConfig({
+    token: flags.token,
+    tunnelId: flags['tunnel-id'],
+    apiUrl: flags['api-url'],
+  });
+
+  if (!config.token) {
+    console.error(`${c.red}${c.bold} error${c.reset} --token is required`);
+    process.exit(1);
+  }
+
+  if (!config.tunnelId) {
+    console.error(`${c.red}${c.bold} error${c.reset} --tunnel-id is required`);
+    process.exit(1);
+  }
+
+  const registry = new CapabilityRegistry();
+  registry.register(createFilesystemCapability(config));
+  registry.register(createShellCapability(config));
+  registry.register(createDesktopCapability());
+
+  clearScreen();
+  await printStartup(config, registry.getCapabilityNames(), '0.1.0');
+
+  const agent = new TunnelAgent(config, registry);
+  agent.connect();
+
+  const shutdown = () => {
+    console.log(`\n${c.dim}  Shutting down…${c.reset}`);
+    agent.disconnect();
+    process.exit(0);
+  };
+
+  process.on('SIGTERM', shutdown);
+  process.on('SIGINT', shutdown);
+}
+
+async function commandStatus(flags: Record<string, string>): Promise<void> {
+  const config = loadConfig({
+    token: flags.token,
+    tunnelId: flags['tunnel-id'],
+    apiUrl: flags['api-url'],
+  });
+
+  if (!config.token || !config.tunnelId) {
+    console.error('Error: --token and --tunnel-id are required');
+    process.exit(1);
+  }
+
+  try {
+    const res = await fetch(`${config.apiUrl}/connections/${config.tunnelId}`, {
+      headers: { Authorization: `Bearer ${config.token}` },
+    });
+
+    if (!res.ok) {
+      console.error(`Error: ${res.status} ${await res.text()}`);
+      process.exit(1);
+    }
+
+    const data = await res.json();
+    console.log(JSON.stringify(data, null, 2));
+  } catch (err) {
+    console.error('Error:', err);
+    process.exit(1);
+  }
+}
+
+function showHelp(): void {
+  console.log('');
+  console.log(`  ${c.cyan}▄▀█ █▀▀ █▀▀ █▄ █ ▀█▀${c.reset}   ${c.cyan}▀█▀ █ █ █▄ █ █▄ █ █▀▀ █  ${c.reset}`);
+  console.log(`  ${c.cyan}█▀█ █▄█ ██▄ █ ▀█  █${c.reset}    ${c.cyan} █  █▄█ █ ▀█ █ ▀█ ██▄ █▄▄${c.reset}`);
+  console.log('');
+  console.log(`  ${c.dim}Secure bridge between AI agents & local machines${c.reset}`);
+  console.log('');
+  console.log(`  ${c.bold}Usage${c.reset}   ${c.dim}npx @kortix/agent-tunnel <command> [options]${c.reset}`);
+  console.log('');
+  console.log(`${c.gray}  ── Commands ────────────────────────────────────────${c.reset}`);
+  console.log(`  ${c.cyan}connect${c.reset}       Connect and start handling RPC requests`);
+  console.log(`  ${c.cyan}status${c.reset}        Check tunnel connection status`);
+  console.log(`  ${c.cyan}help${c.reset}          Show this help message`);
+  console.log('');
+  console.log(`${c.gray}  ── Options ─────────────────────────────────────────${c.reset}`);
+  console.log(`  ${c.white}--token${c.reset} ${c.dim}<token>${c.reset}       API token ${c.dim}(or TUNNEL_TOKEN)${c.reset}`);
+  console.log(`  ${c.white}--tunnel-id${c.reset} ${c.dim}<id>${c.reset}     Tunnel ID ${c.dim}(or TUNNEL_ID)${c.reset}`);
+  console.log(`  ${c.white}--api-url${c.reset} ${c.dim}<url>${c.reset}       API URL ${c.dim}(default: http://localhost:8080)${c.reset}`);
+  console.log('');
+  console.log(`  ${c.dim}Config: ~/.agent-tunnel/config.json${c.reset}`);
+  console.log(`  ${c.dim}powered by ${c.cyan}kortix${c.reset}`);
+  console.log('');
+}
+
+const { command, flags } = parseArgs(process.argv);
+
+switch (command) {
+  case 'connect':
+    commandConnect(flags);
+    break;
+  case 'status':
+    commandStatus(flags);
+    break;
+  case 'help':
+  default:
+    showHelp();
+    break;
+}

package/src/agent/config.ts

@@ -0,0 +1,54 @@
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+
+export interface TunnelConfig {
+  token: string;
+  tunnelId: string;
+  apiUrl: string;
+  /** WS path on the server (default: '/ws'). Override for custom server mounts. */
+  wsPath: string;
+  maxFileSize: number;
+  allowedPaths: string[];
+  allowedCommands: string[];
+  workingDir: string;
+}
+
+const CONFIG_DIR = join(homedir(), '.agent-tunnel');
+const CONFIG_FILE = join(CONFIG_DIR, 'config.json');
+
+const DEFAULTS: Partial<TunnelConfig> = {
+  apiUrl: 'http://localhost:8080',
+  wsPath: '/ws',
+  maxFileSize: 10 * 1024 * 1024,
+  allowedPaths: [homedir()],
+  allowedCommands: [],
+  workingDir: homedir(),
+};
+
+export function loadConfig(overrides: Partial<TunnelConfig> = {}): TunnelConfig {
+  let fileConfig: Partial<TunnelConfig> = {};
+  if (existsSync(CONFIG_FILE)) {
+    try {
+      fileConfig = JSON.parse(readFileSync(CONFIG_FILE, 'utf-8'));
+    } catch (err) {
+      console.warn(`[config] Failed to parse ${CONFIG_FILE}:`, err);
+    }
+  }
+
+  const envConfig: Partial<TunnelConfig> = {};
+  if (process.env.TUNNEL_TOKEN) envConfig.token = process.env.TUNNEL_TOKEN;
+  if (process.env.TUNNEL_ID) envConfig.tunnelId = process.env.TUNNEL_ID;
+  if (process.env.TUNNEL_API_URL) envConfig.apiUrl = process.env.TUNNEL_API_URL;
+  if (process.env.TUNNEL_WS_PATH) envConfig.wsPath = process.env.TUNNEL_WS_PATH;
+  if (process.env.TUNNEL_MAX_FILE_SIZE) envConfig.maxFileSize = parseInt(process.env.TUNNEL_MAX_FILE_SIZE, 10);
+
+  const merged = {
+    ...DEFAULTS,
+    ...fileConfig,
+    ...envConfig,
+    ...overrides,
+  } as TunnelConfig;
+
+  return merged;
+}

package/src/agent/index.ts

@@ -0,0 +1,11 @@
+export { TunnelAgent } from './agent';
+export { loadConfig, type TunnelConfig } from './config';
+export { CapabilityRegistry } from './capabilities/index';
+export type { Capability, RpcHandler } from './capabilities/index';
+export { createFilesystemCapability } from './capabilities/filesystem';
+export { createShellCapability } from './capabilities/shell';
+export { createDesktopCapability } from './capabilities/desktop';
+export { PermissionGuard } from './security/permission-guard';
+export type { LocalPermission } from './security/permission-guard';
+export { validateCommand } from './security/command-validator';
+export { validatePath } from './security/path-validator';

package/src/agent/security/command-validator.ts

@@ -0,0 +1,61 @@
+/**
+ * Command Validator — defense-in-depth command injection prevention.
+ *
+ * Validates that shell commands:
+ *   1. Are in the allowed commands list (if configured)
+ *   2. Don't contain shell metacharacters
+ *   3. Don't execute dangerous system commands
+ */
+
+/** Commands that should never be executed via tunnel regardless of config. */
+const BLOCKED_COMMANDS = new Set([
+  'rm',
+  'rmdir',
+  'mkfs',
+  'dd',
+  'shutdown',
+  'reboot',
+  'halt',
+  'poweroff',
+  'init',
+  'systemctl',
+  'sudo',
+  'su',
+  'passwd',
+  'chown',
+  'chmod',
+  'chgrp',
+  'mount',
+  'umount',
+  'fdisk',
+  'parted',
+  'iptables',
+  'ufw',
+  'firewall-cmd',
+]);
+
+const SHELL_METACHAR_REGEX = /[;&|`$(){}[\]<>!#~]/;
+
+export function validateCommand(command: string, allowedCommands: string[]): void {
+  if (!command || typeof command !== 'string') {
+    throw new Error('Command is required');
+  }
+
+  const trimmed = command.trim();
+
+  if (SHELL_METACHAR_REGEX.test(trimmed)) {
+    throw new Error(`Command contains disallowed characters: "${trimmed}"`);
+  }
+
+  const executable = trimmed.split(/\s+/)[0];
+
+  if (BLOCKED_COMMANDS.has(executable)) {
+    throw new Error(`Command "${executable}" is blocked for security reasons`);
+  }
+
+  if (allowedCommands.length > 0) {
+    if (!allowedCommands.includes(executable)) {
+      throw new Error(`Command "${executable}" is not in the allowed commands list`);
+    }
+  }
+}

package/src/agent/security/path-validator.ts

@@ -0,0 +1,55 @@
+/**
+ * Path Validator — defense-in-depth path traversal prevention.
+ *
+ * Validates that requested paths:
+ *   1. Are absolute
+ *   2. Resolve to an absolute path (follows symlinks)
+ *   3. Fall within allowed directories
+ *   4. Don't hit sensitive system paths
+ */
+
+import { resolve, normalize } from 'path';
+import { realpathSync } from 'fs';
+
+const SENSITIVE_PATHS = [
+  '/etc/shadow',
+  '/etc/passwd',
+  '/etc/sudoers',
+  '/etc/ssh',
+  '/root/.ssh',
+  '/proc',
+  '/sys',
+  '/dev',
+];
+
+
+export function validatePath(path: string, allowedPaths: string[]): void {
+  if (!path) {
+    throw new Error('Path is required');
+  }
+
+  const normalized = normalize(resolve(path));
+  let resolved: string;
+  try {
+    resolved = realpathSync(normalized);
+  } catch {
+    resolved = normalized;
+  }
+
+  for (const sensitive of SENSITIVE_PATHS) {
+    if (resolved === sensitive || resolved.startsWith(sensitive + '/')) {
+      throw new Error(`Access denied: sensitive system path "${path}"`);
+    }
+  }
+
+  if (allowedPaths.length > 0) {
+    const withinAllowed = allowedPaths.some((allowed) => {
+      const normalizedAllowed = normalize(resolve(allowed));
+      return resolved === normalizedAllowed || resolved.startsWith(normalizedAllowed + '/');
+    });
+
+    if (!withinAllowed) {
+      throw new Error(`Access denied: path "${path}" is outside allowed directories`);
+    }
+  }
+}