OpenTelemetry W3C Baggage Sanitization and Header Mutation Invariant

--- description: OpenTelemetry W3C Baggage Sanitization and Header Mutation Invariant - Enforces deterministic sanitization, allowlisting, and byte-budget validation on W3C Baggage context mutations prior to distributed propagation. Unchecked baggage accumulation causes downstream HTTP 431 (Request Header Fields Too Large) outages and propagates unvetted tenant or security context across external trust boundaries. globs: src/observability/**/*.{ts,js}, src/middleware/**/*.{ts,js}, src/telemetry/**/*.{ts,js}, src/tracing/**/*.{ts,js}, src/common/tracing/**/*.{ts,js} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/opentelemetry-w3c-baggage-context-mutation-guardrail" --- # OpenTelemetry W3C Baggage Sanitization and Header Mutation Invariant > **Severity**: CRITICAL | **Category**: devops > **Anti-Pattern Warning**: Blind Baggage Forwarding and Unbounded Context Mutation Inducing Cascading Gateway 431s and Boundary Injection ## System Constraints You are a Principal Software Architect enforcing production-grade OpenTelemetry W3C Baggage standards. Distributed context propagation must never be treated as an open key-value store. You must enforce strict schema allowlisting, character set sanitization conforming to RFC 7230/W3C specifications, rigid size ceilings (maximum 8192 total bytes and 64 entries), and boundary boundary scrubbers that prevent PII, authorization tokens, or unsanitized user inputs from propagating across RPC and HTTP hops. ## Strict Guidelines - Engineers MUST ALWAYS enforce an explicit allowlist of permitted baggage keys before injecting entries into the active OpenTelemetry Context. - Engineers MUST NOT propagate sensitive, high-cardinality, or non-deterministic data (e.g., JWTs, session tokens, arbitrary user payloads, raw error strings) inside W3C Baggage. - Code SHOULD validate the aggregate baggage header byte size against an invariant ceiling (hard limit of 8192 bytes, recommended ceiling of 2048 bytes) and drop non-critical entries when exceeding limits. - Services MUST sanitize key and value strings against W3C Baggage character specifications (keys matching `^[a-zA-Z0-9!#$%&'*+\-.^_`|~]+$`, values URL-encoded) to eliminate header injection and delimiter splitting. - Components NEVER propagate unvalidated incoming Baggage headers directly to downstream external or third-party HTTP endpoints without running context-stripping middleware. ## Bad vs Good Implementations ### Unbounded Baggage Mutation vs. Allowlisted and Guarded Context Injector #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Iterating over raw request headers and populating baggage entries blindly causes HTTP 431 failures downstream due to header bloat (cookie headers, authorization headers). It also violates W3C key-format constraints and propagates unvetted external data across microservice boundaries. ```typescript import { propagation, context } from '@opentelemetry/api'; import { Request, Response, NextFunction } from 'express'; export function telemetryMiddleware(req: Request, res: Response, next: NextFunction) { // ANTI-PATTERN: Blindly mutating Baggage with uncontrolled request headers/query params. // This invites HTTP 431 header bloat, PII leaks, and header injection vulnerabilities. let activeBaggage = propagation.getBaggage(context.active()) || propagation.createBaggage(); for (const [key, value] of Object.entries(req.headers)) { if (typeof value === 'string') { activeBaggage = activeBaggage.setEntry(key, { value }); } } // Propagates raw, unchecked tenant metadata or cookies if (req.query.tenantData) { activeBaggage = activeBaggage.setEntry('tenant_data', { value: String(req.query.tenantData) }); } context.with(propagation.setBaggage(context.active(), activeBaggage), () => { next(); }); } ``` #### Production Standard (Correct) > **Standard**: Implements an explicit key allowlist, verifies key syntax against W3C specification tokens, enforces entry limits and an aggregate byte budget (2048 bytes), and sanitizes values with URL encoding to guarantee downstream network and boundary safety. ```typescript import { propagation, context, Baggage } from '@opentelemetry/api'; import { Request, Response, NextFunction } from 'express'; const ALLOWED_BAGGAGE_KEYS = new Set(['tenant.id', 'routing.tier', 'env.datacenter']); const MAX_BAGGAGE_BYTES = 2048; const MAX_ENTRIES = 16; const KEY_REGEX = /^[a-zA-Z0-9!#$%&'*+\-.^_`|~]+$/; function sanitizeBaggage(sourceBaggage: Baggage | undefined, newEntries: Record<string, string>): Baggage { let target = propagation.createBaggage(); let totalBytes = 0; let entryCount = 0; const mergeEntry = (k: string, v: string) => { if (!ALLOWED_BAGGAGE_KEYS.has(k) || !KEY_REGEX.test(k) || entryCount >= MAX_ENTRIES) { return; } const sanitizedVal = encodeURIComponent(v.trim()); const entrySize = Buffer.byteLength(k, 'utf8') + Buffer.byteLength(sanitizedVal, 'utf8') + 2; // '=' and ';' delimiter if (totalBytes + entrySize > MAX_BAGGAGE_BYTES) { return; } target = target.setEntry(k, { value: sanitizedVal }); totalBytes += entrySize; entryCount++; }; sourceBaggage?.getAllEntries().forEach(([k, entry]) => mergeEntry(k, entry.value)); Object.entries(newEntries).forEach(([k, v]) => mergeEntry(k, v)); return target; } export function telemetryMiddleware(req: Request, res: Response, next: NextFunction) { const currentCtx = context.active(); const rawBaggage = propagation.getBaggage(currentCtx); const candidateEntries: Record<string, string> = {}; const tenantHeader = req.header('x-tenant-id'); if (tenantHeader) { candidateEntries['tenant.id'] = tenantHeader; } const safeBaggage = sanitizeBaggage(rawBaggage, candidateEntries); context.with(propagation.setBaggage(currentCtx, safeBaggage), () => { next(); }); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: OpenTelemetry W3C Baggage Sanitization and Header Mutation Invariant

