Import ECS deployed relay source and historical patches (2026-10-27)

This commit is contained in:
ex_tianzy
2026-10-27 17:26:58 +08:00
commit 011a7797ee
319 changed files with 34265 additions and 0 deletions
+117
View File
@@ -0,0 +1,117 @@
# 中继协议 v1
## 服务接口
| 端点 | 身份/约束 | 用途 |
|---|---|---|
| GET /health | 无 | 存活 |
| GET /ready | 内部网络 | 依赖就绪 |
| POST /admin/devices | X-Admin-Secret | 登记CA签发的设备证书 |
| GET /admin/devices | 同上 | 设备、绑定和在线状态 |
| POST /admin/devices/{host}/revoke | 同上 | 持久吊销并断连 |
| POST /admin/reconcile | 同上 | 从持久库恢复路由准入数据 |
| POST /admin/test/binding-code | 同上,非production | 生成模拟账号绑定码 |
| POST /admin/test/dispatch | 同上,非production | 同步等待模拟指令结果 |
| POST /device/bind | 设备签名+一次性绑定码 | 本机完成绑定 |
| WS /device/ws | B2:CA证书+挑战签名 | PC出站隧道 |
| POST /feishu/event | 平台签名、Token、时窗 | webhook接入 |
| POST /internal/events | X-Internal-Secret | 官方SDK进程转入事件 |
| POST /oauth/start | 限流、容量限制 | 创建授权事务 |
| GET /oauth/cb | 服务端state | 收码后立即换token |
| GET /oauth/claim | state+X-OAuth-Claim-Secret | 一次领取token |
| GET /oauth/pending | 同上 | 查询状态,无token |
| POST /oauth/refresh | refresh_token,防并发重复 | 刷新、返回新token |
| GET /proxy | 本人Bearer+X-Relay-Target | 默认关闭的只读数据代理 |
| GET /api/whoami | 本人Bearer,经平台验证 | 查询本人设备URL |
| GET /h5 | 无,页面内发起OAuth | 入口壳 |
管理接口和internal/events不通过公网反代。不要在nginx/Caddy上额外放开这些路径。
## 设备注册与绑定
1. PC生成Ed25519私钥和随机32位hex host_id,只发送公钥申请。
2. 离线签发工作站签发带 `clientAuth`、SAN URI `urn:hainuo:host:{host_id}`的设备证书。
3. 管理员将证书登记到B1。B1持久保存证书指纹,并把准入指纹同步到Redis。
4. 本人私聊机器人 `/绑定`。绑定码具有96位随机熵、TTL300秒;Redis只保存码的SHA256索引和owner。
5. PC向 `/device/bind`发送:
```json
{"host_id":"32位hex", "proof":{"host_id":"同一host_id","code":"绑定码","ts":1793000000,"signature":"base64url签名"}}
```
签名覆盖去掉signature后的规范JSON。B1先校验证书、签名、时间和注册状态,再原子消费绑定码,持久绑定owner↔host。返回连接器签名的绑定回执;PC使用预置信任公钥验证回执并保存owner。
本版一人一台、一台一人;解绑后必须在PC重新绑定。本版不提供远端任意指定owner的公开接口。
## 隧道握手
1. B2发送 `{type:"challenge",challenge:随机值}`。
2. PC每次连接生成临时X25519密钥和session_id,提交证书与签名proof:
```json
{"host_id":"...","cert":"PEM证书","proof":{"host_id":"...","session_id":"...","challenge":"...","kx":"X25519公钥base64url","ts":1793000000,"signature":"..."}}
```
3. B2验证CA、证书有效期、用途、host_id、挑战、时间、注册指纹和吊销状态。通过后设置30秒在线租约,8秒续约;第二连接被拒绝。
4. B1发送前独立核对持久库指纹、设备证书、握手签名,不能信任B2下发一个新公钥。
## 加密信封
```json
{"v":1,"host_id":"...","session_id":"...","ts":1793000000,"nonce":"12随机字节base64url","ephemeral":"消息发送方临时X25519公钥","ciphertext":"AESGCM密文和tag","signature":"Ed25519签名"}
```
- JSON规范化:UTF-8、键排序、无多余空白、非ASCII不转义。
- ECDH:每消息临时发送密钥 ↔ 当前连接的临时接收密钥。
- HKDF-SHA256:32字节,salt=session_id UTF-8,info=`hainuo-relay-envelope-v1`。
- AEAD:AES-256-GCM;AAD是除ciphertext和signature以外的信封字段。
- 签名:覆盖除signature外所有字段;验证后再解密。
- 接收方验证host、session和90秒时间窗。真正执行去重使用稳定turn_id,PC侧持久记录,不依赖nonce缓存。
- B1每次请求生成独立临时回复密钥,公钥放在加密的请求体中;私钥只在等待结果期间持有。
长期Ed25519身份密钥不参与内容ECDH。已销毁临时密钥的历史流量不能仅凭长期签名私钥解密。本版未接受独立密码协议审计,不将该设计等同已通过企业密码评估。
请求明文只在B1与对应PC内:
```json
{"type":"instruction","turn_id":"稳定请求ID","owner":"ou_xxx","text":"/主机名","read_only":true,"channel":"im","reply_key":"B1临时回复公钥"}
```
PC必须再次核对owner;签名有效不代表可以执行任意系统操作。
回复:
```json
{"type":"reply","turn_id":"同一ID","envelope":{"...":"加密信封"}}
```
解密后为 `{type:"result",turn_id:"同一ID",result:"结果"}`。B2检查存在该host、session、turn的在途记录,B1再检查签名、加密和请求归属。PC不能指定其他聊天收件人。
## 去重和失败语义
- 平台事件以message_id派生稳定turn_id;消息重投不会重新生成随机执行ID。
- B1在发布前写持久去重台账,PC执行前写本机journal。两端均采取“宁可状态未知,不自动重复执行”。
- Redis使用Pub/Sub,不缓存正文,不离线排队。主机离线即返回offline。
- 超时/重启丢失在途结果返回unknown或等待超时,不能当成未执行。重新生成新ID有可能再次执行,应由用户核查。
- 同一ID重复提交只返回duplicate,不缓存/重放原结果正文。
- B1后台处理失败写元数据状态,当前版本没有可靠消息发件箱;已执行但回平台失败时不会自动再次执行。
## 本地Agent适配接口(需客户端开发实现)
固定回环地址,例如 `POST http://127.0.0.1:8765/relay/read-only`:
```json
{"text":"整理测试目录内的文档","open_id":"ou_xxx","turn_id":"...","channel":"im","read_only":true}
```
成功返回HTTP200:`{"result":"助手结果"}`。桥接端只接受文本结果、限制大小,不跟随重定向。可通过桥接端环境变量 `HN_LOCAL_AGENT_TOKEN`提供本地Bearer凭据。
该接口不是从1.065中发现的真实接口,而是本次新增适配契约。Agent服务需要实现按turn_id去重、主体与文件权限校验、只读工具白名单;不能只把read_only字段拼进提示词。未提供适配接口时,诊断命令仍能正常工作。
## OAuth与代理
沿用原手册v1.2响应字段;使用平台实际返回的expires_in/expire,不写死7200。待取token只存在B1内存,600秒过期,领取即删除。错误claim_secret返回404且不消费;同一code并发回调只换一次。
刷新用refresh_token摘要作为分布式一次尝试标记,保留30天。网络故障可能导致平台已轮换但客户端未拿到结果,因此不重试旧token,要求重新授权。
代理固定走配置的平台域名,只支持明确白名单的GET接口;永不使用应用token代替用户token,不代理换token接口,不跟随重定向,不持久保存响应正文。token每次由平台user_info验证,本版不缓存token验证结果。