bug: 自定义供应商旧密钥密文不可解密时配置更新死锁,新 API key 也无法保存

[fico-hub]

问题描述 / What happened

自定义供应商已存的 API key 密文一旦用当前 safeStorage 密钥解不开（例如 Keychain 密钥变更、或密文由另一个构建写入），该供应商的配置更新会永久死锁：即使用户在表单里粘贴了全新的 API key 点保存，也始终报 failed to read existing <agent> provider credential，没有任何自救路径（UI 上无法清除坏密文，只能手动去 safe-storage/ 目录删 .enc 文件）。

根因链路：

• maker:provider:custom:update 在写入新 key 前，会先经 stageProviderKeys 对每个待变更 runtime 做严格快照读取（providerHandlers.ts#L677-L680）。
• 快照读取走 readCustomProviderKeyForMutation，按注释设计「仅 ENOENT 表示没有旧 key，解密失败必须抛错」，目的是防止把暂时不可读的凭证误判为空而永久删除。
• 但当密文是永久性不可解（safeStorage 密钥已变，重试多少次都一样）时，这层保护反而把用户锁死：明明提供了替换值，旧值反正会被覆盖，却因为「拿不到回滚快照」拒绝整个保存。readCustomProviderHeadersForMutation 的请求头路径同理（providerHandlers.ts#L773）。

期望行为（建议方向，供维护者裁量）：

1. 当本次 mutation 携带显式替换值时，快照解密失败可降级为「快照 = 不可恢复」，回滚语义退化为删除该 runtime 的密文，不阻塞覆盖写入；仅在 mutation 是「保留旧值」或「仅删除」语义时维持现有严格失败。
2. 或者至少：错误信息告知用户旧凭证已损坏及恢复方式（重新填 key / 提供「清除已存凭证」入口），而不是笼统的 INTERNAL。

环境 / Environment

• Cindy 版本或 commit / version or commit: 0.1.71（release 安装版）；main 11e02c03 上代码路径一致
• 平台与版本 / platform & OS version: macOS (Darwin 25.4.0, Apple Silicon)
• 安装方式 / install method: 官方 dmg 安装到 /Applications

复现步骤 / Steps to reproduce

1. 自定义供应商配置好 API key（密文落盘为 userData/safe-storage/owner_<id>_provider_key_<provider>_<agent>.enc）。
2. 使该密文对当前 safeStorage 密钥不可解。实机是历史写入的密文解不开（疑似曾由不同签名/构建写入）；模拟复现可直接用任意 base64 垃圾字节覆盖该 .enc 文件内容。
3. 打开「编辑自定义供应商」，粘贴一个全新的 API key，点保存。
4. 观察：顶部 toast 报 failed to read existing claude-code provider credential，保存失败；反复重填 key 均无效，UI 无任何恢复路径。
5. 手动把对应 .enc 文件移走后再保存 → 立即成功（证明死锁仅由坏密文快照引起）。

日志与截图 / Logs & screenshots

[2026-09-02T22:36:34.282+08:00] [WARN ] [providerSecretStore] {
   providerId: 'kimi-code',
   agent: 'claude-code',
   err: 'Error while decrypting the ciphertext provided to safeStorage.decryptString.'
 } decrypt custom provider key snapshot failed
[2026-09-02T22:36:34.282+08:00] [ERROR] [console] Error occurred in handler for 'maker:provider:custom:update': Error: [INTERNAL] failed to read existing claude-code provider credential
     at createIpcError (.../bootstrap-electron-ClZHv728.js:221:19129)
     at throwIpcError (.../bootstrap-electron-ClZHv728.js:221:19279)

（已按模板要求删除凭证与个人数据；kimi-code 为本机自定义供应商 id。）

[dash-s-cindy]

判断：自定义供应商已经具备主进程加密存储、按 provider 串行 mutation、配置与凭证联动提交以及失败回滚能力；当前需要处理的是异常凭证状态下的可恢复性和错误可发现性。旧密文永久无法解密时，用户明确填写新 API key 仍无法保存，造成实际的配置锁死，值得修复。

行动建议：