OpenTelemetry W3C Baggage Sanitization and Header Mutation Invariant defines an industrial-grade behavioral standard for devops engineering. Enforces deterministic sanitization, allowlisting, and byte-budget validation on W3C Baggage context mutations prior to distributed propagation. Unchecked baggage accumulation causes downstream HTTP 431 (Request Header Fields Too Large) outages and propagates unvetted tenant or security context across external trust boundaries. Modern software architectures require strict adherence to deterministic patterns to guarantee high availability, maintainability, and zero security vulnerabilities.

Framework Paradigm Shift & Drift MechanicsLLMs are trained on millions of open-source repositories containing outdated code, legacy idioms, and unpatched antipatterns. When coding assistants generate implementations for this stack, they default to common statistical tokens: Blind Baggage Forwarding and Unbounded Context Mutation Inducing Cascading Gateway 431s and Boundary Injection Without an explicit system instruction file, developers spend hours debugging silent failures.

Failure Modes & Production Blast Radius

Hazard Analysis: What Breaks Without This Rule

The following failure modes have been cataloged from hundreds of hours of production code reviews where AI assistants produced non-compliant implementations:

Failure Mode	AI Symptom (The Anti-Pattern)	Severity	Production Impact & Remedy
AI Hallucination & Deprecation Drift	Blind Baggage Forwarding and Unbounded Context Mutation Inducing Cascading Gateway 431s and Boundary Injection	Critical	Violating this industrial standard introduces regression bugs, security risks, and unexpected runtime failures in production. Enforce explicit behavioral system directives across all AI coding assistants in your repository.
Silent Architecture Inconsistency	AI assistants produce mixed paradigms across files, creating fragmented codebase conventions.	Medium	Increases cognitive load during code reviews and leads to maintenance debt across engineering teams. Pin project conventions in .cursor/rules, CLAUDE.md, and AGENTS.md so all team agents follow identical guardrails.

Architectural Directives in Detail

Step-by-Step Production Directives

Each rule constraint below is injected into the AI agent's system prompt to establish deterministic boundaries:

Engineers MUST ALWAYS enforce an explicit allowlist of permitted baggage keys before injecting entries into the active OpenTelemetry Context.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.