Remove docs/dsh-go-pairing-integration.md (deleted upstream)
This commit is contained in:
parent
c0248212d5
commit
7e3d8f0eaf
|
|
@ -1,239 +0,0 @@
|
|||
# DSH Go 接入扫码配对
|
||||
|
||||
服务端与 Remote 插件已实现。DSH-Go 需要实现本文的手机侧流程,尚未完成 Dart / Android 真机验收。
|
||||
|
||||
权威协议:[device-pairing-v1.md](device-pairing-v1.md)。先执行该协议的固定密钥证明向量,再接入界面和自动连接;不要自行改动 API、状态名称或证明字节编码。
|
||||
|
||||
## 用户看到的流程
|
||||
|
||||
1. 在 DSH-Go 的 Remote 入口选择扫描电脑二维码。
|
||||
2. 展示服务器、Host 名称及公钥指纹,用户在手机主动确认。
|
||||
3. 手机提交 claim 后显示 Server 返回的 8 位验证码,保留前导零。
|
||||
4. 提示用户到**电脑本机 Remote 插件设置**输入验证码、点击“确认绑定”。手机绝不替电脑提交。
|
||||
5. 手机轮询等待;Server 完成后安全保存本手机的设备凭证、固定 Host 公钥,自动连接二维码指定的 Host。
|
||||
|
||||
文案必须说明:**验证码只有一次校验机会,电脑输错后整个会话失效,需重新生成二维码、扫码和手机确认。**
|
||||
|
||||
手机不得提供“替电脑确认”、自动回填、复制/分享验证码到聊天或后台自动猜码的功能。验证码不进入日志、通知正文、分析事件、普通配置或剪贴板。前后台切换、截图及后台预览保护按平台能力落实,并保留无障碍操作。
|
||||
|
||||
## 在现有源码中的接入位置
|
||||
|
||||
此前源码审查基于 DSH-Go `219f2d1`;实施前复核当前分支,路径或函数变化时按实际实现调整:
|
||||
|
||||
| 位置 | 建议改造 |
|
||||
| --- | --- |
|
||||
| `packages/dsh_remote/lib/src/server/server_api.dart` | 二维码校验、mobile proof、claim、mobile/status、mobile/cancel 请求 |
|
||||
| `packages/dsh_remote/lib/src/account/remote_account.dart` | 独立设备身份复用、配对状态、凭证导入、安全存储、Host 公钥固定 |
|
||||
| `app/lib/remote/relay/dsh_remote_backend.dart` | 向 App 暴露扫码配对状态,完成后复用现有连接路径 |
|
||||
| `app/lib/state/hosts_state.dart` | 目标 Host 选择、取消/退出/服务器切换竞态隔离 |
|
||||
| `app/lib/remote/secret_store.dart` | 复用 flutter_secure_storage,不新增普通设置中的秘密存储 |
|
||||
| App Remote 界面 | 相机扫码、手机确认、验证码展示、等待/失败/重试状态 |
|
||||
|
||||
配对是设备登录路径,不走 `_registerWithAccountToken`,不调用 `/auth/register`、`/auth/login`、网站 OAuth 或 `/devices/register`。可以复用其中的身份准备、Token 校验、凭证持久化和状态发布步骤,但不要再请求 Web Token。
|
||||
|
||||
新增方法名由 DSH-Go 自行决定;本文没有宣称其已存在或已实现。
|
||||
|
||||
## 二维码
|
||||
|
||||
## 短凭据二维码(fragment-ticket-v1)
|
||||
|
||||
登录方式发现接口仍为 `GET /api/v1/auth/oauth/providers`,新增独立字段:
|
||||
|
||||
```json
|
||||
{"capabilities":{"devicePairing":"dsh-pairing-v1","devicePairingQr":"fragment-ticket-v1"},"items":[]}
|
||||
```
|
||||
|
||||
新 Remote 仅在服务端明确声明 `devicePairingQr` 时生成短二维码,否则保留旧 JSON 格式;旧 Remote 的创建响应和配对 API 不变。既有未完成的 JSON 二维码继续有效,重启后保留会话原格式。能力发现的网络/非法响应错误不能静默当成不支持;旧发现接口 404 可以保留 JSON 格式。
|
||||
|
||||
```text
|
||||
https://dsh.r2049.cn/pair#v1.<ticket>
|
||||
```
|
||||
|
||||
`ticket` 是现有 `scanSecret`:32 随机字节的 canonical base64url,无 padding,43 个字符(256 位熵),不是可猜测数字短码。二维码不再包含 sessionId、Host 信息或公钥。服务端只存其 SHA-256 摘要,无新增数据库字段或迁移。
|
||||
|
||||
手机必须直接解析扫码文本,不先打开网页、不经过第三方短链服务、不跟随重定向。严格校验 scheme/origin、路径恰为 `/pair`、无 userinfo/query、fragment 匹配 `^v1\.[A-Za-z0-9_-]{43}$`,并验证解码长度与 canonical 编码。限制扫码文本长度(建议最多 2048 UTF-8 字节)。默认要求 HTTPS;HTTP 仅沿用明确允许的本地开发/自托管策略,不能因扫码任意绕过安全策略。先让用户确认服务 origin,再向该 origin 发送无账号凭据的请求;不可携带 Web Cookie、旧 Token、手机私钥或 DeepSeek 凭据。
|
||||
|
||||
```http
|
||||
POST /api/v1/device-pairing/resolve
|
||||
Content-Type: application/json
|
||||
|
||||
{"ticket":"<fragment中v1.之后的43字符>"}
|
||||
```
|
||||
|
||||
响应为现有创建响应,格式完全相同:`v, sessionId, expiresAt, serverPublicKey, scanSecret, host`。手机必须校验 `v === 1`、`scanSecret === ticket`、有效期、Host role/ID、canonical 公钥等原有字段,结合已确认的扫码 origin 建立本次配对上下文;响应不另提供可切换的 serverUrl。只允许 `created` 且未过期的会话解析。未知、错误、已领取、取消、失败、完成或过期的 ticket 均返回 `404 PAIRING_NOT_FOUND`;字段长度或额外字段错误返回 422。响应 `Cache-Control: no-store`。按来源 IP 限流,默认 30/min,超限 429;沿用 8192 字节请求上限。
|
||||
|
||||
解析是只读操作,**不消耗领取机会**,网络丢包可安全重发相同 ticket。真正的一次性消费仍在带手机密钥证明的原子 `claim` 中完成;并发手机只允许一个成功。解析不创建用户、不绑定设备、不返回验证码或设备凭据。解析后,先展示服务器和 Host 身份给用户,手机主动确认后再提交 claim。claim 及后续 proof、8 位验证码单次尝试、Host 最终人工确认、权限和凭证恢复协议均不变。claim 响应丢失应重发原 claim,不重新 resolve。
|
||||
|
||||
手机须固定首次 resolve 的 Host ID/公钥和服务端会话公钥,后续状态/完成响应必须一致。与旧完整 JSON 的离线携带公钥不同,短格式的首次信息来源是用户确认 origin 的 HTTPS 服务;不能声称它额外提供了独立的 Host 公钥验证。若服务端被攻破,短格式没有独立于该服务的身份保证。
|
||||
|
||||
fragment 不进入 HTTP 请求 URL;但 ticket 依旧是秘密,不得进入日志、分析、崩溃上报、剪贴板或外部浏览器历史。POST 请求体也必须在代理和客户端日志中脱敏。GET `/pair` 仅返回无脚本/外部资源的引导文案,不解析、不 claim;设置 no-store、no-referrer 和严格 CSP,通用相机打开页面不会绑定设备。
|
||||
|
||||
DSH Go 实现顺序:识别短格式并确认 origin → resolve → 校验并固定会话/Host 信息 → 展示 Host 并由手机用户确认 → 复用原 claim/验证码/轮询/安全存储/自动连接流程。同时保留下面的旧 JSON 扫码解析,用于旧服务和已显示二维码;未知格式明确拒绝,不猜测协议。Dart/Android 实现和真机扫码尚未完成。
|
||||
|
||||
旧格式(兼容保留):
|
||||
|
||||
```json
|
||||
{
|
||||
"type":"dsh.remote.pairing",
|
||||
"v":1,
|
||||
"serverUrl":"https://dsh.r2049.cn",
|
||||
"sessionId":"<UUID>",
|
||||
"expiresAt":1790000000000,
|
||||
"serverPublicKey":"<32-byte-base64url>",
|
||||
"scanSecret":"<32-byte-base64url>",
|
||||
"host":{
|
||||
"deviceId":"<UUID-or-ULID>",
|
||||
"name":"My computer",
|
||||
"role":"host",
|
||||
"platform":"desktop",
|
||||
"identityKey":"<32-byte-base64url>"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
可含协议定义的 nullable/optional 版本字段。限制扫描文本长度、字段长度和协议版本;拒绝非法公钥、设备角色、过期会话和无效 origin。
|
||||
|
||||
`serverUrl` 只能是规范 origin,不含路径、query、fragment、userinfo。默认 HTTPS;本地开发及自托管遵循现有策略。手机确认新 origin 前不发送任何既有凭证;跨服务器存储隔离不得被二维码绕过。旧 JSON 模式的服务器返回 Host 身份必须与二维码一致;短模式与首次 resolve 固定值一致,不静默接受更换后的公钥。
|
||||
|
||||
双方界面统一显示完整指纹 `lowercaseHex(SHA256(decodedIdentityKey))`,可按组展示,但底层比较完整公钥。
|
||||
|
||||
## 准备手机身份和证明
|
||||
|
||||
为该 Server 生成或复用手机自己的 X25519 身份;私钥只在本机安全存储。重试、前后台切换和恢复过程中不能更换 deviceId 或密钥。
|
||||
|
||||
对每个 mobile POST:
|
||||
|
||||
```text
|
||||
shared = X25519(phonePrivateKey, QR.serverPublicKey)
|
||||
proofKey = HKDF-SHA256(shared,
|
||||
salt=UTF8(QR.sessionId),
|
||||
info=UTF8("dsh-pairing-v1/mobile"), L=32)
|
||||
raw = 实际发送的 JSON 字符串(只序列化一次,无外层空白)
|
||||
message = UTF8("POST\n" + path + "\n" + lowercaseHex(SHA256(UTF8(raw))))
|
||||
X-DSH-Pairing-Proof = base64urlWithoutPadding(HMAC-SHA256(proofKey, message))
|
||||
```
|
||||
|
||||
所有请求使用 UTF-8。哈希的是实际 JSON 文本,不是排序后的对象;属性顺序、内部空白和 Unicode 转义变化都会改变 proof。网络库不能再次序列化。X25519 不是签名算法,不转换为 Ed25519。
|
||||
|
||||
固定向量:Server `clients/fixtures/pairing/v1/proof.json`;Remote `fixtures/pairing/v1/proof.json`,两份相同。覆盖 mobile/status 和 Host 证明,Dart 首先核对 mobile 向量。向量中的私钥是公开测试材料,不能用于真实设备。
|
||||
|
||||
## 手机确认和验证码
|
||||
|
||||
用户主动确认后发送:
|
||||
|
||||
```http
|
||||
POST /api/v1/device-pairing/sessions/{sessionId}/claim
|
||||
Content-Type: application/json
|
||||
X-DSH-Pairing-Proof: <mobile-proof>
|
||||
```
|
||||
|
||||
```json
|
||||
{"scanSecret":"<QR.scanSecret>","device":{"deviceId":"<phone-id>","name":"My phone","role":"client","platform":"android","identityKey":"<phone-public-key>"}}
|
||||
```
|
||||
|
||||
响应:
|
||||
|
||||
```json
|
||||
{"state":"claimed","verificationCode":"00123456","expiresAt":1790000000000}
|
||||
```
|
||||
|
||||
此时**还没有 Remote 登录或连接权限**。
|
||||
|
||||
保存本次 claim 的准确请求字节以便受保护地短期恢复;响应丢失可携同一身份和完全相同的请求恢复同一个验证码,不能修改描述字段或为同一会话生成新码。不要把 claim 请求或验证码放入普通配置。临时配对材料必须按 origin、会话和手机身份隔离并在终态清理。
|
||||
|
||||
`deepseekUserId` 为可选非敏感元数据。没有实际可用接口时省略;不要为取得它上传或解析 DeepSeek 密码、Cookie、Token。它未经验证,不用于账号合并、设备找回或授权。
|
||||
|
||||
## 等待电脑和领取结果
|
||||
|
||||
每 2~3 秒:
|
||||
|
||||
```http
|
||||
POST /api/v1/device-pairing/sessions/{sessionId}/mobile/status
|
||||
Content-Type: application/json
|
||||
X-DSH-Pairing-Proof: <mobile-proof-for-this-path>
|
||||
|
||||
{}
|
||||
```
|
||||
|
||||
| state | 手机行为 |
|
||||
| --- | --- |
|
||||
| claimed | 显示验证码,等待电脑人工提交 |
|
||||
| approved | 电脑验证码已正确提交,等待服务端完成;仍不连接、不发布登录成功 |
|
||||
| completed | 校验并保存本手机 credentials,固定 Host 公钥后自动连接 |
|
||||
| failed | 清除验证码,说明配对失败,需要重新扫码;不能继续使用旧码 |
|
||||
| cancelled | 清除临时状态,回到 Remote 入口 |
|
||||
| expired | 清除临时状态,要求电脑重新生成二维码 |
|
||||
|
||||
completed 响应的 credentials:
|
||||
|
||||
```json
|
||||
{
|
||||
"account":"dsh-device:<UUID>",
|
||||
"accountKind":"device_only",
|
||||
"device":{"deviceId":"<phone-id>","name":"My phone","role":"client","platform":"android","identityKey":"<phone-public-key>"},
|
||||
"inboundOnly":false,
|
||||
"pairingRestricted":true,
|
||||
"tokens":{"accessToken":"...","accessTokenExpiresAt":1790000000000,"refreshToken":"...","refreshTokenExpiresAt":1790000000000}
|
||||
}
|
||||
```
|
||||
|
||||
必须校验:sessionId、二维码 Host 公钥和 ID、本手机 ID/公钥/role、有效的 Token 字段。不要把 Host 凭证作为手机凭证使用。先完成安全存储,再发布登录成功;存储失败可在恢复窗口重取同一组凭证。不能用旧轮询结果覆盖已经刷新的凭证。
|
||||
|
||||
本会话结果在 `expiresAt + 300 秒` 后不可领取(创建后共 480 秒)。验证码有效期仍为创建后 180 秒;恢复窗口不增加验证码尝试机会。
|
||||
|
||||
自动连接复用原有 RemoteAccount/Host 信任固定、Noise IK、WebRTC/P2P/TURN/Relay 逻辑,目标必须是本次二维码的 Host,不能随意选择列表中的第一台。手机后台时暂停不必要轮询,恢复前先验证当前 origin、账号及配对代次。
|
||||
|
||||
## 取消、续期和撤销
|
||||
|
||||
用户取消:`POST .../{sessionId}/mobile/cancel`,body `{}`、mobile proof。completed 后不能靠 cancel 撤销绑定。
|
||||
|
||||
完成后沿用设备 Token:
|
||||
|
||||
- `POST /api/v1/auth/refresh`:正常设备凭证轮换。
|
||||
- `GET /api/v1/devices`:仅发现已经授权的 Host。
|
||||
- `GET /api/v1/devices/{hostId}`:获取并核对公钥和 Membership。
|
||||
- `GET /api/v1/device-memberships`:查看本手机自己的授权关系。
|
||||
- `DELETE /api/v1/device-memberships/{hostId}`:只撤销本手机与该 Host 的关系。
|
||||
- `DELETE /api/v1/devices/self`:退出并撤销本手机身份及其授权。
|
||||
|
||||
不要调用账号级 Host 删除接口删除整台电脑。绑定不赋予手机 Web、Admin、云资源或其他设备的管理权限。
|
||||
|
||||
## 既有账号与异常
|
||||
|
||||
- Device-only 不允许 Remote Web 登录;不要提供“继续登录网页”来完成配对。
|
||||
- 新手机配对既有 Host 时,沿用 Host 内部所有者,只授权这一对。
|
||||
- 手机已注册在另一个内部账号,而目标 Host 已有不同所有者:Server 返回 failed / `PAIRING_ACCOUNT_CONFLICT`。不自动注销、覆盖已有凭证、合并账号或转移 Host;先向用户解释,让其明确选择后续操作。
|
||||
- `PAIRING_CLOSED`、`PAIRING_ATTEMPT_USED`:查询结果或重新扫码,不更换验证码继续尝试。
|
||||
- 429:退避,不能自动生成新会话绕过限制。
|
||||
- 503 / `AUTHORIZATION_SYNC_PENDING`:变更可能已保存,查询状态;不重新 claim 为另一身份。
|
||||
- 旧 Server 404:明确不支持;不退回跳过电脑验证码的流程。
|
||||
- 手机从不调用 `/host/confirm`;原提交恢复由电脑端负责。
|
||||
|
||||
新 Host 默认仅被控,不派生 Client 身份。DSH-Go 不能在配对后替 Host 打开主控权限。
|
||||
|
||||
## 验收清单
|
||||
|
||||
1. Dart 实际运行 mobile proof 固定向量通过。
|
||||
2. 手机人工确认前不提交 claim;电脑成功提交前无 Token、无远程访问。
|
||||
3. 手机显示的码保留前导零、只有一个有效期,不向 Host 查询接口或日志泄露。
|
||||
4. 电脑首次输错,手机进入失败终态;同二维码/验证码不能继续尝试。
|
||||
5. 手机断网、退出、切后台、重复扫码、服务器切换及迟到响应不能串用身份。
|
||||
6. 正确完成后安全存储、Host 公钥固定、自动连接;冷启动后按现有设备凭证恢复。
|
||||
7. 凭证存储失败可在窗口内恢复;已刷新的凭证不被旧结果覆盖。
|
||||
8. Host 公钥替换、错误会话、错误手机身份、撤销及账号冲突均 fail closed。
|
||||
9. 正常账号原有密码/OAuth 登录、恢复和连接保持兼容。
|
||||
10. Android 真机执行完整流程及原有 E2EE/P2P/Relay 回归。Node 模拟手机的通过不等同于 Dart 或真机验收。
|
||||
|
||||
## 已完成的跨仓库验证
|
||||
|
||||
Remote `scripts/check-device-pairing.ts` 使用隔离临时数据库、实际 C# API/Gateway、Remote HostPairing、HostServerConnection 和 Node 模拟手机,覆盖:配对前无凭证、正确配对、独立凭证、重启恢复、Host hello、Noise/Relay 加密 RPC、具体关系撤销。
|
||||
|
||||
它不会连接生产,不使用固定人工账号,不替真实用户批准配对。
|
||||
|
||||
运行前构建 Server 的两个 C# 项目;在 Remote 仓库使用 Node 24.9+:
|
||||
|
||||
```sh
|
||||
DSH_PAIRING_SERVER_ROOT=/absolute/path/to/deepseek-harness-server pnpm exec tsx scripts/check-device-pairing.ts
|
||||
```
|
||||
|
||||
完整 wire schema、错误码、限额和迁移说明以权威协议及 Server OpenAPI 为准。
|
||||
Loading…
Reference in New Issue