# 中继协议 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验证结果。