HTTP Headers Standardization & Canonicalization Subsystem Architectural & Operational Guide
1. Executive Architectural Overview
The HTTP Headers Standardization & Canonicalization Subsystem (pkg/httpheaders) establishes an authoritative, hardened, and high-performance foundation for HTTP header manipulation across the ZQK Knowledge Kernel.
In distributed systems, microservices, and multi-agent coordination architectures, uncontrolled and ad-hoc HTTP header handling introduces severe vulnerabilities and subtle operational bugs:
- CRLF Injection & HTTP Request Smuggling (CWE-113, CWE-444): Unsanitized header values containing carriage returns (
\r), line feeds (\n), or null bytes (\x00) allow attackers to split HTTP messages, bypass perimeter firewalls, or poison HTTP response caches. - Case-Mismatch Routing & Retrieval Flakes: HTTP/1.1 and HTTP/2 header keys are semantically case-insensitive, but direct Go map lookups (
m["content-type"]vsm["Content-Type"]) produce silent retrieval failures, dropped authorization tokens, and broken routing middleware. - Distributed Trace Context Loss: Asynchronous job dispatchers and multi-agent orchestrators require seamless propagation of W3C distributed trace context (
Traceparent,Tracestate) without manual parsing overhead or accidental truncation. - Authentication Fragmentation: Microservices consume diverse auth patterns (Bearer tokens, Basic auth, API keys) across mixed headers (
Authorization,X-API-Key). Inconsistent parsers lead to security bypasses or panics on malformed tokens.
The httpheaders subsystem resolves these challenges by providing:
- Centralized Canonical Constants: Comprehensive standard RFC and ZQK distributed trace header constants, eliminating raw magic literals.
- RFC 7230/9110 Compliant Canonicalization: High-performance title-case hyphenated normalization (
CanonicalKey) matching Go MIME standards. - Fail-Closed RFC Security Validation: Deep validation of header names (
tokengrammar) and values (prohibiting CRLF injection, control bytes, and null bytes). - Hardened Auth Extractors: Resilient, RFC-compliant parsers for Bearer tokens, RFC 7617 Basic auth, and multi-header API keys.
- W3C Distributed Trace Injection & Extraction: Standardized context propagation ensuring telemetry continuity across multi-agent workflows.
- Static Floor Coverage Invariant: A strict statement test coverage invariant (\(\ge 85.0\%\), verified at \(>98.0\%\)) enforcing total test coverage across all boundary and failure conditions.
2. Component Topology & Subsystem Architecture
The subsystem operates as a core foundational utility consumed across agent delivery transports, scheduler transceivers, HTTP client adapters, and graph API servers:
flowchart TD
subgraph Consumers["Kernel Consumers & Transports"]
AgentDelivery["Agent Delivery Transport\n(pkg/agentdelivery)"]
Scheduler["Scheduler Transceiver\n(pkg/scheduler)"]
GraphClient["Graph API Clients\n(pkg/graph)"]
EventMesh["Ambient Event Mesh\n(pkg/ambient)"]
end
subgraph HTTPHeaders["HTTP Headers Subsystem (pkg/httpheaders)"]
Constants["Canonical Header Names\n(names.go)"]
CanonicalEngine["Canonical Normalizer & Operations\n(canonical.go)"]
ValidationEngine["RFC & CRLF Validation Engine\n(validation.go)"]
AuthExtractor["Authentication Parsers\n(auth.go)"]
TracePropagator["W3C Trace Propagator\n(trace.go)"]
end
Consumers -->|"Set/Get/Add/Del"| CanonicalEngine
Consumers -->|"Sanitize Untrusted Headers"| ValidationEngine
Consumers -->|"Extract Credentials"| AuthExtractor
Consumers -->|"Inject/Extract Tracing"| TracePropagator
CanonicalEngine -.->|"Uses Constants"| Constants
Component Responsibilities
| Component | Key Functions / Mechanism | Core Responsibility |
|---|---|---|
| Header Constants | Authorization, ContentType, Traceparent, XRequestID, etc. |
Authoritative constants eliminating hardcoded magic strings across kernel call sites. |
| Canonical Normalizer | CanonicalKey, GetCanonical, SetCanonical, AddCanonical, DelCanonical, Clone |
Title-case hyphen normalization (RFC 7230/9110) and safe map operations resilient against nil headers. |
| RFC Validation Engine | ValidateHeaderName, ValidateHeaderValue, ValidateHeader |
Invariant enforcement rejecting invalid tokens, spaces, non-ASCII characters, null bytes, and CRLF injections. |
| Authentication Parsers | ExtractBearerToken, ExtractBasicAuth, ExtractAPIKey |
Robust extraction of credentials supporting case-insensitive schemes, base64 decoding, and header fallbacks. |
| Trace Propagator | ExtractTraceContext, InjectTraceContext |
Extraction and injection of W3C traceparent and tracestate headers across HTTP requests and responses. |
3. Header Canonicalization & Invariant Enforcement Lifecycle
When an untrusted HTTP request or response header enters the kernel, the lifecycle progresses through validation, canonicalization, authentication extraction, and trace propagation:
sequenceDiagram
autonumber
actor Caller as HTTP Client / Adapter
participant Validation as Validation Engine
participant Canonical as Canonical Engine
participant Auth as Auth Parsers
participant Trace as Trace Propagator
Caller->>Validation: ValidateHeader(key, val)
alt Invalid Token or CRLF Detected
Validation-->>Caller: Return ErrInvalidHeaderNameChar / ErrCRLFInjection
else Valid Header
Validation-->>Caller: nil (Accepted)
end
Caller->>Canonical: SetCanonical(h, "content-type", "application/json")
Canonical->>Canonical: CanonicalKey("content-type") -> "Content-Type"
Canonical-->>Caller: Key stored as "Content-Type"
Caller->>Auth: ExtractBearerToken(h.Get("Authorization"))
Auth-->>Caller: token, nil
Caller->>Trace: ExtractTraceContext(h)
Trace-->>Caller: traceparent, tracestate
4. Security Defenses & Invariant Protection
4.1 CRLF Injection & Request Smuggling Defense
CRLF injection occurs when unsanitized input containing \r (0x0D) or \n (0x0A) is passed into HTTP header values. Attackers exploit this to inject arbitrary headers or terminate the HTTP header block prematurely, leading to HTTP response splitting and cache poisoning.
The ValidateHeaderValue function rigorously scans header values:
- Rejects any occurrence of
\ror\n(ErrCRLFInjection). - Rejects null bytes
\x00(ErrNullByteInjection). - Rejects unprintable control characters (\(< 0\text{x}20\) excluding horizontal tab \(0\text{x}09\), and \(0\text{x}7\text{F}\) DEL) (
ErrInvalidHeaderValue).
4.2 RFC 7230/9110 Token Character Verification
RFC 7230 section 3.2.6 specifies that header field names must be non-empty and consist strictly of tchar tokens:
ValidateHeaderName guarantees that field names containing whitespace, colons, brackets, or control characters fail closed immediately with ErrInvalidHeaderNameChar.
4.3 Hardened Authentication Extraction
ExtractBearerToken: Trims leading/trailing whitespace, validates case-insensitive"Bearer "prefixing, and prevents empty bearer tokens.ExtractBasicAuth: Handles RFC 7617 base64 decoding safely, verifies the presence of the username/password separator colon, and correctly preserves passwords containing colons (user:pass:word).ExtractAPIKey: Evaluates explicitX-API-Keyheaders first, gracefully falling back toAuthorization: ApiKey <key>,Authorization: Bearer <key>, or raw keys while excluding Basic authentication schemes.
5. Concurrency, Nil Safety & Thread Invariants
5.1 Nil-Safe API Design
Go's built-in http.Header is an alias for map[string][]string. Passing an uninitialized (nil) header to standard functions or directly subscripting it causes application panics.
All functions in pkg/httpheaders enforce strict nil safety:
GetCanonical(nil, ...)returns""without panicking.SetCanonical(nil, ...),AddCanonical(nil, ...), andDelCanonical(nil, ...)are safe no-ops.HasCanonical(nil, ...)returnsfalse.Clone(nil)returnsnil.ExtractTraceContext(nil)returns"", ""safely.InjectTraceContext(nil, ...)is a safe no-op.
5.2 Thread Isolation & Safe Concurrency
http.Header maps are not thread-safe for concurrent read/write operations. To guarantee race-free execution in concurrent agent routines:
- Isolated Clones: Consumers operating in concurrent branches invoke
Clone(h)to create independent, deep-copied header representations before mutation. - Managed Goroutines: All concurrent tests and worker tasks utilize
goroutinelabels.NewGoroutinefor lifecycle tracking, budget accounting, and panic recovery.
6. Verification & Operational Directives
6.1 Statement Coverage Invariant
The subsystem enforces a strict statement test coverage invariant:
Test execution must be scoped and bounded using the foreground runner flag:
ZQK_ALLOW_FOREGROUND_GO_TEST=1 go test -v -timeout 30s -cover ./pkg/httpheaders
6.2 Common Operational Recipes
Setting Standardized Headers
import "github.com/zqk-os/zqk/pkg/httpheaders"
req, err := http.NewRequestWithContext(ctx, http.MethodPost, endpoint, body)
if err != nil {
return err
}
httpheaders.SetCanonical(req.Header, httpheaders.ContentType, "application/json")
httpheaders.SetCanonical(req.Header, httpheaders.UserAgent, "ZQK-Agent/1.0")
httpheaders.InjectTraceContext(req.Header, traceparent, tracestate)
Validating Incoming Headers
for key, values := range req.Header {
if err := httpheaders.ValidateHeaderName(key); err != nil {
return fmt.Errorf("rejected malformed header name: %w", err)
}
for _, val := range values {
if err := httpheaders.ValidateHeaderValue(val); err != nil {
return fmt.Errorf("rejected header value: %w", err)
}
}
}
Extracting Client Credentials
// Priority 1: Bearer token
if token, err := httpheaders.ExtractBearerToken(req.Header.Get(httpheaders.Authorization)); err == nil {
return authenticateBearer(token)
}
// Priority 2: API key (header or fallback)
if apiKey := httpheaders.ExtractAPIKey(
req.Header.Get(httpheaders.Authorization),
req.Header.Get(httpheaders.XAPIKey),
); apiKey != "" {
return authenticateAPIKey(apiKey)
}