OpenTelemetry W3C Baggage Dynamic Redaction & Context Ingress Standard

--- description: OpenTelemetry W3C Baggage Dynamic Redaction & Context Ingress Standard - Enforces strict PII filtering, cryptographically secure hash masking, and allowlist validation on W3C Baggage headers at distributed ingress boundaries prior to trace context propagation. Prevents accidental data exfiltration and compliance violations across distributed service meshes caused by unvetted downstream context propagation. globs: src/middleware/**/*.{ts,js}, src/tracing/**/*.{ts,js}, src/telemetry/**/*.{ts,js}, src/interceptors/**/*.{ts,js}, src/gateway/**/*.{ts,js} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/otel-w3c-baggage-dynamic-redaction-standard" --- # OpenTelemetry W3C Baggage Dynamic Redaction & Context Ingress Standard > **Severity**: CRITICAL | **Category**: devops > **Anti-Pattern Warning**: Blind Context Propagation of Raw Ingress Baggage Headers into Downstream Distributed Calls ## System Constraints You are a Principal Software Architect enforcing the OpenTelemetry W3C Baggage Dynamic Redaction & Context Ingress Standard. Mandate that incoming `baggage` HTTP headers and downstream trace contexts undergo strict zero-trust sanitization. Reject direct passthrough of baggage items. Enforce compile-time and runtime allowlists, regex-based PII redaction (emails, SSNs, tokens, session IDs), total byte-length caps, and secure hashing of sensitive identifiers before attaching keys to the active OpenTelemetry context. ## Strict Guidelines - Engineers MUST ALWAYS parse incoming W3C Baggage headers through an explicit schema-driven allowlist filter before injecting them into the OpenTelemetry `Context`. - Engineers MUST NOT propagate raw incoming baggage headers (`req.headers['baggage']`) directly to downstream HTTP, gRPC, or messaging clients without passing through a sanitizing context manager. - Middleware MUST strip, redact, or hash sensitive contextual identifiers (such as user emails, IP addresses, JWTs, API keys, or raw tenant personal identifiers) using deterministic one-way HMAC or SHA-256 before propagation. - Services MUST enforce strict envelope limits: individual baggage item values MUST NOT exceed 256 bytes, and aggregate baggage payload per request MUST NOT exceed 4096 bytes, dropping non-essential keys if the cap is reached. - Components NEVER store mutable credentials, authorization bearer tokens, or PII in `baggage`; baggage is strictly reserved for operational routing metadata, canary flags, and non-sensitive correlation coordinates. ## Bad vs Good Implementations ### Ingress Baggage Sanitization & Dynamic PII Redaction #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Directly extracting propagation headers without inspect-and-redact mechanisms permits downstream propagation of raw PII, sensitive user-agent telemetry, and unrestricted tokens, violating GDPR/HIPAA compliance boundaries. ```typescript import { Request, Response, NextFunction } from 'express'; import { context, propagation } from '@opentelemetry/api'; // ANTI-PATTERN: Blindly extracts and activates untrusted baggage // Propagates raw PII and unvalidated headers across service boundaries export function tracingMiddleware(req: Request, _res: Response, next: NextFunction): void { const extractedContext = propagation.extract(context.active(), req.headers); // Direct propagation allows sensitive headers (e.g. '[email protected],api-key=secret') // to flow transparently to all downstream microservices. context.with(extractedContext, () => { next(); }); } ``` #### Production Standard (Correct) > **Standard**: Implements an explicit allowlist, scans for inline PII signatures, executes pseudonymization via SHA-256 for trace-identifiable correlation, and enforces byte-length caps before updating the ambient active context. ```typescript import { Request, Response, NextFunction } from 'express'; import { context, propagation, baggageEntryMetadataSymbol, Baggage } from '@opentelemetry/api'; import { createHash } from 'crypto'; const ALLOWED_BAGGAGE_KEYS = new Set(['tenant_id', 'tier', 'canary_group', 'request_origin']); const PII_REGEX = /[\w.-]+@[\w.-]+\.[A-Za-z]{2,}|bearer\s+[a-zA-Z0-9._-]+/i; const MAX_BAGGAGE_SIZE_BYTES = 4096; function sanitizeBaggageEntry(key: string, value: string): string | null { if (!ALLOWED_BAGGAGE_KEYS.has(key)) return null; if (PII_REGEX.test(value)) { // Deterministic pseudonymization for correlation without leaking plaintext PII return createHash('sha256').update(value).digest('hex').substring(0, 16); } return value.substring(0, 256); } export function secureBaggageMiddleware(req: Request, _res: Response, next: NextFunction): void { const extractedContext = propagation.extract(context.active(), req.headers); const rawBaggage = propagation.getBaggage(extractedContext); let sanitizedBaggage = propagation.createBaggage(); let currentPayloadSize = 0; if (rawBaggage) { for (const [key, entry] of rawBaggage.getAllEntries()) { const sanitizedVal = sanitizeBaggageEntry(key, entry.value); if (sanitizedVal !== null) { const entryCost = key.length + sanitizedVal.length + 2; if (currentPayloadSize + entryCost <= MAX_BAGGAGE_SIZE_BYTES) { sanitizedBaggage = sanitizedBaggage.setEntry(key, { value: sanitizedVal }); currentPayloadSize += entryCost; } } } } const secureContext = propagation.setBaggage(extractedContext, sanitizedBaggage); context.with(secureContext, () => next()); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: OpenTelemetry W3C Baggage Dynamic Redaction & Context Ingress Standard

OpenTelemetry W3C Baggage Dynamic Redaction & Context Ingress Standard defines an industrial-grade behavioral standard for devops engineering. Enforces strict PII filtering, cryptographically secure hash masking, and allowlist validation on W3C Baggage headers at distributed ingress boundaries prior to trace context propagation. Prevents accidental data exfiltration and compliance violations across distributed service meshes caused by unvetted downstream context propagation. 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 Context Propagation of Raw Ingress Baggage Headers into Downstream Distributed Calls 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 Context Propagation of Raw Ingress Baggage Headers into Downstream Distributed Calls	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 parse incoming W3C Baggage headers through an explicit schema-driven allowlist filter before injecting them into the OpenTelemetry `Context`.

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.