6.9 KiB
中继协议 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上额外放开这些路径。
设备注册与绑定
- PC生成Ed25519私钥和随机32位hex host_id,只发送公钥申请。
- 离线签发工作站签发带
clientAuth、SAN URIurn:hainuo:host:{host_id}的设备证书。 - 管理员将证书登记到B1。B1持久保存证书指纹,并把准入指纹同步到Redis。
- 本人私聊机器人
/绑定。绑定码具有96位随机熵、TTL300秒;Redis只保存码的SHA256索引和owner。 - 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的公开接口。
隧道握手
- B2发送
{type:"challenge",challenge:随机值}。 - PC每次连接生成临时X25519密钥和session_id,提交证书与签名proof:
{"host_id":"...","cert":"PEM证书","proof":{"host_id":"...","session_id":"...","challenge":"...","kx":"X25519公钥base64url","ts":1793000000,"signature":"..."}}
- B2验证CA、证书有效期、用途、host_id、挑战、时间、注册指纹和吊销状态。通过后设置30秒在线租约,8秒续约;第二连接被拒绝。
- 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验证结果。