wishforge-ide/docs/provider-proxy.md
eust-w b47a07e8d2 chore: baseline snapshot of the Codex-delivered code before review
Imports the previously untracked working tree as-is so that the review
changes that follow (requirements -> design -> implementation) can be
reviewed as diffs and reverted if needed. No content changes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-19 13:18:04 +08:00

7.1 KiB

Run-scoped Codex model proxy

The production execution job receives a proxy token, not the tenant's long-lived OpenAI API key. Only the control-plane/Vault process can decrypt that key. The proxy constructs the upstream URL itself: https://api.openai.com/v1/responses for POST and https://api.openai.com/v1/models for GET. Client-selected upstream URLs, redirects, arbitrary headers and additional API routes are refused.

Integration contract

const proxy = new ProviderProxy(store, env);
const credential = await proxy.credential(actor, run);
// { apiKey: proxyToken, baseUrl, expiresAt, metering: 'proxy' }
const upstreamResponse = await proxy.forward({
  authorization, method, path, headers, body: rawUint8Array, signal
});
// Standard Response, including a ReadableStream for SSE.

The public base URL includes /provider-proxy/v1. The HTTP adapter strips that prefix and passes exactly /responses or /models to forward. It must forward Response bodies with backpressure/cancellation, use no request-body logging, and never route this bearer through the ordinary OIDC or internal-service guard. The proxy independently authenticates its own audience. The credential carries metering: proxy; worker-reported model tokens must not be charged again.

Required configuration:

  • WF_PROVIDER_PROXY_PUBLIC_URL: production HTTPS base URL ending in /provider-proxy/v1; development permits explicit localhost HTTP.
  • WF_PROVIDER_PROXY_SIGNING_KEY: independent secret of at least 32 characters.
  • WF_PROVIDER_PROXY_ALLOWED_MODELS: comma-separated operator-approved model IDs.
  • Development additionally requires WF_PROVIDER_PROXY_ENABLED=true.
  • Production credential decryption uses the existing external Vault integration.

Proxy JWTs have a separate issuer/audience and a lifetime bounded by both the remaining task budget and one hour. They bind tenant, run, execution generation, lease token, authenticated worker principal and the exact provider-connection version. Every request rechecks these bindings. While a stream is active the proxy repeats the checks at most one second apart and aborts its upstream reader when cancellation, lease expiry, generation replacement or credential revocation is observed. Polling revocation is bounded, not an instantaneous network cutoff; already-dispatched provider work may still incur usage after an abort.

Budget and request state

Only one upstream request may be active per run. Before external I/O the API persists its request claim under the tenant transaction lock. A request is keyed by run/generation/lease/connection and its idempotency key, or the body digest when the client provides no key. Changing the body under the same key fails. Completed bounded responses can be replayed without another provider request.

The proxy supports self-contained text, local function/custom tools and bounded namespaces containing only those local tool types. It rejects conversation/previous-response references, stored prompt templates, remote MCP and hosted tools, background execution, multimodal/file inputs and unverified top-level parameters. It forces store: false, default service tier, and tenant/run-specific cache and safety identifiers. Model/context choices that need an unsupported wire feature must fail explicitly, without reverting to a raw API key.

Input reservation uses serialized text bytes plus conservative protocol overhead. max_output_tokens is bounded by the run's remaining reservation. This is a conservative admission estimate, not an exact tokenizer or monetary quotation. Actual billing tokens are accepted only from the trusted upstream JSON usage or terminal Responses SSE usage (input_tokens + output_tokens == total_tokens). The ledger charges each proxy request once, independently of executor output. If actual usage exceeds the remaining budget, the actual value is recorded and new execution stops. No preflight estimate guarantees a remote provider cannot report an in-flight overrun.

SSE frames are parsed across byte and CRLF boundaries, bounded in size and redacted before forwarding/caching. Upstream authorization/error headers are not forwarded. Non-success provider bodies are replaced with generic errors so they cannot echo the private key. Requests are bounded to 2 MiB, SSE frames to 1 MiB, responses to 16 MiB, replay caches to 2 MiB and one upstream call to 120 seconds. These limits are explicit compatibility constraints for live Codex validation.

If a dispatched POST times out, the stream ends without trusted terminal usage, or the client disconnects, the record becomes unknown. Its active reservation is retained and the run waits with provider_usage_unknown. Subsequent requests, including after a new execution lease, cannot blindly repeat the operation. There is no automated resolution that invents usage; an operator must reconcile the provider's actual outcome before execution can safely resume. Raw prompts and original credentials are not recorded in these operation rows. Replay data is tenant-owned model output and remains subject to platform retention controls.

Official API references: Responses create, streaming Responses.

Validation boundary

npx vitest run tests/provider-proxy.test.ts uses an injected local fake upstream. It verifies audience separation, tenant/lease/generation/connection binding, SSE chunking, secret redaction, one-time metering/replay, route/tool/model denial, cancellation, connection rotation, budget admission and unresolved-outcome blocking. No model calls, real credentials or production deployments are used.

The pinned Codex SDK/CLI 0.162.1 was executed locally through the actual proxy with a fake upstream (WF_CODEX_SDK_INTEGRATION=1 npx vitest run tests/integration/codex-sdk.test.ts). It sent a local shell tool call, wrote a fixture file in a disposable Git workspace, completed the next response, exported a checkpoint containing the file, and recorded exactly two upstream receipts / 26 fixture tokens. The test did not contact a real model.

This exposed three actual integration defects that are now fixed: reserved openai provider IDs cannot be overridden, the CLI sends transport-only client_metadata, and its local tools include namespaces whose JSON schemas may mention image fields. The adapter selects wishforge_proxy, uses Responses HTTP with retries/WebSocket disabled, and supplies the scoped key through the SDK's private environment. The proxy discards a bounded metadata map, recursively permits only local tool namespaces, and checks actual input content for media instead of treating tool parameter schemas as attachments. Model/hosted-tool/ remote-state restrictions remain enforced. Loopback NO_PROXY is set only on this child process to avoid the macOS development proxy intercepting local traffic.

Real model access, production Vault, TLS and network isolation remain explicit acceptance work. CodeBuddy must remain disabled in production until its equivalent proxy protocol is verified. Unsupported Codex features and expired scoped tokens must never activate an ambient-account or long-lived-key fallback.