@kortix/agent-tunnel 0.1.4 → 0.12.7

package/src/agent/config.test.ts

@@ -0,0 +1,53 @@
+import { afterEach, beforeEach, describe, expect, it } from 'bun:test';
+
+import { loadConfig } from './config';
+
+const ENV_KEYS = ['TUNNEL_API_URL', 'TUNNEL_WS_PATH'] as const;
+
+let saved: Record<string, string | undefined>;
+
+beforeEach(() => {
+  saved = {};
+  for (const key of ENV_KEYS) {
+    saved[key] = process.env[key];
+    delete process.env[key];
+  }
+});
+
+afterEach(() => {
+  for (const key of ENV_KEYS) {
+    if (saved[key] === undefined) delete process.env[key];
+    else process.env[key] = saved[key];
+  }
+});
+
+describe('loadConfig', () => {
+  it('does not let undefined overrides clear defaults or env config', () => {
+    process.env.TUNNEL_API_URL = 'https://relay.example/api?debug=1#token';
+    const config = loadConfig({ apiUrl: undefined });
+
+    expect(config.apiUrl).toBe('https://relay.example/api');
+  });
+
+  it('rejects non-http API URLs before network use', () => {
+    expect(() => loadConfig({ apiUrl: 'file:///tmp/config.json' })).toThrow(
+      'Invalid tunnel API URL protocol',
+    );
+  });
+
+  it('rejects plaintext HTTP for remote tunnel APIs', () => {
+    expect(() => loadConfig({ apiUrl: 'http://relay.example/v1/tunnel' })).toThrow(
+      'Remote tunnel API URLs must use https',
+    );
+    expect(loadConfig({ apiUrl: 'http://127.0.0.1:8008/v1/tunnel' }).apiUrl).toBe(
+      'http://127.0.0.1:8008/v1/tunnel',
+    );
+  });
+
+  it('requires the websocket path to be an absolute path', () => {
+    expect(loadConfig({ wsPath: '/relay/ws' }).wsPath).toBe('/relay/ws');
+    expect(() => loadConfig({ wsPath: 'https://relay.example/ws' })).toThrow(
+      'Tunnel WebSocket path must be an absolute path',
+    );
+  });
+});

package/src/agent/config.ts

@@ -1,6 +1,8 @@
-import { existsSync, readFileSync } from 'fs';
+import { chmodSync, existsSync, lstatSync, readFileSync } from 'fs';
 import { join } from 'path';
 import { homedir } from 'os';
