OpenTelemetry W3C Baggage Multi-Tenant Boundary Quarantine Guardrail

--- description: OpenTelemetry W3C Baggage Multi-Tenant Boundary Quarantine Guardrail - Incoming W3C Baggage headers at ingress boundaries must never be propagated downstream without strict sanitization, authentication-driven claim verification, and tenant quarantine. Propagating raw, unauthenticated tenant context allows untrusted actors to forge tenant boundaries, poison telemetry datasets, and induce multi-tenant data bleed in downstream services. globs: src/middleware/**/*.{ts,js}, src/tracing/**/*.{ts,js}, src/telemetry/**/*.{ts,js}, src/server/**/*.{ts,js} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/otel-w3c-baggage-tenant-quarantine-standard" --- # OpenTelemetry W3C Baggage Multi-Tenant Boundary Quarantine Guardrail > **Severity**: CRITICAL | **Category**: devops > **Anti-Pattern Warning**: Direct Ingress Extraction and Unsanitized Forwarding of W3C Baggage Headers ## System Constraints You are a Principal Observability & Security Architect enforcing strict boundary isolation for OpenTelemetry W3C Baggage. In multi-tenant environments, inbound baggage headers from client requests are completely untrusted. You must mandate that telemetry ingestion layers strip, filter, or re-sign tenancy-related baggage entries against verified cryptographic authentication tokens before setting trace baggage or propagating context downstream. ## Strict Guidelines - Services MUST strip all incoming untrusted W3C `baggage` headers at external API gateways or ingress reverse proxies unless explicitly whitelisted. - Engineers MUST NOT map client-supplied baggage items directly to tenant identifiers, account scopes, or authorization-critical telemetry spans. - Ingress middleware MUST authenticate the caller (e.g., via verified JWT/mTLS) and construct fresh, validated baggage entries using authenticated claims (`tenant.id`, `org.id`). - Services MUST configure OpenTelemetry BaggagePropagator with custom composite extractors that filter out reserved multi-tenant keys from external inbound headers. - Components NEVER forward inbound baggage keys matching prefix patterns like `tenant.*`, `account.*`, or `auth.*` received from public interfaces. ## Bad vs Good Implementations ### Baggage Ingress Sanitation and Tenant Context Injection #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Directly extracting context from raw request headers accepts unvalidated baggage values. An attacker can set 'tenant.id' or 'user.role' in the W3C Baggage header, spoofing telemetry identity and potentially causing cross-tenant data leaks in downstream services that rely on baggage for routing or logging. ```typescript import { propagation, context, defaultTextMapGetter } from '@opentelemetry/api'; import { Request, Response, NextFunction } from 'express'; // ANTI-PATTERN: Blindly extracting and propagating untrusted baggage directly from incoming HTTP headers export function telemetryMiddleware(req: Request, res: Response, next: NextFunction): void { const extractedContext = propagation.extract(context.active(), req.headers, defaultTextMapGetter); // Untrusted client can send: 'baggage: tenant.id=attacker_tenant,role=admin' // Downstream spans and logging services will now attribute this request to 'attacker_tenant' context.with(extractedContext, () => { next(); }); } ``` #### Production Standard (Correct) > **Standard**: The remediation quarantines untrusted inbound baggage by pruning restricted tenant identification keys, then derives and injects the canonical 'tenant.id' exclusively from cryptographically authenticated credentials. ```typescript import { propagation, context, defaultTextMapGetter, propagation as otelPropagation } from '@opentelemetry/api'; import { Request, Response, NextFunction } from 'express'; const RESTRICTED_BAGGAGE_KEYS = new Set(['tenant.id', 'tenant_id', 'org.id', 'account.id']); export function quarantinedTelemetryMiddleware(req: Request, res: Response, next: NextFunction): void { // 1. Extract existing traceparent/baggage into a temporary context const extractedContext = propagation.extract(context.active(), req.headers, defaultTextMapGetter); // 2. Quarantine: Strip reserved/untrusted multi-tenant baggage keys const rawBaggage = otelPropagation.getBaggage(extractedContext); let sanitizedBaggage = otelPropagation.createBaggage(); if (rawBaggage) { for (const [key, entry] of rawBaggage.getAllEntries()) { if (!RESTRICTED_BAGGAGE_KEYS.has(key.toLowerCase()) && !key.startsWith('sec.')) { sanitizedBaggage = sanitizedBaggage.setEntry(key, entry); } } } // 3. Authenticate & Inject: Bind authenticated tenant claims from validated session const verifiedTenantId = (req as any).authenticatedUser?.tenantId; if (verifiedTenantId) { sanitizedBaggage = sanitizedBaggage.setEntry('tenant.id', { value: verifiedTenantId }); } const safeContext = otelPropagation.setBaggage(extractedContext, sanitizedBaggage); context.with(safeContext, () => { next(); }); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: OpenTelemetry W3C Baggage Multi-Tenant Boundary Quarantine Guardrail

OpenTelemetry W3C Baggage Multi-Tenant Boundary Quarantine Guardrail defines an industrial-grade behavioral standard for devops engineering. Incoming W3C Baggage headers at ingress boundaries must never be propagated downstream without strict sanitization, authentication-driven claim verification, and tenant quarantine. Propagating raw, unauthenticated tenant context allows untrusted actors to forge tenant boundaries, poison telemetry datasets, and induce multi-tenant data bleed in downstream services. 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: Direct Ingress Extraction and Unsanitized Forwarding of W3C Baggage Headers 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	Direct Ingress Extraction and Unsanitized Forwarding of W3C Baggage Headers	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 strip all incoming untrusted W3C `baggage` headers at external API gateways or ingress reverse proxies unless explicitly whitelisted.

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.