# Super-frpc

A backend application for managing local frpc instances, allowing users to easily start, stop, restart, and perform daily maintenance operations on frpc instances. It also provides automated error handling, such as automatic restart when an instance crashes.

## Features

- User authentication with token-based login
- Create, delete, and modify frpc instances
- Automatic startup configuration (systemd/init.d)
- User permission management (superuser/admin/visitor)
- SQLite database for data persistence

## Configuration

Create a `config.json` file in the project root:

```json
{
  "listenAddr": "0.0.0.0",
  "listenPort": "8080",
  "frpcPath": "/usr/bin/frpc",
  "instancePath": "./configs"
}
```

| Field | Description | Default |
|-------|-------------|---------|
| listenAddr | Server listening address | 0.0.0.0 |
| listenPort | Server listening port | 8080 |
| frpcPath | Path to frpc executable | /usr/bin/frpc |
| instancePath | Path to store instance config files | ./configs |

## Build

```bash
go build -o super-frpc
```

For Linux:
```bash
GOOS=linux GOARCH=amd64 go build -o super-frpc
```

## Run

```bash
./super-frpc -config ./config.json -db ./database.db
```

## API Documentation

All API responses are returned in JSON format:

**Success Response:**
```json
{
  "success": true,
  "message": "success message",
  "data": { ... }
}
```

**Error Response:**
```json
{
  "success": false,
  "message": "error message"
}
```

**Important Notes:**
- For all requests: Authentication token and timestamp are sent in HTTP headers (prefixed with `X-`)
- For **POST** requests: Other data is sent in the request body as JSON
- For **GET** requests: All data is sent in HTTP headers (prefixed with `X-`)
- All requests require authentication (except `/register` and `/login`)
- Timestamps are in milliseconds (Unix timestamp)

---

### Register User

**Endpoint:** `/register`  
**Method:** POST  
**Content-Type:** application/json

**Request Headers:**
```
X-Timestamp: 1704067200000
```

**Request Body:**
```json
{
  "username": "your_username",
  "passwd": "YourPass123!"
}
```

| Header | Type | Required | Description |
|--------|------|----------|-------------|
| X-Timestamp | int64 | Yes | Client timestamp in milliseconds |

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| username | string | Yes | Username (no special characters) |
| passwd | string | Yes | Password (must contain uppercase, lowercase, digit, and special character, min 8 chars) |
| type | string | No | User type: superuser, admin, visitor (default: visitor) |

**Response:**
```json
{
  "success": true,
  "message": "user registered successfully",
  "data": {
    "userID": 1,
    "username": "your_username",
    "type": "admin"
  }
}
```
> New user only can register as visitor, superuser and admin need to contact the administrator to apply.

---

### Login

**Endpoint:** `/login`  
**Method:** POST  
**Content-Type:** application/json

**Request Headers:**
```
X-Timestamp: 1704067200000
```

**Request Body:**
```json
{
  "username": "your_username",
  "passwd": "YourPass123!"
}
```

| Header | Type | Required | Description |
|--------|------|----------|-------------|
| X-Timestamp | int64 | Yes | Client timestamp in milliseconds |

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| username | string | Yes | Username |
| passwd | string | Yes | Password |

**Response:**
```json
{
  "success": true,
  "message": "login successful",
  "data": {
    "token": "xxxxxxxxxxxxx",
    "userID": 1,
    "username": "your_username",
    "type": "admin"
  }
}
```

---

### Logout

**Endpoint:** `/logout`  
**Method:** GET  
**Auth Required:** Yes (token)

**Request Headers:**
```
X-Token: your_token
X-Timestamp: 1704067200000
```
| Header | Type | Required | Description |
|--------|------|----------|-------------|
| X-Token | string | Yes | Authentication token |
| X-Timestamp | int64 | Yes | Client timestamp in milliseconds |

**Response:**
```json
{
  "success": true,
  "message": "Logout successful"
}
```

---

### 3. Create frpc Instance

**Endpoint:** `/frpcAct/instanceMgr/create`  
**Method:** POST  
**Content-Type:** application/json  
**Auth Required:** Yes (token)

