codex-app-server/docs/chv-muse-p4-gap.md

对齐 Muse P4 差距表：浏览器完全对齐

依据：~/workspace/research_notes/meta-muse-ai-architecture-20261101-0755/report.md （官方以 Meta security.muse.ai 2026-09-08 为准；第三方拆解只作参考， 逆向细节不得写成官方架构）。Muse 浏览器安全要求一句话：真实最新的 Chromium、位于虚拟化层之后；浏览器子代理只看到页面无障碍树快照、 不是原始 DOM；它不能在页面上下文中运行 JavaScript、无脚本动词、 无浏览器进程内 exec、DevTools 被禁用；CDP 连接由单元外 broker 管理； 用户接管浏览器或凭证存储正在填表时，代理被暂停、完全不能行动； 另有浏览器分类器家族与恶意网站拦截。

本轨范围只限 P4：浏览器完全对齐。不碰 P1（常驻 VM/气球/vsock）、 不碰 P3（authd/Sentinel 宿主侧）、不碰 P5（Sentinel 纵深 eBPF）、 不碰 P6（privsep worker/确定性安全检查层）。分支 feat-chv-muse-p4（从 06c3e17 分出）。

0. 与 P2 的关系（先说清，免得合入时糊涂）

P2（提交 c61484a）已把浏览器子代理独立出来：chv-guest/chv-browser.py （只返无障碍树快照，evaluate/content/DevTools 一律拒绝）、 chv-guest/chv-broker.py（单元外转发）、chv-guest/chv-cell.py、 build.sh/buildinfo.py 的安装步骤。P4 的基线 06c3e17 里没有这些 文件——P4 要改的正是它们，所以本轨先把 P2 的五个文件按原样拷进来 （cmp 逐字节核对过，与 c61484a 完全一致），再在上面做 P4 的收紧。 文件头与本表注明来源。

合入时的处理（给集成者）：

• chv-guest/chv-cell.py、chv-guest/chv-broker.py：P4 未改内容， 与 P2 版逐字节一致，合入无冲突。
• chv-guest/chv-browser.py：P4 在 P2 版基础上重构（不再直连 Playwright，改走 CDP broker；见 §2），合入时直接取 P4 版。
• chv-guest/build.sh、chv-guest/buildinfo.py：P4 版 = P2 版的步骤
  • P4 新增步骤（CDP broker 服务、guard 模块、拦截名单、ask 队列目录）， 合入时取并集。
• cloud/tests/test_chv_muse_p2.py：P2 的测试文件本轨不拷、不改； P4 的测试是独立的 cloud/tests/test_chv_muse_p4.py。P2 测试里 有一处与 P4 行为有关：test_open_returns_a11y_snapshot_with_fake_playwright 假定 BrowserAgent 直连 Playwright——合入后该测试须按 P4 的新结构改 （走假 CDP broker），见 §5；本轨不改它，留给集成者按本表执行。

1. 现状 vs Muse

