SSH Connection Pool & Host Verification

[hellodk]

SSH Connection Pool & Host Verification

Description

Implement an SSH connection pool to reuse connections across multiple operations, and add robust host verification to ensure secure connections to known hosts. This prevents connection exhaustion and adds security guards against MITM attacks.

Business Value

• Performance: Reusing SSH connections reduces latency for sequential operations on the same host
• Resource efficiency: Prevents connection leaks and port exhaustion
• Security: Host key verification prevents MITM attacks and validates known_hosts
• Reliability: Automatic connection recovery and cleanup on failure

Acceptance Criteria

• SSH connection pool maintains a pool of open connections per (host, port, user) tuple
• Pool size is configurable with sensible defaults (max 10 connections per host)
• Connections are reused for multiple operations within a timeout window (default 5 min)
• Idle connections are automatically closed after TTL expiration
• Pool emits telemetry: pool size, connection reuse rate, cache hit/miss
• Host verification checks against ~/.ssh/known_hosts before connecting
• Unknown hosts prompt user for acceptance (accept once, accept permanently, reject)
• Host key mismatch is detected and raises an error with clear messaging
• Connection failures trigger automatic pool eviction and backoff retry logic
• Pool handles graceful shutdown (close all connections) on extension deactivation
• Configuration: champ.ssh.poolMaxConnections, champ.ssh.connectionIdleTimeoutSeconds, champ.ssh.verifyHostKey

Tests Required

• Unit: connection pool state management (add, get, remove, evict)
• Unit: pool LRU eviction when max connections exceeded
• Unit: host key verification against known_hosts file
• Unit: host key mismatch detection
• Unit: connection idle timeout tracking
• Integration: two operations reuse same connection from pool
• Integration: unknown host prompt correctly adds to known_hosts
• Integration: pool evicts connection on SSH error and allows reconnect
• Integration: pool cleanup on extension deactivation closes all connections
• Integration: telemetry events emit correct pool metrics
• E2E: user connects to new host, accepts key, connection is cached in known_hosts
• E2E: user attempts to connect to host with mismatched key, receives error and can reject

Implementation Notes

• Base pool on ssh2 client library connection management
• Store known_hosts in ~/.ssh/known_hosts standard format for interoperability
• Pool key: {host}:{port}@{user} for uniqueness
• Connection validation: send a no-op command before reusing from pool
• Telemetry fields: poolSize, reuseCount, evictionCount, verifyStatus (accepted/rejected/mismatch)
• Consider async connection establishment to avoid blocking the UI
• Host verification should be skippable via config for testing/air-gapped environments (default: required)

Related Issues

• SSH Config Storage & Workspace UI #73 SSH Config Storage & Workspace UI
• Persistent checkpoint & session history #72 Persistent checkpoint & session history

Environment

• VS Code 1.95+
• All platforms (Windows, macOS, Linux)
• Requires ssh2 npm package