SFTP Browser

A web-based SFTP file browser for easy server file management.

Forked from: https://github.com/kaysting/sftp-browser

Features

• Connect to SFTP servers hosted on any platform
• Import and export server connections
• Navigate directories with ease
• Sort files by different attributes
• Show or hide hidden (dot) files
• Switch between list and tile views
• Download multiple files/directories as a single zip file
• Upload files by dragging and dropping or using the button
• Create new files and directories
• Rename and delete files
• Cut/copy/paste files between directories
• Use "Move to" and "Copy to" dialogs for contextual organization
• Edit file permissions
• Recursively search for files by name within a directory
• View images, videos, and audio files in the browser
  • File size limitations may apply
• Edit text files in the browser and save directly to the server
  • Syntax highlighting supported for certain languages
• Edit Markdown files with a live preview
• Full mobile support with a responsive UI

Connection Management

SFTP Browser supports seamless connection management through unique connection IDs. When a connection is established via the auto-connection endpoint, a unique connectionId is generated, and a URL in the format /connect/:connectionId is provided. Accessing this URL allows users to connect to the SFTP server without manually entering credentials, as the connection details are retrieved from the server using the connectionId. The connection details are stored temporarily on the server (typically for 12 hours) and in the client's localStorage for persistence across sessions. Duplicate connections are prevented by clearing existing connections when a new /connect/:connectionId URL is accessed.

API Basics

Authentication

All API endpoints (except /auto-connection and /connect/:connectionId) require the following request headers for connecting to the target server:

• sftp-host: The hostname of the server
• sftp-port: The port of the server
• sftp-username: The username to log into
• sftp-password: The password, if using password authentication
• sftp-key: The private key, if using public key authentication

Response Format

All API responses are in JSON format and include a boolean success property. This is true if no errors were encountered, or false otherwise. If an error occurs, a string error property is included with a description of the error.

Successful Response Example:

{
    "success": true,
    "...": "..."
}

Failed Response Example:

{
    "success": false,
    "error": "[error description]",
    "...": "..."
}

Failed responses use a 400 or 500 level HTTP status code.

API Endpoints

Auto-Connection

Endpoint: POST /auto-connection

Creates a temporary connection to an SFTP server and generates a unique connectionId and URL for accessing the connection without re-entering credentials.

Request Body

• Required host (string): The hostname of the server
• Required username (string): The username to log into
• Optional port (number): The port of the server (defaults to 22)
• Optional password (string): The password, if using password authentication
• Optional privateKey (string): The private key, if using public key authentication

Note: Either password or privateKey must be provided.

Successful Response

• success (boolean): true if the connection was established
• connectionId (string): A unique identifier for the connection
• connectionUrl (string): A URL in the format https://<host>/connect/:connectionId for accessing the connection

Example Response:

{
    "success": true,
    "connectionId": "9795d599219c783637efdecc6a91edd8",
    "connectionUrl": "https://sftp.my-mc.link/connect/9795d599219c783637efdecc6a91edd8"
}

Failed Response

• success (boolean): false if the connection failed
• error (string): Description of the error (e.g., "Missing host")

Fetch Connection Details

Endpoint: GET /api/connect/:connectionId

Retrieves the connection details for a given connectionId, typically used when accessing a /connect/:connectionId URL.

Path Parameters

• Required connectionId (string): The unique identifier for the connection

Successful Response

• success (boolean): true if the connection details were found
• connection (object): The connection details
  • host (string): The hostname of the server
  • port (number): The port of the server
  • username (string): The username
  • password (string, optional): The password, if provided
  • privateKey (string, optional): The private key, if provided

Example Response:

{
    "success": true,
    "connection": {
        "host": "my-mc.link",
        "port": 39125,
        "username": "mc",
        "password": "IJhPT15nlOIoJm53"
    }
}

Failed Response

• success (boolean): false if the connection was not found
• error (string): Description of the error (e.g., "Connection not found")

List Files in a Directory

Endpoint: GET /api/sftp/directories/list

Query Parameters

• Required path (string): The target directory path
• Optional dirsOnly (boolean): If true, only directories are returned

Successful Response

