@kortix/agent-tunnel 0.1.0 → 0.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kortix/agent-tunnel",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "private": false,
   "type": "module",
   "description": "Tunnel relay between cloud AI agents and local machines — server relay, local agent, client SDK, JSON-RPC, HMAC signing",
@@ -11,10 +11,12 @@
     "./shared": "./src/shared/index.ts",
     "./server": "./src/server/index.ts",
     "./client": "./src/client/index.ts",
+    "./client/cli": "./src/client/cli.ts",
     "./agent": "./src/agent/index.ts"
   },
   "bin": {
-    "agent-tunnel": "src/agent/cli.ts"
+    "agent-tunnel": "src/agent/cli.ts",
+    "agent-tunnel-cli": "src/client/cli.ts"
   },
   "files": [
     "src/"

package/src/agent/agent.ts

@@ -3,7 +3,7 @@ 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';
+import { deriveSigningKey, signMessage, verifyMessageSignature } from '../shared/crypto';
 
 interface JsonRpcRequest {
   jsonrpc: '2.0';
@@ -56,6 +56,7 @@ export class TunnelAgent {
   // HMAC signature verification
   private signingKey: string;
   private lastNonce = 0;
+  private responseNonce = 0;
 
   constructor(config: TunnelConfig, registry: CapabilityRegistry) {
     this.config = config;
@@ -113,9 +114,13 @@ export class TunnelAgent {
     this.ws.addEventListener('open', () => {
       this.reconnectAttempts = 0;
       this.uptime = 0;
-      this.lastNonce = 0; // Reset nonce on each new connection
+      this.lastNonce = 0;
+      this.responseNonce = 0;
       this.uptimeInterval = setInterval(() => { this.uptime++; }, 1000);
 
+      // Send auth handshake as first message (token never in URL)
+      this.send({ type: 'auth', token: this.config.token });
+
       log(`${c.green}●${c.reset}`, `Connected ${c.reset}${c.gray}(${this.registry.getCapabilityNames().join(', ')})${c.reset}`);
     });
 
@@ -130,6 +135,10 @@ export class TunnelAgent {
       }
 
       if (!this.isShuttingDown) {
+        if (event.code === 4001) {
+          log(`${c.red}✗${c.reset}`, `Authentication failed — check your token`);
+          return; // Don't reconnect on auth failure
+        }
         log(`${c.yellow}○${c.reset}`, `Disconnected ${c.gray}(code: ${event.code})${c.reset}`);
         this.scheduleReconnect();
       }
@@ -149,20 +158,19 @@ export class TunnelAgent {
       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');
+        this.sendSignedError(msg.id, -32000, 'Invalid message signature');
       }
       return;
     }
 
+    // ── Heartbeat ping (signature verified above) ────────────────────
+    if ('method' in msg && msg.method === 'tunnel.ping') {
+      this.sendPong();
+      return;
+    }
+
     // ── Permission sync notification ────────────────────────────────
     if ('method' in msg && msg.method === 'tunnel.permissions.sync') {
       const permissions = (msg.params?.permissions || []) as LocalPermission[];
@@ -194,8 +202,6 @@ export class TunnelAgent {
     // ── 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;
     }
 
@@ -208,7 +214,6 @@ export class TunnelAgent {
 
   /**
    * 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;
@@ -219,13 +224,11 @@ export class TunnelAgent {
       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);
 
@@ -241,38 +244,65 @@ export class TunnelAgent {
   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'}`);
+      this.sendSignedError(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}`);
+      this.sendSignedError(id, -32001, `Capability not registered for method: ${method}`);
       return;
     }
 
     try {
       const result = await handler(params);
-      this.sendResult(id, result);
+      this.sendSignedResult(id, result);
     } catch (err) {
       const message = err instanceof Error ? err.message : String(err);
-      this.sendError(id, -32003, message);
+      this.sendSignedError(id, -32003, message);
     }
   }
 
-  private sendResult(id: string, result: unknown): void {
-    this.send({ jsonrpc: '2.0', id, result });
+  /** Send HMAC-signed RPC result. */
+  private sendSignedResult(id: string, result: unknown): void {
+    const data = { jsonrpc: '2.0' as const, id, result };
+    this.sendSigned(data);
   }
 
-  private sendError(id: string, code: number, message: string): void {
-    this.send({ jsonrpc: '2.0', id, error: { code, message } });
+  /** Send HMAC-signed RPC error. */
+  private sendSignedError(id: string, code: number, message: string): void {
+    const data = { jsonrpc: '2.0' as const, id, error: { code, message } };
+    this.sendSigned(data);
+  }
+
+  private sendSigned(data: Record<string, unknown>): void {
+    if (this.ws?.readyState === WebSocket.OPEN) {
+      const nonce = ++this.responseNonce;
+      const payload = JSON.stringify(data);
+      const sig = signMessage(this.signingKey, payload, nonce);
+      const signed = { ...data, _sig: sig, _nonce: nonce };
+      try {
+        this.ws.send(JSON.stringify(signed));
+      } catch (err) {
+        log(`${c.red}✗${c.reset}`, `Send failed`);
+      }
+    }
+  }
+
+  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 sendPong(): void {
-    this.send({
+    this.sendSigned({
       jsonrpc: '2.0',
       method: 'tunnel.pong',
       params: {
@@ -283,22 +313,12 @@ export class TunnelAgent {
           platform: platform(),
           arch: arch(),
           osVersion: release(),
-          agentVersion: '0.1.0',
+          agentVersion: '0.1.1',
         },
       },
     });
   }
 
-  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;
 
@@ -320,9 +340,12 @@ export class TunnelAgent {
       .replace(/^http:/, 'ws:')
       .replace(/^https:/, 'wss:');
 
+    if (base.startsWith('ws://') && !base.includes('localhost') && !base.includes('127.0.0.1')) {
+      log(`${c.red}!${c.reset}`, `${c.red}WARNING: Connecting over unencrypted ws:// to a remote host. Token will be sent in plaintext. Use https:// API URL for production.${c.reset}`);
+    }
+
     const wsPath = this.config.wsPath || '/ws';
     const params = new URLSearchParams({
-      token: this.config.token,
       tunnelId: this.config.tunnelId,
     });
 

package/src/agent/capabilities/filesystem.ts

@@ -18,15 +18,15 @@ export function createFilesystemCapability(config: TunnelConfig): Capability {
     const path = params.path as string;
     const encoding = (params.encoding as BufferEncoding) || 'utf-8';
 
-    validatePath(path, config.allowedPaths);
+    validatePath(path, config.allowedPaths, config.blockedPaths);
 
-    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})`);
     }
 
+    const content = await readFile(path, { encoding });
+
     return {
       content,
       size: stats.size,
@@ -40,7 +40,7 @@ export function createFilesystemCapability(config: TunnelConfig): Capability {
     const content = params.content as string;
     const encoding = (params.encoding as BufferEncoding) || 'utf-8';
 
-    validatePath(path, config.allowedPaths);
+    validatePath(path, config.allowedPaths, config.blockedPaths);
 
     if (content.length > config.maxFileSize) {
       throw new Error(`Content exceeds max size (${content.length} > ${config.maxFileSize})`);
@@ -62,7 +62,7 @@ export function createFilesystemCapability(config: TunnelConfig): Capability {
     const path = params.path as string;
     const recursive = params.recursive as boolean || false;
 
-    validatePath(path, config.allowedPaths);
+    validatePath(path, config.allowedPaths, config.blockedPaths);
 
     const entries = await readdir(path, { withFileTypes: true });
 
@@ -100,7 +100,7 @@ export function createFilesystemCapability(config: TunnelConfig): Capability {
   methods.set('fs.stat', async (params) => {
     const path = params.path as string;
 
-    validatePath(path, config.allowedPaths);
+    validatePath(path, config.allowedPaths, config.blockedPaths);
 
     const stats = await stat(path);
 
@@ -119,7 +119,7 @@ export function createFilesystemCapability(config: TunnelConfig): Capability {
   methods.set('fs.delete', async (params) => {
     const path = params.path as string;
 
-    validatePath(path, config.allowedPaths);
+    validatePath(path, config.allowedPaths, config.blockedPaths);
 
     await unlink(path);
 

package/src/agent/capabilities/shell.ts

@@ -3,8 +3,8 @@
  *
  * Security:
  *   - Commands are executed as array args (no shell interpolation)
- *   - First arg (executable) is validated against allowedCommands
- *   - Working directory is validated against allowedPaths
+ *   - First arg (executable) is validated against allowedCommands / blockedCommands
+ *   - Working directory is validated against allowedPaths / blockedPaths
  *   - Timeout enforcement
  */
 
@@ -14,9 +14,6 @@ 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>();
 
@@ -25,19 +22,18 @@ export function createShellCapability(config: TunnelConfig): Capability {
     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,
+      (params.timeout as number) || config.shellTimeout,
+      config.shellMaxTimeout,
     );
 
-    validateCommand(command, config.allowedCommands);
+    validateCommand(command, config.allowedCommands, config.blockedCommands);
 
     if (cwd) {
-      validatePath(cwd, config.allowedPaths);
+      validatePath(cwd, config.allowedPaths, config.blockedPaths);
     }
 
-    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) {
+    for (const key of config.shellEnvPassthrough) {
       if (process.env[key]) {
         safeEnv[key] = process.env[key]!;
       }
@@ -57,18 +53,32 @@ export function createShellCapability(config: TunnelConfig): Capability {
       let stderrTruncated = false;
 
       proc.stdout?.on('data', (data: Buffer) => {
-        if (stdout.length < MAX_OUTPUT_SIZE) {
-          stdout += data.toString();
-        } else {
+        if (stdout.length >= config.shellMaxOutputSize) {
           stdoutTruncated = true;
+          return;
+        }
+        const chunk = data.toString();
+        const remaining = config.shellMaxOutputSize - stdout.length;
+        if (chunk.length > remaining) {
+          stdout += chunk.slice(0, remaining);
+          stdoutTruncated = true;
+        } else {
+          stdout += chunk;
         }
       });
 
       proc.stderr?.on('data', (data: Buffer) => {
-        if (stderr.length < MAX_OUTPUT_SIZE) {
-          stderr += data.toString();
-        } else {
+        if (stderr.length >= config.shellMaxOutputSize) {
+          stderrTruncated = true;
+          return;
+        }
+        const chunk = data.toString();
+        const remaining = config.shellMaxOutputSize - stderr.length;
+        if (chunk.length > remaining) {
+          stderr += chunk.slice(0, remaining);
           stderrTruncated = true;
+        } else {
+          stderr += chunk;
         }
       });
 
@@ -80,8 +90,8 @@ export function createShellCapability(config: TunnelConfig): Capability {
         resolve({
           exitCode: code,
           signal,
-          stdout: stdout.slice(0, MAX_OUTPUT_SIZE),
-          stderr: stderr.slice(0, MAX_OUTPUT_SIZE),
+          stdout,
+          stderr,
           stdoutTruncated,
           stderrTruncated,
         });

package/src/agent/config.ts

@@ -6,12 +6,17 @@ 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[];
+  blockedCommands: string[];
+  blockedPaths: string[];
   workingDir: string;
+  shellTimeout: number;
+  shellMaxTimeout: number;
+  shellMaxOutputSize: number;
+  shellEnvPassthrough: string[];
 }
 
 const CONFIG_DIR = join(homedir(), '.agent-tunnel');
@@ -23,7 +28,22 @@ const DEFAULTS: Partial<TunnelConfig> = {
   maxFileSize: 10 * 1024 * 1024,
   allowedPaths: [homedir()],
   allowedCommands: [],
+  blockedCommands: [],
+  blockedPaths: [
+    '/etc/shadow',
+    '/etc/passwd',
+    '/etc/sudoers',
+    '/etc/ssh',
+    '/root/.ssh',
+    '/proc',
+    '/sys',
+    '/dev',
+  ],
   workingDir: homedir(),
+  shellTimeout: 30_000,
+  shellMaxTimeout: 120_000,
+  shellMaxOutputSize: 1024 * 1024,
+  shellEnvPassthrough: ['PATH', 'HOME', 'USER', 'LANG', 'LC_ALL', 'LC_CTYPE', 'TMPDIR', 'NODE_ENV', 'HOSTNAME'],
 };
 
 export function loadConfig(overrides: Partial<TunnelConfig> = {}): TunnelConfig {

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

@@ -1,42 +1,10 @@
-/**
- * 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 {
+export function validateCommand(
+  command: string,
+  allowedCommands: string[],
+  blockedCommands: string[],
+): void {
   if (!command || typeof command !== 'string') {
     throw new Error('Command is required');
   }
@@ -49,8 +17,8 @@ export function validateCommand(command: string, allowedCommands: string[]): voi
 
   const executable = trimmed.split(/\s+/)[0];
 
-  if (BLOCKED_COMMANDS.has(executable)) {
-    throw new Error(`Command "${executable}" is blocked for security reasons`);
+  if (blockedCommands.length > 0 && blockedCommands.includes(executable)) {
+    throw new Error(`Command "${executable}" is blocked`);
   }
 
   if (allowedCommands.length > 0) {

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

@@ -5,25 +5,17 @@
  *   1. Are absolute
  *   2. Resolve to an absolute path (follows symlinks)
  *   3. Fall within allowed directories
- *   4. Don't hit sensitive system paths
+ *   4. Don't hit blocked paths (configurable)
  */
 
 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 {
+export function validatePath(
+  path: string,
+  allowedPaths: string[],
+  blockedPaths: string[] = [],
+): void {
   if (!path) {
     throw new Error('Path is required');
   }
@@ -32,13 +24,18 @@ export function validatePath(path: string, allowedPaths: string[]): void {
   let resolved: string;
   try {
     resolved = realpathSync(normalized);
-  } catch {
-    resolved = normalized;
+  } catch (err) {
+    const code = (err as NodeJS.ErrnoException).code;
+    if (code === 'ENOENT') {
+      resolved = normalized;
+    } else {
+      throw new Error(`Access denied: cannot resolve path "${path}" (${code})`);
+    }
   }
 
-  for (const sensitive of SENSITIVE_PATHS) {
-    if (resolved === sensitive || resolved.startsWith(sensitive + '/')) {
-      throw new Error(`Access denied: sensitive system path "${path}"`);
+  for (const blocked of blockedPaths) {
+    if (resolved === blocked || resolved.startsWith(blocked + '/')) {
+      throw new Error(`Access denied: blocked path "${path}"`);
     }
   }
 

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

@@ -50,7 +50,8 @@ export class PermissionGuard {
     }
 
     if (perm.expiresAt) {
-      if (new Date(perm.expiresAt) < new Date()) {
+      const expiry = new Date(perm.expiresAt).getTime();
+      if (isNaN(expiry) || expiry < Date.now()) {
         this.permissions.delete(permissionId);
         return false;
       }