Add codex-app-server-byo-auth research topic

codex-app-server-byo-auth/index.md

@@ -0,0 +1,69 @@
+---
+title: Codex App Server — Embeddable Agent Protocol & BYO Auth
+description: Research into the Codex app-server JSON-RPC protocol — threads/turns/streaming, the three auth modes (ChatGPT managed, external tokens, API key), and the BYOK harness pattern for building no-sign-in apps where users bring their own model access (OpenRouter key or ChatGPT/Codex auth).
+status: active
+category: technical
+tags: [codex, app-server, byok, byo-auth, oauth, agent-protocol, json-rpc, harness, chatgpt, openrouter]
+draft: true
+created: 2026-08-10
+updated: 2026-08-10
+origin: buzz://d8a718be-031f-4a6e-9f5c-a55466641654/65b5070a316c48eaa673e0ac8961118c280a26f9cb523c06fcefde74daf503a4
+---
+
+# Codex App Server — Embeddable Agent Protocol & BYO Auth
+
+## Summary
+
+Research into Codex app-server, the open-source JSON-RPC protocol that Codex itself uses to power rich clients (VS Code extension, Desktop). It provides programmatic threads, turns, streamed events, approvals, and conversation history — plus first-class "bring your own ChatGPT" auth in three modes. Goal: understand whether it enables the pattern of an app with an internal harness where users BYOK (API key or ChatGPT/Codex auth) without requiring platform sign-in.
+
+## Research Question
+
+Can codex app-server be used as the model-access layer for an app where users bring their own OpenAI/ChatGPT credentials — as a composable alternative to (or complement of) gmail/github sign-in — and what is the right architecture shape?
+
+## Scope
+
+- Protocol: transports, lifecycle, message schema, core primitives (thread/turn/item)
+- Auth: ChatGPT managed, ChatGPT external tokens, API key, Bedrock
+- BYOK harness pattern: no-sign-in app + user-provided model access
+- Excluded: Codex SDK (CI/headless automation path), model internals
+
+## Key Findings
+
+- **app-server is the sanctioned embedding protocol**: open source (`openai/codex/codex-rs/app-server`), JSON-RPC 2.0, transports stdio (default) / WebSocket (experimental, unsupported for prod) / unix socket / off.
+- **Programmatic surface is complete**: initialize → thread/start|resume|fork → turn/start|steer|interrupt → streamed notifications (item deltas, turn/completed), plus command/exec, process sessions (experimental), review/start, account/read, account/rateLimits/read, account/usage/read. Generates exact TypeScript/JSON-Schema bindings per Codex version.
+- **Three auth modes** (`account/login/start`):
+  1. `chatgpt` / `chatgptDeviceCode` — Codex owns OAuth, persists + auto-refreshes tokens; device-code is the best web flow; user's ChatGPT plan pays for calls
+  2. `chatgptAuthTokens` (experimental) — host app owns the user's ChatGPT auth lifecycle, supplies JWT + accountId + planType, refreshes on 401
+  3. `apiKey` — classic BYOK
+- **"Sign in with ChatGPT" ≠ identity provider**: it is a model-access grant, not an identity layer — no email/profile returned; `chatgptAccountId` is OpenAI-side only. Composable pattern: gmail/github = identity, ChatGPT = optional model capability.
+- **BYOK harness pattern is viable**: no-sign-in app + user-provided key/auth is the standard "agent-as-component with BYOK" shape. The key design decision is *where the key lives*: local app → client-side; hosted web → browser localStorage or your DB (security surface); hosted + device-code → token stays in Codex's credential store (best no-account web option).
+- **Caveats**: WebSocket transport experimental for prod (hosted platform = per-user app-server processes + wss bridge); OpenAI compliance gate (`clientInfo.name` → Compliance Logs Platform; enterprise should contact OpenAI for known-clients list); capacity = user's plan rate limits; gray-area posture (Anthropic banned the Claude equivalent; OpenAI currently tolerates via official protocol).
+
+## Sources
+
+For the full reference list see [[codex-app-server-byo-auth/sources|Sources]].
+
+## Detail Files
+
+- [[codex-app-server-byo-auth/sources|Sources]] — primary docs + community references
+- [[codex-app-server-byo-auth/analysis|Analysis]] — protocol deep-dive, auth modes, BYOK pattern, architecture shapes
+- [[codex-app-server-byo-auth/next-steps|Next Steps]] — build considerations, compliance, open questions
+
+## Related Research
+
+- [[durable-agent-runtime/index|Durable Agent Runtimes & Harness Engineering]] — harness libraries family (nanocodex, Codex, pi); code-as-tool-interface pattern
+- Workspace note: `RESEARCH/CODEX_APP_SERVER.md`
+
+## Discussion
+
+Triggered 2026-08-10 from the #research channel: user asked whether codex app-server can be leveraged so people bring their own ChatGPT OAuth to a platform/app. Follow-up clarified: (1) it's a model-access grant not identity; (2) the BYOK harness pattern (no-sign-in app, user provides OpenRouter key or ChatGPT auth) is exactly the "agent-as-component with BYOK" shape, with the key-location decision being the crux. User approved logging this as a vault topic.
+
+## Next Steps
+
+- [ ] Decide target app shape (local/desktop vs hosted web) before building
+- [ ] If hosted: contact OpenAI for known-clients list / compliance assessment
+- [ ] Prototype device-code flow with a minimal app-server client (Node/TS)
+
+## Conclusion
+
+Codex app-server is a complete embeddable agent protocol with first-class BYO-ChatGPT auth. The BYOK harness pattern (anonymous app + user-provided model access) is viable and maps cleanly onto the user's Effect Layer adapter pattern — one provider interface, multiple implementations (ApiKeyProvider, ChatGptAuthProvider). The main engineering decision is key placement; the main risk is OpenAI's gray-area posture on BYO-ChatGPT.