ADR-0013: Proxy input validation and stable error envelope

• Status: Accepted
• Date: 2026-06-02
• Authors: IBEX Harness team

Context

Milestone 1.2.2 parses OpenAI-shaped chat JSON after auth with an unbounded body read and a minimal error envelope. Goal 1.2 requires security boundaries (body size, Content-Type), semantic validation with field_errors, and consistent response headers before rate limiting (1.2.4) and provider HTTP (Phase 2).

Decision

1) Limits (security controls; ADR amendment to change)

2) HTTP mapping

3) Field error codes (canonical)

REQUIRED, TOO_LONG, TOO_MANY, INVALID_ENUM, INVALID_FORMAT

4) Content-Type

POST /v1/chat/completions requires Content-Type: application/json (allows application/json; charset=utf-8).

5) IBEX headers (chat)

• X-IBEX-Agent-ID required; value must be a UUID (v4/v7) via github.com/google/uuid
• Optional session header format checks deferred unless specified in API doc

6) Envelope

Single package services/proxy/internal/errors:

• Detail includes optional docs_url, field_errors
• All proxy JSON errors use errors.Write / WriteFromRequest
• Optional docs URL pattern: {IBEX_ERROR_DOCS_BASE}/errors/{CODE} (empty base omits docs_url)

7) Request / trace IDs

• RequestContextMiddleware (outer chain): accept incoming request ID header when valid UUID (v4 or v7), else generate UUID v7 via packages/reqid (ADR-0017); generate synthetic trace_id per request until OTel (1.3.1)
• Context key owned by packages/reqid; proxy http layer delegates to reqid.FromContext
• AuthMiddleware reuses request ID from context (fallback generate for isolated tests)
• ResponseHeadersMiddleware: sets request ID, trace ID, and X-Response-Time (ms) on every response
• Header names configurable: IBEX_REQUEST_ID_HEADER (default X-Request-ID), IBEX_TRACE_ID_HEADER (default X-Trace-ID)
• Proxy → auth gRPC: x-request-id metadata via client interceptor (ADR-0017)

8) Middleware order

metrics → requestContext → responseHeaders → logging → mux

POST /v1/chat/completions:
  bodyLimit → contentType → auth → agentVerify → rateLimit → handler

GET /v1/internal/auth-probe:
  auth → agentVerify → rateLimit → handler

GET /v1/orgs/{org_id}/auth-probe:
  pathOrgUUID → auth → agentVerify → rateLimit → handler

Rate limit added in 1.2.4 (ADR-0015). Agent verify added in 1.2.5 (ADR-0016).

Amends ADR-0012 §6 footnote accordingly.

9) Packages

• internal/validation/ — limits, chat semantic validation, header validation
• internal/http/middleware.go — body limit, content-type, request context, response headers
• Extend internal/errors/ — do not add internal/http/errors.go

10) Deferred / out of scope

• OTel exporter (1.3.1)
• Multimodal content arrays (string-only until Phase 2+)
• Bloom/LRU auth cache (2.2.1)
• Provider HTTP (upstream/)

Consequences

Positive

• Completes Goal 1.2 validation and stable envelope criteria on the proxy
• DoS risk from unbounded bodies closed before JSON decode
• Single error writer; auth codes stable for clients

Negative

• Platform /health and /ready success payloads remain minimal {status}; errors use stable envelope
• Trace IDs are synthetic until 1.3.1

References

• Milestone 1.2.3
• ADR-0011
• ADR-0012
• ADR-0015
• API_DOCUMENTATION.md
• SECURITY.md §8.1