项	现状（P2 已交付，代码为准）	Muse 目标	本轨做法
子代理看到什么	accessibility.snapshot() 无障碍树（截断 200 节点/64KB）+ 标题/URL；evaluate/content 已拒	只见无障碍树快照，不见原始 DOM	收紧到底：快照路径上所有回包与错误信息过 sanitize_error（去 HTML 标签、截断 200 字符、含尖括号即丢弃原文），任何响应字段不得含 ws://、DevTools 地址、原始 HTML；AST 测试钉住两个客机脚本里不存在脚本注入面
页面内 JS	socket 层拒 evaluate 等操作，但 Playwright 直连在 chv-browser.py 进程内——代码里今天没调，不等于调不了	不能在页面上下文运行 JS，无脚本动词	Chromium 的所有权移到单元外 CDP broker；broker 只调白名单调用（goto/title/url/accessibility.snapshot/screenshot/close + 只读监听 on(request/download)）；evaluate/add_script_tag/add_init_script/expose_function/set_content/eval 等一律不在代码里出现，AST 测试扫两个脚本的全部属性名
浏览器进程内 exec	无此操作	无浏览器进程内 exec	同上：broker 与子代理的代码里不存在任何经浏览器执行命令的调用；page.keyboard/mouse 等交互调用也不在白名单内（本轨无点击/填表操作）
DevTools	未显式开 --remote-debugging-port，但 Playwright 直连默认持有 CDP 端点，且 chv-browser.py 进程内可及	DevTools 被禁用；CDP 由单元外 broker 管理	launch 参数白名单（见 §2），无 --remote-debugging-port、无 devtools=True；CDP 端点（ws 地址）绝不进任何响应；Chromium 由 chv-cdp-broker（单元外、用户 chv-browser）独家启动，子代理只经 broker socket 说话
CDP broker	无（P2 是子代理直连 Playwright）	CDP 连接由单元外 broker 管理	新 chv-guest/chv-cdp-broker.py：单元外进程，Unix socket /run/chv/cdp-broker.sock，独家持有 Playwright/Chromium；chv-browser.py 改为 broker 的客户端
接管/填表暂停	无此语义	用户接管或凭证注入填表时代理被暂停、完全不能行动	状态机 active/paused 落在 CDP broker（pause/resume/status 操作）；暂停时除 ping/resume/status 外一切操作拒绝；触发源：显式 pause 操作（供将来用户接管通道调用）、POST 表单提交被观测到时自动暂停、高风险下载命中时自动暂停；凭证注入填表联动是 P3 的 authd 注入点，本轨只留 pause 操作接口与接线设计
高风险表单提交	无（P2 的 API 里根本没有点击/填表操作）	支付/密码类表单提交前停下等审批	确定性规则（不冒充模型分类器）：detect_form_risk 扫无障碍树，密码/支付字段即标 form_risk；高风险表单在页时 open 导航即返回 ask（入待审批队列、执行停止）；观测到 POST 请求即自动暂停 + 入队。审批队列与 P3 的 ApprovalQueue 同语义（见 §4）
DOM 内提示注入	无标注	外部数据进模型上下文时标注“不受信任输入”	detect_injection 启发式扫描快照文本（中英文注入模式，见 §2），命中即回包带 untrusted: true + injection_flags；快照本身恒带 untrusted_input: true（外部页面文本永远是数据、不是指令）
下载文件	无处理	下载文件中的提示注入要检测/阻断	scan_download 钩子：一条可测规则（可执行扩展名与双扩展名即拦：.exe/.msi/.bat/.cmd/.ps1/.sh/.dmg/.pkg/.apk/.scr/.vbs 及 *.pdf.exe 形），命中即取消下载 + 暂停 + 入队；接口留好，后续规则只加条目
恶意网站拦截	只有 localhost/私有地址字面量拒绝	恶意网站拦截（Meta 现有系统名单）	静态名单 chv-guest/browser-blocklist.txt（一行一个域名/后缀），导航前检查；名单来源与更新机制见 §2；本轮只做静态名单 + 测试，不冒充实时情报

2. 改了什么（本轨交付物）

