# dsh-llm-chatgpt-oauth

Use a ChatGPT Plus/Pro subscription as a DeepSeek Harness model provider through pi-ai's `openai-codex` OAuth route—without an OpenAI API key.

> This package registers the **OpenAI Codex** model catalog exposed through ChatGPT OAuth. It does not turn the public `api.openai.com` route into subscription access, and it does not scrape browser sessions.
>
> This is an independent community project, not an official OpenAI, DeepSeek, or pi-ai package. OpenAI, ChatGPT, and Codex are trademarks of their respective owners.

## What it provides

- DeepSeek Harness provider route: `openai-codex`
- ChatGPT OAuth authentication through `chatgpt.com/backend-api`
- No `OPENAI_API_KEY`
- pi-ai's current Codex model catalog (for example `gpt-5.4`, `gpt-5.5`, and compatible `gpt-5.6-*` models)
- Existing Harness message conversion, tool calling, reasoning levels, replay metadata, attachments, and stream translation through `PiAiAdapter`
- Automatic OAuth access-token refresh
- Private, atomic credential persistence
- Optional bootstrap from an existing Codex CLI login
- A dedicated device-code login command
- An active **OpenAI Codex (ChatGPT)** provider row in DSH's Models settings page
- Live, settings-backed updates for operational options; custom headers are redacted on settings wires

Model availability and usage limits are controlled by the ChatGPT account and may change independently of this connector.

## Requirements

- Node.js `>=22.19.0`
- `pnpm` on `PATH` (used by `dsh plugin add`)
- DeepSeek Harness compatible with `@deepseek-ai/dsh-llm-pi-ai@0.1.0-rc.7`
- `@earendil-works/pi-ai@0.82.1`
- A ChatGPT account with access to OpenAI Codex models

The connector intentionally extends a private-by-convention `PiAiAdapter.current()` construction seam so it can inject pi-ai's OAuth credential store. Its Harness and pi-ai peer versions are therefore pinned exactly; upgrade those pins only after the full suite and opt-in live test pass against the new versions.

## Install & wire (one command)

For an immutable install, use the release commit SHA shown in the GitHub release notes:

```bash
dsh plugin --profile web add 'github:zhangxiubo/dsh-llm-chatgpt-oauth#<release-commit-sha>'
```

A version tag is a more readable alternative:

```bash
dsh plugin --profile web add 'github:zhangxiubo/dsh-llm-chatgpt-oauth#v0.1.0'
```

The connector is a DSH **bundle**, so either command installs the Git dependency and appends its declared `dsh.bundle.patch` to the profile's bundle stack—no manual `cordis.patch.yml` edit. Restart `dsh web` afterwards.

The repository ships directly runnable JavaScript and needs no install-time build, `prepare` script, or pnpm `allowBuilds` entry. This follows Harness's [official GitHub plugin-install guidance](https://github.com/deepseek-ai/deepseek-harness/blob/main/docs/user/develop/basic/publish.md#installing-from-github-the-build-script-catch), including its recommendation to pin a commit SHA. To test the latest development branch instead, omit the revision:

```bash
dsh plugin --profile web add github:zhangxiubo/dsh-llm-chatgpt-oauth
```

The package is marked `private` and includes a failing `prepublishOnly` guard to prevent accidental npm-registry publication; GitHub releases are the supported distribution channel.

### Manual fallback

If you manage the profile yourself, install the package where the profile's Cordis loader resolves Node packages, then add one row to `${DSH_HOME:-$HOME/.dsh}/profiles/web/cordis.patch.yml`:

```yaml
- insert:
    - id: llm-chatgpt-oauth
      name: dsh-llm-chatgpt-oauth
```

The important requirement is that `import('dsh-llm-chatgpt-oauth')` resolves from the profile composition.

## Authenticate

### Dedicated OAuth login (recommended)

After installing the package:

```bash
dsh-llm-chatgpt-auth login
```

The command prints an OpenAI device-code URL and code, waits for authorization, and saves a dedicated connector credential. It never prints tokens.

Other commands:

```bash
dsh-llm-chatgpt-auth status
dsh-llm-chatgpt-auth logout
```

The credential is stored at:

```text
${DSH_HOME:-~/.dsh}/llm-chatgpt-oauth/oauth.json
```

### Bootstrap from Codex CLI

By default, when no dedicated credential exists, the connector reads:

