dsh-grok-provider 0.1.0

package/docs/03-security-threat-model.md

@@ -0,0 +1,243 @@
+# 安全与威胁模型
+
+## 1. 结论
+
+`0.1.0` 的安全边界建立在两条原则上：
+
+- 登录由 Harness 发起，但认证协议由 xAI 官方 Grok Build CLI 完成。
+- 本插件取得的推理 Bearer token 只在 Host 的凭据读取器和固定 origin transport 之间短暂流动。官方 CLI 的登录网络、代理、托管配置同步与遥测是独立上游边界，不受该 transport 约束。
+
+只有本文所有 P0 门禁和 [测试计划](./05-test-plan.md) 的安全用例通过，才允许发布。
+
+## 2. 信任边界
+
+```text
+Web renderer / TUI
+  │ 闭合 RPC 或 /grok 命令；无 token、URL、path、env
+  ▼
+Host AuthCoordinator
+  ├─ OfficialGrokLoginBridge
+  │    └─ path/version-constrained ~/.grok/bin/grok[.exe] login --oauth
+  │         ├─ 标准配置：系统浏览器与 xAI OAuth
+  │         ├─ 有效配置也可能选择 external helper / devbox / 企业 OIDC
+  │         ├─ CLI 自己的代理、托管配置同步与遥测
+  │         └─ ~/.grok/auth.json
+  ├─ OfficialSessionCredentialSource
+  │    └─ 只读 ~/.grok/auth.json
+  └─ PinnedGrokTransport
+       └─ cli-chat-proxy.grok.com（models / responses / billing?format=credits）
+```
+
+受保护资产：
+
+- access token、refresh token、授权码、state 和 PKCE verifier。
+- 用户提示词、工具定义、工具参数与工具结果。
+- 账号身份、订阅状态和配额。
+- Host 进程、用户文件和 xAI 请求额度。
+- npm 发布身份与供应链完整性。
+
+## 3. 威胁与控制
+
+| 威胁 | 影响 | 控制 | 等级 |
+|---|---|---|---|
+| renderer 把任意命令交给 Host | 本机任意代码执行 | RPC/命令只接受闭合 action；路径和参数完全由 Host 生成 | P0 |
+| PATH 或 workspace 劫持 `grok` | 执行恶意二进制 | 不从 cwd 搜索；优先官方 `~/.grok/bin`；realpath、owner、普通文件与目录包含关系校验 | P0 |
+| 插件参数被 shell 解释 | 任意命令执行 | 只用 Harness `ctx.subprocess`、绝对 argv、固定命令表；插件不显式启动 shell | P0 |
+| CLI 有效配置运行 external auth command | 以当前用户权限执行 `sh -c`/`cmd /C` | 官方 CLI 与 user/system/MDM 配置是显式信任边界；已知环境型覆盖在 spawn 前拒绝；磁盘/MDM 配置不能可靠预判；登录后只接受与绑定生产 OIDC schema 相符的候选；README 披露不能保证端到端无 shell | P0 |
+| 登录进程继承 DSH secrets | 凭据横向泄漏 | 构造最小环境；移除 npm token、DSH credential、API keys 和无关 secret | P0 |
+| 登录 stdout/stderr 含敏感字段 | token 或 OAuth 事务泄漏到 UI/日志 | 不透传原始输出；每流 64 KiB；仅映射闭合状态与稳定错误码 | P0 |
+| 登录进程悬挂或并发 | listener/进程泄漏、凭据竞争 | single-flight、5 分钟超时、AbortSignal、取消、卸载清理 | P0 |
+| 恶意/损坏 auth.json | 内存耗尽、解析攻击、任意文件读取 | 路径不来自 UI；64 KiB；普通文件；拒绝 symlink/reparse；严格 schema | P0 |
+| external/企业/歧义凭据误送固定 xAI Proxy | token 泄漏或账号混淆 | 唯一候选；闭合 auth mode/issuer/scope/client/expiry 关系；schema 不符失败关闭；承认 metadata 未签名 | P0 |
+| token 被发往自定义或重定向 origin | 账号接管 | endpoint ID；固定 HTTPS origin/path；`redirect: "error"` | P0 |
+| Authorization 被继承到远端 URL | 账号接管 | `0.1.0` 无图片下载和任意 URL 请求；transport 不接受 URL | P0 |
+| SSE/压缩响应无限增长 | 内存、CPU、磁盘 DoS | 字节、行、事件、总时长和 idle timeout 双重上限 | P0 |
+| 原始远端错误返回 UI | token、账号或内部信息泄漏 | 只返回插件稳定错误码和安全文案；Harness RPC correlation 留在 carrier 内部 | P0 |
+| billing 响应或 credential metadata 越界进入 renderer | 身份、订阅或凭据泄漏 | Host 严格抽取百分比、周期与模型 capability；拒绝/忽略 identity、balance、history、headers、URL 和原始响应 | P0 |
+| token 到期被误标为额度重置 | 错误产品决策、误导用户 | 重置时间只接受 billing period end；credential `expires_at` 不进入 dashboard DTO | P0 |
+| 凭据轮换期间读到半写文件 | 认证失败或旧 token 重放 | 只接受完整 JSON；短退避重读；不写回；已发送请求不自动重放 | P1 |
+| CLI 更新改变协议或文件格式 | 静默错误 | 登录前后重查 realpath/identity/version；只允许发布时冻结的有限精确版本集合，未知更高/更低版本都失败；CLI 自身更新行为属于 vendor boundary | P1 |
+| 未授权复用官方/第三方 OAuth Client ID | 客户端冒充、封禁或条款违约 | 包中不存在独立 OAuth client；只调用官方 CLI 的公开登录命令 | P0 |
+| 恶意 device-flow URI/code | 用户被引向钓鱼站或 token 被劫持 | discovery 与 device/token/revoke endpoint 全部固定；verification URI 只允许 `https://auth.x.ai` 精确路径；device_code 永不进入 renderer | P0 |
+| 凭据 generation/账号目录混用 | 把请求发到错误账号 | 每次 prepare 冻结 auth generation；catalog、lease、logout、401 都绑定同一 generation；禁止 silent fallback | P0 |
+| npm 依赖安装脚本 | 供应链代码执行 | 目标零 runtime dependencies；全图禁止 lifecycle scripts | P0 |
+
+## 4. 官方 CLI 进程边界
+
+### 可执行文件发现
+
+默认候选：
+
+- macOS：`${HOME}/.grok/bin/grok`
+- Windows：`${USERPROFILE}\\.grok\\bin\\grok.exe`
+
+首版只使用 Host 启动时冻结的绝对 `GROK_HOME`（默认 `${HOME}/.grok`）下 `bin/grok[.exe]`。不支持 `GROK_BIN_DIR`、PATH、workspace 或 UI 指定路径。使用 npm trampoline 的用户必须先在 Terminal/PowerShell 从官方安装入口完成 bootstrap 并执行一次 `grok --version`；插件不下载、安装或更新 CLI。
+
+macOS 官方默认路径可能是 symlink；验证时允许 symlink，但 `realpath` 必须仍位于规范化的 `GROK_HOME` 根内，并指向当前用户拥有的普通可执行文件。Windows 候选必须是普通文件并拒绝 reparse point。路径、owner 和版本检查只能约束候选形状，不能证明 publisher；“用户从 xAI 官方渠道安装”是信任假设，除非 spike 证明可稳定验证签名/notarization/官方哈希。
+
+### 固定命令表
+
+| 用户动作 | 可执行参数 | 说明 |
+|---|---|---|
+| 检查版本 | `--version` | 10 秒、16 KiB 输出上限 |
+| 浏览器登录 | `login --oauth` | 标准配置下官方 CLI 打开浏览器并处理 callback |
+| 退出 | `logout` | 官方 CLI 删除自己的凭据 |
+
+`cancel` 不是一个 CLI 参数，只会中止当前 Host 拥有的登录子进程。
+
+禁止：
+
+- 插件通过 argv 显式启动任何 shell。
+- 固定 `["login", "--oauth"]` 之外的 flags、prompt、cwd 或环境变量。
+- 把授权 URL 从 stdout/stderr 提取后交给通用 opener。
+- 自动下载或更新 Grok CLI。
+- 在登录流程中启动 Grok agent、工具或 workspace 会话。
+
+`--oauth` 只固定 loopback transport，不绕过 external auth、devbox、企业 OIDC、system managed config 或 macOS MDM。插件对已知环境覆盖设置 tombstone，但不能靠环境清理覆盖磁盘/MDM 配置。
+
+子进程环境必须从闭合 allowlist 构造，而不是保留任意用户 PATH：
+
+- macOS PATH 固定为系统目录 `/usr/bin:/bin:/usr/sbin:/sbin`；Windows PATH/PATHEXT/COMSPEC 固定为从已验证 `SystemRoot` 派生的系统目录与扩展集合。
+- 只保留必要 OS home、`SystemRoot`/`WINDIR`、临时目录、locale，以及明确披露的 proxy/CA 变量；proxy/CA 属于用户管理的网络信任边界。
+- 明确移除 `XAI_API_KEY`、`GROK_AUTH_PROVIDER_*`、`GROK_OIDC_*`、`GROK_OAUTH2_*`、`GROK_LOCAL_AUTH`、endpoint/model override、`BROWSER`、`RUST_LOG`、`GROK_LOG_FILE`、`NODE_OPTIONS`、`SSLKEYLOGFILE`、`DYLD_*`、`LD_*`、npm/DSH/API secrets和其他进程行为变量。
+- 精确 allowlist/tombstone 列表在协议 spike 按固定 CLI 版本与两平台冻结；workspace/PATH canary 不得被登录链执行。
+
+官方 loopback 登录可能先清除旧 credential，取消/失败也可能使共享会话失效；成功后 CLI 还可能同步 managed config 或发送其自身已启用的遥测。插件无法撤销这些官方副作用。登录前 UI 必须提示，`logout` 必须经前台用户确认，且会影响所有共享同一 `GROK_HOME` 的应用。
+
+“插件不自动更新”只约束本插件；官方 CLI 自身的更新检查/替换仍属于 vendor boundary。登录前后必须重新解析 executable identity 与版本，若发生变化或落出已测集合，凭据状态失败关闭并要求重新验证兼容性。
+
+### 状态机
+
+```text
+idle ──login──> starting ──spawned──> running
+  ▲               │                     │
+  │               ├─spawn error────────>failed
+  │               └─cancel─────────────>cancelled
+  │                                     │
+  └──────── success + valid auth <──────┤
+                                        ├─timeout──>failed
+                                        └─exit/auth invalid──>failed
+```
+
+登录尝试与当前凭据是两个正交状态。CLI 以成功、非零、取消或超时结算后，都必须先 `waitForExit()`、失效旧 cache 并重新检查 auth 文件；例如“尝试 cancelled，但凭据已在取消前写入并有效”必须如实表示，不能静默启用，也不能谎报未登录。
+
+最小公开状态形状：
+
+```ts
+type PublicAuthStatus = {
+  credential: "missing" | "valid" | "expiring" | "expired" | "unsupported"
+  login:
+    | { state: "idle" }
+    | { state: "starting" }
+    | { state: "running"; sessionId: string }
+    | { state: "settled"; outcome: "succeeded" | "failed" | "cancelled" | "timed-out" }
+  expiryBucket?: "under-5m" | "under-1h" | "later"
+}
+```
+
+认证 DTO 不声称能可靠知道浏览器是否打开，也不包含 process ID、binary path、OAuth URL、stdout/stderr、token、auth 文件内容、email、user ID、team/org、subscription 或 fingerprint。stdin 为 ignored，因此插件不支持手工粘贴 code fallback。
+
+## 5. 凭据文件
+
+- 插件只读 Grok CLI 凭据，不创建第二份落盘副本。
+- 官方 CLI 令牌不写入 settings、DSH credentials、workspace、临时文件或诊断包；插件不创建第二份 token grant。
+- `1.0.5` 的真实 `auth.json` 同时包含 refresh token。Host 对文件的有界读取会短暂接触包含它的原始字节；实现不得缓存、使用、记录或写回 refresh token，解析后只保留闭合校验元数据与短期 access-token lease。该约束缩短暴露窗口但不构成进程级隔离。
+- 文件路径只由 OS home、官方 `GROK_HOME` 约定和 Host 环境解析；UI 不可选择路径。
+- 读取前后检查文件元数据，降低替换竞态；解析失败时不保留部分值。
+- 生产 OIDC schema 候选筛选必须版本化：顶层对象有界且只有一个候选；map key 等于规范化 issuer 与 client ID 组合；`auth_mode === "oidc"`；issuer 精确等于该固定 CLI 版本的 xAI 生产 issuer；scope、client ID、access token 和 `expires_at` 关系闭合。拒绝 external、api_key、web_login、legacy scope、企业 issuer、多候选和未知关键模式。最终字段和值必须在协议 spike 绑定到精确 CLI tag/commit，不能长期依赖 mutable `main`。
+- 上述 metadata 未签名，官方源码也只把 auth mode/issuer 当 provenance/debug hint；它不是密码学 trust assertion。插件在信任官方 CLI 与当前用户凭据目录的前提下做本地失败关闭，真实 bearer 最终由固定 xAI Proxy 服务端验证。
+- access token 只在 Host 内存使用；缓存采用短生命周期并可显式清空。Host 有界读取完整 JSON 时原始 buffer/string 可能瞬时包含 refresh token；解析器不提取、不缓存、不使用、不返回、不记录、不写回该字段，且 JavaScript 内存不承诺可靠清零。
+- 解析 `expires_at` 并使用固定 skew 在发送前拒绝过期/将过期凭据。只有 issuer、client ID、scope 与 schema 全部匹配而时间失效时，才 single-flight 启动固定 `grok models`；OAuth refresh 状态机和文件写回仍由官方 CLI 完成。刷新后必须重新读取并完整校验，只重试一次。
+- 401 立即使 lease 失效并返回 LLM `AUTH`，不自动重放已发出的 POST；下一次明确用户动作才重新读取文件或发起登录。
+- `/grok logout` 或 Web 退出通过官方 `grok logout` 完成，插件不直接 unlink 文件。
+- logout 先推进 auth generation 并中止所有插件推理；完成后清缓存。旧 generation 的完成回调不得重新填入凭据。
+
+## 6. 固定网络策略
+
+本插件拥有并注入凭据的生产 endpoint 闭合集合：
+
+```text
+GET  https://cli-chat-proxy.grok.com/v1/models
+POST https://cli-chat-proxy.grok.com/v1/responses
+```
+
+`chat-completions` 与 `messages` 只有在未来真实目录出现相应 backend、对应 codec 和真机门禁通过后才能进入发布集合；当前不得为“看起来兼容”而启用。
+
+要求：
+
+- `redirect: "error"`，301/302/303/307/308 全部失败。
+- Authorization 只能由 `PinnedGrokTransport` 注入。
+- 不接受 base URL、proxy URL、模型返回 URL或 discovery URL。
+- 不把 token 放进 query string。
+- 每个请求携带 Harness `attributionHeaders()`、`X-XAI-Token-Auth: xai-grok-cli`、发布绑定的 `x-grok-client-version` 与本项目真实 `x-grok-client-identifier`/package identity；不得伪造 `grok-shell`。缺失版本会触发 426，版本变更必须重跑协议门禁。
+- token、headers、完整 URL query、prompt 和原始远端 body 都不进日志。
+- 本限制不覆盖官方 CLI 子进程的 OAuth、企业 IdP、managed-config、代理或遥测网络；这些由官方 CLI 及其有效配置负责并在隐私说明中单独披露。
+
+请求在 `JSON.stringify` 前也必须受限：消息数、单条/总 UTF-8 字节、工具数量、单个/总 schema 字节、schema 深度与 tool-result 大小均有闭合上限。响应必须验证允许的 `Content-Type`。Provider 只产生 Harness tool-call chunks，不自行执行工具或写文件；未在本次请求声明的工具名、厂商 server-tool/search/image 事件全部拒绝。
+
+初始上限：
+
+- auth.json：64 KiB。
+- 消息：最多 512 条；单条 2 MiB；序列化前累计 UTF-8 8 MiB。
+- 工具：最多 128 个；单个 schema 256 KiB；全部 schema 2 MiB；结构深度 64。
+- 单个 tool result：2 MiB。
+- 普通 JSON/错误 body：64 KiB。
+- SSE 单行：256 KiB。
+- SSE 单事件：1 MiB。
+- SSE event：最多 100,000；comment/heartbeat 合计最多 100,000。
+- 单次流累计协议字节：32 MiB。
+- block 与 tool call：分别最多 4,096；单个 tool arguments 1 MiB、累计 8 MiB。
+- 响应 JSON/schema 结构深度：64。
+- 首字节超时：30 秒。
+- idle timeout：120 秒。
+- 绝对时长：30 分钟。
+
+同时检查声明长度和实际解压后流字节，覆盖 chunked、伪造 Content-Length、gzip/brotli 炸弹与无限事件。
+
+## 7. RPC 与命令
+
+Web RPC 只允许：
+
+```ts
+type AuthRpc = {
+  status(input: {}): Promise<AuthOutcome>
+  login(input: {}): Promise<AuthOutcome>
+  cancel(input: { sessionId: string }): Promise<AuthOutcome>
+  logout(input: { phase: "begin" } | { phase: "confirm"; confirmationId: string }): Promise<AuthOutcome>
+}
+```
+
+每个 unary handler 实际再包成 Harness `RpcResult<AuthOutcome>`；业务失败留在成功 value union，只有 rc.2 允许的框架错误进入 error 分支。
+
+- authority 使用 `loopback`，依赖 rc.2 Connection 对 Host/Origin/Sec-Fetch 混淆的 trust fence；它不提供网络层认证，handler 也拿不到 sender、frame 或浏览器 user-gesture 证明。
+- Web 的前台按钮与 logout 二次确认属于防误操作 UX，不是 Host 授权边界。能以当前用户身份直接访问本机 Harness RPC 的恶意进程已能直接运行 `grok logout`/读取用户凭据，属于同一用户权限残余风险。
+- handler 对 endpoint/payload 使用严格 schema；拒绝未知字段。`sessionId`/短期 confirmation ID 只降低误操作与陈旧 UI 重放，不能抵御同用户本地进程。
+- `sessionId` 是随机的不透明 ID，不是 OAuth state 或 process ID。
+- renderer 不能获得 token、URL、文件路径或任意命令能力。
+
+TUI 通过 Harness 的 human-command registry 注册一个全局 `/grok`，只接受 `status|login|cancel|logout` 的闭合语法。命令直接在 Host 执行，不发送给模型；取消使用 invocation 自带的 `AbortSignal`。
+
+## 8. 搜索与图片
+
+`0.1.0` 不注册 Web/X Search、图片生成、图片输入或下载工具。因此：
+
+- 请求体中不存在厂商侧搜索工具。
+- 不存在远端图片 URL 下载逻辑。
+- 不存在模型可控文件路径写入。
+- 不存在把 Bearer token 带到第二个 origin 的功能路径。
+
+未来新增时必须另写 ADR 和威胁模型。
+
+## 9. 残余风险
+
+本项目不承诺防御：
+
+- 已取得当前 OS 用户权限、能替换 `~/.grok` 内容的恶意软件。
+- 被攻陷的官方 Grok CLI、系统浏览器或 xAI 服务。
+- 官方 CLI 或其有效 user/system/MDM 配置运行 external helper、企业 OIDC、managed-config sync、代理或遥测的行为；本插件不能给出端到端无 shell或单一网络 origin 保证。
+- xAI 官方凭据文件本身的 0600/Windows ACL 模型；官方文档建议配合 FileVault 或 BitLocker。
+- 同一用户身份下恶意进程读取官方 token。
+- xAI 服务契约、模型行为、订阅配额或服务条款变化。
+- 当前第一方 token 可能包含 conversation/workspace read-write 等较宽 scope；泄漏影响不只一次聊天。精确 scopes 按发布绑定的 CLI 版本披露。
+
+这些风险必须在 README 和发布说明中披露。

