Code Monkey home page Code Monkey logo

sftp-server's Introduction

sftp-server


A Node.js-based SFTP server with an integrated REST API for querying users / files. Provides a customizable authentication strategy. Emits various events as file changes occur, allowing you to notify third-party services. Useful when you need to provide clients with a standardized interface for submitting files, data feeds, etc... to you.

PR's are welcome.

Example

const fs = require('fs');
const Promise = require('bluebird');
const path = require('path');

const server = require('sftp-server')({
    'sftp': {
        'port': 3333,
        'hostKeys': [
            fs.readFileSync(__dirname + '/host_rsa').toString('utf8')
        ],
        'dataDirectory': path.resolve(__dirname, '../data'),
        'auth': function(username, password) {
            return Promise.resolve()
                .then(() => {
                    if (username !== 'foo' || password !== 'bar') {
                        throw new Error();
                    }
                });
        },
        /**
         * Block repeated authentication attempts from the same IP address within the specified
         * window (in seconds).
         */
        'rateLimitTTL': 10
    },
    'api': {
        'port': 8000,
        'key': 'yYNR8xeUGtcim7XYaUTsdfmkNuKxLHjw77MbPMkZzKoNdsAzyMryVLJEzjVMHpHM'
    },
    'log': {
        'console': {
            'enabled': true
        },
        'file': {
            'enabled': true,
            'filename': '/var/log/sftp-server.log'
        }
    }
})
    .then((server) => {

        server.on('ready', () => {
            // ...
        });

        server.on('login', (data) => {
            // ...
        });

        server.on('upload_complete', (data) => {
            // ...
        });

        server.on('remove', (data) => {
            // ...
        });

        server.on('mkdir', (data) => {
            // ...
        });

        server.on('rmdir', (data) => {
            // ...
        });

        server.on('rename', (data) => {
            // ...
        });

        server.listen();

    });

Authentication

SFTPServer has no built-in mechanism for managing users. The expectation is that the service is implemented in conjunction with a separate, pre-existing service that manages this information.

Authentication is implemented by including a callback function (sftp.auth) within the options that are passed when creating a new instance of SFTPServer (see previous example). When a user attempts to sign in, this function will be passed the username and password provided by the client. A promise should be returned. A rejected promise indicates a sign-in failure, while a resolution indicates success.

Once authenticated, a user is only allowed to interact with files that belong to them. User A cannot see user B's files, and vice-versa.

Optionally, you may choose to resolve the returned promise with an object describing the various SFTP commands that the connecting client should be allowed to perform. By default, all commands are enabled. Select commands can be individually disabled as shown below.

{
    'auth': function(username, password) {
        return Promise.resolve()
            .then(() => {
                if (username !== 'foo' || password !== 'bar') {
                    throw new Error();
                }
                return {
                    'permissions': {
                        'MKDIR': false
                    }
                };
            });
    }
}

Commands which can be selectively disabled include:

  • MKDIR
  • READ
  • REMOVE
  • RENAME
  • RMDIR
  • WRITE

REST API

Health Check

$ curl -X GET http://127.0.0.1:8000/api/ping

Fetch Users

$ curl -X GET --header "x-token: yYNR8xeUGtcim7XYaUTsdfmkNuKxLHjw77MbPMkZzKoNdsAzyMryVLJEzjVMHpHM" \
	http://127.0.0.1:8000/api/users

Fetch and Manipulate Files / Folders

The URLs for all API calls related to file / folder interactions are structured in the following manner:

http://[hostname]:[port]/api/users/[username]/files/[path-to-file]

Fetching a list of files at the root level of a user's folder

$ curl -X GET --header "x-token: yYNR8xeUGtcim7XYaUTsdfmkNuKxLHjw77MbPMkZzKoNdsAzyMryVLJEzjVMHpHM" \
	http://127.0.0.1:8000/api/users/foo/files
