docs(prd): add Codex host credentials egress plan
This commit is contained in:
@@ -0,0 +1,169 @@
|
|||||||
|
# PRD 0029: Codex host credentials through egress
|
||||||
|
|
||||||
|
- **Status:** Draft
|
||||||
|
- **Author:** didericis-codex
|
||||||
|
- **Created:** 2026-05-29
|
||||||
|
- **Issue:** #109
|
||||||
|
|
||||||
|
## Summary
|
||||||
|
|
||||||
|
Allow Codex bottles to use a host-authorized ChatGPT/device-login
|
||||||
|
access token by forwarding it only into the egress sidecar, gated by an
|
||||||
|
explicit `agent_provider.forward_host_credentials` manifest flag.
|
||||||
|
|
||||||
|
## Problem
|
||||||
|
|
||||||
|
Codex bottles can reach `chatgpt.com` after the host is added to egress,
|
||||||
|
but requests to `chatgpt.com/backend-api/codex/...` still fail with
|
||||||
|
HTTP 403. The egress proxy strips agent-originated `Authorization`
|
||||||
|
headers and only re-injects auth for routes that declare an egress-owned
|
||||||
|
token. A bare `chatgpt.com` route therefore forwards Codex requests
|
||||||
|
without the ChatGPT bearer token.
|
||||||
|
|
||||||
|
Copying `~/.codex/auth.json` into the agent would solve auth but would
|
||||||
|
also put access and refresh material inside the agent sandbox. That cuts
|
||||||
|
against bot-bottle's credential minimization model: provider credentials
|
||||||
|
should live in the sidecar boundary when possible, not in the agent.
|
||||||
|
|
||||||
|
## Goals / Success Criteria
|
||||||
|
|
||||||
|
- A Codex bottle with host ChatGPT auth can call
|
||||||
|
`chatgpt.com/backend-api/codex/...` through egress.
|
||||||
|
- Host credential forwarding happens only when the bottle declares
|
||||||
|
`agent_provider.forward_host_credentials: true`.
|
||||||
|
- The agent container does not receive `OPENAI_API_KEY`,
|
||||||
|
`CODEX_ACCESS_TOKEN`, `tokens.access_token`, `tokens.refresh_token`,
|
||||||
|
or `auth.json`.
|
||||||
|
- Egress route files remain non-secret: they contain only host/path/auth
|
||||||
|
slot metadata, never token values.
|
||||||
|
- Missing, non-ChatGPT, malformed, or expired host Codex auth fails
|
||||||
|
launch with a clear operator-facing message.
|
||||||
|
- Existing Claude OAuth placeholder behavior remains unchanged.
|
||||||
|
|
||||||
|
## Non-goals
|
||||||
|
|
||||||
|
- Refreshing Codex tokens in the sidecar. The first cut reads the host's
|
||||||
|
current access token at launch; operators can restart after host Codex
|
||||||
|
refreshes auth.
|
||||||
|
- Copying host `~/.codex/auth.json` into the agent.
|
||||||
|
- Allowing arbitrary host credential forwarding. This PRD covers Codex
|
||||||
|
ChatGPT/device-login credentials only.
|
||||||
|
- Hot-applying a new authenticated `chatgpt.com` route to an existing
|
||||||
|
running sidecar. The current hot-apply path cannot safely populate new
|
||||||
|
token env slots in an already-running container.
|
||||||
|
|
||||||
|
## Scope
|
||||||
|
|
||||||
|
### In scope
|
||||||
|
|
||||||
|
- Add `agent_provider.forward_host_credentials` to the bottle manifest
|
||||||
|
schema, defaulting to `false`.
|
||||||
|
- Support the flag for `agent_provider.template: codex`.
|
||||||
|
- Read host Codex auth from `$CODEX_HOME/auth.json` when `CODEX_HOME` is
|
||||||
|
set, otherwise from `~/.codex/auth.json`.
|
||||||
|
- Extract only `tokens.access_token`.
|
||||||
|
- Validate that `auth_mode` is `chatgpt` and the access token is present,
|
||||||
|
JWT-shaped, and not expired.
|
||||||
|
- Add or upgrade a `chatgpt.com` egress route to inject that access token
|
||||||
|
via an `EGRESS_TOKEN_N` sidecar env slot.
|
||||||
|
- Pass the extracted token only into the sidecar compose/run
|
||||||
|
environment, alongside other egress token values.
|
||||||
|
|
||||||
|
### Out of scope
|
||||||
|
|
||||||
|
- Sidecar-owned refresh using `tokens.refresh_token`.
|
||||||
|
- Sharing full Codex auth state with the agent.
|
||||||
|
- Supporting host credential forwarding for non-Codex providers.
|
||||||
|
|
||||||
|
## Design
|
||||||
|
|
||||||
|
### Manifest
|
||||||
|
|
||||||
|
Extend `agent_provider`:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
agent_provider:
|
||||||
|
template: codex
|
||||||
|
forward_host_credentials: true
|
||||||
|
```
|
||||||
|
|
||||||
|
The field defaults to `false`. If set on a non-Codex provider, manifest
|
||||||
|
validation should reject it until that provider has a concrete,
|
||||||
|
credential-minimizing implementation.
|
||||||
|
|
||||||
|
### Host auth extraction
|
||||||
|
|
||||||
|
At prepare/launch time, when the flag is enabled for Codex:
|
||||||
|
|
||||||
|
1. Resolve the host Codex home directory from `$CODEX_HOME`, falling
|
||||||
|
back to `~/.codex`.
|
||||||
|
2. Parse `auth.json`.
|
||||||
|
3. Require `auth_mode == "chatgpt"`.
|
||||||
|
4. Require a non-empty `tokens.access_token`.
|
||||||
|
5. Parse the JWT payload enough to require an `exp` claim in the future.
|
||||||
|
6. Return only the access token value to the launch path.
|
||||||
|
|
||||||
|
Errors should name the missing or invalid condition and point the
|
||||||
|
operator at `codex login --device-auth`, without printing token values.
|
||||||
|
|
||||||
|
### Egress route
|
||||||
|
|
||||||
|
When forwarding host Codex credentials, the effective egress route table
|
||||||
|
should contain an authenticated `chatgpt.com` route. If the bottle
|
||||||
|
already declares `chatgpt.com` as a bare-pass route, upgrade it in the
|
||||||
|
effective route table rather than requiring a duplicate manifest entry.
|
||||||
|
If the bottle already declares an authenticated `chatgpt.com` route,
|
||||||
|
fail rather than guessing whether to override operator-provided auth.
|
||||||
|
|
||||||
|
The rendered route should look like any other egress-owned auth route:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
routes:
|
||||||
|
- host: "chatgpt.com"
|
||||||
|
auth_scheme: "Bearer"
|
||||||
|
token_env: "EGRESS_TOKEN_N"
|
||||||
|
```
|
||||||
|
|
||||||
|
The access token value is supplied through the sidecar process
|
||||||
|
environment for that `EGRESS_TOKEN_N` slot. It must not be written to
|
||||||
|
`routes.yaml`, compose files, env files, logs, or user-facing output.
|
||||||
|
|
||||||
|
### Data flow
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
flowchart LR
|
||||||
|
H["Host ~/.codex/auth.json"] --> L["bot-bottle launch"]
|
||||||
|
L -->|access token only| S["egress sidecar env"]
|
||||||
|
A["Codex agent"] -->|HTTPS via proxy, auth stripped| E["egress"]
|
||||||
|
E -->|Bearer injected from env| C["chatgpt.com"]
|
||||||
|
```
|
||||||
|
|
||||||
|
## Implementation chunks
|
||||||
|
|
||||||
|
1. **PRD first.** Land this document as the first commit on the feature
|
||||||
|
branch.
|
||||||
|
2. **Manifest schema.** Add `forward_host_credentials`, validation, and
|
||||||
|
unit tests.
|
||||||
|
3. **Host Codex auth reader.** Add a small stdlib-only helper for
|
||||||
|
parsing and validating host Codex auth without printing values.
|
||||||
|
4. **Effective egress route.** Add/upgrade the `chatgpt.com` route when
|
||||||
|
the flag is enabled, and add tests for bare route upgrade,
|
||||||
|
missing-route insertion, and authenticated-route conflict.
|
||||||
|
5. **Launch wiring.** Pass the host access token into the egress sidecar
|
||||||
|
env for Docker and smolmachines without exposing it to the agent.
|
||||||
|
6. **Docs and tests.** Update README examples and run the unit suite.
|
||||||
|
|
||||||
|
## Open questions
|
||||||
|
|
||||||
|
- Should a later version support sidecar refresh using the host refresh
|
||||||
|
token, or should restart-on-expiry remain the policy?
|
||||||
|
- Should telemetry hosts such as `ab.chatgpt.com` stay blocked by
|
||||||
|
default even when Codex ChatGPT auth is enabled?
|
||||||
|
|
||||||
|
## References
|
||||||
|
|
||||||
|
- Gitea issue #109: Codex ChatGPT auth should inject host access token
|
||||||
|
via egress.
|
||||||
|
- PRD 0017: Egress-proxy — universal MITM with path filtering + auth
|
||||||
|
injection.
|
||||||
|
- PRD 0026: Agent provider templates.
|
||||||
Reference in New Issue
Block a user