OpenTelemetry W3C Baggage Cryptographic Invariant & PII Boundary Standard

--- description: OpenTelemetry W3C Baggage Cryptographic Invariant & PII Boundary Standard - Enforces strict schema validation, allowlisted key boundaries, and cryptographic HMAC signatures on all incoming and outgoing OpenTelemetry W3C Baggage headers. Prevents downstream privilege escalation through context tampering, suppresses cross-service identity spoofing, and eliminates GDPR/CCPA log contamination by blocking unauthorized baggage injection and redacting sensitive PII before trace propagation. globs: src/instrumentation/**/*.{ts,js}, src/telemetry/**/*.{ts,js}, src/middleware/**/*.{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-boundary-pii-redaction" --- # OpenTelemetry W3C Baggage Cryptographic Invariant & PII Boundary Standard > **Severity**: CRITICAL | **Category**: devops > **Anti-Pattern Warning**: Unvalidated W3C Baggage Passthrough Enabling Context Tampering and Downstream PII Leakage ## System Constraints You are a Principal Software Architect enforcing zero-trust boundaries on OpenTelemetry W3C Baggage context propagation. Distributed baggage operates across untrusted boundaries; therefore, unvalidated propagation of ambient baggage is treated as a critical remote code/privilege escalation risk. You must strictly enforce schema allowlisting, HMAC cryptographic signing on high-trust metadata, and programmatic PII redaction filters across all OpenTelemetry TextMapPropagators. ## Strict Guidelines - Services MUST NEVER accept or propagate unvalidated W3C Baggage headers; an explicit schema-driven allowlist must validate both baggage keys and value structures. - Engineers MUST ALWAYS implement a custom or wrapped TextMapPropagator that drops any baggage entry not present in the strict schema registry. - Privilege-bearing metadata (e.g., tenant_id, role, subject) in Baggage MUST include a companion cryptographic HMAC-SHA256 signature entry to verify origin authenticity before ingestion into internal contexts. - PII and sensitive identifiers (such as email, legal name, credit card tokens, session secrets, or internal IPs) MUST NEVER be injected into W3C Baggage or exported into downstream span attributes. - Inbound HTTP/gRPC extractors MUST purge unauthorized baggage mutations and log boundary violation metrics without echoing the malicious baggage values. - Telemetry exporters and tracing wrappers MUST enforce strict length constraints (e.g., maximum 64 bytes per key, 256 bytes per value) to prevent header-bloat amplification attacks. ## Bad vs Good Implementations ### W3C Baggage Interceptor and PII Redaction Filter #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Accepts raw incoming baggage headers unconditionally, injects unsanitized PII (user.email) into distributed context, and assigns tenant identity from user queries without schema validation or signature verification, allowing context spoofing and downstream compliance breaches. ```typescript import { propagation, context, Baggage } from '@opentelemetry/api'; import { Request, Response, NextFunction } from 'express'; // CRITICAL FLAW: Blindly forward incoming baggage and attach unvalidated user data export function telemetryMiddleware(req: Request, _res: Response, next: NextFunction) { const activeContext = propagation.extract(context.active(), req.headers); let baggage = propagation.getBaggage(activeContext) || propagation.createBaggage(); // Unchecked injection: untrusted user parameters and raw PII leaking into ambient context if (req.headers['x-user-email']) { baggage = baggage.setEntry('user.email', { value: req.headers['x-user-email'] as string }); } if (req.query.tenantId) { baggage = baggage.setEntry('tenant.id', { value: req.query.tenantId as string }); } // Propagates without validation or signature verification context.with(propagation.setBaggage(activeContext, baggage), () => { next(); }); } ``` #### Production Standard (Correct) > **Standard**: Implements an explicit schema allowlist with byte-length boundaries, checks regex constraints, validates cryptographic HMAC signatures on privileged keys (tenant.id), explicitly rejects PII-like keys, and silently drops any untrusted baggage before passing context downstream. ```typescript import { propagation, context, Baggage, BaggageEntry } from '@opentelemetry/api'; import { createHmac, timingSafeEqual } from 'crypto'; import { Request, Response, NextFunction } from 'express'; interface AllowedBaggageSpec { pattern: RegExp; maxBytes: number; requiresSignature?: boolean; } const BAGGAGE_ALLOWLIST: Record<string, AllowedBaggageSpec> = { 'tenant.id': { pattern: /^[a-z0-9_-]{1,64}$/i, maxBytes: 64, requiresSignature: true }, 'request.priority': { pattern: /^(high|medium|low)$/, maxBytes: 16 }, 'feature.flag.cohort': { pattern: /^[a-z0-9_]{1,32}$/i, maxBytes: 32 } }; const PII_FORBIDDEN_PATTERN = /(email|token|auth|bearer|ssn|name|phone|secret|password)/i; const HMAC_SECRET = process.env.BAGGAGE_HMAC_SECRET!; function verifyHmac(key: string, value: string, signature: string | undefined): boolean { if (!signature) return false; const expected = createHmac('sha256', HMAC_SECRET).update(`${key}:${value}`).digest('hex'); return signature.length === expected.length && timingSafeEqual(Buffer.from(signature), Buffer.from(expected)); } export function secureTelemetryMiddleware(req: Request, _res: Response, next: NextFunction): void { const extractedContext = propagation.extract(context.active(), req.headers); const incomingBaggage = propagation.getBaggage(extractedContext); let safeBaggage = propagation.createBaggage(); if (incomingBaggage) { for (const [key, entry] of incomingBaggage.getAllEntries()) { const spec = BAGGAGE_ALLOWLIST[key]; if (!spec || PII_FORBIDDEN_PATTERN.test(key) || entry.value.length > spec.maxBytes) { continue; // Drop untrusted, oversized, or suspicious keys } if (!spec.pattern.test(entry.value)) { continue; // Schema validation failed } if (spec.requiresSignature) { const sigKey = `${key}.sig`; const sigEntry = incomingBaggage.getEntry(sigKey); if (!sigEntry || !verifyHmac(key, entry.value, sigEntry.value)) { continue; // Signature missing or verification failed } safeBaggage = safeBaggage.setEntry(sigKey, sigEntry); } safeBaggage = safeBaggage.setEntry(key, entry); } } const cleanContext = propagation.setBaggage(extractedContext, safeBaggage); context.with(cleanContext, () => next()); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: OpenTelemetry W3C Baggage Cryptographic Invariant & PII Boundary Standard

OpenTelemetry W3C Baggage Cryptographic Invariant & PII Boundary Standard defines an industrial-grade behavioral standard for devops engineering. Enforces strict schema validation, allowlisted key boundaries, and cryptographic HMAC signatures on all incoming and outgoing OpenTelemetry W3C Baggage headers. Prevents downstream privilege escalation through context tampering, suppresses cross-service identity spoofing, and eliminates GDPR/CCPA log contamination by blocking unauthorized baggage injection and redacting sensitive PII before trace 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: Unvalidated W3C Baggage Passthrough Enabling Context Tampering and Downstream PII Leakage 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	Unvalidated W3C Baggage Passthrough Enabling Context Tampering and Downstream PII Leakage	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 accept or propagate unvalidated W3C Baggage headers

Services MUST NEVER accept or propagate unvalidated W3C Baggage headers; an explicit schema-driven allowlist must validate both baggage keys and value structures.

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.