@kortix/agent-tunnel 0.1.0 → 0.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kortix/agent-tunnel",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "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 { signMessage, verifyMessageSignature } from '../shared/crypto';
 
 interface JsonRpcRequest {
   jsonrpc: '2.0';
@@ -54,14 +54,14 @@ export class TunnelAgent {
   private uptimeInterval: ReturnType<typeof setInterval> | null = null;
 
   // HMAC signature verification
-  private signingKey: string;
+  private signingKey: string | null = null;
   private lastNonce = 0;
+  private responseNonce = 0;
 
   constructor(config: TunnelConfig, registry: CapabilityRegistry) {
     this.config = config;
     this.registry = registry;
     this.permissionGuard = new PermissionGuard();
-    this.signingKey = deriveSigningKey(config.token);
   }
 
   connect(): void {
@@ -113,10 +113,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.signingKey = null;
       this.uptimeInterval = setInterval(() => { this.uptime++; }, 1000);
 
-      log(`${c.green}●${c.reset}`, `Connected ${c.reset}${c.gray}(${this.registry.getCapabilityNames().join(', ')})${c.reset}`);
+      // Send auth handshake as first message (token never in URL)
+      this.send({ type: 'auth', token: this.config.token });
     });
 
     this.ws.addEventListener('message', (event) => {
@@ -130,6 +133,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();
       }
@@ -141,7 +148,7 @@ export class TunnelAgent {
   }
 
   private async handleMessage(raw: string): Promise<void> {
-    let msg: IncomingMessage;
+    let msg: any;
     try {
       msg = JSON.parse(raw);
     } catch {
@@ -149,20 +156,31 @@ export class TunnelAgent {
       return;
     }
 
-    // ── Heartbeat ping — no signature required ──────────────────────
-    if ('method' in msg && msg.method === 'tunnel.ping') {
-      this.sendPong();
+    // Handle auth_ok — server sends signing key after successful auth
+    if (msg.type === 'auth_ok' && msg.signingKey) {
+      this.signingKey = msg.signingKey;
+      log(`${c.green}●${c.reset}`, `Connected ${c.reset}${c.gray}(${this.registry.getCapabilityNames().join(', ')})${c.reset}`);
+      return;
+    }
+
+    if (!this.signingKey) {
+      log(`${c.yellow}!${c.reset}`, `Message received before auth completed`);
       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 +212,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 +224,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,17 +234,15 @@ 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);
 
-    if (!verifyMessageSignature(this.signingKey, payload, nonce, sig)) {
+    if (!verifyMessageSignature(this.signingKey!, payload, nonce, sig)) {
       log(`${c.red}✗${c.reset}`, `Invalid HMAC signature`);
       return false;
     }
@@ -241,38 +254,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);
+  }
+
+  /** 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 sendError(id: string, code: number, message: string): void {
-    this.send({ jsonrpc: '2.0', id, error: { code, message } });
+  private sendSigned(data: Record<string, unknown>): void {
+    if (this.ws?.readyState === WebSocket.OPEN && this.signingKey) {
+      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 +323,12 @@ export class TunnelAgent {
           platform: platform(),
           arch: arch(),
           osVersion: release(),
-          agentVersion: '0.1.0',
+          agentVersion: '0.1.2',
         },
       },
     });
   }
 
-  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 +350,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/desktop/atspi-helper.ts

@@ -4,7 +4,7 @@ import { join } from 'path';
 import { homedir } from 'os';
 
 const HELPER_VERSION = 'v1';
-const BIN_DIR = join(homedir(), '.kortix-tunnel', 'bin');
+const BIN_DIR = join(homedir(), '.agent-tunnel', 'bin');
 const HELPER_PATH = join(BIN_DIR, `atspi-helper-${HELPER_VERSION}.py`);
 
 const PYTHON_SOURCE = `#!/usr/bin/env python3

package/src/agent/capabilities/desktop/csharp-helper.ts

@@ -4,7 +4,7 @@ import { join } from 'path';
 import { homedir } from 'os';
 
 const HELPER_VERSION = 'v1';
-const BIN_DIR = join(homedir(), '.kortix-tunnel', 'bin');
+const BIN_DIR = join(homedir(), '.agent-tunnel', 'bin');
 const HELPER_PATH = join(BIN_DIR, `desktop-helper-win-${HELPER_VERSION}.exe`);
 
 const CSHARP_SOURCE = `

package/src/agent/capabilities/desktop/linux-driver.ts

@@ -32,7 +32,7 @@ import type {
 } from './types';
 
 function tmpPath(): string {
-  return join(tmpdir(), `kortix-ss-${randomBytes(6).toString('hex')}.png`);
+  return join(tmpdir(), `tunnel-ss-${randomBytes(6).toString('hex')}.png`);
 }
 
 function exec(cmd: string, args: string[]): Promise<string> {

package/src/agent/capabilities/desktop/macos-driver.ts

@@ -32,7 +32,7 @@ import type {
 } from './types';
 
 function tmpPath(ext: string = '.png'): string {
-  return join(tmpdir(), `kortix-ss-${randomBytes(6).toString('hex')}${ext}`);
+  return join(tmpdir(), `tunnel-ss-${randomBytes(6).toString('hex')}${ext}`);
 }
 
 function exec(cmd: string, args: string[], timeoutMs = 15000): Promise<string> {

package/src/agent/capabilities/desktop/swift-helper.ts

@@ -4,7 +4,7 @@ import { join } from 'path';
 import { homedir } from 'os';
 
 const HELPER_VERSION = 'v4';
-const BIN_DIR = join(homedir(), '.kortix-tunnel', 'bin');
+const BIN_DIR = join(homedir(), '.agent-tunnel', 'bin');
 const HELPER_PATH = join(BIN_DIR, `desktop-helper-${HELPER_VERSION}`);
 
 const SWIFT_SOURCE = `

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,
         });