Skip to content

[PR] fix(zcode): point GUI cert-MITM CA path at combined-ca.pem, not root-ca.pem - #5736

Open
ranxianglei wants to merge 3 commits into
masterfrom
2026-11-05_zcode-ca-combined-bundle
Open

ranxianglei wants to merge 3 commits into
masterfrom
2026-11-05_zcode-ca-combined-bundle

Conversation

@ranxianglei

Copy link
Copy Markdown
Owner

Closes #5725

What & why

ZCode's desktop Proxy CA certificate path field replaces the client's entire trust store, and propagates into child env vars with the same replace semantics (SSL_CERT_FILE / CURL_CA_BUNDLE / REQUESTS_CA_BUNDLE). The docs and the web-UI copy button were handing out the single-cert root-ca.pem for that field, so every non-MITM fetch — including ZCode's own plugin-marketplace refresh — failed with unable to get local issuer certificate, reintroducing the #152 failure class.

combined-ca.pem is the superset bundle bili already maintains (MITM root + Node public roots + OS trust store, OS-store merge since #1807) and is exactly what the codex/dsh/hermes launcher lanes point SSL_CERT_FILE at. It validates both the MITM leg and real public chains under replace semantics, so it is correct whether the consuming host appends or replaces.

Changes

  • Docs (CONFIGURATION.md en + CONFIGURATION.zh-CN.md): cert-MITM one-time setup step 2 and the Windows absolute-path note (证书路径兼容 #342) now recommend combined-ca.pem, with a one-line why. root-ca.pem stays documented as the append-semantics (NODE_EXTRA_CA_CERTS) target.
  • Web UI (src/web/page.ts): the ZCode card's displayed path and copy button now emit combinedCaPath() instead of rootCaPath().
  • Test (tests/web-routing.test.ts): assertions updated to the combined bundle.
  • Consistency: de-staled the rootCaPath() doc comment (it claimed ZCode points at the single cert); two zcode/native.ts guidance strings now say "combined CA path".

Behavior change (old → new)

The CA path surfaced to ZCode users changes from …/ca/root-ca.pem → …/ca/combined-ca.pem. Intended — this is the fix. No change to append-semantics launchers; no config-schema / persistence / wire change.

Config surface

None — no new env var, config key, or CLI flag.

Verification

  • Targeted suite local: node --import tsx --test tests/web-routing.test.ts → 8/8 pass (incl. the updated ZCode-card assertion).
  • tsc --noEmit clean. Full-suite verdict deferred to CI on this head per repo test discipline.

…ca.pem (#5725)

ZCode's "Proxy CA certificate path" field REPLACES the client's whole trust
store (and propagates into child env vars with the same replace semantics), so
handing it the single-cert root-ca.pem breaks every non-MITM fetch — including
ZCode's own plugin-marketplace refresh — with "unable to get local issuer
certificate", reintroducing the #152 failure class. combined-ca.pem is the
superset bundle (MITM root + public/OS roots, #1807) that validates both the
MITM leg and real public chains under replace semantics, matching how the
codex/dsh/hermes launcher lanes already point SSL_CERT_FILE.

- docs (CONFIGURATION.md en + zh): cert-MITM one-time setup step 2 + Windows
  absolute-path note now recommend combined-ca.pem, with the why.
- web UI: ZCode card displayed path + copy button now emit combinedCaPath().
- tests/web-routing.test.ts: assertions updated to the combined bundle.
- consistency: de-stale rootCaPath() doc comment; zcode/native.ts guidance
  strings say "combined CA path".
@github-actions

github-actions Bot commented Nov 5, 2026 •

Copy link
Copy Markdown
Contributor

📦 Built Package Artifact

Branch: 2026-11-05_zcode-ca-combined-bundle (dd244f8)

Latest build — install this exact version

npm install -g billion-context@0.0.8980-pr.5736.1f486d3

This exact version is immutable and reproducible. The rolling pr tag tracks the newest test build across all PRs.

Recent builds (commit → version)

commit version build
dd244f8 billion-context@0.0.8980-pr.5736.1f486d3 build
5ae4927 billion-context@0.0.8246-pr.5736.7fc2144 build
a442dd3 billion-context@0.0.8236-pr.5736.4f7379b build

Download artifact

  1. Download the artifact from the Actions run
  2. Extract the tarball and install:
tar xzf billion-context-pr5736.tgz
npm install -g package

Install instructions are refreshed on each push.

@ranxianglei ranxianglei changed the title fix(zcode): point GUI cert-MITM CA path at combined-ca.pem, not root-ca.pem [PR] fix(zcode): point GUI cert-MITM CA path at combined-ca.pem, not root-ca.pem Nov 5, 2026
@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

(ai: vllm-qwen/qwen3.8-27b)

查重:不重复。本 PR(GitHub #5736)是 #5725 的唯一修复 PR;open [PR] 列表里没有第二个针对 zcode cert-MITM CA 路径的并行 PR。

标签:bug zcode scope/ui p2(+ 既有 pr)——ZCode GUI cert-MITM 用户照文档/卡片粘单证书会挂掉所有非 MITM 抓取,但主链路(压缩模型流量)可用、可手动改用 combined-ca.pem 绕行 → 明显问题而非不可用,判 p2。

PR 审核结论 · GitHub #5736

head a442dd3e8,base master(behind,需 rebase),1 commit,6 文件 +17/−15。

八问

  1. 是什么问题:ZCode GUI「Proxy CA certificate path」字段会替换客户端整个信任库,并以同样的 replace 语义下发到子进程 env(SSL_CERT_FILE / CURL_CA_BUNDLE / REQUESTS_CA_BUNDLE)。此前文档与网页卡片都给出单证书 root-ca.pem,于是所有非 MITM 抓取(含 ZCode 自己的插件市场刷新)报 unable to get local issuer certificate,重现 ZCode 集成:MITM-only CA bundle 覆盖系统根证书,导致 pip/git 等 TLS 校验失败 #152。
  2. 什么原因导致的:把两种信任语义混了——「信任 MITM 根」(append,NODE_EXTRA_CA_CERTS→root-ca.pem)vs「作为整个信任池」(replace,SSL_CERT_FILE 类→必须超集)。GUI 字段属于后者,却给了前者。
  3. 影响范围与严重程度:只影响走 ZCode GUI cert-MITM 且照抄路径的用户;坏的只是旁路非 MITM HTTPS,模型流量(MITM leg)仍正常。p2:能用但有明显问题,手动改 combined-ca.pem 即可绕行。
  4. 怎么修复的:把所有面向 ZCode 用户的出口统一指向已有的 combinedCaPath()(MITM 根 + Node 公共根 + OS 信任库超集,combined-ca.pem 在 Windows 上不是 OS 信任库的超集 —— 替换语义客户端会丢失信任材料 #1807 起维护、codex/dsh/hermes 已在用)——网页卡片 src/web/page.ts:18(显示 + 复制按钮 + ready 态共用同一变量)、CONFIGURATION.md 中英 step2 + Windows 绝对路径注、src/zcode/native.ts 两处引导串、src/ca.ts rootCaPath() 注释去陈旧化;测试断言同步到 combined-ca.pem。append 语义出口(launcher NODE_EXTRA_CA_CERTS、mitm.ts「trust the root」日志)保持 root-ca.pem 不动,正确。
  5. 是否有回归问题:逐项过既有行为——① 网页卡片 caReady = existsSync(caPath):ensureRootCA() 在全部三条路径都调 writeCombinedBundle()(src/ca.ts:274/286/296),combined-ca.pem 每次启动即生成、与 root-ca.pem 同生命周期 → ready 态不会翻红(含 ZCode-only 机器)。② launcher.ts:446(root)/:451(combined)、mitm.ts:36/70 均未被误改。③ 无 wire / config-schema / persistence / kernel / update.ts / session-binding 触碰。未见回归。
  6. 是否破坏缓存:不涉及(纯路径字符串 + 文案变更)。
  7. 是否改了设计方向:否——只是把已有 combined-ca.pem 接到 ZCode 这个此前漏接的出口,机制不变。
  8. 是否引入新配置:无(无新 env / config key / CLI flag)。

一个非阻塞观察(我判断现状自洽,供你定夺):CONFIGURATION.md:2310 / CONFIGURATION.zh-CN.md:2278 step-1 的 ls …/root-ca.pem # exists now 未改。它是「生成校验」而非「填哪个字段」,且 root-ca.pem 恰是被生成的根证书本身,留作生成信号是自洽的;若你要严格一致也可改成 ls combined-ca.pem,但我倾向保留(避免扩大这个已经很干净的 diff)。

验证:本地 clone 无 node_modules,跑定向测试需 npm ci(吃共享资源,按仓库本地测试纪律不做);最终全量判定以远程 CI 为准(当前镜像缓存无 check、PR behind master,需 rebase 后 CI 绿)。代码已逐行核过。

判定:代码正确、完整、范围收敛,行为变更已如实披露(旧 root-ca.pem → 新 combined-ca.pem,原因写明)。rebase 到当前 master + CI 绿即可合并。合并权在你,我不合并。

@ranxianglei ranxianglei added bug Something isn't working p2 scope/ui zcode 改动范围:内核之外的主机侧接线(src/agent 适配器、server 路由、注入拦截)/范围兜底/客户端标签 labels Nov 5, 2026
@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

(ai: vllm-qwen/qwen3.8-27b)

CI 修复完成(继承红,已收敛 ci-fixes) —— 新 head 5ae4927c2,等重跑。

八问:

  1. 是什么问题:本 PR 的 10 个 test shard 全红,但没有一条是本 PR 代码引起的——全部是 master 的继承性红([PR] fix: unknown dsh one-shot sidecars steal the raw-key anchor and kill compression (context-explosion root cause) #5687 合入 DSH: If the first request of a session originates from a bypass call, compression for the entire session is permanently | DSH: If the first request of a session originates from a bypass call, compress for the entire session is permanently inv | DSH:会话首个… #5656 侧车道路由后,master 自带 5 处 dsh 回归钉 born-red,每个 PR head 都继承)。
  2. 什么原因导致的:01fcc5d68(DSH: If the first request of a session originates from a bypass call, compression for the entire session is permanently | DSH: If the first request of a session originates from a bypass call, compress for the entire session is permanently inv | DSH:会话首个… #5656/[Bug][Codex Launcher] Marketplace Git repositories escape CODEX_HOME through Bili .tmp symlinks #5584)把无 tools 的 dsh 单轮请求改走 verbatim 侧车道后,5 个既有回归钉文件仍假定「turn 1 走全量管道」,合并瞬间即红、master 持续红至今。证据:各分片日志唯一失败行逐字相同(tests/issue2481-dsh-runtime-context.test.ts:255 的 BLOCKED-ref 断言,ubuntu/windows 同签名),静态门禁全绿——本 PR 自己的改动(web-routing 等)在失败的那次运行里是过的。
  3. 影响范围与严重程度:所有在途 PR 的 CI(信号级阻塞,非用户侧功能缺陷);不处理则任何 PR 都无法过 CI。本 PR 自身功能零影响。
  4. 怎么修复的:按 CI 协调政策不在分支内重复修——直接把 origin/ci-fixes(HEAD 0470bec62,仅测试侧重对齐那 5 处钉,提交体记录了本地全绿验证)merge 进 PR 分支。干净合并无冲突;逐项核对本 PR 的改动(web/page.ts 用 combinedCaPath()、zcode/native.ts 指引文案、CONFIGURATION en/zh、web-routing 断言)合并后原样保留;fast-forward 推送 a442dd3e8..5ae4927c2(未 force-push)。已在 CI Control Center: Centralized CI Failure Handling & Status Sync (Comment all CI issues here; do not open new issues) | CI 总控: CI 失败集中处理与状态同步(所有 CI 问题在此评论, 勿开新 issue) #4599 留一行协调记录。
  5. 是否有回归问题:无引入。ci-fixes 内容仅为测试期望对齐(以文档化行为为准),本 PR diff 未动;高危模式逐项过——无语义漂移、无 fail-fast 变吞错、无阈值/时序/输出格式变化。本 PR 自身的行为变更(root-ca.pem → combined-ca.pem 的指引面)是 PR 本意且其正文已披露,不属于本次修复引入。
  6. 是否破坏缓存:不涉及。
  7. 是否改了设计方向:不涉及。
  8. 是否引入了新的配置:不涉及。

判定:本轮收工——等待新 head 5ae4927c2 的 CI 重跑;若重跑仍红,attempt 2/3 继续处理。

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷
(ai: vllm-qwen/qwen3.8-27b)

补一条状态更新(完整八问审核见上一条,不重复):

CI 现状已变(我发审核结论时镜像缓存还是空的):分支 HEAD 已由 CI 工程师推进到 5ae4927c(接手的正是更早那批红掉的 test 分片,见楼内 10:26 / 10:34 两条接管记录)。当前镜像 check 缓存(fetched 11:32Z)无失败项:

  • success=12 —— 全部 guard 绿:version-guard、lane-guard、docs-coverage、docs-sync、config-surface-guard、kernel-guard、lock-sync、pi-subagents-guard、unused-exports、test-import-graph、lifecycle-ledger-guard、plan。其中 config-surface-guard + docs-sync 恰好佐证本 PR「无配置面变更 + 中英文档同步改」的声明成立。
  • skipped=17 —— 重型真实客户端 e2e 被路径过滤跳过(本 PR 只碰 web page.ts + 文档 + zcode 引导串 + ca.ts 注释 + 一个测试),正常。
  • cancelled=1 —— static-gates 一条,是推送前旧 run 被新提交顶掉,无害。

剩余唯一卡点:mergeable_state=blocked,但缓存里没有任何失败 check → 与我审核时判定的「落后于 master」一致(up-to-date 门禁),不是 CI 挂。rebase 到当前 master 即可解除,随后由你合并。

我没有动这个分支:CI 工程师已持有并正在推进(楼内接管记录),且现在没有红要修——我再上去 rebase 会跟它的并发工作打架(正是要避免的「两个 agent 抢同一分支」)。代码判定维持不变:正确、完整、行为变更已如实披露。合并权在你。

@ranxianglei ranxianglei left a comment

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

(ai: vllm-qwen/qwen3.8-27b)

Posted as a comment-review because the reviewing token is the PR author's account and GitHub forbids self-approval — the verdict below stands as APPROVE; a maintainer can record the formal approval.

APPROVE — clean, correctly scoped, CI green on head 5ae4927c2 (mirror cache: failed=0, pending=0).

Independence note: verdict re-derived from the diff + source, not from the issue text. Verified against src/ca.ts (generation), src/web/page.ts (render), and a full grep of every remaining root-ca.pem reference in src/ + docs.

Correctness. combinedCaPath() (~/.local/share/billion-context/ca/combined-ca.pem) is the MITM-root + Node-public-roots + OS-store superset (#152/#1807). The ZCode GUI "Proxy CA certificate path" field replaces the client trust store and propagates into replace-semantics child env (SSL_CERT_FILE/CURL_CA_BUNDLE/REQUESTS_CA_BUNDLE), so it needs exactly that superset — the single-cert root-ca.pem cannot validate blind-tunnelled real public chains, breaking every non-MITM fetch (incl. ZCode's own plugin-marketplace refresh). ensureRootCA() writes both root-ca.pem and combined-ca.pem in one startup call, so the UI's caReady = existsSync(caPath) readiness semantics do not regress (a fresh install has the bundle present before the UI is reachable; the #5103 write-refusal path either reuses a valid bundle or fails fast before the proxy serves). page.ts now sources the displayed path, the copy button, and the readiness badge from a single caPath = combinedCaPath() — no dangling rootCaPath import/ref remains.

No missed spots. Every other root-ca.pem reference is either append-semantics (launcher NODE_EXTRA_CA_CERTS, hermes legacy HERMES_CA_BUNDLE, the two mitm.ts "install/trust the root CA in your store" logs) or generic "the MITM root" prose (setup step-1 existence check, launcher-reference bullet) — none feed a replace-semantics GUI field, so leaving them is correct.

Diff hygiene. The zcode commit a442dd3e8 touches exactly its 6 in-scope files (2 docs, src/ca.ts, src/web/page.ts, src/zcode/native.ts, tests/web-routing.test.ts). The six tests/issue2419/2446/2447/2481/2817/5403 changes are not bundled scope creep: they arrive through the origin/ci-fixes sentinel merge (5ae4927c2) — the prescribed absorption of the inherited master red (#5656 sidecar residual broke five dsh regression pins + the fastpath stamp). Net master..head = 12 files, nothing unadvertised.

Tests. tests/web-routing.test.ts asserts the rendered ZCode card carries the machine's real combined-ca.pem path, the copy button emits it, and it is not a hardcoded ~/… string — reverting page.ts to rootCaPath() fails all three, so it is a genuine regression guard, not a tautology.


结构化八问

  1. 是什么问题:ZCode GUI 的「Proxy CA certificate path」字段(及文档 step2 / Windows 注、网页卡片显示+复制按钮)让用户填单证书 root-ca.pem;该字段是 replace 语义(替换客户端整个信任库,并以同样语义下发到子进程 env),导致所有非 MITM 抓取(含 ZCode 自己的插件市场刷新)报 unable to get local issuer certificate,复现 #152 失败类。
  2. 什么原因导致的:把 replace 语义的消费者指向了只含 MITM 根的单证书文件;非白名单主机走盲隧道、呈现真实公共证书链,单证书信任库无法校验这些链。
  3. 影响范围与严重程度:仅 ZCode cert-MITM GUI 这一条姿势面;按文档填了 root-ca.pem 的用户,其模型流量(MITM 腿)仍正常压缩,但该主机的非模型抓取(插件市场刷新等)全挂——核心能力可用、特定功能异常且有绕行(手动指向 combined-ca.pem),属功能性缺陷而非核心可用性丢失。未触及其它车道/代理模式。
  4. 怎么修复的:把 GUI 字段、文档(step2 + Windows 注)、网页卡片显示+复制按钮统一指向既有超集包 combined-ca.pem(MITM 根 + Node 公共根 + OS 信任库,#1807),与 codex/dsh/hermes launcher 车道一致;root-ca.pem 保留为 append 语义(NODE_EXTRA_CA_CERTS)的目标。
  5. 是否有回归问题:无。逐项过既有行为——网页卡片路径/复制按钮/就绪态(均改指 combined,有意且已披露)、en+zh 文档 step2+Windows 注(有意)、ca.ts rootCaPath() doc comment(去陈旧,纯注释无行为)、zcode/native.ts 两条日志措辞(用户可见文案,无行为变更)、web-routing.test.ts(断言对齐)。高危模式逐项:无语义漂移(改动即目标语义,已披露旧值→新值)、无 fail-fast 变吞错、无默认值/阈值/时序漂移、缓存/重试策略不受影响;existsSync 就绪语义不回归(两文件同一 ensureRootCA() 内生成)。
  6. 是否破坏缓存:不涉及——不触碰压缩/折叠/会话/前缀缓存任何逻辑。
  7. 是否改了设计方向:不涉及架构/边界/数据流转向;只是把一个既有字段指到正确的既有产物。
  8. 是否引入新的配置:无(无新 env / config key / CLI flag;PR 正文已声明 Config surface: None)。

判定:可合。 核心修复正确、范围干净、CI 在 head 上绿;六处 dsh 测试项为 ci-fixes 哨兵并入(继承 master 红 #5656 的规定处置流程),非夹带无关改动。

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

(ai: vllm-qwen/qwen3.8-27b) Review of upstream #5736 done: APPROVE — posted as a comment-review (GitHub blocks formal self-approval since the token is the author’s account). Core CA-path fix is correct and cleanly scoped; the six dsh test-pin changes are the sanctioned \ sentinel absorption of the inherited master red (#5656 sidecar residual), not bundled scope creep; CI green on head 5ae4927 (failed=0). No small findings requiring an on-the-spot fix.

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 (ai: vllm-qwen/qwen3.8-27b)

PR review 完成,判定 APPROVE / 可合。

Review 已发(comment-review 形式——token 账号即 PR 作者,GitHub 禁止正式 self-approve,正文判定为 APPROVE,maintainer 可补点正式 approve):
#5736 (review)

结论:可合。 合并权在 maintainer(agent 不合并 PR)。

…ve conflict (re-apply combined-ca.pem lines to docs/configuration*, keep root redirect stubs)
@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

(ai: vllm-qwen/qwen3.8-27b)

Merge conflict resolved — origin/master (tip 58a8796224) merged into the PR branch, pushed fast-forward 5ae4927c2..dd244f8929 (no force-push; remote head verified unchanged before push, so no concurrent work was displaced). Live single GET on the GitHub API confirms: head dd244f8929, base 58a8796224, mergeable = true. mergeable_state still reads blocked only because the required checks haven't run on the new head yet — they will re-trigger automatically.

What the conflict actually was: master moved CONFIGURATION.md / CONFIGURATION.zh-CN.md out of the repo root into docs/configuration*.md, leaving one-line redirect stubs at the old paths (the doc-layout ruling, #5920) — while this PR's branch still carried the pre-move files with its edits inside them. So both sides had rewritten the same two files in incompatible shapes (full doc vs stub). Resolution = union of intent:

One transparency note: the mirror's upstream-checks cache for this PR is stale (last fetched 2026-11-05, still showing the old head), so I could not read the post-push check states from it — the live GitHub GET above is the verification for mergeability, and the CI re-run on dd244f8929 is the verdict for tests. If anything stays red after that re-run, attempt 2/3 continues from here.

八问:

  1. 是什么问题:PR 与 base 分支冲突(dirty)——master 把两份 CONFIGURATION 文档迁到 docs/ 下并留重定向占位,而本 PR 分支还带着迁移前版本且内含本 PR 的修改,两边对同一文件做了不兼容改写。
  2. 什么原因导致的:文档布局调整([PR] docs: batch-migrate 14 root-level documents into docs/ (consolidation + master index + redirect placeholders) | docs: 14 个根级文档一次性迁入 docs/(集中 + 总目录 + 重定向占位) #5920)在本 PR 分叉之后落 master;PR 自身改动(root-ca.pem → combined-ca.pem 指引,en/zh 各两行)落在已被搬走的路径上。
  3. 影响范围与严重程度:仅阻塞本 PR 合并(信号级),无用户侧功能影响;不解决则 PR 永远 dirty、CI 全 skip。
  4. 怎么修复的:把 origin/master(tip 58a8796224)merge 进 PR 分支;冲突按「意图并集」解——根路径保留 master 的重定向占位,本 PR 的四行文档改动逐字重放到新位置 docs/configuration*.md(目标行与 PR 改前文本逐字节一致,无漂移);src/ca.ts 自动合并保留双方意图([Bug][codex][macOS] bili codex fails on every connection: combined-ca.pem includes non-CA keychain certs, and com.apple.kerberos.kdc makes Codex reject the whole bundle #5802 CA-only 过滤 + 本 PR 注释去陈旧化);fast-forward 推送,未 force-push、未覆盖任何并发工作。
  5. 是否有回归问题:无引入。逐项核过既有行为:根路径占位与 master 一致;新位置文档除本 PR 四行外零改动;src/ca.ts 双向意图均在;web UI/zcode 指引/测试断言原样保留。无语义漂移、无阈值/时序/输出格式变化。
  6. 是否破坏缓存:不涉及。
  7. 是否改了设计方向:不涉及。
  8. 是否引入了新的配置:不涉及。

判定:本轮收工——冲突已解(live 验证 mergeable=true)、等 dd244f8929 的 CI 重跑;若仍红,attempt 2/3 继续。

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[ework] CI fix verified green ✓

1 similar comment
@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[ework] CI fix verified green ✓

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

bug Something isn't working p2 scope/ui zcode 改动范围:内核之外的主机侧接线(src/agent 适配器、server 路由、注入拦截)/范围兜底/客户端标签

Projects

None yet

1 participant