• chv-guest/chv_browser_guard.py（新，纯标准库，无 Playwright）： 共享纯函数，两脚本共用：validate_url（P2 规则：只 http/https、 拒 localhost/私有地址字面量）、check_blocklist（读名单文件、 后缀匹配）、truncate_a11y（P2 的截断逻辑原样搬入）、 sanitize_error（错误信息去 HTML、截断 200 字符、凭据形 key=value 与 sk- 形 token 打码、含尖括号即丢弃原文）、 detect_injection（启发式模式表，中英文各 6 条，命中返回标签）、 detect_form_risk（无障碍树扫密码/支付字段）、scan_download （一条可执行扩展名规则）、enqueue_ask/list_asks/resolve_ask （文件型待审批队列，/run/chv/ask-queue/，一条 ask 一个 JSON 文件， pending/allowed/denied 三态）、LAUNCH_ARGS（Chromium 启动参数 白名单）、FORBIDDEN_PAGE_ATTRS（禁用的 Playwright 调用名表）。
• chv-guest/chv-cdp-broker.py（新，标准库 + playwright 懒加载）： 单元外 CDP broker，用户 chv-browser，Unix socket /run/chv/cdp-broker.sock。独家 chromium.launch(headless=True, args=LAUNCH_ARGS)；操作 open/snapshot/screenshot/close/ping/ pause/resume/status/list_asks/resolve_ask；导航前 validate_url + check_blocklist；快照恒带 untrusted_input: true，命中注入模式带 injection_flags；表单风险与 POST 观测、下载命中走 ask 队列 + 自动暂停；所有回包与日志过 sanitize_error，绝不返回 ws 端点。
• chv-guest/chv-browser.py（P2 版基础上改）：不再直连 Playwright， 改为 CDP broker 的客户端（每请求一连接，Unix socket JSON 行）； 保留 validate_url/truncate_a11y 二次校验（纵深防御）、 FORBIDDEN_OPS（扩到 click/fill/type/press/hover/select/check/ evaluate/content/devtools/js/route/expose/add_init_script/ add_script_tag/set_content/eval）、暂停镜像状态（broker 暂停时 本层同样拒绝）；playwright_factory 参数删除（不再需要）。
• chv-guest/browser-blocklist.txt（新）：静态拦截名单。格式一行一个 条目（域名或 .后缀）；来源：随镜像发布的静态文件，首版只含 RFC 2606 保留 .test 域的格式示例与自测条目（malware.test、 .phishing.test），不编造真实恶意域名；生产名单由运维在构建时 用公开情报源（如 URLhaus / Google Safe Browsing 导出）的域名替换 本文件后重建镜像；更新机制 = 换文件 + 重建镜像，无在线更新（在线 更新列为后续，不冒充已做）。
• chv-guest/build.sh：P2 的步骤原样保留，加 P4 步骤：拷入 chv-cdp-broker.py、chv_browser_guard.py、browser-blocklist.txt （缺一即失败）；装 chv-cdp-broker.service（用户 chv-browser） 并 enable；tmpfiles.d 加 /run/chv/ask-queue（0750 chv-browser:chv-browser）。
• chv-guest/buildinfo.py：P2 的内容项原样保留，加 chv-cdp-broker、 chv-browser-guard、browser-blocklist。
• cloud/tests/test_chv_muse_p4.py（新）：见 §5。
• docs/chv-production-readiness.md：补 P4 一节，旧定案不删、只追加。

3. 诚实边界（本轮不宣称的东西）

1. 分类器是确定性规则，不是模型分类器：注入启发式、表单风险、 下载规则都是字面规则，有漏报也有误报；它只做“标注 + 拦截高危”， 不做语义判断。Muse 的浏览器分类器家族是模型 + 规则，本轨只做了 规则那半。
2. a11y-tree-only 的边界与 P2 相同：单元内进程仍可用 curl/Python 标准库直接发 HTTP 取页面原文——那不是“浏览器 DOM 访问”，但也不是 无障碍树；出口只走浏览器子代理是 P3 Sentinel 的事，本轨不冒充已封死。
3. 暂停的触发源不完整：显式 pause 操作与自动暂停（POST 观测、 下载命中）已实现并测试；“用户在浏览器里接管”与“凭证注入填表”这两 个真实触发源还没有对端——前者要等真人浏览器联动（控制面），后者是 P3 的 authd 注入点。接口与状态机已留好，联动列为真机验证。
4. ask 队列的审批人不在本轨：队列是文件型的待审批记录（与 P3 ApprovalQueue 同语义，见 §4），resolve_ask 接受外部写回的 allow/deny；但谁来审批（人、还是 Sentinel 策略）不在本轨决定， P5 做审批 UI 在对话外之后再接。
5. 拦截名单是静态的：首版只有格式示例与自测条目，生产条目须由运维 在构建时填入；名单的覆盖率、误拦率本轮无数据，不宣称“已拦截恶意站”。
6. 性能数字全是待验证目标：CDP broker 多一跳的延迟、快照标注后 的 token 占用、拦截名单加载耗时——本轮无真机验证，一律记入 §5 清单， 不在代码/文档里写成已测得。
7. Chromium 启动参数以 Playwright 1.65 + headless-shell 为准： 白名单参数均为真实 Chromium 开关（--disable-gpu、--no-first-run、 --disable-dev-shm-usage、--disable-extensions、 --disable-background-networking、--disable-sync、 --disable-translate、--mute-audio）；--no-sandbox 刻意不在 白名单内（浏览器以非 root 的 chv-browser 身份跑，不应再降级沙箱； 若客机内启动失败，属真机验证项，不在本轮改参数凑合）。

