diff --git a/README.md b/README.md index fb6d842..062aa4f 100644 --- a/README.md +++ b/README.md @@ -49,465 +49,8 @@ GOOS=linux GOARCH=amd64 go build -o super-frpc ## 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" -} -``` - ---- - -<<<<<<< HEAD -### Create frpc Instance -======= -### 3. Create frpc Instance ->>>>>>> 232e87ae368e0437f2f0d82f1d894741f4412ae0 - -**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 - } -} -``` - ---- - -### 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" - } -} -``` - ---- - -### 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 - ---- - -### 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__.toml -``` - -Example: `superfrpc_admin_my_frpc.toml` +For detailed API documentation, please see [docs/api.md](docs/api.md) ## License -MIT +GPL-3.0 diff --git a/docs/api.md b/docs/api.md new file mode 100644 index 0000000..f3fdace --- /dev/null +++ b/docs/api.md @@ -0,0 +1,456 @@ +# 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" +} +``` + +--- + +## 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 + } +} +``` + +--- + +## 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" + } +} +``` + +--- + +## 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 + +--- + +## 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__.toml +``` + +Example: `superfrpc_admin_my_frpc.toml`