Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 8 additions & 3 deletions .github/SECURITY.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,8 @@ In scope, for example:
- a request sent anywhere other than the platform endpoint it targets;
- the JWT secret accepted in its default `change-this-secret-in-production` value in a deployment that never changed it;
- path traversal through upload or file handling;
- the WebSocket upgrade accepting a cross-origin connection that should be rejected.
- the WebSocket upgrade accepting a cross-origin connection that should be rejected, or an unauthenticated socket being accepted at all;
- a request body read without a size ceiling, or a connection held open without a header deadline.

Out of scope:

Expand All @@ -54,6 +55,9 @@ Out of scope:
- Passwords are stored as bcrypt hashes, never in plaintext.
- API tokens are JWTs signed with HS256 and carry an expiry (`jwt.expiration`, 24 hours by default). Rotate `jwt.secret` in `backend/config/config.yaml` per deployment.
- The `/api/v1` surface except `/auth/register` and `/auth/login` sits behind `AuthRequired`. `AdminRequired` exists but is not wired into any route yet.
- Both WebSocket routes (`/ws/adapter`, `/ws/app`) require a valid JWT at the handshake (`?token=`) and reject an unlisted `Origin` before upgrading. The gateway routes (`/ws`, `/ws/adapter-gateway/...`) keep their own per-adapter `?key=`.
- CORS and the WebSocket `CheckOrigin` read one allow-list, `server.allowed_origins`. The accepted origin is echoed rather than sent as `*`, which is the only form where the accompanying `Access-Control-Allow-Credentials` has an effect.
- `http.Server` runs with header, read, write and idle timeouts, and every request body is capped at `server.max_body_bytes` (8 MiB default) — an unbounded body used to be read whole into memory.
- An adapter's `security` policy declares `sensitive_fields` (for Taobao and Xianyu, `cookie`) so a manifest can mark what must not be echoed back.

### What is not there yet
Expand All @@ -62,8 +66,9 @@ Be aware of these when you deploy, and please send a report if one of them bites

- The adapter instance `config` column stores its Cookie as plain JSON in the database, despite the `encrypted_fields` declaration. Treat the SQLite/PostgreSQL file as a secret.
- `AuthRequired` is still a placeholder: it checks the presence and `Bearer` shape of the header but does not yet verify the JWT signature, and it sets a fixed `user-123` identity. Do not expose the API to the internet and assume per-user isolation until that lands.
- CORS sends `Access-Control-Allow-Origin: *` with `Access-Control-Allow-Credentials: true`, and the WebSocket upgrader accepts any origin. Put the front end behind the same origin as the API in production.
- The default `jwt.secret` is a placeholder; change it before you deploy.
- The WebSocket handshake check proves the caller holds a valid token, not that it owns the `instance_id` / `app_id` it asks to bind. One logged-in user can still attach to another user's instance.
- The default `jwt.secret` is a placeholder. Startup logs a WARN while it is unchanged; change it before you deploy. It is not fatal, so a forgotten deployment still comes up — quietly forgeable.


### Front end

Expand Down
8 changes: 6 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -130,8 +130,12 @@ The dev server starts on `http://localhost:3000`.

### WebSocket

- `ws://localhost:8080/ws/adapter?instance_id=xxx` - Adapter WebSocket
- `ws://localhost:8080/ws/app?app_id=xxx` - Application WebSocket
- `ws://localhost:8080/ws/adapter?instance_id=xxx&token=<JWT>` - Adapter WebSocket
- `ws://localhost:8080/ws/app?app_id=xxx&token=<JWT>` - Application WebSocket

Both sockets need a token at the handshake; the same JWT `/auth/login` returns,
passed as `?token=` (or an `Authorization: Bearer` header from a non-browser
client). An unlisted `Origin` is refused too — see `server.allowed_origins`.

The full contract lives in the [API reference](docs/developer-guide/api-reference.md).

Expand Down
8 changes: 6 additions & 2 deletions README.zh-CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -121,8 +121,12 @@ pnpm dev

### WebSocket 接口

- `ws://localhost:8080/ws/adapter?instance_id=xxx` - 接入器 WebSocket
- `ws://localhost:8080/ws/app?app_id=xxx` - 应用 WebSocket
- `ws://localhost:8080/ws/adapter?instance_id=xxx&token=<JWT>` - 接入器 WebSocket
- `ws://localhost:8080/ws/app?app_id=xxx&token=<JWT>` - 应用 WebSocket

