OpenTelemetry W3C Baggage Context Sanitization and Boundary Filtering

--- description: OpenTelemetry W3C Baggage Context Sanitization and Boundary Filtering - Enforces strict gateway-level validation, allowlisting, and sanitization on incoming and outgoing W3C Baggage HTTP headers to prevent distributed context contamination. Blindly propagating baggage across untrusted trust boundaries causes severe PII leakage, credential exfiltration, and tenant impersonation vulnerabilities. Distributed context propagation must strictly parse, validate against an immutable allowlist, and re-sign or isolate operational metadata at system perimeters. globs: src/middleware/**/*.{ts,js}, src/gateway/**/*.{ts,js}, src/telemetry/**/*.{ts,js}, src/tracing/**/*.{ts,js} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/opentelemetry-w3c-baggage-sanitization-guardrail" --- # OpenTelemetry W3C Baggage Context Sanitization and Boundary Filtering > **Severity**: CRITICAL | **Category**: devops > **Anti-Pattern Warning**: Blind Ingress Extraction and Downstream Forwarding of Untrusted W3C Baggage Headers ## System Constraints You are a Principal Software Architect and Systems Security Engineer enforcing strict boundary controls on OpenTelemetry context propagation. W3C Baggage is arbitrary key-value metadata that flows transitively across distributed microservices. Unsanitized baggage headers allow malicious external actors or compromised internal microservices to inject unauthorized tenant identifiers, trace-level PII, or internal routing overrides. You must mandate strict allowlist-based boundary sanitization, drop foreign unapproved baggage entries at ingress/egress boundaries, and ensure tenant context is derived solely from verified cryptographically signed credentials. ## Strict Guidelines - Engineers MUST ALWAYS sanitize incoming `baggage` headers at edge gateways and ingress microservices before context binding. - Engineers MUST NOT use default OpenTelemetry `W3CCompositePropagator` at network boundaries without custom allowlist filtering middleware. - Services MUST drop any baggage key containing user identifiers, PII, authentication tokens, or internal cluster hostnames. - Services MUST derive critical context keys (such as `tenant.id` and `user.id`) solely from validated cryptographic tokens (e.g., verified JWTs) rather than trusting untrusted incoming baggage values. - Code SHOULD enforce maximum length and character validation constraints on all allowlisted baggage values (e.g., maximum 128 characters, matching `^[a-zA-Z0-9_.-]+$`). - Components NEVER re-inject unparsed or raw `baggage` request headers directly into outgoing HTTP, gRPC, or message queue metadata. ## Bad vs Good Implementations ### W3C Baggage Ingress Sanitization Middleware #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Directly calling propagation.extract blindly ingests client-supplied W3C baggage into the active OpenTelemetry context. This allows external actors to inject spoofed tenant IDs, internal operational flags, or malformed data that propagates across the entire downstream microservice fleet. ```typescript import { Request, Response, NextFunction } from 'express'; import { context, propagation } from '@opentelemetry/api'; // VULNERABLE: Direct extraction and forwarding of unvalidated baggage. // External clients can inject 'tenant.id=victim-tenant' or sensitive internal tokens, // which downstream internal services blindly trust and forward. export function traceContextMiddleware(req: Request, res: Response, next: NextFunction): void { const extractedContext = propagation.extract(context.active(), req.headers); context.with(extractedContext, () => { next(); }); } ``` #### Production Standard (Correct) > **Standard**: Filters incoming baggage against a strict, immutable allowlist and regex character check. Tenant context is derived strictly from verified authentication claims rather than untrusted header payloads, preventing tenant spoofing and trace pollution. ```typescript import { Request, Response, NextFunction } from 'express'; import { context, propagation, baggageEntryMetadataSymbol, BaggageEntry } from '@opentelemetry/api'; // Explicit allowlist of permissible transient operational baggage keys const ALLOWED_BAGGAGE_KEYS = new Set<string>(['traffic.source', 'experiment.variant', 'feature.tier']); const VALUE_REGEX = /^[a-zA-Z0-9_.-]{1,128}$/; export function secureBaggageMiddleware(req: Request, res: Response, next: NextFunction): void { // 1. Extract context using standard propagation const parentContext = propagation.extract(context.active(), req.headers); const rawBaggage = propagation.getBaggage(parentContext); // 2. Instantiate isolated, sanitized baggage collection let sanitizedBaggage = propagation.createBaggage(); if (rawBaggage) { for (const [key, entry] of rawBaggage.getAllEntries()) { // 3. Enforce allowlist and syntax validation; drop untrusted or rogue keys if (ALLOWED_BAGGAGE_KEYS.has(key) && VALUE_REGEX.test(entry.value)) { sanitizedBaggage = sanitizedBaggage.setEntry(key, entry); } } } // 4. Overwrite tenant identity strictly from authenticated session/JWT, NEVER from raw baggage const verifiedTenantId = (req as any).auth?.tenantId; if (verifiedTenantId && VALUE_REGEX.test(verifiedTenantId)) { sanitizedBaggage = sanitizedBaggage.setEntry('tenant.id', { value: verifiedTenantId, metadata: baggageEntryMetadataSymbol ? undefined : undefined }); } // 5. Bind sanitized baggage back to context const secureContext = propagation.setBaggage(parentContext, sanitizedBaggage); context.with(secureContext, () => { next(); }); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: OpenTelemetry W3C Baggage Context Sanitization and Boundary Filtering

OpenTelemetry W3C Baggage Context Sanitization and Boundary Filtering defines an industrial-grade behavioral standard for devops engineering. Enforces strict gateway-level validation, allowlisting, and sanitization on incoming and outgoing W3C Baggage HTTP headers to prevent distributed context contamination. Blindly propagating baggage across untrusted trust boundaries causes severe PII leakage, credential exfiltration, and tenant impersonation vulnerabilities. Distributed context propagation must strictly parse, validate against an immutable allowlist, and re-sign or isolate operational metadata at system perimeters. 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 Ingress Extraction and Downstream Forwarding of Untrusted W3C Baggage Headers 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 Ingress Extraction and Downstream Forwarding of Untrusted W3C Baggage Headers	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 incoming `baggage` headers at edge gateways and ingress microservices before context binding.

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.