**Request Headers:**
```
X-Token: your_token
X-Timestamp: 1704067200000
```

**Request Body:**
```json
{
  "instanceInfo": {
    "name": "my_frpc",
    "serverAddr": "127.0.0.1",
    "serverPort": "7000",
    "auth_method": "token"
  },
  "bootAtStart": true,
  "runUser": "root",
  "additionalProperties": {
    "pool_count": 5
  }
}
```

| Header | Type | Required | Description |
|--------|------|----------|-------------|
| X-Token | string | Yes | Authentication token |
| X-Timestamp | int64 | Yes | Client timestamp in milliseconds |

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| instanceInfo.name | string | Yes | Instance name |
| instanceInfo.serverAddr | string | Yes | frps server address |
| instanceInfo.serverPort | string | Yes | frps server port |
| instanceInfo.auth_method | string | Yes | Authentication method |
| bootAtStart | bool | No | Auto-start on system boot (default: false) |
| runUser | string | No | Run as user (default: root) |
| additionalProperties | object | No | Additional frpc configuration |

**Response:**
```json
{
  "success": true,
  "message": "instance created successfully",
  "data": {
    "name": "my_frpc",
    "configPath": "./configs/superfrpc_user_my_frpc.toml",
    "bootAtStart": true
  }
}
```

---

### 4. Delete frpc Instance

**Endpoint:** `/frpcAct/instanceMgr/delete`  
**Method:** POST  
**Content-Type:** application/json  
**Auth Required:** Yes (token)

**Request Headers:**
```
X-Token: your_token
X-Timestamp: 1704067200000
```

**Request Body:**
```json
{
  "instanceName": "my_frpc"
}
```

**Response:**
```json
{
  "success": true,
  "message": "instance deleted successfully",
  "data": {
    "name": "my_frpc"
  }
}
```

---

### 5. Modify frpc Instance

**Endpoint:** `/frpcAct/instanceMgr/modify`  
**Method:** POST  
**Content-Type:** application/json  
**Auth Required:** Yes (token)

Modify instance configuration. Supports two modification types: `configFile` (modify frpc config file) and `systemConfig` (modify system-level settings).

**Request Headers:**
```
X-Token: your_token
X-Timestamp: 1704067200000
```

#### Type 1: Modify Config File (configFile)

Modify fields in the `[common]` section of the frpc configuration file. Only `[common]` section fields can be modified, `[[proxies]]` sections will not be affected.

**Request Body:**
```json
{
  "instanceName": "my_frpc",
  "instanceID": "1",
  "type": "configFile",
  "modifiedData": {
    "server_addr": "192.168.1.1",
    "server_port": "7000",
    "auth_method": "token",
    "auth_token": "my_secret_token"
  }
}
```

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| instanceName | string | Yes | Current instance name |
| instanceID | string | Yes | Instance ID |
| type | string | Yes | Modification type: `configFile` or `systemConfig` |
| modifiedData | object | Yes | Key-value pairs of fields to modify in `[common]` section |

**Response:**
```json
{
  "success": true,
  "message": "Config file modified successfully",
  "data": {
    "instanceName": "my_frpc",
    "instanceID": 1,
    "configPath": "./configs/superfrpc_user_my_frpc.toml"
  }
}
```

#### Type 2: Modify System Config (systemConfig)

Modify system-level settings such as instance name, boot-at-start configuration, and run user. These changes will also update the operating system service configuration.

**Request Body:**
```json
{
  "instanceName": "my_frpc",
  "instanceID": "1",
  "type": "systemConfig",
  "modifiedData": {
    "name": "new_frpc_name",
    "bootAtStart": true,
    "runUser": "www-data"
  }
}
```

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| instanceName | string | Yes | Current instance name |
| instanceID | string | Yes | Instance ID |
| type | string | Yes | Modification type: `configFile` or `systemConfig` |
| modifiedData.name | string | No | New instance name (renames config file if changed) |
| modifiedData.bootAtStart | bool | No | Auto-start on system boot |
| modifiedData.runUser | string | No | User to run the frpc instance as |

