dsh-grok-auth

English | 中文

A self-contained DeepSeek Harness Grok Auth plugin. It reuses the xAI OAuth login maintained by the official Grok CLI (~/.grok/auth.json, or $GROK_HOME/auth.json) for:

• the xai LLM route (Grok 4.x models over api.x.ai, paid for by the SuperGrok / X Premium subscription instead of an xai-… API key);
• one native Grok Auth Settings section with login status, best-effort weekly credit usage, and both login flows.

⚠️ Unofficial channel — personal development only. The account-gated subscription surface (auth.x.ai public CLI client, cli-chat-proxy.grok.com billing) is unsupported, revocable, and may be rate-limited or changed without notice. Do not rely on it for production workloads.

Features

Shared Grok Login State

• Uses one Host-only auth coordinator for every authenticated operation.
• Resolves credentials through version-bound auth-file snapshots, a short-lived in-memory cache, and proactive refresh ahead of the ~6-hour token expiry.
• Coalesces concurrent refreshes in-process and uses short cross-process lock sections before and after OAuth network I/O; a reply is persisted only while the refresh-token lineage still matches. The DSH lock lives on a plugin-owned sibling (auth.json.dsh.lock) because the official CLI keeps a persistent lock file of its own at auth.json.lock.
• Tolerates auth-file field aliases across Grok CLI versions (key/access_token, refresh_token/refresh, expires_at/expires) and writes back the spelling the file already uses.
• Sends no token value over the plugin-owned, loopback-only /grok-auth Connection RPC channel.

Two login flows, one authority

• Browser login spawns the official grok login; the CLI owns the whole PKCE flow and writes its own auth file.
• Device-code login runs RFC 8628 against auth.x.ai inside the Host (same public client id the CLI ships) and shows the user code and verification link right on the settings card — no CLI required, works on headless machines. Approved tokens are folded into the CLI's own document.

LLM route

The xai route wraps the installed pi-ai xai catalog provider (https://api.x.ai/v1, OpenAI-compatible protocols). The subscription OAuth access token is injected per request as the Bearer credential — the same construction pi-ai's own xAI subscription login uses. Wire protocols, tool calls, and streaming all remain provider-owned.

Live model discovery

The installed pi-ai catalog is a static snapshot pinned by the harness's pi-ai version, so newly released Grok models are missing until pi-ai upgrades. With liveModels on (the default), the plugin overlays the account's real GET api.x.ai/v1/models listing: chat models the catalog does not ship (grok-4.6, the grok-4.20 family, …) are synthesized from a curated catalog template with live context windows and pricing, and the route re-announces itself when the discovered set changes. Curated entries are never modified, and grok-imagine-* media models are skipped.

Weekly usage

The settings card shows a best-effort weekly credit snapshot from the Grok proxy backend:

GET https://cli-chat-proxy.grok.com/v1/billing?format=credits

A failure of any kind degrades to dashes; it never blocks login or requests.

Requirements

• DeepSeek Harness 0.1.1-rc.1 or a compatible later 0.1.x release.
• Node.js ^22.19.0 or >=24.0.0.
• A SuperGrok / X Premium subscription.
• Either the official grok CLI on PATH (run grok login once), or use the device-code login from the Grok Auth card.

Install a prebuilt release (recommended)

The release package includes prebuilt Host and browser bundles, so no install-time build permission is required:

dsh plugin --profile web add https://github.com/Gyanano/dsh-grok-auth/releases/latest/download/dsh-grok-auth-latest.tgz

To pin a specific version, use its versioned asset from the releases page, e.g. releases/download/v0.1.2/dsh-grok-auth-0.1.2.tgz.

Restart dsh web, open Settings, and select Grok Auth.

Install from GitHub source

dsh plugin --profile web add github:Gyanano/dsh-grok-auth

Git dependencies are built by the package's prepare script, and pnpm 10+ blocks that script until explicitly allowed — so the first run is expected to stop with ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED. (pnpm's own hint mentions onlyBuiltDependencies; dsh reads the allowlist from allowBuilds instead.) Add this to ~/.dsh/profiles/web/pnpm-workspace.yaml:

allowBuilds:
  dsh-grok-auth: true

then run the same command again. Only grant this permission after reviewing the source. For a reproducible install, pin a release tag or commit:

dsh plugin --profile web add github:Gyanano/dsh-grok-auth#v0.1.2

Install a tarball

git clone https://github.com/Gyanano/dsh-grok-auth.git
cd dsh-grok-auth
pnpm install
pnpm pack
dsh plugin --profile web add ./dsh-grok-auth-0.1.2.tgz

Restart dsh web, open Settings, and select Grok Auth.

Host configuration

The bundle patch activates one Host row:

Row	Export	Purpose
llm-grok-auth	dsh-grok-auth	Shared auth coordinator and the xai LLM route

All fields are optional. Set llmEnabled: false to keep the shared Login State coordinator available without owning an LLM route:

Field	Default	Meaning
llmEnabled	true	Register the xai LLM route
authJsonPath	'' → $GROK_HOME/~/.grok/auth.json	Grok auth file
credentialRef	GROK_OAUTH_TOKEN	Value-free reference shown by the card
refreshLeadMs	300000	Refresh lead time in milliseconds (the CLI's own default)
grokCommand	grok	CLI command used for browser login and version probing
displayName	xAI Grok (subscription)	Provider label in model selectors
baseUrl	''	Endpoint override; empty keeps the catalog's api.x.ai/v1
timeoutMs	120000	Request timeout in milliseconds (0 disables it)
liveModels	true	Overlay the installed catalog with the account's live model listing

Do not also add an xai entry under llm-pi-ai.providers; duplicate route ownership is rejected with an explicit diagnostic.

Security and limitations

• Token values never enter the browser, settings, logs, session events, or tool metadata. Only Host-side requests receive authorization headers.
• Status may include the account email and auth mode recorded by the CLI; these are identity/status facts, not credentials.
• Refresh writes preserve unknown fields and atomically replace the auth file with owner-only (0600) permissions.
• The status/login RPC channel is restricted to loopback authorities.
• The official CLI does not participate in the plugin's writer lock; the guarantee is fail-closed recovery (lineage checks, newer-state adoption) rather than absolute cross-client serialization.
• The public OAuth client id belongs to the official Grok CLI; xAI has not promised its long-term availability to third parties.

Development

pnpm install
pnpm run check

pnpm run build emits:

• lib/index.js — Auth / LLM Host plugin;
• lib/invariant.js — invariant companion;
• lib/client.js — loader-compatible browser plugin with inline CSS Modules;
• lib/types/** — declarations.

See the architecture decision.

Acknowledgements

Architecture modelled on dsh-codex-auth; the device-code flow mirrors pi-ai's own xAI OAuth implementation.