ssh2-sftp-client

The ssh2-sftp-client package provides a high-level, promise-based SftpClient class for Node.js. It acts as a wrapper around the ssh2 library, which is a pure JavaScript event-based SSH2 implementation.

Because this package is a decorator for ssh2, many of the underlying configuration options and behaviors are inherited from the ssh2 project. For deep technical details on SSH2 protocols or specific low-level options, refer to the ssh2 documentation.

Because ssh2-sftp-client provides a Promise-based API over an event-based module (SSH2), it uses internal strategies to manage asynchronous events like error, end, and close:

• Promise Management: When a method is called, the client attaches listeners to these events to reject the enclosing promise. It tracks if an error has already been handled to ignore subsequent, less informative errors.
• Connection Delays: A small delay (approx. 500ms) is used during connect() to ensure all late-firing events are caught before handlers are removed.
• Termination: The end() method sets up listeners to ignore additional events during connection teardown.
• Global Handlers: Global handlers catch unhandled events, reset the sftp property, and log errors to the console to prevent script crashes.

The fastPut() and fastGet() methods are significantly faster than put() and get() when they work, but they are highly dependent on SFTP server capabilities. Some servers struggle with concurrent connections or specific packet sizes.

If you are developing code that must run against various unknown SFTP servers, consider:

1. Using the standard get() and put() methods for better compatibility.
2. Providing an option for users to choose the method.
3. Tweaking options like the number of concurrent connections or specific packet sizes if issues arise.

While you can mix Promise chains (.then()) and async/await, it is highly discouraged as it creates complex, bug-prone code. A common bug occurs when an await call is made inside a .then() block without returning the resulting promise, causing the chain to proceed to .finally() or the next .then() before the awaited task is finished.

Choose one paradigm and stick to it. Using async/await is generally considered more natural for most developers.

// Recommended: Pure async/await pattern
async function doSftp() {
  try {
    let sftp = await sftp.connect(conf);
    let d = await sftp.cwd();
    console.log(`remote dir is ${d}`);
    await sftp.fastGet(`${d}/foo.txt`, 'bat.txt');
  } catch (e) {
    console.error(e.message);
  } finally {
    await sftp.end();
  }
}

When connecting to Windows-based SFTP servers, an ECONNRESET error is often raised after a delay when calling end(). To prevent uncaught exceptions, ssh2-sftp-client must keep error handlers attached to the object.

If you re-use the same SftpClient object for multiple connections (e.g., connect() -> end() -> connect()), these handlers accumulate. After 11 handlers are added, Node.js will trigger a memory leak warning.

Best Practice: Always generate a new SftpClient object for each new connection. You can perform multiple operations (uploads/downloads) within a single connection, but do not call connect() again on the same instance after calling end().

To connect via a SOCKS 5 proxy, you must create the connection using a SOCKS client (like the socks package) and then pass the resulting socket to the connect method via the sock option. Note that the SOCKS client connection must be ingested by ssh2-sftp-client immediately to avoid timeouts.

import { SocksClient } from 'socks';
import SFTPClient from 'ssh2-sftp-client';

const host = 'my-sftp-server.net';
const port = 22;

// connect to SOCKS 5 proxy
const { socket } = await SocksClient.createConnection({
  proxy: {
    host: 'my.proxy',
    port: 1080,
    type: 5,
  },
  command: 'connect',
  destination: { host, port }
});

const client = new SFTPClient();
client.connect({
  host,
  sock: socket, // pass the socket to proxy here
  // other config options
});

To use this package, install it via your preferred package manager. This package provides the SftpClient class, which is a promise-based decorator around the ssh2 module.

Requirements:

• Node.js version 20.x or higher (Node versions prior to v20.x are not supported).

# Example installation command
npm install ssh2-sftp-client

You can avoid using passwords by setting up SSH keys and using one of the following two methods in your connection configuration:

1. Using an SSH Agent: Pass the SSH_AUTH_SOCK environment variable to the agent option.
2. Using a Private Key directly: Pass the contents of your private key file to the privateKey option using fs.readFileSync().

// Option 1: Using SSH Agent
let sftp = new Client();
sftp.connect({
  host: 'YOUR-HOST',
  port: 'YOUR-PORT',
  username: 'YOUR-USERNAME',
  agent: process.env.SSH_AUTH_SOCK
}).then(() => {
  sftp.fastPut(/* ... */)
});

// Option 2: Using Private Key directly
let sftp = new Client();
sftp.connect({
  host: 'YOUR-HOST',
  port: 'YOUR-PORT',
  username: 'YOUR-USERNAME',
  privateKey: fs.readFileSync('/path/to/ssh/key')
}).then(() => {
  sftp.fastPut(/* ... */)
});