4. 与 P3/P5/P6 的接口（不碰对方文件，只定契约）

• P4 → P3（ask 队列）：ask 记录格式与 P3 ApprovalQueue 同语义： {ask_id, kind, url, detail, status: pending/allowed/denied, created_at}；kind 本轨有三类：form_submit（高风险表单时导航）、 form_submit_observed（观测到 POST）、download_blocked（下载命中）。 宿主侧 Sentinel 读到 pending 的 ask 后按 P3 的 allow/deny/ask 决策， 经 resolve_ask 写回；allowed 后 broker 解除暂停（form_submit 类还需调用方重发原操作，本轨不自动续跑）。队列的宿主侧读取路径是 host.py 经 SSH 读 /run/chv/ask-queue/（接线设计，P6 或控制面实现， 本轨只留 list_asks 操作与文件格式）。
• P4 → P5（审批 UI）：resolve_ask 的调用方是 P5 的对话外审批 UI； 在此之前 ask 只记录、不自动放行（allowed 缺席即一直停）。
• P4 → P6（确定性安全检查层）：detect_injection 的 untrusted_input: true 标注是 P6 的外部数据标注的浏览器侧来源； P6 复用本轨的模式表时以本文件为准，不另起一份。
• P2 → P4（已兑现）：P2 的 BrowserAgent 直连 Playwright 的结构 已被本轨改成 broker 客户端；P2 测试里假定直连的那一处（见 §0）由 集成者按本表改，不在本轨动 P2 的测试文件。

5. 真机待验证清单（round 12，测试机空闲后）

• lite 验收照旧：qcow2 ≤1GB、冷启动到 SSH、codex 版本、headless-shell 例、Gitea 双向同步。
• 浏览器对齐验收（新增）：
  1. 客机内 chv-cdp-broker 进程以 chv-browser 身份跑，Chromium 正常启动（--no-sandbox 未加时仍能起）；启动参数里无 --remote-debugging-port。
  2. 经 broker browser open https://example.com 返回标题 Example Domain 与无障碍树，响应里无 ws://、无 DevTools 地址、无 HTML。
  3. 单元内进程连不上 CDP 端点（broker 的 socket 只在单元外，单元内 无 Chromium 可连；python3 -c "import playwright" 在单元内仍失败）。
  4. 含密码字段的测试页快照带 form_risk: password；此时 open 导航 返回 ask、页面不跳转；resolve_ask allow 后重发导航成功。
  5. 注入文本测试页快照带 untrusted: true + injection_flags。
  6. 命中拦截名单的域名导航被拒（先用 .test 自测条目，再换生产名单复测）。
  7. 触发下载 .exe 的测试页：下载被取消、代理暂停、ask 入队。
  8. pause 后 open/snapshot 被拒、ping 仍通；resume 后恢复。
  9. 性能记录（只记录、不设门）：broker 多一跳的快照往返、拦截名单加载耗时。
• 集成者须改的一处：P2 测试 test_open_returns_a11y_snapshot_with_fake_playwright 在合入 P4 后失效（BrowserAgent 不再直连 Playwright），改为走假 CDP broker（与 P4 测试的 FakeCdpBroker 同款），断言不变。