Feature Request: SSH Proxy/Jump Host Support

[billchurch]

Feature Description

Add support for SSH proxy/jump hosts (bastion hosts) to allow WebSSH2 to connect to target servers through intermediate SSH servers. This is a critical feature for accessing servers in private networks or behind firewalls.

Background

PR #365 attempted to implement this feature but needs significant improvements and the codebase has evolved considerably since then. This issue captures the requirements for a proper implementation.

Use Cases

1. Bastion Host Access: Connect to internal servers through a bastion/jump host
2. Multi-hop Connections: Chain multiple SSH connections to reach deeply nested infrastructure
3. Security Compliance: Many organizations require all SSH access to go through audited jump servers
4. Cloud Infrastructure: Access private cloud instances through public-facing gateways

Proposed Implementation

Configuration Options

Support both global and per-connection proxy settings:

// Global proxy configuration in config.json
{
  "ssh": {
    "proxy": {
      "enabled": false,
      "type": "ssh|socks5|http",  // Proxy type
      "host": "proxy.example.com",
      "port": 22,
      "username": "proxyuser",
      "auth": {
        "type": "password|publickey|agent|keyboard-interactive",
        "password": "...",
        "privateKey": "/path/to/key",
        "passphrase": "..."
      },
      "keepalive": 60000,
      "readyTimeout": 20000
    }
  }
}

Per-Connection Proxy (via URL params or form)

/ssh/host/target.internal?proxy=bastion.example.com&proxyUser=admin

Multi-hop Support (ProxyJump style)

{
  "proxy": {
    "chain": [
      { "host": "jump1.example.com", "user": "user1" },
      { "host": "jump2.example.com", "user": "user2" }
    ]
  }
}

Technical Requirements

Core Functionality

• Support SSH tunnel through proxy using forwardOut() method
• Support both password and public key authentication for proxy
• Support SSH agent forwarding through proxy
• Implement proper connection lifecycle management
• Handle proxy connection errors gracefully
• Support connection timeout configuration

Authentication Methods

• Password authentication
• Public key authentication (with encrypted key support)
• SSH agent authentication
• Keyboard-interactive authentication
• Certificate-based authentication

Advanced Features

• ProxyCommand support: Execute custom commands for establishing proxy connection
• ProxyJump support: OpenSSH-style jump host configuration
• SOCKS proxy support: Connect through SOCKS4/SOCKS5 proxies
• HTTP CONNECT proxy support: For corporate environments
• Dynamic proxy selection: Choose proxy based on target host
• Proxy authentication caching: Reuse proxy connections for multiple targets
• Connection pooling: Maintain persistent proxy connections

Security Considerations

• Validate all proxy configuration parameters
• Implement rate limiting for proxy connections
• Audit logging for proxy connections
• Support for proxy allowlist/blocklist
• Secure storage of proxy credentials
• Support for MFA on proxy connections

UI/UX Enhancements

• Visual indicator when connected through proxy
• Display proxy chain in connection info
• Allow proxy configuration in connection dialog
• Save proxy preferences per host
• Test proxy connection feature

Implementation Notes

From PR #365 Analysis

The original PR used a basic approach with ssh2.forwardOut() but had several issues:

• Hardcoded values and debug statements
• No password authentication support for proxy
• Memory management issues (unnecessary connection object creation)
• Synchronous file operations blocking event loop
• Limited error handling

Recommended Approach

1. Create a separate ProxyManager class to handle proxy connections
2. Implement connection pooling for efficiency
3. Use async/await patterns for better error handling
4. Add comprehensive configuration validation
5. Support OpenSSH config file format for familiarity
6. Implement proper cleanup on disconnection

Testing Requirements

• Unit tests for proxy connection logic
• Integration tests with actual SSH servers
• Test multiple authentication methods
• Test connection failure scenarios
• Test multi-hop configurations
• Performance testing with connection pooling
• Security testing for credential handling

Documentation Needs

• Configuration examples for common scenarios
• Migration guide for OpenSSH ProxyJump users
• Troubleshooting guide for proxy issues
• Security best practices
• Performance tuning guide

References

• OpenSSH ProxyJump documentation: https://www.openssh.com/txt/release-7.3
• SSH2 forwardOut documentation: https://github.com/mscdex/ssh2#client-methods
• Original PR Added initial support ssh proxy #365 for initial implementation ideas

Success Criteria

• Users can connect to internal servers through bastion hosts
• Support for common enterprise proxy configurations
• Performance comparable to native SSH clients
• Clear error messages for connection issues
• Secure handling of proxy credentials

---

This feature request is based on the analysis of PR #365 and current architectural requirements for the WebSSH2 v2.0 rewrite.