Fence installation transaction durability (T-613)

2026-07-18 16:28:49 +08:00
parent 84befee70f
commit 20596a7de4
18 changed files with 697 additions and 64 deletions
@@ -47,7 +47,7 @@ SoftBox 软件盒子是一个使用 Go + Gio 开发的 Windows 桌面客户端,

 ## 当前阶段

-当前项目已完成 Phase 0～2、T-301 与审核整改 `T-604`～`T-612`。Windows 安全路径阻断项、图标缓存资源边界、后台结果回 UI 线程的事件接线、双适配器交互契约、`VisibleItems` 快照生命周期、双端 Gio shell 职责拆分、unsafe cache 安全诊断/runbook 以及 ZIP 中央目录/EOCD(含 ZIP64)预扫描均已关闭;`T-613` 已落成为安装文件、目录与 journal 耐久顺序任务并是当前唯一待领取项,T-302 暂后置。
+当前项目已完成 Phase 0～2、T-301 与审核整改 `T-604`～`T-613`。Windows 安全路径阻断项、图标缓存资源边界、后台结果回 UI 线程的事件接线、双适配器交互契约、`VisibleItems` 快照生命周期、双端 Gio shell 职责拆分、unsafe cache 安全诊断/runbook、ZIP 中央目录/EOCD(含 ZIP64)预扫描以及安装文件/目录/journal 的代码层耐久顺序均已关闭;物理断电、文件锁与杀毒软件干扰验证仍后置到 T-302/T-601,T-302 暂后置。

 优先路径:

@@ -55,7 +55,7 @@ SoftBox 软件盒子是一个使用 Go + Gio 开发的 Windows 桌面客户端,
 2. 已完成 Phase 1:清单验签、ZIP 安全解压、原子切换回滚原型。
 3. 已完成 Phase 2 与 T-301:清单/列表/详情/图标缓存 + 可恢复下载队列。
 4. 已完成 T-604:modern/Win7 workspace 与 Gio 版本解析彻底隔离。
-5. 已完成 T-606～T-612:图标缓存资源边界、UI 线程事件接线、双 Gio 适配器交互契约、`VisibleItems` generation 生命周期、双端 `shell.go` 同 package 镜像职责拆分、unsafe cache 诊断/人工恢复指引和 ZIP 中央目录/EOCD 预扫描;下一步执行 T-613 的 Phase 1 文件/目录/journal 耐久整改,再继续 T-302/T-303 与 Phase 4-6。
+5. 已完成 T-606～T-613:图标缓存资源边界、UI 线程事件接线、双 Gio 适配器交互契约、`VisibleItems` generation 生命周期、双端 `shell.go` 同 package 镜像职责拆分、unsafe cache 诊断/人工恢复指引、ZIP 中央目录/EOCD 预扫描和安装耐久顺序;下一步先落成并执行独立签名向量任务,再继续 T-302/T-303 与 Phase 4-6。T-302/T-601 仍须补真实 Windows 环境的断电/干扰注入。

 ## 领取任务规则

@@ -183,7 +183,9 @@ Phase 1 ZIP 原型采用“两阶段解压”:第 0 阶段在任何 `zip.Reader`

 Phase 1 原子切换原型把 `install-transaction.json` 与目录现实共同作为恢复依据。阶段写入顺序为 `prepared → current_backed_up → staging_activated → committed`,健康失败写 `rollback_required`;崩溃恢复不自动信任未健康检查的新 current,而是恢复旧 backup 或撤销首次安装。日志结构见 [api.md](api.md)。

-该原型已覆盖进程在关键持久化步骤之间退出的恢复;真实断电时的目录项落盘顺序、杀毒软件/文件锁干扰仍需 T-302/T-601 在 Windows VM/真机做故障注入,当前结论不替代硬件级断电验证。
+T-613 已把该状态机的代码层耐久顺序收敛为:payload 的 CRC/长度检查后 `Sync`/`Close` → staging 子目录到根及其父目录同步 → prepared journal 的临时文件 `Sync`/`Close` 与 root 栅栏 → 每次目录 rename 的 root 栅栏与下一 phase journal → committed journal 的 root 栅栏 → backup/journal 清理的 root 栅栏。所有栅栏通过 installer 内部接口复用;非 Windows 使用目录 `File.Sync`,Windows 用 Win7 已有的 `CreateFile(FILE_FLAG_BACKUP_SEMANTICS)` 读写目录句柄和 `FlushFileBuffers`,失败一律 fail closed。测试可注入失败并验证状态机保留可恢复 journal,但这仍不是物理掉电证明。
+
+真实断电时的硬件/驱动缓存、杀毒软件/文件锁干扰和目标文件系统行为仍需 T-302/T-601 在 Windows VM/真机做故障注入,当前结论不替代硬件级断电验证。

 盒子自更新由独立 `SoftBoxUpdater.exe` 完成(传入 PID、暂存目录、目标目录;等待退出→备份→切换→启动新版→失败恢复)。