[
    {
        "file": ".viminfo",
        "stats": {
            "dev": 16777224,
            "mode": 33188,
            "nlink": 1,
            "uid": 501,
            "gid": 20,
            "rdev": 0,
            "blksize": 4096,
            "ino": 117661849,
            "size": 9171,
            "blocks": 24,
            "atime": "2017-09-11T13:58:58.000Z",
            "mtime": "2017-09-11T00:42:45.000Z",
            "ctime": "2017-09-11T00:42:45.000Z",
            "birthtime": "2017-09-11T00:42:45.000Z",
            "isFile": true,
            "isDirectory": false
        }
    },
    {
        "file": "herp",
        "stats": {
            "dev": 16777224,
            "mode": 16877,
            "nlink": 3,
            "uid": 501,
            "gid": 20,
            "rdev": 0,
            "blksize": 4096,
            "ino": 117690342,
            "size": 102,
            "blocks": 0,
            "atime": "2017-09-11T14:00:44.000Z",
            "mtime": "2017-09-11T13:59:05.000Z",
            "ctime": "2017-09-11T13:59:05.000Z",
            "birthtime": "2017-09-11T13:58:58.000Z",
            "isFile": false,
            "isDirectory": true
        }
    }
]

Addressing Specific Files / Sub-Directories

Specific files / sub-directories can be addressed by appending the desired path to the URL we saw in the previous example.

# Fetch files within the 'herp' subdirectory of the specified user's (foo) folder:
$ curl -X GET --header "x-token: yYNR8xeUGtcim7XYaUTsdfmkNuKxLHjw77MbPMkZzKoNdsAzyMryVLJEzjVMHpHM" \
	http://127.0.0.1:8000/api/users/foo/files/herp

# Delete the 'herp' subdirectory of the specified user's (foo) folder:
$ curl -X DELETE --header "x-token: yYNR8xeUGtcim7XYaUTsdfmkNuKxLHjw77MbPMkZzKoNdsAzyMryVLJEzjVMHpHM" \
	http://127.0.0.1:8000/api/users/foo/files/herp

# Fetch a specific file:
$ curl -X GET --header "x-token: yYNR8xeUGtcim7XYaUTsdfmkNuKxLHjw77MbPMkZzKoNdsAzyMryVLJEzjVMHpHM" \
	http://127.0.0.1:8000/api/users/foo/files/herp/derp.txt

# Delete a specific file:
$ curl -X DELETE --header "x-token: yYNR8xeUGtcim7XYaUTsdfmkNuKxLHjw77MbPMkZzKoNdsAzyMryVLJEzjVMHpHM" \
	http://127.0.0.1:8000/api/users/foo/files/herp/derp.txt

Fetching User Meta Information

To fetch meta information for a file or folder, append ?meta=true to the appropriate GET call. For example - to fetch meta information regarding a user's root folder, you would make the following call:

$ curl -X GET --header "x-token: yYNR8xeUGtcim7XYaUTsdfmkNuKxLHjw77MbPMkZzKoNdsAzyMryVLJEzjVMHpHM" \
	http://127.0.0.1:8000/api/users/foo/files?meta=true

Returns:

{
    "dev": 16777224,
    "mode": 16877,
    "nlink": 6,
    "uid": 501,
    "gid": 20,
    "rdev": 0,
    "blksize": 4096,
    "ino": 117649567,
    "size": 204,
    "blocks": 0,
    "atime": "2017-09-11T14:40:17.000Z",
    "mtime": "2017-09-11T13:58:58.000Z",
    "ctime": "2017-09-11T13:58:58.000Z",
    "birthtime": "2017-09-10T20:02:42.000Z",
    "isFile": false,
    "isDirectory": true,
    "totalSize": 10017653
}

The totalSize property indicates the total combined size of all files / directories contained within the specified directory. When metadata is fetched for a specific file, this attribute will not be present.

Fetching System Meta Information

$ curl -X GET --header "x-token: yYNR8xeUGtcim7XYaUTsdfmkNuKxLHjw77MbPMkZzKoNdsAzyMryVLJEzjVMHpHM" \
	http://127.0.0.1:8000/api/system/meta

Returns:

{
    "totalUsers": 1,
    "totalStorage": 10023937
}

To-Do

  • Additional tests
  • Additional logging
  • Additional work on REST API
  • Improved support for various SFTP commands (FSTAT, etc...)
  • Fix sub-directory upload bug (when uploading a file to a sub-directory the client has created, the file is always uploaded to the root folder)

Development

Launching the Example Server

Install dependencies then launch the included example instance (./example/server.js) via Nodemon:

$ npm i
$ npm run dev

Production Environments

Disable debug messages in production by ensuring the NODE_ENV environmental variable is set to production.

Tests

$ npm run test

Related Resources

Tests

$ npm run test

sftp-server's People

Contributors

tkambler avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.