OpenTelemetry Baggage Context Sanitization and Boundary Filtering Standard

--- description: OpenTelemetry Baggage Context Sanitization and Boundary Filtering Standard - Enforces deterministic ingress filtering and validation of OpenTelemetry Baggage metadata across service trust boundaries. Prevents header spoofing, tenant injection, and telemetry buffer exhaustion by constraining baggage keys to strict namespace regexes, validating payload sizes, and stripping untrusted propagation headers at boundary gateways. globs: src/telemetry/**/*.{ts,js}, src/middleware/**/*.{ts,js}, src/tracing/**/*.{ts,js}, src/instrumentation/**/*.{ts,js} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/opentelemetry-baggage-sanitization-standard-opentelemetry-ba-254" --- # OpenTelemetry Baggage Context Sanitization and Boundary Filtering Standard > **Severity**: CRITICAL | **Category**: devops > **Anti-Pattern Warning**: Blind Ingress Baggage Propagation Without Trust Boundary Filtering or Key Allowlisting ## System Constraints You are a Principal Software Architect enforcing the OpenTelemetry Baggage Context Sanitization Standard. Distributed trace context propagation must never pass unverified, raw W3C baggage headers across untrusted service boundaries. You must enforce explicit allowlists, regex key constraints, namespace isolation, and payload bounds on all incoming and outgoing baggage context. ## Strict Guidelines - Services MUST ALWAYS strip incoming raw 'baggage' HTTP headers at public ingress boundaries unless extracted and sanitized by a custom TextMapPropagator with an explicit allowlist. - Engineers MUST NEVER inject unvalidated user-controlled parameters directly into Baggage without namespace-prefix verification and character set validation. - Baggage keys MUST strictly adhere to the standardized organizational regex format (e.g., `^[a-z0-9_\-]+(\.[a-z0-9_\-]+)+$`) to prevent prototype pollution and metric label poisoning. - Baggage values MUST NOT exceed 256 bytes per entry, and cumulative baggage size MUST NOT exceed 2048 bytes per request context. - Services MUST drop or reject any baggage key containing security-critical identifiers (e.g., 'tenant_id', 'user_role', 'is_admin') unless the request originates from a cryptographically verified internal mTLS trust domain. ## Bad vs Good Implementations ### Unsanitized vs. Allowlist-Sanitized Custom Baggage Propagator #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Default OpenTelemetry W3CBaggagePropagator extracts all arbitrary key-value pairs from the HTTP 'baggage' header. Untrusted clients can spoof tenant IDs, tamper with downstream authorization policies that read baggage, or execute denial of service attacks by saturating downstream memory with large baggage payloads. ```typescript import { Context, defaultTextMapGetter, TextMapPropagator } from '@opentelemetry/api'; import { W3CBaggagePropagator } from '@opentelemetry/core'; // ANTI-PATTERN: Default W3CBaggagePropagator extracts all untrusted external headers // allowing malicious callers to inject 'tenant_id', 'is_admin', or arbitrary large strings. export const unsafePropagator: TextMapPropagator = new W3CBaggagePropagator(); export function applyIngressTracing(carrier: Record<string, string | string[] | undefined>): Context { // Unfiltered context extraction directly into the active tracing context return unsafePropagator.extract(Context.ROOT, carrier, defaultTextMapGetter); } ``` #### Production Standard (Correct) > **Standard**: Implements an explicit allowlist and structural constraints using a custom TextMapPropagator. Keys are validated against an allowed regex namespace, individual values are bounded to 256 bytes, and cumulative size is capped to prevent telemetry buffer exhaustion and unauthorized context escalation. ```typescript import { Context, defaultTextMapGetter, TextMapPropagator, baggageUtils, propagation } from '@opentelemetry/api'; import { W3CBaggagePropagator } from '@opentelemetry/core'; const ALLOWED_BAGGAGE_KEY_PATTERN = /^corp\.ctx\.(app_version|request_origin|experiment_id)$/; const MAX_KEY_LENGTH = 64; const MAX_VALUE_LENGTH = 256; const MAX_TOTAL_BAGGAGE_BYTES = 2048; export class SanitizedBaggagePropagator implements TextMapPropagator { private readonly basePropagator = new W3CBaggagePropagator(); inject(context: Context, carrier: unknown, setter: any): void { this.basePropagator.inject(context, carrier, setter); } extract(context: Context, carrier: unknown, getter = defaultTextMapGetter): Context { const extractedContext = this.basePropagator.extract(context, carrier, getter); const currentBaggage = propagation.getBaggage(extractedContext); if (!currentBaggage) return context; let sanitizedBaggage = propagation.createBaggage(); let totalBytes = 0; for (const [key, entry] of currentBaggage.getAllEntries()) { if (!ALLOWED_BAGGAGE_KEY_PATTERN.test(key) || key.length > MAX_KEY_LENGTH) { continue; // Strip disallowed or malformed keys } if (entry.value.length > MAX_VALUE_LENGTH) { continue; // Discard oversized entries } const entryBytes = Buffer.byteLength(key, 'utf8') + Buffer.byteLength(entry.value, 'utf8'); if (totalBytes + entryBytes > MAX_TOTAL_BAGGAGE_BYTES) { break; // Hard cap on cumulative context size } totalBytes += entryBytes; sanitizedBaggage = sanitizedBaggage.setEntry(key, entry); } return propagation.setBaggage(context, sanitizedBaggage); } fields(): string[] { return this.basePropagator.fields(); } } ```

Architectural Specification & Invariant Rationale

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

OpenTelemetry Baggage Context Sanitization and Boundary Filtering Standard defines an industrial-grade behavioral standard for devops engineering. Enforces deterministic ingress filtering and validation of OpenTelemetry Baggage metadata across service trust boundaries. Prevents header spoofing, tenant injection, and telemetry buffer exhaustion by constraining baggage keys to strict namespace regexes, validating payload sizes, and stripping untrusted propagation headers at boundary gateways. 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 Baggage Propagation Without Trust Boundary Filtering or Key Allowlisting 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 Baggage Propagation Without Trust Boundary Filtering or Key Allowlisting	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 ALWAYS strip incoming raw 'baggage' HTTP headers at public ingress boundaries unless extracted and sanitized by a custom TextMapPropagator with an explicit allowlist.

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.