@kortix/agent-tunnel 0.12.7 → 0.13.0

package/package.json

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

@@ -1,11 +1,26 @@
 import { hostname, platform, arch, release } from 'os';
-import { trustedCredential, trustedHttpUrl, type TunnelConfig } from './config';
+import { buildTunnelWsUrl, trustedCredential, type TunnelConfig } from './config';
+import { agentTunnelVersion } from './version';
+import { c } from './terminal';
 import { CapabilityRegistry } from './capabilities/index';
 import { PermissionGuard } from './security/permission-guard';
 import type { LocalPermission } from './security/permission-guard';
 import { signMessage, verifyMessageSignature } from '../shared/crypto';
 
-const AGENT_VERSION = '0.1.2';
+export const AGENT_VERSION = agentTunnelVersion();
+
+/**
+ * Relay close codes that mean the credential itself is bad. They are terminal:
+ * reconnecting with the same token can never succeed.
+ */
+export const AUTH_REJECTED_CLOSE_CODES: readonly number[] = [4001, 4003];
+
+/**
+ * The relay closes an already-registered socket with this code when a second
+ * process authenticates with the same credential. Only one agent may hold a
+ * tunnel, so this is terminal for the displaced process.
+ */
+export const AGENT_REPLACED_CLOSE_CODE = 4004;
 
 interface JsonRpcRequest {
   jsonrpc: '2.0';
@@ -27,25 +42,24 @@ interface JsonRpcNotification {
 type IncomingMessage = JsonRpcRequest | JsonRpcNotification;
 const MAX_RPC_MESSAGE_SIZE = 5 * 1024 * 1024;
 
-const c = {
-  reset:   '\x1b[0m',
-  bold:    '\x1b[1m',
-  dim:     '\x1b[2m',
-  cyan:    '\x1b[36m',
-  green:   '\x1b[32m',
-  yellow:  '\x1b[33m',
-  red:     '\x1b[31m',
-  white:   '\x1b[97m',
-  gray:    '\x1b[90m',
-};
-
 function log(icon: string, msg: string) {
   const safeIcon = icon.replace(/[\r\n]/g, ' ');
   const safeMsg = msg.replace(/[\r\n]/g, ' ');
   process.stdout.write(`  ${safeIcon} ${c.dim}${safeMsg}${c.reset}\n`);
 }
 
+export interface TunnelAgentHooks {
+  /**
+   * Fires when the relay closes the connection for a reason reconnecting cannot
+   * fix. The agent has already stopped retrying by this point.
+   */
+  onTerminalClose?: (info: { code: number; reason: TerminalCloseReason }) => void;
+}
+
+export type TerminalCloseReason = 'credential-rejected' | 'replaced';
+
 export class TunnelAgent {
+  private hooks: TunnelAgentHooks;
   private ws: WebSocket | null = null;
   private registry: CapabilityRegistry;
   private permissionGuard: PermissionGuard;
@@ -64,10 +78,11 @@ export class TunnelAgent {
   private lastNonce = 0;
   private responseNonce = 0;
 
-  constructor(config: TunnelConfig, registry: CapabilityRegistry) {
+  constructor(config: TunnelConfig, registry: CapabilityRegistry, hooks: TunnelAgentHooks = {}) {
     this.config = config;
     this.registry = registry;
     this.permissionGuard = new PermissionGuard();
+    this.hooks = hooks;
   }
 
   connect(): void {
@@ -149,19 +164,24 @@ export class TunnelAgent {
 
       if (!this.isShuttingDown) {
         if (event.code === 4001) {
-          log(`${c.red}✗${c.reset}`, `Authentication failed — check your token`);
+          this.isShuttingDown = true;
+          log(`${c.red}✗${c.reset}`, `Credential rejected — run \`agent-tunnel connect --reauth\` to pair again`);
+          this.hooks.onTerminalClose?.({ code: event.code, reason: 'credential-rejected' });
           return; // Don't reconnect on auth failure
         }
         if (event.code === 4003) {
-          log(`${c.red}✗${c.reset}`, `Device credential was revoked — run connect again`);
+          this.isShuttingDown = true;
+          log(`${c.red}✗${c.reset}`, `Device credential was revoked — run \`agent-tunnel connect --reauth\` to pair again`);
+          this.hooks.onTerminalClose?.({ code: event.code, reason: 'credential-rejected' });
           return;
         }
-        if (event.code === 4004) {
+        if (event.code === AGENT_REPLACED_CLOSE_CODE) {
           this.isShuttingDown = true;
           log(
             `${c.yellow}○${c.reset}`,
             `Another Agent Tunnel process connected with these credentials — stopping this process`,
           );
+          this.hooks.onTerminalClose?.({ code: event.code, reason: 'replaced' });
           return;
         }
         log(`${c.yellow}○${c.reset}`, `Disconnected ${c.gray}(code: ${event.code})${c.reset}`);
@@ -191,7 +211,16 @@ export class TunnelAgent {
     // 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}`);
+      const capabilityNames = this.registry.getCapabilityNames();
+      if (capabilityNames.length === 0) {
+        // Reporting a bare "Connected ()" hides that this tunnel is inert.
+        log(
+          `${c.yellow}!${c.reset}`,
+          `Connected, but no capabilities are enabled — this tunnel cannot do anything. Run \`agent-tunnel connect --reauth\` to pair again.`,
+        );
+      } else {
+        log(`${c.green}●${c.reset}`, `Connected ${c.reset}${c.gray}(${capabilityNames.join(', ')})${c.reset}`);
+      }
       if (this.stableConnectionTimer) clearTimeout(this.stableConnectionTimer);
       this.stableConnectionTimer = setTimeout(() => {
         this.reconnectAttempts = 0;
@@ -358,6 +387,10 @@ export class TunnelAgent {
   private send(data: unknown): void {
     if (this.ws?.readyState === WebSocket.OPEN) {
       try {
+        // The auth handshake carries the credential read from the local config
+        // file to the relay by design. loadConfig() validates the file and
+        // trustedCredential() rejects control characters before it gets here.
+        // lgtm[js/file-access-to-http]
         this.ws.send(JSON.stringify(data));
       } catch (err) {
         log(`${c.red}✗${c.reset}`, `Send failed`);
@@ -400,15 +433,6 @@ export class TunnelAgent {
   }
 
   private buildWsUrl(): string {
-    const base = trustedHttpUrl(this.config.apiUrl)
-      .replace(/^http:/, 'ws:')
-      .replace(/^https:/, 'wss:');
-
-    const wsPath = this.config.wsPath || '/ws';
-    const params = new URLSearchParams({
-      tunnelId: trustedCredential(this.config.tunnelId, 'tunnelId'),
-    });
-
-    return `${base}${wsPath}?${params.toString()}`;
+    return buildTunnelWsUrl(this.config);
   }
 }

package/src/agent/banner.ts

@@ -0,0 +1,82 @@
+import { arch, hostname, platform } from 'os';
+import { c, sleep, visibleLength } from './terminal';
+
+const BOX_WIDTH = 60;
+const BAR_WIDTH = 50;
+const BAR_FRAMES = 14;
+
+const WORDMARK = [
+  `${c.cyan}▄▀█ █▀▀ █▀▀ █▄ █ ▀█▀${c.reset}   ${c.cyan}▀█▀ █ █ █▄ █ █▄ █ █▀▀ █  ${c.reset}`,
+  `${c.cyan}█▀█ █▄█ ██▄ █ ▀█  █${c.reset}    ${c.cyan} █  █▄█ █ ▀█ █ ▀█ ██▄ █▄▄${c.reset}`,
+];
+
+function truncate(value: string, max: number): string {
+  return value.length > max ? `${value.slice(0, max)}…` : value;
+}
+
+async function animateConnectingBar(): Promise<void> {
+  for (let frame = 0; frame <= BAR_FRAMES; frame++) {
+    const filled = Math.round((frame / BAR_FRAMES) * BAR_WIDTH);
+    process.stdout.write(
+      `\r      ${c.cyan}◇${c.reset} ${c.cyan}${'═'.repeat(filled)}${c.reset}${c.gray}${'─'.repeat(BAR_WIDTH - filled)}${c.reset}  `,
+    );
+    await sleep(20);
+  }
+  process.stdout.write(`\r      ${c.cyan}◇ ${'═'.repeat(BAR_WIDTH)} ◆${c.reset}  \n`);
+  await sleep(120);
+}
+
+export interface BannerDetails {
+  tunnelId: string;
+  apiUrl: string;
+  capabilities: string[];
+  version: string;
+}
+
+export async function printStartupBanner({
+  tunnelId,
+  apiUrl,
+  capabilities,
+  version,
+}: BannerDetails): Promise<void> {
+  console.log('');
+  for (const line of WORDMARK) console.log(`      ${line}`);
+  console.log('');
+
+  await animateConnectingBar();
+
+  const row = (content: string) => {
+    const pad = Math.max(0, BOX_WIDTH - visibleLength(content));
+    console.log(`  ${c.gray}│${c.reset}${content}${' '.repeat(pad)}${c.gray}│${c.reset}`);
+  };
+  const blank = () => row('');
+
+  const titleLeft =`   ${c.cyan}◆${c.reset}  ${c.bold}${c.white}Agent Tunnel${c.reset}`;
+  const titleRight = `${c.dim}v${version}${c.reset}   `;
+  const titlePad = Math.max(1, BOX_WIDTH - visibleLength(titleLeft) - visibleLength(titleRight));
+
+  // An empty capability set means the tunnel can connect but do nothing, so it
+  // is stated outright rather than rendered as an empty gap.
+  const capabilityRow =
+    capabilities.length > 0
+      ? capabilities.map((name) => `${c.green}●${c.reset} ${c.white}${name}${c.reset}`).join('   ')
+      : `${c.yellow}none — this tunnel cannot act${c.reset}`;
+
+  const brand = 'created by kortix';
+
+  console.log('');
+  console.log(`  ${c.gray}╭${'─'.repeat(BOX_WIDTH)}╮${c.reset}`);
+  blank();
+  row(`${titleLeft}${' '.repeat(titlePad)}${titleRight}`);
+  row(`   ${c.dim}Bridge between AI agents & local machines${c.reset}`);
+  blank();
+  row(`   ${c.dim}tunnel${c.reset}    ${c.white}${truncate(tunnelId, 40)}${c.reset}`);
+  row(`   ${c.dim}relay${c.reset}     ${c.white}${truncate(apiUrl, 40)}${c.reset}`);
+  row(`   ${c.dim}machine${c.reset}   ${c.white}${truncate(hostname(), 28)}${c.reset} ${c.dim}(${platform()} ${arch()})${c.reset}`);
+  row(`   ${c.dim}access${c.reset}    ${capabilityRow}`);
+  blank();
+  console.log(
+    `  ${c.gray}╰${'─'.repeat(BOX_WIDTH - brand.length - 3)} ${c.dim}created by ${c.cyan}kortix${c.reset} ${c.gray}─╯${c.reset}`,
+  );
+  console.log('');
+}

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

@@ -1,25 +1,89 @@
-import { describe, expect, test } from 'bun:test';
-import { spawnSync } from 'child_process';
-import { resolve } from 'path';
+import { describe, expect, test } from "bun:test";
+import { spawnSync } from "child_process";
+import { mkdtempSync, rmSync } from "fs";
+import { tmpdir } from "os";
+import { join, resolve } from "path";
 
-const CLI_PATH = resolve(import.meta.dir, 'cli.ts');
+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' });
+/**
+ * The published CLI's help text is its documented surface. tests/bin/package-quality.ts
+ * asserts the same list against the packed tarball; duplicating it here makes an
+ * accidental removal fail in this package's own suite instead of only in CI.
+ */
+const DOCUMENTED_SURFACE = [
+  "connect",
+  "run",
+  "install-service",
+  "service-status",
+  "uninstall-service",
+  "status",
+  "logs",
+  "logout",
+  "--daemon",
+  "--foreground",
+] as const;
 
-    expect(result.status).toBe(0);
-    expect(result.stdout).toContain('--daemon');
-    expect(result.stdout).toContain('--foreground');
-    expect(result.stdout).not.toContain('--keep-awake');
+describe("agent tunnel documented CLI surface", () => {
+  for (const entry of DOCUMENTED_SURFACE) {
+    test(`help lists ${entry}`, () => {
+      const result = spawnSync("bun", ["run", CLI_PATH, "help"], {
+        encoding: "utf8",
+      });
+      expect(result.status).toBe(0);
+      expect(result.stdout).toContain(entry);
+    });
+  }
+
+  // Only read-only commands are executed here. start/stop/restart/logout/unpair
+  // mutate the real launchd domain and credential file — running them from a
+  // test suite would stop a developer's live service or delete their pairing.
+  for (const command of ["status", "service-status"] as const) {
+    test(`${command} routes to the status view`, () => {
+      const home = mkdtempSync(join(tmpdir(), "agent-tunnel-help-"));
+      try {
+        const result = spawnSync("bun", ["run", CLI_PATH, command, "--json"], {
+          encoding: "utf8",
+          env: { ...process.env, HOME: home },
+        });
+        expect(result.status).toBe(0);
+        expect(JSON.parse(result.stdout)).toMatchObject({ paired: false });
+      } finally {
+        rmSync(home, { recursive: true, force: true });
+      }
+    });
+  }
+
+  test("an unknown command falls back to help", () => {
+    const result = spawnSync("bun", ["run", CLI_PATH, "not-a-command"], {
+      encoding: "utf8",
+    });
+    expect(result.stdout).toContain("Secure bridge between AI agents");
   });
+});
 
-  test('rejects the removed keep-awake flag instead of silently ignoring it', () => {
-    const result = spawnSync('bun', ['run', CLI_PATH, 'connect', '--keep-awake'], {
-      encoding: 'utf8',
+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');
+    expect(result.stderr).toContain("--keep-awake is not supported");
   });
 });

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

@@ -0,0 +1,205 @@
+import { afterEach, describe, expect, test } from 'bun:test';
+import { spawn, type ChildProcess } from 'node:child_process';
+import { mkdir, mkdtemp, readFile, rm, writeFile } 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>();
+
+const STALE_TUNNEL_ID = '00000000-0000-4000-8000-0000000000ff';
+const STALE_TOKEN = 'kortix_tnl_STALEAAAAAAAAAAAAAAAAAAAAAAAAAAAA';
+const FRESH_TUNNEL_ID = '00000000-0000-4000-8000-000000000042';
+const FRESH_TOKEN = 'kortix_tnl_FRESHBBBBBBBBBBBBBBBBBBBBBBBBBBBB';
+
+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 seedStaleCredentials(apiUrl: string): Promise<string> {
+  const home = await mkdtemp(join(tmpdir(), 'agent-tunnel-reauth-home-'));
+  temporaryHomes.add(home);
+  const configDir = join(home, '.agent-tunnel');
+  await mkdir(configDir, { recursive: true, mode: 0o700 });
+  await writeFile(
+    join(configDir, 'config.json'),
+    JSON.stringify({ tunnelId: STALE_TUNNEL_ID, token: STALE_TOKEN, apiUrl }),
+    { mode: 0o600 },
+  );
+  return home;
+}
+
+async function waitFor<T>(read: () => Promise<T>, timeoutMs = 15_000): Promise<T> {
+  const deadline = Date.now() + timeoutMs;
+  let lastError: unknown;
+  while (Date.now() < deadline) {
+    try {
+      return await read();
+    } catch (error) {
+      lastError = error;
+      await Bun.sleep(50);
+    }
+  }
+  throw lastError ?? new Error('timed out');
+}
+
+/** Relay that refuses every credential, and a device-auth endpoint that issues a fresh one. */
+function startRejectingRelay(options: { serveDeviceAuth: boolean }) {
+  let deviceAuthCalls = 0;
+  const server = Bun.serve({
+    port: 0,
+    fetch(request, server) {
+      const url = new URL(request.url);
+      if (url.pathname === '/v1/tunnel/ws') {
+        return server.upgrade(request) ? undefined : new Response('no upgrade', { status: 400 });
+      }
+      if (!options.serveDeviceAuth) return new Response('not found', { status: 404 });
+
+      if (request.method === 'POST' && url.pathname === '/v1/tunnel/device-auth') {
+        deviceAuthCalls++;
+        return Response.json(
+          {
+            deviceCode: 'RAUT-0001',
+            deviceSecret: 'ABCDEFGHIJKLMNOPQRSTUVWXYZ123456',
+            verificationUrl: 'https://dev.kortix.com/tunnel/authorize/RAUT-0001',
+            expiresAt: new Date(Date.now() + 60_000).toISOString(),
+            pollIntervalMs: 250,
+          },
+          { status: 201 },
+        );
+      }
+      if (request.method === 'GET' && url.pathname.endsWith('/RAUT-0001/status')) {
+        return Response.json({
+          status: 'approved',
+          tunnelId: FRESH_TUNNEL_ID,
+          token: FRESH_TOKEN,
+          capabilities: ['filesystem'],
+        });
+      }
+      return new Response('not found', { status: 404 });
+    },
+    websocket: {
+      // 4001 is the relay's "credential refused" code.
+      message(ws) {
+        ws.close(4001, 'auth failed');
+      },
+    },
+  });
+  return { server, deviceAuthCalls: () => deviceAuthCalls };
+}
+
+function runConnect(home: string, apiUrl: string, extraArgs: string[] = []) {
+  const child = spawn(
+    process.execPath,
+    ['run', CLI_PATH, 'connect', '--foreground', '--api-url', apiUrl, ...extraArgs],
+    {
+      env: { ...process.env, HOME: home, KORTIX_AGENT_TUNNEL_NO_BROWSER: '1' },
+      stdio: ['ignore', 'pipe', 'pipe'],
+    },
+  );
+  children.add(child);
+  let stdout = '';
+  let stderr = '';
+  child.stdout?.on('data', (chunk) => { stdout += String(chunk); });
+  child.stderr?.on('data', (chunk) => { stderr += String(chunk); });
+  return { child, out: () => stdout, err: () => stderr };
+}
+
+describe('agent tunnel connect re-authorization', () => {
+  test('re-pairs through device auth when the saved token is rejected', async () => {
+    const relay = startRejectingRelay({ serveDeviceAuth: true });
+    const apiUrl = `http://127.0.0.1:${relay.server.port}/v1/tunnel`;
+    const home = await seedStaleCredentials(apiUrl);
+    const configPath = join(home, '.agent-tunnel', 'config.json');
+    const run = runConnect(home, apiUrl);
+
+    try {
+      const config = await waitFor(async () => {
+        const parsed = JSON.parse(await readFile(configPath, 'utf8')) as { token?: string };
+        if (parsed.token !== FRESH_TOKEN) throw new Error('still holding the stale token');
+        return parsed as { token: string; tunnelId: string };
+      });
+
+      expect(config.tunnelId).toBe(FRESH_TUNNEL_ID);
+      expect(run.out()).toContain('Checking saved credentials');
+      expect(run.out()).toContain('Saved token rejected');
+      expect(relay.deviceAuthCalls()).toBeGreaterThan(0);
+    } finally {
+      run.child.kill('SIGTERM');
+      relay.server.stop(true);
+    }
+  }, 30_000);
+
+  test('keeps the saved credential when the relay is unreachable', async () => {
+    // Port 1 is reserved and refuses connections, so the probe cannot conclude
+    // anything about the credential itself.
+    const apiUrl = 'http://127.0.0.1:1/v1/tunnel';
+    const home = await seedStaleCredentials(apiUrl);
+    const configPath = join(home, '.agent-tunnel', 'config.json');
+    const run = runConnect(home, apiUrl);
+
+    const exitCode = await new Promise<number | null>((r) => run.child.once('exit', r));
+    expect(exitCode).toBe(1);
+    expect(run.err()).toContain('Cannot reach the relay');
+
+    const config = JSON.parse(await readFile(configPath, 'utf8')) as { token?: string };
+    expect(config.token).toBe(STALE_TOKEN);
+  }, 30_000);
+
+  test('--reauth discards a saved credential without probing it first', async () => {
+    const relay = startRejectingRelay({ serveDeviceAuth: true });
+    const apiUrl = `http://127.0.0.1:${relay.server.port}/v1/tunnel`;
+    const home = await seedStaleCredentials(apiUrl);
+    const configPath = join(home, '.agent-tunnel', 'config.json');
+    const run = runConnect(home, apiUrl, ['--reauth']);
+
+    try {
+      const config = await waitFor(async () => {
+        const parsed = JSON.parse(await readFile(configPath, 'utf8')) as { token?: string };
+        if (parsed.token !== FRESH_TOKEN) throw new Error('not re-paired yet');
+        return parsed;
+      });
+      expect(config.token).toBe(FRESH_TOKEN);
+      expect(run.out()).not.toContain('Checking saved credentials');
+    } finally {
+      run.child.kill('SIGTERM');
+      relay.server.stop(true);
+    }
+  }, 30_000);
+
+  test('logout clears the credential but keeps unrelated settings', async () => {
+    const home = await mkdtemp(join(tmpdir(), 'agent-tunnel-logout-home-'));
+    temporaryHomes.add(home);
+    const configDir = join(home, '.agent-tunnel');
+    await mkdir(configDir, { recursive: true, mode: 0o700 });
+    const configPath = join(configDir, 'config.json');
+    await writeFile(
+      configPath,
+      JSON.stringify({
+        tunnelId: STALE_TUNNEL_ID,
+        token: STALE_TOKEN,
+        apiUrl: 'https://api.kortix.com/v1/tunnel',
+        shellTimeout: 12_345,
+      }),
+      { mode: 0o600 },
+    );
+
+    const child = spawn(process.execPath, ['run', CLI_PATH, 'logout'], {
+      env: { ...process.env, HOME: home },
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    children.add(child);
+    await new Promise<number | null>((r) => child.once('exit', r));
+
+    const config = JSON.parse(await readFile(configPath, 'utf8')) as Record<string, unknown>;
+    expect(config.token).toBeUndefined();
+    expect(config.tunnelId).toBeUndefined();
+    expect(config.shellTimeout).toBe(12_345);
+  }, 30_000);
+});