@kortix/agent-tunnel 0.1.4 → 0.12.7

package/src/agent/capabilities/security.test.ts

@@ -0,0 +1,204 @@
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { chmod, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import type { TunnelConfig } from '../config';
+import { createDesktopCapability } from './desktop';
+import { createEnabledCapabilityRegistry } from './enabled-registry';
+import { CuaDriver } from './desktop/cua-driver';
+import { createFilesystemCapability } from './filesystem';
+import { createShellCapability } from './shell';
+
+let root = '';
+let outside = '';
+
+function config(): TunnelConfig {
+  return {
+    token: 'kortix_tnl_test',
+    tunnelId: '00000000-0000-4000-8000-000000000000',
+    apiUrl: 'http://127.0.0.1:8008/v1/tunnel',
+    wsPath: '/ws',
+    maxFileSize: 1024,
+    allowedPaths: [root],
+    allowedCommands: [],
+    blockedCommands: [],
+    blockedPaths: [],
+    workingDir: root,
+    shellTimeout: 1_000,
+    shellMaxTimeout: 2_000,
+    shellMaxOutputSize: 1024,
+    shellEnvPassthrough: ['PATH'],
+  };
+}
+
+beforeEach(async () => {
+  root = await mkdtemp(join(tmpdir(), 'agent-tunnel-allowed-'));
+  outside = await mkdtemp(join(tmpdir(), 'agent-tunnel-outside-'));
+  await writeFile(join(root, 'allowed.txt'), 'allowed');
+  await writeFile(join(outside, 'secret.txt'), 'secret');
+});
+
+afterEach(async () => {
+  await Promise.all([
+    rm(root, { recursive: true, force: true }),
+    rm(outside, { recursive: true, force: true }),
+  ]);
+});
+
+describe('local capability permission enforcement', () => {
+  test('a zero-capability approval registers no local RPC handlers', () => {
+    const registry = createEnabledCapabilityRegistry({
+      ...config(),
+      enabledCapabilities: [],
+    });
+    expect(registry.getCapabilityNames()).toEqual([]);
+    expect(registry.getHandler('fs.read')).toBeNull();
+    expect(registry.getHandler('shell.exec')).toBeNull();
+    expect(registry.getHandler('desktop.cua.call')).toBeNull();
+  });
+
+  test('desktop is not advertised when no trusted local driver exists', () => {
+    const registry = createEnabledCapabilityRegistry(
+      { ...config(), enabledCapabilities: ['desktop'] },
+      () => null,
+    );
+    expect(registry.getCapabilityNames()).toEqual([]);
+    expect(registry.getHandler('desktop.cua.get_screen_size')).toBeNull();
+  });
+
+  test('desktop is advertised when a trusted local driver exists', () => {
+    const registry = createEnabledCapabilityRegistry(
+      { ...config(), enabledCapabilities: ['desktop'] },
+      () => '/trusted/cua-driver',
+    );
+    expect(registry.getCapabilityNames()).toEqual(['desktop']);
+    expect(registry.getHandler('desktop.cua.get_screen_size')).not.toBeNull();
+  });
+  test('a permission scope cannot widen the local filesystem ceiling', async () => {
+    const handler = createFilesystemCapability(config()).methods.get('fs.read')!;
+    await expect(
+      handler({
+        path: join(outside, 'secret.txt'),
+        __permission: {
+          permissionId: 'permission-1',
+          capability: 'filesystem',
+          scope: { paths: [outside], operations: ['read'] },
+        },
+      }),
+    ).rejects.toThrow('outside allowed directories');
+  });
+
+  test('filesystem operations are checked again on the machine', async () => {
+    const handler = createFilesystemCapability(config()).methods.get('fs.read')!;
+    await expect(
+      handler({
+        path: join(root, 'allowed.txt'),
+        __permission: {
+          permissionId: 'permission-1',
+          capability: 'filesystem',
+          scope: { operations: ['write'] },
+        },
+      }),
+    ).rejects.toThrow('operation "read" is not allowed');
+  });
+
+  test('shell command and working-directory scopes are checked on the machine', async () => {
+    const handler = createShellCapability(config()).methods.get('shell.exec')!;
+    await expect(
+      handler({
+        command: 'node',
+        args: ['--version'],
+        cwd: outside,
+        __permission: {
+          permissionId: 'permission-1',
+          capability: 'shell',
+          scope: { commands: ['node'], workingDir: root },
+        },
+      }),
+    ).rejects.toThrow('outside allowed directories');
+  });
+
+  test('disjoint local and permission command allowlists fail closed', async () => {
+    const handler = createShellCapability({ ...config(), allowedCommands: ['node'] }).methods.get(
+      'shell.exec',
+    )!;
+    await expect(
+      handler({
+        command: 'sh',
+        args: ['-c', 'echo must-not-run'],
+        __permission: {
+          permissionId: 'permission-1',
+          capability: 'shell',
+          scope: { commands: ['sh'] },
+        },
+      }),
+    ).rejects.toThrow('not in the allowed commands list');
+  });
+
+  test('desktop feature scopes deny before invoking cua-driver', async () => {
+    const handler = createDesktopCapability().methods.get('desktop.cua.click')!;
+    await expect(
+      handler({
+        x: 10,
+        y: 10,
+        __permission: {
+          permissionId: 'permission-1',
+          capability: 'desktop',
+          scope: { features: ['screenshot'] },
+        },
+      }),
+    ).rejects.toThrow('desktop feature "mouse" is not allowed');
+  });
+
+  test('remote desktop calls cannot trigger mutable installer or update tools', async () => {
+    const capability = createDesktopCapability();
+    expect(capability.methods.has('desktop.cua.check_for_update')).toBe(false);
+    expect(capability.methods.has('desktop.cua.install_ffmpeg')).toBe(false);
+
+    const call = capability.methods.get('desktop.cua.call')!;
+    await expect(
+      call({
+        tool: 'check_for_update',
+        __permission: {
+          permissionId: 'permission-1',
+          capability: 'desktop',
+          scope: { features: ['computer_use'] },
+        },
+      }),
+    ).rejects.toThrow('local-only');
+  });
+
+  test('cua-driver receives neither tunnel environment secrets nor internal permission data', async () => {
+    if (process.platform === 'win32') return;
+    const binary = join(root, 'fake-cua-driver');
+    await writeFile(
+      binary,
+      [
+        '#!/usr/bin/env node',
+        'process.stdout.write(JSON.stringify({',
+        '  token: process.env.TUNNEL_TOKEN ?? null,',
+        '  args: process.argv.slice(2),',
+        '}));',
+      ].join('\n'),
+    );
+    await chmod(binary, 0o700);
+    const previousBinary = process.env.CUA_DRIVER_BIN;
+    const previousToken = process.env.TUNNEL_TOKEN;
+    process.env.CUA_DRIVER_BIN = binary;
+    process.env.TUNNEL_TOKEN = 'must-not-leak';
+
+    try {
+      const result = (await new CuaDriver().call('click', {
+        x: 1,
+        __permission: { permissionId: 'private-permission-id' },
+      })) as { token: string | null; args: string[] };
+      expect(result.token).toBeNull();
+      expect(result.args.join(' ')).not.toContain('private-permission-id');
+    } finally {
+      if (previousBinary === undefined) delete process.env.CUA_DRIVER_BIN;
+      else process.env.CUA_DRIVER_BIN = previousBinary;
+      if (previousToken === undefined) delete process.env.TUNNEL_TOKEN;
+      else process.env.TUNNEL_TOKEN = previousToken;
+    }
+  });
+});

package/src/agent/capabilities/shell.ts

@@ -13,6 +13,21 @@ import type { Capability, RpcHandler } from './index';
 import { validateCommand } from '../security/command-validator';
 import { validatePath } from '../security/path-validator';
 import type { TunnelConfig } from '../config';
+import type { LocalPermission } from '../security/permission-guard';
+
+interface LocalShellScope {
+  commands?: string[];
+  workingDir?: string;
+  maxTimeout?: number;
+}
+
+function permissionShellScope(params: Record<string, unknown>): LocalShellScope {
+  const permission = params.__permission as LocalPermission | undefined;
+  if (permission?.capability !== 'shell') {
+    throw new Error('Permission denied: shell permission required');
+  }
+  return (permission.scope ?? {}) as LocalShellScope;
+}
 
 export function createShellCapability(config: TunnelConfig): Capability {
   const methods = new Map<string, RpcHandler>();
@@ -20,16 +35,35 @@ export function createShellCapability(config: TunnelConfig): Capability {
   methods.set('shell.exec', async (params) => {
     const command = params.command as string;
     const args = (params.args as string[]) || [];
+    if (!Array.isArray(args) || !args.every((arg) => typeof arg === 'string')) {
+      throw new Error('Command args must be an array of strings');
+    }
+    const scope = permissionShellScope(params);
     const cwd = (params.cwd as string) || config.workingDir;
+    const requestedTimeout =
+      params.timeout === undefined ? config.shellTimeout : Number(params.timeout);
+    if (!Number.isFinite(requestedTimeout) || requestedTimeout <= 0) {
+      throw new Error('Command timeout must be a positive number');
+    }
     const timeout = Math.min(
-      (params.timeout as number) || config.shellTimeout,
+      requestedTimeout,
       config.shellMaxTimeout,
+      typeof scope.maxTimeout === 'number' ? scope.maxTimeout : config.shellMaxTimeout,
     );
 
-    validateCommand(command, config.allowedCommands, config.blockedCommands);
+    const scopedCommands = Array.isArray(scope.commands)
+      ? scope.commands.filter((value): value is string => typeof value === 'string')
+      : [];
+    const executable = validateCommand(command, config.allowedCommands, config.blockedCommands);
+    if (scopedCommands.length > 0) {
+      validateCommand(executable, scopedCommands, []);
+    }
 
     if (cwd) {
       validatePath(cwd, config.allowedPaths, config.blockedPaths);
+      if (typeof scope.workingDir === 'string' && scope.workingDir.length > 0) {
+        validatePath(cwd, [scope.workingDir], config.blockedPaths);
+      }
     }
 
     const safeEnv: Record<string, string> = { TERM: 'dumb' };
@@ -40,7 +74,7 @@ export function createShellCapability(config: TunnelConfig): Capability {
     }
 
     return new Promise((resolve, reject) => {
-      const proc = spawn(command, args, {
+      const proc = spawn(executable, args, {
         cwd,
         shell: false,
         timeout,

package/src/agent/cli-device-auth.test.ts

@@ -0,0 +1,179 @@
+import { afterEach, describe, expect, test } from 'bun:test';
+import { spawn, type ChildProcess } from 'node:child_process';
+import { access, mkdtemp, readFile, rm, stat } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+
+const CLI_PATH = resolve(import.meta.dir, 'cli.ts');
+const children = new Set<ChildProcess>();
+const temporaryHomes = new Set<string>();
+
+afterEach(async () => {
+  for (const child of children) child.kill('SIGTERM');
+  children.clear();
+  await Promise.all(
+    [...temporaryHomes].map((path) => rm(path, { recursive: true, force: true })),
+  );
+  temporaryHomes.clear();
+});
+
+async function waitForFile(path: string, timeoutMs = 5_000): Promise<void> {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    try {
+      await stat(path);
+      return;
+    } catch {
+      await Bun.sleep(20);
+    }
+  }
+  throw new Error(`Timed out waiting for ${path}`);
+}
+
+describe('agent tunnel device authorization CLI', () => {
+  test('persists the exact browser-approved capability list as the local ceiling', async () => {
+    const approvedCapabilities = ['desktop', 'filesystem'];
+    const server = Bun.serve({
+      port: 0,
+      fetch(request) {
+        const url = new URL(request.url);
+        if (request.method === 'POST' && url.pathname === '/v1/tunnel/device-auth') {
+          return Response.json(
+            {
+              deviceCode: 'TEST-0001',
+              deviceSecret: 'ABCDEFGHIJKLMNOPQRSTUVWXYZ123456',
+              verificationUrl: 'https://dev.kortix.com/tunnel/authorize/TEST-0001',
+              expiresAt: new Date(Date.now() + 60_000).toISOString(),
+              pollIntervalMs: 250,
+            },
+            { status: 201 },
+          );
+        }
+        if (request.method === 'GET' && url.pathname.endsWith('/TEST-0001/status')) {
+          expect(request.headers.get('authorization')).toBe(
+            'Bearer ABCDEFGHIJKLMNOPQRSTUVWXYZ123456',
+          );
+          return Response.json({
+            status: 'approved',
+            tunnelId: '00000000-0000-4000-8000-000000000001',
+            token: 'kortix_tnl_ABCDEFGHIJKLMNOPQRSTUVWXYZ123456',
+            capabilities: approvedCapabilities,
+          });
+        }
+        return new Response('not found', { status: 404 });
+      },
+    });
+
+    const temporaryHome = await mkdtemp(join(tmpdir(), 'agent-tunnel-cli-home-'));
+    temporaryHomes.add(temporaryHome);
+    const child = spawn(
+      process.execPath,
+      [
+        'run',
+        CLI_PATH,
+        'connect',
+        '--foreground',
+        '--api-url',
+        `http://127.0.0.1:${server.port}/v1/tunnel`,
+      ],
+      {
+        env: {
+          ...process.env,
+          HOME: temporaryHome,
+          KORTIX_AGENT_TUNNEL_NO_BROWSER: '1',
+        },
+        stdio: ['ignore', 'pipe', 'pipe'],
+      },
+    );
+    children.add(child);
+
+    try {
+      const configPath = join(temporaryHome, '.agent-tunnel', 'config.json');
+      await waitForFile(configPath);
+      const config = JSON.parse(await readFile(configPath, 'utf8')) as {
+        enabledCapabilities?: string[];
+      };
+      expect(config.enabledCapabilities).toEqual(approvedCapabilities);
+      expect((await stat(configPath)).mode & 0o077).toBe(0);
+    } finally {
+      child.kill('SIGTERM');
+      children.delete(child);
+      server.stop(true);
+    }
+  });
+
+  test('rejects malformed credentials returned by the authorization server', async () => {
+    let approvedResponseSent!: () => void;
+    const responseSent = new Promise<void>((resolve) => {
+      approvedResponseSent = resolve;
+    });
+    const server = Bun.serve({
+      port: 0,
+      fetch(request) {
+        const url = new URL(request.url);
+        if (request.method === 'POST' && url.pathname === '/v1/tunnel/device-auth') {
+          return Response.json(
+            {
+              deviceCode: 'TEST-0002',
+              deviceSecret: 'ABCDEFGHIJKLMNOPQRSTUVWXYZ123456',
+              verificationUrl: 'https://dev.kortix.com/tunnel/authorize/TEST-0002',
+              expiresAt: new Date(Date.now() + 60_000).toISOString(),
+              pollIntervalMs: 250,
+            },
+            { status: 201 },
+          );
+        }
+        if (request.method === 'GET' && url.pathname.endsWith('/TEST-0002/status')) {
+          approvedResponseSent();
+          return Response.json({
+            status: 'approved',
+            tunnelId: 'not-a-uuid',
+            token: 'kortix_tnl_invalid\ncredential',
+            capabilities: ['desktop'],
+          });
+        }
+        return new Response('not found', { status: 404 });
+      },
+    });
+
+    const temporaryHome = await mkdtemp(join(tmpdir(), 'agent-tunnel-cli-home-'));
+    temporaryHomes.add(temporaryHome);
+    const configPath = join(temporaryHome, '.agent-tunnel', 'config.json');
+    const child = spawn(
+      process.execPath,
+      [
+        'run',
+        CLI_PATH,
+        'connect',
+        '--foreground',
+        '--api-url',
+        `http://127.0.0.1:${server.port}/v1/tunnel`,
+      ],
+      {
+        env: {
+          ...process.env,
+          HOME: temporaryHome,
+          KORTIX_AGENT_TUNNEL_NO_BROWSER: '1',
+        },
+        stdio: ['ignore', 'pipe', 'pipe'],
+      },
+    );
+    children.add(child);
+    let stderr = '';
+    child.stderr?.on('data', (chunk) => {
+      stderr += String(chunk);
+    });
+    const exitCode = new Promise<number | null>((resolve) => child.once('exit', resolve));
+
+    try {
+      await responseSent;
+      expect(await Promise.race([exitCode, Bun.sleep(2_000).then(() => -1)])).toBe(1);
+      await expect(access(configPath)).rejects.toThrow();
+      expect(stderr).toContain('invalid tunnel ID');
+    } finally {
+      child.kill('SIGTERM');
+      children.delete(child);
+      server.stop(true);
+    }
+  });
+});

package/src/agent/cli-help.test.ts

@@ -0,0 +1,25 @@
+import { describe, expect, test } from 'bun:test';
+import { spawnSync } from 'child_process';
+import { resolve } from 'path';
+
+const CLI_PATH = resolve(import.meta.dir, 'cli.ts');
+
+describe('agent tunnel service UX', () => {
+  test('offers persistent daemon mode without an unsupported keep-awake flag', () => {
+    const result = spawnSync('bun', ['run', CLI_PATH, 'help'], { encoding: 'utf8' });
+
+    expect(result.status).toBe(0);
+    expect(result.stdout).toContain('--daemon');
+    expect(result.stdout).toContain('--foreground');
+    expect(result.stdout).not.toContain('--keep-awake');
+  });
+
+  test('rejects the removed keep-awake flag instead of silently ignoring it', () => {
+    const result = spawnSync('bun', ['run', CLI_PATH, 'connect', '--keep-awake'], {
+      encoding: 'utf8',
+    });
+
+    expect(result.status).toBe(2);
+    expect(result.stderr).toContain('--keep-awake is not supported');
+  });
+});