@kadi.build/tunnel-client 0.1.0

package/README.md

@@ -0,0 +1,128 @@
+# @kadi/tunnel-client
+
+Supporting classes for **KadiTunnelService** — the self-hosted HTTPS tunnel provider for KĀDI agents.
+
+This package provides the SSH mode, frpc client mode, config generation, output parsing, reconnection management, and utility functions that `KadiTunnelService.js` depends on.
+
+> **KadiTunnelService.js itself is NOT part of this package.** It is a standalone drop-in file — just like `NgrokTunnelService.js` and `ServeoTunnelService.js` — that you copy into your project's services directory.
+
+## Architecture
+
+```
+Your project (e.g. @kadi.build/local-remote-file-manager-ability)
+├── BaseTunnelService.js          ← base class (your project)
+├── errors.js                     ← error classes (your project)
+└── services/
+    ├── NgrokTunnelService.js     ← drop-in file, uses `ngrok` npm package
+    ├── ServeoTunnelService.js    ← drop-in file, uses system `ssh`
+    └── KadiTunnelService.js      ← drop-in file, uses `@kadi/tunnel-client`
+```
+
+## Installation
+
+```bash
+npm install @kadi/tunnel-client
+```
+
+Then copy `KadiTunnelService.js` into your project's services directory (alongside the other tunnel services).
+
+## What this package exports
+
+| Export | Description |
+|--------|-------------|
+| `KadiSSHMode` | SSH gateway tunnel mode (`ssh -R`) — zero binary dependencies |
+| `KadiClientMode` | frpc binary tunnel mode — enhanced features, native reconnect |
+| `KadiConfigGenerator` | Generates frpc TOML configuration |
+| `KadiOutputParser` | Parses frpc/ssh stdout for tunnel URLs and status |
+| `ReconnectionManager` | Exponential backoff reconnection with jitter |
+| `detectFrpcBinary` | Detects whether `frpc` is available on `$PATH` |
+| `generateSubdomain` | Deterministic subdomain generation from agent ID + port |
+
+## Usage
+
+In your copied `KadiTunnelService.js`:
+
+```javascript
+// These come from your project (same as Ngrok/Serveo services)
+import { BaseTunnelService } from '../BaseTunnelService.js';
+import { TransientTunnelError, PermanentTunnelError, ... } from '../errors.js';
+
+// These come from this npm package
+import {
+  KadiSSHMode,
+  KadiClientMode,
+  ReconnectionManager,
+  detectFrpcBinary,
+  generateSubdomain
+} from '@kadi/tunnel-client';
+```
+
+## Connection Modes
+
+### SSH Mode (default, zero dependencies)
+Uses `ssh -R` to create a reverse tunnel through the KĀDI SSH gateway. No binary installation needed — works anywhere `ssh` is available.
+
+### frpc Mode (enhanced)
+Uses the [frp](https://github.com/fatedier/frp) client binary for enhanced features including native reconnection, health checks, and multiplexed connections. Requires `frpc` on `$PATH`.
+
+### Auto Mode
+Tries frpc first, falls back to SSH if the binary is not found.
+
+## Configuration
+
+When instantiating `KadiTunnelService` in your project:
+
+```javascript
+const service = new KadiTunnelService({
+  agentId: 'my-agent',
+  frp: {
+    serverAddr: 'broker.kadi.build',
+    serverPort: 7000,
+    sshPort: 2200,
+    token: 'your-tunnel-token',
+    tunnelDomain: 'tunnel.kadi.build',
+    mode: 'auto'  // 'auto' | 'ssh' | 'frpc'
+  }
+});
+
+const tunnel = await service.connect({ port: 3000 });
+console.log(tunnel.url);   // https://<subdomain>.tunnel.kadi.build
+console.log(tunnel.mode);  // 'ssh' or 'frpc'
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `frp.serverAddr` | *(required)* | Tunnel server hostname |
+| `frp.serverPort` | `7000` | frp server bind port |
+| `frp.sshPort` | `2200` | SSH gateway port |
+| `frp.token` | *(required)* | Authentication token |
+| `frp.tunnelDomain` | *(required)* | Wildcard tunnel domain |
+| `frp.mode` | `'auto'` | `'auto'`, `'ssh'`, or `'frpc'` |
+| `agentId` | `'agent'` | Agent ID for subdomain generation |
+
+## Development
+
+```bash
+# Run all tests (unit + integration)
+npm test
+
+# Unit tests only
+npm run test:unit
+
+# SSH mode tests
+npm run test:ssh
+
+# frpc client mode tests
+npm run test:frpc
+
+# Integration tests (requires running tunnel server)
+npm run test:integration
+```
+
+## Server Setup
+
+See the [server README](../server/README.md) for VPS deployment instructions (frps + Caddy + wildcard TLS).
+
+## License
+
+UNLICENSED

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@kadi.build/tunnel-client",
+  "version": "0.1.0",
+  "description": "Supporting classes for KadiTunnelService — SSH mode, frpc client mode, reconnection, config generation, and output parsing.",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "src/index.js",
+    "src/KadiSSHMode.js",
+    "src/KadiClientMode.js",
+    "src/KadiConfigGenerator.js",
+    "src/KadiOutputParser.js",
+    "src/ReconnectionManager.js",
+    "src/utils.js",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test tests/",
+    "test:unit": "node --test tests/test-kadi-tunnel-service.js tests/test-kadi-output-parser.js tests/test-kadi-config-generator.js tests/test-reconnection.js",
+    "test:ssh": "node --test tests/test-kadi-ssh-mode.js",
+    "test:frpc": "node --test tests/test-kadi-client-mode.js",
+    "test:integration": "node --test tests/test-integration.js"
+  },
+  "keywords": ["kadi", "tunnel", "frp", "ssh", "reverse-proxy", "frpc"],
+  "license": "UNLICENSED",
+  "author": "KĀDI",
+  "repository": {
+    "type": "git",
+    "url": "https://gitlab.com/anthropic-kadi/kadi-tunnel.git",
+    "directory": "client"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/KadiClientMode.js

@@ -0,0 +1,162 @@
+/**
+ * @fileoverview frpc binary mode strategy for KadiTunnelService
+ * 
+ * Uses the `frpc` binary (when available) for enhanced tunnel features:
+ *   - Built-in auto-reconnect
+ *   - Connection pooling
+ *   - Dashboard integration
+ * 
+ * Generates a per-tunnel TOML config file and spawns `frpc -c <config>`.
+ */
+
+import { spawn } from 'child_process';
+import { promises as fs } from 'fs';
+import path from 'path';
+import os from 'os';
+import {
+  TransientTunnelError,
+  PermanentTunnelError,
+  ConnectionTimeoutError,
+  AuthenticationFailedError
+} from '../errors.js';
+import { KadiConfigGenerator } from './KadiConfigGenerator.js';
+import { KadiOutputParser } from './KadiOutputParser.js';
+
+/**
+ * frpc binary connection mode for KADI tunnels
+ */
+export class KadiClientMode {
+
+  /**
+   * @param {Object} config
+   * @param {string} config.serverAddr - frps server hostname
+   * @param {number} config.serverPort - frps bind port (default 7000)
+   * @param {string} config.token - Authentication token
+   * @param {string} config.tunnelDomain - Tunnel subdomain host
+   */
+  constructor(config) {
+    this.serverAddr = config.serverAddr;
+    this.serverPort = config.serverPort || 7000;
+    this.token = config.token;
+    this.tunnelDomain = config.tunnelDomain;
+    this.configGenerator = new KadiConfigGenerator(config);
+  }
+
+  /**
+   * Create a tunnel via frpc binary
+   * 
+   * @param {Object} options
+   * @param {number} options.localPort - Local port to tunnel
+   * @param {string} options.subdomain - Subdomain for the tunnel
+   * @param {string} options.proxyName - Proxy name for frp dashboard
+   * @param {number} options.timeout - Connection timeout in ms
+   * @returns {Promise<ChildProcess>} The spawned frpc process
+   */
+  async connect(options) {
+    const { localPort, subdomain, proxyName, timeout } = options;
+
+    // Generate temporary config file
+    const configPath = await this.configGenerator.generate({
+      localPort,
+      subdomain,
+      proxyName,
+      tunnelId: proxyName // Use proxyName for config file naming
+    });
+
+    return new Promise((resolve, reject) => {
+      let resolved = false;
+      let frpcProcess = null;
+      let timeoutHandle = null;
+
+      console.log(`🔗 frpc binary: frpc -c ${configPath}`);
+
+      try {
+        frpcProcess = spawn('frpc', ['-c', configPath], {
+          stdio: ['pipe', 'pipe', 'pipe']
+        });
+
+        let output = '';
+        let errorOutput = '';
+
+        // --- stdout ---
+        frpcProcess.stdout.on('data', (data) => {
+          const text = data.toString();
+          output += text;
+          console.log('frpc stdout:', text.trim());
+
+          if (!resolved && KadiOutputParser.isFrpcConnected(output)) {
+            resolved = true;
+            if (timeoutHandle) clearTimeout(timeoutHandle);
+            resolve(frpcProcess);
+          }
+        });
+
+        // --- stderr ---
+        frpcProcess.stderr.on('data', (data) => {
+          const text = data.toString();
+          errorOutput += text;
+          console.log('frpc stderr:', text.trim());
+
+          // Check for auth failure
+          if (KadiOutputParser.isAuthFailure(text)) {
+            if (!resolved) {
+              resolved = true;
+              if (timeoutHandle) clearTimeout(timeoutHandle);
+              frpcProcess.kill('SIGTERM');
+              reject(new AuthenticationFailedError('Token authentication failed'));
+            }
+          }
+        });
+
+        // --- process error ---
+        frpcProcess.on('error', (error) => {
+          if (!resolved) {
+            resolved = true;
+            if (timeoutHandle) clearTimeout(timeoutHandle);
+
+            if (error.code === 'ENOENT') {
+              reject(new PermanentTunnelError('frpc binary not found in PATH. Install frpc or use SSH mode.'));
+            } else {
+              reject(new TransientTunnelError(`frpc process error: ${error.message}`, error));
+            }
+          }
+        });
+
+        // --- process exit ---
+        frpcProcess.on('exit', (code) => {
+          if (!resolved) {
+            resolved = true;
+            if (timeoutHandle) clearTimeout(timeoutHandle);
+
+            const msg = `frpc exited with code ${code}. Output: ${errorOutput || output}`;
+            reject(new TransientTunnelError(msg));
+          }
+        });
+
+        // --- timeout ---
+        timeoutHandle = setTimeout(() => {
+          if (!resolved) {
+            resolved = true;
+            if (frpcProcess) frpcProcess.kill('SIGTERM');
+            reject(new ConnectionTimeoutError('frpc', timeout));
+          }
+        }, timeout);
+
+      } catch (error) {
+        if (!resolved) {
+          resolved = true;
+          if (timeoutHandle) clearTimeout(timeoutHandle);
+          reject(new TransientTunnelError(`Failed to spawn frpc: ${error.message}`, error));
+        }
+      }
+    });
+  }
+
+  /**
+   * Clean up the temporary config file for a tunnel
+   * @param {string} tunnelId 
+   */
+  async cleanupConfig(tunnelId) {
+    await this.configGenerator.cleanup(tunnelId);
+  }
+}

package/src/KadiConfigGenerator.js

@@ -0,0 +1,112 @@
+/**
+ * @fileoverview Generates temporary frpc TOML configuration files
+ * 
+ * Each tunnel gets its own config file at /tmp/frpc-{tunnelId}.toml
+ * which is cleaned up when the tunnel is disconnected.
+ */
+
+import { promises as fs } from 'fs';
+import path from 'path';
+import os from 'os';
+
+/**
+ * Generates per-tunnel frpc configuration files
+ */
+export class KadiConfigGenerator {
+
+  /**
+   * @param {Object} config
+   * @param {string} config.serverAddr - frps server hostname
+   * @param {number} config.serverPort - frps bind port
+   * @param {string} config.token - Authentication token
+   * @param {string} config.tunnelDomain - Tunnel subdomain host
+   */
+  constructor(config) {
+    this.serverAddr = config.serverAddr;
+    this.serverPort = config.serverPort || 7000;
+    this.token = config.token;
+    this.tunnelDomain = config.tunnelDomain;
+    this.configDir = os.tmpdir();
+  }
+
+  /**
+   * Generate a TOML config file for a tunnel
+   * 
+   * @param {Object} options
+   * @param {number} options.localPort - Local port to tunnel
+   * @param {string} options.subdomain - Subdomain for the tunnel
+   * @param {string} options.proxyName - Proxy name
+   * @param {string} options.tunnelId - Tunnel identifier (for file naming)
+   * @returns {Promise<string>} Path to the generated config file
+   */
+  async generate(options) {
+    const { localPort, subdomain, proxyName, tunnelId } = options;
+    const configPath = path.join(this.configDir, `frpc-${tunnelId}.toml`);
+
+    const toml = this._buildToml(localPort, subdomain, proxyName);
+
+    await fs.writeFile(configPath, toml, 'utf8');
+    console.log(`📝 Generated frpc config: ${configPath}`);
+
+    return configPath;
+  }
+
+  /**
+   * Remove a tunnel's config file
+   * @param {string} tunnelId 
+   */
+  async cleanup(tunnelId) {
+    const configPath = path.join(this.configDir, `frpc-${tunnelId}.toml`);
+    try {
+      await fs.unlink(configPath);
+      console.log(`🗑️  Cleaned up frpc config: ${configPath}`);
+    } catch (error) {
+      if (error.code !== 'ENOENT') {
+        console.warn(`Warning: Failed to clean up ${configPath}:`, error.message);
+      }
+    }
+  }
+
+  /**
+   * Build the TOML configuration string
+   * 
+   * Uses `subdomain` instead of `customDomains` because frps has
+   * `subDomainHost` configured. Using customDomains for a domain
+   * that belongs to the subdomain host is rejected by frps.
+   * 
+   * @param {number} localPort 
+   * @param {string} subdomain 
+   * @param {string} proxyName 
+   * @returns {string} TOML configuration content
+   * @private
+   */
+  _buildToml(localPort, subdomain, proxyName) {
+    const fullDomain = `${subdomain}.${this.tunnelDomain}`;
+    return `# Auto-generated by KĀDI Tunnel Service
+# Tunnel: ${proxyName}
+# Domain: ${fullDomain}
+
+serverAddr = "${this.serverAddr}"
+serverPort = ${this.serverPort}
+
+auth.method = "token"
+auth.token = "${this.token}"
+
+# Logging
+log.to = "console"
+log.level = "info"
+
+# Auto-reconnect
+loginFailExit = false
+transport.heartbeatInterval = 30
+transport.heartbeatTimeout = 90
+
+[[proxies]]
+name = "${proxyName}"
+type = "http"
+localIP = "127.0.0.1"
+localPort = ${localPort}
+subdomain = "${subdomain}"
+`;
+  }
+}

package/src/KadiOutputParser.js

@@ -0,0 +1,138 @@
+/**
+ * @fileoverview Output parser for frp SSH gateway and frpc binary output
+ * 
+ * Parses stdout/stderr from both SSH gateway mode and frpc binary mode
+ * to detect connection success, authentication failures, and errors.
+ */
+
+/**
+ * Static utility class for parsing tunnel process output
+ */
+export class KadiOutputParser {
+
+  /**
+   * Check if SSH gateway output indicates successful connection
+   * 
+   * Expected SSH gateway output:
+   *   frp (via SSH) (Ctrl+C to quit)
+   *   User:
+   *   ProxyName: agent-abc-tunnel-1
+   *   Type: http
+   *   RemoteAddress: :80
+   * 
+   * @param {string} output - Combined stdout/stderr output
+   * @returns {boolean} True if connection is confirmed
+   */
+  static isSSHConnected(output) {
+    // Look for the frp SSH gateway confirmation pattern
+    return (
+      output.includes('frp (via SSH)') &&
+      output.includes('ProxyName:') &&
+      output.includes('Type:')
+    );
+  }
+
+  /**
+   * Check if frpc binary output indicates successful connection
+   * 
+   * Expected frpc output includes lines like:
+   *   [I] [proxy_name] start proxy success
+   *   or
+   *   start proxy success
+   * 
+   * @param {string} output - Combined stdout/stderr output
+   * @returns {boolean} True if connection is confirmed
+   */
+  static isFrpcConnected(output) {
+    return (
+      output.includes('start proxy success') ||
+      output.includes('proxy started') ||
+      output.includes('login to server success')
+    );
+  }
+
+  /**
+   * Check if output indicates an authentication failure
+   * 
+   * @param {string} output - Process output text
+   * @returns {boolean} True if auth failure detected
+   */
+  static isAuthFailure(output) {
+    const lowerOutput = output.toLowerCase();
+    return (
+      lowerOutput.includes('authorization failed') ||
+      lowerOutput.includes('auth failed') ||
+      lowerOutput.includes('token auth failed') ||
+      lowerOutput.includes('invalid token') ||
+      lowerOutput.includes('authentication failed')
+    );
+  }
+
+  /**
+   * Parse the proxy name from SSH gateway output
+   * 
+   * @param {string} output 
+   * @returns {string|null} Proxy name or null
+   */
+  static parseProxyName(output) {
+    const match = output.match(/ProxyName:\s*(.+)/);
+    return match ? match[1].trim() : null;
+  }
+
+  /**
+   * Parse the proxy type from SSH gateway output
+   * 
+   * @param {string} output 
+   * @returns {string|null} Proxy type or null
+   */
+  static parseProxyType(output) {
+    const match = output.match(/Type:\s*(.+)/);
+    return match ? match[1].trim() : null;
+  }
+
+  /**
+   * Parse the remote address from SSH gateway output
+   * 
+   * @param {string} output 
+   * @returns {string|null} Remote address or null
+   */
+  static parseRemoteAddress(output) {
+    const match = output.match(/RemoteAddress:\s*(.+)/);
+    return match ? match[1].trim() : null;
+  }
+
+  /**
+   * Extract error message from frpc output
+   * 
+   * @param {string} output 
+   * @returns {string|null} Error message or null
+   */
+  static parseError(output) {
+    // frpc error format: [E] [service.go:xxx] message
+    const match = output.match(/\[E\]\s*(?:\[[\w.]+:\d+\]\s*)?(.+)/);
+    return match ? match[1].trim() : null;
+  }
+
+  /**
+   * Check if the error indicates a duplicate proxy name
+   * 
+   * @param {string} output 
+   * @returns {boolean}
+   */
+  static isDuplicateProxy(output) {
+    return output.includes('proxy name already in use') ||
+           output.includes('proxy already exists');
+  }
+
+  /**
+   * Check if the error indicates a subdomain/custom_domain conflict
+   * This happens when --custom_domain is used for a domain that belongs
+   * to the configured subDomainHost (should use --sd instead)
+   * 
+   * @param {string} output 
+   * @returns {boolean}
+   */
+  static isSubdomainHostConflict(output) {
+    return output.includes('should not belong to subdomain host');
+  }
+}

package/src/KadiSSHMode.js

@@ -0,0 +1,191 @@
+/**
+ * @fileoverview SSH Gateway mode strategy for KadiTunnelService
+ * 
+ * Uses frp's SSH tunnel gateway feature to create tunnels via plain `ssh -R`.
+ * Zero dependency — only requires the SSH client that ships with macOS/Linux.
+ * 
+ * Pattern closely follows ServeoTunnelService.js for process management.
+ */
+
+import { spawn } from 'child_process';
+import {
+  TransientTunnelError,
+  SSHUnavailableError,
+  ConnectionTimeoutError,
+  AuthenticationFailedError
+} from '../errors.js';
+import { KadiOutputParser } from './KadiOutputParser.js';
+
+/**
+ * SSH Gateway connection mode for KADI tunnels
+ */
+export class KadiSSHMode {
+
+  /**
+   * @param {Object} config
+   * @param {string} config.serverAddr - frps server hostname
+   * @param {number} config.sshPort - SSH gateway port (default 2200)
+   * @param {string} config.token - Authentication token
+   * @param {string} config.tunnelDomain - Tunnel subdomain host
+   */
+  constructor(config) {
+    this.serverAddr = config.serverAddr;
+    this.sshPort = config.sshPort || 2200;
+    this.token = config.token;
+    this.tunnelDomain = config.tunnelDomain;
+  }
+
+  /**
+   * Create a tunnel via SSH gateway
+   * 
+   * @param {Object} options
+   * @param {number} options.localPort - Local port to tunnel
+   * @param {string} options.subdomain - Subdomain for the tunnel
+   * @param {string} options.proxyName - Proxy name for frp dashboard
+   * @param {number} options.timeout - Connection timeout in ms
+   * @returns {Promise<ChildProcess>} The spawned SSH process
+   */
+  connect(options) {
+    const { localPort, subdomain, proxyName, timeout } = options;
+
+    return new Promise((resolve, reject) => {
+      let resolved = false;
+      let sshProcess = null;
+      let timeoutHandle = null;
+
+      const sshArgs = this._buildSSHArgs(localPort, subdomain, proxyName);
+      console.log(`🔗 SSH gateway: ssh ${sshArgs.join(' ')}`);
+
+      try {
+        sshProcess = spawn('ssh', sshArgs, {
+          stdio: ['pipe', 'pipe', 'pipe']
+        });
+
+        let output = '';
+        let errorOutput = '';
+
+        // --- stdout ---
+        sshProcess.stdout.on('data', (data) => {
+          const text = data.toString();
+          output += text;
+          console.log('kadi-ssh stdout:', text.trim());
+
+          if (!resolved && KadiOutputParser.isSSHConnected(output)) {
+            resolved = true;
+            if (timeoutHandle) clearTimeout(timeoutHandle);
+            resolve(sshProcess);
+          }
+        });
+
+        // --- stderr ---
+        sshProcess.stderr.on('data', (data) => {
+          const text = data.toString();
+          errorOutput += text;
+          output += text;
+          console.log('kadi-ssh stderr:', text.trim());
+
+          // Check for auth failure
+          if (KadiOutputParser.isAuthFailure(text)) {
+            if (!resolved) {
+              resolved = true;
+              if (timeoutHandle) clearTimeout(timeoutHandle);
+              sshProcess.kill('SIGTERM');
+              reject(new AuthenticationFailedError('Token authentication failed'));
+            }
+            return;
+          }
+
+          if (!resolved && KadiOutputParser.isSSHConnected(output)) {
+            resolved = true;
+            if (timeoutHandle) clearTimeout(timeoutHandle);
+            resolve(sshProcess);
+          }
+        });
+
+        // --- process error (e.g., ENOENT = ssh not found) ---
+        sshProcess.on('error', (error) => {
+          if (!resolved) {
+            resolved = true;
+            if (timeoutHandle) clearTimeout(timeoutHandle);
+
+            if (error.code === 'ENOENT') {
+              reject(new SSHUnavailableError());
+            } else {
+              reject(new TransientTunnelError(`SSH process error: ${error.message}`, error));
+            }
+          }
+        });
+
+        // --- process exit ---
+        sshProcess.on('exit', (code) => {
+          if (!resolved) {
+            resolved = true;
+            if (timeoutHandle) clearTimeout(timeoutHandle);
+
+            const msg = `SSH tunnel exited with code ${code}. Output: ${errorOutput || output}`;
+            reject(new TransientTunnelError(msg));
+          }
+        });
+
+        // --- timeout ---
+        timeoutHandle = setTimeout(() => {
+          if (!resolved) {
+            resolved = true;
+            if (sshProcess) sshProcess.kill('SIGTERM');
+            reject(new ConnectionTimeoutError('kadi-ssh', timeout));
+          }
+        }, timeout);
+
+      } catch (error) {
+        if (!resolved) {
+          resolved = true;
+          if (timeoutHandle) clearTimeout(timeoutHandle);
+          reject(new TransientTunnelError(`Failed to spawn SSH: ${error.message}`, error));
+        }
+      }
+    });
+  }
+
+  /**
+   * Build SSH command arguments for the KADI SSH tunnel gateway
+   * 
+   * Command pattern:
+   *   ssh -R :80:localhost:{port} v0@{server} -p {sshPort} \
+   *     http --sd {subdomain} \
+   *     --token {token} --proxy_name {name} \
+   *     -o StrictHostKeyChecking=no -o ServerAliveInterval=30
+   * 
+   * Note: Uses --sd (subdomain) instead of --custom_domain because frps
+   * has subDomainHost configured. The frps gateway rejects --custom_domain
+   * for domains that belong to the subdomain host.
+   * 
+   * Note: Do NOT use -N flag. The frp SSH gateway sends interactive
+   * confirmation output (ProxyName, Type, RemoteAddress) that we need
+   * to parse for connection status. -N would suppress this output.
+   * 
+   * @param {number} localPort 
+   * @param {string} subdomain 
+   * @param {string} proxyName 
+   * @returns {string[]} SSH arguments array
+   * @private
+   */
+  _buildSSHArgs(localPort, subdomain, proxyName) {
+    return [
+      // SSH options MUST come before destination and remote command
+      '-o', 'StrictHostKeyChecking=no',
+      '-o', 'UserKnownHostsFile=/dev/null',
+      '-o', 'ServerAliveInterval=30',
+      '-o', 'ExitOnForwardFailure=yes',
+      // SSH reverse port forward
+      '-R', `:80:localhost:${localPort}`,
+      // Connect to frps SSH gateway as user "v0"
+      `v0@${this.serverAddr}`,
+      '-p', String(this.sshPort),
+      // frp proxy type + options (this is the remote command)
+      'http',
+      '--sd', subdomain,
+      '--token', this.token,
+      '--proxy_name', proxyName
+    ];
+  }
+}

package/src/ReconnectionManager.js

@@ -0,0 +1,132 @@
+/**
+ * @fileoverview Reconnection manager with exponential backoff
+ * 
+ * Used by KadiTunnelService to automatically retry SSH-mode tunnels
+ * when the process exits unexpectedly. frpc mode has built-in reconnect.
+ */
+
+/**
+ * Manages reconnection attempts with exponential backoff
+ */
+export class ReconnectionManager {
+
+  /**
+   * @param {Object} [options]
+   * @param {number} [options.maxRetries=5] - Maximum retry attempts
+   * @param {number} [options.baseDelay=1000] - Initial delay in ms
+   * @param {number} [options.maxDelay=30000] - Maximum delay cap in ms
+   * @param {number} [options.backoffMultiplier=2] - Backoff multiplier
+   */
+  constructor(options = {}) {
+    this.maxRetries = options.maxRetries ?? 5;
+    this.baseDelay = options.baseDelay ?? 1000;
+    this.maxDelay = options.maxDelay ?? 30000;
+    this.backoffMultiplier = options.backoffMultiplier ?? 2;
+
+    this._attempt = 0;
+    this._stopped = false;
+    this._currentTimeout = null;
+    this._waitResolve = null; // Reference to current _wait() resolver for cancellation
+  }
+
+  /**
+   * Retry a function with exponential backoff
+   * 
+   * @param {Function} fn - Async function to retry (should return a result on success)
+   * @returns {Promise<*>} Result of the successful function call
+   * @throws {Error} After max retries exhausted
+   */
+  async retry(fn) {
+    this._attempt = 0;
+    this._stopped = false;
+
+    while (this._attempt < this.maxRetries && !this._stopped) {
+      this._attempt++;
+      const delay = this._calculateDelay(this._attempt);
+
+      console.log(`🔄 Reconnection attempt ${this._attempt}/${this.maxRetries} (delay: ${delay}ms)`);
+
+      // Wait before retrying
+      await this._wait(delay);
+
+      if (this._stopped) break;
+
+      try {
+        const result = await fn();
+        console.log(`✅ Reconnection succeeded on attempt ${this._attempt}`);
+        this._attempt = 0; // Reset on success
+        return result;
+      } catch (error) {
+        console.warn(`⚠️  Reconnection attempt ${this._attempt} failed: ${error.message}`);
+
+        if (this._attempt >= this.maxRetries) {
+          throw new Error(`Reconnection failed after ${this.maxRetries} attempts. Last error: ${error.message}`);
+        }
+      }
+    }
+
+    throw new Error('Reconnection stopped');
+  }
+
+  /**
+   * Stop any in-progress reconnection
+   */
+  stop() {
+    this._stopped = true;
+    if (this._currentTimeout) {
+      clearTimeout(this._currentTimeout);
+      this._currentTimeout = null;
+    }
+    // Resolve any pending _wait() promise so retry() can exit
+    if (this._waitResolve) {
+      this._waitResolve();
+      this._waitResolve = null;
+    }
+  }
+
+  /**
+   * Get current attempt count
+   * @returns {number}
+   */
+  get attempt() {
+    return this._attempt;
+  }
+
+  /**
+   * Check if reconnection is active
+   * @returns {boolean}
+   */
+  get isActive() {
+    return this._attempt > 0 && !this._stopped;
+  }
+
+  /**
+   * Calculate delay for a given attempt using exponential backoff
+   * Sequence: 1s → 2s → 4s → 8s → 16s → 30s (capped)
+   * 
+   * @param {number} attempt - Attempt number (1-based)
+   * @returns {number} Delay in ms
+   * @private
+   */
+  _calculateDelay(attempt) {
+    const delay = this.baseDelay * Math.pow(this.backoffMultiplier, attempt - 1);
+    return Math.min(delay, this.maxDelay);
+  }
+
+  /**
+   * Wait for a specified duration (cancellable)
+   * @param {number} ms 
+   * @returns {Promise<void>}
+   * @private
+   */
+  _wait(ms) {
+    return new Promise((resolve) => {
+      this._waitResolve = resolve;
+      this._currentTimeout = setTimeout(() => {
+        this._currentTimeout = null;
+        this._waitResolve = null;
+        resolve();
+      }, ms);
+    });
+  }
+}

package/src/index.js

@@ -0,0 +1,13 @@
+/**
+ * @fileoverview @kadi/tunnel-client — package entry point
+ *
+ * Exports the supporting classes and utilities used by KadiTunnelService.
+ * KadiTunnelService itself is a standalone drop-in file (not part of this package).
+ */
+
+export { KadiSSHMode } from './KadiSSHMode.js';
+export { KadiClientMode } from './KadiClientMode.js';
+export { KadiConfigGenerator } from './KadiConfigGenerator.js';
+export { KadiOutputParser } from './KadiOutputParser.js';
+export { ReconnectionManager } from './ReconnectionManager.js';
+export { detectFrpcBinary, generateSubdomain } from './utils.js';

package/src/utils.js

@@ -0,0 +1,76 @@
+/**
+ * @fileoverview Utility functions for KadiTunnelService
+ */
+
+import { execSync } from 'child_process';
+import crypto from 'crypto';
+
+/**
+ * Detect if the `frpc` binary is available in PATH
+ * 
+ * @returns {Promise<boolean>} True if frpc is available
+ */
+export async function detectFrpcBinary() {
+  try {
+    execSync('command -v frpc', { stdio: 'pipe' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Detect if the `ssh` command is available in PATH
+ * 
+ * @returns {Promise<boolean>} True if ssh is available
+ */
+export async function detectSSHBinary() {
+  try {
+    execSync('command -v ssh', { stdio: 'pipe' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Generate a random subdomain string
+ * Produces a short, URL-safe identifier like "a7b3x9"
+ * 
+ * @param {number} [length=8] - Length of the subdomain
+ * @returns {string} Random subdomain
+ */
+export function generateSubdomain(length = 8) {
+  // Use lowercase alphanumeric characters (DNS-safe)
+  const bytes = crypto.randomBytes(Math.ceil(length * 3 / 4));
+  return bytes
+    .toString('base64url')
+    .slice(0, length)
+    .toLowerCase()
+    .replace(/[^a-z0-9]/g, 'x'); // Ensure DNS-safe characters only
+}
+
+/**
+ * Validate a subdomain string for DNS compatibility
+ * 
+ * @param {string} subdomain 
+ * @returns {boolean} True if valid
+ */
+export function isValidSubdomain(subdomain) {
+  // DNS label rules: lowercase alphanumeric + hyphens, 1-63 chars, no leading/trailing hyphen
+  return /^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$/.test(subdomain);
+}
+
+/**
+ * Get the frpc binary version (if available)
+ * 
+ * @returns {string|null} Version string or null
+ */
+export function getFrpcVersion() {
+  try {
+    const output = execSync('frpc --version', { stdio: 'pipe', encoding: 'utf8' });
+    return output.trim();
+  } catch {
+    return null;
+  }
+}