194 lines
13 KiB
Markdown
194 lines
13 KiB
Markdown
# CC Switch 加密配置与切换重构方案（V1）
|
||
|
||
## 1. 目标与范围
|
||
|
||
- 目标：将 `~/.cc-switch/config.json` 作为单一真实来源（SSOT），改为“加密落盘”；切换时从解密后的内存配置写入目标应用主配置（Claude/Codex）。
|
||
- 范围：
|
||
- 后端（Rust/Tauri）新增加密模块与读写改造。
|
||
- 调整切换逻辑为“内存 → 主配置”，切换前回填 live 配置到当前供应商，避免用户外部手改丢失。
|
||
- 新增“旧文件清理与归档”能力：默认仅归档不删除，并在迁移成功后提醒用户执行；可在设置页手动触发。
|
||
- 兼容旧明文配置（v1/v2），首次保存迁移为加密文件。
|
||
|
||
## 2. 背景现状（简述）
|
||
|
||
- 当前：
|
||
- 全局配置：`~/.cc-switch/config.json`（v2：`MultiAppConfig`，含多个 `ProviderManager`）。
|
||
- 切换：依赖“供应商副本文件”（Claude：`~/.claude/settings-<name>.json`；Codex：`~/.codex/auth-<name>.json`、`config-<name>.toml`）→ 恢复到主配置。
|
||
- 启动：若检测到现有主配置，自动导入为 `current` 供应商。
|
||
- 问题：存在“副本 ↔ 总配置”双来源，可能不一致；明文落盘有泄露风险。
|
||
|
||
## 3. 总体方案
|
||
|
||
- 以加密文件 `~/.cc-switch/config.enc.json` 替代明文存储；进程启动时解密一次加载到内存，后续以内存为准；保存时加密写盘。
|
||
- 切换时：直接从内存 `Provider.settings_config` 写入目标应用主配置；切换前回填当前 live 配置到 `current` 供应商，保留外部修改。
|
||
- 明文兼容：若无加密文件，读取旧 `config.json`（含 v1→v2 迁移），首次保存写加密文件，并备份旧明文。
|
||
- 旧文件清理：提供“可回滚归档”而非删除。扫描 `~/.cc-switch/config.json`（v1/v2）与 Claude/Codex 的历史副本文件，用户确认后移动到 `~/.cc-switch/archive/<ts>/`，生成 `manifest.json` 以便恢复；默认不做静默清理。
|
||
|
||
## 4. 密钥管理
|
||
|
||
- 存储：系统级凭据管家（keyring crate）。
|
||
- Service：`cc-switch`；Account：`config-key-v1`；内容：Base64 编码的 32 字节随机密钥（AES-256）。
|
||
- 首次运行：生成随机密钥，写入 Keychain。
|
||
- 进程内缓存：启动加载后缓存密钥，避免重复 IO。
|
||
- 轮换（后续）：支持命令触发“旧密钥解密 → 新密钥加密”的原子迁移。
|
||
- 回退策略：Keychain 不可用时进入“只读模式”并提示用户（不建议将密钥落盘）。
|
||
|
||
## 5. 加密封装格式
|
||
|
||
- 文件：`~/.cc-switch/config.enc.json`
|
||
- 结构（JSON 封装，便于演进）：
|
||
```json
|
||
{
|
||
"v": 1,
|
||
"alg": "AES-256-GCM",
|
||
"nonce": "<base64-nonce>",
|
||
"ct": "<base64-ciphertext>"
|
||
}
|
||
```
|
||
- 明文：`serde_json::to_vec(MultiAppConfig)`；加密：AES-GCM（12 字节随机 nonce）；每次保存生成新 nonce。
|
||
|
||
## 6. 模块与改造点
|
||
|
||
- 新增 `src-tauri/src/secure_store.rs`：
|
||
- `get_or_create_key() -> Result<[u8;32], String>`：从 Keychain 获取/生成密钥。
|
||
- `encrypt_bytes(key, plaintext) -> (nonce, ciphertext)`；`decrypt_bytes(key, nonce, ciphertext)`。
|
||
- `read_encrypted_config() -> Result<MultiAppConfig, String>`：读取 `config.enc.json`、解析封装、解密、反序列化。
|
||
- `write_encrypted_config(cfg: &MultiAppConfig) -> Result<(), String>`：序列化→加密→原子写入。
|
||
- 新增 `src-tauri/src/legacy_cleanup.rs`（旧文件清理/归档）：
|
||
- `scan_legacy_files() -> LegacyScanReport`：扫描旧 `config.json`（v1/v2）与 Claude/Codex 副本文件（`settings-*.json`、`auth-*.json`、`config-*.toml`），返回分组清单、大小、mtime；永不将 live 文件（`settings.json`、`auth.json`、`config.toml`、`config.enc.json`）列为可归档。
|
||
- `archive_legacy_files(selection) -> ArchiveResult`：将选中文件移动到 `~/.cc-switch/archive/<ts>/` 下对应子目录（`cc-switch/`、`claude/`、`codex/`），生成 `manifest.json`（记录原路径、归档路径、大小、mtime、sha256、类别）；同分区 `rename`，跨分区“copy + fsync + remove”。
|
||
- `restore_from_archive(manifest_path, items?) -> RestoreResult`：从归档恢复选中文件；若原路径已有同名文件则中止并提示冲突。
|
||
- 可选：`purge_archived(before_days)` 仅删除 `archive/` 内的过期归档；默认关闭。
|
||
- 安全护栏：操作前后做 mtime/hash 复核（CAS）；发生变化中止并提示“外部已修改”。
|
||
- 调整 `src-tauri/src/app_config.rs`：
|
||
- `MultiAppConfig::load()`：优先 `read_encrypted_config()`；若无则读旧明文：
|
||
- 若检测到 v1（`ProviderManager`）→ 迁移到 v2（原有逻辑保留）。
|
||
- `MultiAppConfig::save()`：统一调用 `write_encrypted_config()`；若检测到旧 `config.json`，首次保存时备份为 `config.v1.backup.<ts>.json`（或保留为只读，视实现选择）。
|
||
- 调整 `src-tauri/src/commands.rs::switch_provider`：
|
||
- Claude：
|
||
1. 回填：若 `~/.claude/settings.json` 存在且 `current` 非空 → 读取 JSON，写回 `manager.providers[current].settings_config`。
|
||
2. 切换：从目标 `provider.settings_config` 直接写 `~/.claude/settings.json`（确保父目录存在）。
|
||
- Codex：
|
||
1. 回填：读取 `~/.codex/auth.json`（JSON）与 `~/.codex/config.toml`（字符串；非空做 TOML 校验）→ 合成为 `{auth, config}` → 写回 `manager.providers[current].settings_config`。
|
||
2. 切换：从目标 `provider.settings_config` 中取 `auth`（必需）与 `config`（可空）写入对应主配置（非空 `config` 校验 TOML）。
|
||
- 更新 `manager.current = id`，`state.save()` → 触发加密保存。
|
||
- 保留/清理：
|
||
- 阶段一保留 `codex_config.rs` 与 `config.rs` 的副本读写函数（减少改动面），但切换不再依赖“副本恢复”。
|
||
- 阶段二可移除 add/update 时的“副本写入”，转为仅更新内存并保存加密配置。
|
||
|
||
## 7. 数据流与时序
|
||
|
||
- 启动：`AppState::new()` → `MultiAppConfig::load()`（优先加密）→ 进程内持有解密后的配置。
|
||
- 添加/编辑/删除：更新内存中的 `ProviderManager` → `state.save()`（加密写盘）。
|
||
- 切换：回填 live → 以目标供应商内存配置写入主配置 → 更新 `current` → `state.save()`。
|
||
- 迁移后提醒：若首次从旧明文迁移成功，弹出“发现旧配置，可归档”提示；用户可进入“存储与清理”页面查看并执行归档。
|
||
|
||
## 8. 迁移策略
|
||
|
||
- 读取顺序：`config.enc.json`（新）→ `config.json`（旧）。
|
||
- 旧版支持：
|
||
- v1 明文（单 `ProviderManager`）→ 自动迁移为 v2（已有逻辑）。
|
||
- v2 明文 → 直接加载。
|
||
- 首次保存：写 `config.enc.json`；若存在旧 `config.json`，备份为 `config.v1.backup.<ts>.json`（或保留为只读）。
|
||
- 失败处理：解密失败/破损 → 明确提示并拒绝覆盖；允许用户手动回滚备份。
|
||
- 旧文件处理：默认不自动删除。提供“扫描→归档”的可选流程，将旧 `config.json` 与历史副本文件移动到 `~/.cc-switch/archive/<ts>/`，保留 `manifest.json` 以支持恢复。
|
||
|
||
## 9. 回滚策略
|
||
|
||
- 加密回滚：保留 `config.v1.backup.<ts>.json` 作为明文快照；必要时让 `load()` 回退到该备份（手动步骤）。
|
||
- 切换回退：临时切换回“副本恢复”路径（现有代码仍在，快速恢复可用）。
|
||
|
||
## 10. 安全与性能
|
||
|
||
- 算法：AES-256-GCM（AEAD）；随机 12 字节 nonce；每次保存新 nonce。
|
||
- 性能：对几十 KB 级别文件，加解密开销远低于磁盘 IO 和 JSON 处理；冷启动 Keychain 取密钥 1–20ms，可缓存。
|
||
- 可靠性：原子写入（临时文件 + rename）；写入失败不破坏现有文件。
|
||
- 可选增强：`zeroize` 清理密钥与明文；Claude 配置 JSON Schema 校验。
|
||
- 清理安全：归档而非删除；不触及 live 文件；归档/恢复采用 CAS 校验与错误回滚；归档路径冲突加后缀去重（如 `-2`、`-3`）。
|
||
|
||
## 11. API 与 UX 影响
|
||
|
||
- 前端 API：现有行为不变；新增清理相关命令（Tauri）供 UI 调用：`scan_legacy_files`、`archive_legacy_files`、`restore_from_archive`（`purge_archived` 可选）。
|
||
- UI 提示：在“配置文件位置”旁提示“已加密存储”。
|
||
- 清理入口：设置页新增“存储与清理”面板，展示扫描结果、支持归档与从归档恢复；首次迁移成功后弹出提醒（可稍后再说）。
|
||
- 文案约定：明确“仅归档、不删除；删除需二次确认且默认关闭自动删除”。
|
||
|
||
## 12. 开发任务拆解（阶段一为本次交付）
|
||
|
||
- 阶段一（核心改造 + 清理能力最小闭环）
|
||
- 新增模块 `secure_store.rs`：Keychain 与加解密工具函数。
|
||
- 改造 `app_config.rs`：`load()/save()` 支持加密文件与旧明文迁移、原子写入、备份。
|
||
- 改造 `commands.rs::switch_provider`：
|
||
- 回填 live 配置 → 写入目标主配置（Claude/Codex）。
|
||
- 去除对“副本恢复”的依赖（保留函数以便回退）。
|
||
- 旧文件清理：新增 `legacy_cleanup.rs` 与对应 Tauri 命令，完成“扫描→归档→恢复”；首次迁移成功后在 UI 弹提醒，指向“设置 > 存储与清理”。
|
||
- 保持 `import_default_config`、`get_config_status` 行为不变。
|
||
- 阶段二（清理与增强）
|
||
- 移除 add/update 对“副本文件”的写入，完全以内存+加密文件为中心。
|
||
- Claude settings 的 JSON Schema 校验；导出明文快照；只读模式显式开关。
|
||
- 阶段三（安全升级）
|
||
- 密钥轮换；可选 passphrase（KDF: Argon2id + salt）。
|
||
|
||
## 14. 验收标准
|
||
|
||
- 功能：
|
||
- 无加密明文文件也能启动并正确读写；
|
||
- 切换成功将内存配置写入主配置；
|
||
- 外部手改在下一次切换前被回填保存；
|
||
- 旧配置自动迁移并生成加密文件；
|
||
- Keychain/解密异常时不损坏已有文件，给出可理解错误。
|
||
- 清理：扫描能准确识别旧明文与副本文件；执行归档后原路径不再存在文件、归档目录生成 `manifest.json`；从归档恢复可还原到原路径（不覆盖已存在文件）。
|
||
- 质量：
|
||
- 关键路径加错误处理与日志；
|
||
- 写入采用原子替换；
|
||
- 代码变更集中、最小侵入，与现有风格一致。
|
||
- 清理操作具备 CAS 校验、错误回滚、绝不触及 live 文件与 `config.enc.json`。
|
||
|
||
## 15. 风险与对策
|
||
|
||
- Keychain 不可用或权限受限：
|
||
- 对策：只读模式 + 明确提示；不覆盖落盘；允许手动恢复明文备份。
|
||
- 加密文件损坏：
|
||
- 对策：严格校验与错误分支；保留旧文件；不做“盲目重置”。
|
||
- 与“副本文件”并存导致混淆：
|
||
- 对策：阶段一保留但不依赖；阶段二移除写入，文档化行为变更。
|
||
- 清理误删或不可逆：
|
||
- 对策：默认仅归档不删除；删除需二次确认且仅作用于 `archive/`；提供 `manifest.json` 恢复；归档/恢复全程 CAS 校验与回滚。
|
||
|
||
## 16. 发布与回退
|
||
|
||
- 发布：随 Tauri 应用正常发布，无需前端变更。
|
||
- 回退：保留旧明文备份；将切换逻辑临时改回“副本恢复”路径可快速回退。
|
||
|
||
## 17. 旧文件清理与归档（新增）
|
||
|
||
- 归档对象：
|
||
- `~/.cc-switch/config.json`（v1/v2，迁移成功后）
|
||
- `~/.claude/settings-*.json`（保留 `settings.json`）
|
||
- `~/.codex/auth-*.json`、`~/.codex/config-*.toml`（保留 `auth.json`、`config.toml`）
|
||
- 归档位置与结构：`~/.cc-switch/archive/<timestamp>/{cc-switch,claude,codex}/...`
|
||
- `manifest.json`：记录原路径、归档路径、大小、mtime、sha256、类别（v1/v2/claude/codex）；用于恢复与可视化。
|
||
- 提醒策略：首次迁移成功后弹窗提醒；设置页“存储与清理”提供扫描、归档、恢复操作；默认不自动删除，可选“删除归档 >N 天”开关（默认关闭）。
|
||
- 护栏：永不移动/删除 live 文件与 `config.enc.json`；执行前后 CAS 校验；跨分区采用“copy+fsync+remove”；失败即时回滚并提示。
|
||
|
||
## 18. 变更点清单（代码）
|
||
|
||
- 新增：`src-tauri/src/secure_store.rs`
|
||
- 修改：
|
||
- `src-tauri/src/app_config.rs`（load/save 加密化、迁移与原子写入）
|
||
- `src-tauri/src/commands.rs`（switch_provider 改为内存 → 主配置，并回填 live）
|
||
- `src-tauri/src/legacy_cleanup.rs`（扫描/归档/恢复旧文件）
|
||
- 保持：
|
||
- `src-tauri/src/config.rs`、`src-tauri/src/codex_config.rs`（读写工具与校验，阶段一不大动）
|
||
- 前端 `src/lib/tauri-api.ts` 与 UI 逻辑
|
||
|
||
## 19. 开放问题（待确认）
|
||
|
||
- Keychain 失败时是否提供“本地明文密钥文件（600 权限）”的应急模式（当前建议：不提供，保持只读）。
|
||
- 加密文件名固定为 `config.enc.json` 是否满足预期，或需隐藏（如 `.config.enc`）。
|
||
- 是否需要提供“自动删除归档 >N 天”的开关（默认关闭，建议 N=30）。
|
||
|
||
---
|
||
|
||
以上方案为“阶段一”可落地版本，能在保持前端无感的前提下完成“加密存储 + 内存驱动切换”的核心目标。如需，我可以继续补充任务看板（Issue 列表）与实施顺序的 PR 规划。
|