dsh-grok-provider 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+## 0.1.0 - Unreleased
+
+- Clean-room Grok Build provider for DeepSeek Harness `0.1.1-rc.2`.
+- Dynamic discovery of every account-visible Responses model.
+- Streaming text, reasoning, encrypted reasoning replay, tools, usage, and finish reasons.
+- Official Grok CLI browser OAuth on macOS arm64 and Windows x64; the CLI owns token persistence.
+- Single authentication path with no embedded OAuth client identity, client secret, or plugin-managed refresh token.
+- Single-flight renewal delegates expired official credentials to the verified Grok CLI `models` command; the plugin never executes an OAuth refresh grant itself.
+- Loopback-only Web settings and a closed `/grok` TUI command surface.
+- Responsive Web account dashboard with live Grok Build billing-period reset data and dynamic model capability cards; complete typed periods recover proto3-omitted zero usage while ambiguous missing percentages remain unknown.
+- Community-oriented Simplified Chinese default `README.md` and English `README.en.md`, plus contribution and private security-reporting guidance; all are included in the npm artifact.
+- Windows x64 code path is included but remains real-device unverified until the documented post-release `0.1.0` validation.
+- Export package metadata for the Harness rc.2 Web client-module scanner and report credential readiness only after validating the official credential source.

package/CONTRIBUTING.md

@@ -0,0 +1,51 @@
+# 贡献指南 / Contributing Guide
+
+感谢你帮助改进 `dsh-grok-provider`。项目优先保证凭据安全、协议准确和跨平台可维护性；小而可验证的变更比同时扩展多个边界的大改动更容易合并。
+
+## 提交问题
+
+提交 Bug 前请先确认问题在受支持版本中可复现，并提供：
+
+- 操作系统与架构；
+- `dsh`、Node.js、Grok CLI 和本插件的精确版本；
+- 最小复现步骤、预期行为与实际行为；
+- 已脱敏的错误码或必要日志片段；
+- 问题发生在 Web、TUI 还是 headless profile。
+
+不要提交 `auth.json`、access/refresh token、`user_id`、邮箱、姓名、完整提示词、工具参数、私人路径或未经检查的诊断包。安全问题遵循 [`SECURITY.md`](SECURITY.md)，不要开公开 Issue。
+
+## 变更流程
+
+1. 阅读 [`docs/README.md`](docs/README.md) 和与改动相关的 ADR。
+2. 先写或更新测试，保持变更范围单一。
+3. 认证、凭据、固定 endpoint、模型协议或发布边界变化时，先更新 ADR、威胁模型和测试计划。
+4. 同步维护 `README.md` 与 `README.en.md` 的用户可见信息。
+5. 运行验证：
+
+```sh
+npm ci --ignore-scripts
+npm test
+npm run pack:check
+```
+
+## Pull Request 检查表
+
+- [ ] 变更解决一个清晰的问题，没有无关重构或格式化噪音；
+- [ ] 新行为有针对性测试，错误路径失败关闭；
+- [ ] 没有新增 token、账号数据、真实响应、机器路径或日志 fixture；
+- [ ] 没有增加普通 runtime dependency；如确有必要，PR 解释原因、体积与供应链影响；
+- [ ] 中英文 README、CHANGELOG 和相关 `docs/` 已同步；
+- [ ] `npm test` 与 `npm run pack:check` 通过；
+- [ ] Windows 专用行为有自动化覆盖，并清楚标注是否完成真机验证。
+
+## 设计原则
+
+- 模型能力来自动态目录，不通过隐藏未知模型制造“全部支持”的假象。
+- Renderer、RPC 与错误信息不接触凭据或身份数据。
+- 只允许固定官方网络目标，拒绝用户配置任意 base URL 和认证重定向。
+- 使用官方 CLI 的登录与持久化，不复制 refresh token 或实现第二套 OAuth 存储。
+- 未知协议和不完整数据保持未知或失败关闭，不猜测安全关键值。
+
+---
+
+English summary: include exact versions, a minimal reproduction, and redacted diagnostics in bug reports. Never post credentials or personal data. Keep PRs focused, add tests first, update design/security documents for boundary changes, keep both READMEs synchronized, and run `npm test` plus `npm run pack:check` before submission.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 YukiRyou
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.en.md

