Skip to content

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

TypeScript

fix(llm-proxy): keep dev's unknown outcome on a dropped stream and answer ticket_expired

Alfredo Lopezed5e9477cee8
diff --git a/codex-llm-proxy/src/auth/executionTicketVerifier.ts b/codex-llm-proxy/src/auth/executionTicketVerifier.ts
index ae1ec5d8e..41a38c562 100644
--- a/codex-llm-proxy/src/auth/executionTicketVerifier.ts
+++ b/codex-llm-proxy/src/auth/executionTicketVerifier.ts
@@ -12,33 +12,62 @@ export type ExecutionTicketClaims = {
expiresAtMs: number
}
+function readExecutionTicket(
+ token: string,
+ config: CodexLlmProxyConfig,
+ ignoreExpiration: boolean
+): ExecutionTicketClaims | null {
+ const verified = jwt.verify(token, config.jwtPublicKey, {
+ algorithms: ['RS256'],
+ issuer: config.jwtIssuer,
+ audience: 'codex-llm-proxy',
+ ignoreExpiration,
+ })
+ if (typeof verified !== 'object' || verified === null) return null
+ const claims = verified as jwt.JwtPayload
+ if (typeof claims.exp !== 'number') return null
+ 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,
+ expiresAtMs: claims.exp * 1000,
+ }
+}
+
export function verifyExecutionTicket(
token: string,
config: CodexLlmProxyConfig
): ExecutionTicketClaims | null {
try {
- const verified = jwt.verify(token, config.jwtPublicKey, {
- algorithms: ['RS256'],
- issuer: config.jwtIssuer,
- audience: 'codex-llm-proxy',
- })
- if (typeof verified !== 'object' || verified === null) return null
- const claims = verified as jwt.JwtPayload
- if (typeof claims.exp !== 'number') return null
- 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,
- expiresAtMs: claims.exp * 1000,
- }
+ return readExecutionTicket(token, config, false)
} catch {
return null
}
}
+
+/**
+ * True only for a ticket that `verifyExecutionTicket` refused because its
+ * `exp` has passed (#739 R17-2). jsonwebtoken checks `exp` before audience and
+ * issuer, so an expiry error alone does not prove the ticket is authentic: it
+ * is re-read without the expiry and must pass every other check.
+ */
+export function isExpiredExecutionTicket(token: string, config: CodexLlmProxyConfig): boolean {
+ try {
+ readExecutionTicket(token, config, false)
+ return false
+ } catch (error) {
+ if (!(error instanceof jwt.TokenExpiredError)) return false
+ }
+ try {
+ return readExecutionTicket(token, config, true) !== null
+ } catch {
+ return false
+ }
+}
diff --git a/codex-llm-proxy/src/codexTransport.ts b/codex-llm-proxy/src/codexTransport.ts
index 54d562923..817e6c71d 100644
--- a/codex-llm-proxy/src/codexTransport.ts
+++ b/codex-llm-proxy/src/codexTransport.ts
@@ -632,7 +632,11 @@ async function consumeSse(
}
for (const call of pending.values()) {
if (call.emitted) continue
- const args = parseToolArguments(call.arguments, { closed: false })
+ // R17-1: a stream with no terminal event delivers none of its calls, so
+ // an open call there keeps dev's name and count checks but its arguments
+ // are not parsed, and the attempt stays `unknown`. Refusing them would
+ // report a dropped connection as a malformed model response.
+ const args = completed ? parseToolArguments(call.arguments, { closed: false }) : {}
await acceptFrame({ type: 'tool_call', id: call.id, name: call.name, arguments: args })
call.emitted = true
}
diff --git a/codex-llm-proxy/src/server.ts b/codex-llm-proxy/src/server.ts
index e2e492358..75110a0f8 100644
--- a/codex-llm-proxy/src/server.ts
+++ b/codex-llm-proxy/src/server.ts
@@ -10,7 +10,10 @@ import { type Server, createServer } from 'node:http'
import { Registry, collectDefaultMetrics } from 'prom-client'
import { z } from 'zod'
import { verifyAdminPermit } from './auth/adminPermitVerifier.js'
-import { verifyExecutionTicket } from './auth/executionTicketVerifier.js'
+import {
+ isExpiredExecutionTicket,
+ verifyExecutionTicket,
+} from './auth/executionTicketVerifier.js'
import { type PlatformJwtClaims, verifyPlatformJwt } from './auth/platformJwtVerifier.js'
import {
CodexTransportError,
@@ -418,7 +421,14 @@ export function createProxyApps(
const ticket = verifyExecutionTicket(parsed.data.executionTicket, config)
if (!ticket) {
releaseAdmission()
- reject(res, 403, 'ticket_invalid')
+ // R17-2: body admission can wait up to maxQueueWaitMs, the ticket TTL,
+ // before this read, so an honest ticket can arrive expired. The Host
+ // retries ticket_expired with a fresh authorization.
+ if (isExpiredExecutionTicket(parsed.data.executionTicket, config)) {
+ reject(res, 403, 'ticket_expired')
+ } else {
+ reject(res, 403, 'ticket_invalid')
+ }
return
}
if (platform.hostRefs.includes('*') || !platform.hostRefs.includes(ticket.hostRef)) {
diff --git a/docs/architecture/codex-subscription-transport-contract.md b/docs/architecture/codex-subscription-transport-contract.md
index 5bc29bcb5..5f729207c 100644
--- a/docs/architecture/codex-subscription-transport-contract.md
+++ b/docs/architecture/codex-subscription-transport-contract.md
@@ -436,9 +436,12 @@ code the proxy constructs, and every code it refuses a request with
so its client always sets `Content-Length`, never sets `Content-Encoding` and
always sends `application/json`. Either code means a caller other than the
Host, or a Host defect, and retrying the same request cannot succeed.
-- `ticket_expired`: HTTP 403. control-api refused the redeem because the
- execution ticket outlived `executionTicketTtlMs`; the proxy passes the code
- through.
+- `ticket_expired`: HTTP 403. The execution ticket outlived
+ `executionTicketTtlMs`. The proxy answers it directly when the ticket's
+ signature, audience, issuer and claims are valid and only `exp` has passed,
+ which body admission's wait can cause; it also passes the code through when
+ control-api refuses the redeem for the same reason. Every other ticket
+ failure is `ticket_invalid`. The Host retries it with a fresh authorization.
- `unknown_field`: HTTP 400. The completion or admin body carries a top-level
field outside the schema.
- `host_binding_mismatch`: HTTP 403. The execution ticket is bound to a Host
@@ -505,9 +508,12 @@ code the proxy constructs, and every code it refuses a request with
flushed at `response.completed`, are refused like truncated JSON. A stream
that was canceled or that the upstream failed keeps its own outcome (`canceled`,
`context_length_exceeded` or `provider_unavailable`), because its open call
- is truncated as a consequence. Delivered like `tool_call_limit_exceeded` —
- 422 carrying the code, or an SSE error frame once text is on the wire. The
- Host maps it to `LLM_INVALID_RESPONSE`, not retryable, failover class `null`.
+ is truncated as a consequence. A stream that ends with no terminal event
+ keeps the outcome `unknown`: its open calls keep the name and count checks,
+ their arguments are not parsed, and none is delivered. Delivered like
+ `tool_call_limit_exceeded` — 422 carrying the code, or an SSE error frame
+ once text is on the wire. The Host maps it to `LLM_INVALID_RESPONSE`, not
+ retryable, failover class `null`.
- `request_limit_exceeded` (Host-side only): the turn carries too much. The
Host raises it before authorization — so no provider attempt is spent — and
maps it to `LLM_CONTEXT_LENGTH_EXCEEDED`, not retryable, which the UI shows
diff --git a/docs/architecture/grok-subscription-transport-contract.md b/docs/architecture/grok-subscription-transport-contract.md
index c8e1ebfde..019237faa 100644
--- a/docs/architecture/grok-subscription-transport-contract.md
+++ b/docs/architecture/grok-subscription-transport-contract.md
@@ -310,9 +310,12 @@ code the proxy constructs, and every code it refuses a request with
so its client always sets `Content-Length`, never sets `Content-Encoding` and
always sends `application/json`. Either code means a caller other than the
Host, or a Host defect, and retrying the same request cannot succeed.
-- `ticket_expired`: HTTP 403. control-api refused the redeem because the
- execution ticket outlived `executionTicketTtlMs`; the proxy passes the code
- through.
+- `ticket_expired`: HTTP 403. The execution ticket outlived
+ `executionTicketTtlMs`. The proxy answers it directly when the ticket's
+ signature, audience, issuer and claims are valid and only `exp` has passed,
+ which body admission's wait can cause; it also passes the code through when
+ control-api refuses the redeem for the same reason. Every other ticket
+ failure is `ticket_invalid`. The Host retries it with a fresh authorization.
- `unknown_field`: HTTP 400. The completion or admin body carries a top-level
field outside the schema.
- `host_binding_mismatch`: HTTP 403. The execution ticket is bound to a Host
@@ -400,7 +403,10 @@ code the proxy constructs, and every code it refuses a request with
that was
canceled or that the upstream failed keeps its own outcome (`canceled`,
`provider_unavailable`), because its open call is truncated as a
- consequence. Delivered like `tool_call_limit_exceeded` — 422 carrying the
+ consequence. A stream that ends with no terminal event keeps the outcome
+ `unknown`: its open calls keep the name and count checks, their arguments
+ are not parsed, and none is delivered. Delivered like
+ `tool_call_limit_exceeded` — 422 carrying the
code, or an SSE error frame once text is on the wire. The Host maps it to
`LLM_INVALID_RESPONSE`, not retryable, failover class `null`.
- `request_limit_exceeded` (Host-side only): the turn carries too much. The
diff --git a/grok-llm-proxy/src/auth/executionTicketVerifier.ts b/grok-llm-proxy/src/auth/executionTicketVerifier.ts
index 0f30a4611..0e54ea538 100644
--- a/grok-llm-proxy/src/auth/executionTicketVerifier.ts
+++ b/grok-llm-proxy/src/auth/executionTicketVerifier.ts
@@ -12,33 +12,62 @@ export type ExecutionTicketClaims = {
expiresAtMs: number
}
+function readExecutionTicket(
+ token: string,
+ config: GrokLlmProxyConfig,
+ ignoreExpiration: boolean
+): ExecutionTicketClaims | null {
+ const verified = jwt.verify(token, config.jwtPublicKey, {
+ algorithms: ['RS256'],
+ issuer: config.jwtIssuer,
+ audience: 'grok-llm-proxy',
+ ignoreExpiration,
+ })
+ if (typeof verified !== 'object' || verified === null) return null
+ const claims = verified as jwt.JwtPayload
+ if (typeof claims.exp !== 'number') return null
+ if (claims.typ !== 'grok-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: 'grok-execution-ticket',
+ hostRef: claims.hostRef,
+ model: claims.model,
+ requestHash: claims.requestHash,
+ providerAttemptId: claims.providerAttemptId,
+ expiresAtMs: claims.exp * 1000,
+ }
+}
+
export function verifyExecutionTicket(
token: string,
config: GrokLlmProxyConfig
): ExecutionTicketClaims | null {
try {
- const verified = jwt.verify(token, config.jwtPublicKey, {
- algorithms: ['RS256'],
- issuer: config.jwtIssuer,
- audience: 'grok-llm-proxy',
- })
- if (typeof verified !== 'object' || verified === null) return null
- const claims = verified as jwt.JwtPayload
- if (typeof claims.exp !== 'number') return null
- if (claims.typ !== 'grok-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: 'grok-execution-ticket',
- hostRef: claims.hostRef,
- model: claims.model,
- requestHash: claims.requestHash,
- providerAttemptId: claims.providerAttemptId,
- expiresAtMs: claims.exp * 1000,
- }
+ return readExecutionTicket(token, config, false)
} catch {
return null
}
}
+
+/**
+ * True only for a ticket that `verifyExecutionTicket` refused because its
+ * `exp` has passed (#739 R17-2). jsonwebtoken checks `exp` before audience and
+ * issuer, so an expiry error alone does not prove the ticket is authentic: it
+ * is re-read without the expiry and must pass every other check.
+ */
+export function isExpiredExecutionTicket(token: string, config: GrokLlmProxyConfig): boolean {
+ try {
+ readExecutionTicket(token, config, false)
+ return false
+ } catch (error) {
+ if (!(error instanceof jwt.TokenExpiredError)) return false
+ }
+ try {
+ return readExecutionTicket(token, config, true) !== null
+ } catch {
+ return false
+ }
+}
diff --git a/grok-llm-proxy/src/grokTransport.ts b/grok-llm-proxy/src/grokTransport.ts
index 346b55651..d8434a7b6 100644
--- a/grok-llm-proxy/src/grokTransport.ts
+++ b/grok-llm-proxy/src/grokTransport.ts
@@ -662,7 +662,11 @@ async function consumeSse(
}
for (const call of pending.values()) {
if (call.emitted) continue
- const args = parseToolArguments(call.arguments, { closed: false })
+ // R17-1: a stream with no terminal event delivers none of its calls, so
+ // an open call there keeps dev's name and count checks but its arguments
+ // are not parsed, and the attempt stays `unknown`. Refusing them would
+ // report a dropped connection as a malformed model response.
+ const args = completed ? parseToolArguments(call.arguments, { closed: false }) : {}
await acceptFrame({ type: 'tool_call', id: call.id, name: call.name, arguments: args })
call.emitted = true
}
diff --git a/grok-llm-proxy/src/server.ts b/grok-llm-proxy/src/server.ts
index 1a80aad2f..bd7a6ce6c 100644
--- a/grok-llm-proxy/src/server.ts
+++ b/grok-llm-proxy/src/server.ts
@@ -10,7 +10,10 @@ import { type Server, createServer } from 'node:http'
import { Registry, collectDefaultMetrics } from 'prom-client'
import { z } from 'zod'
import { verifyAdminPermit } from './auth/adminPermitVerifier.js'
-import { verifyExecutionTicket } from './auth/executionTicketVerifier.js'
+import {
+ isExpiredExecutionTicket,
+ verifyExecutionTicket,
+} from './auth/executionTicketVerifier.js'
import { type PlatformJwtClaims, verifyPlatformJwt } from './auth/platformJwtVerifier.js'
import type { GrokLlmProxyConfig } from './config.js'
import { ControlApiClient, ControlApiClientError } from './controlApiClient.js'
@@ -309,7 +312,14 @@ export function createProxyApps(
}
const ticket = verifyExecutionTicket(parsed.data.executionTicket, config)
if (!ticket) {
- reject(res, 403, 'ticket_invalid')
+ // R17-2: body admission can wait up to maxQueueWaitMs, the ticket TTL,
+ // before this read, so an honest ticket can arrive expired. The Host
+ // retries ticket_expired with a fresh authorization.
+ if (isExpiredExecutionTicket(parsed.data.executionTicket, config)) {
+ reject(res, 403, 'ticket_expired')
+ } else {
+ reject(res, 403, 'ticket_invalid')
+ }
return
}
if (platform.hostRefs.includes('*') || !platform.hostRefs.includes(ticket.hostRef)) {
diff --git a/grok-llm-proxy/test/contractFreeze.test.ts b/grok-llm-proxy/test/contractFreeze.test.ts
index d20266b17..900a78e03 100644
--- a/grok-llm-proxy/test/contractFreeze.test.ts
+++ b/grok-llm-proxy/test/contractFreeze.test.ts
@@ -340,8 +340,9 @@ describe('grok-subscription contract freeze', () => {
it('lists the admission codes the proxy emits or passes through in the frozen taxonomy', () => {
// request_timeout, length_required and unsupported_media_type are direct
- // refusals in src/server.ts; ticket_expired is a control-api redeem code
- // the proxy passes through (ATTEMPT_ERROR_STATUS, mapError).
+ // refusals in src/server.ts; ticket_expired is both a direct refusal for
+ // an authentic expired ticket and a control-api redeem code the proxy
+ // passes through (ATTEMPT_ERROR_STATUS, mapError).
const serverSource = readFileSync(join(srcDir, 'server.ts'), 'utf8')
// Witness: the pass-through table carries the code this test requires.
expect(serverSource).toMatch(/^\s*ticket_expired: 403,$/m)
diff --git a/tests/e2e/integration/codex-subscription-contract-freeze.test.ts b/tests/e2e/integration/codex-subscription-contract-freeze.test.ts
index 26895863f..fe8f42b53 100644
--- a/tests/e2e/integration/codex-subscription-contract-freeze.test.ts
+++ b/tests/e2e/integration/codex-subscription-contract-freeze.test.ts
@@ -321,7 +321,8 @@ describe('codex-subscription contract freeze', () => {
expect(String(code)).toMatch(/^(?:[a-z][a-z0-9_]+|Unauthorized)$/)
}
// Codes the proxy emits directly (request_timeout, length_required,
- // unsupported_media_type) or passes through from redeem (ticket_expired).
+ // unsupported_media_type, ticket_expired) or passes through from redeem
+ // (ticket_expired).
expect(errors).toContain('request_timeout')
expect(errors).toContain('length_required')
expect(errors).toContain('ticket_expired')
diff --git a/tests/e2e/package-lock.json b/tests/e2e/package-lock.json
index 9247d0f1c..3e074b47d 100644
--- a/tests/e2e/package-lock.json
+++ b/tests/e2e/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "clerum-e2e-tests",
- "version": "0.1.95",
+ "version": "0.1.96",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-e2e-tests",
- "version": "0.1.95",
+ "version": "0.1.96",
"devDependencies": {
"@clerum/llm-provider-attempt-contract": "file:../../packages/llm-provider-attempt-contract",
"@types/jsonwebtoken": "^9.0.10",
diff --git a/tests/e2e/package.json b/tests/e2e/package.json
index 2f2e2cbbc..125b1df5d 100644
--- a/tests/e2e/package.json
+++ b/tests/e2e/package.json
@@ -1,6 +1,6 @@
{
"name": "clerum-e2e-tests",
- "version": "0.1.95",
+ "version": "0.1.96",
"private": true,
"type": "module",
"scripts": {