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

6.9 KiB
Raw Permalink Blame History

中继协议 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发送:
{"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:
{"host_id":"...","cert":"PEM证书","proof":{"host_id":"...","session_id":"...","challenge":"...","kx":"X25519公钥base64url","ts":1793000000,"signature":"..."}}
  1. B2验证CA、证书有效期、用途、host_id、挑战、时间、注册指纹和吊销状态。通过后设置30秒在线租约,8秒续约;第二连接被拒绝。
  2. B1发送前独立核对持久库指纹、设备证书、握手签名,不能信任B2下发一个新公钥。

加密信封

{"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内:

{"type":"instruction","turn_id":"稳定请求ID","owner":"ou_xxx","text":"/主机名","read_only":true,"channel":"im","reply_key":"B1临时回复公钥"}

PC必须再次核对owner;签名有效不代表可以执行任意系统操作。

回复:

{"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:

{"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验证结果。