|
| 1 | +# 010 — #2073: injector env_key contract (codex-cli 0.146+) |
| 2 | + |
| 3 | +## Contract facts (verified against openai/codex rust-v0.146.0 source, wp5 research lane) |
| 4 | + |
| 5 | +- env_key reads the named env var and sends Authorization: Bearer <value> |
| 6 | + (model-provider-info/src/lib.rs#L263-281). Missing/empty var = HARD error |
| 7 | + (CodexErr::EnvVar), never an empty bearer. |
| 8 | +- env_key + requires_openai_auth = true is valid; env_key WINS for wire auth |
| 9 | + (first-party scoped auth disabled), requires_openai_auth keeps login/account |
| 10 | + UX (provider.rs#L153-174, auth.rs#L162-178). |
| 11 | +- env_http_headers is still honored in 0.146 (not removed), but bearer auth is |
| 12 | + the documented modern form. |
| 13 | + |
| 14 | +## Server-side prerequisite (already landed) |
| 15 | + |
| 16 | +#1686 chain (22d5492b2, acfedae0a, f848b4997): /v1/responses admits our |
| 17 | +admission secret via Authorization: Bearer and SUBSTITUTES stored main auth |
| 18 | +upstream (materializeCodexUpstreamAuth). So an env_key client works end to end |
| 19 | +on dev today. The injector is the only stale half (this issue). |
| 20 | + |
| 21 | +## Change |
| 22 | + |
| 23 | +src/codex/inject.ts buildProviderTableBlock (legacy/non-loopback mode only — |
| 24 | +loopback Design B emits no auth line at all): |
| 25 | + |
| 26 | +- BEFORE: env_http_headers = { "x-opencodex-api-key" = "OPENCODEX_API_AUTH_TOKEN" } |
| 27 | +- AFTER: env_key = "OPENCODEX_API_AUTH_TOKEN" |
| 28 | + |
| 29 | +requires_openai_auth = true stays (login UX; env_key wins wire auth). |
| 30 | +Sub-table strip logic from #2061 (env_http_headers orphan cleanup) STAYS — it |
| 31 | +cleans historic configs regenerated by the app. stripExistingModelProvider |
| 32 | +already removes the whole marker-owned block, so old env_http_headers lines |
| 33 | +from prior injections are replaced on next inject (idempotent). |
| 34 | + |
| 35 | +## Behavior deltas (accepted) |
| 36 | + |
| 37 | +- Missing OPENCODEX_API_AUTH_TOKEN in the codex process env: was silent header |
| 38 | + omission -> 401; now a clear codex-side hard error. Better diagnosability; |
| 39 | + the unauthenticated-loopback-listener case already suppresses the auth line |
| 40 | + entirely (shouldInjectApiAuthHeader), so the known no-var environment never |
| 41 | + sees env_key. |
| 42 | +- The client's own ChatGPT bearer is no longer forwarded on this path (env_key |
| 43 | + replaces Authorization); the proxy substitutes stored main auth — exactly the |
| 44 | + #1686 design. Hand-configured env_http_headers remains honored by the runtime |
| 45 | + for users who want the legacy form. |
| 46 | + |
| 47 | +## Tests |
| 48 | + |
| 49 | +- tests/codex-inject.test.ts:44,194 — flip to env_key expectation + add a |
| 50 | + regression that env_http_headers is NOT emitted. |
| 51 | +- tests/loopback-listener-admission.test.ts:199 / integration:617 — extend the |
| 52 | + not-contains to env_key (loopback emits no auth line). |
| 53 | +- Keep #2061 sub-table strip tests untouched. |
| 54 | + |
| 55 | +## Docs |
| 56 | + |
| 57 | +- structure/02_config-and-codex-home.md provider-block sample: update line. |
| 58 | +- docs-site reference mentions of env_http_headers (if any) updated. |
| 59 | + |
| 60 | +Verifier: bun test tests/codex-inject.test.ts tests/loopback-listener-admission.test.ts tests/loopback-listener-integration.test.ts + bun x tsc --noEmit. |
| 61 | + |
0 commit comments