Class SSHTunnel

src/utils/ssh-tunnel.ts:12–376

 * Supports ProxyJump for multi-hop SSH connections through bastion/jump hosts.
 */
export class SSHTunnel {
  private sshClients: Client[] = []; // All SSH clients in the chain
  private localServer: Server | null = null;
  private tunnelInfo: SSHTunnelInfo | null = null;
  private isConnected: boolean = false;

  /**
   * Establish an SSH tunnel, optionally through jump hosts (ProxyJump).
   * @param config SSH connection configuration
   * @param options Tunnel options including target host and port
   * @returns Promise resolving to tunnel information including local port
   */
  async establish(
    config: SSHTunnelConfig,
    options: SSHTunnelOptions
  ): Promise<SSHTunnelInfo> {
    if (this.isConnected) {
      throw new Error('SSH tunnel is already established');
    }

    // Set isConnected immediately to prevent concurrent calls
    this.isConnected = true;

    try {
      // Use the fully-resolved jump-host chain when available (per-hop config/auth
      // from ~/.ssh/config); otherwise fall back to literal ProxyJump parsing.
      const jumpHosts = config.resolvedJumpHosts
        ?? (config.proxyJump ? parseJumpHosts(config.proxyJump) : []);

      // Read the target's private key once.
      const privateKeyBuffer = config.privateKey ? this.loadPrivateKey(config.privateKey) : undefined;

      // Validate authentication
      if (!config.password && !privateKeyBuffer) {
        throw new Error('Either password or privateKey must be provided for SSH authentication');
      }

      // Establish the SSH connection chain
      const finalClient = await this.establishChain(jumpHosts, config, privateKeyBuffer);

      // Create local server for the tunnel
      return await this.createLocalTunnel(finalClient, options);
    } catch (error) {
      this.cleanup();
      throw error;
    }
  }

  /**
   * Load an SSH private key, supporting both a file path (with symlink resolution)
   * and base64-encoded key content.
   */
  private loadPrivateKey(key: string): Buffer {
    try {
      const resolvedKeyPath = resolveSymlink(key);
      return readFileSync(resolvedKeyPath);
    } catch {
      // Not a readable file — try base64 decode