feat: encrypt desktop sub requests
This commit is contained in:
gongzhiyong
@@ -257,19 +257,19 @@
|
||||
|
||||
| 项 | 内容 |
|
||||
|---|---|
|
||||
| 目标 | 明确桌面客户端调用 Manager 时，请求体当前依赖 HTTPS/TLS 传输加密；是否需要额外应用层 body 加密需单独评估，不默认混入 sub 敏捷接口 |
|
||||
| 目标 | 桌面客户端调用 Manager 的 sub 流程接口时，支持与模型调用一致的 V2 应用层 body 加密；浏览器后台页面继续兼容普通 HTTPS JSON |
|
||||
| 修改文件 | `docs/integration/heicode-desktop-sub-agile-api.md`、`docs/heicode-runtime-auth-newapi-secret-design.md`、必要时补充 `heicode/middleware` 或客户端 SDK 加解密模块 |
|
||||
| 当前现实 | 生产入口应使用 `https://code.xinghanlab.com`；JSON body 在网络传输中由 TLS 加密，到 Manager 后端后按普通 JSON 解析 |
|
||||
| 当前现实 | `/api/agnet/user/*` 与 `/api/heicode-auth/*` 已支持 `Content-Encoding: heicode-aead-v1`；Manager 会先解密并校验设备签名，再把明文 JSON 交给业务处理或代理给上游 |
|
||||
| 安全红线 | 请求体、回调、日志、artifact metadata、timeline 中禁止出现明文密码、Token、私钥、连接串、云 access key、模型 key；长期凭证只传 `secret_ref` |
|
||||
| 后续判断 | 如有合规要求再设计应用层加密，例如请求体 AES-GCM + 短期会话密钥/设备公钥；同时要设计密钥分发、轮换、重放保护、版本兼容和排障方案 |
|
||||
| 测试 | 检查生产 API 只走 HTTPS；敏感字段扫描；单测覆盖疑似明文凭据拒绝；如实现应用层加密，再补加解密兼容测试 |
|
||||
| 后续判断 | 桌面客户端需要在 sub 流程调用中复用模型调用的 encryptedFetch/V2 签名能力；服务端保留未加密 JSON 只用于 Manager Web 控制台兼容 |
|
||||
| 测试 | 单测覆盖 V2 malformed 请求拒绝、普通代理请求兼容；生产需用真实已配对设备发起加密 sub 请求冒烟 |
|
||||
|
||||
验收标准：
|
||||
|
||||
- 文档明确“HTTPS 传输加密已覆盖 body 在网络中的保密性”，不误导为当前已有业务层 body 加密。
|
||||
- 文档明确桌面端优先走 V2 应用层 body 加密，且保留浏览器后台未加密 JSON 兼容。
|
||||
- 客户端对接文档明确禁止传明文长期凭据，只允许 `secret_ref` / `lease://...` / 资源元数据。
|
||||
- 服务端日志不打印请求 body 中的敏感字段。
|
||||
- 如果后续实现应用层 body 加密，必须保留版本字段和灰度开关，避免旧客户端直接不可用。
|
||||
- V2 加密失败时返回 `X-Heicode-Auth-Error` 和 `X-Heicode-Server-Time`，便于客户端排障。
|
||||
|
||||
## 五、推荐执行批次
|
||||
|
||||
@@ -353,7 +353,7 @@ Manager 独立任务完成，不等于蜂群生产闭环完成。本文完成的
|
||||
| 幂等 | 重复回调不重复写入 |
|
||||
| 审计 | task/deployment/correlation_id 下能聚合审计、审批、artifact、callback |
|
||||
| 安全 | API、日志、页面不出现明文长期密钥 |
|
||||
| 请求加密 | 文档明确当前依赖 HTTPS/TLS 传输加密；应用层 body 加密如需实现，有清晰设计和兼容策略 |
|
||||
| 请求加密 | 桌面端 sub 请求支持与模型调用一致的 V2 body 加密；浏览器后台普通 JSON 兼容路径不受影响 |
|
||||
| 口径 | 页面和文档不把本地占位/模拟事件说成真实 Runtime |
|
||||
|
||||
## 八、执行时不能突破的边界
|
||||
@@ -365,4 +365,4 @@ Manager 独立任务完成，不等于蜂群生产闭环完成。本文完成的
|
||||
5. 不把本地模拟事件当真实蜂群完成证据。
|
||||
6. 不把 Azure Key Vault 暴露成普通用户要直接操作的后台。
|
||||
7. 不绕过客户端高危审批的产品边界；Manager 只能先提供记录和 API。
|
||||
8. 不在未完成密钥协商、轮换和兼容设计前，临时硬塞应用层 body 加密，避免客户端和 Manager 联调不可排障。
|
||||
8. 不破坏 V2 body 加密的版本字段、诊断头、重放保护和未加密 Web 控制台兼容路径，避免客户端和 Manager 联调不可排障。
|
||||
|
||||
@@ -22,7 +22,59 @@ Manager 负责辅助控制面：任务草稿桥接、资源/权限、Agnet deplo
|
||||
| `/api/agnet/user/*` | Manager 用户态 Agnet 控制面，deployment、timeline、artifact、审批 | Manager 登录 session cookie + `New-Api-User: <user_id>` |
|
||||
| `/api/user/self` | 查询当前 Manager 用户 | Manager 登录 session cookie |
|
||||
|
||||
### 2.2 Manager 用户态 Header
|
||||
### 2.2 桌面端请求 body 加密
|
||||
|
||||
桌面客户端调用 Manager 的 sub 流程接口时，应优先使用与模型调用一致的 V2 加密请求协议。
|
||||
|
||||
适用接口：
|
||||
|
||||
| API 前缀 | V2 加密 body | 说明 |
|
||||
|---|---|---|
|
||||
| `/api/agnet/user/*` | 支持 | Manager 解密并校验设备签名后，按当前设备对应用户执行 |
|
||||
| `/api/heicode-auth/*` | 支持 | Manager 解密并校验设备签名后，把明文 body 代理给上游 HeicodeTask 服务；仍需携带 `heicode_access_token` |
|
||||
| 浏览器后台普通页面请求 | 兼容未加密 JSON | 不影响现有 Manager Web 控制台 |
|
||||
|
||||
V2 请求头与模型调用一致：
|
||||
|
||||
```http
|
||||
Content-Encoding: heicode-aead-v1
|
||||
X-Heicode-Device-Id: <device_id>
|
||||
X-Heicode-Timestamp: <unix_ms>
|
||||
X-Heicode-Nonce: <nonce_hex>
|
||||
X-Heicode-Fingerprint: <device_fingerprint>
|
||||
X-Heicode-Eph-Pubkey: <base64_x25519_ephemeral_pubkey>
|
||||
X-Heicode-Signature: <base64_ed25519_signature>
|
||||
X-Heicode-Client-Version: <desktop_version>
|
||||
Content-Type: application/json
|
||||
Accept: application/json
|
||||
```
|
||||
|
||||
加密和签名协议沿用模型调用：
|
||||
|
||||
```text
|
||||
body = nonce || ChaCha20-Poly1305(plaintext_json, aad)
|
||||
aad = device_id + "|" + timestamp + "|" + nonce + "|" + method + "|" + path_with_query
|
||||
|
||||
canonical = method + "\n"
|
||||
+ path_with_query + "\n"
|
||||
+ timestamp_ms + "\n"
|
||||
+ nonce_hex + "\n"
|
||||
+ device_fingerprint + "\n"
|
||||
+ ephemeral_pubkey_b64 + "\n"
|
||||
+ sha256_hex(plaintext_body)
|
||||
|
||||
signature = base64(ed25519_sign(device_private_key, sha256(canonical)))
|
||||
```
|
||||
|
||||
`/api/heicode-auth/*` 额外要求：
|
||||
|
||||
```http
|
||||
Authorization: Bearer <heicode_access_token>
|
||||
```
|
||||
|
||||
原因：该 token 是上游 HeicodeTask 服务认证用；V2 设备签名只证明请求来自已配对的 Manager 桌面设备。
|
||||
|
||||
### 2.3 Manager 用户态 Header
|
||||
|
||||
调用 `/api/agnet/user/*` 时必须带：
|
||||
|
||||
@@ -35,7 +87,9 @@ Accept: application/json
|
||||
|
||||
`New-Api-User` 必须等于当前登录用户 ID，否则会返回未授权。
|
||||
|
||||
### 2.3 统一响应 Envelope
|
||||
使用 V2 加密 body 时，`/api/agnet/user/*` 可以不依赖浏览器 session cookie；Manager 会从设备绑定 token 中解析用户身份。为兼容当前 Web 控制台，未加密请求仍按 session cookie + `New-Api-User` 处理。
|
||||
|
||||
### 2.4 统一响应 Envelope
|
||||
|
||||
成功：
|
||||
|
||||
|
||||
Reference in New Issue
Block a user