Skip to content

同步与恢复工作线 ​

接手状态(2026-11-16,新加坡时间) ​

已有提交实现 Folder/Git transport、三设备合并模拟、设备加入/撤销和 CLI;工作区干净。8557b11 已合并设计中的 5.1/5.2;本轮遵从用户不再合并 main 的指令。首次基线发现 CLI 同步测试未适配 daemon 默认路径,已用 --no-daemon 隔离测试;device add 缺少明文输出边界,补上 stdin/stdout TTY 检查及回归测试。

设备二维码携带长期 Secret Key,不能宣称服务端保证“一次性”:任何持有二维码及主密码的人都具有账户恢复能力。CLI 只允许人在交互终端生成二维码;agent 的 JSON 调用返回 8。撤销设备阻止旧设备身份继续写入,不能消除其已读数据或已持有的账户恢复材料。

实现参考 ​

  • rust-s3(MIT):研究同步客户端、条件 PUT、分页列表 API,用 crate 处理 SigV4,不自写签名。
  • reqwest(MIT/Apache-2.0):研究 blocking client、重定向策略与超时,用于 WebDAV。
  • security-framework(MIT/Apache-2.0):研究可同步 generic-password 选项,与现有 SecretKeyStore 保持一致。

Contract changes ​

  • pn device add 非交互输出现在返回 PolicyDenied / 8,交互 JSON 仍可用。
  • 存储、恢复及发现接口已在本工作线补齐,详见下文。

需要用户本人 ​

真实 iCloud 钥匙串授权、同 Apple ID 跨设备同步,以及云存储真实账号验收。开发测试只用临时目录和合成数据,不接触已安装 App 或真实保险库。

已实现的核心 ​

  • SyncTransport:Folder(原子写、校验和、iCloud placeholder 请求下载)、Git(逐次提交、fetch/merge、绝不强推)、S3/R2/MinIO(rust-s3 SigV4、分页列表、If-None-Match: *)、WebDAV(Depth:1 遍历、MKCOL、条件 PUT)。HTTP 仅允许 loopback 测试,真实端点须 HTTPS;WebDAV 禁止重定向,错误不包含响应体或凭据。
  • 同步引擎先暂存再验签,检查成员、纪元、操作哈希链、分叉、回滚、撤销、传输摘要和路径。既有三设备测试覆盖同项/跨字段并发、删除/编辑、离线追赶、伪造签名、回放、截断和合并顺序性质。
  • 公开 vault.json 是不可变签名发现头,不含条目、Secret Key、存储凭据;含 vault/member ID、名称、头创建时间、KDF 参数、成员公钥及账户包摘要。旧保险库在首次解锁同步/配置位置时补写,不改已有操作文件。
  • RecoveryBundleStore:macOS MacRecoveryBundleStore 使用固定 service/account 的 synchronizable generic-password,首次启动时还没有本地 vault ID 也能找到。不会像 SecretKeyStore 那样退到明文文件;不可用时明确报错。支持多保险库记录,每库包含 Secret Key、成员身份及多个存放位置/凭据。
  • FileRecoveryBundleStore 用现有 XChaCha20-Poly1305 原语,密钥由宿主注入。CLI 测试替身只在临时 PASSNO_HOME + 显式 PASSNO_RECOVERY_TEST_DIR 下启用;这个测试目录里有独立 0600 包裹密钥,不能当真实恢复方案。
  • 普通 local/sync.json 仅存 recovery 引用(vault/id/kind)、主位置/备份列表及调度设置。保留旧 Folder/Git 配置读取兼容;新默认配置全部进入恢复包。Git URL 不允许密码/token userinfo,Git 认证走 SSH agent/credential helper;本地 mirror 不保存 origin URL,执行时才注入 URL。
  • VaultDiscovery:恢复包、iCloud Drive/Dropbox/Sync/Syncthing 根目录及一层子目录、gh 私有仓库 topic passno-vault。GitHub 发现显式 --github,避免首次启动无谓访问账号。来源失败在 warnings 中报告;发现不是解锁授权。恢复包可能过期,不显示“保证可恢复”。
  • 恢复:先下载到目标 home 内临时目录,验签/比对恢复包固定公钥、验证主密码并解包账户材料、生成新设备密钥;全部成功才移入正式路径。错误密码、损坏文件不覆盖现有保险库、不写目标 SecretKeyStore。恢复不自动写远端,成功后 pn sync now 发布新设备。
  • 应急套件包含 Secret Key、存放位置及完整 URI(含访问凭据),只能在人类 TTY 导出。导入只返回成功状态;支持没有 iCloud 的宿主注入加密 RecoveryBundleStore。
  • SyncScheduler 不依赖 daemon,提供 Manual/PeriodicTick/AfterMutation/DaemonStartup。备份从已验证本地状态只上传,不把备份当第二个可写主库;备份失败返回错误,不掩盖为成功。

构建与验证 ​

sh
cargo test -p passno-sync
cargo test -p passno-cli --test sync_cli_integration
cargo fmt --all
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace

