dsh-codex-keychain

中文

An unofficial, independent ChatGPT OAuth provider for DeepSeek Harness. It adds the openai-codex model route while keeping the complete OAuth credential in the operating system's native credential store:

• macOS Keychain
• Windows Credential Manager
• Linux Secret Service

There is no OpenAI Platform API key involved, no fallback plaintext credential file, and no reuse of ~/.codex/auth.json.

[!IMPORTANT] ChatGPT subscription access and OpenAI Platform API access are different products. This package connects only to the Codex backend made available to eligible ChatGPT accounts. It is not affiliated with or endorsed by OpenAI or DeepSeek.

Status

0.1.0-alpha.1 is a developer preview targeting DeepSeek Harness 0.1.0-rc.6 and @earendil-works/pi-ai 0.82.1.

Install

Install the prebuilt bundle into a DSH profile:

dsh plugin --profile web add dsh-codex-keychain@next
dsh web

Open Settings → OpenAI Codex, choose Sign in with browser, then click Open authorization page and finish the OpenAI authorization. The plugin deliberately does not change the default model; select an openai-codex model from DSH's model picker after signing in.

For headless hosts or when the localhost callback cannot bind:

dsh plugin --profile web exec dsh-codex-keychain login --device-code

CLI

dsh plugin --profile web exec dsh-codex-keychain login
dsh plugin --profile web exec dsh-codex-keychain login --device-code
dsh plugin --profile web exec dsh-codex-keychain status
dsh plugin --profile web exec dsh-codex-keychain status --json
dsh plugin --profile web exec dsh-codex-keychain logout

status --json contains only the sign-in state, provider, platform, backend, and—on failure—a stable code and safe message. It never includes tokens, account IDs, or token timestamps.

Security model

The plugin stores a versioned manifest and bounded Base64 chunks entirely as native credential items. The service is io.github.CpfPatrick.dsh-codex-keychain; its root account is a SHA-256 digest of the normalized DSH_HOME, and chunk accounts are derived from that digest. Different Harness homes therefore do not share rotating refresh tokens. Two fixed chunk banks keep updates crash-safe: a new bank is written and verified before the small manifest is switched, then the retired bank is cleared. The bounded items also stay below Windows Credential Manager's per-item limit.

Token refresh and logout use a non-secret cross-process lock under $DSH_HOME/.locks. A refresh failure preserves the previous credential for a later retry or explicit re-login. If the native credential store is missing, locked, or unavailable, the plugin reports KEYCHAIN_UNAVAILABLE and refuses to sign in—there is no silent file fallback.

Web authentication RPC is loopback-only. A remote DSH browser must run the CLI on the DSH host. OAuth URLs and device codes are transient; the plugin does not write them to application logs or persistent storage. The CLI displays them when required for login, so do not share or capture that terminal output.

See SECURITY.md for reporting and operational guidance.

Troubleshooting

• KEYCHAIN_UNAVAILABLE on macOS: unlock the login keychain and allow the terminal or DSH process to use it. The plugin stays loaded but refuses model requests until secure storage works.
• KEYCHAIN_UNAVAILABLE on Windows: make sure Windows Credential Manager is available for the current user and that DSH is not running under a different service account.
• KEYCHAIN_UNAVAILABLE on Linux: run DSH inside a desktop or server session with a Secret Service provider, such as GNOME Keyring or KWallet, and a working D-Bus session. The plugin never substitutes a file backend or the Linux kernel keyring.
• Browser callback cannot bind: the browser flow uses localhost port 1455. Stop the process occupying that port, use device-code login, or paste the callback response when the CLI or settings page asks for it.
• Another login is already running: one OAuth flow is allowed at a time across DSH and CLI processes. Finish or cancel that flow, then retry.
• A process crashed while holding a lock: first confirm that no DSH or dsh-codex-keychain process for this DSH_HOME is still running. Only then, remove the orphaned $DSH_HOME/.locks/dsh-codex-keychain-openai-codex.lock and/or $DSH_HOME/.locks/dsh-codex-keychain-openai-codex-login.lock. Never remove a live process's lock.
• Duplicate openai-codex provider: disable the other Codex/OAuth provider plugin and restart DSH. Two adapters cannot own the same model route.
• Refresh or authorization failed: run login again. A failed refresh or incomplete login does not replace the previously stored credential.
• After a DSH upgrade: this alpha is pinned to DSH 0.1.0-rc.6; wait for a compatibility update or test the newer Developer Preview in an isolated profile before upgrading a working profile.

Remote browsers cannot call the authentication RPC. Run the CLI command on the DSH host instead. To remove the native credential before uninstalling:

dsh plugin --profile web exec dsh-codex-keychain logout
dsh plugin --profile web remove dsh-codex-keychain

Supported scope

The alpha includes:

• browser and device-code ChatGPT OAuth
• automatic locked token refresh
• the Codex model catalog and DSH model-picker integration
• DSH-native streaming, reasoning, tool calls, replay, and existing DSH image attachments/model vision
• a dedicated Web settings page and a headless CLI

It intentionally does not include quota displays, web search, a standalone image-viewing UI, or image generation.

Known alpha limitation: DSH 0.1.0-rc.6 resolves adapter authentication before it creates the per-stream cancellation signal and idle watchdog. Normal model streaming remains cancellable, but a network-stalled token refresh cannot be cancelled by the current request. Do not remove a live process's writer lock; stop that process first if recovery is required.

Development

Requirements: Node.js ^22.19 || >=24 and pnpm 11.7.0.

pnpm install
pnpm check
node scripts/native-keyring-smoke.mjs

The native smoke script sends a disposable OAuth-shaped document larger than 4 KiB through the production chunk store, verifies it, and deletes every item in finally. Unit tests use an injected in-memory driver and never touch the developer's real keychain.

Acknowledgements and clean-room boundary

The DSH community already has OAuth plugins, including Yan-Zero/dsh-codex. This repository was implemented independently against the public DSH and pi-ai interfaces; it does not copy that project's source. The narrow differentiator here is strict, cross-platform native credential storage with no ordinary-file fallback.

License

MIT