@sipi/dsh-openai-codex-auth

Readme

# @sipi/dsh-openai-codex-auth

English | [中文](README.zh.md)

An independently versioned, installable OpenAI Codex device-login plugin for `@deepseek-ai/dsh-llm-pi-ai`. It contributes OAuth storage and the `openai-codex` interactive-auth controller without adding a second model adapter.

## Install

```sh
dsh plugin --profile web add @sipi/dsh-openai-codex-auth
```

The bundle inserts one `openai-codex-auth` configuration row. Remove the same package to unload its controller and credential contribution without changing the base adapter:

```sh
dsh plugin --profile web remove @sipi/dsh-openai-codex-auth
```

The Models page then offers a ChatGPT device-code login. OAuth requests run in the DSH Node process; on Node 24, proxy environment variables require `NODE_USE_ENV_PROXY=1` (or `--use-env-proxy`).

## Configuration

Structured credentials are stored at `$DSH_HOME/.llm-oauth.json`. `path` overrides that file, `dshHome` changes the default home, `lockTimeoutMs` defaults to 30 seconds, `lockStaleMs` to 60 seconds, `loginTimeoutMs` to 16 minutes, and `startupTimeoutMs` to 30 seconds.

```yaml
- id: openai-codex-auth
  name: '@sipi/dsh-openai-codex-auth'
  config:
    dshHome: ~/.dsh
```

The store serializes mutations in process and across processes. A provider generation prevents a login completing after logout from restoring a deleted credential. POSIX files are atomically replaced at mode `0600`; Windows users must protect `DSH_HOME` with their account ACL. Browser RPC state never includes tokens or raw provider responses.

## Extension Role

The plugin claims `openai-codex` in `ctx.piAiCredentials` and registers its controller on `ctx.llm`. `dsh-llm-pi-ai` snapshots that mapping with each `Models` collection, so an active request retains its original store while later requests observe load or unload. A second plugin claiming the provider fails loud.

## Development

The current DSH release has no published pi-ai credential contribution seam. Develop this package beside the SIPI-patched `deepseek-harness` checkout that provides `ctx.piAiCredentials` and `ctx.llm.registerProviderAuth()`. Installing against an unpatched upstream release fails at startup rather than silently losing OAuth persistence. See [compatibility notes](COMPATIBILITY.zh.md).

## Model Experience

### OAuth authentication

#### What the model sees

Nothing. `openai-codex` login state and OAuth credentials stay outside model requests.

#### Token effect

Zero direct token effect.

#### KV Cache effect

Independent of cache identity. The selected `openai-codex` model request determines provider cache behavior.

## Known Limitations and Deferred Work

- **One login method** — only OpenAI's device authorization is exposed.
- **pi-ai catalog dependency** — activation fails when the installed catalog does not expose `openai-codex` OAuth.