tests/recovery.rs 的本地 HTTP 服务器使用合成凭据,实际走 rust-s3/reqwest 协议、S3 三条一页的分页、条件 PUT/412、不覆盖冲突对象、两种协议完整恢复;不需要 MinIO/Nextcloud 账号。文件夹及 Git 恢复同样包含密文附件块。临时 HTTP 服务测试曾误按 GET 的 Content-Length 等待请求体,已修正为只读取 PUT/PROPFIND body。

CLI 测试/手动演示必须先设置临时目录,不能使用真实保险库:

sh
export PASSNO_HOME="$(mktemp -d /tmp/passno-sync-demo.XXXXXX)"
export PASSNO_RECOVERY_TEST_DIR="$(mktemp -d /tmp/passno-recovery-demo.XXXXXX)"
cargo run -p passno-cli --bin pn -- --no-daemon init
cargo run -p passno-cli --bin pn -- sync setup --folder /tmp/passno-synthetic-remote
cargo run -p passno-cli --bin pn -- sync now
cargo run -p passno-cli --bin pn -- vault discover --folder /tmp/passno-synthetic-remote --json
# 新设备保留同一个测试 recovery 目录,另设 PASSNO_HOME,然后:
cargo run -p passno-cli --bin pn -- vault restore <vault-id>

真实环境支持 sync setup --icloud、--git <URL>、--s3 <HTTPS endpoint> --bucket <bucket> --region auto --prefix <vault-prefix>、--webdav <HTTPS root>,--backup 追加备份。S3 凭据输入环境变量 PASSNO_SYNC_ACCESS_KEY/PASSNO_SYNC_SECRET_KEY;WebDAV 使用 PASSNO_SYNC_USERNAME/PASSNO_SYNC_PASSWORD,不打印、不写 sync.json。--no-recovery 只适用于 Folder,明确退出自动恢复包;此时请保留原始应急套件/Secret Key。

Contract changes(增补) ​

  • passno-vault::DiscoveryHeader 和 Vault::ensure_discovery_header 是增量格式/API;签名域 passno-discovery-header-v1。设计 5 节已解释信任边界。
  • SyncLocation 增加 S3/WebDav/Stored;SyncConfig.backups 默认为空,旧配置可读。
  • 首次启动服务方法在 docs/dev/api.md 末尾列出;由协调者将其接入 GUI/IPC,不把恢复秘密放进 agent DTO。
  • 当前名称/时间是签名头首次创建时的值,不是最后同步时间。改名需要未来的签名元数据版本迁移,不能覆盖 immutable header。

平台边界与后续集成 ​

此工作线只改 Rust 核心与 CLI,没有前端/iOS 壳文件改动。首次启动 UI、daemon 自动调用 hooks、iOS iCloud 容器/钥匙串 entitlement 由协调者接线;这里提供可注入 trait 和已验证服务函数。Windows/Linux 真正的安全凭据后端需宿主实现 RecoveryBundleStore;不提供不安全的默认明文替代。

真实 iCloud 跨 Apple ID 设备同步、R2/自建服务器权限与条件写支持、GitHub 私有仓库 topic/auth 的现场验收尚需用户账号和已签名 App。远端服务若不履行条件写语义,无法由客户端保证原子性;本地协议测试验证客户端确实发送条件并处理 412。

CLI 帮助与回归边界 ​

pn help 'sync setup' --json、pn help 'vault restore' --json 等支持嵌套命令路径,包含对应参数与输出结构;CLI 文档生成器现在同时保留嵌套命令的例子和退出码。pn device rm 找不到设备统一返回 5。agent-help 明确禁止 agent 请求二维码/应急套件。工作树没有 MCP 实现,本工作线不新增返回恢复材料的 MCP 工具。

新增回归覆盖恢复时锁文件 inode 不变、双线程同路径只创建不覆盖、拒绝符号链接、备份上传不污染主位置回滚状态、新设备恢复后备份配置仍在、非 TTY 不泄露恢复材料。四种传输的恢复都在本机临时目录/loopback 服务器验证。

最终验证(2026-11-16,新加坡时间) ​

  • cargo fmt --all 完成;git diff --check 通过。
  • cargo clippy --workspace --all-targets -- -D warnings 通过。
  • cargo test --workspace 全部通过:104 项测试,包含 7 项恢复/协议测试、8 项同步模拟/性质测试、4 项同步 CLI 集成测试,以及既有 daemon/桌面 Rust 服务测试。
  • 本轮没有前端或 iOS 壳改动,因此未运行 npm 或 iOS UI 检查;实际 GUI 接线与真实 iCloud 权限仍按上文边界交由协调者/用户验收。
  • 所有测试均使用合成数据、临时目录、本地 bare git/loopback HTTP 服务;未推送源码分支、未合并 main、未修改其他工作树或已安装应用。

daemon 接线(integrate2) ​

