dsh-grok-build-auth-bridge

Readme

# dsh-grok-build-auth-bridge

Reuse the official [Grok Build](https://github.com/xai-org/grok-build) CLI subscription login in [DeepSeek Harness (DSH)](https://github.com/deepseek-ai/deepseek-harness).

This package is a **Host Cordis bundle**. It reads Grok Build's local session, delegates refresh-token handling to the official `grok` binary, synchronizes only the short-lived access token into DSH's credential service, and provisions a pi-ai route for the Grok Build subscription proxy.

It does not contain, upload, or commit any token.

## Requirements

- Node.js 22.19 or later
- DSH with the `dsh-llm-pi-ai` adapter
- The official Grok Build CLI installed and logged in:

```bash
grok update
grok login
grok models
```

The login must produce `${GROK_HOME:-~/.grok}/auth.json`.

## Install

Run this on each device after logging in with Grok Build:

```bash
npx --yes github:shaomingbo/dsh-grok-build-auth-bridge#v0.1.0
```

The installer adds the package and its Cordis bundle to `~/.dsh/profiles/web/package.json`, then runs `pnpm install`. Restart `dsh web` afterward.

The plugin creates this model route through DSH settings without replacing existing providers:

- Provider: `grok-build`
- Model: `grok-4.6`
- Protocol: OpenAI Responses
- Endpoint: `https://cli-chat-proxy.grok.com/v1`

## How it works

At startup, every ten minutes, and immediately before a `grok-build` LLM stream:

1. read `${GROK_HOME:-~/.grok}/auth.json`;
2. select the first-party xAI OAuth session, excluding plain API-key entries;
3. check `expires_at`, JWT expiry, or Grok's 30-day fallback lifetime;
4. when near expiry, run the official `grok models` command and let Grok perform its own locked, race-safe OAuth refresh;
5. re-read the refreshed session and store only its access token as `GROK_BUILD_ACCESS_TOKEN` in DSH.

Using the official CLI for refresh preserves Grok Build's file-locking, team-principal parameters, refresh-token rotation handling, and sleep/suspend safeguards. The bridge never writes `~/.grok/auth.json` itself.

The route sends the subscription proxy headers required by the official client, including `X-XAI-Token-Auth`, model override, client mode, and the locally installed Grok version from `~/.grok/version.json`.

## Environment overrides

| Variable | Default | Purpose |
| --- | --- | --- |
| `DSH_GROK_AUTH_PATH` | `${GROK_HOME:-~/.grok}/auth.json` | Exact Grok auth file |
| `DSH_GROK_VERSION_PATH` | `${GROK_HOME:-~/.grok}/version.json` | Installed Grok version metadata |
| `DSH_GROK_BIN` | `${GROK_HOME:-~/.grok}/bin/grok` | Official CLI executable |
| `DSH_GROK_AUTH_SCOPE` | auto-detected | Exact auth.json scope for multiple-session files |
| `DSH_GROK_CREDENTIAL_REF` | `GROK_BUILD_ACCESS_TOKEN` | DSH credential reference |
| `DSH_GROK_PROVIDER_ID` | `grok-build` | DSH provider route ID |
| `DSH_GROK_CLIENT_VERSION` | version.json value; fallback `1.0.3` | Proxy version header override |
| `DSH_GROK_REFRESH_MARGIN_MS` | `300000` | Refresh margin before expiry |
| `DSH_GROK_SYNC_INTERVAL_MS` | `600000` | Background synchronization interval |

If you override the provider ID or credential reference after the route has already been created, update or remove the old route in DSH's Models settings.

## Security notes

- `~/.grok/auth.json` contains a refresh token. The bridge refuses to read it on Unix if group or other users have access; use `chmod 600 ~/.grok/auth.json`.
- Only the short-lived access token is copied to `$DSH_HOME/.credentials.yaml` through the normal DSH credential service.
- The plugin never logs credential values or sends the refresh token anywhere.
- If `GROK_BUILD_ACCESS_TOKEN` is exported in the parent environment, it shadows DSH's writable credential store. Unset it before starting DSH.

## Current model scope

The proxy requires `x-grok-model-override` at the provider-header level, while DSH provider headers are shared by every model on that route. Version `0.1.0` therefore exposes one verified route, `grok-4.6`. Additional Grok models can be added as separate provider routes in later releases.

## Development

```bash
npm install
npm test
npm run check
```

The primary-source research behind the bridge is in [`docs/research.md`](docs/research.md).

## License

MIT