package/docs/04-harness-contract.md

@@ -0,0 +1,325 @@
+# DeepSeek Harness `0.1.1-rc.2` 接口契约
+
+## 1. 目标
+
+插件只使用 Harness 的公开 npm 接口，不读取私有对象、不修改 Harness 源码，也不依赖当前 YukiRyou DeepSeek 工作区的内部实现。
+
+兼容基线：
+
+- DeepSeek Harness：`0.1.1-rc.2`
+- Harness 内置 Node：`24.19.0`
+- 首版发布平台：`darwin-arm64`、`win32-x64`
+
+## 2. Host peer packages
+
+首版预计需要以下版本。脚手架前必须按真实静态 import 图分为 required 与 optional peer：
+
+```json
+{
+  "@deepseek-ai/cordis": "4.0.1",
+  "@deepseek-ai/dsh-llm": "0.1.1-rc.2",
+  "@deepseek-ai/dsh-subprocess": "0.1.1-rc.2",
+  "@deepseek-ai/dsh-settings": "0.1.1-rc.2",
+  "@deepseek-ai/dsh-commands": "0.1.1-rc.2",
+  "@deepseek-ai/dsh-client-connection": "0.1.1-rc.2",
+  "@deepseek-ai/dsh-client-runtime": "0.1.1-rc.2",
+  "@deepseek-ai/dsh-client-locale": "0.1.1-rc.2",
+  "@deepseek-ai/dsh-client-ui-settings": "0.1.1-rc.2",
+  "@deepseek-ai/schemastery": "3.18.1"
+}
+```
+
+初步分组：
+
+- required：`@deepseek-ai/cordis`、`@deepseek-ai/dsh-llm`、`@deepseek-ai/schemastery`。
+- profile-specific optional：subprocess、commands、connection 和 client UI packages。目标桌面 Runtime 必须实际挂载 subprocess service 才能提供官方 CLI 登录；缺失时模型 Provider 仍可读取已有有效官方凭据，但登录/注销动作不可用。
+
+全部放入 `peerDependencies`，optional 项同时声明 `peerDependenciesMeta.<name>.optional: true`。可选 peer 不得被 Host 入口无条件静态 import；需要通过独立 export、条件加载或已证明的 Runtime external 方式隔离。Web、TUI、headless 三种缺失可选 service/peer 的测试必须通过。
+
+这些包由 Harness Runtime 满足，不进入插件普通 dependency 图。版本在脚手架阶段以实际 rc.2 manifest 再核对；不自动放宽到未经测试的 Harness 版本。
+
+目标是零普通 runtime dependencies。登录进程只经过 Runtime 提供的 `ctx.subprocess`；HTTP、流解析、crypto、path 和用户 home 凭据读取使用 Node 24 内建能力。插件不依赖或打包 `@deepseek-ai/dsh-subprocess-local`。
+
+## 3. Cordis 入口
+
+宿主入口形状：
+
+```ts
+export const name = "llm-grok"
+export const inject = ["llm"]
+export const Config = /* Schemastery */
+
+export function apply(ctx, config) {
+  // registration only after services validate
+}
+```
+
+可选服务不能加入强制 `inject`：
+
+- settings 使用可选安装 helper。
+- commands 使用 `ctx.inject(["commands"], ...)`。
+- Web RPC 使用 `ctx.inject(["connection"], ...)`。
+- CLI login/logout 使用 `ctx.inject(["subprocess"], (subprocessCtx) => ...)`；内部只能调用该 child context 的 `subprocessCtx.subprocess`。
+- 无 Web、无 TUI、无 settings 的 headless profile 仍应安全启动 LLM Provider。
+
+所有 registration、listener、timer和 inflight promise 都必须由 Cordis effect disposer 管理。登录 capability 安装在 `ctx.inject(["subprocess"], ...)` 的 child fiber；service 被替换或卸载时，先中止登录，再 `waitForExit()`，随后等待 in-flight settle。
+
+## 4. LLM adapter
+
+实现 `LlmAdapter` 的公开成员：
+
+- `providerInfo`
+- `providerRetryPolicy`
+- `listModels`
+- `resolveModel`
+- `prepareCall`
+- `stream`
+
+注册：
+
+```ts
+ctx.llm.registerAdapter(["grok"], adapter)
+
+ctx.llm.registerConfigurableProviders([{
+  provider: "grok",
+  displayName: "Grok Build",
+  settingsNs: "llm-grok",
+  settingsPath: [],
+}])
+```
+
+`listModels()` 是异步动态目录：使用所选 auth generation 请求固定 `/v1/models`，返回该账号当前全部可见模型。目录是 discovery surface，不是路由白名单；`resolveModel()` 对未缓存的显式模型 ID 可做一次有界刷新，但不得根据 ID 名称猜 capability。
+
+每个 provider HTTP 请求必须包含 `attributionHeaders()`。
+
+### `prepareCall` generation
+
+`prepareCall()` 返回公开 `PreparedAdapterCall` 的精确形状只有 `{ model: LlmResolvedModelInfo, stream }`。adapter 在其 `stream` 闭包内冻结私有 generation，例如：
+
+```ts
+type AdapterGeneration = {
+  resolvedModel: LlmResolvedModelInfo
+  transportContractVersion: 1
+}
+```
+
+retry policy 由 LLM Runtime 与 adapter registration generation 一起绑定，不伪装成 `PreparedAdapterCall` 字段。access token 不写入可序列化 generation；stream 真正发请求前从私有 `HostCredentialSource` 取得一次 lease，并绑定到该次尝试。设置热更新不能改变已经 prepare 的模型和协议；logout/auth generation 可以使尚未发送或在途 lease 失效。直接调用 `stream()` 时，也必须在返回惰性 iterable 前同步捕获 adapter generation。
+
+### 流顺序
+
+本插件对成功响应采用比 rc.2 最低要求更严格的序列：
+
+```text
+block-start
+  text-delta | reasoning-delta | tool-call-delta ...
+block-end
+usage
+finish
+```
+
+- 每个 block chunk 的 `index` 都是非负 safe integer；多个 index 可以交错。同一 index 不可重复 start；delta 只能指向相同 index、相同类型的 open block。
+- `block-start` 携带 `blockType`；`tool-call-delta` 携带稳定 `id`、可选 `name` 与原始 JSON `argumentsDelta`；`block-end.block` 是该 index 的完整组装 block。
+- 成功 finish（`stop|tool-calls|max-tokens`）前所有 block 必须闭合，`usage` 必须且至多出现一次并紧邻 terminal finish。rc.2 本身允许 usage 缺失，但本插件把缺失视为协议失败。
+- `TokenUsage.inputTokens`、`cacheReadTokens`、`cacheWriteTokens` 可同时存在，但各自计数集合不重叠；billed input 是三者之和。
+- 必须有且只有一个 terminal `finish`，之后不得再有 chunk。只有 `error`/`aborted` finish 可按 rc.2 容许未闭合 block，并必须携带 `failure`。
+- provider stop reason 映射为对象 `{kind:"stop"}`、`{kind:"tool-calls"}`、`{kind:"max-tokens"}`，异常/取消映射 `{kind:"error"|"aborted", failure}`。
+- 空成功响应映射为 `EMPTY_RESPONSE`。
+- 截断 SSE、未知事件、重复 finish 和无闭合 tool call 必须失败。
+- AbortSignal 贯穿 fetch、reader、codec 和 adapter iterator。
+- 首版遇到任何 image content block，都必须在发出 HTTP 前以 `UNSUPPORTED_CONTENT` 失败；Provider 不因此依赖 attachment service。
+- 认证缺失或被拒使用 Harness 已识别的 LLM code `AUTH`，不用自造 `AUTH_REQUIRED`。
+
+## 5. TUI `/grok` 命令
+
+使用 `@deepseek-ai/dsh-commands` 的公开 human-command registry：
+
+```ts
+ctx.commands.register({
+  name: "grok",
+  description: "Manage Grok Build authentication",
+  input: { hint: "status|login|cancel|logout" },
+  recordInput: false,
+  handler: async ({ rawInput, signal }) => {
+    // parse closed grammar; call shared Host AuthCoordinator
+    return { kind: "success", text: "<redacted-safe-status>" }
+  },
+})
+```
+
+约束：
+
+- 命令由交互 UI 直接执行，绝不发送给模型。
+- 只接受闭合语法：`status`、`login`、`cancel`、`logout`；额外参数返回 usage。
+- `recordInput: false` 只是不把 `rawInput` 复制进 `command/run.args`；命令名、run/done 生命周期与返回 text 仍会持久化，因此返回文本必须脱敏。
+- parser 必须保留并测试命令名后的原始分隔空白，再按闭合 grammar 决定成功或返回 `{ kind: "error", text: usage }`。
+- `signal` 取消 `login` 等待；不会把授权 URL、token 或原始 CLI 输出写入命令结果。
+- TUI 先调用共享 controller 的 `beginLogin(mode)`，再用 invocation signal 等待该 session；等待被取消时，由本次命令拥有的 session 执行 `cancel()`。Web 只启动并轮询 `status`。每个 auth mode 同时最多一个事务，selection generation 防止两种 token 混用。
+- `/grok logout` 第一次只建立短期 confirmation；在 TTL 内第二次输入同一闭合命令才执行，不新增可携带任意参数的 grammar。
+
+## 6. Web 设置与 RPC
+
+设置 namespace：`llm-grok`。
+
+设置页只存非敏感 UI/功能配置，不存 token、auth 文件路径、binary path 或 base URL。
+
+Host channel 示例：
+
+```ts
+ctx.connection.rpc.handle(
+  "/grok-auth",
+  handler,
+  { authority: "loopback" },
+)
+```
+
+闭合方法：
+
+- `status`
+- `dashboard`
+- `login`
+- `cancel`
+- `logout`
+
+`status`、`login`、`logout` 只接受空对象；`cancel` 只接受当前公开状态中的 `sessionId`。不存在 `authMode`、模式选择、OAuth URL、device code、access/refresh token、identity 或 token endpoint 字段。
+
+`dashboard` 也只接受空对象，并且只在 `status.available === true` 时由页面调用。它返回脱敏模型 capability 和额度摘要；不得返回 credential metadata、用户身份、上游原文、headers 或 endpoint。额度重置时间只能来自 billing period end，不得使用 OAuth credential expiry。
+
+业务状态不能冒充 rc.2 的 `RpcErrorCode`。成功分支承载闭合 outcome：
+
+```ts
+type AuthOutcome =
+  | { kind: "status"; status: PublicAuthStatus }
+  | { kind: "login-started"; status: PublicAuthStatus; sessionId: string }
+  | { kind: "logout-confirmation-required"; confirmationId: string; expiresAt: string }
+  | { kind: "busy"; status: PublicAuthStatus; diagnosticId: string }
+  | { kind: "cli-not-found"; diagnosticId: string }
+  | { kind: "cli-unsupported"; diagnosticId: string }
+  | { kind: "unsupported-auth-config"; diagnosticId: string }
+  | { kind: "auth-required"; diagnosticId: string }
+
+return { ok: true, value: outcome }
+```
+
+RPC error 分支只使用 rc.2 已有且语义匹配的码：schema 失败为 `bad-request` 并填 `details.issues`，调用 signal 中止为 `cancelled`，未分类异常为 `internal`。不得借用 `agent-busy`。Connection 的 correlation ID 留在 carrier 内部，handler/业务 DTO 不把它当可访问字段；`diagnosticId` 是本插件另行生成的随机安全标识。
+
+handler 必须全程 non-throwing：依赖调用、业务逻辑、DTO 校验与 JSON 可序列化检查全部包在边界内；任何未知 throw 都折叠为固定脱敏的 `internal` `RpcResult`。若 throw 逃到 rc.2 carrier，它会变成可能含 `String(error)` 的 HTTP 500，因此属于 P0 实现错误。
+
+## 7. 客户端 bundle
+
+导出 `./client`，构建为 Harness lazy-CJS wrapper：
+
+```js
+window.__ModuleLoader__.load({
+  id: "<package-json-name>",
+  factory: (require) => {
+    var module = { exports: {} }
+    var exports = module.exports
+    // compiled client
+    return module.exports
+  },
+})
+```
+
+bundle ID 必须由最终 `package.json.name` 在构建时注入，不能在包名决策前硬编码；Host/client/patch 三处必须使用同一个精确 ID。
+
+客户端依赖图至少包含：
+
+- `@deepseek-ai/dsh-client-runtime`
+- `@deepseek-ai/dsh-client-ui-settings`
+- `@deepseek-ai/dsh-client-locale`
+- `@deepseek-ai/dsh-client-connection`
+
+最终 `package.json` 至少声明：
+
+```json
+{
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts",
+      "default": "./dist/host/index.js"
+    },
+    "./client": {
+      "types": "./dist/client/index.d.ts",
+      "default": "./dist/client/client.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "grok-provider.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "inject": [
+        "@deepseek-ai/dsh-client-runtime",
+        "@deepseek-ai/dsh-client-ui-settings",
+        "@deepseek-ai/dsh-client-locale",
+        "@deepseek-ai/dsh-client-connection"
+      ]
+    }
+  }
+}
+```
+
+rc.2 的 Host 端 client-module scanner 会执行 `require.resolve("<package>/package.json")` 读取 `dsh.client` 声明，因此 `./package.json` 是 Web bundle 可发现性的必要公开元数据入口；缺失时 Host 插件仍可挂载，但浏览器启动图不会包含该包。
+
+client bundle 导出 Cordis `inject` 与 `apply`，所需 services 至少为 `slots`、`locale`、`connection`。设置页通过 `ctx.slots.inject("settings.section", () => ctx.slots.register(...))` 注册。
+
+三类依赖必须分开：`dsh.client.inject` 只列提供所需 Cordis service 的 client plugin；bundle 动态 `require()` 且不是平台 seed 的 package 列入 `dsh.client.external`；React、UI primitives 等 Runtime 平台 seed 不进入 inject。Host/client 的真实静态和动态 import 图决定 peer 与 external，不能把所有 bundle require 一律塞进 inject。
+
+客户端编译必须证明不能 import Host credential、transport、fs、path、child_process 或 auth JSON parser 模块。
+
+## 8. 认证协调器
+
+公共认证控制与私有凭据源必须在类型边界上拆开，避免 RPC/TUI 即使误用也拿到 token 方法：
+
+```ts
+interface PublicAuthController {
+  status(): Promise<PublicAuthStatus>
+  beginLogin(signal: AbortSignal): Promise<{ sessionId: string; status: PublicAuthStatus }>
+  waitForLogin(sessionId: string, signal: AbortSignal): Promise<PublicAuthStatus>
+  cancel(sessionId: string, signal: AbortSignal): Promise<PublicAuthStatus>
+  beginLogoutConfirmation(): Promise<{ confirmationId: string; expiresAt: string }>
+  confirmLogout(confirmationId: string, signal: AbortSignal): Promise<PublicAuthStatus>
+}
+
+interface HostCredentialSource {
+  acquire(signal: AbortSignal): Promise<HostTokenLease>
+  invalidateRejected(fingerprint: string): void
+}
+```
+
+Web RPC 和 TUI 只获得同一个 `PublicAuthController`；`PinnedGrokTransport` 私有持有 `HostCredentialSource`。二者内部共享一个认证状态核，但没有可互相转换的公开对象。`HostTokenLease` 只能在 Host transport 消费，不可序列化，也不能被 RPC handler 返回。token fingerprint 只使用不可逆、进程内加盐的短摘要，用于缓存失效和测试，不写日志。
+
+`beginLogin()` 只有在受管 CLI 已成功 spawn 后才返回 session；进程随后独立结算并更新共享状态。Web 用 `status` 观察，TUI 用 `waitForLogin` 等待。`cancel` 必须匹配当前 sessionId。logout confirmation 单次使用、短 TTL、绑定当前 auth generation；它是防误操作/陈旧 UI 机制，不是网络认证。
+
+登录事务由 controller 自己的 `AbortController` 所有。RPC request signal 只控制“spawn 并发布 session 之前”的启动阶段；`beginLogin()` 返回后不能再把已结算的 unary request signal 当事务 owner。后台事务只能由匹配的 `cancel(sessionId)`、5 分钟 deadline、subprocess service teardown 或插件 dispose 中止。`PublicAuthStatus` 的 running 分支公开当前不透明 sessionId，因此 `/grok cancel` 可先读 status 后取消，无需用户输入 ID。
+
+## 9. 官方 CLI 边界
+
+Harness rc.2 不提供 HTTPS URL opener，也不需要插件自建 opener：插件通过受管进程 seam 启动官方 `grok login --oauth`，标准配置下由 CLI 自己跨平台打开浏览器。
+
+只使用 `ctx.subprocess.resolveExecutable()` / `ctx.subprocess.spawn()`：
+
+- 经过本插件路径/owner/realpath 检查的绝对 executable path，再交给 seam 验证。
+- 固定完整 argv；seam 不做 shell 解释，插件自身不启动 shell。
+- stdin ignored；stdout/stderr 使用 raw pipe，自行按 UTF-8 原始字节计数，任一超过 64 KiB 就 abort；始终 drain 且不透传原文。collect 模式的截断本身不会终止进程，因此不用于该门禁。
+- 受控 cwd 与过滤环境。
+- single-flight、5 分钟 deadline、AbortSignal、`terminate()`、有界 `waitForExit(teardownSignal)` 与 async dispose cleanup。`waitForExit()` 返回 `false` 时记录脱敏 cleanup failure、让 disposer 有界结算，并把登录 capability 隔离为“需 Host 重启或 subprocess service replacement”；不得自动重新启用或永久卡住卸载。
+- 只承诺 seam 可观察到的受管进程树；官方 CLI 根据可信配置启动并主动脱离该树的后代属于 vendor trust boundary。
+
+不引入 npm `open`，不调用 `host.openPath`，也不把 HTTPS URL 当文件路径处理。
+
+`--oauth` 只固定 loopback transport，不保证绕过 external provider/企业 OIDC，也不保证官方 CLI 内部不用 shell。公开 `SubprocessSpawnSpec` 没有 `windowsHide`；“Windows 不出现额外 console 闪窗”必须在 Gate 1 真实设备验证，失败则阻断发布并向 Harness seam 请求能力，不能绕回 `node:child_process`。
+
+## 10. HMR 与卸载
+
+卸载或热替换后必须：
+
+- 注销 adapter 和 configurable provider。
+- 注销 settings section、RPC handler 和 `/grok` command。
+- 中止所有 fetch 和登录进程。
+- 清空 token 内存缓存。
+- 清理 timer、reader 与 event listener。
+- 等待受控 inflight promise settle，不留下未处理 rejection。
+- 覆盖 Host activate → unload → activate 后只有一个 adapter/RPC/command；client bundle revision 更新后旧 slot、listener、store/controller 全部释放；subprocess service 替换时 child fiber 执行进程终止与有界等待后才卸载，并覆盖 `waitForExit()` 返回 `false` 的路径。