@kortix/agent-tunnel 0.1.1 → 0.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kortix/agent-tunnel",
-  "version": "0.1.1",
+  "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",

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, signMessage, verifyMessageSignature } from '../shared/crypto';
+import { signMessage, verifyMessageSignature } from '../shared/crypto';
 
 interface JsonRpcRequest {
   jsonrpc: '2.0';
@@ -54,7 +54,7 @@ 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;
 
@@ -62,7 +62,6 @@ export class TunnelAgent {
     this.config = config;
     this.registry = registry;
     this.permissionGuard = new PermissionGuard();
-    this.signingKey = deriveSigningKey(config.token);
   }
 
   connect(): void {
@@ -116,12 +115,11 @@ export class TunnelAgent {
       this.uptime = 0;
       this.lastNonce = 0;
       this.responseNonce = 0;
+      this.signingKey = null;
       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}`);
     });
 
     this.ws.addEventListener('message', (event) => {
@@ -150,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 {
@@ -158,6 +156,18 @@ export class TunnelAgent {
       return;
     }
 
+    // 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;
+    }
+
     if (!this.verifyIncomingSignature(msg, raw)) {
       if ('id' in msg && msg.id) {
         this.sendSignedError(msg.id, -32000, 'Invalid message signature');
@@ -232,7 +242,7 @@ export class TunnelAgent {
     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;
     }
@@ -278,7 +288,7 @@ export class TunnelAgent {
   }
 
   private sendSigned(data: Record<string, unknown>): void {
-    if (this.ws?.readyState === WebSocket.OPEN) {
+    if (this.ws?.readyState === WebSocket.OPEN && this.signingKey) {
       const nonce = ++this.responseNonce;
       const payload = JSON.stringify(data);
       const sig = signMessage(this.signingKey, payload, nonce);
@@ -313,7 +323,7 @@ export class TunnelAgent {
           platform: platform(),
           arch: arch(),
           osVersion: release(),
-          agentVersion: '0.1.1',
+          agentVersion: '0.1.2',
         },
       },
     });

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/cli.ts

@@ -1,11 +1,15 @@
 #!/usr/bin/env bun
-import { loadConfig } from './config';
+import { loadConfig, type TunnelConfig } 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';
+import { existsSync, mkdirSync, writeFileSync, readFileSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+import { execSync } from 'child_process';
 
 const c = {
   reset:   '\x1b[0m',
@@ -114,30 +118,14 @@ async function printStartup(config: { tunnelId: string; apiUrl: string }, capabi
   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);
-  }
-
+function startAgent(config: TunnelConfig): void {
   const registry = new CapabilityRegistry();
   registry.register(createFilesystemCapability(config));
   registry.register(createShellCapability(config));
   registry.register(createDesktopCapability());
 
   clearScreen();
-  await printStartup(config, registry.getCapabilityNames(), '0.1.0');
+  printStartup(config, registry.getCapabilityNames(), '0.1.2');
 
   const agent = new TunnelAgent(config, registry);
   agent.connect();
@@ -152,6 +140,152 @@ async function commandConnect(flags: Record<string, string>): Promise<void> {
   process.on('SIGINT', shutdown);
 }
 
+function openBrowser(url: string): void {
+  try {
+    const plat = platform();
+    if (plat === 'darwin') execSync(`open "${url}"`);
+    else if (plat === 'win32') execSync(`start "" "${url}"`);
+    else execSync(`xdg-open "${url}"`);
+  } catch {}
+}
+
+const CONFIG_DIR = join(homedir(), '.agent-tunnel');
+const CONFIG_FILE = join(CONFIG_DIR, 'config.json');
+
+function saveCredentials(tunnelId: string, token: string, apiUrl: string): void {
+  mkdirSync(CONFIG_DIR, { recursive: true });
+  let existing: Record<string, unknown> = {};
+  if (existsSync(CONFIG_FILE)) {
+    try { existing = JSON.parse(readFileSync(CONFIG_FILE, 'utf-8')); } catch {}
+  }
+  writeFileSync(CONFIG_FILE, JSON.stringify({ ...existing, tunnelId, token, apiUrl }, null, 2));
+}
+
+async function commandConnectDeviceAuth(config: TunnelConfig): Promise<void> {
+  console.log('');
+  console.log(`  ${c.cyan}◆${c.reset} ${c.bold}Device Authorization${c.reset}`);
+  console.log('');
+
+  // Step 1: Create device auth request
+  let deviceCode: string;
+  let deviceSecret: string;
+  let verificationUrl: string;
+  let expiresAt: string;
+  let pollIntervalMs: number;
+
+  try {
+    const res = await fetch(`${config.apiUrl}/device-auth`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ machineHostname: hostname() }),
+    });
+    if (!res.ok) {
+      const text = await res.text().catch(() => '');
+      console.error(`  ${c.red}✗${c.reset} Failed to create device auth request: ${res.status} ${text.slice(0, 200)}`);
+      process.exit(1);
+    }
+    const data = await res.json();
+    deviceCode = data.deviceCode;
+    deviceSecret = data.deviceSecret;
+    verificationUrl = data.verificationUrl;
+    expiresAt = data.expiresAt;
+    pollIntervalMs = data.pollIntervalMs || 2000;
+  } catch (err) {
+    console.error(`  ${c.red}✗${c.reset} Failed to reach API at ${config.apiUrl}`);
+    process.exit(1);
+    return;
+  }
+
+  // Step 2: Display code and open browser
+  console.log(`  ${c.dim}Code:${c.reset}  ${c.bold}${c.white}${deviceCode}${c.reset}`);
+  console.log('');
+  console.log(`  ${c.dim}Open this URL on any device to approve:${c.reset}`);
+  console.log(`  ${c.cyan}${verificationUrl}${c.reset}`);
+  console.log('');
+
+  openBrowser(verificationUrl);
+
+  // Step 3: Poll for approval
+  const expiresAtMs = new Date(expiresAt).getTime();
+
+  while (true) {
+    const remaining = Math.max(0, Math.floor((expiresAtMs - Date.now()) / 1000));
+    if (remaining <= 0) {
+      console.log(`\n  ${c.red}✗${c.reset} Authorization expired. Please try again.`);
+      process.exit(1);
+    }
+
+    const min = Math.floor(remaining / 60);
+    const sec = remaining % 60;
+    process.stdout.write(`\r  ${c.dim}Waiting for approval... ${c.white}${min}:${sec.toString().padStart(2, '0')}${c.reset}  `);
+
+    try {
+      const res = await fetch(`${config.apiUrl}/device-auth/${deviceCode}/status?secret=${deviceSecret}`);
+      if (res.ok) {
+        const data = await res.json();
+
+        if (data.status === 'approved' && data.tunnelId && data.token) {
+          process.stdout.write('\r' + ' '.repeat(60) + '\r');
+          console.log(`  ${c.green}●${c.reset} ${c.bold}Authorized!${c.reset}`);
+          console.log('');
+
+          // Save credentials
+          saveCredentials(data.tunnelId, data.token, config.apiUrl);
+          console.log(`  ${c.dim}Credentials saved to ${CONFIG_FILE}${c.reset}`);
+          console.log('');
+
+          // Connect with received credentials
+          const fullConfig = loadConfig({
+            token: data.token,
+            tunnelId: data.tunnelId,
+            apiUrl: config.apiUrl,
+          });
+          startAgent(fullConfig);
+          return;
+        }
+
+        if (data.status === 'denied') {
+          process.stdout.write('\r' + ' '.repeat(60) + '\r');
+          console.log(`  ${c.red}✗${c.reset} Authorization denied.`);
+          process.exit(1);
+        }
+
+        if (data.status === 'expired') {
+          process.stdout.write('\r' + ' '.repeat(60) + '\r');
+          console.log(`  ${c.red}✗${c.reset} Authorization expired. Please try again.`);
+          process.exit(1);
+        }
+      }
+    } catch {}
+
+    await sleep(pollIntervalMs);
+  }
+}
+
+async function commandConnect(flags: Record<string, string>): Promise<void> {
+  const config = loadConfig({
+    token: flags.token,
+    tunnelId: flags['tunnel-id'],
+    apiUrl: flags['api-url'],
+  });
+
+  // If both token and tunnelId are provided, connect directly
+  if (config.token && config.tunnelId) {
+    startAgent(config);
+    return;
+  }
+
+  // If neither is provided, use device auth flow
+  if (!config.token && !config.tunnelId) {
+    await commandConnectDeviceAuth(config);
+    return;
+  }
+
+  // Partial — error
+  console.error(`${c.red}${c.bold} error${c.reset} Provide both --token and --tunnel-id, or neither (for device auth)`);
+  process.exit(1);
+}
+
 async function commandStatus(flags: Record<string, string>): Promise<void> {
   const config = loadConfig({
     token: flags.token,
@@ -192,13 +326,13 @@ function showHelp(): void {
   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}connect${c.reset}       Connect via device auth (opens browser)`);
   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}--token${c.reset} ${c.dim}<token>${c.reset}       Skip device auth, connect directly`);
+  console.log(`  ${c.white}--tunnel-id${c.reset} ${c.dim}<id>${c.reset}     Tunnel ID ${c.dim}(required with --token)${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}`);

package/src/client/cli.test.ts

@@ -3,7 +3,7 @@
  *
  * Strategy: spin up a lightweight mock HTTP server that simulates the
  * tunnel relay API, then invoke the CLI as a child process via `bun run`
- * with KORTIX_API_URL pointing at the mock. Assert on JSON stdout,
+ * with TUNNEL_API_URL pointing at the mock. Assert on JSON stdout,
  * stderr, and exit codes.
  *
  * Run: bun test src/client/cli.test.ts
@@ -267,9 +267,9 @@ function runCli(
     const child = spawn("bun", cliArgs, {
       env: {
         ...process.env,
-        KORTIX_API_URL: `http://localhost:${mockPort}`,
-        KORTIX_TOKEN: "test-token",
-        KORTIX_TUNNEL_ID: "",
+        TUNNEL_API_URL: `http://localhost:${mockPort}`,
+        TUNNEL_TOKEN: "test-token",
+        TUNNEL_ID: "",
         ...envOverrides,
       },
       cwd: dirname(dirname(CLI_PATH)),