+import { isTunnelCapability } from '../shared/permissions';
+import type { TunnelCapability } from '../shared/types';
 
 export interface TunnelConfig {
   token: string;
@@ -17,6 +19,8 @@ export interface TunnelConfig {
   shellMaxTimeout: number;
   shellMaxOutputSize: number;
   shellEnvPassthrough: string[];
+  /** Local maximum. An API permission cannot enable a capability outside this set. */
+  enabledCapabilities?: TunnelCapability[];
 }
 
 const CONFIG_DIR = join(homedir(), '.agent-tunnel');
@@ -43,16 +47,169 @@ const DEFAULTS: Partial<TunnelConfig> = {
   shellTimeout: 30_000,
   shellMaxTimeout: 120_000,
   shellMaxOutputSize: 1024 * 1024,
-  shellEnvPassthrough: ['PATH', 'HOME', 'USER', 'LANG', 'LC_ALL', 'LC_CTYPE', 'TMPDIR', 'NODE_ENV', 'HOSTNAME'],
+  shellEnvPassthrough: [
+    'PATH',
+    'HOME',
+    'USER',
+    'LANG',
+    'LC_ALL',
+    'LC_CTYPE',
+    'TMPDIR',
+    'NODE_ENV',
+    'HOSTNAME',
+  ],
+  // Compatibility for existing configs. New device-auth connections persist
+  // the exact capability set that the user approved in the browser.
+  enabledCapabilities: ['filesystem', 'shell', 'desktop'],
 };
 
+function compactConfig(input: Partial<TunnelConfig>): Partial<TunnelConfig> {
+  const output: Partial<TunnelConfig> = {};
+  for (const [key, value] of Object.entries(input)) {
+    if (value !== undefined) {
+      (output as Record<string, unknown>)[key] = value;
+    }
+  }
+  return output;
+}
+
+function assertPrivateOwnedPath(
+  path: string,
+  kind: 'directory' | 'file',
+  expectedMode: number,
+): void {
+  const stats = lstatSync(path);
+  const validType = kind === 'directory' ? stats.isDirectory() : stats.isFile();
+  if (stats.isSymbolicLink() || !validType) {
+    throw new Error(`Tunnel config ${kind} must be a regular ${kind}, not a symlink`);
+  }
+  if (
+    typeof process.getuid === 'function' &&
+    typeof stats.uid === 'number' &&
+    stats.uid !== process.getuid()
+  ) {
+    throw new Error(`Tunnel config ${kind} is not owned by the current user`);
+  }
+  if (process.platform !== 'win32') {
+    try {
+      chmodSync(path, expectedMode);
+    } catch (error) {
+      throw new Error(
+        `Cannot secure tunnel config ${kind}: ${error instanceof Error ? error.message : error}`,
+      );
+    }
+    const secured = lstatSync(path);
+    if ((secured.mode & 0o077) !== 0) {
+      throw new Error(`Tunnel config ${kind} permissions are not private`);
+    }
+  }
+}
+
+function assertStringArray(value: unknown, name: string): asserts value is string[] {
+  if (!Array.isArray(value) || !value.every((item) => typeof item === 'string')) {
+    throw new Error(`Tunnel config ${name} must be an array of strings`);
+  }
+}
+
+function validateConfigValues(config: TunnelConfig): void {
+  assertStringArray(config.allowedPaths, 'allowedPaths');
+  assertStringArray(config.allowedCommands, 'allowedCommands');
+  assertStringArray(config.blockedCommands, 'blockedCommands');
+  assertStringArray(config.blockedPaths, 'blockedPaths');
+  assertStringArray(config.shellEnvPassthrough, 'shellEnvPassthrough');
+  if (config.enabledCapabilities !== undefined) {
+    assertStringArray(config.enabledCapabilities, 'enabledCapabilities');
+    if (
+      new Set(config.enabledCapabilities).size !== config.enabledCapabilities.length ||
+      !config.enabledCapabilities.every(isTunnelCapability)
+    ) {
+      throw new Error(
+        'Tunnel config enabledCapabilities must contain unique supported capabilities',
+      );
+    }
+  }
+
+  for (const [name, value] of [
+    ['maxFileSize', config.maxFileSize],
+    ['shellTimeout', config.shellTimeout],
+    ['shellMaxTimeout', config.shellMaxTimeout],
+    ['shellMaxOutputSize', config.shellMaxOutputSize],
+  ] as const) {
+    if (!Number.isSafeInteger(value) || value <= 0) {
+      throw new Error(`Tunnel config ${name} must be a positive safe integer`);
+    }
+  }
+  if (typeof config.workingDir !== 'string' || config.workingDir.length === 0) {
+    throw new Error('Tunnel config workingDir must be a non-empty string');
+  }
+}
+
+export function trustedCredential(value: string, name: string): string {
+  if (!value || /[\r\n]/.test(value)) {
+    throw new Error(`Invalid tunnel ${name}`);
+  }
+  return value;
+}
+
+export function trustedHttpUrl(value: string): string {
+  const raw = trustedCredential(value, 'apiUrl');
+  const url = new URL(raw);
+  if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+    throw new Error('Tunnel API URL must use http or https');
+  }
+  assertEncryptedOrLoopback(url);
+  return url.toString().replace(/\/$/, '');
+}
+
+function assertEncryptedOrLoopback(url: URL): void {
+  const loopback =
+    url.hostname === 'localhost' ||
+    url.hostname === '127.0.0.1' ||
+    url.hostname === '[::1]' ||
+    url.hostname === '::1';
+  if (url.protocol !== 'https:' && !loopback) {
+    throw new Error('Remote tunnel API URLs must use https');
+  }
+}
+
+export function normalizeApiUrl(value: string): string {
+  const raw = trustedCredential(value, 'apiUrl');
+  let url: URL;
+  try {
+    url = new URL(raw);
+  } catch {
+    throw new Error('Invalid tunnel API URL protocol');
+  }
+  if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+    throw new Error('Invalid tunnel API URL protocol');
+  }
+  assertEncryptedOrLoopback(url);
+  return `${url.origin}${url.pathname}`.replace(/\/$/, '');
+}
+
+export function absoluteWsPath(value: string): string {
+  if (!value.startsWith('/')) {
+    throw new Error('Tunnel WebSocket path must be an absolute path');
+  }
+  return value;
+}
+
 export function loadConfig(overrides: Partial<TunnelConfig> = {}): TunnelConfig {
   let fileConfig: Partial<TunnelConfig> = {};
   if (existsSync(CONFIG_FILE)) {
+    if (!existsSync(CONFIG_DIR)) throw new Error('Tunnel config directory is missing');
+    assertPrivateOwnedPath(CONFIG_DIR, 'directory', 0o700);
+    assertPrivateOwnedPath(CONFIG_FILE, 'file', 0o600);
     try {
-      fileConfig = JSON.parse(readFileSync(CONFIG_FILE, 'utf-8'));
+      const parsed = JSON.parse(readFileSync(CONFIG_FILE, 'utf-8'));
+      if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new Error('root value must be an object');
+      }
+      fileConfig = parsed;
     } catch (err) {
-      console.warn(`[config] Failed to parse ${CONFIG_FILE}:`, err);
+      throw new Error(
+        `Tunnel config is invalid: ${err instanceof Error ? err.message : String(err)}`,
+      );
     }
   }
 
