Skip to content

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

TypeScript

docs: scope the authorize parser-error wording and the image reader claims

Alfredo Lopez9b3cf93aa341
diff --git a/control-api/package-lock.json b/control-api/package-lock.json
index dac8a3f72..5ec8f7bf8 100644
--- a/control-api/package-lock.json
+++ b/control-api/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "clerum-control-api",
- "version": "0.1.642",
+ "version": "0.1.643",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-control-api",
- "version": "0.1.642",
+ "version": "0.1.643",
"dependencies": {
"@clerum/display-field": "file:../packages/display-field",
"@clerum/grok-provider-attempt-contract": "file:../packages/grok-provider-attempt-contract",
diff --git a/control-api/package.json b/control-api/package.json
index 48ff97068..3aafb96fd 100644
--- a/control-api/package.json
+++ b/control-api/package.json
@@ -1,6 +1,6 @@
{
"name": "clerum-control-api",
- "version": "0.1.642",
+ "version": "0.1.643",
"description": "Internal Clerum control plane REST API + UI for managing CRDs and secrets",
"main": "dist/main.js",
"engines": {
diff --git a/control-api/src/routes/mcp-host/llmProviderAttempts.routes.ts b/control-api/src/routes/mcp-host/llmProviderAttempts.routes.ts
index 3c04b014f..eceb6dc42 100644
--- a/control-api/src/routes/mcp-host/llmProviderAttempts.routes.ts
+++ b/control-api/src/routes/mcp-host/llmProviderAttempts.routes.ts
@@ -165,9 +165,11 @@ export function createMcpHostLlmProviderAttemptRoutes(gateway: K8sGateway): Rout
}
})
)
- // Every parser error is answered here. body-parser attaches the raw body to
- // a verify or JSON.parse error as `err.body`, and the global error handler
- // would parse it again.
+ // The size, structure, depth, charset, encoding and JSON.parse errors are
+ // answered here, because body-parser attaches the raw body to them as
+ // `err.body` and the global error handler would parse it again. The other
+ // parser errors (`request.aborted`, `request.size.invalid`, `stream.*`)
+ // carry no body and go to the global handler, which logs no body.
router.use((err: unknown, _req: Request, res: Response, next: NextFunction) => {
const typed = err as { type?: string; status?: number }
if (typed.type === 'entity.too.large' || typed.status === 413) {
diff --git a/docs/architecture/codex-subscription-transport-contract.md b/docs/architecture/codex-subscription-transport-contract.md
index 25510dce0..c0397992d 100644
--- a/docs/architecture/codex-subscription-transport-contract.md
+++ b/docs/architecture/codex-subscription-transport-contract.md
@@ -257,9 +257,11 @@ raw body before parsing it.
that is too deep 400 `invalid_request`, and a charset other than UTF-8 415
`unsupported_media_type`. A refused visual body frees its slot.
- body-parser attaches the raw body to these errors, so the proxies' error
- handlers log only the error type and status, and the control-api authorize
- route answers every parser error itself instead of passing it to the global
- error handler.
+ handlers log only the error type and status. The control-api authorize route
+ answers the size, structure, depth, charset, encoding and JSON.parse errors
+ itself instead of passing them to the global error handler; the parser
+ errors that carry no body (`request.aborted`, `request.size.invalid`,
+ `stream.*`) reach the global handler, which logs no body.
- The control-api authorize route parses with `inflate: false`, so an encoded
body is refused 415 before it is read. Before, 35750 bytes of gzip inflated
to 35 MiB.
diff --git a/docs/architecture/grok-subscription-transport-contract.md b/docs/architecture/grok-subscription-transport-contract.md
index 7a24a2880..aa4920dbb 100644
--- a/docs/architecture/grok-subscription-transport-contract.md
+++ b/docs/architecture/grok-subscription-transport-contract.md
@@ -88,8 +88,9 @@ Where the envelope is enforced:
scan described under "Body structure before parse", and the authorizer
builds the exact V2
proxy envelope inside its transaction after signing and before commit, so
- an envelope over the cap rolls back the attempt, the ticket and the
- reservation;
+ an envelope over the cap rolls back the attempt, the ticket and a
+ reservation created in that transaction (a reservation the Host presented
+ is kept);
- the workflow-approval gateway's authorize location has
`client_max_body_size 36700160`;
- `grok-llm-proxy` reads a V2 body with a separate parser whose limit is
diff --git a/packages/grok-provider-attempt-contract/visualPayload.cjs b/packages/grok-provider-attempt-contract/visualPayload.cjs
index 0fc3d786a..f372e7ca0 100644
--- a/packages/grok-provider-attempt-contract/visualPayload.cjs
+++ b/packages/grok-provider-attempt-contract/visualPayload.cjs
@@ -9,6 +9,9 @@
* decode pixels, verify PNG CRCs, validate entropy-coded JPEG data, or prove
* that the image renders. "Valid" here means "syntactically well-formed
* container inside the local budget", never "decoded and visually correct".
+ * The readers are stricter than the formats: they also refuse some rare valid
+ * images, such as a JPEG whose SOF declares height 0 and defers it to a DNL
+ * marker, or a PNG with bytes after IEND.
*
* The numbers come from the xAI documentation for api.x.ai/v1 (read
* 2026-09-23): at most 20 MiB per image, jpg/jpeg and png only, no
@@ -17,8 +20,8 @@
* cli-chat-proxy.grok.com/v1/responses is UNMEASURED for images: these limits
* are not an upstream capability fact for it.
*
- * There is no dimension or pixel limit. Dimensions are read only to validate
- * the container.
+ * There is no dimension or pixel limit. The declared dimensions are read as
+ * part of the container check and are never compared with a bound.
*
* The decoder and the container readers are a copy of the Codex contract's
* visualPayload.cjs, kept separate so this package never imports the Codex
diff --git a/packages/llm-provider-attempt-contract/visualPayload.cjs b/packages/llm-provider-attempt-contract/visualPayload.cjs
index 63894fe1a..52a347e29 100644
--- a/packages/llm-provider-attempt-contract/visualPayload.cjs
+++ b/packages/llm-provider-attempt-contract/visualPayload.cjs
@@ -9,6 +9,9 @@
* decode pixels, verify PNG CRCs, validate entropy-coded JPEG data, or prove
* that the image renders. "Valid" here means "syntactically well-formed
* container inside the local budget", never "decoded and visually correct".
+ * The readers are stricter than the formats: they also refuse some rare valid
+ * images, such as a JPEG whose SOF declares height 0 and defers it to a DNL
+ * marker, or a PNG with bytes after IEND.
*
* The budget below is a conservative local safety/product decision. It is not
* an upstream capability fact; the frozen ChatGPT endpoint is not certified by