@@ -38,6 +38,7 @@
 - 任意 `zip.Reader` 构造前,必须以同一普通文件句柄核对已验签 Catalog 的 exact package `size` 与完成下载实际长度,并有界预扫描 EOCD/ZIP64:原始包、中央目录字节数和声明条目数超过硬上限,跨盘/截断/边界不一致元数据一律拒绝;不得先扫描路径后按该路径重新打开,不得仅依赖 `len(archive.File)`。
 - ZIP 解压必须保留文件数、展开体积和压缩比硬上限。
 - 安装/更新只走 `staging → current → backup` 原子流程;任何写 `current/` 的捷径都不允许。
+- 安装 payload 在 CRC/长度检查后必须 `Sync` 再 Close;staging 目录按子→根及其父目录建立栅栏。journal 临时文件内容、journal/backup rename 或删除、受控目录 rename 或删除后必须同步 app root,成功 phase 不得越过失败栅栏。Windows 目录栅栏使用 Win7 可用的 `FILE_FLAG_BACKUP_SEMANTICS` + `FlushFileBuffers`,不支持或失败必须 fail closed;单元测试不等同于物理断电证明。
 - 程序更新不得触碰 `data/` 与 `licenses/`。
 - 不强杀用户进程;更新前等待正常退出,超时取消。
 - 私钥、真实注册码、真实机器标识不进代码、测试数据和文档;`testdata/` 只放假数据和专用测试密钥对。
@@ -42,7 +42,7 @@

 #### Phase 1 交叉审核加固

-Phase 1 安全整改按 `docs/review/phase1-security-review.md` 的交叉复核定稿顺序串行落成。T-605 与 T-612 已关闭;T-613 处理文件、目录和 journal 的断电耐久顺序。签名向量任务在前一整改完成并提交后再正式编号,T-302 继续后置。
+Phase 1 安全整改按 `docs/review/phase1-security-review.md` 的交叉复核定稿顺序串行落成。T-605、T-612 与 T-613 已关闭;T-613 建立文件、目录和 journal 的代码层耐久顺序,物理断电验证仍后置到 T-302/T-601。签名向量任务在前一整改完成并提交后再正式编号,T-302 继续后置。

 | ID | 任务 | 依赖 | 验收要点 |
 | --- | --- | --- | --- |
@@ -212,6 +212,10 @@ T-102 Phase 1 原型进一步固定:

 phase 只允许:`prepared`、`current_backed_up`、`staging_activated`、`rollback_required`、`committed`。日志使用临时文件 + 同目录 backup 原子替换;恢复时同时检查日志与 current/staging/backup 实际状态。未完成健康检查的 current 不视为可信:有旧版时恢复 backup,首次安装则撤销 current。

+T-613 为该原型建立了 fail-closed 的耐久顺序:每个 payload 先完成 CRC/长度检查、`Sync`、`Close`;staging 目录按子目录→staging 根→父目录同步。每次 journal 写入均为临时文件内容 `Sync`/`Close` 后 rename,并在 transaction/backup rename、删除后同步 app root。`current → backup`、`staging → current`、rollback/recovery rename 和受控目录删除也必须先同步 app root,才可写下一 phase 或触发测试步骤;只有 `committed` journal 完成该栅栏后才清理 backup 和 journal。非 Windows 打开目录后 `File.Sync`;Windows 以 `CreateFile(FILE_FLAG_BACKUP_SEMANTICS)` 打开读写目录句柄并调用 `FlushFileBuffers`,任一打开、flush 或 close 失败均返回安装耐久错误,不得静默降级。
+
+这些栅栏与注入失败测试只证明代码层面的调用顺序和 fail-closed 行为,不证明断电后硬件/驱动缓存、网络文件系统、文件锁或杀毒软件的物理表现。T-302/T-601 仍须在目标 Windows VM/真机执行断电与干扰故障注入。
+
 ### 2.6 下载任务元数据 download-task.json(本地)

 每个任务以稳定 `request_id` 为主键,元数据位于 `downloads/tasks/<request_id>.json`,字节文件位于 `downloads/files/<request_id>.part|.download`。本地路径只由客户端从 request_id 派生,不接受 URL 或 Content-Disposition 提供的文件名。
