modernssh

A typed, ESM-native SSH client and server library for Node.js.

The project implements SSH from its standards and includes typed client, server, channel, forwarding, agent, key-management, and SFTP APIs. Public asynchronous operations return Promises; awaited application policy is handled through Hooker.

Install the package from the public npm registry:

pnpm add @bunkerch/modernssh

Quick start

This example verifies the server against the user's known-hosts file, authenticates, runs a command, and waits for the channel to close:

import { once } from "node:events"
import { homedir } from "node:os"
import { join } from "node:path"
import { Client, KnownHosts } from "@bunkerch/modernssh"

const hostname = "ssh.example.com"
const knownHosts = await KnownHosts.load(join(homedir(), ".ssh", "known_hosts"))
const client = new Client({
    hostname,
    username: "deploy",
    password: process.env.SSH_PASSWORD,
    hostVerifier: knownHosts.verifier(hostname),
})

client.on("error", (error) => console.error("SSH connection error", error))

try {
    await client.connect()
    const command = await client.exec("uname -a")
    command.pipe(process.stdout)
    command.stderr.pipe(process.stderr)
    await once(command, "close")
} finally {
    client.end()
}

EventEmitter listeners are observation-only and should remain synchronous. Authorization and other asynchronous policy decisions belong in awaited Hooker handlers.

Documentation

Goal	Guide
Connect a client or create a server	Getting started
Copy practical recipes	Examples
Look up every package export and its exact TypeScript declaration	API reference
Configure authentication and multi-factor flows	Authentication
Run commands, shells, and subsystems	Channels
Transfer and manage files	SFTP
Create direct, remote, HTTP, and tunnel forwarding	Forwarding and packet tunnels
Verify and rotate host keys	Known hosts
Use or expose an authentication agent	Agent protocol
Check implemented standards and tested peers	Standards coverage and interoperability

Protocol-level and specialist guides cover transport behavior, connection-wide requests, public-key management, key revocation lists, and detached signatures.

Development

pnpm install
pnpm test
pnpm lint
pnpm format:check
pnpm docs:api
pnpm docs:dev
pnpm docs:build

pnpm test builds the distributable entry point before running unit and integration tests. pnpm docs:api rebuilds the package and regenerates the complete declaration reference under docs/api/. pnpm docs:dev starts the local Fumadocs site, and pnpm docs:build verifies the production documentation build. The documentation toolchain requires Node.js 22 or newer; the published library continues to support Node.js 20.