# 对齐 Muse P3 差距表：authd 替身凭证 + Sentinel 式出口审批

依据：`~/workspace/research_notes/meta-muse-ai-architecture-20261101-0755/report.md`
（官方以 Meta security.muse.ai 2026-09-08 为准；第三方拆解只作参考，
逆向细节不得写成官方架构）。Muse 模型一句话：凭证由 VM 内独立服务
authd 保管、代理只见替身令牌；所有连接器动作与网络出口由 Sentinel
唯一审批（allow/deny/ask，L4+L7 评估，SSRF 防护，严格能力绑定）；
审批 UI 不在对话内；连接器执行走 privsep worker，按连接器做凭证白名单。

本轨范围只限 P3：authd 式替身凭证 + Sentinel 式出口审批。
不碰 P1（常驻 VM、WarmPool、气球、vsock）、不碰 P2（客机 nspawn 单元、
浏览器子代理独立）。分支 `feat-chv-muse-p3`（从 `feat-chv-cover100`
分出，基线 HEAD `06c3e17`）。

## 1. 现状 vs Muse

| 项 | 现状（实测/代码为准） | Muse 目标 | 本轨做法 |
|---|---|---|---|
| Gitea token 可见面 | 真 token 经 seed 写进 `/etc/chv/guest-env`（0600 root）；`build_ssh_command` 在每个任务的远程命令前 `source` 该文件，codex 进程环境里直接含真值；`chv-sync boot` 再把它写进 `/home/chv/.git-credentials` 落盘 | authd 保管凭证，代理只见替身令牌；凭证存入运行时单元之外的安全凭证存储，代理不可见；仅在需要时注入 | 真 token 改走 seed 里的独立文件 `/etc/chv/authd-seed`（0600 root），只给客内 authd 守护进程读；guest-env 不再含 GITEA_TOKEN；任务期 `build_ssh_command` 不再把 GITEA_TOKEN source 进 codex 环境；`chv-sync` 经 git credential helper 按次向 authd 取凭证，只进 git 子进程内存，不落盘、不进 agent 环境/argv/日志 |
| authd 位置 | 无 | 存于用户 VM 内（非 Meta 集中基础设施），在运行时单元之外 | 客内 authd 守护进程（`chv-guest/authd.py`，标准库 Unix socket 服务），以 root 身份跑在单元外；宿主侧不存任何 VM 的 token。选客内不选宿主的理由：Muse 的 authd 就在用户 VM 里；宿主侧方案要走 vsock（P1 范围、未就绪），且会把全部 VM 的 token 集中到宿主，违背“存于用户 VM”的口径 |
| 替身令牌 | 无（真值直给） | authd 签发替身令牌，带作用域与有效期 | 两档：① 本期默认——按次释放：每次 git 操作向 authd 取一次凭证，绑定 {连接器=gitea, 主机, 仓库路径, 操作}，单次有效 + 300 秒 TTL，过期即废，释放全程审计（审计里无值）；② 真铸 token：authd 可经 Gitea API 铸短期专用 token（`POST /api/v1/users/{user}/tokens`），默认关闭，见诚实边界第 2 条 |
| 凭证白名单（privsep） | 无连接器概念；`_CHV_SECRET_ENV_NAMES` 只有“密钥/非密钥”二分 | 每个 privsep worker 有明确凭证白名单（日历 worker 不能仅改参数就索取邮件凭证） | authd 只认一个连接器 `gitea`，白名单只含 GITEA_TOKEN；未知连接器/越权主机/仓库/操作一律拒绝；SUB2API_API_KEY 仍走 guest-env（见诚实边界第 3 条） |
| 出口审批 | 只有代码门：preflight 要求代理或显式直连 + `validate_egress_proxy` 格式校验；真正的隔离靠 Tinyproxy 白名单 + 宿主防火墙（第三棒落地中）；客内 root 绕过代理直连在代码层无第二道门 | Sentinel 是连接器动作与全部网络出口的唯一权限机构；L4+L7 评估（主机名、解析后 IP、端口、协议、HTTP 方法、路径、解码后请求）；SSRF 防护；审批是严格能力（绑定连接器/目的地/用例，一次性/会话级/任务级/时限级） | `cloud/chv/sentinel.py` 决策引擎：每动作审批钩子 allow/deny/ask；L4（解析后 IP、端口、协议）+ L7（主机、方法、路径）评估；SSRF 挡截（公开主机名解析到私有/回环/链路本地/CGNAT/保留地址即 deny）；能力绑定 {连接器, 主机, 方法, 路径, 有效期, 次数}；ask 记入待审批队列、执行停止。本期两个接线点：① wake 时 Gitea 出口预审（解析失败/私网 IP/不在白名单 → 起 VMM 前 fail-closed）；② authd 放凭证前先过 Sentinel 评估 |
| 审批 UI | 无 | Sentinel 直接向客户端发审批请求，弹窗在客户端 UI 内，答复直接回 Sentinel；目的：防对话内容伪造审批 | 本期只做设计约束 + 待审批队列（`sentinel.ApprovalQueue`，内存态 pending 记录）：ask 出现即停止执行、记入队列，不自动放行；UI 不在对话内这一条记为约束，不在本期实现任何对话内审批入口 |
| 污点出口（eBPF） | 无 | eBPF cgroup 程序做网络拦截与进程归因、LSM hook 做污点传播 | 列为后续，不冒充已做。见诚实边界第 4 条 |
| 审计 | `_emit` 审计只含 VM 名/路径/URL/kind，不含 key 值（M5） | 审计轨迹展示已做与计划做的事 | 沿用 `_emit` 契约：新增 `sentinel_egress_allow/deny/ask`、`authd_credential_released/refused` 事件，detail 只含连接器/主机/路径/ verdict/原因，不含任何凭证值；authd 客内审计文件 `/var/log/chv-authd.log`（0600）同款口径 |

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