两条 WS 都要在握手带令牌(与 `/auth/login` 返回的同一个 JWT,走 `?token=`;
非浏览器客户端可改发 `Authorization: Bearer`)。`Origin` 不在白名单同样会被拒,
白名单见 `server.allowed_origins`。

## 架构设计

Expand Down
12 changes: 10 additions & 2 deletions adapters/taobao/esp_bridge.py
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,7 @@
import uuid
from dataclasses import dataclass, field
from typing import Any, Callable, Dict, List, Optional
from urllib.parse import quote

import requests
import websockets
Expand Down Expand Up @@ -188,9 +189,16 @@ def __init__(
self.running = False

def _ws_url(self) -> str:
"""构造后端适配器 WebSocket 地址。"""
"""构造后端适配器 WebSocket 地址。

握手带 `?token=`:后端在升级前校验 JWT,缺失或过期会回 401 而
不是接受连接。浏览器 WebSocket API 设不了请求头,所以走 query。
"""
base = self.backend_url.replace("http://", "ws://").replace("https://", "wss://")
return f"{base}/ws/adapter?instance_id={self.instance_id}"
url = f"{base}/ws/adapter?instance_id={self.instance_id}"
if self.token:
url += f"&token={quote(self.token, safe='')}"
return url

def _tag(self) -> str:
"""短标签:instance_id 前 8 位,便于在日志中区分多个桥。"""
Expand Down
11 changes: 10 additions & 1 deletion adapters/xianyu/esp_bridge.py
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,7 @@
import uuid
from dataclasses import dataclass, field
from typing import Any, Dict, Optional, Callable
from urllib.parse import quote

import requests
import websockets
Expand Down Expand Up @@ -170,8 +171,16 @@ def __init__(
self.running = False

def _ws_url(self) -> str:
"""构造后端适配器 WebSocket 地址。

握手带 `?token=`:后端在升级前校验 JWT,缺失或过期会回 401 而
不是接受连接。浏览器 WebSocket API 设不了请求头,所以走 query。
"""
base = self.backend_url.replace("http://", "ws://").replace("https://", "wss://")
return f"{base}/ws/adapter?instance_id={self.instance_id}"
url = f"{base}/ws/adapter?instance_id={self.instance_id}"
if self.token:
url += f"&token={quote(self.token, safe='')}"
return url

def _tag(self) -> str:
"""短标签:instance_id 前 8 位,便于在日志中区分多个桥。"""
Expand Down
26 changes: 26 additions & 0 deletions config/config.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,28 @@ host: "0.0.0.0"
port: 8080
version: "1.0.0"

# HTTP hardening.
#
# allowed_origins is the browser-origin allow-list shared by CORS and the
# WebSocket handshake. It is NOT a same-origin allow-list: a deployment served
# behind one reverse proxy needs no entries at all, because the browser then
# sends no Origin. The defaults exist for the Vite dev server (make
# build-frontend-dev / run-desktop) only — replace them with your UI host when
# the UI lives somewhere else. An entry of "*" allows any origin.
#
# The timeouts are seconds; 0 disables the corresponding net/http timeout.
# Active WebSocket connections are unaffected (the upgrade takes the socket off
# these deadlines), so read_timeout/write_timeout do not cut long-lived sockets.
server:
allowed_origins:
- "http://localhost:3000"
- "http://127.0.0.1:3000"
read_header_timeout: 5
read_timeout: 60
write_timeout: 60
idle_timeout: 120
max_body_bytes: 8388608 # 8 MiB; adapter configs are JSON blobs, not files

# Database settings
database:
driver: "sqlite" # sqlite or postgres
Expand All @@ -28,6 +50,10 @@ redis:
log_level: "info" # debug, info, warn, error

# JWT settings
#
# Change the secret before exposing the API. Startup logs a WARN while this is
# still the shipped value, because every copy of the repository has it and
# tokens are HS256-signed with it.
jwt:
secret: "change-this-secret-in-production"
expiration: 24 # hours
Expand Down
71 changes: 69 additions & 2 deletions docs/developer-guide/api-reference.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,54 @@ E-SP-Line2 provides a RESTful API and WebSocket interfaces for managing platform
- **Authentication**: Bearer Token
- **Response format**: JSON

## CORS and origins

The server only names a browser origin it was configured to accept, so the
`Access-Control-Allow-Origin` value is the caller's own origin, never `*`, and
it is paired with `Access-Control-Allow-Credentials: true` (a pair that only
means something when the origin is echoed rather than starred).

The allow-list is one setting, `server.allowed_origins`, shared by the REST
surface and the WebSocket handshake:

```yaml
server:
allowed_origins:
- "http://localhost:3000" # the Vite dev server default
```

- A deployment served behind one reverse proxy is same-origin and needs no
entries. The REST surface sees no `Origin` at all, and the WebSocket
handshake compares the `Origin` host against the request `Host`, so the
embedded desktop build (UI and API on one port) works untouched.
- Add the UI's real scheme+host+port when the UI is hosted separately.
- An entry of `"*"` allows any origin. The origin is still echoed, so the
credentials flag stays meaningful.
- Matching is exact. `http://localhost:3000.evil.example` does not pass for
`http://localhost:3000`, and a different port is a different origin.
- A request with no `Origin` at all (curl, a native client) always passes.

An origin that is not listed still gets a normal HTTP response; the browser
just refuses to hand it to the page. The WebSocket handshake is stricter — the
upgrade is refused with `403`.

## Server limits

`http.Server` runs with the timeouts below and every request body is capped.
Both are configured under `server` in `config/config.yaml` and are in seconds;
`0` disables the corresponding timeout.

| Setting | Default | Effect |
| --- | --- | --- |
| `read_header_timeout` | 5 | A client must finish sending headers in this window (Slowloris) |
| `read_timeout` | 60 | Whole-request read budget, body included |
| `write_timeout` | 60 | Response write budget |
| `idle_timeout` | 120 | Keep-alive reuse budget |
| `max_body_bytes` | 8388608 (8 MiB) | Request body cap; over it the API answers `413` |

Active WebSocket connections are not affected: the upgrade takes the socket off
the HTTP deadlines, so a long-lived socket is not cut at `write_timeout`.

## Authentication endpoints

### User registration
Expand Down Expand Up @@ -752,9 +800,27 @@ Public. Returns the message field contract that [message-fields.md](./message-fi

## WebSocket interface

Both socket routes authenticate **at the handshake**: the token goes in the
query string as `?token=<JWT>` because the browser `WebSocket` constructor
cannot set request headers. A non-browser client may send
`Authorization: Bearer <JWT>` instead. Either way, the token is the same JWT
`/auth/login` returns and it is signature-checked before the upgrade.

Failure is an ordinary HTTP response, so a client can tell "not
authenticated" from "network down":

| Situation | Response |
| --- | --- |
| No token | `401` |
| Malformed, unsigned or expired token | `401` |
| `Origin` present and not allow-listed | `403` |

The check proves the caller holds a valid token. It does not prove the caller
owns the `instance_id` / `app_id` in the query — those remain caller-supplied.

### Adapter WebSocket

**URL**: `ws://localhost:8080/ws/adapter?instance_id=<instance_id>`
**URL**: `ws://localhost:8080/ws/adapter?instance_id=<instance_id>&token=<JWT>`

**Message format**:
```json
Expand All @@ -776,7 +842,7 @@ Public. Returns the message field contract that [message-fields.md](./message-fi

### App WebSocket

**URL**: `ws://localhost:8080/ws/app?app_id=<app_id>`
**URL**: `ws://localhost:8080/ws/app?app_id=<app_id>&token=<JWT>`

**Message format**:
```json
Expand Down Expand Up @@ -805,6 +871,7 @@ Public. Returns the message field contract that [message-fields.md](./message-fi
| 403 | Forbidden |
| 404 | Resource not found |
| 409 | Resource conflict |
| 413 | Request body over `server.max_body_bytes` |
| 500 | Internal server error |

## Rate limiting
Expand Down
12 changes: 10 additions & 2 deletions docs/developer-guide/bridge-protocol.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@
## 1. 概述

- **传输**:WebSocket
- **连接端点**:`ws://<esp-host>:<esp-port>/ws/adapter?instance_id=<INSTANCE_ID>`
- **连接端点**:`ws://<esp-host>:<esp-port>/ws/adapter?instance_id=<INSTANCE_ID>&token=<JWT>`
- **方向**:桥进程主动连接后端核心(桥是 Client,核心是 Server)
- **消息格式**:JSON 文本帧

Expand Down Expand Up @@ -41,9 +41,17 @@ Authorization: Bearer <token>
### 2.2 建立 WebSocket 连接

```
ws://<esp-host>:<esp-port>/ws/adapter?instance_id=<INSTANCE_ID>
ws://<esp-host>:<esp-port>/ws/adapter?instance_id=<INSTANCE_ID>&token=<JWT>
```

`token` 与 2.1 的 `Authorization` 是同一个 JWT。浏览器 `WebSocket` API 设不了
请求头,所以握手令牌走 query;非浏览器客户端也可以改发
`Authorization: Bearer <JWT>`。后端在升级前验签,失败回 `401`,`Origin`
不在白名单回 `403`,客户端据状态码就能区分"没登录"与"网络不通"。

> 令牌只证明调用方持有有效 JWT,不证明它拥有 query 里的 `instance_id`——
> 归属校验仍由实例接口负责。

### 2.3 握手

连接建立后,后端发送 `connected` 消息:
Expand Down
6 changes: 3 additions & 3 deletions docs/developer-guide/inactive-fields.md
Original file line number Diff line number Diff line change
Expand Up @@ -151,7 +151,7 @@

| 链路 | 入口 | 处理代码 |
| --- | --- | --- |
| 桥(Bridge) | `/ws/adapter?instance_id=xxx` | [`handler/websocket.go`](../../internal/handler/websocket.go) `registerToolsFromFrame` |
| 桥(Bridge) | `/ws/adapter?instance_id=xxx&token=<JWT>` | [`handler/websocket.go`](../../internal/handler/websocket.go) `registerToolsFromFrame` |
| 接入框架(server 模式) | `/ws/adapter-gateway?key=xxx` | [`adaptergateway/client.go`](../../internal/adaptergateway/client.go) `handleMessage` |
| 接入框架(client 模式) | E-SP-Line2 主动外拨到框架 | [`adaptergateway/client_connector.go`](../../internal/adaptergateway/client_connector.go) `handleInbound` |

Expand Down Expand Up @@ -241,7 +241,7 @@ tool = adapter.get_gateway_tool('publish_item') # 单个定义
```

网关将其转换为**桥协议**帧(`type: tool_call`,`command_type: tool_call`)下发到
`/ws/adapter?instance_id=xianyu-1` 的连接:
`/ws/adapter?instance_id=xianyu-1&token=<JWT>` 的连接:

```json
{
Expand Down Expand Up @@ -443,7 +443,7 @@ curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/jso

## 5. 桥(Bridge)实现工具

桥在 `/ws/adapter?instance_id=<ID>` 连接上接收 `tool_call` 帧,执行后回 `tool_result`。
桥在 `/ws/adapter?instance_id=<ID>&token=<JWT>` 连接上接收 `tool_call` 帧,执行后回 `tool_result`。

Python 伪代码:

Expand Down
7 changes: 5 additions & 2 deletions docs/user-guide/troubleshooting.md
Original file line number Diff line number Diff line change
Expand Up @@ -161,9 +161,12 @@ queue:

**Implement reconnect logic**
```javascript
// Frontend reconnect example
// Frontend reconnect example. The handshake needs the JWT (the browser
// WebSocket API cannot set an Authorization header, so it goes in the query)
// and an allow-listed Origin.
function connect() {
const ws = new WebSocket('ws://localhost:8080/ws/app');
const token = localStorage.getItem('auth_token');
const ws = new WebSocket(`ws://localhost:8080/ws/app?app_id=app-1&token=${token}`);

ws.onclose = () => {
setTimeout(connect, 5000);
Expand Down
8 changes: 5 additions & 3 deletions internal/adaptergateway/gateway.go
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,10 @@ type GatewayConfig struct {
ReadTimeout int
// MaxMessageSize is the maximum inbound frame size in bytes.
MaxMessageSize int64
// CheckOrigin decides which browser origins may open a gateway socket,
// including the custom per-adapter listen paths. A nil value allows every
// origin, which is what the gateway did before the allow-list existed.
CheckOrigin func(*http.Request) bool
}

// DefaultGatewayConfig returns the default gateway configuration.
Expand Down Expand Up @@ -297,9 +301,7 @@ func NewGateway(cfg GatewayConfig, svc *service.AdapterGatewayService) *Gateway
upgrader: websocket.Upgrader{
ReadBufferSize: 1024,
WriteBufferSize: 1024,
CheckOrigin: func(r *http.Request) bool {
return true // Allow all origins for development
},
CheckOrigin: cfg.CheckOrigin,
},
}

Expand Down
Loading
Loading