Skip to content

Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

TypeScript

feat(codex-proxy): stream subscription completions safely

Alfredo Lopeze195850bdefc
diff --git a/codex-llm-proxy/package-lock.json b/codex-llm-proxy/package-lock.json
index efa2f1cd1..76fa8ff7f 100644
--- a/codex-llm-proxy/package-lock.json
+++ b/codex-llm-proxy/package-lock.json
@@ -9,6 +9,7 @@
"version": "0.1.0",
"license": "SEE LICENSE IN LICENSE",
"dependencies": {
+ "@clerum/llm-provider-attempt-contract": "file:../packages/llm-provider-attempt-contract",
"express": "^4.21.2",
"jsonwebtoken": "^9.0.2",
"pino": "^10.3.1",
@@ -28,6 +29,15 @@
"node": ">=24"
}
},
+ "../packages/llm-provider-attempt-contract": {
+ "name": "@clerum/llm-provider-attempt-contract",
+ "version": "0.1.0",
+ "license": "MIT"
+ },
+ "node_modules/@clerum/llm-provider-attempt-contract": {
+ "resolved": "../packages/llm-provider-attempt-contract",
+ "link": true
+ },
"node_modules/@jridgewell/sourcemap-codec": {
"version": "1.5.5",
"resolved": "https://registry.npmjs.org/@jridgewell/sourcemap-codec/-/sourcemap-codec-1.5.5.tgz",
diff --git a/codex-llm-proxy/package.json b/codex-llm-proxy/package.json
index d55b7bbfa..2651b2c2d 100644
--- a/codex-llm-proxy/package.json
+++ b/codex-llm-proxy/package.json
@@ -15,6 +15,7 @@
},
"license": "SEE LICENSE IN LICENSE",
"dependencies": {
+ "@clerum/llm-provider-attempt-contract": "file:../packages/llm-provider-attempt-contract",
"express": "^4.21.2",
"jsonwebtoken": "^9.0.2",
"pino": "^10.3.1",
diff --git a/codex-llm-proxy/src/auth/executionTicketVerifier.ts b/codex-llm-proxy/src/auth/executionTicketVerifier.ts
index 23762f1a6..b2bac769d 100644
--- a/codex-llm-proxy/src/auth/executionTicketVerifier.ts
+++ b/codex-llm-proxy/src/auth/executionTicketVerifier.ts
@@ -7,6 +7,7 @@ export type ExecutionTicketClaims = {
hostRef: string
model: string
requestHash: string
+ providerAttemptId: string
}
export function verifyExecutionTicket(
@@ -24,12 +25,14 @@ export function verifyExecutionTicket(
if (claims.typ !== 'codex-execution-ticket') return null
if (typeof claims.jti !== 'string' || typeof claims.hostRef !== 'string') return null
if (typeof claims.model !== 'string' || typeof claims.requestHash !== 'string') return null
+ if (typeof claims.providerAttemptId !== 'string') return null
return {
jti: claims.jti,
typ: 'codex-execution-ticket',
hostRef: claims.hostRef,
model: claims.model,
requestHash: claims.requestHash,
+ providerAttemptId: claims.providerAttemptId,
}
} catch {
return null
diff --git a/codex-llm-proxy/src/codexTransport.ts b/codex-llm-proxy/src/codexTransport.ts
new file mode 100644
index 000000000..e986253c9
--- /dev/null
+++ b/codex-llm-proxy/src/codexTransport.ts
@@ -0,0 +1,374 @@
+import {
+ hashCodexCompletionRequestV1,
+ parseCodexCompletionRequestV1,
+ type CodexCompletionRequestV1,
+} from '@clerum/llm-provider-attempt-contract'
+import type { FinalizeAttemptSuccess, RedeemAttemptSuccess } from './controlApiClient.js'
+import { logger } from './logger.js'
+import {
+ CODEX_CATALOG_ORIGIN,
+ CODEX_COMPLETIONS_ORIGIN,
+ OriginDeniedError,
+ assertAllowedUpstreamUrl,
+ assertRedirectLocation,
+ assertResolvedUpstream,
+ type OriginPolicyOptions,
+} from './originPolicy.js'
+import { assertBoundedDeadline } from './requestLimits.js'
+import { parseSafeUsage, type SafeUsage } from './usage.js'
+
+export type StreamFrame =
+ | { type: 'text'; text: string }
+ | { type: 'tool_call'; id: string; name: string; arguments: Record<string, unknown> }
+
+export type TransportTicket = {
+ jti: string
+ hostRef: string
+ model: string
+ requestHash: string
+ providerAttemptId: string
+}
+
+export class CodexTransportError extends Error {
+ constructor(
+ readonly code: string,
+ message: string
+ ) {
+ super(message)
+ this.name = 'CodexTransportError'
+ }
+}
+
+export type StreamCodexCompletionInput = {
+ executionTicket: string
+ requestHash: string
+ request: unknown
+ ticket: TransportTicket
+ deadlineMs?: number
+ maxDeadlineMs?: number
+ signal?: AbortSignal
+ redeem: (input: {
+ executionTicket: string
+ requestHash: string
+ model: string
+ hostRef: string
+ operation: 'completion_stream'
+ }) => Promise<RedeemAttemptSuccess>
+ finalize: (input: {
+ attemptReceipt: string
+ receipt: {
+ schemaVersion: 'codex-attempt-receipt.v1'
+ providerAttemptId: string
+ requestHash: string
+ outcome: 'success' | 'canceled' | 'error' | 'unknown'
+ usage?: SafeUsage
+ }
+ }) => Promise<FinalizeAttemptSuccess>
+ fetchFn: typeof fetch
+ lookup?: OriginPolicyOptions['lookup']
+ onFrame?: (frame: StreamFrame) => void
+}
+
+export type StreamCodexCompletionResult = {
+ outcome: 'success' | 'canceled' | 'error' | 'unknown'
+ usage?: SafeUsage
+}
+
+export async function streamCodexCompletion(
+ input: StreamCodexCompletionInput
+): Promise<StreamCodexCompletionResult> {
+ const parsed = parseCodexCompletionRequestV1(input.request)
+ if (!parsed.ok) {
+ throw new CodexTransportError('invalid_request', parsed.message)
+ }
+ const request = parsed.value
+ const digest = hashCodexCompletionRequestV1(request)
+ if (digest !== input.requestHash || input.ticket.requestHash !== input.requestHash) {
+ throw new CodexTransportError('request_hash_mismatch', 'request hash does not match the ticket')
+ }
+ if (request.model !== input.ticket.model) {
+ throw new CodexTransportError('model_not_allowed', 'request model does not match the ticket')
+ }
+ const deadlineMs = assertBoundedDeadline(input.deadlineMs ?? request.deadlineMs, input.maxDeadlineMs ?? 300_000)
+
+ const redeemed = await input.redeem({
+ executionTicket: input.executionTicket,
+ requestHash: input.requestHash,
+ model: request.model,
+ hostRef: input.ticket.hostRef,
+ operation: 'completion_stream',
+ })
+ if (redeemed.transport.servedModel !== request.model) {
+ await finalizeQuietly(input, redeemed, 'error')
+ throw new CodexTransportError('model_not_allowed', 'served model does not match the request')
+ }
+
+ const accessToken = redeemed.accessToken
+ let outcome: StreamCodexCompletionResult['outcome'] = 'unknown'
+ let usage: SafeUsage | undefined
+ const started = Date.now()
+ try {
+ const streamed = await readUpstreamStream({
+ request,
+ accessToken,
+ deadlineMs,
+ signal: input.signal,
+ fetchFn: input.fetchFn,
+ lookup: input.lookup,
+ onFrame: input.onFrame,
+ })
+ outcome = streamed.outcome
+ usage = streamed.usage
+ return { outcome, usage }
+ } catch (err) {
+ if (input.signal?.aborted || (err instanceof DOMException && err.name === 'AbortError')) {
+ outcome = 'canceled'
+ return { outcome, usage }
+ }
+ if (err instanceof OriginDeniedError) {
+ outcome = 'error'
+ throw new CodexTransportError('origin_denied', err.message)
+ }
+ if (err instanceof CodexTransportError) {
+ outcome = 'error'
+ throw err
+ }
+ outcome = 'error'
+ throw err
+ } finally {
+ void accessToken
+ await finalizeQuietly(input, redeemed, outcome, usage)
+ logger.info(
+ {
+ event: 'codex_proxy_attempt_closed',
+ outcome,
+ durationMs: Date.now() - started,
+ },
+ 'codex stream finalized'
+ )
+ }
+}
+
+async function finalizeQuietly(
+ input: StreamCodexCompletionInput,
+ redeemed: RedeemAttemptSuccess,
+ outcome: StreamCodexCompletionResult['outcome'],
+ usage?: SafeUsage
+): Promise<void> {
+ const payload = {
+ attemptReceipt: redeemed.attemptReceipt,
+ receipt: {
+ schemaVersion: 'codex-attempt-receipt.v1' as const,
+ providerAttemptId: input.ticket.providerAttemptId,
+ requestHash: input.requestHash,
+ outcome,
+ ...(usage ? { usage } : {}),
+ },
+ }
+ try {
+ await input.finalize(payload)
+ } catch {
+ try {
+ await input.finalize(payload)
+ } catch (err) {
+ logger.error({ event: 'codex_proxy_finalize_failed', err }, 'finalize retry exhausted')
+ }
+ }
+}
+
+async function readUpstreamStream(input: {
+ request: CodexCompletionRequestV1
+ accessToken: string
+ deadlineMs: number
+ signal?: AbortSignal
+ fetchFn: typeof fetch
+ lookup?: OriginPolicyOptions['lookup']
+ onFrame?: (frame: StreamFrame) => void
+}): Promise<StreamCodexCompletionResult> {
+ const url = assertAllowedUpstreamUrl(CODEX_COMPLETIONS_ORIGIN, 'completions')
+ await assertResolvedUpstream(url, input.lookup)
+ const timeout = AbortSignal.timeout(input.deadlineMs)
+ const signal = input.signal ? AbortSignal.any([input.signal, timeout]) : timeout
+ const response = await input.fetchFn(url.href, {
+ method: 'POST',
+ redirect: 'manual',
+ signal,
+ headers: {
+ authorization: `Bearer ${input.accessToken}`,
+ 'content-type': 'application/json',
+ accept: 'text/event-stream',
+ },
+ body: JSON.stringify(toUpstreamPayload(input.request)),
+ })
+ if (response.status >= 300 && response.status < 400) {
+ const location = response.headers.get('location') || ''
+ assertRedirectLocation(location, url)
+ throw new OriginDeniedError('origin_denied')
+ }
+ if (!response.ok || !response.body) {
+ throw new CodexTransportError('provider_unavailable', 'upstream completion failed')
+ }
+ return consumeSse(response.body, input.onFrame, signal)
+}
+
+function toUpstreamPayload(request: CodexCompletionRequestV1): Record<string, unknown> {
+ return {
+ model: request.model,
+ stream: true,
+ input: request.messages.map(message => ({
+ role: message.role,
+ content: message.content,
+ })),
+ tools: request.tools?.map(tool => ({
+ type: 'function',
+ name: tool.name,
+ description: tool.description,
+ parameters: tool.parameters,
+ })),
+ max_output_tokens: request.generation?.maxOutputTokens,
+ temperature: request.generation?.temperature,
+ }
+}
+
+async function consumeSse(
+ body: ReadableStream<Uint8Array>,
+ onFrame: ((frame: StreamFrame) => void) | undefined,
+ signal: AbortSignal
+): Promise<StreamCodexCompletionResult> {
+ const reader = body.getReader()
+ const decoder = new TextDecoder()
+ let buffer = ''
+ let completed = false
+ let usage: SafeUsage | undefined
+ try {
+ while (!signal.aborted) {
+ const { done, value } = await reader.read()
+ if (done) break
+ buffer += decoder.decode(value, { stream: true })
+ const parts = buffer.split('\n\n')
+ buffer = parts.pop() ?? ''
+ for (const part of parts) {
+ const dataLine = part
+ .split('\n')
+ .map(line => line.trim())
+ .find(line => line.startsWith('data:'))
+ if (!dataLine) continue
+ const payload = dataLine.slice(5).trim()
+ if (!payload || payload === '[DONE]') continue
+ let parsed: unknown
+ try {
+ parsed = JSON.parse(payload)
+ } catch {
+ continue
+ }
+ const mapped = mapUpstreamEvent(parsed)
+ if (mapped.frame) onFrame?.(mapped.frame)
+ if (mapped.usage) usage = mapped.usage
+ if (mapped.completed) completed = true
+ }
+ if (signal.aborted) break
+ }
+ } finally {
+ reader.releaseLock()
+ }
+ if (signal.aborted) return { outcome: 'canceled', usage }
+ if (completed) return { outcome: 'success', usage }
+ return { outcome: 'unknown', usage }
+}
+
+function mapUpstreamEvent(event: unknown): {
+ frame?: StreamFrame
+ usage?: SafeUsage
+ completed?: boolean
+} {
+ if (!event || typeof event !== 'object') return {}
+ const row = event as Record<string, unknown>
+ const type = String(row.type || '')
+ if (type === 'response.output_text.delta' && typeof row.delta === 'string') {
+ return { frame: { type: 'text', text: row.delta } }
+ }
+ if (type === 'response.output_item.added' && isPlainObject(row.item) && row.item.type === 'function_call') {
+ const args = parseToolArguments(row.item.arguments)
+ return {
+ frame: {
+ type: 'tool_call',
+ id: String(row.item.id || 'tool'),
+ name: String(row.item.name || 'tool'),
+ arguments: args,
+ },
+ }
+ }
+ if (type === 'response.completed') {
+ const response = isPlainObject(row.response) ? row.response : row
+ return { completed: true, usage: parseSafeUsage(response.usage) }
+ }
+ return {}
+}
+
+function parseToolArguments(raw: unknown): Record<string, unknown> {
+ if (isPlainObject(raw)) return raw
+ if (typeof raw !== 'string' || raw.length === 0) return {}
+ try {
+ const parsed = JSON.parse(raw)
+ return isPlainObject(parsed) ? parsed : {}
+ } catch {
+ return {}
+ }
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+ return typeof value === 'object' && value !== null && Array.isArray(value) === false
+}
+
+export async function listCodexModels(input: {
+ accessToken: string
+ fetchFn: typeof fetch
+ lookup?: OriginPolicyOptions['lookup']
+}): Promise<{ outcome: 'ready' | 'auth-rejected' | 'unavailable'; models: Array<{ model: string; displayName?: string }> }> {
+ const url = assertAllowedUpstreamUrl(CODEX_CATALOG_ORIGIN, 'catalog')
+ await assertResolvedUpstream(url, input.lookup)
+ const response = await input.fetchFn(url.href, {
+ method: 'GET',
+ redirect: 'manual',
+ headers: {
+ authorization: `Bearer ${input.accessToken}`,
+ accept: 'application/json',
+ },
+ })
+ if (response.status >= 300 && response.status < 400) {
+ assertRedirectLocation(response.headers.get('location') || '', url)
+ throw new OriginDeniedError('origin_denied')
+ }
+ if (response.status === 401 || response.status === 403) return { outcome: 'auth-rejected', models: [] }
+ if (!response.ok) return { outcome: 'unavailable', models: [] }
+ const body = (await response.json()) as unknown
+ return { outcome: 'ready', models: normalizeModels(body) }
+}
+
+export async function testCodexConnection(input: {
+ accessToken: string
+ fetchFn: typeof fetch
+ lookup?: OriginPolicyOptions['lookup']
+}): Promise<{ outcome: 'ready' | 'auth-rejected' | 'unavailable' }> {
+ const listed = await listCodexModels(input)
+ return { outcome: listed.outcome }
+}
+
+function normalizeModels(body: unknown): Array<{ model: string; displayName?: string }> {
+ const rows = Array.isArray(body)
+ ? body
+ : isPlainObject(body) && Array.isArray(body.models)
+ ? body.models
+ : isPlainObject(body) && Array.isArray(body.data)
+ ? body.data
+ : []
+ const models: Array<{ model: string; displayName?: string }> = []
+ for (const row of rows) {
+ if (!isPlainObject(row)) continue
+ const model = String(row.model || row.slug || row.id || '').trim()
+ if (!model) continue
+ const displayName = typeof row.displayName === 'string' ? row.displayName : typeof row.title === 'string' ? row.title : undefined
+ models.push(displayName ? { model, displayName } : { model })
+ }
+ return models
+}
diff --git a/codex-llm-proxy/src/config.ts b/codex-llm-proxy/src/config.ts
index cd78ce4ae..dee88f64e 100644
--- a/codex-llm-proxy/src/config.ts
+++ b/codex-llm-proxy/src/config.ts
@@ -8,6 +8,9 @@ export type CodexLlmProxyConfig = {
jwtIssuer: string
jwtPublicKey: string
executionEnabled: boolean
+ controlApiBaseUrl: string
+ controlApiServiceName: string
+ controlApiServiceToken: string
}
function requiredPositiveInt(name: string, raw: string | undefined, fallback?: number): number {
@@ -52,5 +55,8 @@ export function loadConfig(env: NodeJS.ProcessEnv = process.env): CodexLlmProxyC
jwtIssuer: env.CODEX_LLM_PROXY_JWT_ISSUER?.trim() || 'control-api',
jwtPublicKey: requiredPem('CODEX_LLM_PROXY_JWT_PUBLIC_KEY', env.CODEX_LLM_PROXY_JWT_PUBLIC_KEY),
executionEnabled: env.CODEX_LLM_PROXY_EXECUTION_ENABLED === 'true',
+ controlApiBaseUrl: env.CODEX_LLM_PROXY_CONTROL_API_URL?.trim() || '',
+ controlApiServiceName: env.CODEX_LLM_PROXY_CONTROL_API_SERVICE?.trim() || 'codex-llm-proxy',
+ controlApiServiceToken: env.CODEX_LLM_PROXY_CONTROL_API_TOKEN?.trim() || '',
}
}
diff --git a/codex-llm-proxy/src/controlApiClient.ts b/codex-llm-proxy/src/controlApiClient.ts
new file mode 100644
index 000000000..31deaed11
--- /dev/null
+++ b/codex-llm-proxy/src/controlApiClient.ts
@@ -0,0 +1,164 @@
+import { logger } from './logger.js'
+import {
+ CODEX_CATALOG_ORIGIN,
+ CODEX_COMPLETIONS_ORIGIN,
+ CODEX_TRANSPORT_PROTOCOL,
+} from './originPolicy.js'
+
+export type RedeemOperation = 'completion_stream' | 'completion_cancel' | 'connection_test'
+
+export type RedeemAttemptSuccess = {
+ accessToken: string
+ transport: {
+ protocolVersion: typeof CODEX_TRANSPORT_PROTOCOL
+ completionsOrigin: typeof CODEX_COMPLETIONS_ORIGIN
+ catalogOrigin: typeof CODEX_CATALOG_ORIGIN
+ operation: RedeemOperation
+ servedModel: string
+ maxStreamDurationMs: number
+ }
+ expiryClass: 'short_lived' | 'upstream_managed'
+ attemptReceipt: string
+}
+
+export type FinalizeAttemptSuccess = {
+ providerAttemptId: string
+ outcome: 'success' | 'canceled' | 'error' | 'unknown'
+ duplicate: boolean
+}
+
+export type ControlApiClientConfig = {
+ baseUrl: string
+ serviceName: string
+ serviceToken: string
+ fetchFn?: typeof fetch
+}
+
+export class ControlApiClientError extends Error {
+ constructor(
+ readonly code: string,
+ message: string
+ ) {
+ super(message)
+ this.name = 'ControlApiClientError'
+ }
+}
+
+export class ControlApiClient {
+ constructor(private readonly config: ControlApiClientConfig) {}
+
+ async redeem(input: {
+ executionTicket: string
+ requestHash: string
+ model?: string
+ hostRef?: string
+ operation: RedeemOperation
+ }): Promise<RedeemAttemptSuccess> {
+ const body = await this.post('/internal/llm/provider-attempts/redeem', {
+ executionTicket: input.executionTicket,
+ requestHash: input.requestHash,
+ model: input.model,
+ hostRef: input.hostRef,
+ operation: input.operation,
+ })
+ return parseRedeem(body)
+ }
+
+ async finalize(input: {
+ attemptReceipt: string
+ receipt: {
+ schemaVersion: 'codex-attempt-receipt.v1'
+ providerAttemptId: string
+ requestHash: string
+ outcome: 'success' | 'canceled' | 'error' | 'unknown'
+ usage?: { inputTokens?: number; outputTokens?: number }
+ }
+ }): Promise<FinalizeAttemptSuccess> {
+ const body = await this.post('/internal/llm/provider-attempts/finalize', {
+ attemptReceipt: input.attemptReceipt,
+ receipt: input.receipt,
+ })
+ if (!isPlainObject(body)) {
+ return { providerAttemptId: input.receipt.providerAttemptId, outcome: input.receipt.outcome, duplicate: false }
+ }
+ return {
+ providerAttemptId: String(body.providerAttemptId ?? input.receipt.providerAttemptId),
+ outcome:
+ body.outcome === 'canceled' || body.outcome === 'error' || body.outcome === 'unknown'
+ ? body.outcome
+ : 'success',
+ duplicate: body.duplicate === true,
+ }
+ }
+
+ private async post(path: string, payload: Record<string, unknown>): Promise<unknown> {
+ const base = this.config.baseUrl.replace(/\/+$/, '')
+ const fetchFn = this.config.fetchFn ?? fetch
+ const response = await fetchFn(`${base}${path.startsWith('/') ? path : `/${path}`}`, {
+ method: 'POST',
+ headers: {
+ 'content-type': 'application/json',
+ authorization: `Bearer ${this.config.serviceToken}`,
+ 'x-service-token': this.config.serviceName,
+ },
+ body: JSON.stringify(payload),
+ })
+ const raw = await response.text()
+ let parsed: unknown = null
+ if (raw) {
+ try {
+ parsed = JSON.parse(raw)
+ } catch {
+ parsed = null
+ }
+ }
+ if (!response.ok) {
+ const code =
+ isPlainObject(parsed) && typeof parsed.error === 'string' ? parsed.error : 'provider_unavailable'
+ logger.warn({ event: 'codex_proxy_control_api_denied', code, path }, 'control API request denied')
+ throw new ControlApiClientError(code, 'control API request denied')
+ }
+ return parsed
+ }
+}
+
+function parseRedeem(body: unknown): RedeemAttemptSuccess {
+ if (!isPlainObject(body) || typeof body.accessToken !== 'string' || !isPlainObject(body.transport)) {
+ throw new ControlApiClientError('provider_unavailable', 'redeem response is invalid')
+ }
+ const transport = body.transport
+ if (
+ transport.protocolVersion !== CODEX_TRANSPORT_PROTOCOL ||
+ transport.completionsOrigin !== CODEX_COMPLETIONS_ORIGIN ||
+ transport.catalogOrigin !== CODEX_CATALOG_ORIGIN ||
+ typeof transport.servedModel !== 'string'
+ ) {
+ throw new ControlApiClientError('origin_denied', 'redeem transport metadata is not frozen')
+ }
+ if (typeof body.attemptReceipt !== 'string' || !/^[a-f0-9]{64}$/.test(body.attemptReceipt)) {
+ throw new ControlApiClientError('provider_unavailable', 'attemptReceipt is invalid')
+ }
+ return {
+ accessToken: body.accessToken,
+ transport: {
+ protocolVersion: CODEX_TRANSPORT_PROTOCOL,
+ completionsOrigin: CODEX_COMPLETIONS_ORIGIN,
+ catalogOrigin: CODEX_CATALOG_ORIGIN,
+ operation:
+ transport.operation === 'completion_cancel' || transport.operation === 'connection_test'
+ ? transport.operation
+ : 'completion_stream',
+ servedModel: transport.servedModel,
+ maxStreamDurationMs:
+ typeof transport.maxStreamDurationMs === 'number' && Number.isFinite(transport.maxStreamDurationMs)
+ ? transport.maxStreamDurationMs
+ : 300_000,
+ },
+ expiryClass: body.expiryClass === 'upstream_managed' ? 'upstream_managed' : 'short_lived',
+ attemptReceipt: body.attemptReceipt,
+ }
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+ return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
diff --git a/codex-llm-proxy/src/metrics.ts b/codex-llm-proxy/src/metrics.ts
new file mode 100644
index 000000000..ce5b8a67c
--- /dev/null
+++ b/codex-llm-proxy/src/metrics.ts
@@ -0,0 +1,26 @@
+import { Counter, Histogram, Registry } from 'prom-client'
+
+export function createProxyMetrics(register: Registry) {
+ const outcomes = new Counter({
+ name: 'codex_llm_proxy_attempts_total',
+ help: 'Codex proxy attempt outcomes',
+ labelNames: ['outcome', 'operation'],
+ registers: [register],
+ })
+ const streamSeconds = new Histogram({
+ name: 'codex_llm_proxy_stream_duration_seconds',
+ help: 'Codex proxy stream duration',
+ buckets: [0.1, 0.5, 1, 2, 5, 15, 30, 60, 120, 300],
+ registers: [register],
+ })
+ return {
+ observeAttempt(outcome: string, operation: string) {
+ outcomes.inc({ outcome, operation })
+ },
+ observeStream(durationMs: number) {
+ streamSeconds.observe(durationMs / 1000)
+ },
+ }
+}
+
+export type ProxyMetrics = ReturnType<typeof createProxyMetrics>
diff --git a/codex-llm-proxy/src/originPolicy.ts b/codex-llm-proxy/src/originPolicy.ts
new file mode 100644
index 000000000..c06ac1b14
--- /dev/null
+++ b/codex-llm-proxy/src/originPolicy.ts
@@ -0,0 +1,117 @@
+export const CODEX_COMPLETIONS_ORIGIN = 'https://chatgpt.com/backend-api/codex/responses'
+export const CODEX_CATALOG_ORIGIN = 'https://chatgpt.com/backend-api/codex/models'
+export const CODEX_TRANSPORT_PROTOCOL = 'codex-subscription-transport.v1' as const
+
+export type UpstreamKind = 'completions' | 'catalog'
+
+export class OriginDeniedError extends Error {
+ readonly code = 'origin_denied'
+ constructor(message: string) {
+ super(message)
+ this.name = 'OriginDeniedError'
+ }
+}
+
+const FROZEN: Record<UpstreamKind, URL> = {
+ completions: new URL(CODEX_COMPLETIONS_ORIGIN),
+ catalog: new URL(CODEX_CATALOG_ORIGIN),
+}
+
+export type AddressLookup = () => Promise<Array<{ address: string; family: number }>>
+
+export type OriginPolicyOptions = {
+ lookup?: (hostname: string) => Promise<Array<{ address: string; family: number }>>
+}
+
+export function assertAllowedUpstreamUrl(raw: string, kind: UpstreamKind): URL {
+ let parsed: URL
+ try {
+ parsed = new URL(raw)
+ } catch {
+ throw new OriginDeniedError('origin_denied')
+ }
+ const frozen = FROZEN[kind]
+ if (parsed.protocol !== 'https:') throw new OriginDeniedError('origin_denied')
+ if (parsed.username || parsed.password) throw new OriginDeniedError('origin_denied')
+ if (parsed.hash) throw new OriginDeniedError('origin_denied')
+ if (parsed.search) throw new OriginDeniedError('origin_denied')
+ if (parsed.origin !== frozen.origin || parsed.pathname !== frozen.pathname) {
+ throw new OriginDeniedError('origin_denied')
+ }
+ if (isIpLiteral(parsed.hostname) || isBlockedHostname(parsed.hostname)) {
+ throw new OriginDeniedError('origin_denied')
+ }
+ return parsed
+}
+
+export async function assertResolvedUpstream(
+ url: URL,
+ lookup: OriginPolicyOptions['lookup']
+): Promise<void> {
+ if (!lookup) return
+ const records = await lookup(url.hostname)
+ if (!records.length) throw new OriginDeniedError('origin_denied')
+ for (const record of records) {
+ if (isBlockedAddress(record.address)) throw new OriginDeniedError('origin_denied')
+ }
+}
+
+export function assertRedirectLocation(location: string, from: URL): URL {
+ let next: URL
+ try {
+ next = new URL(location, from)
+ } catch {
+ throw new OriginDeniedError('origin_denied')
+ }
+ if (next.protocol !== 'https:') throw new OriginDeniedError('origin_denied')
+ if (next.origin !== from.origin) throw new OriginDeniedError('origin_denied')
+ if (isIpLiteral(next.hostname) || isBlockedHostname(next.hostname)) {
+ throw new OriginDeniedError('origin_denied')
+ }
+ if (next.pathname !== from.pathname) throw new OriginDeniedError('origin_denied')
+ return next
+}
+
+export function isBlockedAddress(address: string): boolean {
+ if (address.includes(':')) return isBlockedV6(address)
+ const parts = address.split('.').map(part => Number(part))
+ if (parts.length !== 4 || parts.some(part => !Number.isInteger(part) || part < 0 || part > 255)) {
+ return true
+ }
+ const [a, b] = parts
+ if (a === 0 || a === 10 || a === 127) return true
+ if (a === 169 && b === 254) return true
+ if (a === 172 && b >= 16 && b <= 31) return true
+ if (a === 192 && b === 168) return true
+ if (a === 192 && b === 0) return true
+ if (a === 198 && (b === 51 || b === 18)) return true
+ if (a === 203 && b === 113) return true
+ if (a >= 224) return true
+ return false
+}
+
+function isBlockedV6(address: string): boolean {
+ const normalized = address.toLowerCase()
+ return (
+ normalized === '::1' ||
+ normalized === '::' ||
+ normalized.startsWith('fc') ||
+ normalized.startsWith('fd') ||
+ normalized.startsWith('fe80') ||
+ normalized.startsWith('::ffff:')
+ )
+}
+
+function isIpLiteral(hostname: string): boolean {
+ return /^\d{1,3}(?:\.\d{1,3}){3}$/.test(hostname) || hostname.includes(':')
+}
+
+function isBlockedHostname(hostname: string): boolean {
+ const host = hostname.toLowerCase()
+ return (
+ host === 'localhost' ||
+ host.endsWith('.localhost') ||
+ host.endsWith('.local') ||
+ host.endsWith('.internal')
+ )
+}
diff --git a/codex-llm-proxy/src/requestLimits.ts b/codex-llm-proxy/src/requestLimits.ts
new file mode 100644
index 000000000..1d092b926
--- /dev/null
+++ b/codex-llm-proxy/src/requestLimits.ts
@@ -0,0 +1,60 @@
+import { LIMITS as CONTRACT_LIMITS } from '@clerum/llm-provider-attempt-contract'
+
+export const STREAM_LIMITS = {
+ maxConcurrentStreams: 8,
+ maxQueuedRequests: 16,
+ maxStreamDurationMs: 300_000,
+} as const
+
+export class RequestLimitError extends Error {
+ readonly code = 'provider_unavailable'
+ constructor(message: string) {
+ super(message)
+ this.name = 'RequestLimitError'
+ }
+}
+
+export function assertBoundedDeadline(deadlineMs: number | undefined, maxDeadlineMs: number): number {
+ const requested = deadlineMs ?? Math.min(maxDeadlineMs, STREAM_LIMITS.maxStreamDurationMs)
+ if (!Number.isFinite(requested) || !Number.isInteger(requested) || requested <= 0) {
+ throw new RequestLimitError('deadline is invalid')
+ }
+ return Math.min(requested, maxDeadlineMs, STREAM_LIMITS.maxStreamDurationMs, CONTRACT_LIMITS.maxDeadlineMs)
+}
+
+export class StreamGate {
+ private running = 0
+ private queued = 0
+
+ constructor(
+ private readonly maxConcurrent = STREAM_LIMITS.maxConcurrentStreams,
+ private readonly maxQueued = STREAM_LIMITS.maxQueuedRequests
+ ) {}
+
+ async acquire(): Promise<() => void> {
+ if (this.running >= this.maxConcurrent) {
+ if (this.queued >= this.maxQueued) throw new RequestLimitError('stream queue is full')
+ this.queued += 1
+ try {
+ await new Promise<void>(resolve => {
+ const wait = () => {
+ if (this.running < this.maxConcurrent) {
+ resolve()
+ return
+ }
+ setTimeout(wait, 10)
+ }
+ wait()
+ })
+ } finally {
+ this.queued -= 1
+ }
+ }
+ this.running += 1
+ return () => {
+ this.running = Math.max(0, this.running - 1)
+ }
+ }
+}
+
+export const streamGate = new StreamGate()
diff --git a/codex-llm-proxy/src/server.ts b/codex-llm-proxy/src/server.ts
index 7aa423983..7d57a77e9 100644
--- a/codex-llm-proxy/src/server.ts
+++ b/codex-llm-proxy/src/server.ts
@@ -5,15 +5,21 @@ import { z } from 'zod'
import { verifyAdminPermit } from './auth/adminPermitVerifier.js'
import { verifyExecutionTicket } from './auth/executionTicketVerifier.js'
import { verifyPlatformJwt } from './auth/platformJwtVerifier.js'
+import {
+ CodexTransportError,
+ listCodexModels,
+ streamCodexCompletion,
+ testCodexConnection,
+} from './codexTransport.js'
import type { CodexLlmProxyConfig } from './config.js'
+import { ControlApiClient, ControlApiClientError } from './controlApiClient.js'
import { logger } from './logger.js'
+import { createProxyMetrics } from './metrics.js'
+import { OriginDeniedError } from './originPolicy.js'
+import { RequestLimitError, streamGate } from './requestLimits.js'
-const COMPLETION_KEYS = new Set([
- 'executionTicket',
- 'requestHash',
- 'request',
- 'deadlineMs',
-])
+const COMPLETION_KEYS = new Set(['executionTicket', 'requestHash', 'request', 'deadlineMs'])
+const ADMIN_KEYS = new Set(['accessToken'])
const completionBodySchema = z
.object({
@@ -24,12 +30,15 @@ const completionBodySchema = z
})
.strict()
+const adminBodySchema = z.object({ accessToken: z.string().min(1) }).strict()
+
function bearer(req: Request): string {
const raw = String(req.header('authorization') || '')
return raw.replace(/^bearer\s+/i, '').trim()
}
function reject(res: Response, status: number, code: string): void {
+ if (res.headersSent) return
logger.warn({ event: 'codex_proxy_denied', code }, 'request denied')
res.status(status).json({ error: code })
}
@@ -48,6 +57,11 @@ function boundedErrorHandler(err: unknown, _req: Request, res: Response, _next:
reject(res, 500, 'internal_error')
}
+export type ProxyRuntimeDeps = {
+ controlApiClient?: ControlApiClient
+ fetchFn?: typeof fetch
+}
+
export type ProxyServers = {
runtime: Server
admin: Server
@@ -58,9 +72,18 @@ export type ProxyServers = {
close: () => Promise<void>
}
-export function createProxyApps(config: CodexLlmProxyConfig): ProxyServers {
- const metrics = new Registry()
- collectDefaultMetrics({ register: metrics })
+export function createProxyApps(config: CodexLlmProxyConfig, deps: ProxyRuntimeDeps = {}): ProxyServers {
+ const metricsRegistry = new Registry()
+ collectDefaultMetrics({ register: metricsRegistry })
+ const metrics = createProxyMetrics(metricsRegistry)
+ const client =
+ deps.controlApiClient ??
+ new ControlApiClient({
+ baseUrl: config.controlApiBaseUrl,
+ serviceName: config.controlApiServiceName,
+ serviceToken: config.controlApiServiceToken,
+ })
+ const fetchFn = deps.fetchFn ?? fetch
const runtimeApp = express()
runtimeApp.use(express.json({ limit: config.maxBodyBytes }))
@@ -101,14 +124,56 @@ export function createProxyApps(config: CodexLlmProxyConfig): ProxyServers {
reject(res, 404, 'disabled')
return
}
- reject(res, 503, 'provider_unavailable')
+
+ void (async () => {
+ const release = await streamGate.acquire()
+ const abort = new AbortController()
+ req.on('close', () => abort.abort())
+ try {
+ res.status(200)
+ res.setHeader('content-type', 'text/event-stream')
+ res.setHeader('cache-control', 'no-cache')
+ const started = Date.now()
+ const result = await streamCodexCompletion({
+ executionTicket: parsed.data.executionTicket,
+ requestHash: parsed.data.requestHash,
+ request: parsed.data.request,
+ deadlineMs: parsed.data.deadlineMs,
+ maxDeadlineMs: config.maxDeadlineMs,
+ ticket: {
+ jti: ticket.jti,
+ hostRef: ticket.hostRef,
+ model: ticket.model,
+ requestHash: ticket.requestHash,
+ providerAttemptId: ticket.providerAttemptId,
+ },
+ signal: abort.signal,
+ redeem: input => client.redeem(input),
+ finalize: input => client.finalize(input),
+ fetchFn,
+ onFrame: frame => {
+ res.write(`data: ${JSON.stringify(frame)}\n\n`)
+ },
+ })
+ res.write(`data: ${JSON.stringify({ type: 'done', outcome: result.outcome })}\n\n`)
+ metrics.observeAttempt(result.outcome, 'completion_stream')
+ metrics.observeStream(Date.now() - started)
+ res.end()
+ } catch (err) {
+ const mapped = mapError(err)
+ metrics.observeAttempt('error', 'completion_stream')
+ reject(res, mapped.status, mapped.code)
+ } finally {
+ release()
+ }
+ })()
})
runtimeApp.use((_req, res) => reject(res, 404, 'not_found'))
runtimeApp.use(boundedErrorHandler)
const adminApp = express()
adminApp.use(express.json({ limit: config.maxBodyBytes }))
- const adminHandler = (req: Request, res: Response) => {
+ const adminHandler = (kind: 'models' | 'test') => (req: Request, res: Response) => {
if (!req.is('application/json')) {
reject(res, 415, 'unsupported_media_type')
return
@@ -125,10 +190,33 @@ export function createProxyApps(config: CodexLlmProxyConfig): ProxyServers {
reject(res, 404, 'disabled')
return
}
- reject(res, 503, 'provider_unavailable')
+ const extra = Object.keys(req.body ?? {}).find(key => !ADMIN_KEYS.has(key))
+ if (extra) {
+ reject(res, 400, 'unknown_field')
+ return
+ }
+ const parsed = adminBodySchema.safeParse(req.body)
+ if (!parsed.success) {
+ reject(res, 400, 'invalid_request')
+ return
+ }
+ void (async () => {
+ try {
+ if (kind === 'models') {
+ const listed = await listCodexModels({ accessToken: parsed.data.accessToken, fetchFn })
+ res.status(200).json(listed)
+ return
+ }
+ const tested = await testCodexConnection({ accessToken: parsed.data.accessToken, fetchFn })
+ res.status(200).json(tested)
+ } catch (err) {
+ const mapped = mapError(err)
+ reject(res, mapped.status, mapped.code)
+ }
+ })()
}
- adminApp.post('/internal/admin/v1/codex/models', adminHandler)
- adminApp.post('/internal/admin/v1/codex/test', adminHandler)
+ adminApp.post('/internal/admin/v1/codex/models', adminHandler('models'))
+ adminApp.post('/internal/admin/v1/codex/test', adminHandler('test'))
adminApp.use((_req, res) => reject(res, 404, 'not_found'))
adminApp.use(boundedErrorHandler)
@@ -136,8 +224,8 @@ export function createProxyApps(config: CodexLlmProxyConfig): ProxyServers {
probeApp.get('/healthz', (_req, res) => res.status(200).json({ ok: true }))
probeApp.get('/readyz', (_req, res) => res.status(200).json({ ok: true }))
probeApp.get('/metrics', async (_req, res) => {
- res.set('content-type', metrics.contentType)
- res.status(200).send(await metrics.metrics())
+ res.set('content-type', metricsRegistry.contentType)
+ res.status(200).send(await metricsRegistry.metrics())
})
probeApp.use((_req, res) => reject(res, 404, 'not_found'))
@@ -175,6 +263,23 @@ export function startProxy(config: CodexLlmProxyConfig): ProxyServers {
return servers
}
+function mapError(err: unknown): { status: number; code: string } {
+ if (err instanceof OriginDeniedError) return { status: 403, code: 'origin_denied' }
+ if (err instanceof RequestLimitError) return { status: 503, code: 'provider_unavailable' }
+ if (err instanceof CodexTransportError || err instanceof ControlApiClientError) {
+ const status =
+ err.code === 'request_hash_mismatch' || err.code === 'ticket_invalid' || err.code === 'model_not_allowed'
+ ? 403
+ : err.code === 'disabled'
+ ? 404
+ : err.code === 'ticket_replayed'
+ ? 409
+ : 503
+ return { status, code: err.code }
+ }
+ return { status: 503, code: 'provider_unavailable' }
+}
+
function closeServer(server: Server): Promise<void> {
return new Promise(resolve => {
server.close(() => resolve())
diff --git a/codex-llm-proxy/src/usage.ts b/codex-llm-proxy/src/usage.ts
new file mode 100644
index 000000000..d935531ce
--- /dev/null
+++ b/codex-llm-proxy/src/usage.ts
@@ -0,0 +1,20 @@
+export type SafeUsage = { inputTokens?: number; outputTokens?: number }
+
+export function parseSafeUsage(input: unknown): SafeUsage | undefined {
+ if (!input || typeof input !== 'object' || Array.isArray(input)) return undefined
+ const row = input as Record<string, unknown>
+ const inputTokens = asNonNegativeInt(row.input_tokens ?? row.inputTokens ?? row.prompt_tokens)
+ const outputTokens = asNonNegativeInt(row.output_tokens ?? row.outputTokens ?? row.completion_tokens)
+ if (inputTokens === undefined && outputTokens === undefined) return undefined
+ const usage: SafeUsage = {}
+ if (inputTokens !== undefined) usage.inputTokens = inputTokens
+ if (outputTokens !== undefined) usage.outputTokens = outputTokens
+ return usage
+}
+
+function asNonNegativeInt(value: unknown): number | undefined {
+ if (typeof value !== 'number' || !Number.isFinite(value) || !Number.isInteger(value) || value < 0) {
+ return undefined
+ }
+ return value
+}
diff --git a/codex-llm-proxy/test/codexTransport.conformance.test.ts b/codex-llm-proxy/test/codexTransport.conformance.test.ts
new file mode 100644
index 000000000..4a9d67807
--- /dev/null
+++ b/codex-llm-proxy/test/codexTransport.conformance.test.ts
@@ -0,0 +1,272 @@
+import { hashCodexCompletionRequestV1 } from '@clerum/llm-provider-attempt-contract'
+import { describe, expect, it, vi } from 'vitest'
+import { CodexTransportError, streamCodexCompletion } from '../src/codexTransport.js'
+import type { RedeemAttemptSuccess } from '../src/controlApiClient.js'
+import { CODEX_COMPLETIONS_ORIGIN } from '../src/originPolicy.js'
+
+const REQUEST = {
+ schemaVersion: 'codex-completion-request.v1' as const,
+ requestId: 'req-001',
+ idempotencyKey: 'idem-001',
+ provider: 'codex-subscription' as const,
+ model: 'gpt-5.1',
+ messages: [{ role: 'user' as const, content: 'hello' }],
+}
+
+const REQUEST_HASH = hashCodexCompletionRequestV1(REQUEST)
+
+function redeemSuccess(overrides: Partial<RedeemAttemptSuccess> = {}): RedeemAttemptSuccess {
+ return {
+ accessToken: 'tok-live',
+ transport: {
+ protocolVersion: 'codex-subscription-transport.v1',
+ completionsOrigin: CODEX_COMPLETIONS_ORIGIN,
+ catalogOrigin: 'https://chatgpt.com/backend-api/codex/models',
+ operation: 'completion_stream',
+ servedModel: 'gpt-5.1',
+ maxStreamDurationMs: 300_000,
+ },
+ expiryClass: 'short_lived',
+ attemptReceipt: 'a'.repeat(64),
+ ...overrides,
+ }
+}
+
+function sseResponse(frames: string[], status = 200, headers: Record<string, string> = {}): Response {
+ return new Response(frames.join(''), {
+ status,
+ headers: { 'content-type': 'text/event-stream', ...headers },
+ })
+}
+
+describe('streamCodexCompletion', () => {
+ it('validates ticket bindings before redeem and maps stream frames including tool-call data', async () => {
+ const redeem = vi.fn(async () => redeemSuccess())
+ const finalize = vi.fn(async () => ({
+ providerAttemptId: 'att-1',
+ outcome: 'success' as const,
+ duplicate: false,
+ }))
+ const frames: unknown[] = []
+ const fetchFn = vi.fn(async (url: string) => {
+ expect(url).toBe(CODEX_COMPLETIONS_ORIGIN)
+ return sseResponse([
+ 'data: {"type":"response.output_text.delta","delta":"hi"}\n\n',
+ 'data: {"type":"response.output_item.added","item":{"type":"function_call","id":"call-1","name":"lookup","arguments":"{\\"q\\":\\"x\\"}"}}\n\n',
+ 'data: {"type":"response.completed","response":{"usage":{"input_tokens":3,"output_tokens":2}}}\n\n',
+ ])
+ })
+
+ const result = await streamCodexCompletion({
+ executionTicket: 'ticket-1',
+ requestHash: REQUEST_HASH,
+ request: REQUEST,
+ ticket: {
+ jti: '11111111-1111-4111-8111-111111111111',
+ hostRef: 'research-host',
+ model: 'gpt-5.1',
+ requestHash: REQUEST_HASH,
+ providerAttemptId: 'att-1',
+ },
+ redeem,
+ finalize,
+ fetchFn,
+ lookup: async () => [{ address: '1.2.3.4', family: 4 }],
+ onFrame: frame => frames.push(frame),
+ })
+
+ expect(redeem).toHaveBeenCalledOnce()
+ expect(fetchFn).toHaveBeenCalledOnce()
+ expect(frames).toEqual(
+ expect.arrayContaining([
+ { type: 'text', text: 'hi' },
+ { type: 'tool_call', id: 'call-1', name: 'lookup', arguments: { q: 'x' } },
+ ])
+ )
+ expect(result.outcome).toBe('success')
+ expect(result.usage).toEqual({ inputTokens: 3, outputTokens: 2 })
+ expect(finalize).toHaveBeenCalledWith(
+ expect.objectContaining({
+ attemptReceipt: 'a'.repeat(64),
+ receipt: expect.objectContaining({ outcome: 'success', requestHash: REQUEST_HASH }),
+ })
+ )
+ expect(String(fetchFn.mock.calls[0]?.[1]?.headers?.['authorization'])).toContain('tok-live')
+ })
+
+ it('rejects a mutated requestHash before redeem', async () => {
+ const redeem = vi.fn()
+ await expect(
+ streamCodexCompletion({
+ executionTicket: 'ticket-1',
+ requestHash: 'f'.repeat(64),
+ request: REQUEST,
+ ticket: {
+ jti: 'jti-1',
+ hostRef: 'research-host',
+ model: 'gpt-5.1',
+ requestHash: REQUEST_HASH,
+ providerAttemptId: 'att-1',
+ },
+ redeem,
+ finalize: vi.fn(),
+ fetchFn: vi.fn(),
+ })
+ ).rejects.toMatchObject({ code: 'request_hash_mismatch' } satisfies Partial<CodexTransportError>)
+ expect(redeem).not.toHaveBeenCalled()
+ })
+
+ it('rejects a served-model mismatch and loopback redirects', async () => {
+ await expect(
+ streamCodexCompletion({
+ executionTicket: 'ticket-1',
+ requestHash: REQUEST_HASH,
+ request: REQUEST,
+ ticket: {
+ jti: 'jti-1',
+ hostRef: 'research-host',
+ model: 'gpt-5.1',
+ requestHash: REQUEST_HASH,
+ providerAttemptId: 'att-1',
+ },
+ redeem: async () => redeemSuccess({ transport: { ...redeemSuccess().transport, servedModel: 'other' } }),
+ finalize: vi.fn(async () => ({ providerAttemptId: 'att-1', outcome: 'error', duplicate: false })),
+ fetchFn: vi.fn(),
+ })
+ ).rejects.toMatchObject({ code: 'model_not_allowed' })
+
+ const fetchFn = vi.fn(async () =>
+ new Response(null, {
+ status: 302,
+ headers: { location: 'https://127.0.0.1/steal' },
+ })
+ )
+ await expect(
+ streamCodexCompletion({
+ executionTicket: 'ticket-1',
+ requestHash: REQUEST_HASH,
+ request: REQUEST,
+ ticket: {
+ jti: 'jti-1',
+ hostRef: 'research-host',
+ model: 'gpt-5.1',
+ requestHash: REQUEST_HASH,
+ providerAttemptId: 'att-1',
+ },
+ redeem: async () => redeemSuccess(),
+ finalize: vi.fn(async () => ({ providerAttemptId: 'att-1', outcome: 'error', duplicate: false })),
+ fetchFn,
+ lookup: async () => [{ address: '1.2.3.4', family: 4 }],
+ })
+ ).rejects.toMatchObject({ code: 'origin_denied' })
+ })
+
+ it('finalizes canceled after the first frame and treats finalize 500 as idempotent retry', async () => {
+ const abort = new AbortController()
+ const finalize = vi
+ .fn()
+ .mockRejectedValueOnce(new Error('finalize 500'))
+ .mockResolvedValueOnce({ providerAttemptId: 'att-1', outcome: 'canceled', duplicate: true })
+ const fetchFn = vi.fn(async () => {
+ const stream = new ReadableStream({
+ start(controller) {
+ controller.enqueue(
+ new TextEncoder().encode('data: {"type":"response.output_text.delta","delta":"x"}\n\n')
+ )
+ setTimeout(() => controller.close(), 20)
+ },
+ })
+ return new Response(stream, { headers: { 'content-type': 'text/event-stream' } })
+ })
+
+ const frames: unknown[] = []
+ const result = await streamCodexCompletion({
+ executionTicket: 'ticket-1',
+ requestHash: REQUEST_HASH,
+ request: REQUEST,
+ ticket: {
+ jti: 'jti-1',
+ hostRef: 'research-host',
+ model: 'gpt-5.1',
+ requestHash: REQUEST_HASH,
+ providerAttemptId: 'att-1',
+ },
+ signal: abort.signal,
+ redeem: async () => redeemSuccess(),
+ finalize,
+ fetchFn,
+ lookup: async () => [{ address: '1.2.3.4', family: 4 }],
+ onFrame: frame => {
+ frames.push(frame)
+ abort.abort()
+ },
+ })
+ expect(frames[0]).toEqual({ type: 'text', text: 'x' })
+ expect(result.outcome).toBe('canceled')
+ expect(finalize).toHaveBeenCalledTimes(2)
+ expect(finalize.mock.calls[0]?.[0]?.receipt.outcome).toBe('canceled')
+ })
+
+ it('does not reuse a redeemed access token across requests', async () => {
+ const tokens: string[] = []
+ const redeem = vi.fn(async (input: { executionTicket: string }) => {
+ tokens.push(input.executionTicket)
+ return redeemSuccess({ accessToken: `tok-${input.executionTicket}` })
+ })
+ const fetchFn = vi.fn(async () =>
+ sseResponse(['data: {"type":"response.completed","response":{"usage":{}}}\n\n'])
+ )
+ const ticket = {
+ jti: 'jti-1',
+ hostRef: 'research-host',
+ model: 'gpt-5.1',
+ requestHash: REQUEST_HASH,
+ providerAttemptId: 'att-1',
+ }
+ await streamCodexCompletion({
+ executionTicket: 't-a',
+ requestHash: REQUEST_HASH,
+ request: REQUEST,
+ ticket,
+ redeem,
+ finalize: vi.fn(async () => ({ providerAttemptId: 'att-1', outcome: 'success', duplicate: false })),
+ fetchFn,
+ lookup: async () => [{ address: '1.2.3.4', family: 4 }],
+ })
+ await streamCodexCompletion({
+ executionTicket: 't-b',
+ requestHash: REQUEST_HASH,
+ request: REQUEST,
+ ticket,
+ redeem,
+ finalize: vi.fn(async () => ({ providerAttemptId: 'att-1', outcome: 'success', duplicate: false })),
+ fetchFn,
+ lookup: async () => [{ address: '1.2.3.4', family: 4 }],
+ })
+ expect(tokens).toEqual(['t-a', 't-b'])
+ expect(String(fetchFn.mock.calls[0]?.[1]?.headers?.['authorization'])).toContain('tok-t-a')
+ expect(String(fetchFn.mock.calls[1]?.[1]?.headers?.['authorization'])).toContain('tok-t-b')
+ })
+
+ it('does not retry after an ambiguous upstream response', async () => {
+ const fetchFn = vi.fn(async () => sseResponse(['data: {"type":"response.output_text.delta","delta":"partial"}\n\n']))
+ const result = await streamCodexCompletion({
+ executionTicket: 'ticket-1',
+ requestHash: REQUEST_HASH,
+ request: REQUEST,
+ ticket: {
+ jti: 'jti-1',
+ hostRef: 'research-host',
+ model: 'gpt-5.1',
+ requestHash: REQUEST_HASH,
+ providerAttemptId: 'att-1',
+ },
+ redeem: async () => redeemSuccess(),
+ finalize: vi.fn(async () => ({ providerAttemptId: 'att-1', outcome: 'unknown', duplicate: false })),
+ fetchFn,
+ lookup: async () => [{ address: '1.2.3.4', family: 4 }],
+ })
+ expect(result.outcome).toBe('unknown')
+ expect(fetchFn).toHaveBeenCalledOnce()
+ })
+})
diff --git a/codex-llm-proxy/test/controlApiClient.test.ts b/codex-llm-proxy/test/controlApiClient.test.ts
new file mode 100644
index 000000000..dba9ca3d2
--- /dev/null
+++ b/codex-llm-proxy/test/controlApiClient.test.ts
@@ -0,0 +1,127 @@
+import { createServer, type IncomingMessage, type Server } from 'node:http'
+import { describe, expect, it } from 'vitest'
+import { ControlApiClient, ControlApiClientError } from '../src/controlApiClient.js'
+
+function listen(handler: (req: IncomingMessage, body: unknown, res: Server) => void): Promise<{
+ url: string
+ close: () => Promise<void>
+ requests: Array<{ url: string; headers: IncomingMessage['headers']; body: unknown }>
+}> {
+ const requests: Array<{ url: string; headers: IncomingMessage['headers']; body: unknown }> = []
+ const server = createServer((req, res) => {
+ const chunks: Buffer[] = []
+ req.on('data', chunk => chunks.push(Buffer.from(chunk)))
+ req.on('end', () => {
+ const raw = Buffer.concat(chunks).toString('utf8')
+ const body = raw ? JSON.parse(raw) : {}
+ requests.push({ url: String(req.url), headers: req.headers, body })
+ handler(req, body, res as unknown as Server)
+ if (!res.writableEnded) {
+ res.statusCode = 200
+ res.setHeader('content-type', 'application/json')
+ res.end(
+ JSON.stringify({
+ accessToken: 'tok-live',
+ transport: {
+ protocolVersion: 'codex-subscription-transport.v1',
+ completionsOrigin: 'https://chatgpt.com/backend-api/codex/responses',
+ catalogOrigin: 'https://chatgpt.com/backend-api/codex/models',
+ operation: 'completion_stream',
+ servedModel: 'gpt-5.1',
+ maxStreamDurationMs: 300000,
+ },
+ expiryClass: 'short_lived',
+ attemptReceipt: 'a'.repeat(64),
+ })
+ )
+ }
+ })
+ })
+ return new Promise(resolve => {
+ server.listen(0, '127.0.0.1', () => {
+ const addr = server.address()
+ const port = typeof addr === 'object' && addr ? addr.port : 0
+ resolve({
+ url: `http://127.0.0.1:${port}`,
+ requests,
+ close: () =>
+ new Promise(done => {
+ server.close(() => done())
+ }),
+ })
+ })
+ })
+}
+
+describe('ControlApiClient', () => {
+ it('redeems and finalizes with the dedicated service identity and no token cache', async () => {
+ const seenTokens: string[] = []
+ const server = await listen((req, body, res) => {
+ if (String(req.url).endsWith('/redeem')) {
+ seenTokens.push(String((body as { executionTicket: string }).executionTicket))
+ }
+ })
+ try {
+ const client = new ControlApiClient({
+ baseUrl: `${server.url}/api/v1`,
+ serviceName: 'codex-llm-proxy',
+ serviceToken: 'dev-codex-llm-proxy-token',
+ })
+ const first = await client.redeem({
+ executionTicket: 'ticket-1',
+ requestHash: 'b'.repeat(64),
+ model: 'gpt-5.1',
+ operation: 'completion_stream',
+ })
+ const second = await client.redeem({
+ executionTicket: 'ticket-2',
+ requestHash: 'c'.repeat(64),
+ model: 'gpt-5.1',
+ operation: 'completion_stream',
+ })
+ expect(first.accessToken).toBe('tok-live')
+ expect(second.accessToken).toBe('tok-live')
+ expect(seenTokens).toEqual(['ticket-1', 'ticket-2'])
+ expect(server.requests[0]?.headers['x-service-token']).toBe('codex-llm-proxy')
+ expect(String(server.requests[0]?.headers.authorization)).toContain('dev-codex-llm-proxy-token')
+
+ const finalized = await client.finalize({
+ attemptReceipt: 'a'.repeat(64),
+ receipt: {
+ schemaVersion: 'codex-attempt-receipt.v1',
+ providerAttemptId: 'att-1',
+ requestHash: 'b'.repeat(64),
+ outcome: 'success',
+ },
+ })
+ expect(finalized).toMatchObject({ outcome: 'success' })
+ expect(server.requests.some(item => item.url?.includes('/finalize'))).toBe(true)
+ } finally {
+ await server.close()
+ }
+ })
+
+ it('maps redeem failures to bounded codes and never retries an ambiguous attempt', async () => {
+ const server = await listen((req, _body, res) => {
+ ;(res as unknown as { statusCode: number; setHeader: Function; end: Function }).statusCode = 409
+ ;(res as unknown as { setHeader: Function }).setHeader('content-type', 'application/json')
+ ;(res as unknown as { end: Function }).end(JSON.stringify({ error: 'ticket_replayed' }))
+ })
+ try {
+ const client = new ControlApiClient({
+ baseUrl: `${server.url}/api/v1`,
+ serviceName: 'codex-llm-proxy',
+ serviceToken: 'dev-codex-llm-proxy-token',
+ })
+ await expect(
+ client.redeem({
+ executionTicket: 'replay',
+ requestHash: 'd'.repeat(64),
+ operation: 'completion_stream',
+ })
+ ).rejects.toMatchObject({ code: 'ticket_replayed' } satisfies Partial<ControlApiClientError>)
+ } finally {
+ await server.close()
+ }
+ })
+})
diff --git a/codex-llm-proxy/test/originPolicy.test.ts b/codex-llm-proxy/test/originPolicy.test.ts
new file mode 100644
index 000000000..31894e404
--- /dev/null
+++ b/codex-llm-proxy/test/originPolicy.test.ts
@@ -0,0 +1,70 @@
+import { describe, expect, it } from 'vitest'
+import {
+ CODEX_CATALOG_ORIGIN,
+ CODEX_COMPLETIONS_ORIGIN,
+ OriginDeniedError,
+ assertAllowedUpstreamUrl,
+ assertRedirectLocation,
+} from '../src/originPolicy.js'
+
+describe('originPolicy', () => {
+ it('accepts only the frozen HTTPS catalog and completions URLs', () => {
+ expect(assertAllowedUpstreamUrl(CODEX_COMPLETIONS_ORIGIN, 'completions').href).toBe(
+ CODEX_COMPLETIONS_ORIGIN
+ )
+ expect(assertAllowedUpstreamUrl(CODEX_CATALOG_ORIGIN, 'catalog').href).toBe(CODEX_CATALOG_ORIGIN)
+ })
+
+ it('rejects caller-supplied, HTTP, billing, loopback, and metadata URLs', () => {
+ expect(() =>
+ assertAllowedUpstreamUrl('https://api.openai.com/v1/chat/completions', 'completions')
+ ).toThrow(OriginDeniedError)
+ expect(() => assertAllowedUpstreamUrl('http://chatgpt.com/backend-api/codex/responses', 'completions')).toThrow(
+ /origin_denied/
+ )
+ expect(() => assertAllowedUpstreamUrl('https://127.0.0.1/backend-api/codex/responses', 'completions')).toThrow(
+ OriginDeniedError
+ )
+ expect(() => assertAllowedUpstreamUrl('https://169.254.169.254/', 'catalog')).toThrow(OriginDeniedError)
+ expect(() => assertAllowedUpstreamUrl('https://chatgpt.com/backend-api/codex/responses?hijack=1', 'completions')).toThrow(
+ OriginDeniedError
+ )
+ })
+
+ it('rejects cross-origin and private-address redirects', () => {
+ expect(() =>
+ assertRedirectLocation('https://evil.example/cb', new URL(CODEX_COMPLETIONS_ORIGIN))
+ ).toThrow(OriginDeniedError)
+ expect(() =>
+ assertRedirectLocation('https://127.0.0.1/loopback', new URL(CODEX_COMPLETIONS_ORIGIN))
+ ).toThrow(OriginDeniedError)
+ expect(() =>
+ assertRedirectLocation('http://chatgpt.com/backend-api/codex/responses', new URL(CODEX_COMPLETIONS_ORIGIN))
+ ).toThrow(OriginDeniedError)
+ expect(
+ assertRedirectLocation(
+ 'https://chatgpt.com/backend-api/codex/responses',
+ new URL(CODEX_COMPLETIONS_ORIGIN)
+ ).href
+ ).toBe(CODEX_COMPLETIONS_ORIGIN)
+ })
+
+ it('rejects DNS rebinding onto private or metadata addresses', async () => {
+ const { assertResolvedUpstream } = await import('../src/originPolicy.js')
+ await expect(
+ assertResolvedUpstream(new URL(CODEX_COMPLETIONS_ORIGIN), async () => [
+ { address: '127.0.0.1', family: 4 },
+ ])
+ ).rejects.toBeInstanceOf(OriginDeniedError)
+ await expect(
+ assertResolvedUpstream(new URL(CODEX_COMPLETIONS_ORIGIN), async () => [
+ { address: '169.254.169.254', family: 4 },
+ ])
+ ).rejects.toBeInstanceOf(OriginDeniedError)
+ await expect(
+ assertResolvedUpstream(new URL(CODEX_COMPLETIONS_ORIGIN), async () => [
+ { address: '1.2.3.4', family: 4 },
+ ])
+ ).resolves.toBeUndefined()
+ })
+})
diff --git a/codex-llm-proxy/test/redaction.test.ts b/codex-llm-proxy/test/redaction.test.ts
new file mode 100644
index 000000000..ea80a8725
--- /dev/null
+++ b/codex-llm-proxy/test/redaction.test.ts
@@ -0,0 +1,48 @@
+import pino from 'pino'
+import { describe, expect, it } from 'vitest'
+import { logger } from '../src/logger.js'
+
+describe('proxy redaction', () => {
+ it('strips access tokens, tickets, receipts, and authorization headers', () => {
+ const messages: string[] = []
+ const stream = {
+ write(chunk: string) {
+ messages.push(chunk)
+ },
+ }
+ const child = pino(
+ {
+ level: 'info',
+ redact: {
+ paths: [
+ 'accessToken',
+ 'refreshToken',
+ 'executionTicket',
+ 'authorization',
+ 'headers.authorization',
+ 'attemptReceipt',
+ ],
+ remove: true,
+ },
+ },
+ stream
+ )
+ child.info({
+ accessToken: 'sk-live-secret',
+ refreshToken: 'rt-secret',
+ executionTicket: 'ticket-secret',
+ attemptReceipt: 'receipt-secret',
+ authorization: 'Bearer secret',
+ headers: { authorization: 'Bearer secret' },
+ event: 'codex_proxy_probe',
+ })
+ const joined = messages.join('\n')
+ expect(joined).toContain('codex_proxy_probe')
+ expect(joined).not.toContain('sk-live-secret')
+ expect(joined).not.toContain('rt-secret')
+ expect(joined).not.toContain('ticket-secret')
+ expect(joined).not.toContain('receipt-secret')
+ expect(joined).not.toContain('Bearer secret')
+ expect(logger.bindings()).toMatchObject({ svc: 'codex-llm-proxy' })
+ })
+})
diff --git a/codex-llm-proxy/test/server.security.test.ts b/codex-llm-proxy/test/server.security.test.ts
index b510fb5aa..cb494c4fd 100644
--- a/codex-llm-proxy/test/server.security.test.ts
+++ b/codex-llm-proxy/test/server.security.test.ts
@@ -22,6 +22,9 @@ function config(overrides: Partial<CodexLlmProxyConfig> = {}): CodexLlmProxyConf
jwtIssuer: 'control-api',
jwtPublicKey: publicKey,
executionEnabled: true,
+ controlApiBaseUrl: '',
+ controlApiServiceName: 'codex-llm-proxy',
+ controlApiServiceToken: '',
...overrides,
}
}
@@ -54,6 +57,7 @@ function ticket(): string {
hostRef: 'research-host',
model: 'gpt-5.1',
requestHash: 'a'.repeat(64),
+ providerAttemptId: 'att-1',
},
'codex-llm-proxy'
)
diff --git a/control-api/src/routes/admin/codexSubscription.ts b/control-api/src/routes/admin/codexSubscription.ts
index 95341f264..b1bb6af4d 100644
--- a/control-api/src/routes/admin/codexSubscription.ts
+++ b/control-api/src/routes/admin/codexSubscription.ts
@@ -6,7 +6,7 @@ import { deriveOAuthEncryptionKey } from '../../oauth/encryption.js'
import { rootLogger } from '../../observability/logger.js'
import {
type CodexCatalogTransport,
- createUnavailableCodexCatalogTransport,
+ createCodexCatalogTransportFromEnv,
syncCodexSubscriptionCatalog,
} from '../../services/codexSubscriptionCatalog.js'
import { loadCodexSubscriptionSecrets } from '../../services/codexSubscriptionConnection.js'
@@ -84,7 +84,7 @@ function sendOAuthError(
}
export function createAdminCodexSubscriptionRouter(
- catalogTransport: CodexCatalogTransport = createUnavailableCodexCatalogTransport()
+ catalogTransport: CodexCatalogTransport = createCodexCatalogTransportFromEnv()
): Router {
const router = Router()
diff --git a/control-api/src/services/codexSubscriptionCatalog.ts b/control-api/src/services/codexSubscriptionCatalog.ts
index 0532e89fa..086034f44 100644
--- a/control-api/src/services/codexSubscriptionCatalog.ts
+++ b/control-api/src/services/codexSubscriptionCatalog.ts
@@ -1,3 +1,5 @@
+import jwt from 'jsonwebtoken'
+import { config } from '../config.js'
import type { DbClient } from '../db.js'
import { rootLogger } from '../observability/logger.js'
import {
@@ -163,6 +165,61 @@ export function createUnavailableCodexCatalogTransport(): CodexCatalogTransport
}
}
+export function signCodexAdminPermit(operation: 'catalog_list' | 'connection_test'): string {
+ return jwt.sign(
+ { sub: 'control-api', typ: 'codex-admin-permit', operation },
+ config.adminJwtPrivateKey,
+ {
+ algorithm: 'RS256',
+ issuer: config.adminJwtIssuer,
+ audience: 'codex-llm-proxy-admin',
+ expiresIn: 60,
+ }
+ )
+}
+
+export function createCodexProxyCatalogTransport(deps: {
+ adminBaseUrl: string
+ fetchFn?: typeof fetch
+ signPermit?: (operation: 'catalog_list' | 'connection_test') => string
+}): CodexCatalogTransport {
+ const fetchFn = deps.fetchFn ?? fetch
+ const signPermit = deps.signPermit ?? signCodexAdminPermit
+ return {
+ async listModels(input: { accessToken: string }): Promise<CodexCatalogTransportResult> {
+ const base = deps.adminBaseUrl.replace(/\/+$/, '')
+ const response = await fetchFn(`${base}/internal/admin/v1/codex/models`, {
+ method: 'POST',
+ headers: {
+ 'content-type': 'application/json',
+ authorization: `Bearer ${signPermit('catalog_list')}`,
+ },
+ body: JSON.stringify({ accessToken: input.accessToken }),
+ })
+ if (!response.ok) {
+ if (response.status === 401 || response.status === 403) return { outcome: 'auth-rejected' }
+ return { outcome: 'unavailable' }
+ }
+ const body = (await response.json()) as {
+ outcome?: CodexCatalogOutcome
+ models?: CodexDiscoveredModel[]
+ }
+ if (body.outcome === 'auth-rejected' || body.outcome === 'unavailable') {
+ return { outcome: body.outcome }
+ }
+ return { outcome: 'ready', models: Array.isArray(body.models) ? body.models : [] }
+ },
+ }
+}
+
+export function createCodexCatalogTransportFromEnv(
+ env: NodeJS.ProcessEnv = process.env
+): CodexCatalogTransport {
+ const adminBaseUrl = env.CODEX_LLM_PROXY_ADMIN_URL?.trim() ?? ''
+ if (!adminBaseUrl) return createUnavailableCodexCatalogTransport()
+ return createCodexProxyCatalogTransport({ adminBaseUrl })
+}
+
async function loadCodexRows(db: DbClient): Promise<CodexCatalogRow[]> {
const result = await db.query(
`SELECT model, source, enabled, stale
diff --git a/control-api/test/services.codexSubscriptionCatalog.test.ts b/control-api/test/services.codexSubscriptionCatalog.test.ts
index 7e7de80ba..3dbf3beb3 100644
--- a/control-api/test/services.codexSubscriptionCatalog.test.ts
+++ b/control-api/test/services.codexSubscriptionCatalog.test.ts
@@ -1,5 +1,7 @@
import { describe, expect, it, vi } from 'vitest'
import {
+ createCodexCatalogTransportFromEnv,
+ createCodexProxyCatalogTransport,
planCodexCatalogReconcile,
syncCodexSubscriptionCatalog,
} from '../src/services/codexSubscriptionCatalog.js'
@@ -138,3 +140,38 @@ describe('syncCodexSubscriptionCatalog fencing', () => {
expect(result.staled).toBe(0)
})
})
+
+describe('Codex proxy catalog transport', () => {
+ it('stays unavailable when the proxy admin URL is unset', () => {
+ const transport = createCodexCatalogTransportFromEnv({})
+ return expect(transport.listModels({ accessToken: 'tok' })).resolves.toEqual({
+ outcome: 'unavailable',
+ })
+ })
+
+ it('posts a JIT access token to the proxy admin models route and returns normalized models', async () => {
+ const fetchFn = vi.fn(async (url: string, init?: RequestInit) => {
+ expect(url).toBe(
+ 'http://codex-llm-proxy.control-plane.svc:8081/internal/admin/v1/codex/models'
+ )
+ expect(
+ String(init?.headers && (init.headers as Record<string, string>).authorization)
+ ).toContain('Bearer ')
+ expect(JSON.parse(String(init?.body))).toEqual({ accessToken: 'tok-live' })
+ return new Response(JSON.stringify({ outcome: 'ready', models: [{ model: 'gpt-5.1' }] }), {
+ status: 200,
+ headers: { 'content-type': 'application/json' },
+ })
+ })
+ const transport = createCodexProxyCatalogTransport({
+ adminBaseUrl: 'http://codex-llm-proxy.control-plane.svc:8081',
+ fetchFn,
+ signPermit: () => 'permit',
+ })
+ await expect(transport.listModels({ accessToken: 'tok-live' })).resolves.toEqual({
+ outcome: 'ready',
+ models: [{ model: 'gpt-5.1' }],
+ })
+ expect(fetchFn).toHaveBeenCalledOnce()
+ })
+})