@@ -669,7 +669,7 @@ describe("Agent Tunnel CLI", () => {
 
     test("permission denied returns structured response", async () => {
       const r = await runCli("fs_read", '{"path":"/etc/passwd"}', {
-        KORTIX_API_URL: `http://localhost:${permPort}`,
+        TUNNEL_API_URL: `http://localhost:${permPort}`,
       });
       // CLI should output permission-required JSON (not crash)
       expect(r.json).not.toBeNull();
@@ -683,7 +683,7 @@ describe("Agent Tunnel CLI", () => {
       const r = await runCli(
         "shell",
         '{"command":"rm","args":["-rf","/"]}',
-        { KORTIX_API_URL: `http://localhost:${permPort}` }
+        { TUNNEL_API_URL: `http://localhost:${permPort}` }
       );
       expect(r.json!.success).toBe(false);
       expect(r.json!.permissionRequired).toBe(true);
@@ -695,7 +695,7 @@ describe("Agent Tunnel CLI", () => {
   describe("server unreachable", () => {
     test("status with dead server returns error JSON", async () => {
       const r = await runCli("status", undefined, {
-        KORTIX_API_URL: "http://localhost:1",
+        TUNNEL_API_URL: "http://localhost:1",
       });
       expect(r.exitCode).toBe(1);
       expect(r.json).not.toBeNull();
@@ -705,7 +705,7 @@ describe("Agent Tunnel CLI", () => {
 
     test("fs_read with dead server returns error JSON", async () => {
       const r = await runCli("fs_read", '{"path":"/tmp/x"}', {
-        KORTIX_API_URL: "http://localhost:1",
+        TUNNEL_API_URL: "http://localhost:1",
       });
       expect(r.exitCode).toBe(1);
       expect(r.json!.success).toBe(false);
@@ -738,7 +738,7 @@ describe("Agent Tunnel CLI", () => {
 
     test("status with no connections returns empty list", async () => {
       const r = await runCli("status", undefined, {
-        KORTIX_API_URL: `http://localhost:${emptyPort}`,
+        TUNNEL_API_URL: `http://localhost:${emptyPort}`,
       });
       expect(r.exitCode).toBe(0);
       expect(r.json!.success).toBe(true);
@@ -748,7 +748,7 @@ describe("Agent Tunnel CLI", () => {
 
     test("fs_read with no connections returns error", async () => {
       const r = await runCli("fs_read", '{"path":"/tmp/x"}', {
-        KORTIX_API_URL: `http://localhost:${emptyPort}`,
+        TUNNEL_API_URL: `http://localhost:${emptyPort}`,
       });
       expect(r.exitCode).toBe(1);
       expect(r.json!.success).toBe(false);

package/src/client/cli.ts

@@ -56,15 +56,15 @@ function getEnv(key: string): string | undefined {
 const FALLBACK_API_URL = "http://localhost:8008";
 
 function getApiBase(): string {
-  const raw = getEnv("KORTIX_API_URL") || FALLBACK_API_URL;
+  const raw = getEnv("TUNNEL_API_URL") || FALLBACK_API_URL;
   const url = raw.startsWith("http") ? raw : FALLBACK_API_URL;
   return url.replace(/\/+$/, "");
 }
 
 const client = new TunnelClient({
   apiUrl: `${getApiBase()}/v1/tunnel`,
-  token: getEnv("KORTIX_TOKEN") || "",
-  tunnelId: getEnv("KORTIX_TUNNEL_ID"),
+  token: getEnv("TUNNEL_TOKEN") || "",
+  tunnelId: getEnv("TUNNEL_ID"),
 });
 
 // ── Helpers ───────────────────────────────────────────────────────────────

package/src/server/ws-handler.ts

@@ -81,6 +81,11 @@ export function createWsHandlers(relay: TunnelRelay, opts?: WsHandlerOptions): W
             return;
           }
 
+          // Send signing key to agent so it never needs the server secret
+          try {
+            pending.ws.send(JSON.stringify({ type: 'auth_ok', signingKey: result.signingKey }));
+          } catch {}
+
           relay.registerAgent(tunnelId, pending.ws, result.signingKey, result.metadata);
           if (heartbeat) {
             heartbeat.register(tunnelId);

package/src/shared/crypto.ts

@@ -1,6 +1,5 @@
 import { createHash, createHmac, timingSafeEqual, randomBytes } from 'crypto';
 
-const SIGNING_KEY_CONTEXT = 'kortix-tunnel-signing-v1';
 const CHARS = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
 
 function randomAlphanumeric(length: number): string {
@@ -12,8 +11,8 @@ function randomAlphanumeric(length: number): string {
   return result;
 }
 
-export function deriveSigningKey(token: string): string {
-  return createHmac('sha256', SIGNING_KEY_CONTEXT)
+export function deriveSigningKey(token: string, secret: string): string {
+  return createHmac('sha256', secret)
     .update(token)
     .digest('hex');
 }