- `cloud/chv/authd.py`（新，叶子模块，标准库）：凭证保险库（只活内存，
  `__repr__` 不含值）+ 按次释放（作用域绑定、单次有效、300 秒 TTL、
  过期即废）+ 连接器白名单（本期只 `gitea`）+ Gitea API 铸 token
  辅助函数（可注入 HTTP 客户端，默认关闭）+ 无值审计记录。
- `cloud/chv/sentinel.py`（新，叶子模块，标准库）：决策引擎
  `evaluate()`（allow/deny/ask）+ L4/L7 评估 + SSRF 挡截
  （解析器可注入，默认 `socket.getaddrinfo`）+ 严格能力
  `Capability`（连接器/主机/方法/路径/有效期/次数绑定）+
  `ApprovalQueue`（ask 待审批队列，内存态）+ 无值审计记录。
- `cloud/chv/hostkeys.py`：`write_seed` 加 `authd_env` 参数——authd
  专用密钥写进独立的客内文件 `/etc/chv/authd-seed`（0600 root），
  不再与 guest-env 混写；`AUTHD_SEED_PATH` 常量。
- `cloud/chv/gitea_sync.py`：`AUTHD_SECRET_KEYS = {"GITEA_TOKEN"}` +
  `split_authd_env()`（把 GITEA_TOKEN 从密钥集里拆出来走 authd 通道）。
- `cloud/chv/ssh_transport.py`：`_CHV_AUTHD_SECRET_NAMES`；`remote_command`
  语义不变（仍只 source guest-env 文件）。
- `cloud/chv/executor.py`：`provision_host_key`/`_provision_seed_disk`
  透传 `authd_env`；新增 `_authd_delivered` 投递集（与
  `_guest_env_delivered` 同锁）——authd 投递的密钥名在
  `build_ssh_command` 里不报错、但不 source 进 codex 环境；
  `_wake_prechecks` 加 Gitea 出口 Sentinel 预审（deny/ask 即
  `sentinel_egress_denied`，起 VMM 前 fail-closed）。
- `cloud/chv/config.py`：`CHV_SENTINEL_ALLOW_HOSTS`（逗号分隔主机名白名单，
  默认只放行配置的 Gitea 主机）。
- `chv-guest/authd.py`（新，标准库守护进程）：读 `/etc/chv/authd-seed`
  持 token 于内存、Unix socket `/run/chv-authd/authd.sock`（0700 目录、
  0600 socket）、SO_PEERCRED 只放行 root 与 chv 用户、每次放凭证前先过
  Sentinel 评估、审计落盘 0600。
- `chv-guest/git-credential-chv-authd`（新，标准库 helper）：git
  credential 协议（stdin 读 `protocol/host/path`，stdout 回用户名/口令），
  口令只进 git 子进程内存。
- `chv-guest/chv-authd.service`（新）：systemd 单元（root 运行，单元外）。
- `chv-guest/chv-sync.sh`：`boot` 在 authd socket 存在时改配
  `credential.helper` 走 authd，不再把真 token 写进
  `.git-credentials`；同时配 `credential.useHttpPath=true`
  （git 默认不把 path 发给 helper，没有 path helper 无法推断
  仓库与操作、每次都拒绝——新测试抓到的真问题）；socket 不存在
  时走旧路径 + stderr 警告（过渡兼容，见诚实边界第 5 条）。
