OpenTelemetry W3C Baggage Ingress Sanitization and Tenant Context Isolation

--- description: OpenTelemetry W3C Baggage Ingress Sanitization and Tenant Context Isolation - Enforces deterministic stripping, allowlisting, and cryptographic re-anchoring of W3C Baggage headers at API gateway and ingress boundaries. Prevents multi-tenant context spoofing, downstream trace attribute pollution, and tenant escalation caused by naive propagation of unauthenticated client-supplied baggage. globs: src/middleware/**/*.{ts,js}, src/gateway/**/*.{ts,js}, src/ingress/**/*.{ts,js}, src/telemetry/**/*.{ts,js}, apps/api-gateway/src/**/*.{ts,js} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/otel-w3c-baggage-tenant-ingress-sanitization" --- # OpenTelemetry W3C Baggage Ingress Sanitization and Tenant Context Isolation > **Severity**: CRITICAL | **Category**: devops > **Anti-Pattern Warning**: Naive Propagation of Client-Supplied W3C Baggage Headers Without Ingress Tenant Boundary Re-Anchoring ## System Constraints You are a Principal Platform Security and Telemetry Architect enforcing strict multi-tenant isolation within OpenTelemetry tracing pipelines. You must mandate that all edge gateways and ingress interceptors scrub unauthenticated W3C Baggage entries, enforce an explicit allowlist for propagateable keys, and overwrite tenant identifiers strictly from cryptographically verified identity tokens before passing baggage downstream. ## Strict Guidelines - Services MUST NEVER blindly pass client-supplied `baggage` HTTP headers into `propagation.extract()` without ingress sanitization. - Engineers MUST ALWAYS strip all reserved tenant-identifying baggage keys (e.g., `tenant.id`, `tenant.tier`, `auth.user_id`, `org.id`) at the ingress boundary. - Ingress middleware MUST synthesize and inject verified tenant baggage strictly from authenticated identity artifacts (e.g., validated JWT claims, verified mTLS peer identities). - Services MUST implement an explicit allowlist for acceptable non-tenant baggage entries forwarded by external clients (e.g., client-side synthetic transaction flags). - Gateway implementations MUST isolate the current OpenTelemetry execution context such that downstream HTTP/gRPC client spans only inherit sanitized, verified baggage instances. - Components NEVER accept raw baggage mutations from upstream proxies that reside outside the mutual TLS zero-trust mesh boundary. ## Bad vs Good Implementations ### Naive Baggage Propagation vs. Secure Ingress Sanitization Middleware #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Directly propagating incoming headers via propagation.extract imports untrusted W3C Baggage entries directly into the active tracing context. Downstream services and telemetry processors that trust baggage values for tenant routing or audit logs become vulnerable to tenant impersonation and metric poisoning. ```typescript import { Request, Response, NextFunction } from 'express'; import { context, propagation } from '@opentelemetry/api'; export function naiveIngressTracingMiddleware(req: Request, res: Response, next: NextFunction): void { // CRITICAL SECURITY FLAW: Extracts raw incoming headers including client-manipulated 'baggage'. // An external attacker can send 'baggage: tenant.id=target-corp,role=admin' to spoof context // consumed by downstream microservices for routing, billing, or authorization. const incomingContext = propagation.extract(context.active(), req.headers); context.with(incomingContext, () => { next(); }); } ``` #### Production Standard (Correct) > **Standard**: The secure implementation strips any unauthorized client baggage matching sensitive namespaces, strictly cross-checks third-party keys against an allowlist, and explicitly populates multi-tenant keys exclusively from the authenticated session context before context activation. ```typescript import { Request, Response, NextFunction } from 'express'; import { context, propagation, trace, propagation as otelPropagation } from '@opentelemetry/api'; const RESERVED_BAGGAGE_PREFIXES = ['tenant.', 'org.', 'auth.', 'sec.']; const ALLOWED_PUBLIC_BAGGAGE_KEYS = new Set(['synthetic-run-id', 'client-session-trace']); interface AuthenticatedRequest extends Request { authContext?: { tenantId: string; accountTier: string }; } export function secureIngressBaggageMiddleware(req: AuthenticatedRequest, res: Response, next: NextFunction): void { // 1. Extract raw context to preserve TraceContext (traceparent, tracestate) const extractedContext = otelPropagation.extract(context.active(), req.headers); const incomingBaggage = otelPropagation.getBaggage(extractedContext); // 2. Build a brand-new, isolated baggage instance let sanitizedBaggage = otelPropagation.createBaggage(); // 3. Filter external baggage against explicit allowlist and block reserved namespaces if (incomingBaggage) { for (const [key, entry] of incomingBaggage.getAllEntries()) { const isReserved = RESERVED_BAGGAGE_PREFIXES.some(prefix => key.startsWith(prefix)); if (!isReserved && ALLOWED_PUBLIC_BAGGAGE_KEYS.has(key)) { sanitizedBaggage = sanitizedBaggage.setEntry(key, entry); } } } // 4. Anchor verified tenant identity strictly from trusted authentication stage if (req.authContext?.tenantId) { sanitizedBaggage = sanitizedBaggage.setEntry('tenant.id', { value: req.authContext.tenantId, metadata: undefined }); sanitizedBaggage = sanitizedBaggage.setEntry('tenant.tier', { value: req.authContext.accountTier, metadata: undefined }); } // 5. Overwrite the baggage in the extracted context with the sanitized baggage const secureContext = otelPropagation.setBaggage(extractedContext, sanitizedBaggage); context.with(secureContext, () => { next(); }); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: OpenTelemetry W3C Baggage Ingress Sanitization and Tenant Context Isolation

OpenTelemetry W3C Baggage Ingress Sanitization and Tenant Context Isolation defines an industrial-grade behavioral standard for devops engineering. Enforces deterministic stripping, allowlisting, and cryptographic re-anchoring of W3C Baggage headers at API gateway and ingress boundaries. Prevents multi-tenant context spoofing, downstream trace attribute pollution, and tenant escalation caused by naive propagation of unauthenticated client-supplied baggage. 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: Naive Propagation of Client-Supplied W3C Baggage Headers Without Ingress Tenant Boundary Re-Anchoring 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	Naive Propagation of Client-Supplied W3C Baggage Headers Without Ingress Tenant Boundary Re-Anchoring	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 pass client-supplied `baggage` HTTP headers into `propagation.extract()` without ingress sanitization.

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.