Required dependencies

npm install asn1 bcrypt-pbkdf

No native build steps are required for core operation. An optional cpu-features native addon may be installed to improve cipher selection performance; if it fails to build it is silently ignored:

npm install cpu-features   # optional; requires a C++ build toolchain (node-gyp)

Project setup

1. Copy the source/ directory into your project, e.g. src/vendor/ssh2/.
2. There are no TypeScript declarations bundled; install community types if needed:

   npm install --save-dev @types/ssh2
   

3. In tsconfig.json add a path alias if desired:

   {
     "compilerOptions": {
       "paths": {
         "ssh2": ["./src/vendor/ssh2/index.js"]
       }
     }
   }
   

4. The source is CJS (require-based). In an ESM project use dynamic import() or set "type": "commonjs" in the nearest package.json.
5. No environment variables are required. Pass all connection parameters programmatically.
6. For SFTP file-flag helpers, import from the nested utils.sftp namespace exposed by index.js.

Public API

Client

import { Client } from './src/vendor/ssh2/index.js';

const conn = new Client();
conn.connect(config: ConnectConfig): void;
conn.exec(command: string, options?: ExecOptions, callback: (err, stream) => void): boolean;
conn.shell(options?: PseudoTtyOptions | false, callback: (err, stream) => void): boolean;
conn.sftp(callback: (err, sftp: SFTPWrapper) => void): boolean;
conn.end(): void;
// Events: 'ready', 'error', 'close', 'keyboard-interactive', 'tcp/ip forward', ...

Client is the primary class for outbound SSH connections. Instantiate it, attach a ready listener, then call connect() with host/port/credentials. All channel-opening methods (exec, shell, sftp, forwardOut, etc.) must be called inside the ready handler.

Server

import { Server } from './src/vendor/ssh2/index.js';

const srv = new Server(options: ServerConfig, connectionListener?: (client, info) => void);
srv.listen(port: number, host?: string, callback?: () => void): Server;
srv.close(callback?: () => void): void;
// Connection events: 'authentication', 'ready', 'session', 'request', 'tcpip', ...

Server accepts inbound SSH connections. Supply at least one host key in options.hostKeys. Handle the connection event (or pass a listener to the constructor) to receive Client connection objects, then subscribe to authentication to validate credentials and session to handle channel requests.

utils.parseKey

import { utils } from './src/vendor/ssh2/index.js';

utils.parseKey(keyData: string | Buffer, passphrase?: string | Buffer):
  ParsedKey | ParsedKey[] | Error | null;

Parses PEM, PKCS#8, or OpenSSH-format public or private keys. Returns a ParsedKey object (or array for files containing multiple keys) with .sign(), .verify(), .getPublicSSH(), and .equals() methods. Returns an Error instance (not thrown) on parse failure. Use this to pre-validate host keys or user public keys before passing them to connect() or an auth context.

utils.generateKeyPair / utils.generateKeyPairSync

import { utils } from './src/vendor/ssh2/index.js';

utils.generateKeyPair(
  type: 'rsa' | 'ecdsa' | 'ed25519',
  options: KeyPairOptions,
  callback: (err, keys: { private: string; public: string }) => void
): void;

utils.generateKeyPairSync(
  type: 'rsa' | 'ecdsa' | 'ed25519',
  options: KeyPairOptions
): { private: string; public: string };

Generates SSH key pairs in OpenSSH wire format. RSA requires { bits: number }, ECDSA requires { bits: 256 | 384 | 521 }, Ed25519 takes no extra options. Use for automated key provisioning or test fixtures.

Working examples

Scenario - Execute a remote command and capture output

Connect to a remote host with a private key, run a command, and collect stdout/stderr.

import { readFileSync } from 'fs';
import { Client } from './src/vendor/ssh2/index.js';

const conn = new Client();

conn.on('ready', () => {
  conn.exec('df -h', (err, stream) => {
    if (err) throw err;
    let stdout = '';
    let stderr = '';
    stream
      .on('close', (code: number, signal: string) => {
        console.log('exit code:', code);
        console.log('stdout:', stdout);
        console.error('stderr:', stderr);
        conn.end();
      })
      .on('data', (chunk: Buffer) => { stdout += chunk; })
      .stderr.on('data', (chunk: Buffer) => { stderr += chunk; });
  });
}).on('error', (err: Error) => {
  console.error('Connection error:', err.message);
}).connect({
  host: '10.0.0.1',
  port: 22,
  username: 'deploy',
  privateKey: readFileSync('/home/user/.ssh/id_ed25519'),
});

Scenario - Upload a file via SFTP

Open an SFTP session and write a local buffer to a remote path.

import { readFileSync } from 'fs';
import { Client } from './src/vendor/ssh2/index.js';

const conn = new Client();
const payload = Buffer.from('hello from ssh2\n');

conn.on('ready', () => {
  conn.sftp((err, sftp) => {
    if (err) throw err;
    const writeStream = sftp.createWriteStream('/tmp/hello.txt');
    writeStream.on('close', () => {
      console.log('Upload complete');
      conn.end();
    });
    writeStream.end(payload);
  });
}).connect({
  host: '10.0.0.1',
  port: 22,
  username: 'deploy',
  privateKey: readFileSync('/home/user/.ssh/id_ed25519'),
});

Scenario - Minimal SSH server with password authentication

Accept connections, validate a password, and handle an exec request.

import { readFileSync } from 'fs';
import { Server } from './src/vendor/ssh2/index.js';
import { utils } from './src/vendor/ssh2/index.js';

const hostKey = readFileSync('/etc/ssh/ssh_host_ed25519_key');