@@ -61,14 +218,19 @@ export function loadConfig(overrides: Partial<TunnelConfig> = {}): TunnelConfig
   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);
+  if (process.env.TUNNEL_MAX_FILE_SIZE)
+    envConfig.maxFileSize = parseInt(process.env.TUNNEL_MAX_FILE_SIZE, 10);
 
   const merged = {
     ...DEFAULTS,
-    ...fileConfig,
+    ...compactConfig(fileConfig),
     ...envConfig,
-    ...overrides,
+    ...compactConfig(overrides),
   } as TunnelConfig;
 
+  merged.apiUrl = normalizeApiUrl(merged.apiUrl);
+  merged.wsPath = absoluteWsPath(merged.wsPath);
+  validateConfigValues(merged);
+
   return merged;
 }

package/src/agent/index.ts

@@ -5,6 +5,7 @@ export type { Capability, RpcHandler } from './capabilities/index';
 export { createFilesystemCapability } from './capabilities/filesystem';
 export { createShellCapability } from './capabilities/shell';
 export { createDesktopCapability } from './capabilities/desktop';
+export { createEnabledCapabilityRegistry } from './capabilities/enabled-registry';
 export { PermissionGuard } from './security/permission-guard';
 export type { LocalPermission } from './security/permission-guard';
 export { validateCommand } from './security/command-validator';

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

@@ -4,7 +4,7 @@ export function validateCommand(
   command: string,
   allowedCommands: string[],
   blockedCommands: string[],
-): void {
+): string {
   if (!command || typeof command !== 'string') {
     throw new Error('Command is required');
   }
@@ -15,7 +15,7 @@ export function validateCommand(
     throw new Error(`Command contains disallowed characters: "${trimmed}"`);
   }
 
-  const executable = trimmed.split(/\s+/)[0];
+  const executable = trimmed;
 
   if (blockedCommands.length > 0 && blockedCommands.includes(executable)) {
     throw new Error(`Command "${executable}" is blocked`);
@@ -26,4 +26,6 @@ export function validateCommand(
       throw new Error(`Command "${executable}" is not in the allowed commands list`);
     }
   }
+
+  return executable;
 }

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

