SSH/SFTP File System Client

Modern SSH/SFTP client for Node.js

A robust TypeScript library providing seamless file system operations over SSH/SFTP with a clean, promise-based API. Perfect for secure file transfers, remote server management, and automation tasks.

Table of Contents

• Installation
• Usage
• API Reference
• Contributing
• License
• Author

Installation

npm install fs-tunnel

Usage

Basic example

import { SSHFileSystem } from 'fs-tunnel'

const config = {
  host: 'example.com',
  port: 22,
  username: 'user',
  password: 'password'
}

async function main() {
  const fs = new SSHFileSystem(config)
  
  try {
    await fs.connect()
    
    // List files in directory
    const files = await fs.readdir('/remote/path')
    console.log('Directory contents:', files)
    
    // Get file stats
    const stats = await fs.stat('/remote/file.txt')
    console.log('File stats:', stats)
    
    // Download file
    const readStream = fs.createReadStream('/remote/file.txt')
    readStream.pipe(fs.createWriteStream('./local-file.txt'))
    
  } finally {
    fs.disconnect()
  }
}

main()

Advanced example

// Upload directory recursively
async function uploadDirectory(localPath, remotePath) {
  const items = await fs.promises.readdir(localPath, { withFileTypes: true })
  
  await fs.mkdir(remotePath)
  
  for (const item of items) {
    const localItemPath = path.join(localPath, item.name)
    const remoteItemPath = path.posix.join(remotePath, item.name)
    
    if (item.isDirectory()) {
      await uploadDirectory(localItemPath, remoteItemPath)
    } else {
      const readStream = fs.createReadStream(localItemPath)
      const writeStream = fs.createWriteStream(remoteItemPath)
      readStream.pipe(writeStream)
    }
  }
}

API Reference

Class: SSHFileSystem

Constructor

new SSHFileSystem(config: SSHConfiguration)

• config: Connection configuration object
  • host: Server hostname (required)
  • port: SSH port (required)
  • username: Authentication username
  • password: Authentication password

Methods

Method	Description
connect()	Connects using configured credentials
connectWithCredentials(username, password)	Connects with explicit credentials
readdir(path)	Lists directory contents
stat(path)	Gets file/directory stats
mkdir(path)	Creates a directory
rmdir(path)	Removes a directory
unlink(path)	Deletes a file
rename(oldPath, newPath)	Renames/moves a file
createReadStream(path)	Creates readable file stream
createWriteStream(path, options)	Creates writable file stream
disconnect()	Closes the connection

Interfaces

FileInfo

{
  name: string
  isDirectory: boolean
  size: number
  mtime: Date
  mode: number
}

StatInfo

{
  isDirectory: boolean
  size: number
  mtime: Date
  mode: number
}

SSHConfiguration

{
  host: string
  port: number
  username?: string
  password?: string
}

Contributing

Contributions are welcome! Please open an issue or submit a pull request on the GitHub repository.

License

fs-tunnel is licensed under the MIT license.

Author

@SheikhAminul