fix: wrapper download-chain integrity + honest runtime version (#392, #393)

[kiki830621]

Refs #392
Refs #393

Cluster PR（兩案同檔 plugin/bin/che-apple-mail-mcp-wrapper.sh，Conflict Class C —— 分開改必互撞）。

本 body 於 2026-09-09 重寫（#398 verify round 3）。 前一版描述的是 round-1 的設計，其中一項機制（curl --fail）已被 head 刻意否決，測試數字停在 25/25，並列了一列實測不存在的覆蓋。PR body 是決定合併時實際被讀的東西，讓它落後於 head 等於把 #318 的「closing comment 是死信」提早一個 artifact 重演。

#392 — 下載鏈完整性

1. HTTP 狀態碼判讀（不是 curl --fail）。前一版 body 說要用 --fail；head 明確拒絕：

   # Deliberately NOT -f: distinguishing a definitive 404 from rate-limits /
   # timeouts / 5xx is the whole point
   

   因為 --fail 會把「pinned tag 確定不存在（404）」與「暫時性失敗（403 rate-limit / 5xx / timeout）」壓成同一種 curl 失敗，而這兩者必須分開才能決定「fallback 一次並記 marker」還是「保留現有 binary、下次 spawn 重試」。改用 -w '%{http_code}' 讀狀態碼。錯誤頁的防線因此是另外兩道：狀態碼閘 + looks_like_html 形狀檢查（後者在 round 3 之前沒有測試，見下）。

2. sha256 驗證，fail closed。digest 取自 release 自己的 asset list；比對在 chmod / mv 之前。唯一允許未驗證安裝的情形是該 release 根本沒發布 digest。「本機算不出 digest」（無 hash 工具、或 shasum 存在但壞掉）是拒裝，不是降級 —— round 1 在這裡 fail open，正是 bug: wrapper 下載鏈零完整性驗證 — curl 缺 --fail、有 .sha256 asset 卻不驗、pinned-tag 落空每次 spawn 重下載 (#335 verify) #392 要關掉的洞。

3. asset URL 結構化驗證（round 3 新增）。round 2 用字串前綴比對「釘住」host，round 3 證明那不是釘住：curl 會在送出請求前正規化路徑。實測 curl -w '%{url_effective}'：

   .../che-apple-mail-mcp/releases/download/../../../../attacker-org/evil-repo/releases/download/v1/CheAppleMailMCP
     → https://github.com/attacker-org/evil-repo/releases/download/v1/CheAppleMailMCP
   

   且 .sha256 走同一條選取規則、來自同一個攻擊者路徑，所以驗證會通過、印出 (sha256 verified)、然後 exec 別人的 binary。#fragment 同理在送出前被丟棄，於是 basename 檢查可以被伺服器根本看不到的文字滿足。現在改為結構化驗證：/download/ 後恰好兩段、無 query、無 fragment、任何拼法的 dot-segment 皆拒。

4. latest-fallback 迴圈 guard。pinned tag 確定 404 → fallback latest 一次並寫 .fallback-tried（<pin> <epoch> <miss|verify>，24h TTL）。pin 改變、TTL 到期、或手動刪檔皆解除。

#393 — runtime state 記實際版本

version_at_spawn 原寫 DESIRED_VERSION（期望值）——下載失敗保舊 binary 時 runtime 記著新版號，staleness hook 比對 plugin.json 恆相等 → 假陰性永不 respawn。現在寫入前重讀 sidecar；sidecar 無法解析 tag 時寫 unknown，不回填 pin（回填 pin 正是 #393 的謊）。

degraded_pin 不變量（round 2 建立，round 3 未變）

degraded_pin 有值 若且唯若同一個 pin 寫了 marker。其餘所有降級結果（暫時性 API 失敗、下載錯誤、digest 抓取失敗、rename 失敗）刻意留空，因為對那些情況而言 hook 的 kill 就是重試觸發器 —— 它讓 Claude Code 重新 spawn wrapper。round 1 在暫時性路徑也蓋 degraded_pin，等於掐掉唯一的重試觸發器，把「下次 spawn 重試」變成「永不重試」。

hook 端另外重新驗證 marker 本身（存在、pin 相符、TTL 未過、無時鐘偏移），因為 TTL 只有 wrapper 會判讀，而 wrapper 要等 kill 才會再跑 —— 只信 runtime 欄位會讓降級狀態永久化。

Verification

plugin/tests/test-wrapper-download.sh（PATH-shim mock curl）——95 asserts / 28 scenarios（round 1 是 25、round 2 是 76）。

涵蓋含：minified API body、外部 host、dot-segment（兩種形狀）、#fragment、無 hash 工具、present-but-broken shasum、HTML 錯誤頁、marker 注入 payload、未來日期 epoch、SemVer build metadata、temp 洩漏與檔案權限、逾時預算、hook 整合（含 miss / verify 兩種 marker 與負對照）。

Round 3 稽核了 round 2「每個修復都做過 mutation 測試」這句話，發現它是假的 —— 五個修復零覆蓋（stale-marker 清除、HTML 錯誤頁拒裝、openssl fallback、SemVer build metadata、未來 epoch guard），加上 hook 的 verify 分支。全部補上 case。

九個 mutation 全被抓到 —— 但其中兩個新 case 一開始自己也在空轉：dot-segment payload 早被「恰好兩段」的 regex 擋掉、根本沒走到 dot-segment 檢查；stale-marker case 讓下載成功，所以事後清理無論那個分支在不在都會清掉 marker。兩者都已改成真的觸及它們宣稱測的程式碼。

Case 28 是結構性的：grep 出貨腳本裡的 bash-4 專屬語法。shebang 是 /bin/bash，在 macOS 上是 3.2，${x,,} 在那裡 bash -n 解析得過、展開時才炸 —— 這一輪就出貨過這個錯，套件當場 0/76 而症狀看起來像邏輯 bug。

bash -n 通過（wrapper + hook + suite）。

[kiki830621]

6-AI verify — round 2 + fixes (#392, #393)

Backend: pai-ensemble 2.20.0 · 4 lenses + devil's-advocate + Codex gpt-5.6-sol (xhigh) · dispatch model opus · 65 findings (18 HIGH / 27 MEDIUM / 10 LOW / 10 INFO).

Round 1 drove an architectural redesign. Round 2 showed the redesign had introduced a regression of its own and had the retry story backwards.

The load-bearing findings

Finding	Verdict	Fix
Binary download timeout 300s → 30s	Real regression, verified against the pre-patch file (line 66 was --max-time 30 for metadata, line 80 --max-time 300 for the binary). Unifying both behind one http_get collapsed the 18 MB download onto 30s. At 400 KiB/s a fresh install can never finish: exit 1, no MCP server	http_get takes a timeout; the binary gets 300s. The mock ignored --max-time, so the suite was structurally blind — it now records and asserts both budgets
degraded_pin written on TRANSIENT failures	Real	The hook suppresses the kill whenever it is set, and the kill is the only thing that respawns the wrapper — so "will retry next spawn" meant "never retries". degraded_pin is now set iff a marker was written, stated as a named invariant at the top of the wrapper
The hook never checked the marker or its TTL	Real, and it made the degraded state permanent	The 24h TTL is only ever evaluated by the wrapper, which cannot run until a kill respawns it — so at TTL+1h the hook still suppressed. Deleting the marker by hand did not help either, because nothing read it. The hook now re-derives the decision from the marker (existence, pin, TTL, clock skew)
sha256 fails OPEN when the hash tool is missing	Real — the fail-open #392 exists to close	Refuses. A published digest that cannot be checked is a refusal, not a downgrade
sha256_of dispatched on command -v shasum alone	Real — a shasum that exists but is broken never reached the openssl fallback, then reported "no sha256 tool available" and installed anyway	Tries each, validates the output shape, falls through
asset_url is line-based grep + greedy sed	Real — a minified body returns the LAST url on the line (the .sha256, or the zipball). Nothing in the API contract promises pretty-printing, and round 1 had reshaped the fixture to fit the parser	One url per line, exact basename match, host+path pinned to this repo's own release downloads
Marker epoch reaches bash arithmetic unvalidated	Real — a crafted value is executed there, and a non-numeric one aborted the wrapper	Validated, plus future-dated epochs
Four mktemp sites, zero traps	Real — unique names turned a bounded leak into ~18 MB per interrupted spawn	Trap added
Sidecar falls back to DESIRED when the tag cannot be parsed	Real — that is the #393 lie	Writes unknown
Marker's third field written but never read	Real	A digest mismatch is now reported as possible tampering, not "unavailable upstream"

Also fixed: an HTML error page can no longer be installed on the no-digest path; chmod is explicit (755) and checked; a fresh install that substitutes latest for an unresolvable pin says so; a stale marker for a pin we no longer want is cleared.

Evidence

bash plugin/tests/test-wrapper-download.sh   → 76 pass / 0 fail  (19 scenarios; was 55/12)
bash -n  (wrapper + hook + suite)            → clean

Nine mutations run, nine caught — each fix above had its defect deliberately re-introduced, one at a time, and every one turned the suite red. That exercise also caught one of my own assertions testing nothing: the corrupt-marker payload contained whitespace, so read split it across three fields and it never reached the arithmetic it claimed to exercise. Fixed with a whitespace-free ${IFS} payload, then re-run.

Two of my own bugs were caught the same way: X=$(new_temp …) ran the registration in a subshell and discarded it (the trap had nothing to clean), and the Case 17 shim omitted cp, which the mock curl itself uses — so the wrapper failed for the wrong reason while the case's negative asserts still passed.

Honest status

Not independently re-verified. MAX_ROUND=2 was reached. What stands behind these fixes is reproduction + the mutation battery above, not another adversarial round. Given this round found 18 HIGH on a diff that had already been through one full round, a third round on the current head is worth running before merge.