first commit
This commit is contained in:
MCHost
309
README.md
Normal file
309
README.md
Normal file
@ -0,0 +1,309 @@
|
||||
# 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:**
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"...": "..."
|
||||
}
|
||||
```
|
||||
|
||||
**Failed Response Example:**
|
||||
```json
|
||||
{
|
||||
"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:**
|
||||
```json
|
||||
{
|
||||
"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:**
|
||||
```json
|
||||
{
|
||||
"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
|
||||
Reference in New Issue
Block a user