CC-Switch/docs/restore-hardening-debt-zh.md

Restore 加固工程:债务登记表(自 Pi 工程移交)

状态:立项挂起的独立未来工程。由用户裁决(2026-08-02)自 Pi 支持工程移交: Pi 的 PR 聚焦业务点,restore 存量产品面的对抗加固不属于其范围。 移交时点:前置 B 终止 checkpoint 3fa6b1f158b4e609b1588affb366bd90fb11878e。 表中 D1–D4 为 Pi 工程之前即存在的产品面债务(非 Pi 引入、非回归); D5 例外:该死代码由 Pi 工程自身的 4f784514(typed provider writes / canonical restore)引入,属本工程遗留物,未来工程处理时应优先直接删除。 Pi 耦合面(设备本地台账重建、弱化 schema 不可发布、token 不入可迁移产物) 已实现并在两套认证套件中持续全绿。

Pi 工程期间已完成并保留的加固(随 Pi PR 交付)

• Data-only canonical restore:UntrustedScratch/CanonicalStage 类型屏障, 导入 schema 永不成为发布权威;
• MigrationSourceSpec(v16/v17)源规格先行 + 全函数 typed 映射;
• 不可信恢复版本门:仅接受 user_version N/N−1(16/17),含升级前备份回滚专测;
• MigrationRunContext { LocalUpgrade, UntrustedRestore } 语义分离;
• 值域强制(sort_index、circuit_error_rate_threshold ∈ [0,1] 等)、 auto_vacuum 继承、设备本地台账 canonical 重建;
• 恶意 schema 语料、预算、文件边界等既有测试全绿(Rust 2372 passed)。

未决 finding(终止时点,均已双 reviewer/主审确认)

#	严重度	描述	现有缓解
D1	High	Database 未持有不可变 live 路径:配置目录变更"稍后重启"期间,旧连接与新目录缓存并存,safety backup 与 canonical publish 可作用于不同库(mod.rs:90、backup.rs:2295、app_store.rs:104、useSettings.ts:363)。根治需 DatabaseHome/BackupRepository 不可变注入架构	无(建议未来工程首项;临时缓解可为"待重启状态禁用备份/恢复操作")
D2	High	restore 行校验未复用写面校验链:可发布空 ID/app_type(ProviderKey::new 会拒)、空白或尾斜杠 URL 的 endpoint(尾斜杠规范化在 NewProviderAggregate::from_input 而非 NewEndpoint 内,恢复路径两者都绕过),恢复后无法被 remove/touch 命中(backup.rs:549)	写面自身拒绝此类值;仅恢复路径可引入
D3	High	safety backup 直写可预测最终文件名;dangling symlink 绕过 Path::exists(),Connection::open 跟随链接;nofollow 检查晚于内容写出(backup.rs:2307)	需本机文件系统攻击者前置
D4	Medium	全表 decoder sweep 不完整:proxy_live_backup.original_config 非法 JSON、usage_daily_rollups.date 非法日期可发布,生产读取时失败(backup.rs:633)	读取侧失败即暴露,无静默数据错
D5	Medium	取消标志固定 false,无 setter/外部 token,cancellation check 不可触发(backup.rs:1248)	纯死代码,建议未来删除或接真实 token

一并挂起的既定立项

• v1–v15 历史备份导入(缩围裁决 2026-08-02;MigrationSourceSpec 架构为其地基);
• 主审否决记录:两位 reviewer 建议"升级前备份失败应阻断启动",因违反 "LocalUpgrade 既有行为不变"裁决未采信——未来工程重议时须重新评估。

机制锁定

Pi PR 内 restore 面已被前置 A 认证套件的 infra SHA-256 基线重冻 (schema.rs/migration.rs/backup.rs @ 3fa6b1f1 状态):任何再触碰即认证红, 防止范围回潮。未来工程启动时由其裁决方解冻。