```text
${CODEX_HOME:-~/.codex}/auth.json
```

That makes an existing `codex login` immediately usable. Refreshed connector credentials are written to the connector's own file and never overwrite the Codex CLI file.

For independent token lifecycle, use the dedicated login command and disable bootstrap in `${DSH_HOME:-~/.dsh}/settings.yaml`:

```yaml
llm-chatgpt-oauth:
  bootstrapFromCodexCli: false
```

## Select the provider

After the post-install restart, the Models settings page lists **OpenAI Codex (ChatGPT)** as an active provider. Select a concrete model in the composer model picker, or set the default for new agents in `${DSH_HOME:-~/.dsh}/settings.yaml`:

```yaml
agent-default-model:
  provider: openai-codex
  model: gpt-5.4
  reasoningEffort: high
```

The current DSH Models editor has curated forms only for its built-in DeepSeek and pi-ai settings namespaces. This third-party OAuth row is therefore provider visibility/status; use the login CLI for OAuth and the `llm-chatgpt-oauth:` settings section below for advanced connector options.

## Optional plugin configuration

Set connector options in `${DSH_HOME:-~/.dsh}/settings.yaml`; valid changes apply live and refresh both the adapter metadata and Models provider directory:

```yaml
llm-chatgpt-oauth:
  displayName: OpenAI Codex (ChatGPT)
  streamIdleTimeoutMs: 300000
  bootstrapFromCodexCli: true
  # Optional explicit paths:
  # codexAuthFile: /path/to/codex/auth.json
  # credentialFile: /path/to/dsh/oauth.json
  # Optional provider request headers (redacted as secret on settings wires):
  # headers:
  #   X-Custom-Header: value
```

The same fields may be set as the composition base by targeting `llm-chatgpt-oauth` in the profile's `cordis.patch.yml`; settings values override that base. OAuth access and refresh tokens never enter either file. Custom headers are validated, redacted from settings wire responses, and cannot override authorization, cookie, proxy-authorization, or HTTP transport headers.

To disable the route without uninstalling the package:

```yaml
- id: llm-chatgpt-oauth
  disabled: true
```

## Architecture

1. The plugin registers one Harness route, `openai-codex`, plus a configurable-provider directory entry addressed by the `llm-chatgpt-oauth` settings namespace.
2. `CodexOAuthAdapter` subclasses `PiAiAdapter` and builds pi-ai's `Models` collection with an OAuth credential store.
3. Settings changes replace the profile snapshot and the switching credential-store delegate without replacing the active adapter registration.
4. The provider comes from pi-ai's `openaiCodexProvider()` and uses `https://chatgpt.com/backend-api`.
5. pi-ai resolves and refreshes the OAuth credential, then supplies the access token to its Codex Responses transport.
6. The inherited `PiAiAdapter` converts Harness messages to pi-ai context and converts streamed pi-ai events back to Harness chunks.

The connector does not place access or refresh tokens in DSH settings, model configuration, logs, or the Git repository.

## Development

```bash
npm install
npm run verify
```

The ordinary test suite never contacts OpenAI and does not require credentials.

Run the opt-in live test only on an authenticated machine:

```bash
RUN_LIVE_CODEX=1 npm run test:live
```

Choose another model with:

```bash
RUN_LIVE_CODEX=1 CODEX_MODEL=gpt-5.5 npm run test:live
```

Inspect the package payload before creating a GitHub release:

```bash
npm pack --dry-run
```

## GitHub releases

This project is distributed directly from GitHub rather than the npm registry. `package.json` is intentionally marked `private` and carries a registry-publication denial hook; its package name still identifies the Cordis module when pnpm installs the Git dependency.

Canonical repository links are declared in `package.json`. Release maintainers should follow [RELEASING.md](RELEASING.md), publish an annotated version tag, and include its immutable commit SHA in the GitHub release notes.

## Security and limitations

- Never commit `~/.codex/auth.json` or the connector's `oauth.json`.
- Dedicated device-code login is recommended over importing an existing Codex CLI grant.
- The credential store serializes refreshes inside one process; running several connector processes against the same credential file is not currently supported.
- Provider/model access and subscription accounting are controlled by OpenAI.
- This project depends on pi-ai's OpenAI Codex OAuth provider and the current Harness `PiAiAdapter` implementation; upstream changes may require an update.

See [SECURITY.md](SECURITY.md) for reporting guidance.

## License

MIT