@@ -13,22 +13,22 @@
 ## 当前快照

 - 日期:2026-07-18
- 阶段:Phase 2 已完成(T-201～T-204);Phase 3 的 T-301 可恢复下载队列已完成;审核整改 T-604～T-612 已完成,T-613 已落成为唯一 TODO,T-302 继续暂后置
+- 阶段:Phase 2 已完成(T-201～T-204);Phase 3 的 T-301 可恢复下载队列已完成;审核整改 T-604～T-613 已完成,T-302 继续暂后置
 - 技术栈:根 Go 1.25 workspace 只纳入 core/app-modern,`app-win7/go.work` 独立纳入 core/app-win7;版本闸门证明 modern Gio v0.10.1 与 win7 Gio v0.6.0 不交叉解析
- 生产代码:core 已有 Catalog/本地状态/存储、共享 Windows 安全相对路径策略、安全 ZIP 解压/回滚原型(Extractor 在同一普通文件句柄上核对 expected Catalog size 后有界预扫 EOCD/ZIP64、中央目录与条目数)、发布稳定只读 generation 的无 IO 软件列表模型、按 key in-flight + 流式有界读取 + 32 MiB/256-key LRU 的可信图标缓存、图标 Load/Decode 事件发布用例、有界 application event relay,以及默认并发 2 的持久可恢复下载队列;modern/win7 主循环已接 relay/Invalidate,AppShell 已实现搜索/分类/视图、惰性列表、详情右栏、完整图标失败 identity 生命周期与仅 `unsafe_cache` 可见的安全 locator/人工恢复提示,并按 root/header/catalog/detail/style 同 package 镜像职责拆文件
- 测试:core 覆盖 Catalog、列表快照 generation/零复制、SemVer/12 状态、本地安装记录、Windows dot-space/设备名/Unicode 折叠路径攻击、ZIP destination 包含性与 EOCD/ZIP64 原始包/中央目录/条目数预扫描、图标并发/取消/读取边界/LRU、真实目录/symlink fail-closed 与 cache→`unsafe_cache` event、relay 背压与关闭、下载并发/暂停/取消/重试/Range/断连/恢复/事件失败与文件身份替换;两个 app 覆盖 Editor/视图/分类/行/恢复/关闭接线、500 项 viewport、AppID 控件与分类控件生命周期、详情上下文、空状态语义、UI drain 前后、图标失败身份生命周期与 `unsafe_cache` 详情语义;安装恢复矩阵保持通过
+- 生产代码:core 已有 Catalog/本地状态/存储、共享 Windows 安全相对路径策略、安全 ZIP 解压/回滚原型(Extractor 在同一普通文件句柄上核对 expected Catalog size 后有界预扫 EOCD/ZIP64、中央目录与条目数,每个 payload Sync/Close 后同步 staging tree 及父目录;transaction/switch/rollback/recovery 的 journal、rename、清理经统一 fail-closed 耐久栅栏,Windows 使用目录句柄 FlushFileBuffers)、发布稳定只读 generation 的无 IO 软件列表模型、按 key in-flight + 流式有界读取 + 32 MiB/256-key LRU 的可信图标缓存、图标 Load/Decode 事件发布用例、有界 application event relay,以及默认并发 2 的持久可恢复下载队列;modern/win7 主循环已接 relay/Invalidate,AppShell 已实现搜索/分类/视图、惰性列表、详情右栏、完整图标失败 identity 生命周期与仅 `unsafe_cache` 可见的安全 locator/人工恢复提示,并按 root/header/catalog/detail/style 同 package 镜像职责拆文件
+- 测试:core 覆盖 Catalog、列表快照 generation/零复制、SemVer/12 状态、本地安装记录、Windows dot-space/设备名/Unicode 折叠路径攻击、ZIP destination 包含性与 EOCD/ZIP64 原始包/中央目录/条目数预扫描、payload/staging tree/journal/rename/rollback/recovery/cleanup 耐久顺序及错误注入、Windows 原生目录 `FlushFileBuffers`、图标并发/取消/读取边界/LRU、真实目录/symlink fail-closed 与 cache→`unsafe_cache` event、relay 背压与关闭、下载并发/暂停/取消/重试/Range/断连/恢复/事件失败与文件身份替换;两个 app 覆盖 Editor/视图/分类/行/恢复/关闭接线、500 项 viewport、AppID 控件与分类控件生命周期、详情上下文、空状态语义、UI drain 前后、图标失败身份生命周期与 `unsafe_cache` 详情语义;安装恢复矩阵保持通过
 - 数据:`schemas/` 已有 manifest/app.json/installed-app.json/download-task.json v1 Schema并注明 Windows 路径运行时权威规则;`testdata/catalog/` 有公开虚构清单样例;`testdata/zip/` 与 `testdata/download/` 记录运行时生成的攻击/传输矩阵
 - 标准启动路径:`./init.sh` / `./init.ps1`(同步依赖、执行完整 Phase 0 闸门、打印双目标构建命令)
 - 标准验证路径:`bash scripts/verify_phase0.sh` / `./scripts/verify_phase0.ps1`
 - 版本管理:git 已初始化,main 分支,远端 origin 为 Gitea `opc/soft_quay`;harness 文档已提交
