Files
ecs-relay-service/deployment-source/docs/PROTOCOL.md

118 lines
6.9 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 中继协议 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验证结果。