@@ -0,0 +1,200 @@
+# dsh-grok-provider
+
+[简体中文](README.md) | [English](README.en.md)
+
+Use an already authenticated official Grok Build account from DeepSeek Harness, with dynamic model discovery, streaming reasoning, tool calls, and an account quota/model capability dashboard.
+
+> Unofficial community project; not affiliated with xAI or DeepSeek Harness. `0.1.0` has not been published to npm, so the registry installation command below is not available yet. Windows x64 is code-supported, with its first real-device validation scheduled after the initial release.
+
+## What it provides
+
+| Capability | Current implementation |
+| --- | --- |
+| Sign-in | Invokes official `grok login --oauth`; the plugin does not implement an OAuth grant |
+| Credentials | Reuses official CLI session state without creating a second token store |
+| Models | Discovers every model visible to the account at runtime; no static model allowlist |
+| Conversations | Streaming Responses text, reasoning, encrypted reasoning replay, usage, and finish reasons |
+| Tools | Returns function calls to the Harness permission layer; the provider never executes tools |
+| Account dashboard | Login status, weekly/monthly quota, reset time, dynamic model capabilities and reasoning efforts |
+| Surfaces | Bilingual Web settings and a closed `/grok` TUI command set |
+
+## Quick start
+
+### 1. Prerequisites
+
+- DeepSeek Harness `0.1.1-rc.2`
+- Node.js `24.19.0` or newer
+- macOS arm64 or Windows x64
+- Official Grok Build CLI `1.0.5 (5115b46bc909)`
+
+Install the CLI from the [official Grok Build documentation](https://docs.x.ai/build/overview), then verify:
+
+```sh
+grok --version
+grok models
+```
+
+The official CLI opens a browser on first use. The provider supports only the official default `~/.grok` directory (`%USERPROFILE%\.grok` on Windows).
+
+### 2. Install the provider
+
+After `0.1.0` is released, install the exact version:
+
+```sh
+dsh plugin --profile web add dsh-grok-provider@0.1.0
+dsh web
+```
+
+Pre-release acceptance installs only a verified local tarball:
+
+```sh
+dsh plugin --profile web add ./dsh-grok-provider-0.1.0.tgz
+dsh web
+```
+
+### 3. Sign in and select a model
+
+Open **Settings → Grok Build**:
+
+1. Select “Sign in with Grok.”
+2. Complete authorization in the page opened by the official Grok CLI.
+3. Return to Harness and refresh the account dashboard.
+4. Select any account-visible Grok model from the model picker.
+
+The provider does not take over the login page or ask you to paste an access or refresh token.
+
+## User surfaces
+
+The Web settings page shows:
+
+- login state and sign-in, cancel, and logout actions;
+- used/remaining quota and the real billing-period reset time;
+- account-visible models, context windows, reasoning efforts, streaming and tool capabilities.
+
+When protobuf-backed billing includes a complete weekly/monthly period but omits a zero-valued percentage, the page restores “0% used / 100% remaining.” Other incomplete responses remain unknown.
+
+TUI commands:
+
+```text
+/grok status
+/grok login
+/grok cancel
+/grok logout
+```
+
+These commands never enter model context. Logout requires confirmation because it invokes official `grok logout` and affects other clients sharing the same Grok home.
+
+## Update and uninstall
+
+Update after release:
+
+```sh
+dsh plugin --profile web update dsh-grok-provider
+dsh web
+```
+
+Uninstall:
+
+```sh
+dsh plugin --profile web remove dsh-grok-provider
+dsh web
+```
+
+Uninstalling the provider does not remove the official Grok CLI or directly modify/delete `auth.json`.
+
+## Compatibility and scope
+
+| Item | `0.1.0` status |
+| --- | --- |
+| DeepSeek Harness | Exact support for `0.1.1-rc.2` |
+| Node.js | `>=24.19.0` |
+| macOS arm64 | Real-network and isolated Harness acceptance completed |
+| Windows x64 | Code-supported; real-device validation after initial release |
+| macOS x64 / Linux | Unsupported |
+| Grok CLI | Exact support for `1.0.5 (5115b46bc909)` |
+| Models | Every account catalog model whose backend has a strict codec in this release |
+
+The initial release excludes image input, Web/X Search, arbitrary downloads, API-key mode, multiple accounts, enterprise OIDC, ACP, and Headless agent wrapping. See the complete [product requirements](docs/01-product-requirements.md).
+
+## How it works
+
+```text
+Harness UI / TUI
+       │ closed actions and redacted DTOs only
+       ▼
+dsh-grok-provider Host
+       ├── Official Grok CLI: login / models / logout
+       ├── Pinned Models/Billing endpoints: catalog and quota
+       └── Pinned Responses endpoint: streamed inference
+                    │
+                    ▼
+              xAI Grok Build
+```
+
+Model IDs come from the runtime catalog rather than a hardcoded list. If an account exposes a new backend that cannot be mapped safely, discovery fails closed instead of hiding the model and claiming complete support.
+
+## Security and privacy
+
+- Model, catalog, and billing requests allow only compile-time pinned HTTPS origins/paths and reject redirects.
+- Renderer and RPC code never receive tokens, `user_id`, credential paths, arbitrary URLs, or raw upstream responses.
+- The provider does not implement a refresh grant. Near expiry it may invoke one bounded official `grok models`, then reread and revalidate the official credential file.
+- Login subprocesses use fixed argv, a scrubbed environment, output limits, deadlines, cancellation, and no shell.
+- Prompts and tool results are sent to the xAI Grok Build service; the provider itself does not log them.
+
+See the full [threat model](docs/03-security-threat-model.md). For vulnerabilities, read the [security policy](SECURITY.md) and never post tokens, `auth.json`, personal data, or full diagnostic logs in a public issue.
+
+## Troubleshooting
+
+### “Grok CLI not found”
+
+Confirm the official CLI is in its default location and run `grok --version`. The provider will not load an executable from PATH, the workspace, or a UI-selected arbitrary path.
+
+### The page asks you to sign in again
+
+Use the settings button or run `grok login --oauth` in a terminal. If the official CLI has updated to an unverified version, the provider fails closed instead of bypassing version checks.
+
+### A model is missing
+
+Run `grok models` and verify that the same account can see it. The provider returns every valid catalog record; an unknown backend fails discovery rather than being silently filtered.
+
+### Why is quota percentage unknown?
+
+A protobuf-omitted zero is restored only with a complete typed period. In every other case the upstream response lacks enough information, so the provider preserves “unknown.” OAuth token expiry is never shown as a quota reset.
+
+### Does Windows work?
+
+Windows x64 code and automated tests are present, but the first Registry real-device acceptance for `0.1.0` happens after release. Until then it remains “code-supported, real-device unverified.”
+
+## Development
+
+```sh
+npm ci --ignore-scripts
+npm test
+npm run pack:check
+```
+
+The package has zero ordinary runtime dependencies; Harness services are exact peer dependencies. `npm run build` creates disposable `dist/` artifacts. The npm tarball excludes `src/`, tests, spikes, and local evidence.
+
+Project map:
+
+- [`docs/README.md`](docs/README.md): design-document index and current decisions;
+- [`docs/04-harness-contract.md`](docs/04-harness-contract.md): Harness integration contract;
+- [`docs/05-test-plan.md`](docs/05-test-plan.md): platform, security, and release gates;
+- [`docs/09-implementation-status.md`](docs/09-implementation-status.md): implementation and acceptance status;
+- [`CHANGELOG.md`](CHANGELOG.md): version history.
+
+Read the [contributing guide](CONTRIBUTING.md) before filing an issue or PR. Changes to authentication, transport, credential formats, or release boundaries must update the relevant ADR/threat model before implementation and tests.
+
+## Roadmap
+
+- [x] Official CLI browser login, dynamic model catalog, and Responses streaming
+- [x] Web/TUI account controls, quota dashboard, and model capability display
+- [ ] Publish `0.1.0` and verify Registry integrity/provenance
+- [ ] Complete the first Windows x64 real-device acceptance after release
+- [ ] Evaluate additional content types and platforms only against verified Harness/xAI contracts
+
+The roadmap is not a compatibility promise; every new capability must pass the documented design and security gates.
+
+## License
+
+[MIT](LICENSE)

package/README.md

@@ -0,0 +1,200 @@
+# dsh-grok-provider
+
+[简体中文](README.md) | [English](README.en.md)
+
+让 DeepSeek Harness 使用你已登录的官方 Grok Build 账号：动态模型发现、流式推理、工具调用，以及账号额度与模型能力面板。
+
+> 非官方社区项目，与 xAI 或 DeepSeek Harness 官方无隶属关系。`0.1.0` 尚未发布到 npm；请勿把下面的 Registry 安装命令理解为已经可用。Windows x64 已完成代码支持，首次真机验证安排在首版发布后。
+
+## 它解决什么问题
+
+| 能力 | 当前实现 |
+| --- | --- |
+| 登录 | 调用官方 `grok login --oauth` 打开浏览器；插件不实现 OAuth grant |
+| 凭据 | 复用官方 CLI 的登录状态；插件不创建第二份 token 存储 |
+| 模型 | 运行时读取账号可见的全部 Grok Build 模型，不维护静态模型白名单 |
+| 对话 | Responses 流式文本、reasoning、加密 reasoning replay、usage 与 finish reason |
+| 工具 | 将 function call 交回 Harness 权限层；Provider 本身不执行工具 |
+| 账户面板 | 登录状态、每周/月额度、重置时间、动态模型能力与 reasoning 档位 |
+| 界面 | Web 设置页中英文切换；TUI 提供闭合的 `/grok` 命令 |
+
+## 快速开始
+
+### 1. 准备环境
+
+- DeepSeek Harness `0.1.1-rc.2`
+- Node.js `24.19.0` 或更高版本
+- macOS arm64 或 Windows x64
+- 官方 Grok Build CLI `1.0.5 (5115b46bc909)`
+
+请从 [Grok Build 官方文档](https://docs.x.ai/build/overview) 安装 CLI，并先确认：
+
+```sh
+grok --version
+grok models
+```
+
+首次运行 Grok CLI 会打开浏览器登录。插件只支持官方默认的 `~/.grok`（Windows 为 `%USERPROFILE%\.grok`）目录。
+
+### 2. 安装 Provider
+
+`0.1.0` 正式发布后，安装精确版本：
+
+```sh
+dsh plugin --profile web add dsh-grok-provider@0.1.0
+dsh web
+```
+
+发布前验收只安装经过校验的本地 tarball：
+
+```sh
+dsh plugin --profile web add ./dsh-grok-provider-0.1.0.tgz
+dsh web
+```
+
+### 3. 登录并选择模型
+
+打开 **设置 → Grok Build**：
+
+1. 点击“使用 Grok 登录”；
+2. 在官方 Grok CLI 打开的浏览器页面完成授权；
+3. 返回 Harness，刷新账户面板；
+4. 在模型选择器中选择当前账号可见的 Grok 模型。
+
+插件不会接管登录页面，也不会要求粘贴 access token 或 refresh token。
+
+## 使用界面
+
+Web 设置页展示：
+
+- 当前登录状态及登录、取消、退出操作；
+- 已使用/剩余额度和真实周期重置时间；
+- 当前账号可见模型、上下文窗口、reasoning 档位、streaming 与 tool capability。
+
+当 protobuf-backed billing 返回完整的 weekly/monthly 周期但省略零值百分比时，页面会恢复为“已使用 0% / 剩余 100%”；其他不完整响应保持未知，不伪造额度。
+
+TUI 命令：
+
+```text
+/grok status
+/grok login
+/grok cancel
+/grok logout
+```
+
+这些命令不会进入模型上下文。退出操作需要二次确认，因为它会调用官方 `grok logout`，并影响共享同一 Grok home 的其他客户端。
+
+## 更新与卸载
+
+正式发布后更新：
+
+```sh
+dsh plugin --profile web update dsh-grok-provider
+dsh web
+```
+
+卸载：
+
+```sh
+dsh plugin --profile web remove dsh-grok-provider
+dsh web
+```
+
+卸载插件不会删除官方 Grok CLI，也不会直接修改或删除 `auth.json`。
+
+## 兼容性与范围
+
+| 项目 | `0.1.0` 状态 |
+| --- | --- |
+| DeepSeek Harness | 精确支持 `0.1.1-rc.2` |
+| Node.js | `>=24.19.0` |
+| macOS arm64 | 已完成真实网络与隔离 Harness 验收 |
+| Windows x64 | 代码支持；首版发布后真机验证 |
+| macOS x64 / Linux | 不支持 |
+| Grok CLI | 精确支持 `1.0.5 (5115b46bc909)` |
+| 模型 | 当前账号目录中 backend 已被严格 codec 支持的全部模型 |
+
+首版不包含图片输入、Web/X Search、任意文件下载、API Key 模式、多账号、企业 OIDC、ACP 或 Headless agent 封装。完整范围见[产品需求](docs/01-product-requirements.md)。
+
+## 工作原理
+
+```text
+Harness UI / TUI
+       │ 仅发送闭合操作与脱敏 DTO
+       ▼
+dsh-grok-provider Host
+       ├── 官方 Grok CLI：login / models / logout
+       ├── 固定 Models/Billing endpoint：目录与额度
+       └── 固定 Responses endpoint：流式推理
+                    │
+                    ▼
+              xAI Grok Build
+```
+
+模型 ID 来自运行时目录，不是硬编码列表。如果账号出现当前版本无法安全映射的新 backend，发现过程会失败关闭，而不是隐藏模型后宣称“全部支持”。
+
+## 安全与隐私
+
+- 模型、目录和计费请求只允许编译时固定的 HTTPS origin/path，并拒绝重定向。
+- Renderer 和 RPC 不接收 token、`user_id`、凭据路径、任意 URL 或原始上游响应。
+- 插件不实现 refresh grant；凭据临近过期时，只能有界调用一次官方 `grok models`，再重新读取并验证官方文件。
+- 登录子进程使用固定 argv、过滤后的环境、输出上限、deadline 与取消处理，不通过 shell 启动。
+- 提示词和工具结果会发送给 xAI Grok Build 服务；插件本身不把它们写入日志。
+
+完整边界见[威胁模型](docs/03-security-threat-model.md)。发现安全问题时，请阅读[安全策略](SECURITY.md)，不要在公开 Issue 中提交 token、`auth.json`、个人信息或完整诊断日志。
+
+## 常见问题
+
+### 页面显示“找不到 Grok CLI”
+
+确认官方 CLI 位于默认路径，并在终端执行 `grok --version`。插件不会从 PATH、工作区或 UI 指定的任意路径加载可执行文件。
+
+### 页面要求重新登录
+
+在设置页点击登录，或先在终端运行 `grok login --oauth`。如果官方 CLI 已更新到未验证版本，插件会失败关闭，而不是跳过版本检查。
+
+### 没有看到某个模型
+
+先运行 `grok models`，确认该模型对同一账号可见。Provider 动态返回全部合法目录记录；未知 backend 会让发现失败，而不会被静默过滤。
+
+### 为什么额度百分比显示未知
+
+完整类型化周期下缺失的 protobuf 零值会恢复为 0%；其他情况下，上游没有提供足够信息，插件会保留未知。OAuth token 过期时间绝不会冒充额度刷新时间。
+
+### Windows 能用吗
+
+代码和自动测试覆盖 Windows x64，但 `0.1.0` 首次 Registry 真机验收将在发布后完成；在此之前按“代码支持、真机未验证”处理。
+
+## 开发
+
+```sh
+npm ci --ignore-scripts
+npm test
+npm run pack:check
+```
+
+该包没有普通 runtime dependency；Harness services 使用精确 peer dependency。`npm run build` 生成可丢弃的 `dist/`，npm tarball 不包含 `src/`、测试、spike 或本机证据。
+
+项目导航：
+
+- [`docs/README.md`](docs/README.md)：设计文档索引与当前决策；
+- [`docs/04-harness-contract.md`](docs/04-harness-contract.md)：Harness 集成契约；
+- [`docs/05-test-plan.md`](docs/05-test-plan.md)：平台、安全与发行门禁；
+- [`docs/09-implementation-status.md`](docs/09-implementation-status.md)：实现与验收状态；
+- [`CHANGELOG.md`](CHANGELOG.md)：版本变化。
+
+提交 Issue 或 PR 前请阅读[贡献指南](CONTRIBUTING.md)。认证、传输、凭据格式或发布边界的变化必须先更新对应 ADR/威胁模型，再开发和测试。
+
+## 路线图
+
+- [x] 官方 CLI 浏览器登录、动态模型目录和 Responses 流
+- [x] Web/TUI 账户控制、额度面板与模型能力展示
+- [ ] 发布 `0.1.0` 并完成 Registry/provenance 回读
+- [ ] 发布后完成 Windows x64 首次真机验收
+- [ ] 根据已验证的 Harness/xAI 协议逐项评估更多内容类型和平台
+
+路线图不是兼容性承诺；新增能力必须通过文档决策与安全门禁。
+
+## 许可证
+
+[MIT](LICENSE)

package/SECURITY.md

@@ -0,0 +1,35 @@
+# 安全策略 / Security Policy
+
+`dsh-grok-provider` 处理官方 Grok CLI 的本机会话，并把模型请求发送到固定的 xAI Grok Build 服务，因此凭据泄漏、任意 endpoint、重定向、命令执行和解析器绕过都属于高优先级安全问题。
+
+## 支持范围
+
+项目尚处于 `0.1.0` 预发布阶段。正式发布后，仅维护当前发布线中明确列出的 DeepSeek Harness、Node.js、操作系统和 Grok CLI 精确版本；未经验证的版本会失败关闭。
+
+## 私下报告漏洞
+
+请优先使用公开仓库启用后的 GitHub **Private vulnerability reporting**。如果该入口暂不可用，请只创建一个不含技术细节、凭据或个人信息的公开联络 Issue，请维护者提供私下沟通渠道。
+
+报告应包含：
+
+- 受影响的精确版本与平台；
+- 最小复现条件和安全影响；
+- 已脱敏的请求/响应形状或错误码；
+- 建议修复方向（如有）。
+
+绝对不要发送真实 `auth.json`、access/refresh token、`user_id`、Cookie、邮箱、姓名、完整提示词、工具参数或包含这些数据的诊断包。若秘密已暴露，请先通过官方 Grok CLI 注销/重新登录并按相应服务流程撤销凭据。
+
+## 不属于漏洞的情况
+
+- Windows x64 在首次发布前尚未完成真机验证这一已披露状态；
+- 上游未提供额度字段时 UI 显示 unknown；
+- 不受支持的 CLI/Harness/平台版本被明确拒绝；
+- 官方 CLI 或 xAI 服务自身的行为，且无法由本插件边界缓解的问题。
+
+## 披露原则
+
+维护者会先确认报告是否可复现和是否落在本项目边界内，再协调修复与发布。请在修复版本可用前避免公开可直接利用的细节。
+
+---
+
+English summary: use GitHub Private vulnerability reporting when available. If it is unavailable, open only a detail-free contact issue. Never publish or send real credentials, identity data, prompts, tool arguments, cookies, or unreviewed diagnostic archives. Include exact versions, platform, minimal reproduction conditions, impact, and redacted evidence.