@@ -8,45 +8,100 @@
  *   4. Don't hit blocked paths (configurable)
  */
 
-import { resolve, normalize } from 'path';
+import { dirname, basename, join, resolve, normalize, relative, isAbsolute } from 'path';
 import { realpathSync } from 'fs';
 
-export function validatePath(
-  path: string,
-  allowedPaths: string[],
-  blockedPaths: string[] = [],
-): void {
-  if (!path) {
-    throw new Error('Path is required');
+function resolveExistingRoot(path: string): string {
+  const normalized = normalize(resolve(path));
+  try {
+    return realpathSync(normalized);
+  } catch {
+    return normalized;
   }
+}
 
+function resolvePathForValidation(path: string): string {
   const normalized = normalize(resolve(path));
-  let resolved: string;
   try {
-    resolved = realpathSync(normalized);
+    return realpathSync(normalized);
   } catch (err) {
     const code = (err as NodeJS.ErrnoException).code;
-    if (code === 'ENOENT') {
-      resolved = normalized;
-    } else {
+    if (code !== 'ENOENT') {
       throw new Error(`Access denied: cannot resolve path "${path}" (${code})`);
     }
+
+    const parent = dirname(normalized);
+    if (parent === normalized) return normalized;
+    return join(resolvePathForValidation(parent), basename(normalized));
   }
+}
 
+function assertAllowedResolvedPath(
+  originalPath: string,
+  resolved: string,
+  allowedPaths: string[],
+  blockedPaths: string[] = [],
+): void {
   for (const blocked of blockedPaths) {
-    if (resolved === blocked || resolved.startsWith(blocked + '/')) {
-      throw new Error(`Access denied: blocked path "${path}"`);
+    const normalizedBlocked = resolveExistingRoot(blocked);
+    if (isPathInside(resolved, normalizedBlocked)) {
+      throw new Error(`Access denied: blocked path "${originalPath}"`);
     }
   }
 
   if (allowedPaths.length > 0) {
     const withinAllowed = allowedPaths.some((allowed) => {
-      const normalizedAllowed = normalize(resolve(allowed));
-      return resolved === normalizedAllowed || resolved.startsWith(normalizedAllowed + '/');
+      const normalizedAllowed = resolveExistingRoot(allowed);
+      return isPathInside(resolved, normalizedAllowed);
     });
 
     if (!withinAllowed) {
-      throw new Error(`Access denied: path "${path}" is outside allowed directories`);
+      throw new Error(`Access denied: path "${originalPath}" is outside allowed directories`);
     }
   }
 }
+
+function isPathInside(target: string, root: string): boolean {
+  const child = relative(root, target);
+  return child === '' || (!child.startsWith('..') && !isAbsolute(child));
+}
+
+export function validatePath(
+  path: string,
+  allowedPaths: string[],
+  blockedPaths: string[] = [],
+): string {
+  if (!path) {
+    throw new Error('Path is required');
+  }
+
+  const resolved = resolvePathForValidation(path);
+
+  assertAllowedResolvedPath(path, resolved, allowedPaths, blockedPaths);
+  return resolved;
+}
+
+export function validateWritePath(
+  path: string,
+  allowedPaths: string[],
+  blockedPaths: string[] = [],
+): string {
+  const resolved = validatePath(path, allowedPaths, blockedPaths);
+
+  let parent = dirname(normalize(resolve(path)));
+  while (parent && parent !== dirname(parent)) {
+    try {
+      const resolvedParent = realpathSync(parent);
+      assertAllowedResolvedPath(path, resolvedParent, allowedPaths, blockedPaths);
+      return resolved;
+    } catch (err) {
+      const code = (err as NodeJS.ErrnoException).code;
+      if (code !== 'ENOENT') {
+        throw new Error(`Access denied: cannot resolve parent for "${path}" (${code})`);
+      }
+      parent = dirname(parent);
+    }
+  }
+
+  throw new Error(`Access denied: cannot resolve parent for "${path}"`);
+}

package/src/agent/security/permission-guard.test.ts

@@ -0,0 +1,52 @@
+import { describe, expect, test } from 'bun:test';
+import { PermissionGuard } from './permission-guard';
+
+describe('PermissionGuard method binding', () => {
+  test('does not let a valid permission id authorize another capability', () => {
+    const guard = new PermissionGuard();
+    guard.addPermission({
+      permissionId: 'filesystem-permission',
+      capability: 'filesystem',
+      scope: {},
+    });
+
+    expect(guard.getPermissionForMethod('filesystem-permission', 'fs.read')).not.toBeNull();
+    expect(guard.getPermissionForMethod('filesystem-permission', 'shell.exec')).toBeNull();
+    expect(guard.getPermissionForMethod('filesystem-permission', 'desktop.cua.click')).toBeNull();
+  });
+
+  test('unknown methods fail closed', () => {
+    const guard = new PermissionGuard();
+    guard.addPermission({
+      permissionId: 'filesystem-permission',
+      capability: 'filesystem',
+      scope: {},
+    });
+    expect(guard.getPermissionForMethod('filesystem-permission', 'fs.unknown')).toBeNull();
+  });
+
+  test('malformed server scopes fail closed on the machine', () => {
+    const guard = new PermissionGuard();
+    guard.syncPermissions([
+      {
+        permissionId: 'empty-commands',
+        capability: 'shell',
+        scope: { commands: [] },
+      },
+      {
+        permissionId: 'unknown-field',
+        capability: 'filesystem',
+        scope: { path: '/tmp/secret' },
+      },
+      {
+        permissionId: 'invalid-timeout',
+        capability: 'shell',
+        scope: { maxTimeout: Number.NaN },
+      },
+    ]);
+
+    expect(guard.getPermissionForMethod('empty-commands', 'shell.exec')).toBeNull();
+    expect(guard.getPermissionForMethod('unknown-field', 'fs.read')).toBeNull();
+    expect(guard.getPermissionForMethod('invalid-timeout', 'shell.exec')).toBeNull();
+  });
+});

package/src/agent/security/permission-guard.ts

@@ -1,3 +1,9 @@
+import {
+  capabilityForMethod,
+  isTunnelCapability,
+  validateTunnelPermissionScope,
+} from '../../shared/permissions';
+
 /**
  * Permission Guard — local-side permission enforcement (defense in depth).
  *
@@ -18,18 +24,27 @@ export interface LocalPermission {
 
 export class PermissionGuard {
   private permissions = new Map<string, LocalPermission>();
-  private hasSynced = false;
 
   /** Bulk-load permissions from server sync notification. */
   syncPermissions(permissions: LocalPermission[]): void {
     this.permissions.clear();
     for (const perm of permissions) {
-      this.permissions.set(perm.permissionId, perm);
+      this.addPermission(perm);
     }
-    this.hasSynced = true;
   }
 
   addPermission(permission: LocalPermission): void {
+    if (
+      typeof permission?.permissionId !== 'string' ||
+      !permission.permissionId ||
+      !isTunnelCapability(permission.capability) ||
+      !validateTunnelPermissionScope(permission.capability, permission.scope).valid
+    ) {
+      if (typeof permission?.permissionId === 'string') {
+        this.permissions.delete(permission.permissionId);
+      }
+      return;
+    }
     this.permissions.set(permission.permissionId, permission);
   }
 
@@ -38,30 +53,42 @@ export class PermissionGuard {
   }
 
   checkPermission(permissionId: string | undefined): boolean {
+    return !!this.getPermission(permissionId);
+  }
+
+  getPermission(permissionId: string | undefined): LocalPermission | null {
     if (!permissionId) {
-      return false;
+      return null;
     }
 
     const perm = this.permissions.get(permissionId);
     if (!perm) {
       // After sync, unknown permission = deny (fail-closed).
       // Before sync, also deny — we have no basis to allow.
-      return false;
+      return null;
     }
 
     if (perm.expiresAt) {
       const expiry = new Date(perm.expiresAt).getTime();
       if (isNaN(expiry) || expiry < Date.now()) {
         this.permissions.delete(permissionId);
-        return false;
+        return null;
       }
     }
 
-    return true;
+    return perm;
+  }
+
+  getPermissionForMethod(permissionId: string | undefined, method: string): LocalPermission | null {
+    const permission = this.getPermission(permissionId);
+    const requiredCapability = capabilityForMethod(method);
+    if (!permission || !requiredCapability || permission.capability !== requiredCapability) {
+      return null;
+    }
+    return permission;
   }
 
   clear(): void {
     this.permissions.clear();
-    this.hasSynced = false;
   }
 }

package/src/agent/service.test.ts

@@ -0,0 +1,63 @@
+import { describe, expect, test } from 'bun:test';
+import {
+  DEFAULT_INSTALL_BACKGROUND_SERVICE,
+  SERVICE_LABEL,
+  buildServiceShellCommand,
+  getServicePaths,
+  renderLaunchdPlist,
+  renderSystemdUnit,
+  renderWindowsPowerShellScript,
+} from './service';
+
+describe('agent tunnel service definitions', () => {
+  test('defaults the interactive connection flow to the background service', () => {
+    expect(DEFAULT_INSTALL_BACKGROUND_SERVICE).toBe(true);
+  });
+
+  test('builds a command that runs the supervised tunnel agent', () => {
+    const command = buildServiceShellCommand();
+    expect(command).toContain("'run'");
+    expect(command).toContain("'--service'");
+    expect(command).toStartWith('exec ');
+  });
+
+  test('launchd plist restarts and runs at login', () => {
+    const plist = renderLaunchdPlist('exec /bin/echo tunnel');
+    expect(plist).toContain(`<string>${SERVICE_LABEL}</string>`);
+    expect(plist).toContain('<key>RunAtLoad</key>');
+    expect(plist).toContain('<key>KeepAlive</key>');
+    expect(plist).toContain('<key>Umask</key>');
+    expect(plist).toContain('agent-tunnel.out.log');
+    expect(plist).toContain('agent-tunnel.err.log');
+  });
+
+  test('systemd unit restarts forever', () => {
+    const unit = renderSystemdUnit('exec /bin/echo tunnel');
+    expect(unit).toContain('Description=Kortix Agent Tunnel');
+    expect(unit).toContain('Restart=always');
+    expect(unit).toContain('UMask=0077');
+    expect(unit).toContain('WantedBy=default.target');
+    expect(unit).toContain('agent-tunnel.out.log');
+    expect(unit).toContain('agent-tunnel.err.log');
+  });
+
+  test('windows scheduled-task script restarts forever', () => {
+    const script = renderWindowsPowerShellScript({
+      command: 'node',
+      args: ['agent-tunnel.js', 'run', '--service'],
+    });
+    expect(script).not.toContain('SetThreadExecutionState');
+    expect(script).toContain('while ($true)');
+    expect(script).toContain("& 'node' 'agent-tunnel.js' 'run' '--service'");
+    expect(script).toContain('Start-Sleep -Seconds 5');
+  });
+
+  test('service paths are under the user home', () => {
+    const paths = getServicePaths();
+    expect(paths.configDir).toContain('.agent-tunnel');
+    expect(paths.logDir).toContain('.agent-tunnel');
+    expect(paths.launchdPlist).toContain(`${SERVICE_LABEL}.plist`);
+    expect(paths.systemdUnit).toContain(`${SERVICE_LABEL}.service`);
+    expect(paths.windowsScript).toContain('agent-tunnel-service.ps1');
+  });
+});