new Server({ hostKeys: [hostKey] }, (client) => {
  client.on('authentication', (ctx) => {
    if (ctx.method === 'password' && ctx.password === 'secret') {
      ctx.accept();
    } else {
      ctx.reject(['password']);
    }
  });

  client.on('ready', () => {
    client.on('session', (accept) => {
      const session = accept();
      session.on('exec', (accept, reject, info) => {
        console.log('exec:', info.command);
        const stream = accept();
        stream.stdout.write(`You ran: ${info.command}\n`);
        stream.exit(0);
        stream.close();
      });
    });
  });
}).listen(2222, '0.0.0.0', () => {
  console.log('SSH server listening on port 2222');
});

File walkthrough

• index.js - Aggregates and re-exports all public symbols; the sole import point for consumers.
• client.js - Full outbound SSH client; manages connection lifecycle, authentication, and all channel types.
• server.js - Inbound SSH server built on net.Server; exposes auth contexts and session objects.
• agent.js - SSH agent protocol client; OpenSSHAgent speaks to a UNIX socket, PageantAgent to Windows named pipe, CygwinAgent bridges the two. Extend BaseAgent for custom agents.
• http-agents.js - Drop-in http.Agent / https.Agent replacements that tunnel requests through an SSH connection using forwardOut.
• keygen.js - Wraps Node.js crypto.generateKeyPair to produce SSH-wire-format key strings with optional passphrase encryption.
• utils.js - Shared internal helpers: ChannelManager, generateAlgorithmList, isWritable, and channel-close callbacks.
• Channel.js - Duplex stream for a single SSH channel; handles windowing, extended data (stderr), and EOF/close sequencing.
• protocol/Protocol.js - Central SSH protocol state machine driving all packet I/O.
• protocol/SFTP.js - SFTP subsystem; exports OPEN_MODE, STATUS_CODE, flagsToString, stringToFlags.
• protocol/keyParser.js - Multi-format key parser supporting RSA, ECDSA, Ed25519, DSA in PEM and OpenSSH formats.
• protocol/constants.js - Numeric SSH protocol constants, algorithm name lists, disconnect reason codes.
• protocol/crypto.js - Cipher/MAC/AEAD initialisation; exports CIPHER_INFO and init.
• protocol/kex.js - Key exchange: DH, ECDH, curve25519, and KexInit negotiation.
• protocol/utils.js - Low-level buffer utilities: readUInt32BE, writeUInt32BE, makeBufferParser, sigSSHToASN1.
• protocol/zlib.js - Zlib compression/decompression for SSH transport.
• protocol/handlers.js / protocol/handlers.misc.js - Dispatch tables for inbound SSH packet types.
• protocol/node-fs-compat.js - Thin compatibility shim for Node.js fs differences across versions.
• protocol/crypto/ - Poly1305 MAC implementation and optional native C++ binding for performance.

Common pitfalls and fixes

• asn1 or bcrypt-pbkdf not found at runtime - These are runtime dependencies not bundled with Node; run npm install asn1 bcrypt-pbkdf in the project root before starting.
• parseKey returns an Error object instead of throwing - Always check if (result instanceof Error) before using the returned key; the API signals parse failure via return value, not exceptions.
• CJS require in an ESM project causes ERR_REQUIRE_ESM or syntax errors - The source is CommonJS; in ESM files use const { Client } = await import('./src/vendor/ssh2/index.js') or add "type": "commonjs" to the vendor directory's package.json.
• Host key authentication fails with "All configured authentication methods failed" - Ensure the private key file has Unix permissions 0600; readFileSync itself does not validate permissions but the remote sshd may reject connections from clients presenting keys generated from world-readable files.
• SFTP open() flags must use OPEN_MODE constants, not string literals - Import utils.sftp.OPEN_MODE and combine flags with bitwise OR: OPEN_MODE.READ | OPEN_MODE.WRITE; passing raw integers not derived from these constants causes protocol errors on some servers.
• generateKeyPairSync throws TypeError: Key type must be a string - The first argument must be the lowercase string 'rsa', 'ecdsa', or 'ed25519'; passing a capitalized or enum value is not accepted.

Vibe-coding prompt template

I have copied the ssh2 library source (ssh2@1.17.0) into `src/vendor/ssh2/`.
The integration guide is in `USAGE.md` next to this message.

Please help me integrate ssh2 into my project step by step:

1. Read `USAGE.md` and the file walkthrough to understand what each file in
   `src/vendor/ssh2/` does.
2. Add the required runtime dependencies (`asn1`, `bcrypt-pbkdf`) to
   `package.json` and provide the install command.
3. Import `Client` and/or `Server` from `src/vendor/ssh2/index.js` (not from
   the npm registry) in the file I specify.
4. Write a working example for my use case (described below) using only the
   real exports visible in USAGE.md: Client, Server, utils.parseKey,
   utils.generateKeyPair, utils.sftp.OPEN_MODE, HTTPAgent, HTTPSAgent,
   AgentProtocol, BaseAgent, OpenSSHAgent.
5. Do not invent methods or options not documented in USAGE.md or visible in
   the source excerpts.
6. Flag any CJS/ESM interop issues for my module system.

My use case:
[DESCRIBE YOUR USE CASE HERE - e.g. "connect to a remote server, run a
command, and stream output to an HTTP response"]

License and credit

ssh2 is released under the MIT License. See source/LICENSE if present, or refer to the upstream repository. Original package: ssh2 on npm by Brian White (mscdex), version 1.17.0.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

完整安装指南与集成提示词将在购买后解锁。

Automation, Utilities & Developer Tools

免费