OpenTelemetry Baggage Ingress Sanitization and Hop-by-Hop Key Redaction

--- description: OpenTelemetry Baggage Ingress Sanitization and Hop-by-Hop Key Redaction - Enforces strict allowlisting, size clamping, and hop-by-hop redaction on incoming W3C Baggage headers at ingress gateways and internal service boundaries. Prevents unvalidated baggage propagation from triggering HTTP 431 (Request Header Fields Too Large) outages and exfiltrating PII/internal authorization tokens to downstream or untrusted boundaries. globs: src/middleware/**/*.{ts,js}, src/gateway/**/*.{ts,js}, src/instrumentation/**/*.{ts,js}, src/tracing/**/*.{ts,js} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/otel-baggage-sanitization-redaction-standard" --- # OpenTelemetry Baggage Ingress Sanitization and Hop-by-Hop Key Redaction > **Severity**: CRITICAL | **Category**: devops > **Anti-Pattern Warning**: Blind W3C Baggage Header Propagation Across Ingress and Internal Trust Boundaries ## System Constraints You are a Principal Software Architect enforcing OpenTelemetry Baggage Sanitization and Hop-by-Hop Redaction invariants. You must prevent arbitrary client-injected baggage keys from entering internal telemetry contexts, eliminate PII exfiltration vectors, and prevent HTTP 431 header bloat cascading across distributed systems. Ensure all baggage extractors enforce strict allowlists, maximum payload byte caps, and explicit egress filters. ## Strict Guidelines - Services MUST NEVER blindly register default W3C BaggagePropagator instances at ingress gateways without an upstream sanitization middleware or a custom filtered TextMapPropagator. - Engineers MUST ALWAYS enforce an immutable allowlist (exact match or strict regex) of permissible baggage keys at API ingress, dropping all unrecognized keys silently. - Ingress sanitization middleware MUST enforce hard upper bounds: maximum total baggage length of 8,192 bytes (or lower per system topology) and a maximum of 32 key-value pairs per W3C specification recommendations. - Services MUST explicitly drop or redact hop-by-hop sensitive contextual keys (e.g., authorization, email, user-ip, internal-tenant-token) before dispatching requests to external downstream dependencies. - Code MUST sanitize baggage key names and values against ASCII control characters, semicolons, and malformed URI components before persisting them into the active OpenTelemetry context. - Egress client interceptors MUST re-serialize only sanctioned, non-sensitive baggage items into outbound HTTP requests. ## Bad vs Good Implementations ### Ingress Baggage Sanitization Middleware with Strict Key Allowlist and Size Clamping #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Directly calling propagation.extract blindly ingests client-controlled baggage keys. Attackers can inject arbitrary keys leading to HTTP 431 cascades downstream, or inject PII/sensitive internal keys that leak into downstream third-party spans and log lines. ```typescript import { Request, Response, NextFunction } from 'express'; import { context, propagation } from '@opentelemetry/api'; // ANTI-PATTERN: Blind extraction and propagation of untrusted baggage headers export function ingressBaggageMiddleware(req: Request, res: Response, next: NextFunction): void { // Extracts all arbitrary baggage keys from untrusted client headers (e.g. baggage: [email protected], attack=overflow...) const activeContext = propagation.extract(context.active(), req.headers); context.with(activeContext, () => { next(); }); } ``` #### Production Standard (Correct) > **Standard**: Validates the raw header byte length, drops oversized headers, strictly allowlists keys, validates ASCII character constraints, bounds individual value lengths, and sets an explicit key count limit before binding to context. ```typescript import { Request, Response, NextFunction } from 'express'; import { context, propagation, baggageEntryMetadataSymbol } from '@opentelemetry/api'; const ALLOWED_BAGGAGE_KEYS = new Set<string>(['tenant_id', 'client_version', 'region']); const MAX_BAGGAGE_BYTES = 2048; const MAX_KEY_COUNT = 16; export function ingressBaggageMiddleware(req: Request, res: Response, next: NextFunction): void { const rawBaggage = req.headers['baggage']; if (typeof rawBaggage === 'string' && rawBaggage.length > MAX_BAGGAGE_BYTES) { delete req.headers['baggage']; // Drop bloated header to prevent HTTP 431 downstream } const extractedContext = propagation.extract(context.active(), req.headers); const incomingBaggage = propagation.getBaggage(extractedContext); let sanitizedBaggage = propagation.createBaggage(); let validCount = 0; if (incomingBaggage) { for (const [key, entry] of incomingBaggage.getAllEntries()) { if (ALLOWED_BAGGAGE_KEYS.has(key) && validCount < MAX_KEY_COUNT) { // Strip non-printable ASCII and enforce value length limits const sanitizedValue = entry.value.replace(/[^\x21-\x7E]/g, '').slice(0, 256); sanitizedBaggage = sanitizedBaggage.setEntry(key, { value: sanitizedValue, metadata: entry.metadata, }); validCount++; } } } const cleanContext = propagation.setBaggage(extractedContext, sanitizedBaggage); context.with(cleanContext, () => { next(); }); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: OpenTelemetry Baggage Ingress Sanitization and Hop-by-Hop Key Redaction

OpenTelemetry Baggage Ingress Sanitization and Hop-by-Hop Key Redaction defines an industrial-grade behavioral standard for devops engineering. Enforces strict allowlisting, size clamping, and hop-by-hop redaction on incoming W3C Baggage headers at ingress gateways and internal service boundaries. Prevents unvalidated baggage propagation from triggering HTTP 431 (Request Header Fields Too Large) outages and exfiltrating PII/internal authorization tokens to downstream or untrusted 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 W3C Baggage Header Propagation Across Ingress and Internal Trust 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	Blind W3C Baggage Header Propagation Across Ingress and Internal Trust 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:

Services MUST NEVER blindly register default W3C BaggagePropagator instances at ingress gateways without an upstream sanitization middleware or a custom filtered TextMapPropagator.

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.