45 lines
5.8 KiB
Markdown
45 lines
5.8 KiB
Markdown
# 加密云同步客户端
|
||
|
||
实现版本：`2.0.0-Beta.3+build.20260925`。协议版本为 `1`，密码学 profile 为 `argon2id-xchacha20poly1305-v1`。本页描述客户端实现和验证边界；正式发布状态以对应 GitHub Release 为准。
|
||
|
||
## 地址与协议边界
|
||
|
||
新客户端使用独立入口 `https://apic.openless.top:9443/v1/...`。启动同步前读取 `/v1/capabilities`，核对协议、体积上限及现有 OpenLess GitHub OAuth client ID，再使用原生层的 GitHub 登录令牌交换短期同步会话。数字 GitHub ID 是账号隔离依据。新请求不回退到旧 `/me/sync`；旧四个 `cloud_sync_*` 命令不改接新协议。旧 standalone 仓库仍保留有限明文快照语义；已注册加密同步写入门的仓库暂不支持旧 `cloud_sync_restore`，明确返回 Unsupported，避免绕过加密恢复事务。
|
||
|
||
2026-09-26 的不带凭据检查中，正式 origin 的 `/v1/capabilities` 返回了协议 `1`、匹配的 OAuth client ID 与加密 profile，备份保留上限为 7 天。这仅证明能力接口当时可用，不代表真实账号授权、私有数据往返或生产验收已经完成。
|
||
|
||
## 原生边界
|
||
|
||
- `crates/openless-core/src/cloud_sync_e2ee_protocol/`：严格 wire DTO、规范编码、Argon2id、XChaCha20-Poly1305、带身份与版本的 AAD、HTTPS/CAS/幂等收据。
|
||
- `crates/openless-core/src/cloud_sync_e2ee_documents/`：逐字段登记、11 类逻辑文档、渠道和凭据一起合并、删除标记、脱敏冲突与加密恢复日志。
|
||
- `crates/openless-core/src/cloud_sync_e2ee_store/`：受控仓库、持久化代次、写隔离、完整恢复与读回验证。
|
||
- `crates/openless-core/src/cloud_sync_e2ee/`：默认关闭的状态机、密码解锁、创建、同步、改密、删除、原生凭据库中的记住密钥与加密本地基线。
|
||
- `src-tauri/src/commands/cloud_sync_e2ee.rs`：仅主窗口的本地 IPC；`src/lib/ipc/cloud-sync-e2ee.ts` 为对应 typed wrapper。浏览器预览返回 unavailable。
|
||
- `src/lib/encryptedSyncUiBridge.ts`：主窗口中实际语言/字号偏好的受控镜像，以及恢复成功后的界面更新。
|
||
|
||
上传只发送密文。密码和派生密钥不进入服务器请求；系统凭据库只导出登记过的服务账号，不复制 keyring/Keystore 文件。普通服务 API Key、接口设置、文本历史和风格内容纳入加密范围；OAuth 登录态、同步令牌、同步密码/派生密钥、设备私钥、远程输入 PIN、系统权限、录音、模型权重、缓存和程序不进入快照。
|
||
|
||
旧版 Omni 初始化可能将默认 `custom` 槽错误保存为空标识。原生读取时仅在目标不存在或规范后全部字段相同的情况下，将这条旧槽完整映射回 `custom`，保留其他已选供应商；不同配置发生碰撞时继续拒绝同步并保留两份数据。读取只规范内存副本，持久化仍走既有写入门，不通过删除凭据或放宽同步文档校验绕过错误。
|
||
|
||
## 行为
|
||
|
||
首次开启需明确确认完整范围；已有云端快照必须验证 AEAD 并展示恢复预览，不能用新设备默认值直接覆盖。密码按 NFC 规范化，创建/改密执行本地强度策略。记住密钥由系统安全存储实现，并绑定服务 origin、数字账号、vault、key 和设备。
|
||
|
||
共同基线、未确认操作及恢复资料在本机加密。网络丢失响应时保留原始请求体和操作 ID，先核对收据，必要时仅重送同一请求。不能将 404 收据当作“未提交”。上传中发生的新本地代次仍待同步。删除状态会停用自动上传，不能由旧设备自动重建。
|
||
|
||
自动同步仅在已开启、已登录且已解锁时运行：一次启动触发，持久化变更后 750 ms 防抖、最长 5 秒；没有周期轮询或无限重试。关闭与删除是独立操作。跨设备路径和平台设置以设备档案保留，恢复不授予系统权限或自动执行 Agent。
|
||
|
||
完成有效服务配置后，本机首次引导只申请一次持久化提示。凭据读取失败、配置正在保存、录音/输入/恢复繁忙时不申请；提示不访问同步网络、不启用上传。欢迎流程可直接打开“从云端恢复”，无需先填写服务密钥。窗口隐藏、失焦或任务开始后会丢弃迟到的提示结果。
|
||
|
||
短暂的本机写入竞争最多触发 4 次有界延后重试；网络失败、结果未知、版本冲突不进入该重试。后续手动任务、锁定或停用会淘汰旧重试链。同步连接遵循当前系统代理偏好，策略变化后重建连接，回环测试始终直连。
|
||
|
||
系统自启动 `launchAtLogin` 不进入远端文档或设备档案；保留接收设备本机值，实际 OS 状态仍由现有 UI 自启动插件管理，恢复不宣称替用户重建自启动授权。
|
||
|
||
恢复必须绑定 `RestoreRuntimeEffects` 的真实 Host 适配器。所有仓库写入后，在同一加密 journal、独占写入门和运行态屏障内等待绝对目标设置生效；副作用失败按 before 镜像回滚。只保存在本地 journal 的 Agent 开关、provider 镜像和录音标记恢复后，再应用最终旧设置；若回滚副作用也失败，保留 recovery_required，不能提前放行录音或 Agent。未绑定适配器明确失败，不使用空实现代替平台确认。
|
||
|
||
## 验证边界
|
||
|
||
协议测试使用公开互操作向量；服务测试使用 loopback 模拟 OAuth/同步端和内存凭据库，不触碰真实账号或用户钥匙串。恢复层须单独覆盖文件/凭据故障、进程中断、账号/版本隔离及排除项。通过协议测试不能替代真实平台钥匙串、两设备恢复与正式 OAuth 的人工验收。
|
||
|
||
发布遵循 [RELEASING.md](../RELEASING.md) 的对应提交 CI、签名和资产检查流程。真实 GitHub 授权及两台设备的生产数据往返仍须单独验收，不能由本地模拟服务器的通过结果代替。
|