- `cloud/tests/test_chv_muse_p3.py`（新）：替身过期、真 token 泄露面、
  SSRF 挡截、deny/ask 路径、seed 拆分、wake 预审、helper 端到端
  （真 git `credential fill` + 假 authd socket）；全量 cloud 套件全过。
- 镜像集成（只留接入说明，不改 `chv-guest/build.sh`，与 P1 同款规矩，
  合并时由 P2 一并带进镜像）：
  `--copy-in chv-guest/authd.py:/usr/local/bin/`、
  `--copy-in chv-guest/git-credential-chv-authd:/usr/local/bin/`、
  `--copy-in chv-guest/chv-authd.service:/etc/systemd/system/`、
  `--copy-in cloud/chv/authd.py:/usr/local/lib/chv-authd/cloud/chv/`、
  `--copy-in cloud/chv/sentinel.py:/usr/local/lib/chv-authd/cloud/chv/`、
  `--copy-in cloud/__init__.py:/usr/local/lib/chv-authd/cloud/`、
  `--copy-in cloud/chv/__init__.py:/usr/local/lib/chv-authd/cloud/chv/`、
  `--run-command 'chmod +x /usr/local/bin/chv-authd /usr/local/bin/git-credential-chv-authd'`、
  `--run-command 'systemctl enable chv-authd || true'`、
  `99-chv-sync.cfg` 的 runcmd 在 `chv-sync boot` 之前加
  `systemctl start chv-authd || true`。

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

1. **seed 文件仍是 0600 root 落盘**：真 token 在 `/etc/chv/authd-seed`
   里仍以文件形式存在（cloud-init 的唯一投递通道就是写文件），且 seed
   ISO 本身挂在客机上。真正让它对 agent 不可见的是 P2 的 nspawn 单元
   隔离（单元内 root 映射为非特权用户，读不到单元外的 0600 文件）；在
   P2 落地之前、codex 仍以客内 root 跑的镜像上，root agent 理论上仍能
   读到它。本轮堵住的是“进程环境/argv/日志/`.git-credentials` 落盘”
   这条泄露面，不是“客内 root 万能”——后者是 P2 的边界，不是 P3 能修的。
2. **本期默认的“替身”不是 Gitea 侧可独立校验的新 token**：按次释放给
   git 子进程的值仍是真 token，只是只进 git 进程内存、不进 agent。
   真铸 token（Gitea API 铸短期专用 token、到期吊销）已实现辅助函数
   与假客户端测试，但默认关闭——它要求真 token 有建 token 的权限，
   现有测试 token 只有 `write:repository`，铸 token 会失败；开它须另配
   有铸 token 权限的 token，并做真机验证。不得把本期默认写成“Muse 同款
   替身令牌已落地”。
3. **SUB2API_API_KEY 不在本轮**：网关 key 仍走 guest-env 进 codex 环境
   （H2 既有行为）。按 Muse 模型它也该走 privsep worker（由 worker 代
   codex 调网关、codex 不见 key），那是网关调用链改造，超出本轮范围，
   列为后续，不静默声称已覆盖。
4. **eBPF 污点传播未做**：Sentinel 本轮是决策层（wake 预审 + authd 放
   凭证前评估），不是网络层强制。客内任意进程的直连仍由 Tinyproxy
   白名单 + 宿主防火墙（第三棒）兜底；eBPF cgroup 拦截 + LSM 污点传播
   是后续工作，不得写成“出口已全部经 Sentinel”。
5. **过渡兼容已关闭（round-11 真机修复，层 5）**：此前 `chv-sync
   boot` 在 authd socket 不存在时仍走旧的 `.git-credentials` 落盘
   （只多一句 stderr 警告），为的是 lite9/lite10 旧镜像不被一次
   改断。round-11 真机测试证实该回落把 authd 释放的长效 token 写
   进了客内磁盘，修复轮已改为无 socket 即 fail-closed（`die`），
   同时镜像 `/etc/gitconfig` 的 `credential.helper store` 也已删
   除——authd helper 是唯一凭证 helper，且自身绝不落盘。旧镜像
   （lite10 及更早）上 boot 现在会直接失败，须用含 authd 的新
   镜像；真机复测须验证跑完一次完整 Gitea 链后客内
   `~/.git-credentials` 不存在。
6. **无真机验证**：本轮全部是代码 + 本地单测（含真 git helper 端到端，
   但 authd 守护进程本身未在真 VM 里跑过）。真机待验证清单：authd 在
   lite11 镜像里启动时序（须在 `chv-sync boot` 之前就绪）、SO_PEERCRED
   放行 chv 用户、helper 在 pull/push 下的实际表现、wake 预审对真实
   Gitea 主机解析的判定、铸 token 的真实 API 行为。测试机（WSL）须等
   第三棒 V-1～V-9 让出后再做。