1. 将凭证快照状态从二值的 string | null 扩展为至少三态：可恢复的旧值、确实不存在、存在但不可恢复。对 headers 也采用同样语义。
2. 在 apps/desktop/src/main/maker-ipc/providerHandlers.ts 的 stageProviderKeys（约 L668）和 stageProviderHeaders（约 L762）中，仅当本次 mutation 携带显式替换值时，允许“不可恢复”快照继续覆盖写入。快照必须先记录为不可恢复状态，不能当成 null，否则后续回滚会误认为原凭证不存在。
3. 对不可恢复快照定义明确的补偿语义：新密文写入成功、后续配置或另一类凭证提交失败时，删除新写入的 runtime 密文；不要尝试恢复不可读的旧 blob，也不要把新值遗留在配置提交失败的状态中。删除失败应继续返回结构化 INTERNAL 并记录主进程日志。
4. 对以下情况保留现有严格失败：未提供显式替换值而只是保留旧值、仅删除凭证、仅修改名称/模型、因端点变化而清理旧的 endpoint-bound 凭证，以及 safeStorage/文件系统异常尚未明确属于可覆盖场景的情况。Issue 提出的“显式替换时放宽、其他语义严格”是合理的实现方向；是否把某些端点变更也视为显式替换，仍应以 mutation 入参语义为准，不应仅凭配置差异推断用户想覆盖。
5. 将当前笼统的 failed to read existing <agent> provider credential 改为可识别的错误分类或至少改进文案，说明旧凭证无法读取、重新填写新 key 可恢复，以及仅删除/保留旧值时需要先处理凭证存储问题。不要把密文、明文或文件绝对路径透传给 renderer。

已确认的代码事实：

• apps/desktop/src/main/secrets/providerSecretStore.ts:442 的 readCustomProviderKeyForMutation：只有物理文件 ENOENT 返回 null；safeStorage 不可用、读取异常和 decryptString 失败都会抛出。
• apps/desktop/src/main/secrets/providerSecretStore.ts:477 的 readCustomProviderHeadersForMutation 对加密请求头采用同样的严格快照语义。
• providerHandlers.ts:668-696 的 stageProviderKeys 在快照读取失败时尚未将该 runtime 放进 snapshots，因此当前不会写新值，也没有 UI 可触发的清除路径。
• providerHandlers.ts:762-790 的 stageProviderHeaders 存在同样结构；显式 headers 替换时也可能被坏密文阻塞。
• planProviderKeyMutations 只有在 API key 被显式填写、凭证被移除、runtime 被移除或 endpoint 发生变化时才生成 mutation；未填写 key 且端点未变时会保留旧 key。planProviderHeaderMutations 则明确把“未回传 headers”解释为保留 main-only 旧 headers。因此不能简单把所有解密失败都降级为空。
• providerHandlers.test.ts 已覆盖端点变更时清理凭证、更新失败后的 headers 回滚，以及旧快照读取失败应拒绝（约 L1859 的用例）；这些测试应保留并改造成同时覆盖严格路径与显式替换路径。

建议测试最小集合：

• 旧 API key 解密失败 + 显式新 key：成功写入新 key，配置更新成功。
• 旧 API key 解密失败 + 未提供新 key：仍拒绝，且不删除坏密文。
• 旧 API key 解密失败 + 后续数据库更新失败：删除新 key，配置保持旧值；若删除补偿失败，返回结构化错误。
• 多 runtime 部分写入时，其中一个 runtime 快照不可恢复：显式替换的 runtime 可覆盖；此前已写入的 runtime 按不可恢复/可恢复快照分别执行正确补偿。
• headers 对应的显式替换、保留旧 headers、仅删除三组行为与 API key 对齐。
• safeStorage 暂时不可用与永久损坏密文至少在日志/错误分类上可区分；日志不得包含明文、密文或完整本地路径。
• 回归现有“未填写凭证时仅改名称/模型不会清掉凭证”和“端点改变会清理 endpoint-bound 凭证”的测试。

相关记录：

• PR #912：直接说明 macOS 上不同签名身份或构建可能共享/更换 safeStorage 钥匙串条目，导致存量密文无法互读；该 PR 只隔离独立 dev 实例，明确没有为 packaged 构建做存量凭证迁移，因此可解释本 Issue 的触发背景，但不是当前更新死锁的修复。
• Issue #871：记录 cn/global/dev safeStorage 条目复用及 ACL 冲突的产品背景；其中“存量密文绑定原主密钥、迁移需要单独设计”的边界说明了为什么不能把不可解密一律当作空凭证。
• Issue #1687：虽非自定义供应商 CRUD，但同样要求对持续 safeStorage 故障进行原因区分、持久升级和用户可操作提示，可复用其错误体验方向。

发布与验证：该修复不应仅停留在 main。合并后应在 macOS packaged 构建中验证：人为替换某 runtime .enc 内容后，重新填写 key 能保存并实际使用新凭证；配置更新失败时不会留下新凭证或破坏其他 runtime。还应确认 0.1.71 用户在升级后能通过重新填写 key 自助恢复，而无需手动进入 safe-storage 目录。