- 当前 blocker:无;T-612 已闭合 ZIP reader 前的 Catalog size/完成文件长度/中央目录 EOCD(含 ZIP64)预扫描边界。T-613 已落成,将为 payload、staging tree、journal 与目录 rename/remove 建立耐久顺序和 Windows Flush 栅栏;T-302 继续后置到该阻断项关闭
+- 当前 blocker:无;T-613 已建立 payload、staging tree、journal 与目录 rename/remove 的 fail-closed 耐久顺序,并由 Windows 原生目录 `FlushFileBuffers` 用例验证。物理断电、文件锁/杀毒软件干扰仍需 T-302/T-601 的目标 Windows VM/真机故障注入;T-302 继续后置到签名向量整改完成

 ## 当前目录要点

 | 路径 | 状态 | 说明 |
 | --- | --- | --- |
 | `docs/` | 已有 | harness coding 文档集(本次初始化完成) |
-| `docs/tasks/` | 已有 | Phase 0～2、T-301 与 T-604～T-612 已完成;T-613 是当前唯一 TODO 的 Phase 1 文件/目录/journal 耐久整改,T-302 暂后置 |
+| `docs/tasks/` | 已有 | Phase 0～2、T-301 与 T-604～T-613 已完成;下一项先落成 Phase 1 签名向量整改,T-302 暂后置 |
 | `scripts/` | 已有 | harness 治理、core 边界、Go 版本检查与 Phase 0 双平台验证入口 |
 | `core/` | 已建 | Go 1.20 兼容;已有正式 Catalog、本地状态/存储、共享 Windows safepath、列表模型、有界并发图标缓存、图标事件/relay、可恢复下载队列与 Phase 1 安装安全原型 |
 | `app-modern/` | 已建 | Go 1.25.0 + Gio v0.10.1;Modern AppShell 已接入虚拟列表、详情、图标事件 drain/过期拒绝和内存 ImageOp,并拆为五类 shell 职责文件 |
@@ -40,9 +40,9 @@

 任务状态以 `docs/tasks/` 各任务文件 frontmatter 的 `status` 为准。本节只写项目级摘要:

- 已完成:Phase 0 的 `T-001`～`T-004`;Phase 1 的 `T-101`、`T-102`、`T-103`;Phase 2 的 `T-201`～`T-204`;Phase 3 的 `T-301`;审核整改 `T-604`～`T-612`。
+- 已完成:Phase 0 的 `T-001`～`T-004`;Phase 1 的 `T-101`、`T-102`、`T-103`;Phase 2 的 `T-201`～`T-204`;Phase 3 的 `T-301`;审核整改 `T-604`～`T-613`。
 - 正在进行:无。