**Response:**
```json
{
  "success": true,
  "message": "System config modified successfully",
  "data": {
    "instanceName": "new_frpc_name",
    "instanceID": 1,
    "configPath": "./configs/superfrpc_user_new_frpc_name.toml",
    "bootAtStart": true,
    "runUser": "www-data"
  }
}
```

**Response with bootServiceError (when boot service operations fail):**
```json
{
  "success": true,
  "message": "System config modified successfully",
  "data": {
    "instanceName": "new_frpc_name",
    "instanceID": 1,
    "configPath": "./configs/superfrpc_user_new_frpc_name.toml",
    "bootAtStart": true,
    "runUser": "www-data",
    "bootServiceError": "Failed to create boot service: unsupported init system"
  }
}
```

> **Note about bootServiceError:**
> - The `bootServiceError` field appears in the response when boot service operations (create/remove) fail
> - This field is only present when there is an error; it will not be included in the response if operations succeed
> - The overall request still returns `success: true` because the system config modification (database update, config file rename, etc.) succeeded
> - Common scenarios where `bootServiceError` may appear:
>   - Enabling `bootAtStart` when the init system is not supported (e.g., on Windows or systems without systemd/init.d)
>   - Disabling `bootAtStart` when the service file cannot be removed due to permission issues
>   - Changing instance name or run user when `bootAtStart` is enabled (requires removing old service and creating new one)
> - The error message provides detailed information about what went wrong, which should be displayed to the user
> - Frontend applications should check for this field and display the error message to the user, even though the request was technically successful

---

### 6. List frpc Instances

**Endpoint:** `/frpcAct/instanceMgr/list`  
**Method:** GET  
**Auth Required:** Yes (token)

**Request Headers:**
```
X-Token: your_token
X-Timestamp: 1704067200000
```

| Header | Type | Required | Description |
|--------|------|----------|-------------|
| X-Token | string | Yes | Authentication token |
| X-Timestamp | int64 | Yes | Client timestamp in milliseconds |

**Response (admin/superuser):**
```json
{
  "success": true,
  "message": "instances retrieved successfully",
  "data": [
    {
      "name": "my_frpc",
      "serverAddr": "127.0.0.1",
      "serverPort": "7000",
      "auth_method": "token",
      "bootAtStart": true,
      "runUser": "root",
      "configPath": "./configs/superfrpc_user_my_frpc.toml",
      "createdAt": "2024-01-01T00:00:00Z"
    }
  ]
}
```

**Response (visitor):**
```json
{
  "success": true,
  "message": "instances retrieved successfully",
  "data": [
    {
      "name": "my_frpc",
      "bootAtStart": true,
      "runUser": "root",
      "configPath": "./configs/superfrpc_user_my_frpc.toml",
      "createdAt": "2024-01-01T00:00:00Z"
    }
  ]
}
```

> Note: Visitor users do not see sensitive information (serverAddr, serverPort, auth_method).

---

## User Permissions

| Permission | superuser | admin | visitor |
|------------|-----------|-------|---------|
| Create instance | ✓ | ✓ | ✗ |
| Delete instance | ✓ | ✓ | ✗ |
| Modify instance | ✓ | ✓ | ✗ |
| List instances | ✓ | ✓ | ✓ (limited) |
| Manage users | ✓ | ✗ | ✗ |

## Timestamp Validation

All requests include a `timeStamp` field (Unix timestamp in milliseconds). The server validates that the timestamp is within ±3000ms of the server time. This prevents replay attacks.

## Password Requirements

Passwords must meet the following complexity requirements:
- At least 8 characters
- At least one uppercase letter (A-Z)
- At least one lowercase letter (a-z)
- At least one digit (0-9)
- At least one special character (!@#$%^&*()_+-=[]{}|;:,.<>?)

## Token

Tokens are valid for 1 hour. After expiration, users need to re-login to get a new token.

## Generated Config Files

Instance configuration files are saved in the specified `instancePath` with the naming convention:
```
superfrpc_<username>_<instanceName>.toml
```

Example: `superfrpc_admin_my_frpc.toml`

## License

MIT