OpenTelemetry W3C Baggage Redaction and PII Erasure Gatekeeper

--- description: OpenTelemetry W3C Baggage Redaction and PII Erasure Gatekeeper - Enforces strict zero-trust schema validation, allowlist enforcement, and cryptographic masking on distributed W3C Baggage and TraceState headers at edge perimeters. Prevents propagation of sensitive identity tokens, credentials, and regulatory PII (GDPR/HIPAA/CCPA) into downstream distributed contexts and telemetry observability backends. globs: src/telemetry/**/*.ts, src/middleware/**/*.ts, src/tracing/**/*.ts, src/instrumentation/**/*.ts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/opentelemetry-w3c-baggage-redaction-pii-erasure-gatekeeper" --- # OpenTelemetry W3C Baggage Redaction and PII Erasure Gatekeeper > **Severity**: CRITICAL | **Category**: devops > **Anti-Pattern Warning**: Unconstrained Ingress Propagation and Span Injection of Raw W3C Baggage ## System Constraints You are a Principal Software Architect enforcing zero-trust OpenTelemetry security standards. You must strictly mandate that all distributed context extraction (W3C Baggage, TraceState) passes through a declarative sanitization and redaction gatekeeper at boundary perimeters. Reject any implementation that blindly accepts, forwards, or logs unverified baggage keys or raw high-cardinality PII values into active span attributes. ## Strict Guidelines - Services MUST ALWAYS wrap default OpenTelemetry context propagators (e.g., `W3CBaggagePropagator`) with a strict allowlist-based gatekeeper before extracting or injecting context. - Engineers MUST NOT copy unsanitized W3C Baggage key-value pairs directly into span attributes or downstream HTTP headers. - Gatekeeper filters MUST enforce strict byte-length ceilings (maximum 256 bytes per baggage value) and match keys against an immutable canonical allowlist. - Components NEVER store credentials, bearer tokens, email addresses, payment identifiers, or national IDs in W3C Baggage; pseudonymous tenant or correlation identifiers MUST be strictly validated via deterministic regular expressions. - Telemetry processors MUST drop or cryptographically hash all TraceState and Baggage attributes during `onEnd` callbacks before spans are serialized to collectors. ## Bad vs Good Implementations ### W3C Baggage Ingress Sanitization and PII Redaction #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Default context propagation indiscriminately captures baggage values sent by untrusted clients or external services and attaches them as span attributes. This leaks unencrypted PII, auth headers, and session tokens into central telemetry collectors (Jaeger, Datadog, Honeycomb) in violation of GDPR and HIPAA. ```typescript import { baggage, context, trace } from '@opentelemetry/api'; import { Request, Response, NextFunction } from 'express'; export function telemetryMiddleware(req: Request, res: Response, next: NextFunction): void { const currentBaggage = baggage.getBaggage(context.active()); const span = trace.getActiveSpan(); // CRITICAL SECURITY FLAW: Blindly copying all baggage items into span attributes // Exposes PII (e.g., user.email, auth_token, ssn) to external collectors and logs if (currentBaggage && span) { for (const [key, entry] of currentBaggage.getAllEntries()) { span.setAttribute(`baggage.${key}`, entry.value); } } next(); } ``` #### Production Standard (Correct) > **Standard**: Implements an explicit zero-trust perimeter gatekeeper. Incoming baggage keys must pass an immutable canonical allowlist with strict regex format validation and maximum length enforcement. Unsanitized baggage is completely pruned before span attribution or downstream context propagation. ```typescript import { baggage, context, trace, Baggage, BaggageEntry } from '@opentelemetry/api'; import { Request, Response, NextFunction } from 'express'; const ALLOWED_BAGGAGE_RULES: Readonly<Record<string, RegExp>> = Object.freeze({ 'tenant.id': /^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/i, 'request.priority': /^(high|medium|low)$/, 'region': /^[a-z]{2}-[a-z]+-\d{1}$/, }); const MAX_BAGGAGE_VALUE_LENGTH = 128; export function sanitizeTelemetryContext(incomingBaggage: Baggage | undefined): Baggage { let cleanBaggage = baggage.createBaggage(); if (!incomingBaggage) return cleanBaggage; for (const [key, pattern] of Object.entries(ALLOWED_BAGGAGE_RULES)) { const entry: BaggageEntry | undefined = incomingBaggage.getEntry(key); if (entry && entry.value.length <= MAX_BAGGAGE_VALUE_LENGTH && pattern.test(entry.value)) { cleanBaggage = cleanBaggage.setEntry(key, { value: entry.value, metadata: entry.metadata }); } } return cleanBaggage; } export function telemetryGatekeeperMiddleware(req: Request, res: Response, next: NextFunction): void { const rawBaggage = baggage.getBaggage(context.active()); const sanitized = sanitizeTelemetryContext(rawBaggage); const sanitizedContext = baggage.setBaggage(context.active(), sanitized); context.with(sanitizedContext, () => { const span = trace.getActiveSpan(); if (span) { for (const [key, entry] of sanitized.getAllEntries()) { span.setAttribute(`telemetry.context.${key}`, entry.value); } } next(); }); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: OpenTelemetry W3C Baggage Redaction and PII Erasure Gatekeeper

OpenTelemetry W3C Baggage Redaction and PII Erasure Gatekeeper defines an industrial-grade behavioral standard for devops engineering. Enforces strict zero-trust schema validation, allowlist enforcement, and cryptographic masking on distributed W3C Baggage and TraceState headers at edge perimeters. Prevents propagation of sensitive identity tokens, credentials, and regulatory PII (GDPR/HIPAA/CCPA) into downstream distributed contexts and telemetry observability backends. 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: Unconstrained Ingress Propagation and Span Injection of Raw W3C Baggage 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	Unconstrained Ingress Propagation and Span Injection of Raw W3C Baggage	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 wrap default OpenTelemetry context propagators (e.g., `W3CBaggagePropagator`) with a strict allowlist-based gatekeeper before extracting or injecting 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.