backend/README.md

# 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)

---

### 1. 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.

---

### 2. 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"
  }
}
```

---

### 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/{field}`  
**Method:** POST  
**Content-Type:** application/json  
**Auth Required:** Yes (token)

You can modify multiple fields at once:

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

**Request Body:**
```json
{
  "instanceName": "my_frpc",
  "name": "new_name",
  "serverAddr": "192.168.1.1",
  "serverPort": "7000",
  "auth_method": "token",
  "runUser": "www-data",
  "bootAtStart": false
}
```

**Response:**
```json
{
  "success": true,
  "message": "instance modified successfully",
  "data": {
    "name": "new_name",
    "configPath": "./configs/superfrpc_user_new_name.toml"
  }
}
```

---

### 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