@cumulus/sftp-client

@cumulus/sftp-client

A Promise-based SFTP client

Install

npm install @cumulus/sftp-client

Usage

const { SftpClient } = require("@cumulus/sftp-client");

(async () => {
  const sftpClient = new SftpClient({
    host: "ssh.example.com",
    port: 2222,
    username: "my-username",
    password: "my-password"
  });

  console.log(await sftpClient.list("./"));
})();

API

constructor(config)

config

Type: object

config.host

Type: string

The hostname or IP address of the remote SFTP server.

config.port

Type: number
Default: 22

The TCP port to connect to.

config.username

Type: string

The username to use when connecting to the SFTP server.

config.password

Type: string

The password to use when connecting to the SFTP server.

config.privateKey

Type: string

A private key to use when connecting to the SFTP server.

sftpClient.download(remotePath, localPath)

Download a remote file to disk. Returns a Promise that resolves to a string containing the local path that the file was saved to.

remotePath

Type: string

The full path to the remote file to be fetched

localPath

Type: string

The full local destination file path

sftpClient.end()

Close the connect to the SFTP server.

sftpClient.list(remotePath)

Returns a Promise that resolves to an array of objects containing information about discovered files.

The returned file objects will each contain name, path, type, size, and time fields.

remotePath

Type: string

The remote path to be listed.

sftpClient.sftp()

Returns the ssh2-sftp-client Client as a convenience.

sftpClient.syncFromS3(s3Object, remotePath)

Returns a Promise that resolves to undefined once a file has been transferred from S3 to the SFTP server.

s3Object

Type: object

s3Object.Bucket

Type: string

The bucket containing the S3 object to be transferred to the SFTP server.

s3Object.Key

Type: string

The key of the S3 object to be transferred to the SFTP server.

remotePath

Type: string

The full remote destination file path.

sftpClient.syncToS3(remotePath, bucket, key)

Returns a Promise that resolves to a string containing the S3 URI of the destination file

remotePath

Type: string

The full path to the remote file to be fetched

bucket

Type: string

Destination S3 bucket of the file

key

Type: string

Destination S3 key of the file

sftpClient.unlink(remotePath)

Returns a Promise that resolves to undefined once the remote file has been deleted.

remotePath

Type: string

The path to file on the SFTP server to be deleted

Changelog

[v20.3.0] 2025-08-18

Notable Changes

• CUMULUS-4194
  • update cumulus-process to 1.5.0
• CUMULUS-4131
  • Users upgrading to this release will be required to update their terraform version to at least 1.12.2. Reference migration instructions are included at https://nasa.github.io/cumulus/docs/next/upgrade-notes/upgrade-terraform-1.12
• CUMULUS-4176
  • Updated engine_version default value to 17.4 in example/rds-cluster-tf/variables.tf.
  • Updated tf-modules/cumulus-rds-tf module to take additional parameter enable_upgrade in support of migration from Aurora PostgreSQl v13 to v17.

Breaking Changes

• CUMULUS-4131
  • Updated Terraform version requirement to >=1.12.2
  • Updated AWS provider requirement to 5.100.x

Changed

• CUMULUS-4142, CUMULUS-4144
  • Updated the S3 credentials endpoint attached to TEA to delete the access token after successful authentication.
  • Configured both Cumulus distribution and S3 credentials to set the SameSite attribute on cookies in the response.

Fixed

• CUMULUS-4177
  • Update form-data sub-dependency to safe version ^4.0.4
• CUMULUS-4174
  • Fix broken CreateReconciliationReportSpec test cleanup
• CUMULUS-4170
  • Upgrade Node Docker image from buster to bullseye for a compatible debian version