OpenTelemetry Inbound W3C Baggage Scrubbing and Size Partitioning Standard

--- description: OpenTelemetry Inbound W3C Baggage Scrubbing and Size Partitioning Standard - Mandates strict allowlisting, key-level length validation, and cumulative payload size partitioning for incoming W3C Baggage in distributed tracing setups. Prevents cross-tenant context injection, metadata privilege escalation, and downstream HTTP 431 (Request Header Fields Too Large) outages caused by unconstrained baggage propagation across trust boundaries. globs: src/telemetry/**/*.{ts,js}, src/tracing/**/*.{ts,js}, src/middleware/**/*.{ts,js}, src/instrumentation/**/*.{ts,js} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/opentelemetry-inbound-baggage-scrubbing-guardrail" --- # OpenTelemetry Inbound W3C Baggage Scrubbing and Size Partitioning Standard > **Severity**: CRITICAL | **Category**: devops > **Anti-Pattern Warning**: Blind Inbound Baggage Passthrough Causing Header Poisoning and Downgrade Overflows ## System Constraints You are a Principal Software Architect enforcing enterprise-grade OpenTelemetry propagation security. You must ensure all inbound W3C baggage headers passing through edge proxies, APIs, and microservices are explicitly scrubbed against a zero-trust allowlist, sanitized for illegal control characters, and constrained by hard-coded byte budgets before injection into active Trace Context. ## Strict Guidelines - Services MUST NEVER configure default `W3CBaggagePropagator` directly on edge-facing or multi-tenant entry points without a scrubbing decorator. - Engineers MUST ALWAYS enforce a strict key allowlist (exact match or pinned regex) when extracting inbound baggage. - Services MUST drop or reject any baggage key-value pair where the key exceeds 64 bytes or the value exceeds 256 bytes. - The cumulative byte size of all retained baggage entries in a single request context MUST NOT exceed 2048 bytes (to defend against HTTP 431 cascading failures). - Engineers MUST NEVER permit client-supplied headers to override immutable security claims (e.g., `tenant_id`, `account_id`, `auth_subject`) extracted from verified authentication tokens. - Custom baggage propagators MUST validate RFC 7230 and RFC 2616 token compliance, stripping non-printable ASCII or control characters. ## Bad vs Good Implementations ### Unsanitized Baggage Propagation vs. Defensive Scrubbing Propagator #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Default W3CBaggagePropagator copies arbitrary key-value pairs from the inbound HTTP baggage header into the Active Context. Untrusted upstream clients can inject spoofed routing metadata or bloat the context, crashing downstream services with HTTP 431 errors. ```typescript import { NodeSDK } from '@opentelemetry/sdk-node'; import { CompositePropagator, W3CBaggagePropagator, W3CTraceContextPropagator } from '@opentelemetry/core'; // ANTI-PATTERN: Default propagator blindly propagates untrusted external baggage. // Allows external attackers to inject tenant spoofing keys and saturate downstream headers (>8KB). export const otelSdk = new NodeSDK({ textMapPropagator: new CompositePropagator({ propagators: [ new W3CTraceContextPropagator(), new W3CBaggagePropagator(), ], }), }); ``` #### Production Standard (Correct) > **Standard**: Decorates the standard propagator with an allowlist filter and strict byte partition limits (key, value, and cumulative total). Eliminates header bloat attacks and stops untrusted baggage keys from entering downstream trace workflows. ```typescript import { Context, TextMapGetter, TextMapPropagator, TextMapSetter, baggageEntryMetadataSymbol, propagation } from '@opentelemetry/api'; import { W3CBaggagePropagator } from '@opentelemetry/core'; const ALLOWED_BAGGAGE_KEYS = new Set(['traffic.tier', 'feature_flags.canary', 'region.origin']); const MAX_KEY_BYTES = 64; const MAX_VALUE_BYTES = 256; const MAX_TOTAL_BYTES = 2048; export class SanitizedBaggagePropagator implements TextMapPropagator { private readonly delegate = new W3CBaggagePropagator(); inject(context: Context, carrier: unknown, setter: TextMapSetter): void { this.delegate.inject(context, carrier, setter); } extract(context: Context, carrier: unknown, getter: TextMapGetter): Context { const rawContext = this.delegate.extract(context, carrier, getter); const incomingBaggage = propagation.getBaggage(rawContext); if (!incomingBaggage) return context; let sanitizedBaggage = propagation.createBaggage(); let cumulativeBytes = 0; for (const entry of incomingBaggage.getAllEntries()) { const [key, value] = entry; const keyBytes = Buffer.byteLength(key, 'utf8'); const valBytes = Buffer.byteLength(value.value, 'utf8'); if (!ALLOWED_BAGGAGE_KEYS.has(key)) continue; if (keyBytes > MAX_KEY_BYTES || valBytes > MAX_VALUE_BYTES) continue; if (cumulativeBytes + keyBytes + valBytes > MAX_TOTAL_BYTES) break; sanitizedBaggage = sanitizedBaggage.setEntry(key, value); cumulativeBytes += (keyBytes + valBytes); } return propagation.setBaggage(context, sanitizedBaggage); } fields(): string[] { return this.delegate.fields(); } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: OpenTelemetry Inbound W3C Baggage Scrubbing and Size Partitioning Standard

OpenTelemetry Inbound W3C Baggage Scrubbing and Size Partitioning Standard defines an industrial-grade behavioral standard for devops engineering. Mandates strict allowlisting, key-level length validation, and cumulative payload size partitioning for incoming W3C Baggage in distributed tracing setups. Prevents cross-tenant context injection, metadata privilege escalation, and downstream HTTP 431 (Request Header Fields Too Large) outages caused by unconstrained baggage propagation across 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 Inbound Baggage Passthrough Causing Header Poisoning and Downgrade Overflows 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 Inbound Baggage Passthrough Causing Header Poisoning and Downgrade Overflows	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:

Services MUST NEVER configure default `W3CBaggagePropagator` directly on edge-facing or multi-tenant entry points without a scrubbing decorator.

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.