jkooe
cc0aaffffd
fix(pairing): 配对码改由设备本地生成、随连接上报 —— 零鉴权取码端点下线为 410（M4″）
## 修的是什么
`POST /api/pairing/code {device_id}` 原先**零鉴权地生成码并在响应体里返回**：
```
POST /api/pairing/code {"device_id":"<任何存在的设备>"}
→ 200 {"code":"483920","expires_at":...}
```
只要知道一个存在的 `device_id`，**任何人不登录、不持有任何凭据**，就能拿到该设备
的配对码，再去查看端输入，换到该设备的查看授权。比认领洞更浅：认领洞还要先登录。
根因不是"端点忘了加鉴权"，是**码的来源错了**。服务端凭什么相信"请求方就是那台
设备"？`device_id` 是可猜的公开标识；`device_token` 只发给已归属设备（新设备会
成环，M4′ 里已经推演过）。唯一不可伪造的是**那条已建立的连接本身**。
## 改成什么
码由设备本地生成（`client/lib/host/pairing_code.dart`），随 `agent:hello` 的
`payload.claim_code` 上报，网关在这一刻登记为配对码（`PairingStore.registerDeviceCode`），
**断连即删**（`forgetDeviceCode`），TTL 300s 只是崩溃兜底。
于是码的语义变成真话：**"设备此刻在这条连接上活着"**。屏幕上那个码因此永远是服务端
认可的那一个，不存在"屏幕显示 A、服务端认 B"。
**配对码与认领码是同一个字符串**：用户只有一个六格输入框的心智，两条链路各发一个码
只会让人念错。
`POST /api/pairing/code` 保留为 **410 `E_ENDPOINT_GONE`** 而不是删掉：404 会让人以为
路径拼错或版本不对，410 明确说"它被有意移除了，码从哪来"。
## 客户端
`pairing_api.issueCode` 改为**幂等只读**：返回单例里的当前码，不发网络。别把它改成
"每次调用都换一个码" —— 换了却不同时重发 hello，屏幕就会显示一个服务端从未登记过的
值，用户念它必然失败，而且看起来像服务端坏了。
## 顺带补上 M4′ 在客户端的缺口
上一轮 M4′ 只做了服务端：`grep claim_code client/lib` 命中 **0**。也就是服务端能力建好
了、测试全绿，而**真实客户端从不上报码** —— 生产上认领只能走 `isNew` 路径。同一个
"必须有真实产生方"的坑在 M5 里刚踩过一次（表恒空）。本次 `link.dart` 的 hello 已带
`claim_code`，两条链路同时有了产生方。
## ⚠️ 一个比原洞更大的发现：84 项配对回归网跑的是 9 天前的镜像
`tests/pairing-security-test.js` 默认打 `http://127.0.0.1:4000`，那是 docker-compose
的实例。实测 `pmon-business-1` / `pmon-gateway-1` 镜像构建于 **2026-10-30**，而本轮
改动在 **2026-11-08** —— 早 9 天。所以那些"84 项全绿"只证明旧镜像行为没变，对仓库里的
代码一个字都没说。
所以本套件（`pairing-code-origin-test.js`）**自起源码实例**（business + gateway，
随机端口，源码直跑），并在 `run-all.sh` 里那一段加了大字警告：在其余套件改成自起
之前，**不要把它们的绿当作本仓代码的回归证据**。
## 测试
`tests/pairing-code-origin-test.js` **16 项全绿**，已接入 `run-all.sh`。16 条里 13 条是
"拿不到"型（410 / 无码返回 / 猜码被拒 / 跨设备被拒 / 断连失效），3 条是"该拿到的人
拿得到"（hello 登记、verify 成功、一次性消费）—— 只验前者的话，一个把配对整体做死的
实现也能全绿。
客户端：`pairing_card_test` 6/6、全量 **595 通过 / 2 失败**（两条仍是 `libpmon_core.dylib`
未编译）。两条断言按行为变更改写而不是删除：
- "发码失败不静默" → 改为"**一次请求都不发**"（失败路径已不存在，但新风险更大：
任何一次发出的取码请求都意味着码又能被第三方索取）；
- "服务端返回 123456" → 改为"卡片显示的码必须与上报给服务端的是同一个"。
第一次跑本套件时 E 段红了两条，原因是我自己的夹具没关掉前一条连接 —— 网关判定
"这台设备还有别的活连接"，正确行为就是不删码。已修，并在测试里写清这个坑。
回归：认领 57/0、埋点 29/0、权限 60/0、schema 116/0。
2026-11-08 19:57:57 +08:00
..
2026-11-08 19:57:57 +08:00
2026-11-08 19:57:57 +08:00
2026-11-08 19:46:29 +08:00
2026-09-13 10:36:22 +08:00
2026-09-16 12:09:53 +08:00