# 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
**Permission Level:** None

**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  
**Permission Level:** None

**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)
**Permission Level:** None

**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"
}
```

---

## Create User

**Endpoint**: `/userMgr/create`  
**Method**: POST  
**Content-Type**: application/json  
**Auth Required**: Yes (token)  
**Permission Level**: Superuser

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

**Request Body**:
```json
{
  "username": "new_user",
  "passwd": "NewPass123!",
  "type": "admin"
}
```

**Response**:
```json
{
  "success": true,
  "message": "User created successfully",
  "data": {
    "userID": 2,
    "username": "new_user",
    "type": "admin"
  }
}
```

---

## Remove User

**Endpoint**: `/userMgr/remove`  
**Method**: POST  
**Content-Type**: application/json  
**Auth Required**: Yes (token)  
**Permission Level**: Superuser

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

**Request Body**:
```json
{
  "targetUserID": 2
}
```

**Response**:
```json
{
  "success": true,
  "message": "User removed successfully"
}
```

---

## List Users

**Endpoint**: `/userMgr/list`  
**Method**: GET  
**Auth Required**: Yes (token)  
**Permission Level**: Superuser

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

**Response**:
```json
{
  "success": true,
  "message": "User list retrieved successfully",
  "data": [
    {
      "userID": 1,
      "username": "admin",
      "type": "superuser"
    },
    {
      "userID": 2,
      "username": "new_user",
      "type": "admin"
    }
  ]
}
```

---

## Create frpc Instance

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

**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
  }
}
```

---

## Delete frpc Instance

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

**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"
  }
}
```

---

## Modify frpc Instance

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

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

---

## List frpc Instances

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

Retrieve a list of all frpc instances.

**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`