- 下一个可领取任务:`T-613` — 为 payload、staging tree、journal 与目录 rename/remove 建立可测试的耐久顺序和 Windows Flush 栅栏。
+- 下一个可领取任务:暂无;应先按 Phase 1 审核定稿顺序落成独立 canonicalization/签名测试向量任务,再领取。T-302/T-601 的物理断电与干扰故障注入仍保留为发布前环境验证。

 ## 当前可运行内容

@@ -201,7 +201,7 @@ ZIP mode 决定 `0o600`/`0o700` 在目标 Windows 上基本不构成安全问题

 1. **[阻断 T-302 · 最高 · T-605]** 修 Windows 尾部空格/点、DOS 设备名与路径别名:建逐段 Windows 安全路径校验器(各层共用)+ 提取时 destination 包含性兜底检查;补 Win7/10/11 真实文件系统用例。关闭前不得把 Extractor 描述为"无路径穿越"。
 2. **[已关闭 · T-612]** 已在构造 `zip.Reader` 前增加同句柄包大小与中央目录/EOCD(含 ZIP64)预扫描边界;Extractor 强制接收 expected Catalog `size`,核对打开文件长度并限制原始包、中央目录与声明条目数,不只依赖 `len(archive.File)`。T-302 仍须把已验签 Catalog、完成下载文件和 SHA-256 编排为真实安装调用链。
-3. **[发布前必做]** 完整断电耐久策略:payload 文件 Sync → staging 目录元数据 → journal 顺序点 → 每次 rename 后父目录顺序点 → committed 耐久后才删 backup/journal;评估 Windows 目录句柄 `FlushFileBuffers`/写穿方案;T-302/T-601 用 VM/真机断电注入验证。
+3. **[代码顺序已关闭 · T-613；发布前环境验证仍必做]** payload 文件 Sync/Close → staging 子目录、根与父目录元数据栅栏 → journal 临时文件 Sync/Close 与 root 栅栏 → 每次 rename 后 root 栅栏 → committed 耐久后才删 backup/journal。Windows 已使用 Win7 可用的目录句柄 `CreateFile(FILE_FLAG_BACKUP_SEMANTICS)` + `FlushFileBuffers`,失败 fail closed;fake 覆盖 payload/tree/journal/rename/rollback/recovery/cleanup 失败，且原生 Windows 用例验证目录 fence 可执行。T-302/T-601 仍必须在 VM/真机进行真实断电、文件锁/杀毒干扰注入，不能以单元测试替代。
 4. **[协议冻结前]** `softbox-catalog` 与客户端独立 canonicalization/签名测试向量:Unicode 键序、转义、`<>&`、U+2028/2029、合法/非法 surrogate 拒绝策略、`-0`/大整数/嵌套 signature、base64 padding/CR/LF、同语义不同表示同签名字节。
 5. **[整合时复核]** 按真实包采样调解压硬上限,保留硬边界,不降级为软信号。
 6. **[实现时重点审]** T-402/T-403 真实健康检查:防"进程短暂启动即判健康"、错误工作目录/错误二进制被探活。
@@ -215,3 +215,10 @@ ZIP mode 决定 `0o600`/`0o700` 在目标 Windows 上基本不构成安全问题
 - 新的 EOCD 预扫描只读取最多 65,557 字节尾部和固定 ZIP64 locator/end 记录,拒绝跨盘、截断、offset/size 溢出或不一致结构,在标准库解析中央目录前限制 64 MiB 中央目录及 10,000 个声明条目。现有完整 `preflight` 保留为第二道 ZIP 语义和展开数据防线。
 - installer 回归覆盖 size 不一致、原始包超限、经典 EOCD 条目/目录伪造、跨盘/截断、ZIP64 有效和损坏 locator/end、非普通输入与 staging 未创建;`GOWORK=off go vet ./installer` 和 `go test -count=10 ./installer` 均通过。
 - 关闭的是 Extractor 边界,不是 T-302 生产安装整合或真实下载信任链;下一项断电耐久性整改仍独立阻断 T-302。
