OpenTelemetry Baggage Ingress Sanitization and Boundary Validation Standard

Enforces strict perimeter schema validation, maximum byte-length constraints, and allowlist-based stripping of W3C Baggage HTTP headers (`baggage`) at API gateways and ingress proxies. Prevents untrusted external clients from injecting unvalidated contextual key-value pairs that cause downstream memory amplification attacks, log poisoning, or accidental exfiltration of personally identifiable information (PII). Unsanitized external baggage must never cross from untrusted public networks into internal trace contexts.

--- description: OpenTelemetry Baggage Ingress Sanitization and Boundary Validation Standard - Enforces strict perimeter schema validation, maximum byte-length constraints, and allowlist-based stripping of W3C Baggage HTTP headers (`baggage`) at API gateways and ingress proxies. Prevents untrusted external clients from injecting unvalidated contextual key-value pairs that cause downstream memory amplification attacks, log poisoning, or accidental exfiltration of personally identifiable information (PII). Unsanitized external baggage must never cross from untrusted public networks into internal trace contexts. globs: src/gateway/**/*.{ts,js}, src/middleware/**/*.{ts,js}, src/plugins/**/*.{ts,js}, src/tracing/**/*.{ts,js} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/otel-baggage-ingress-sanitization-standard-opentelemetry-ba-720" --- # OpenTelemetry Baggage Ingress Sanitization and Boundary Validation Standard > **Severity**: CRITICAL | **Category**: devops > **Anti-Pattern Warning**: Pass-Through of Arbitrary W3C Baggage Headers Across Public Network Boundaries ## System Constraints You are a Principal Software Architect and Security Engineer enforcing the OpenTelemetry Baggage Ingress Sanitization Standard. W3C Baggage propagated over HTTP (`baggage` header) carries application metadata across microservice boundaries, but external clients can exploit unchecked baggage to inject arbitrary payloads, PII, or attack vectors that amplify across all downstream distributed services. You must mandate that perimeter ingress gateways strictly strip all raw external baggage headers by default or filter them through an explicit, typed allowlist with bounded byte lengths and character regex validation. ## Strict Guidelines - Perimeter gateways MUST ALWAYS strip the incoming `baggage` HTTP header completely unless a strictly enforced allowlist configuration explicitly permits designated keys. - Engineers MUST NOT allow unbounded Baggage header sizes; the total sanitized baggage header size MUST NOT exceed 8192 bytes, and individual key-value pairs MUST NOT exceed 256 bytes for keys and 2048 bytes for values. - Sanitizers MUST validate baggage keys against the strict W3C token character set (RFC 7230 / RFC 9110 token) and reject or discard keys containing control characters, spaces, or delimiters. - Perimeter sanitization logic MUST NEVER permit keys matching common sensitive or PII patterns (e.g., `*token*`, `*auth*`, `*secret*`, `*email*`, `*ssn*`, `*cookie*`, `*user_id*`) to propagate from untrusted external sources. - Internal distributed context propagation MUST rebuild the OpenTelemetry `Context` via `propagation.setBaggage` using only the validated and normalized subset of entries, discarding malformed or oversized entries with incremented security telemetry metrics. - Services MUST log discarded or malformed external baggage attempts at the WARN level with sanitized diagnostics (counter metrics and header length only, omitting raw values to prevent log injection). ## Bad vs Good Implementations ### Ingress Baggage Sanitization Middleware for Fastify / Express Gateways #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Directly running `propagation.extract()` against untrusted perimeter headers captures arbitrary external `baggage` without length limits or key validation. This exposes internal downstream microservices to memory exhaustion, context stuffing attacks, and security policy bypasses. ```typescript import { Request, Response, NextFunction } from 'express'; import { propagation, defaultTextMapGetter, ROOT_CONTEXT } from '@opentelemetry/api'; // ANTI-PATTERN: Blindly propagating untrusted external baggage context into downstream trace export function ingressTracingMiddleware(req: Request, res: Response, next: NextFunction): void { // Extracts incoming traceparent and unvalidated raw baggage from untrusted client const extractedContext = propagation.extract(ROOT_CONTEXT, req.headers, defaultTextMapGetter); // Directly binds untrusted client baggage to active execution context // Allows unbounded payload memory consumption and arbitrary PII/auth injection req.openTelemetryContext = extractedContext; next(); } ``` #### Production Standard (Correct) > **Standard**: Strips raw `baggage` from extraction, validates incoming baggage against a strict key allowlist, verifies key regex conformances, enforces absolute size bounds, and explicitly reconstructs a trusted OpenTelemetry Baggage context. ```typescript import { Request, Response, NextFunction } from 'express'; import { propagation, defaultTextMapGetter, ROOT_CONTEXT, trace, createBaggage } from '@opentelemetry/api'; // PRODUCTION INVARIANT: Perimeter allowlist with strict boundary enforcement const ALLOWED_BAGGAGE_KEYS = new Set(['tenant_id', 'client_tier', 'region']); const MAX_TOTAL_BAGGAGE_BYTES = 2048; const MAX_VALUE_BYTES = 256; const KEY_REGEX = /^[a-zA-Z0-9!#$%&'*+\-.^_`|~]+$/; export function sanitizedIngressBaggageMiddleware(req: Request, _res: Response, next: NextFunction): void { // 1. Extract raw trace context (e.g., traceparent) without accepting external baggage const headersCopy = { ...req.headers }; const rawBaggageHeader = headersCopy['baggage']; delete headersCopy['baggage']; let activeContext = propagation.extract(ROOT_CONTEXT, headersCopy, defaultTextMapGetter); // 2. Safely parse and sanitize external baggage if present if (typeof rawBaggageHeader === 'string' && rawBaggageHeader.length <= MAX_TOTAL_BAGGAGE_BYTES) { const sanitizedEntries: Record<string, { value: string }> = {}; const pairs = rawBaggageHeader.split(','); for (const pair of pairs) { const [rawKey, ...rest] = pair.split('='); if (!rawKey || rest.length === 0) continue; const key = rawKey.trim(); const value = rest.join('=').trim(); if ( ALLOWED_BAGGAGE_KEYS.has(key) && KEY_REGEX.test(key) && value.length <= MAX_VALUE_BYTES ) { sanitizedEntries[key] = { value: encodeURIComponent(decodeURIComponent(value)) }; } } if (Object.keys(sanitizedEntries).length > 0) { const validatedBaggage = createBaggage(sanitizedEntries); activeContext = propagation.setBaggage(activeContext, validatedBaggage); } } // 3. Bind only validated context to request req.openTelemetryContext = activeContext; next(); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: OpenTelemetry Baggage Ingress Sanitization and Boundary Validation Standard

OpenTelemetry Baggage Ingress Sanitization and Boundary Validation Standard defines an industrial-grade behavioral standard for devops engineering. Enforces strict perimeter schema validation, maximum byte-length constraints, and allowlist-based stripping of W3C Baggage HTTP headers (`baggage`) at API gateways and ingress proxies. Prevents untrusted external clients from injecting unvalidated contextual key-value pairs that cause downstream memory amplification attacks, log poisoning, or accidental exfiltration of personally identifiable information (PII). Unsanitized external baggage must never cross from untrusted public networks into internal trace contexts. 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: Pass-Through of Arbitrary W3C Baggage Headers Across Public Network Boundaries 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	Pass-Through of Arbitrary W3C Baggage Headers Across Public Network Boundaries	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:

Perimeter gateways MUST ALWAYS strip the incoming `baggage` HTTP header completely unless a strictly enforced allowlist configuration explicitly permits designated keys.

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.