passnod 现持有可注入的 SyncScheduler 与 RecoveryBundleStore:启动、解锁、写入后 500ms 防抖、定期轮询、macOS 唤醒均进入同一串行通道。定期失败至少间隔 5 秒再试; 后台同步不刷新用户活动时间。远端更新与备份失败后的有效主库更新都会重载会话并发出 vault_changed。安全重载失败则锁定,避免继续使用旧状态。

网络/磁盘同步在 Tokio blocking worker 中运行,避免在 async runtime 内构造 blocking HTTP client。单次同步期间请求排队;大库或慢网络仍可能使交互变慢,未来可拆成 staging worker 与短时提交锁(不得削弱当前串行写入与验签保证)。

默认 pn sync now|status 经 daemon,无需再次输入主密码;--no-daemon 保留维护路径。 位置和设备管理使用同一 IPC,位置凭据只进恢复存储,普通返回值没有 Secret Key 或凭据。 local/sync-state.json 新增可选 backups 状态映射,逐备份记录最后成功时间与失败标志, 不污染主位置的回滚哈希。一个备份失败仍尝试其余备份,整体报告失败。

恢复、设置页面与端到端运行方法见 integrate2。

iPhone:iCloud 同步和从 iCloud 恢复(2026-11-16) ​

iOS 没有后台进程,App 直接经 FFI 调同步库(crates/passno-ffi/src/sync.rs):启动时 set_icloud_root(容器/Documents/passno),sync_configure_icloud()(把 iCloud 容器里以库 id 命名的文件夹设为主存放位置,记为与设备无关的 SyncLocation::ICloud,并写恢复包)、sync_configure_folder(folder)、sync_now()、sync_status()、discover_vaults(icloud_root)(恢复包 + ICloudDiscovery 扫描容器)、restore_vault(vault_id, 主密码)。恢复包和 Mac 用同一个 iCloud 钥匙串条目(apple_recovery_store,iOS 现在也编译这段),所以在 Mac 上设好的保险库,iPhone 只输主密码就能恢复。

模拟器通常没登录 iCloud:调试版允许用 PASSNO_RECOVERY_SIMULATOR_DIR 指向一个文件版恢复包;正式版不读这个变量。测试 crates/passno-ffi/tests/icloud_sync.rs:A 设备设置 iCloud 并首次同步(状态显示“iCloud Drive · passno/…”,不显示内部引用),B 设备从恢复包发现、错误密码被拒、只用主密码恢复,两边改动双向同步。Swift 界面(PassnoKit/VaultSync.swift、PassnoApp/RestoreView.swift):

  • 首次打开先查恢复包和 iCloud 容器,查的时候只显示底色(最多 1.5 秒),不会先闪出“创建保险库”再跳成“恢复”。找到就显示“恢复保险库”,只要主密码;“改为创建新的保险库”是次要链接。输错密码时提示出现在输入框下方,位置预留好,按钮不跳。
  • 设置 → 密钥与同步:没开时只有“开启 iCloud 同步”;开了显示存放位置(只写“iCloud Drive”,不露内部编号)、上次同步(“10 秒钟前”)、“立即同步”。开了之后,原来那个“通过 iCloud 钥匙串同步 Secret Key”开关换成一句如实的说明,因为恢复包本来就把 Secret Key 放在 iCloud 钥匙串里。
  • 回到前台、解锁后、保存修改后,都会在后台同步(防抖 1.2 秒)。

模拟器验收(sim:iPhone 17 Pro,phone 逐步操作,调试版用启动参数 --passno-env KEY=VALUE 指定测试目录和模拟的 iCloud 目录):手机 A 建库并开启 iCloud 同步 → 手机 B(空目录)启动直接显示“恢复保险库:个人” → 输错密码有提示 → 输对后进入条目页 → B 新建条目自动同步 → A 解锁后看到 B 的条目。这次 iOS 库按正式版编译,恢复包走的是真实的钥匙串代码。截图:设置。

验收中修的问题:存放位置显示了内部编号;上次同步显示成“4秒”;冷启动解锁后不同步;Secret Key 开关与实际情况不符。

活动记录随同步走(2026-11-16) ​

  • 新增两种同步对象:vaults/<id>/activity/<设备>/<序号>(活动记录段)和 vaults/<id>/activity-checkpoints/<设备>/<序号>(压缩检查点),同样只写一次、内容不可变。拉取时每个活动文件都必须由它所在目录的设备签名(passno-sync/src/activity.rs 的 check_staged),否则整次拉取拒绝。
  • 保留期限:被有效签名检查点覆盖的段和旧检查点可以从存储里消失,不算回滚,也不再下载,本地副本随之删除;只有写入它的设备在推送后删除存储里的文件(SyncTransport::delete_compacted,目录、Git、S3、WebDAV、内存实现都只接受活动记录,其他种类直接报错)。没被覆盖的文件消失仍报 RollbackDetected。
  • SyncEngine::sync_unlocked 推送前按批发布本机未发布的活动记录。详见 docs/dev/activity.md。

文档对应提交 56d1c45 · 由仓库 docs/ 自动生成