鸿渐加密客户端：让网关与存储只见密文

鸿渐支持端到端加密调用：客户端在本地把请求加密，网关只做鉴权、路由、计费与密文转发，明文只在受控沙箱内短暂出现。本文用 hj-crypto CLI 走一遍完整流程。

加密客户端是独立桌面/CLI 应用（crypto-app/），不是浏览器插件。它保护的是“客户端 → 网关与存储”这一段；沙箱与最终上游模型仍会看到解密后的明文（详见第 6 节，不要把它理解成“服务端永远不可见”）。

1. 生成密钥

hj-crypto keygen --out ~/.hongjian/key.bin
# 输出：public-key（base64）与 fingerprint

私钥用你的密码加密后落盘；公钥与指纹可以公开。私钥丢失 = 历史密文不可解，请离线备份 key.bin 与密码。

2. 在鸿渐控制台绑定公钥

控制台 → API Keys → 编辑目标 Key → 填入 public-key。绑定后，这个 Key 才能提交 ciphertext；未绑定的 Key 会返回 409 encrypted_key_not_configured。

同时确认沙箱公钥指纹与文档/控制台一致（当前内测环境为 6a11f04182ec3f5f2c9cdf85e84af1a6）。客户端应 pin 这个指纹，指纹变化时拒绝发送，防止中间人替换服务端公钥。

3. 加密请求

请求体是规范 OpenAI Chat Completions JSON：

{
  "model": "deepseek-chat",
  "messages": [{"role": "user", "content": "用一句话解释端到端加密"}],
  "max_tokens": 200
}

hj-crypto encrypt \
  --server-pub "$HUGEN_SANDBOX_PUB_KEY" \
  --input req.json \
  --output req.env.json
# 可选：--alg chacha20-poly1305 / xchacha20-poly1305
# 可选：--resp-alg 声明响应使用的算法

生成的 Envelope 形如：

{"v":2,"alg":"aes-256-gcm","eph_pub":"...","recip_fp":"...","nonce":"...","ct":"...","aad":"..."}

4. 发送与解密

curl https://hugen.tydash.net/v1/chat/completions \
  -H "Authorization: Bearer $HUGEN_KEY" \
  -H 'content-type: application/json' \
  -d "$(jq -n --arg model deepseek-chat --slurpfile env req.env.json \
        '{model:$model, stream:false, ciphertext:($env[0]|tostring), client_pub_key:"<你的公钥>"}')"

hj-crypto decrypt --key ~/.hongjian/key.bin --input resp.env.json --output resp.json

服务端返回 ciphertext、sandbox_pub_key_fp 与 usage；usage 在密文外，供网关计费，不含你的提示词明文。

5. 流式

流式请求把 stream 设为 true，响应是 SSE；每个 data: 帧是独立密文， AAD 绑定 session_id|seq，必须按序解密：

data: {"seq":0,"ciphertext":"..."}
data: {"seq":1,"ciphertext":"..."}
data: {"seq":N,"final":true,"usage":{...}}
data: [DONE]

乱序、重放或跨会话拼接都会解密失败。断线重连时从最后一个成功解密的 seq+1 继续，不要重放已收到的帧（否则会被重放防护拒绝）。

6. 信任边界（务必如实理解）

flowchart LR
  C["客户端<br/>持私钥"] -->|"密文"| G["网关<br/>鉴权/路由/计费"]
  G -->|"密文 + 路由目标"| S["加密沙箱<br/>gVisor 只读根/零 capability"]
  S -->|"解密后调用"| U["上游模型"]
  U -->|"明文响应"| S
  S -->|"重新加密"| G --> C

网关、数据库、对象存储：只见密文；
加密沙箱：会解密，运行在 gVisor（用户态内核）里，降低逃逸与提权风险；
上游模型厂商：会看到明文请求（这是推理本身的要求）；
宿主机 root / 云厂商：gVisor 不能阻止他们读内存。要消除这一层需要 SEV-SNP / TDX 等 TEE 与远程证明，当前内测环境没有 TEE。

因此对外文案不要写“服务端永远看不到明文”；准确说法是“网关与存储不可见，沙箱是受控解密边界，TEE 尚未启用”。

7. 常见错误

错误	原因
`409 encrypted_key_not_configured`	API Key 未绑定客户端公钥
`401` / 解密失败	私钥与公钥不匹配，或 `recip_fp` 不是你的指纹
`replay detected`	同一密文重复提交（重试请重新加密）
`sandbox_unavailable`	沙箱未启动/不健康；看 `GET /healthz` 与告警