# Secure Local Persistence Postmortem

## 问题摘要

用户现场反馈很直接：

- 当前会话里 Gateway 可以正常连接
- App 一重启，本地配置和已保存凭证丢失
- `Gateway 访问` 页重新出现 `gateway token missing`

这不是单点 bug，而是持久层设计里连续几处降级路径叠加后的结果。

## 用户可见症状

### 1. 重启后网关凭证丢失

表现：

- token / password 在当前会话内可用
- 退出再打开后不可用
- 首次连接提示重新输入 shared token

### 2. 本地配置或任务会话恢复不稳定

表现：

- settings snapshot 或 assistant threads 在某些路径下恢复失败
- backup 虽然存在，但仍可能是明文旧格式

### 3. 明文本地状态残留

表现：

- 旧版 `SharedPreferences` 和 SQLite 中存在明文 settings / threads
- backup 文件也可能保留明文副本

## 根因

## 根因 1：对 `FlutterSecureStorage` 强制套了 400ms 超时

旧逻辑：

- secure storage 读写只要超过 `400ms`，就视为失败
- 一旦失败，直接退化成“仅内存”

结果：

- 当前进程内看起来一切正常
- 因为值实际上没持久化，进程退出后凭证全部丢失

这是这次“重启后 token 消失”的直接根因。

## 根因 2：secure storage 失败时降级策略设计错了

旧策略把“可恢复 secret”误当成“会话临时缓存”处理：

- token / password / API key 没写进 durable fallback
- 只保存在进程内存

这个策略对调试场景看似友好，但对桌面 App 的真实使用是灾难性的，因为用户天然预期“已经保存”的 secret 会跨重启存在。

## 根因 3：legacy prefs 迁移把明文直接写回了主存储

迁移链路里存在一个关键缺口：

- 从 `SharedPreferences` 读取到旧版明文 settings / threads
- 直接调用数据库写入
- 没有经过 sealed local state

结果：

- 用户完成升级后，本地状态仍可能继续以明文形式存在 SQLite
- 旧的 pref key 也没有被及时清理

这让“升级到新版本后自动变安全”的承诺失效了。

## 根因 4：本地状态密钥也被允许走普通 fallback

旧版把 `xworkmate.local_state.key` 当成普通 secret 处理。

结果：

- 一旦它掉进 fallback 文件，secure storage 就不再是本地状态加密的真正前提
- 架构上变成“有 secure storage 更好，没有也能常态运行”

这违背了本次补丁要建立的安全模型。

## 根因 5：线程状态异步保存存在覆盖竞态

Assistant 线程会话是异步落盘的。旧逻辑没有串行 flush：

- 线程 A 的旧快照可能在稍后写入
- 覆盖线程 B 或更新后的新状态

在加密封装增加写入成本后，这个竞态更容易暴露。

## 修复策略

### 1. secure storage 不再 400ms 即判死刑

- 超时提高到 `5s`
- 对真实 `FlutterSecureStorage` 保留超时保护
- 对测试注入 client 不套这层超时

### 2. secure storage 失败时改为 durable fallback，而不是仅内存

- Gateway token
- Gateway password
- AI Gateway API key
- Vault token

这些 secret 在 secure storage 异常时会写入持久化 fallback，保证跨实例恢复。

### 3. 本地配置和任务会话统一 sealed

对以下状态统一改为 AES-GCM sealed payload：

- `SettingsSnapshot`
- Assistant thread records
- `assistant-state-backup.json`

目标是消除明文 SQLite / 明文 JSON backup。

### 4. legacy 明文状态迁移时立即重写并清理旧 pref

新逻辑：

- 读旧 pref
- 若目标存储不存在，则按 sealed 路径写入
- 写入成功后删除旧 pref key

这样升级后不会继续遗留明文主副本。

### 5. 本地状态密钥升级为 primary secure storage only

`xworkmate.local_state.key` 现在的规则是：

- 必须优先保存在主 secure storage
- 不再纳入普通 secure fallback 白名单
- 对旧版 `local-state-key.txt` 仅做一次迁移，随后删除

### 6. Assistant 线程持久化改为串行队列

新增线程持久化 queue 和 flush 机制，保证：

- 新状态不会被晚到的旧写入覆盖
- clear / send / view-mode 切换前可以先 flush

### 7. dispose 后的异步通知保护

`SettingsController` 新增 dispose guard，避免恢复链路异步完成后向已销毁对象 `notifyListeners()`。

## 为什么旧方案会失效

旧方案的问题不在“没加密”，而在于它把三件不同的事混在了一起：

- 当前请求是否可用
- 是否已经持久化
- 是否已经安全持久化

一旦 secure storage 稍慢，系统就会把“当前连接可继续”错误地当成“数据已经保存”，这正是桌面应用里最危险的误导。

## 回归防线

这次新增的回归覆盖重点包括：

- secure storage 超时后 secret 仍能跨实例恢复
- SQLite 不可用时，sealed 的 settings / threads 仍能恢复
- plaintext local state 能迁移为 sealed storage
- legacy `local-state-key.txt` 能迁移到主 secure storage 并被清理
- backup 文件不再泄露明文 settings / threads

## 后续约束

后续所有涉及本地状态持久化的修改，都必须继续满足：

- `.env` 仍是预填，不是持久化真值
- 当前用户发起连接时可直接用表单值握手，不依赖 secure-store 回读
- local state 不得重新落回 `SharedPreferences` 明文
- backup 不得重新变成明文副本
- 不能再让 `xworkmate.local_state.key` 走常态文件 fallback