sftp-browser/README.md

# 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