[feat] add trusted device pairing and management UI

2026-11-03 12:32:53 +08:00 · 2026-11-01 23:27:17 +08:00
parent e15e2c33bd
commit 489491008a
10 changed files with 823 additions and 7 deletions
@@ -4,6 +4,8 @@

 本文描述当前已实现的桌面客户端架构，代码依据为 CrossDesk `cc48eb65`、MiniRTC `040114d`，核对日期为 **2026-10-25**。ID 模式的服务端行为按客户端协议说明；服务端内部实现由独立的 CrossDesk Server 项目维护。

+可信设备认证及配对身份文件的说明于 **2026-11-01** 按当前工作区更新；服务器登录沿用原有 ID、密码及重连令牌流程。
+
 ## 1. 两种模式的边界

 两种模式复用桌面采集、编码、音视频传输、键鼠、文件和剪贴板处理。差别主要在**如何找到设备、在哪里验证密码，以及通过什么通道交换连接参数**。
@@ -217,6 +219,24 @@ IP 直连采用 **TLS 内提交密码，由被控端本地验证**：

 对应代码：[密码验证](../apps/desktop/src/network/lan/lan_password.cpp)、[本地身份和凭据存储](../apps/desktop/src/network/lan/lan_identity.cpp)、[认证限流](../apps/desktop/src/network/lan/lan_auth_limiter.cpp)、[DTLS/SRTP 就绪处理](../deps/submodules/minirtc/src/transport/ice_transport.cpp)。

+### 4.3 可选可信设备认证
+
+可信设备限制默认关闭，认证及授权全部由 CrossDesk 应用层完成。被控端为每次新会话生成 32 字节随机挑战，控制端签署协议域 `crossdesk.device-trust.v1`、挑战随机数、本机公钥、设备 ID 和名称。被控端验证签名后，还必须确认公钥在本地可信名单中，才开放控制权限；相同 ID 或名称不能替代公钥匹配。
+
+首次添加支持离线配对：在控制端复制本机配对信息，通过双方认可的渠道交给被控端；被控端粘贴后点击“添加”即校验并写入可信名单，也支持添加本机，无需预览和二次确认。已存在的公钥不会重复添加，完整指纹可在列表中查看。复制结果显示在“本机配对信息”栏目，添加结果显示在添加区域。配对信息只包含公钥和展示信息，不含私钥或密码，也不需要先建立远程连接或关闭可信设备限制。导入仅更新名单，后续连接仍须完成原有密码验证及实时签名认证；配对信息本身不能证明来源，用户通过传递渠道确认其来源。也可以继续从已连接且完成身份验证的控制端中选择添加。
+
+挑战有效期为 10 秒，只接受一次成功证明。重复的已连接通知沿用当前挑战及截止时间；断开或重新进入连接阶段时清除认证状态，下次连接重新生成挑战。开启限制时，未完成证明、签名无效或公钥不在名单中的设备不能获得控制权限；不支持该应用层协议的旧客户端同样不能通过。关闭限制时保持原连接行为。
+
+MiniRTC 仅通过现有可靠数据通道收发这些应用消息，不提供可信设备专用接口，也不参与名单、签名或授权判断。认证证明不包含 DTLS 连接绑定：随机挑战可防止历史证明重放，但不防护攻击者在两条连接之间实时转发挑战和签名的情形。原有传输加密及其兼容规则仍由第 4.1、4.2 节描述。
+
+可信设备配对私钥保存在缓存目录中的 `identity.json`，仅用于控制端与被控端之间的签名认证。服务器登录使用原有 ID、密码缓存及重连令牌，不使用这个私钥。macOS/Linux 文件权限为 `0600`，Windows 使用当前用户 ACL；身份存储通过 `identity.json.lock` 保护读写，并基于最新内容原子更新。锁文件不含凭据，无需备份。
+
+可信列表保存在配置目录的 `trusted-devices/devices.json`，新版格式只含可信设备的公钥、名称和 ID，可包含本机。旧格式中的本机私钥会自动迁入 `identity.json`，持久写入成功后才从列表文件移除，因此原有指纹和配对关系保持不变。迁移中断可重试；发现两处密钥冲突时停止加载，不自动覆盖。Windows 无人值守服务使用其独立资料目录中的同一布局。
+
+只删除普通 ID/密码缓存不会删除配对私钥，但配对私钥不能恢复服务器分配的 ID；后续身份分配沿用原有缓存流程。删除整个缓存目录会丢失配对私钥，重新生成后需要其他设备重新信任本机的新指纹。备份配对身份应保存 `identity.json`，保留允许控制本机的设备名单还应备份可信列表。身份文件损坏或权限不安全时停止加载；已开启的可信设备限制不会因此自动关闭。
+
+对应代码：[设备签名与名单存储](../apps/desktop/src/gui/runtime/trusted_devices.cpp)、[应用层认证及授权](../apps/desktop/src/gui/runtime/device_trust_runtime.cpp)、[连接状态与认证生命周期](../apps/desktop/src/gui/runtime/peer_event_handler.cpp)。
+
 ## 5. 运行时复用、线程与关闭

 ```mermaid