+
+### T-613 完成记录(2026-07-18)
+
+- `Extractor` 在每个 payload 的 CRC/长度检查后同步并关闭文件,随后从 staging 子目录到根、再到 staging 父目录执行栅栏;任一失败删除本次 staging,不返回可安装结果。
+- transaction、Switcher、rollback、Recovery 和受控删除统一经内部耐久接口:journal 临时文件先同步内容,所有 journal/目录 rename 或删除后同步 app root,未完成栅栏不得推进测试步骤或下一 phase。清理路径同时保留 `ErrRecoveryRequired` 与底层耐久错误,以便调用方可判定恢复状态。
+- Windows 原生目录测试已验证读写目录句柄 `CreateFile(FILE_FLAG_BACKUP_SEMANTICS)` + `FlushFileBuffers`;Go 1.20 标准 `syscall` 路径不引入 Win10+ API 或第三方依赖。fake 覆盖 payload/tree、journal、switch、rollback/recovery 与 committed 清理的错误传播和后续 Recover 不变式。
+- 关闭的是代码中的耐久顺序与 fail-closed 策略;T-302/T-601 的 Windows VM/真机物理断电、文件锁与杀毒软件故障注入仍为发布前环境验证,不宣称当前单元测试提供硬件级保证。
@@ -3,7 +3,7 @@ id: T-613
 title: 建立安装文件与目录事务耐久顺序
 phase: 1
 deps: [T-612]
-status: TODO
+status: DONE
 created: 2026-07-18
 issue: null
 context_ref: 0f69fa3bb4d00e6c79938c0a7bc66f5e0faec09e
@@ -77,3 +77,7 @@ T-103 已建立 `staging → current → backup` 的进程崩溃恢复状态机,
 - 2026-07-18:根据 `docs/review/phase1-security-review.md` 最终处理顺序第 3 项落成任务;现有全局最大任务为 T-612,因此取 T-613,依赖已完成的 T-612。
 - 2026-07-18:本地代码检索确认 Extractor 在 `io.Copy` 后仅 Close payload,`replaceFileWithBackup` 只 Sync 临时 journal 内容,Switcher/Recovery 的目录 rename 与 `removeManagedDirectory` 后均没有父目录栅栏。任务因此覆盖 payload、目录树、journal、切换/恢复 rename 与清理的统一顺序,不只修单个 `Sync()`。
 - 2026-07-18:Windows 策略限定为 Win7 已有的目录句柄 `CreateFile(FILE_FLAG_BACKUP_SEMANTICS)` + `FlushFileBuffers`,失败 fail closed;物理掉电/锁/杀毒故障注入的实测证据仍明确后置到 T-302/T-601。
+- 2026-07-18:在 `core/installer` 落地单一内部耐久接口。Extractor 现在在每个 payload 的 CRC/长度检查后 Sync、Close,并按 staging 子目录→根→父目录建立栅栏;transaction 的临时 journal 先 Sync/Close,全部 journal rename/remove 都同步 app root。Switcher、rollback、Recovery 与受控目录删除复用同一路径,每次目录可见变更完成 root 栅栏后才可进入下一 phase/afterStep。
+- 2026-07-18:Windows 目录实现使用 Go 1.20 标准 `syscall.CreateFile` 的读写目录句柄、`FILE_FLAG_BACKUP_SEMANTICS` 和 `FlushFileBuffers`,没有新增第三方或 Win10+ API;非 Windows 以打开目录的 `File.Sync` 实现。原生 Windows `TestSyncDirectoryPath` 通过,打开、flush、close 任一步失败均返回 `ErrDurability` 错误链。
+- 2026-07-18:新增 fake fence 顺序/失败测试,覆盖 payload、staging tree、journal、rename、rollback、Recovery 和 committed cleanup;失败不越过下一 phase,既有 `Recover` 仍将可恢复状态收敛。同步完成 API/架构/编码规则/审核结论,明确代码层顺序不替代 T-302/T-601 的 VM/真机物理断电、文件锁与杀毒软件故障注入。
+- 2026-07-18:验证通过:`GOWORK=off go -C core vet ./installer`、`GOWORK=off go -C core test -count=10 ./installer`、`./scripts/verify_phase0.ps1`、`python scripts/validate_agent_context.py`、`python scripts/validate_harness_governance.py` 与 `git diff --check`;完整验证同时覆盖 Go 1.20.14 core、现代版与 Win7 版构建/测试。无 blocker。