ssh2

ssh2 is a pure-JavaScript implementation of the SSH2 protocol for Node.js, providing both client and server capabilities without shelling out to system SSH binaries. It supports command execution, interactive shells, SFTP file transfer, local/remote/dynamic TCP forwarding, X11 forwarding, and custom subsystems, all through an EventEmitter-based API built directly on top of Node’s net.Socket.

Because it implements the wire protocol itself — key exchange, ciphers, MACs, compression, and authentication — ssh2 gives applications fine-grained control over connection behavior (algorithm negotiation, host key verification, keyboard-interactive auth) that shelling out to the OpenSSH client can’t offer, making it a common building block for remote automation tools, deployment scripts, and SFTP-backed file services.

What You Get

• A Client class for connecting to SSH servers with exec, shell, SFTP, and forwarding support
• A Server class for building SSH-accessible services (custom shells, git-over-ssh, SFTP endpoints)
• A full SFTP protocol implementation for uploads, downloads, and directory operations
• Key generation and parsing utilities supporting RSA, ED25519, and ECDSA formats
• HTTPAgent/HTTPSAgent classes that tunnel Node’s http/https clients through an SSH connection
• Building blocks for dynamic (SOCKS-style) and remote port forwarding, plus X11 forwarding

Common Use Cases

• Automating remote server administration — running commands, checking status, deploying code
• Building SFTP-backed file transfer, sync, or backup services
• Implementing a custom SSH-accessible CLI or git-over-ssh style server
• Tunneling HTTP requests or arbitrary TCP traffic over an SSH connection
• Chaining connections through jump/bastion hosts to reach hosts on private networks

Under The Hood

Architecture ssh2 is layered around lib/protocol/Protocol.js, a low-level state machine that frames and parses SSH2 binary packets, sitting directly on Node’s net.Socket. Above it, lib/protocol/kex.js and lib/protocol/crypto.js handle key exchange, cipher/MAC negotiation, and encryption using Node’s crypto module (with an optional native cpu-features addon compiled via node-gyp to pick optimal ciphers). lib/client.js and lib/server.js wrap the protocol layer in EventEmitter-based Client/Server classes that expose high-level operations (exec, shell, forwardOut, sftp), while lib/Channel.js implements SSH channel multiplexing (window sizing, flow control) shared by both exec/shell streams and forwarded connections. The SFTP subsystem is its own protocol implementation in lib/protocol/SFTP.js (4,000+ lines) layered on top of a channel, and lib/agent.js separately implements the SSH agent protocol (OpenSSH, Pageant, Cygwin variants) for forwarded-agent authentication.

Tech Stack The library is written entirely in plain JavaScript (CommonJS, no TypeScript) targeting Node.js >=16, with only two runtime dependencies (asn1, bcrypt-pbkdf) and two optional native dependencies (cpu-features, nan) that are compiled at install time via install.js/node-gyp but degrade gracefully to pure-JS crypto if the build fails. There’s no bundler or build step for the library itself since it ships as-is for Node consumption; linting is handled by a shared @mscdex/eslint-config ESLint setup.

Code Quality The test/ directory contains a substantial, protocol-focused suite driven by a custom test/test.js orchestrator, with dedicated files for SFTP (test-sftp.js), key generation, protocol crypto, key parsing, user auth, server host keys, and even integration tests that exercise a real OpenSSH server (test-integration-openssh.js, test-openssh.js). Error handling favors explicit err callback arguments and emitted 'error' events over exceptions, consistent with Node’s streams/EventEmitter conventions, and naming is consistent across the client/server halves of the API (mirrored method and event names).

API Design The public surface follows familiar Node idioms — Client and Server extend EventEmitter, connections resolve via a 'ready' event, and operations like exec/shell/sftp use Node-style (err, stream) callbacks rather than promises, which keeps it consistent with older Node APIs but means promise/async-await usage requires manual wrapping. The README (70KB+) and separate SFTP.md document nearly every event, method, and option exhaustively with runnable examples for common scenarios (exec, shell, forwarding, SFTP, connection hopping, X11), which lowers the ramp-up cost despite the library’s large surface area and lack of bundled TypeScript definitions (community @types/ssh2 fills that gap separately).