OpenTelemetry W3C Baggage Header Sanitization and Trust-Boundary Propagation

--- description: OpenTelemetry W3C Baggage Header Sanitization and Trust-Boundary Propagation - Enforces strict trust boundaries, size budgets, and schema validation on W3C Baggage headers entering or exiting asynchronous message brokers (e.g., Kafka, RabbitMQ, SQS). Eliminates multitenant cross-contamination, PII leakage, and unbounded HTTP/broker header inflation vulnerabilities (HTTP 431 / broker message size rejection). globs: src/**/tracing/**/*.{ts,js}, src/**/telemetry/**/*.{ts,js}, src/**/messaging/**/*.{ts,js}, src/**/kafka/**/*.{ts,js}, src/**/middleware/**/*.{ts,js} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/otel-baggage-sanitization-propagation-boundary" --- # OpenTelemetry W3C Baggage Header Sanitization and Trust-Boundary Propagation > **Severity**: CRITICAL | **Category**: devops > **Anti-Pattern Warning**: Blind Passthrough of Unvalidated, Unbounded W3C Baggage Across Heterogeneous Message Brokers ## System Constraints You are a Principal Software Architect and Site Reliability Engineer enforcing OpenTelemetry W3C Baggage hygiene. You mandate that OpenTelemetry Baggage is never treated as an arbitrary distributed cache. You enforce an explicit allowlist of baggage keys, strict per-entry and total-size limits matching RFC 7230/W3C specifications, tenant boundary enforcement, and redacting/stripping unvalidated context across asynchronous message queues. ## Strict Guidelines - Engineers MUST ALWAYS sanitize, validate, and prune W3C Baggage at network and asynchronous messaging ingress/egress boundaries. - Engineers MUST NOT propagate raw, unparsed incoming baggage headers across asynchronous event brokers without evaluating against an explicit key allowlist. - Services MUST enforce a strict total baggage size budget (maximum 4096 bytes total, maximum 64 entries, max 256 bytes per key-value pair) to prevent HTTP 431 Request Header Fields Too Large crashes. - Services MUST extract only verified tenant identifiers from cryptographically signed authentication contexts (JWT/mTLS) instead of trusting baggage tenant keys received from untrusted clients. - Components NEVER store PII, credentials, access tokens, or arbitrary payload blobs inside OpenTelemetry Baggage. ## Bad vs Good Implementations ### Unbounded Baggage Passthrough vs. Boundary-Gated Sanitized Propagation in Kafka Producer #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Directly injecting ambient OpenTelemetry context into message broker headers propagates unvalidated, unbudgeted client-originating baggage. This causes header inflation (exceeding Kafka max.message.bytes or downstream HTTP 431) and permits tenant-spoofing via untrusted incoming baggage keys. ```typescript import { propagation, context } from '@opentelemetry/api'; import { ProducerRecord } from 'kafkajs'; // ANTI-PATTERN: Blindly injecting ambient context containing unverified, // potentially unbounded client baggage into Kafka message headers. export async function publishEvent(topic: string, message: unknown): Promise<ProducerRecord> { const headers: Record<string, string> = {}; // Injects raw baggage directly, propagating unverified client-provided tenant_id // and arbitrarily bloated headers that exceed broker limits or leak across tenants propagation.inject(context.active(), headers); return { topic, messages: [{ value: JSON.stringify(message), headers }], }; } ``` #### Production Standard (Correct) > **Standard**: Enforces an immutable allowlist, overrides security-critical values (tenant.id) from verified session credentials, and enforces byte-size guardrails to guarantee safe broker propagation without header inflation or tenant contamination. ```typescript import { propagation, context, trace, Baggage, BaggageEntry } from '@opentelemetry/api'; import { ProducerRecord } from 'kafkajs'; const ALLOWED_BAGGAGE_KEYS = new Set(['tenant.id', 'feature.flags', 'client.type']); const MAX_BAGGAGE_BYTES = 2048; const MAX_KEY_VALUE_BYTES = 256; export function sanitizeBaggageBoundary( activeContext = context.active(), trustedTenantId: string ): Baggage { const incomingBaggage = propagation.getBaggage(activeContext); let totalBytes = 0; const sanitizedEntries: Record<string, BaggageEntry> = {}; // Enforce authoritative, authenticated tenant boundary sanitizedEntries['tenant.id'] = { value: trustedTenantId }; totalBytes += 'tenant.id'.length + trustedTenantId.length; if (incomingBaggage) { for (const [key, entry] of incomingBaggage.getAllEntries()) { if (!ALLOWED_BAGGAGE_KEYS.has(key) || key === 'tenant.id') continue; const entryBytes = key.length + entry.value.length; if (entryBytes > MAX_KEY_VALUE_BYTES) continue; if (totalBytes + entryBytes > MAX_BAGGAGE_BYTES) break; sanitizedEntries[key] = { value: entry.value }; totalBytes += entryBytes; } } return propagation.createBaggage(sanitizedEntries); } export async function publishEvent(topic: string, message: unknown, trustedTenantId: string): Promise<ProducerRecord> { const sanitizedBaggage = sanitizeBaggageBoundary(context.active(), trustedTenantId); const cleanContext = propagation.setBaggage(trace.setSpan(context.active(), trace.getActiveSpan(context.active())!), sanitizedBaggage); const headers: Record<string, string> = {}; propagation.inject(cleanContext, headers); return { topic, messages: [{ value: JSON.stringify(message), headers }], }; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: OpenTelemetry W3C Baggage Header Sanitization and Trust-Boundary Propagation

OpenTelemetry W3C Baggage Header Sanitization and Trust-Boundary Propagation defines an industrial-grade behavioral standard for devops engineering. Enforces strict trust boundaries, size budgets, and schema validation on W3C Baggage headers entering or exiting asynchronous message brokers (e.g., Kafka, RabbitMQ, SQS). Eliminates multitenant cross-contamination, PII leakage, and unbounded HTTP/broker header inflation vulnerabilities (HTTP 431 / broker message size rejection). 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 Passthrough of Unvalidated, Unbounded W3C Baggage Across Heterogeneous Message Brokers 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 Passthrough of Unvalidated, Unbounded W3C Baggage Across Heterogeneous Message Brokers	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 sanitize, validate, and prune W3C Baggage at network and asynchronous messaging ingress/egress boundaries.

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.