• path (string): The normalized path
• list (object[]): An array of file objects
  • list[].name (string): The name of the file
  • list[].accessTime (number): Timestamp of the last access time
  • list[].modifyTime (number): Timestamp of the last modification time
  • list[].size (number): File size in bytes
  • list[].type (string): A 1-character string representing the file type
  • list[].group (number): ID of the group the file belongs to
  • list[].owner (number): ID of the user the file belongs to
  • list[].rights (object): Permissions for the file
    • list[].rights.user (string): Permissions for the owner (r, w, x)
    • list[].rights.group (string): Permissions for the group (r, w, x)
    • list[].rights.other (string): Permissions for others (r, w, x)
  • list[].longname (string): Raw SFTP output for the file

Create a Directory

Endpoint: POST /api/sftp/directories/create

Query Parameters

• Required path (string): The new directory path

Successful Response

• path (string): The normalized path

Delete a Directory

Endpoint: DELETE /api/sftp/directories/delete

Query Parameters

• Required path (string): The path of the directory to delete

Successful Response

• path (string): The normalized path

Check if a Path Exists

Endpoint: GET /api/sftp/files/exists

Query Parameters

• Required path (string): The path to check

Successful Response

• path (string): The normalized path
• exists (boolean): true if the path exists, false otherwise
• type (string|boolean): File type character if the path exists, false otherwise

Get Information About a File

Endpoint: GET /api/sftp/files/stat

Query Parameters

• Required path (string): The path to stat

Successful Response

• path (string): The normalized path
• stats (object): File statistics
  • accessTime (number): Last accessed time
  • modifyTime (number): Last modified time
  • size (number): File size in bytes
  • uid (number): ID of the file's owner
  • gid (number): ID of the file's group
  • mode (number): Integer representing file type and permissions
  • isBlockDevice (boolean): true if a block device
  • isCharacterDevice (boolean): true if a character device
  • isDirectory (boolean): true if a directory
  • isFIFO (boolean): true if a first-in first-out file
  • isSocket (boolean): true if a socket
  • isSymbolicLink (boolean): true if a symlink

Get Raw File Data

Endpoint: GET /api/sftp/files/get/single

Query Parameters

• Required path (string): The path of the file

Successful Response

• Raw file data

Failed Response

• JSON error response

Get File Download Link

Gets a temporary URL to download a single file without connection headers. URLs last 24 hours or until the server restarts.

Endpoint: GET /api/sftp/files/get/single/url

Query Parameters

• Required path (string): The path of the file

Successful Response

• path (string): The normalized path
• download_url (string): The download URL

Get Zipped Download Link

Gets a temporary URL for downloading files and directories as a zip archive without connection headers.

Endpoint: GET /api/sftp/files/get/multi

Query Parameters

• Required paths (string[]): JSON-formatted array of file or directory paths

Successful Response

• path (string): The normalized path
• download_url (string): The download URL

Create a File

Endpoint: POST /api/sftp/files/create

Query Parameters

• Required path (string): The path of the new file

Request Body

• Raw data to insert into the new file

Successful Response

• path (string): The normalized path

Append Data to a File

Endpoint: PUT /api/sftp/files/append

Query Parameters

• Required path (string): The path of the file

Request Body

• Raw data to append to the file

Successful Response

• path (string): The normalized path

Move a File

Endpoint: PUT /api/sftp/files/move

Query Parameters

• Required pathOld (string): The current path
• Required pathNew (string): The new path

Successful Response

• pathOld (string): The normalized old path
• pathNew (string): The normalized new path

Copy a File

Directories not supported.

Endpoint: PUT /api/sftp/files/copy

Query Parameters

• Required pathSrc (string): The source path
• Required pathDest (string): The destination path

Successful Response

• pathSrc (string): The normalized source path
• pathDest (string): The normalized destination path

Edit a File's Permissions

Directories supported, but without recursion.

Endpoint: PUT /api/sftp/files/chmod

Query Parameters

• Required path (string): The path of the file
• Required mode (string): The new mode in the form xyz, where x, y, and z are integers from 0 to 7

Successful Response

• path (string): The normalized path
• mode (string): The supplied mode

Delete a File

Endpoint: DELETE /api/sftp/files/delete

Query Parameters

• Required path (string): The path of the file

Successful Response

• path (string): The normalized path