Merge origin/dev (PR #87 images endpoint) with encrypted-marker fixes (#85)

Author: lidge-jun

devlog/260710_issue83_images_endpoint/000_plan.md

@@ -0,0 +1,85 @@
+# 260710 — /v1/images relay for codex's built-in image_gen (issue #83)
+
+## Problem
+
+GitHub issue #83: the built-in `image_gen` tool fails instantly with
+`http 404 Not Found: {"error":{"message":"Unknown endpoint: POST /v1/images/generations",...}}`.
+
+The 404 is ours: codex-rs's standalone image-generation extension executes CLIENT-SIDE —
+it POSTs `{base_url}/images/generations` (edits variant: `/images/edits`) with the same
+ChatGPT bearer auth it uses for chat (`ext/image-generation`, request body
+`{prompt, background, model:"gpt-image-2", quality, size}`, expected response
+`{created, data:[{b64_json}]}`, both strict serde). Under Design B injection `base_url`
+IS the proxy, and the request died on the `/v1/*` JSON-404 guard (previously even
+test-pinned as an intentional 404 in server-auth.test.ts).
+
+Why now: codex 0.144.0 graduated `image_generation` from the disabled-by-default
+`imagegenext` experiment to Stage::Stable / default-enabled, so ChatGPT-signed-in users
+started hitting the tool organically. The hosted `image_generation` tools[] entry on
+`/v1/responses` was never affected (passthrough already forwards it); only the
+extension's direct REST call 404'd.
+
+## Fix
+
+New relay route `POST /v1/images/{generations,edits}` (src/server/images.ts), inserted
+before the /v1/* guard with the standard data-plane preamble (drain 503, requireApiAuth,
+origin check, withCors, request log with `client_cancel` meta on 499).
+
+Upstream selection (`findImagesUpstreams` collects BOTH candidates; selection is
+per-request):
+
+1. **ChatGPT forward provider** — preferred, same precedence as the vision/web-search
+   sidecars; it is the backend codex itself would have called absent the base_url
+   override, so request/response bodies relay verbatim (no mapping). Auth via
+   `resolveCodexAuthContext`/`headersForCodexAuthContext`: forwarded caller bearer, or
+   the routed multi-account pool token. Guards:
+   - `startServer` auto-upserts a `chatgpt` forward entry into every config, so the
+     forward candidate is only used when the resolved headers actually carry an
+     authorization value — otherwise an unauthenticated request would bounce off
+     chatgpt.com as an opaque `{"detail":"Unauthorized"}`.
+   - A bearer equal to the proxy's own admission secret (non-loopback binds accept
+     `Authorization: Bearer <OPENCODEX_API_AUTH_TOKEN>`) is stripped before selection —
+     the proxy secret must never be relayed to chatgpt.com
+     (`isProxyAdmissionSecret`, extracted from `hasValidApiAuth`).
+   - Forward-auth FAILURES (pool cooldown 429, reauth 401, affinity 409) are captured,
+     not returned: a configured keyed provider still serves the request, and the
+     captured error only surfaces when no keyed candidate exists. Without this, "all
+     pool accounts cooling down" would 429 image_gen while api.openai.com sat idle.
+   - Pool upstream outcomes are recorded via `sidecarOutcomeRecorder` (status /
+     timeout / connect_error), keeping rotation failover signals alive.
+2. **Keyed openai-responses provider** (e.g. api.openai.com) — fallback when no
+   relayable ChatGPT auth; its `/v1/images/*` is the real platform Images API. URL is
+   normalized like the adapter (`baseUrl.replace(/\/v1\/?$/,"")` + `/v1/images/…`), so
+   baseUrl with or without `/v1` both work; forward URLs stay bare
+   (`${baseUrl}/images/…`, the ChatGPT-backend convention).
+3. **Neither** — honest 400 (`invalid_request_error`) naming the fix
+   (`codex features disable image_generation` or add an OpenAI provider). 400, not 5xx:
+   codex retries every 5xx up to 5 total attempts and this is a permanent config state.
+
+Relay details: `readJsonRequestBody` (zstd/gzip decode + 256MB cap) → JSON re-serialize →
+`fetchWithResetRetry` (stale keep-alive resets) with a `config.images.timeoutMs`
+(default 300s) timeout linked to the client abort; response buffered (single JSON
+document, few MB) and passed through status+content-type+body verbatim so upstream
+plan-gating errors stay legible. Client cancel returns 499 (`client_closed_request`),
+never a fake 502; genuine timeout returns 504 (retriable by codex, acceptable for a
+transient hang).
+
+Deliberately NOT done:
+
+- No auto-injection of `[features] image_generation = false` — it would remove a
+  capability the relay makes work, and openai/codex#21952 suggests app-server ignores
+  the flag anyway. Documented as a user opt-out instead (docs-site codex-integration,
+  en/ko/zh-cn).
+- No image generation via routed providers (Gemini image models etc.) — the adapter
+  event pipeline has no image-output event; separate feature, not this bug fix.
+
+## Tests
+
+tests/server-images.test.ts (16): forward relay (auth + path + body), edits path,
+pool-token override (caller bearer must not leak), zstd body decode, keyed fallback +
+`/v1` URL normalization (with and without suffix), unauthenticated-request gate (keyed
+fallback / 401), forward-auth-failure fallback (keyed / surfaced 401), no-upstream 400,
+upstream error passthrough, 504 timeout via `config.images.timeoutMs`, GET falls to 404
+guard, non-loopback auth/origin, admission-secret never relayed.
+server-auth.test.ts's 404-guard list swaps `/v1/images/generations` for
+`/v1/realtime/sessions`.

docs-site/src/content/docs/guides/codex-integration.md

@@ -23,7 +23,24 @@ fast_mode = true
 ```
 
 The proxy listens on port `10100` by default and serves `POST /v1/responses`,
-`POST /v1/responses/compact`, `GET /v1/models`, `GET /healthz`, and the `/api/*` management surface.
+`POST /v1/responses/compact`, `POST /v1/images/generations`, `POST /v1/images/edits`,
+`GET /v1/models`, `GET /healthz`, and the `/api/*` management surface.
+
+### Built-in image generation (`image_gen`)
+
+Codex's built-in `image_gen` tool does not go through `/v1/responses` — the codex-rs extension
+POSTs `{base_url}/images/generations` (or `/images/edits` when reference images are attached)
+directly, with the same ChatGPT bearer auth it uses for chat. Because the injected `base_url`
+points at opencodex, the proxy relays those calls to the OpenAI upstream:
+
+- **ChatGPT login (default):** the request is forwarded to `chatgpt.com/backend-api/codex` with
+  the caller's OAuth token (or the routed multi-account pool token). No API key is needed.
+- **OpenAI API-key provider:** if no ChatGPT auth is available on the request, the relay falls
+  back to a configured `openai-responses` API-key provider (e.g. `api.openai.com`).
+- **Neither:** the proxy returns a clear error instead of a generic 404. Routed providers
+  (Cursor, Gemini, Kiro, …) cannot serve image generation; if you don't want the tool offered at
+  all, disable it in Codex with `codex features disable image_generation`
+  (`[features] image_generation = false` in `config.toml`).
 
 For a non-loopback `hostname`, Codex must send the generated API auth header. The injector therefore
 uses a dedicated provider instead:

docs-site/src/content/docs/ko/guides/codex-integration.md

@@ -22,7 +22,24 @@ fast_mode = true
 ```
 
 프록시의 기본 포트는 `10100`입니다. `POST /v1/responses`, `POST /v1/responses/compact`,
-`GET /v1/models`, `GET /healthz`, `/api/*` 관리 API를 제공합니다.
+`POST /v1/images/generations`, `POST /v1/images/edits`, `GET /v1/models`, `GET /healthz`,
+`/api/*` 관리 API를 제공합니다.
+
+### 내장 이미지 생성 (`image_gen`)
+
+Codex의 내장 `image_gen` 도구는 `/v1/responses`를 거치지 않습니다. codex-rs 확장이
+`{base_url}/images/generations`(참조 이미지가 있으면 `/images/edits`)를 채팅과 동일한
+ChatGPT bearer 인증으로 직접 POST합니다. 주입된 `base_url`이 opencodex를 가리키므로,
+프록시가 이 호출을 OpenAI 업스트림으로 중계합니다.
+
+- **ChatGPT 로그인(기본):** 호출자의 OAuth 토큰(또는 멀티 계정 풀에서 선택된 계정의 토큰)으로
+  `chatgpt.com/backend-api/codex`에 전달합니다. API 키가 필요 없습니다.
+- **OpenAI API 키 프로바이더:** 요청에 사용할 ChatGPT 인증이 없으면, 설정된 `openai-responses`
+  API 키 프로바이더(예: `api.openai.com`)로 대신 전달합니다.
+- **둘 다 없음:** 모호한 404 대신 명확한 오류를 반환합니다. 라우팅되는 다른 프로바이더(Cursor,
+  Gemini, Kiro 등)는 이미지 생성을 제공할 수 없습니다. 도구 자체를 끄고 싶다면 Codex에서
+  `codex features disable image_generation`(`config.toml`의 `[features] image_generation = false`)을
+  사용하세요.
 
 `hostname`이 loopback 주소가 아니면 Codex가 자동 생성된 API 인증 헤더를 보내야 합니다. 이때는 전용
 프로바이더를 주입합니다.

docs-site/src/content/docs/ko/reference/architecture.md

@@ -40,7 +40,9 @@ HTTP 경계는 `server/index.ts`가 맡고, Responses 데이터 플레인은 `se
 
 1. `server/index.ts`에서 CORS와 API 인증을 확인하고, 종료 대기 중이면 새 요청을 거부한 뒤 요청 수명
    주기를 기록합니다. 여기서 `GET /v1/models`, `POST /v1/responses`,
-   `POST /v1/responses/compact`, `/v1/responses`의 선택적 WebSocket 업그레이드를 제공합니다.
+   `POST /v1/responses/compact`, `POST /v1/images/generations` / `POST /v1/images/edits`
+   (Codex 내장 `image_gen` 도구용 — `server/images.ts`가 OpenAI 계열 업스트림으로 중계),
+   `/v1/responses`의 선택적 WebSocket 업그레이드를 제공합니다.
 2. `server/responses.ts`가 압축을 풀고 JSON을 읽습니다. 기억해 둔 `previous_response_id` 입력이 있으면
    펼친 다음 `responses/parser.ts`로 넘깁니다.
 3. `router.ts`가 일반 모델 id 또는 `provider/model` id를 해석합니다. 이어서 Codex 계정 affinity를

docs-site/src/content/docs/reference/architecture.md

@@ -41,7 +41,9 @@ src/
 
 1. `server/index.ts` applies CORS and API authentication, rejects new work while draining, and
    records request lifecycle metadata. It serves `GET /v1/models`, `POST /v1/responses`,
-   `POST /v1/responses/compact`, and the optional WebSocket upgrade on `/v1/responses`.
+   `POST /v1/responses/compact`, `POST /v1/images/generations` / `POST /v1/images/edits`
+   (relayed to an OpenAI-family upstream by `server/images.ts` for codex's built-in `image_gen`
+   tool), and the optional WebSocket upgrade on `/v1/responses`.
 2. `server/responses.ts` decompresses and parses JSON, expands locally remembered
    `previous_response_id` input when available, then calls `responses/parser.ts`.
 3. `router.ts` resolves a bare or `provider/model` id. The server then resolves Codex account

docs-site/src/content/docs/zh-cn/guides/codex-integration.md

@@ -21,7 +21,24 @@ fast_mode = true
 ```
 
 proxy 的默认端口为 `10100`，提供 `POST /v1/responses`、`POST /v1/responses/compact`、
-`GET /v1/models`、`GET /healthz` 以及 `/api/*` 管理 API。
+`POST /v1/images/generations`、`POST /v1/images/edits`、`GET /v1/models`、`GET /healthz`
+以及 `/api/*` 管理 API。
+
+### 内置图像生成（`image_gen`）
+
+Codex 的内置 `image_gen` 工具不经过 `/v1/responses`——codex-rs 扩展直接 POST
+`{base_url}/images/generations`（附带参考图像时为 `/images/edits`），使用与聊天相同的
+ChatGPT bearer 认证。由于注入的 `base_url` 指向 opencodex，proxy 会把这些调用中继到
+OpenAI 上游：
+
+- **ChatGPT 登录（默认）：** 请求会携带调用方的 OAuth token（或多账户池选中账户的 token）
+  转发到 `chatgpt.com/backend-api/codex`，无需 API key。
+- **OpenAI API key 提供商：** 如果请求中没有可用的 ChatGPT 认证，中继会退回到已配置的
+  `openai-responses` API key 提供商（例如 `api.openai.com`）。
+- **两者都没有：** proxy 返回明确的错误而不是含糊的 404。其他路由提供商（Cursor、Gemini、
+  Kiro 等）无法提供图像生成；如果想完全关闭该工具，可在 Codex 中执行
+  `codex features disable image_generation`（即 `config.toml` 的
+  `[features] image_generation = false`）。
 
 如果 `hostname` 不是 loopback 地址，Codex 必须发送自动生成的 API 认证请求头。此时注入器会改用
 专用提供商：

docs-site/src/content/docs/zh-cn/reference/architecture.md

@@ -40,7 +40,9 @@ src/
 
 1. `server/index.ts` 应用 CORS 和 API 认证，在 drain 期间拒绝新请求，并记录请求生命周期
    metadata。它提供 `GET /v1/models`、`POST /v1/responses`、
-   `POST /v1/responses/compact`，以及 `/v1/responses` 上可选的 WebSocket upgrade。
+   `POST /v1/responses/compact`、`POST /v1/images/generations` / `POST /v1/images/edits`
+   （供 Codex 内置 `image_gen` 工具使用——由 `server/images.ts` 中继到 OpenAI 系上游），
+   以及 `/v1/responses` 上可选的 WebSocket upgrade。
 2. `server/responses.ts` 解压并解析 JSON；如果本地记住了对应输入，则展开
    `previous_response_id`，随后调用 `responses/parser.ts`。
 3. `router.ts` 解析 bare id 或 `provider/model` id。server 随后确定 Codex account affinity，

src/server/auth-cors.ts

@@ -117,31 +117,34 @@ export function assertServerAuthConfig(config: OcxConfig): void {
   }
 }
 
-export function hasValidApiAuth(req: Request, config: OcxConfig): boolean {
-  if (!isApiAuthRequired(config)) return true;
-  const actual = req.headers.get("x-opencodex-api-key")?.trim()
-    || req.headers.get("authorization")?.replace(/^Bearer\s+/i, "").trim();
+/** Whether `token` is one of the proxy's own admission secrets (env token or config API keys). */
+export function isProxyAdmissionSecret(token: string, config: OcxConfig): boolean {
+  const actual = token.trim();
   if (!actual) return false;
+  const enc = new TextEncoder();
+  const actualBytes = enc.encode(actual);
   // Check env-based token
   const expected = configuredApiAuthToken(config);
   if (expected) {
-    const enc = new TextEncoder();
     const expectedBytes = enc.encode(expected);
-    const actualBytes = enc.encode(actual);
     if (expectedBytes.length === actualBytes.length && timingSafeEqual(actualBytes, expectedBytes)) return true;
   }
   // Check config-based API keys
-  if (config.apiKeys?.length) {
-    const enc = new TextEncoder();
-    const actualBytes = enc.encode(actual);
-    for (const k of config.apiKeys) {
-      const keyBytes = enc.encode(k.key);
-      if (keyBytes.length === actualBytes.length && timingSafeEqual(actualBytes, keyBytes)) return true;
-    }
+  for (const k of config.apiKeys ?? []) {
+    const keyBytes = enc.encode(k.key);
+    if (keyBytes.length === actualBytes.length && timingSafeEqual(actualBytes, keyBytes)) return true;
   }
   return false;
 }
 
+export function hasValidApiAuth(req: Request, config: OcxConfig): boolean {
+  if (!isApiAuthRequired(config)) return true;
+  const actual = req.headers.get("x-opencodex-api-key")?.trim()
+    || req.headers.get("authorization")?.replace(/^Bearer\s+/i, "").trim();
+  if (!actual) return false;
+  return isProxyAdmissionSecret(actual, config);
+}
+
 export function requireApiAuth(req: Request, config: OcxConfig, kind: "management" | "data-plane"): Response | null {
   if (hasValidApiAuth(req, config)) return null;
   if (kind === "management") return jsonResponse({ error: "opencodex API key required" }, 401);