dsh-coding-subscription-oauth 0.5.0

package/CHANGELOG.md

@@ -0,0 +1,136 @@
+# Changelog
+
+All notable changes to `dsh-coding-subscription-oauth` are documented here, following the release loop in `docs/00-project-rules.md`. Format: [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). Versioning follows [SemVer](https://semver.org/).
+
+## Unreleased
+
+## v0.5.0 - 2026-08-17
+
+### Added
+
+- Add an opt-in local API gateway (`gateway.enabled`, default off) that binds loopback-only and serves `/healthz`, `/v1/models`, streaming `POST /v1/chat/completions`, `POST /v1/responses`, and `POST /v1/messages` from signed-in subscription sessions.
+- Let Settings copy the OpenAI/Anthropic base URLs and the current Bearer key. Loopback `POST /gateway/reveal` returns the current key without rotating it; rotate stays a confirmed destructive action.
+- Let Settings change the gateway listen port with Apply or Random (18100–18999). The chosen port is stored in the owner-only gateway document and the listener rebinds when it is already running.
+
+### Changed
+
+- Rebuild Settings as four top tabs (Accounts, Gateway, Capabilities, About). Signed-in account cards stay collapsed until expanded, CLI pull preview is full-width, and Imagine status sits on Capabilities.
+
+## v0.4.1 - 2026-08-17
+
+### Added
+
+- Add accessible live numeric controls for `searchResults`, `imageCount`, and video artifact retention (shown as 1–168 hours), using the same compare-and-swap conflict handling as capability switches. Lowering retention rewrites and cleans existing expiries; raising it affects only new artifacts.
+- Add a fast `check:next` Docker development gate (`lint` + `typecheck` + tests) before the full release build gate.
+
+### Changed
+
+- Resolve the Codex search model at call time so sign-in, sign-out, and live catalog changes do not leave a stale model captured by an existing provider.
+- Clarify browser, device-code, and manual redirect/code sign-in guidance; use the profile-aware Antigravity command `dsh plugin --profile web exec dsh-agy login --headless`.
+- Raise the `undici` floor to `^7.24.8` so scoped `socks5://` proxies are supported.
+- Document the first public install path as `dsh plugin --profile web add dsh-coding-subscription-oauth@0.4.1`, matching other DSH plugins.
+
+### Fixed
+
+- Declare image input on the Grok 4.5 and Grok 4.6 baseline descriptors so both fallback and live-derived catalog entries accept image attachments instead of failing locally as unsupported.
+- Resolve subscription requests from the refreshed access token persisted by each OAuth session. This prevents Kimi's header-only `Authorization: Bearer` auth result from being misclassified as “not signed in” merely because it has no `auth.apiKey` field.
+- Treat Kimi Code's HTTP 401 `authentication_error` that says a model `supports only 256K context` as `CONTEXT_WINDOW_EXCEEDED`. The previous AUTH classification invalidated a still-valid token and retried a request that cannot succeed.
+- Strip `user:pass@` from the CLI proxy line, and when a scoped proxy is installed append a `CODING_OAUTH_PROXY` reachability hint to Grok discovery, token, and live-catalog transport errors.
+- Preserve composition capability defaults before Settings is injected and after a Settings service is replaced or disposed; contain asynchronous settings-listener failures; keep empty PATCH writes revision-checked but side-effect free.
+- Make generated media download filenames safe for `Content-Disposition` while preserving opaque DSH attachment ids.
+- Dispose in-flight Grok Imagine API/download work before awaiting media cleanup, isolate caller-owned video-poll cancellation, and remove an artifact if cancellation wins during persistence.
+- Finish Settings disposal even when an injected watch disposer throws, while reporting the contained failure.
+- Reject owner-only or group/world-writable npm package entries and require the packed CLI to remain executable.
+- Close preview-proxy WebSocket halves when either side ends so isolated proxy tests and shutdown cannot hang on leftover upgrade pipes.
+
+### Security
+
+- Require Grok discovery to declare the exact configured issuer identity, pin authorization/token endpoints to its approved origin, refuse redirects, bound discovery/token responses and pasted authorization codes, and redact every repeated opaque credential-shaped diagnostic.
+- Reject unknown, secret-shaped, mistyped, fractional, and out-of-range capability writes instead of silently coercing or clamping caller-authored values.
+- Add a 60-second Codex request ceiling that covers response streaming, plus cancellation-aware stream cleanup; strengthen Imagine request-id, prompt, base64, redirect, MIME, size, and cancellation boundaries.
+
+## v0.4.0 - 2026-08-16
+
+### Added
+
+- Add read-only Settings discovery of allowlisted official Grok / Codex / Kimi / Claude CLI OAuth files, plus an explicit one-way manual Pull: discover → preview → conflict/fingerprint check → overwrite confirmation. Official CLI files are never written.
+- Add default-off live optional capabilities: Codex search, usage/quota, image generation/edit, Fast, and Grok Imagine image/video. Limits: search results 1–20, image count 1–4, artifact TTL 1 hour–7 days. A secret-free `capabilities` composition base is optional; user settings override it.
+- Advertise `codex-oauth-fast` only after a fresh live catalog lists at least one `priority`-eligible model. Requests send `service_tier: priority` and a routing hint. The UI says **Fast requested** and does not guarantee latency or upstream honor.
+- Add opt-in Codex private `chatgpt.com/backend-api` endpoints. Image generation uses the fixed model `gpt-image-2`. Image edit requires current-session top-level attachment ownership.
+- Add Grok Imagine against official `https://api.x.ai` with `grok-imagine-image-2.0` and `grok-imagine-video-1.5`, using a separate DSH credential reference `XAI_API_KEY` (never Grok OAuth, never a process-env fallback).
+- Serve generated outputs on same-origin loopback routes under `/plugins/dsh-grok-build/imagine/*`. Remote downloads apply MIME / size / time / redirect / DNS controls from frozen hosts `imgen.x.ai`, `videogen.x.ai`, and `vidgen.x.ai`. The private artifact store hard-caps both one object and aggregate unique object bytes at 256 MiB, with retention capped at seven days.
+
+### Changed
+
+- Add a tracked multi-stage Docker sandbox for networkless check/verify, generated artifact export, local candidate packaging, and a script-disabled isolated consumer install.
+- Settings CLI synchronization is a manual Pull, not auto-import. Discovery stays automatic and read-only; writing the dsh store still requires preview and an explicit confirm.
+- Capability switches apply live; turning one off withdraws the matching search provider, tools, or Fast route without a restart.
+
+### Fixed
+
+- Bound in-memory Pull preview tickets to one-use, a five-minute TTL, and a process maximum of 32 so credential-bearing preview material cannot accumulate.
+
+### Security
+
+- Harden official CLI reads: reject symlinks, non-regular files, non-owner files, group/other access, and oversized documents; open with `O_NOFOLLOW`; never write the official CLI path.
+- Keep Imagine media on frozen xAI output hosts with DNS pinning and blocked private/loopback addresses; never return a signed upstream URL to the client.
+
+## v0.3.0
+
+### Added
+
+- Add a provider retry policy for the four OAuth routes: transient failures (`RATE_LIMIT`/`SERVER`/`TIMEOUT`/`TRANSPORT`/`EMPTY_RESPONSE`) **and `AUTH`** now retry with exponential backoff (default 2 retries, 500 ms → 10 s, 10% jitter) instead of killing the turn.
+- Add AUTH-failure credential invalidation: when an upstream rejects a locally-valid token with 401/403, the stored credential's expiry is backdated so the retried step refreshes before reuse — recovering the stale-token 401 race without user-visible failure.
+- Add an optional `retryPolicy` plugin config (harness `RetryPolicySchema`) to override the built-in policy per deployment.
+
+### Changed
+
+- Migrate the package toolchain from npm/tsdown to pnpm 11, TypeScript 6, Biome, and an esbuild multi-entry server/client build with declaration emit, promote/verify, and CI. Published package identity, dual CLI, Cordis/HTTP/credential identifiers, and `pi-ai` 0.84.2 stay unchanged.
+- Require Node.js 22.19+ (or 24+) for the TypeScript 6/esbuild release pipeline and runtime bundle.
+- Upgrade `@earendil-works/pi-ai` to `^0.84.2`: OAuth access tokens now refresh proactively five minutes before the stored expiry (previously only at the exact expiry instant, which raced server-side revocation on the Kimi/Codex routes), with a 15 s refresh timeout.
+- Request OAuth access tokens with an explicit minimum remaining validity (60 s); a refresh that returns an even-shorter-lived token hard-fails instead of being handed to a request.
+- Translate a rejected token refresh (revoked refresh token / dead grant) into `MISSING_CREDENTIAL` with a sign-in prompt rather than surfacing a bare upstream 401, and never retry it.
+- Quota exhaustion stays outside the retryable set so a billing-limit response fails fast with its real message instead of the generic "API key is invalid".
+- Expand README (all languages) with a searchable “problems this plugin solves” table covering SuperGrok vs `api.x.ai`, AUTH/`API key is invalid`, `INVALID_REPLAY_STATE`, grok-4.6 `xhigh`, Kimi Bearer vs `x-api-key`, remote device login and China-direct Kimi.
+- Rename the published project to **`dsh-coding-subscription-oauth`**. The old `dsh-grok-build` name only covered the first provider. Cordis id, HTTP `/plugins/dsh-grok-build/*` paths, credential files and the `dsh-grok-build` CLI alias stay compatible.
+
+### Fixed
+
+- Fix the stale-token 401 turn failure (`API key is invalid` banner) observed on the Kimi Code OAuth route when an access token expired mid-session: the turn now refreshes and retries transparently.
+- Expose Grok 4.6 `xhigh` reasoning effort. Live `/models-v2` already returns `reasoning_efforts` including xhigh, but the plugin previously kept only model ids and materialized grok-4.6 from the grok-4.5 template. pi-ai hides xhigh unless that key is an explicit non-null mapping. The catalog now applies live effort lists; the baseline ships grok-4.6 with xhigh while grok-4.5 stays low/medium/high.
+- Invalidate credentials on an `AUTH` finish even when that same finish also carries replay state, then rewrite the replay provider without skipping the refresh path.
+- Bound OAuth JSON request bodies to 64 KiB (400 for malformed JSON, 413 for oversized bodies) and stream the live model catalog through a real 4 MiB ceiling.
+- Contain startup cache/catalog failures and redact token-like material from refresh diagnostics instead of retaining it in user-visible errors or error causes.
+
+## v0.2.0
+
+### Added
+
+- Add unified `/plugins/dsh-grok-build/oauth/*` API across Grok, Codex, Kimi and Claude.
+- Add `codex-oauth`, `kimi-code-oauth` and `claude-code-oauth` routes alongside the preserved Grok Build and native API-key routes.
+- Add the Coding OAuth settings page with per-provider sign-in, model selection and status cards.
+- Add pinned `dsh-agy@0.1.2` integration for Google Antigravity and a safe patch that hides unauthenticated models and labels the provider `(OAuth)`.
+- Add authentication-gated model discovery: unauthenticated OAuth routes expose no models, while authenticated providers are explicitly labelled `(OAuth)`.
+- Add `verify:deployed` and `smoke:deployed` scripts for live-deployment verification.
+- Add plugin-level scoped proxy configuration (`config.proxy`) and Kimi direct-connect default.
+- Add high-contrast settings actions and localized community README translations.
+
+### Fixed
+
+- Fix Kimi OAuth wire authentication so the final request uses `Authorization: Bearer` without an extra Anthropic `x-api-key`.
+- Fix OAuth catalog refresh so listeners cannot make a successful login/logout appear failed, and cleanup failures cannot leave stale models visible.
+- Fix OAuth route replay state so Codex/Kimi assistant messages keep the Harness route provider id and remain replayable across multi-turn conversations.
+- Heal older poisoned OAuth replay metadata at request time and strip replay state when switching between sibling OAuth routes.
+- Make deployment smoke require explicit `DSH_RESTORE_PROVIDER`/`DSH_RESTORE_MODEL`, then restore that default after testing.
+
+### Security
+
+- Store all OAuth credential files as owner-only `0600` with atomic writes and cross-process locks.
+- Keep OAuth tokens out of HTTP status responses, logs and the settings UI.
+- Document disabling the unauthenticated `dsh-agy-web` dashboard on trusted-host deployments.
+
+## v0.1.0
+
+- Initial release: Grok Build device OAuth, `import`, dynamic `/v1/models-v2` catalog and Responses streaming inference.
+- `dsh-grok-build` CLI with login/import/status/logout.
+- Web settings section for Grok Build account.

package/CONTRIBUTING.md

@@ -0,0 +1,109 @@
+# Contributing
+
+Welcome! `dsh-coding-subscription-oauth` is an open-source coding-subscription OAuth plugin for DeepSeek Harness. We appreciate issue reports, questions and pull requests. Read `docs/00-project-rules.md` first — it defines the release loop, versioning, commit/push hygiene and the publish vs local-only document split that every contribution must respect.
+
+## Code of Conduct
+
+- Be respectful and constructive in issues, PRs and reviews.
+- Only ever use coding subscriptions you own. The project does not support bulk accounts, quota resale, remote relay, paywall bypass or client impersonation — see the compliance note in `README.md`.
+
+## Getting started
+
+Development verification for this plugin runs only in an isolated Docker build sandbox; do not run installs, builds, tests, typechecks, linters or package checks directly on a shared developer host. The tracked `Dockerfile` copies the filtered source into the image (never credentials), downloads dependencies in a dedicated stage, then runs project code with `--network=none`. Do not use privileged mode, credential or host-directory bind mounts, or the Docker socket. Tests use no published ports. The narrowly controlled interactive Web preview below is the only port-publishing exception; host networking remains prohibited unless its documented fallback conditions are all met.
+
+```bash
+docker build --target check --build-arg NODE_VERSION=22.19.0 \
+  --resource memory=3g --resource cpu-quota=200000 \
+  --tag test-dsh-coding-oauth:check .
+
+docker build --target verify --build-arg NODE_VERSION=22.19.0 \
+  --resource memory=3g --resource cpu-quota=200000 \
+  --tag test-dsh-coding-oauth:verify .
+```
+
+The `artifacts`, `package`, `inspect`, and `isolated-install` targets cover generated `lib/`, the candidate tarball, release inspection, and a script-disabled consumer install.
+
+### Isolated Web preview
+
+`docker/run-preview.sh` is the only supported interactive preview launcher. It builds `web-preview` offline from two auditable inputs: this checkout's committed `lib/` and a BuildKit named context containing an installed `@deepseek-ai/dsh@0.1.0-rc.6` **program package**. Point `DSH_INSTALL_DIR` at that package directory, never at a DSH home/profile or any credential directory:
+
+```bash
+export DSH_INSTALL_DIR=/path/to/node_modules/@deepseek-ai/dsh
+export DSH_PREVIEW_AUTHORITIES=review-host.example:17800
+./docker/run-preview.sh
+```
+
+The launcher defaults to Docker bridge networking and `0.0.0.0:17800`, checks the allowed high-port ranges, and enforces a non-root user, read-only root filesystem, dropped capabilities, no-new-privileges, CPU/memory/PID limits, isolated named volumes, and tmpfs runtime state. The DSH backend remains on a separate loopback-only high port. It does not mount, modify, restart, or validate against an existing host DSH. If provider endpoints require an outbound proxy, set `DSH_PREVIEW_PROXY` explicitly.
+
+The launcher prints a command for reading the runtime-generated bootstrap token from the container. Append it to the printed local or allowlisted remote URL as `?preview_token=<token>` using a private channel. The proxy exchanges it once for an HttpOnly, SameSite=Strict cookie and redirects to a token-free URL. Treat both the bootstrap URL and the isolated preview volumes as credentials; never paste either into logs, issues, commits, or chat.
+
+Host networking is **not** a normal preview mode. It may be selected only after a minimal container proves ordinary Docker port publishing unavailable and the maintainer explicitly approves that one run. The explicit guard is:
+
+```bash
+DSH_PREVIEW_NETWORK=host \
+DSH_PREVIEW_HOST_NETWORK_CONFIRMED=yes \
+./docker/run-preview.sh
+```
+
+Even then, the launcher permits only the isolated high-port ranges and refuses occupied preview/backend ports. Stop the preview with the exact `docker rm -f <container>` command printed by the launcher. Remove its named volumes only after confirming they contain no OAuth credentials that need to be retained.
+
+This repo also ships a Grok Build CLI (`dsh-coding-oauth`, legacy `dsh-grok-build`), an OAuth settings page, and verification scripts for a live deployment (`verify:deployed` / `smoke:deployed`). Those exercise real providers, so they are meant for maintainer/dev workflows, not for CI.
+
+## Development flow
+
+1. Open an issue describing the change (or link an existing one) so scope is agreed first.
+2. Branch from the default branch. Keep commits atomic and conventional — see **Commits & pushes** below.
+3. When you change a capability or add a doc, update `README.md` (and the community translations added in `docs/00-project-rules.md` §2 if user-facing) and the relevant entries in `docs/` (public layer), **and** add a changelog entry under `Unreleased` in `CHANGELOG.md`.
+4. Build the Docker `check` and `verify` targets until green, then commit that passing slice promptly (do not stack later work on an uncommitted green tree).
+5. Push the branch as a version/milestone checkpoint and open a PR. Describe what changed and how it was verified. Keep the scope of local-only docs (`docs/local/`) out of the PR unless you are a maintainer doing internal investigation.
+
+## Commits & pushes
+
+History is part of the review. The maintainer counterpart — tags, clean-tree releases, changelog folding — lives in `docs/00-project-rules.md` §7.
+
+### Conventional, atomic commits
+
+- Use [Conventional Commits](https://www.conventionalcommits.org/): `type(optional-scope): summary` in the imperative, about 50–72 characters.
+- Types:
+  - `feat:` new capability / route / provider
+  - `fix:` bug fix
+  - `docs:` documentation (publishable layer)
+  - `test:` tests
+  - `refactor:` behaviour-preserving cleanup
+  - `build:` toolchain, packaging, or committed `lib/` artifacts
+  - `ci:` CI workflow
+  - `chore:` process-only (including a release bump)
+- Optional scopes such as `M1` / `M3` or a module name are welcome when they help a reviewer.
+- **One coherent concern per commit.** Do not mix docs, build/toolchain and feature/fix work unless they are inseparable (a new capability that cannot be reviewed without its README/changelog note, or a source change that must ship with the `lib/` it generated).
+- Do not rewrite published history. Amend or squash only on an unpushed local commit.
+
+### Before you commit
+
+- Build the relevant Docker targets (`check`, then `verify`) and wait until green. Do not commit a failing tree.
+- Commit promptly once checks pass — do not leave a finished, verified change sitting uncommitted next to later work.
+- Generated `lib/` is a committed release artifact (git installs + the CI `git diff --exit-code -- lib` drift gate). Rebuild it and include it in the **same** commit as the source or build-script change that produced it. Do not land stale `lib/` against newer `src/`, and do not land a `lib/`-only commit unless the only change is a verified rebuild with no source delta.
+- Never commit secrets, tokens, credentials, private keys, `.env` files, host-specific paths, or local-only notes (`docs/local/`, `reference/`). See `docs/00-project-rules.md` §0.3.
+
+### Pushing
+
+- Push the feature branch as a **checkpoint** at each version or milestone (for example after an M1/M2/M3 slice, or when a version-ready cut is green), not only when the PR is finished.
+- Never force-push (`--force` / `--force-with-lease`) without **explicit maintainer approval**. Default history is append-only, including on your own feature branch once it has been pushed.
+- Open the PR from a pushed checkpoint. Describe what changed and how it was verified.
+
+## Review & merging
+
+- At least one other person's approval is needed to merge.
+- A PR that changes public behaviour must not be merged without its README/changelog updates.
+- Do not force-push `main` or a published release tag. Feature-branch force-pushes still need explicit approval (see above).
+- Maintainers run the release loop (`docs/00-project-rules.md` §3–4 and §7) after merging a substantive change: clean working tree, bump version, annotated tag `v<version>`, publish to npm, and keep the GitHub milestone/release updated.
+
+## Reporting security issues
+
+Do not open a public issue for a credential or account-safety problem. Follow the compliance/safety policy in `README.md`; for anything sensitive, contact a maintainer directly rather than pasting tokens or credentials anywhere.
+
+## Document layers reminder
+
+- **Publishable**: root `README.md` + the community-language READMEs, `INSTALL.md`, `CHANGELOG.md`, `LICENSE`, `NOTICE`, `docs/00-project-rules.md`, `docs/02-architecture.md` + `docs/02-architecture.zh-CN.md`, and other generic `docs/` files. These ship to npm and git — keep them privacy-free.
+- **Local-only**: `docs/local/` and `reference/` are git-ignored and never shipped. Do not reference them from publishable docs.
+
+If you are not sure whether a detail is publishable, keep it in the local-only layer or ask a maintainer.

package/INSTALL.md

@@ -0,0 +1,220 @@
+# 安装与使用 · dsh-coding-subscription-oauth
+
+本仓库原名 **`dsh-grok-build`**。新安装请用：
+
+```bash
+dsh plugin --profile web add github:lninghaha/dsh-coding-subscription-oauth
+```
+
+CLI 新命令是 `dsh-coding-oauth`（旧命令 `dsh-grok-build` 仍可用）。为兼容已有 profile，Cordis id 仍是 `llm-grok-build-oauth`，设置页 HTTP 路径仍是 `/plugins/dsh-grok-build/*`，凭据文件名不变。
+
+第一次公开发布是 **`0.4.1`**。当前推荐 **`0.5.0`**：
+
+```bash
+dsh plugin --profile web add dsh-coding-subscription-oauth@0.5.0
+dsh plugin --profile web update dsh-coding-subscription-oauth
+```
+
+旧 GitHub 地址会解析到同一条 `main`。
+
+## 前置条件
+
+- DeepSeek Harness 0.1.0-rc.6+
+- Node.js 22.19+
+- 需要使用的个人编码订阅；没有 Claude/Google 账号也可以先安装路由
+- 部分网络需要 HTTP/HTTPS 代理
+
+## 安装
+
+```bash
+# 从 GitHub
+dsh plugin --profile web add github:lninghaha/dsh-coding-subscription-oauth
+
+# 或本地开发目录
+dsh plugin --profile web add ./dsh-coding-subscription-oauth
+
+# Google Antigravity 可选依赖，固定版本
+dsh plugin --profile web add dsh-agy@0.1.2
+```
+
+安装后重启现有 dsh web 进程；不要另起一个端口相同的服务器。
+
+本地 API 网关默认关闭。需要时在 profile 里打开（只绑 loopback）：
+
+```yaml
+gateway:
+  enabled: true
+  bind: 127.0.0.1
+  port: 18080
+```
+
+或在 Settings → Coding OAuth → Local API gateway 打开。Bearer key 存在 `$DSH_HOME/.coding-oauth-gateway.json`。不要绑定 `0.0.0.0`。
+
+## Antigravity 安全配置
+
+`dsh-agy@0.1.2` 的 `/agy` standalone dashboard 没有自己的认证，并包含凭据导出接口。Web 服务带 trusted-host 或反向代理时，建议在 profile 最终 `cordis.patch.yml` 禁用该 dashboard：
+
+```yaml
+- id: dsh-agy-web
+  disabled: true
+```
+
+这不会禁用 `agy` LLM route 或 profile 内的 `dsh-agy` CLI。
+
+Google OAuth 后续可用：
+
+```bash
+NODE_USE_ENV_PROXY=1 \
+HTTPS_PROXY=http://127.0.0.1:7890 \
+dsh plugin --profile web exec dsh-agy login --headless
+```
+
+仅在当前网络确实需要代理时设置 `NODE_USE_ENV_PROXY` / `HTTPS_PROXY`；其他环境直接执行最后一行即可。不要把 Google credential export 粘贴到聊天或日志。
+
+## 代理配置
+
+推荐在 profile 的最终 patch 里配置常驻服务：
+
+```yaml
+- id: llm-grok-build-oauth
+  config:
+    proxy: http://127.0.0.1:7890
+    proxyKimi: false
+```
+
+解析优先级：`config.proxy` → `CODING_OAUTH_PROXY` → `GROK_BUILD_PROXY` → `HTTPS_PROXY` / `HTTP_PROXY`。
+
+默认进入代理的域名组：
+
+- xAI/Grok Build
+- OpenAI Codex
+- Claude/Anthropic
+- Google OAuth/Cloud Code
+
+Kimi Code 中国流量默认直连；只有 `proxyKimi: true` 才代理。
+
+## 弹性重试
+
+OAuth access token 会在本地记录过期时间前 5 分钟主动刷新。服务端若仍以 401/403 拒绝一个本地尚未过期的令牌，插件会把凭据 `expires` 回写到过去，重试的 step 先刷新再发请求。瞬时故障（429/5xx/超时/网络）和 AUTH 默认最多重试 2 次（500 ms → 10 s，10% jitter）。配额耗尽和 refresh token 失效不重试。
+
+部署级覆盖（可选）：
+
+```yaml
+- id: llm-grok-build-oauth
+  config:
+    retryPolicy:
+      mode: normal
+      maxRetries: 2
+      retryableCodes: [EMPTY_RESPONSE, RATE_LIMIT, SERVER, TIMEOUT, TRANSPORT, AUTH]
+      backoff: { initialDelayMs: 500, maxDelayMs: 10000, jitterRatio: 0.1 }
+```
+
+## 登录
+
+### 设置页
+
+打开 **设置 → 编码 OAuth**：
+
+- **Grok Build**：授权码或设备码
+- **OpenAI Codex**：远程部署推荐设备码；浏览器 PKCE 支持粘贴 redirect URL
+- **Kimi Code**：设备码
+- **Claude Code**：浏览器 PKCE，远程访问时粘贴完整 localhost redirect URL
+
+设置页会**只读发现**白名单内的官方 Grok / Codex / Kimi / Claude CLI OAuth 文件。同步是显式的单向**拉取**（不是自动导入）：发现 → 预览 → 冲突/指纹核对 → 确认覆盖。官方 CLI 文件从不被写入。读取会拒绝符号链接、非普通文件、非属主文件、组/其他人可读，以及超大文档（`O_NOFOLLOW`）。预览票据一次性、五分钟过期、最多 32 张。CLI 的 `dsh-coding-oauth import` 仍只支持 Grok。
+
+登录过程只交换授权 code；状态接口不返回 access/refresh token。
+
+### 可选能力
+
+设置页的七项订阅能力开关默认全部关闭，打开后立即生效（无需重启）：`codexSearch`、`codexImages`、`codexImageEdits`、`codexUsage`、`codexFast`、`grokImagineImage`、`grokImagineVideo`。
+
+数值控制为 `searchResults`（1–20，默认 5）、`imageCount`（1–4，默认 1）、`videoArtifactTtlMs`（1 小时–7 天，默认 7 天；界面以 1–168 小时显示）。降低视频保留时间会立即缩短并清理已有产物；提高只影响之后生成的产物。管理员可在插件配置的 `capabilities` 下提供不含秘密的 composition 默认值；`coding-subscription-oauth` 设置区中的用户值会覆盖该 base，省略时所有开关仍默认关闭。
+
+`codex-oauth-fast` 仅在最新一次 live catalog 标明至少有一个 `priority` 可用模型后才会出现。请求发送 `service_tier: priority` 和路由提示；界面写 **已请求 Fast**，不保证延迟或上游兑现。Codex 搜索/用量/图像是需打开的私有 `chatgpt.com/backend-api` 端点；图像固定 `gpt-image-2`；编辑只接受当前会话顶层、本会话持有的附件。
+
+Grok Imagine 只走官方 `https://api.x.ai`（`grok-imagine-image-2.0` / `grok-imagine-video-1.5`），凭据是独立的 DSH 引用 `XAI_API_KEY`——不用 Grok OAuth，也不回退进程环境变量。下载受 MIME / 大小 / 超时 / 重定向 / DNS 控制，冻结主机为 `imgen.x.ai`、`videogen.x.ai`、`vidgen.x.ai`；私有产物库的单件与唯一对象总量均硬限 256 MiB、最长七天；只通过同源 loopback 路由提供。
+
+### CLI
+
+```bash
+# Grok（`dsh-grok-build` 仍是同一条命令的别名）
+dsh-coding-oauth login
+dsh-coding-oauth login --pkce
+dsh-coding-oauth import
+
+# Codex / Kimi / Claude
+dsh-coding-oauth login codex --device-auth
+dsh-coding-oauth login codex --browser
+dsh-coding-oauth login kimi
+dsh-coding-oauth login claude
+
+# 状态/登出
+dsh-coding-oauth status all
+dsh-coding-oauth logout kimi
+```
+
+## 模型路由
+
+- `grok-build/<model>`
+- `codex-oauth/<model>`
+- `codex-oauth-fast/<model>`（可选；仅在最新 live catalog 标明 `priority` 可用后出现，界面为 已请求 Fast）
+- `kimi-code-oauth/<model>`
+- `claude-code-oauth/<model>`
+- `agy/<model>`（安装 dsh-agy 后）
+
+这些别名专门避免与已有的 `xai`、`openai`、`kimi-coding` API-key routes 冲突。插件不会修改现有默认模型设置。未认证的 OAuth route 不向模型选择器返回任何模型；认证后供应商名显示为 `(OAuth)`，登录/登出会立即触发目录刷新。
+
+## 凭据与缓存
+
+OAuth 凭据：
+
+```text
+$DSH_HOME/.grok-build-auth.json
+$DSH_HOME/.codex-oauth-auth.json
+$DSH_HOME/.kimi-code-oauth-auth.json
+$DSH_HOME/.claude-code-oauth-auth.json
+```
+
+均为 `0600`、原子写、文件锁保护。模型缓存为对应的 `*-models.json`，不含 token。Grok Imagine 使用 DSH 凭据引用 `XAI_API_KEY`，与上述 OAuth 文件分离；视频产物存入 `$DSH_HOME/.dsh-coding-subscription-oauth-media/`（目录 `0700`、文件 `0600`），按保留设置自动清理。
+
+## 卸载
+
+```bash
+dsh plugin --profile web remove dsh-agy dsh-coding-subscription-oauth
+rm -f ~/.dsh/.grok-build-auth.json ~/.dsh/.codex-oauth-auth.json \
+  ~/.dsh/.kimi-code-oauth-auth.json ~/.dsh/.claude-code-oauth-auth.json
+rm -f ~/.dsh/.grok-build-models.json ~/.dsh/.codex-oauth-models.json \
+  ~/.dsh/.kimi-code-oauth-models.json ~/.dsh/.claude-code-oauth-models.json
+```
+
+只有在确认不再需要账号后才删除凭据文件。
+
+## 部署验收
+
+```bash
+pnpm run verify:deployed
+
+DSH_RESTORE_PROVIDER=openai \
+DSH_RESTORE_MODEL=gpt-5.6-sol \
+DSH_RESTORE_REASONING=max \
+pnpm run smoke:deployed
+```
+
+第一条命令验证真实模型目录的认证门禁和 `(OAuth)` 标签。第二条会通过运行中的 DSH 分别执行 Codex/Kimi 的 tool-call 与第二个用户 turn（覆盖 `INVALID_REPLAY_STATE` 回归），随后恢复显式指定的默认模型并归档测试会话；为避免覆盖现有默认设置，不提供 `DSH_RESTORE_*` 时脚本拒绝运行。
+
+## 故障排查
+
+| 现象 | 处理 |
+|---|---|
+| 还在搜 / 装着 `dsh-grok-build` | 仓库已更名为 `dsh-coding-subscription-oauth`；旧 GitHub 地址仍跟踪同一条 `main`。新安装请用新名 |
+| Codex localhost callback 打不开 | 改用设备码，或把完整 redirect URL 粘贴回设置页 |
+| Claude localhost callback 在远端浏览器 | 把完整 redirect URL 粘贴回设置页 |
+| Kimi 401/403 | 重新登录并确认 Kimi Code 会员有效；不要改成 moonshot.cn OAuth |
+| OAuth refresh failed | 对应账号重新登录；插件不会回退到其他账号或 API key |
+| 模型 route 重复 | 保留本插件的 `*-oauth` alias，移除冲突的第三方 OAuth 插件 |
+| Antigravity 页面 404 | 安全配置默认禁用了 `dsh-agy-web`；使用 CLI |
+| Google/Claude/OpenAI 网络不可达 | 检查插件 scoped proxy；不要重启或修改系统网络服务 |
+
+## 合规提示
+
+订阅 OAuth 接入第三方 harness 可能违反或触及供应商服务条款。仅供个人账号使用，自行承担配额和账号风险；商用请使用官方 API-key 通道。

package/LICENSE

@@ -0,0 +1,19 @@
+Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+Copyright 2026 dsh-xai contributors
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/NOTICE

@@ -0,0 +1,11 @@
+NOTICE
+======
+
+dsh-coding-subscription-oauth (formerly dsh-grok-build) — coding-subscription OAuth for DeepSeek Harness
+Copyright 2026 lninghaha
+
+This product includes software developed by the dsh-xai project
+(https://github.com/MirDie/dsh-xai), licensed under the Apache License,
+Version 2.0. Portions of src/store.ts, src/session.ts, src/grok-import.ts,
+src/redact.ts, src/invariant.ts, src/adapter.ts, src/auth.ts, src/bin.ts and
+the build scaffolding are derived from that work.