SFTP Transfer

An SFTP event plugin for the xyOps Workflow Automation System. It can upload, download, list, and delete files on remote SFTP servers, and is designed to work naturally with xyOps job input and output files.

Features

• Pure Node.js / npx plugin.
• Uses SSH File Transfer Protocol through the ssh2 module.
• Supports password auth, private key auth, private key passphrases, and ssh-agent.
• Allows SSH private keys from either a Secret Vault variable or a local file path.
• Supports optional host fingerprint pinning.
• Uploads files from the xyOps job temp directory by default.
• Downloads files into the xyOps job temp directory by default.
• Optionally attaches downloaded files to the xyOps job output.
• Supports filename glob filters, recursive folder traversal, max file limits, sorting, and age filters.
• Includes a dry run option for deletes.

Requirements

• Node.js
• npx
• Network access from the xyOps runner host to your SFTP server

This plugin uses ssh2 for SSH and SFTP client support. The library is MIT licensed.

Secrets / Environment Variables

Create a Secret Vault in xyOps and assign this plugin to it. Add whichever credentials your SFTP server requires:

• SFTP_USER
• SFTP_PASSWORD
• SFTP_PRIVATE_KEY
• SFTP_PASSPHRASE

For convenience, the plugin also accepts these SSH-style aliases:

• SSH_PASSWORD
• SSH_PRIVATE_KEY
• SSH_PASSPHRASE

You can also enter a password directly in the plugin parameters, or enter a local Private Key File path. For production use, a Secret Vault is recommended.

If the runner host has SSH_AUTH_SOCK set, the plugin can use ssh-agent when no password or private key is supplied.

Data Collection

This plugin does not collect, store, or transmit telemetry, analytics, or usage metrics. It only connects to the SFTP server you configure. Your SFTP server may log requests according to its own policies.

Overview

The plugin exposes a toolset with four tools:

• Upload Files
• Download Files
• List Files
• Delete Files

All tools operate against a single configured SFTP server per job run.

Common Parameters

Parameter	Required	Description
SFTP Hostname	Yes	Remote SFTP hostname or IP address.
Username	No	SFTP username. Leave blank to use SFTP_USER from a Secret Vault or the environment.
Password	No	SFTP password. Prefer SFTP_PASSWORD in a xyOps Secret Vault.
Port	No	SSH TCP port for SFTP. Defaults to 22.
Private Key File	No	Local path to an SSH private key on the runner host. Secret Vault variables are recommended when possible.
Host Fingerprint	No	Optional host key pin. Accepts SHA256:... or MD5 fingerprint text.
Connect Timeout (sec)	No	Timeout for the SSH connection. Defaults to 30.
Verbose Logging	No	Logs SSH connection debug details.

General Notes

• Remote Path values are SFTP paths. Leave blank to use the server's login directory.
• Relative remote paths are interpreted by the SFTP server relative to the login directory.
• Absolute remote paths can be used when your SFTP account has permission.
• Filename Pattern uses glob-style matching and is applied to filenames.
• Multiple filename patterns can be separated with commas, for example *.csv,*.tsv.
• Older Than and Newer Than can be raw seconds or friendly text like 7 days, 12 hours, or 30 minutes.
• Maximum Files is especially useful when combined with Sort Files.
• Progress is reported back to xyOps during file uploads and downloads.
• Host fingerprint pinning is strongly recommended for production SFTP workflows.

Tool Reference

Upload Files

Uploads local files to the SFTP server.

In normal xyOps usage, if you leave Local Path blank, the plugin uploads files from the job temp directory. This means the easiest way to upload files is to attach them as job inputs or pass them from upstream workflow steps.

If you want to upload from a specific path on the server running the job, set Local Path explicitly. It can point to a file or a directory.

Parameter	Required	Description
Local Path	No	Local file or directory to upload from. Leave blank to use the xyOps job temp directory.
Filename Pattern	No	Optional glob to limit which local files are uploaded.
Remote Path	No	Remote SFTP directory to upload into. Leave blank for the login directory.
Include Subfolders	No	Upload matching files from subdirectories too, preserving relative paths.

Output:

• data.files: Array of uploaded files with local path, remote path, filename, and size.
• data.bytes: Total uploaded bytes.
• data.count: Number of uploaded files.

Download Files

Downloads files from the SFTP server to the local machine running the job.

By default, if you leave Local Path blank, files are downloaded into the job temp directory. Also by default, Attach Files is enabled, so downloaded files are attached to the job output and become available to downstream workflow steps.

Parameter	Required	Description
Remote Path	No	Remote SFTP directory to download from. Leave blank for the login directory.
Filename Pattern	No	Optional glob to limit which remote files are downloaded.
Local Path	No	Destination directory on local disk. Leave blank to use the xyOps job temp directory.
Include Subfolders	No	Download matching files from subdirectories too, preserving relative paths.
Delete Files	No	Delete each remote file after successful download.
Attach Files	No	Attach downloaded files to the xyOps job output. Enabled by default.
Maximum Files	No	Limit how many files are downloaded. 0 means no limit.
Sort Files	No	Sort before downloading: path, newest, oldest, largest, or smallest.

Output:

• data.files: Array of downloaded files with remote path, local path, filename, size, and modified time.
• data.bytes: Total downloaded bytes.
• data.count: Number of downloaded files.

List Files

Lists remote SFTP files and returns metadata without downloading contents.

This is useful for audits, preflight checks, inventory workflows, and driving downstream workflow logic from remote file state.

Parameter	Required	Description
Remote Path	No	Remote SFTP directory to list. Leave blank for the login directory.
Filename Pattern	No	Optional glob to limit which remote files are included.
Include Subfolders	No	List matching files from subdirectories too.
Older Than	No	Include only files older than this relative time.
Newer Than	No	Include only files newer than this relative time.
Maximum Files	No	Limit how many files are returned. 0 means no limit.
Sort Files	No	Sort before returning metadata: path, newest, oldest, largest, or smallest.

Output:

• data.files: Array of remote file objects containing path, relative path, filename, size, and modification metadata.
• data.bytes: Total bytes across all matched files.
• data.count: Number of matched files.

The job details page also gets a compact file listing table for quick viewing.

Delete Files

Deletes files from the SFTP server.

Use this tool when you want to purge files matching a directory, filename pattern, age filter, or size/date ordering strategy. Start with Dry Run enabled when building destructive workflows.

Parameter	Required	Description
Remote Path	No	Remote SFTP directory to delete from. Leave blank for the login directory.
Filename Pattern	No	Optional glob to limit which remote files are deleted.
Include Subfolders	No	Delete matching files from subdirectories too.
Older Than	No	Delete only files older than this relative time.
Newer Than	No	Delete only files newer than this relative time.
Maximum Files	No	Limit how many files are deleted. 0 means no limit.
Sort Files	No	Sort before deleting: oldest, newest, path, largest, or smallest.
Dry Run	No	Preview the matched files without actually deleting anything. Enabled by default.

Output:

• data.files: Array of matched or deleted remote file objects.
• data.bytes: Total bytes across matched files.
• data.count: Number of matched or deleted files.
• data.dry: Whether dry run mode was enabled.

Local Testing

When invoked by xyOps, the plugin expects a single JSON document on STDIN using the xyOps Wire Protocol. You can simulate this locally by piping JSON into node index.js.

Install dependencies first:

npm install

Example upload test using the current directory as the local source:

{
	"xy": 1,
	"params": {
		"hostname": "sftp.example.com",
		"username": "deploy",
		"port": 22,
		"tool": "uploadFiles",
		"localPath": "./",
		"filespec": "*.txt",
		"remotePath": "incoming/"
	},
	"secrets": {
		"SFTP_PASSWORD": "REPLACE_ME"
	}
}

Example download test:

{
	"xy": 1,
	"params": {
		"hostname": "sftp.example.com",
		"username": "deploy",
		"port": 22,
		"tool": "downloadFiles",
		"remotePath": "outgoing/",
		"localPath": "./downloads/",
		"filespec": "*.csv",
		"attach": false
	},
	"secrets": {
		"SFTP_PASSWORD": "REPLACE_ME"
	}
}

Example list test with a private key stored in a Secret Vault:

{
	"xy": 1,
	"params": {
		"hostname": "sftp.example.com",
		"username": "deploy",
		"port": 22,
		"tool": "listFiles",
		"remotePath": "reports/",
		"filespec": "*.csv",
		"recursive": true,
		"newer": "24 hours",
		"sort": "newest",
		"max": 25
	},
	"secrets": {
		"SFTP_PRIVATE_KEY": "-----BEGIN OPENSSH PRIVATE KEY-----\nREPLACE_ME\n-----END OPENSSH PRIVATE KEY-----\n"
	}
}

Example delete dry run:

{
	"xy": 1,
	"params": {
		"hostname": "sftp.example.com",
		"username": "deploy",
		"port": 22,
		"tool": "deleteFiles",
		"remotePath": "archive/",
		"filespec": "*.tmp",
		"older": "30 days",
		"dry": true
	},
	"secrets": {
		"SFTP_PASSWORD": "REPLACE_ME"
	}
}

Run any of the above like this:

cat sample.json | node index.js

Or without a file:

echo '{"xy":1,"params":{"hostname":"sftp.example.com","username":"deploy","tool":"listFiles","remotePath":"incoming/","filespec":"*.csv"},"secrets":{"SFTP_PASSWORD":"REPLACE_ME"}}' | node index.js

You can also use environment variables:

export SFTP_PASSWORD="REPLACE_ME"
echo '{"xy":1,"params":{"hostname":"sftp.example.com","username":"deploy","tool":"listFiles"}}' | node index.js

You can test a private key file path like this:

echo '{"xy":1,"params":{"hostname":"sftp.example.com","username":"deploy","private_key_file":"/home/xyops/.ssh/id_ed25519","tool":"listFiles"}}' | node index.js

Output Summary

Depending on the selected tool, the plugin returns structured job data such as:

• uploaded file paths
• downloaded file metadata
• listed file metadata
• deleted file metadata
• total byte counts
• file counts

For file-producing tools, the plugin can also attach local files to the xyOps job output:

• Download Files: attaches downloaded files when Attach Files is enabled

License

MIT