OpenTelemetry 1.28 Baggage Tamper-Proof & Telemetry Boundary Enforcement

--- description: OpenTelemetry 1.28 Baggage Tamper-Proof & Telemetry Boundary Enforcement - Enforces strict cryptographic integrity, schema validation, and trust-boundary sanitization on W3C Baggage propagation conforming to OpenTelemetry Semantic Conventions 1.28. Precludes telemetry spoofing, routing injection, and cross-service privilege escalation by ensuring distributed context cannot be mutated or consumed across untrusted network edges without HMAC-SHA256 verification. 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-1-28-baggage-tamper-proof-guardrail" --- # OpenTelemetry 1.28 Baggage Tamper-Proof & Telemetry Boundary Enforcement > **Severity**: CRITICAL | **Category**: devops > **Anti-Pattern Warning**: Unvalidated Ingestion and Downstream Propagation of Raw W3C Baggage Headers across Security Boundaries ## System Constraints You are a Principal Security and Distributed Telemetry Architect enforcing OpenTelemetry Semantic Conventions 1.28 Baggage Tamper-Proof Guardrails. Mandate that incoming W3C Baggage headers from untrusted network edges are never blindly injected into active trace contexts or downstream requests without cryptographic validation. Reject any authorization or identity decision derived from unverified baggage entries. ## Strict Guidelines - Services MUST sanitize or strip unauthenticated incoming W3C Baggage (`baggage` header) at perimeter API gateways and zero-trust perimeter boundaries. - Engineers MUST NEVER use W3C Baggage entries for authentication, authorization checks, multitenancy access control, or routing decisions without an accompanying verified cryptographic signature (e.g., HMAC-SHA256 signature entry). - Telemetry interceptors MUST validate all baggage keys and values against OpenTelemetry Semantic Conventions 1.28 naming constraints and enforce strict schema allowlists before propagating downstream context. - Downstream HTTP/gRPC extractors MUST reject baggage items exceeding 8192 bytes or containing non-US-ASCII control characters to preclude HTTP request smuggling and trace context pollution. - Edge-facing proxies MUST sign outbound baggage payloads using an ephemeral or rotatable internal signing key and populate an immutable `.sig` companion attribute in compliance with W3C propagation rules. ## Bad vs Good Implementations ### Blind Ingestion vs. Cryptographically Verified Baggage Propagation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Directly extracting unverified baggage from incoming HTTP request headers enables telemetry spoofing and arbitrary tenant impersonation if downstream logic reads identity claims from context baggage. ```typescript import { propagation, context } from '@opentelemetry/api'; import { Request, Response, NextFunction } from 'express'; export function telemetryMiddleware(req: Request, res: Response, next: NextFunction): void { // Anti-pattern: Blindly extracting and propagating untrusted baggage header // Allows an attacker to spoof 'tenant.id', 'user.role', or span telemetry metadata const extractedContext = propagation.extract(context.active(), req.headers); context.with(extractedContext, () => { // Attacker-controlled baggage can lead to telemetry poisoning or broken access control const baggage = propagation.getBaggage(context.active()); const tenantId = baggage?.getEntry('tenant.id')?.value; (req as any).tenantId = tenantId; next(); }); } ``` #### Production Standard (Correct) > **Standard**: Enforces an allowlist of permitted Semantic Convention attributes, strictly verifies a cryptographic HMAC signature against canonicalized baggage pairs, and strips tainted baggage before binding to the active trace context. ```typescript import { propagation, context, Baggage, BaggageEntry } from '@opentelemetry/api'; import { Request, Response, NextFunction } from 'express'; import { createHmac, timingSafeEqual } from 'crypto'; const BAGGAGE_SIGNING_SECRET = process.env.BAGGAGE_HMAC_SECRET!; const ALLOWED_BAGGAGE_KEYS = new Set(['tenant.id', 'client.env', 'session.id']); function verifyAndFilterBaggage(rawBaggage: Baggage | undefined): Baggage | undefined { if (!rawBaggage) return undefined; const signatureEntry = rawBaggage.getEntry('sec.sig')?.value; if (!signatureEntry) return undefined; const entriesToSign: string[] = []; const validEntries: [string, BaggageEntry][] = []; for (const [key, entry] of rawBaggage.getAllEntries()) { if (key === 'sec.sig') continue; if (!ALLOWED_BAGGAGE_KEYS.has(key)) continue; entriesToSign.push(`${key}=${entry.value}`); validEntries.push([key, entry]); } entriesToSign.sort(); const expectedSig = createHmac('sha256', BAGGAGE_SIGNING_SECRET) .update(entriesToSign.join(';')) .digest('hex'); const isValid = signatureEntry.length === expectedSig.length && timingSafeEqual(Buffer.from(signatureEntry), Buffer.from(expectedSig)); if (!isValid) return undefined; return propagation.createBaggage(Object.fromEntries(validEntries)); } export function secureTelemetryMiddleware(req: Request, res: Response, next: NextFunction): void { const extractedContext = propagation.extract(context.active(), req.headers); const unverifiedBaggage = propagation.getBaggage(extractedContext); const sanitizedBaggage = verifyAndFilterBaggage(unverifiedBaggage); // Replace unverified baggage with cryptographically verified context or empty baggage const safeContext = sanitizedBaggage ? propagation.setBaggage(extractedContext, sanitizedBaggage) : propagation.deleteBaggage(extractedContext); context.with(safeContext, () => next()); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: OpenTelemetry 1.28 Baggage Tamper-Proof & Telemetry Boundary Enforcement

OpenTelemetry 1.28 Baggage Tamper-Proof & Telemetry Boundary Enforcement defines an industrial-grade behavioral standard for devops engineering. Enforces strict cryptographic integrity, schema validation, and trust-boundary sanitization on W3C Baggage propagation conforming to OpenTelemetry Semantic Conventions 1.28. Precludes telemetry spoofing, routing injection, and cross-service privilege escalation by ensuring distributed context cannot be mutated or consumed across untrusted network edges without HMAC-SHA256 verification. 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 Ingestion and Downstream Propagation of Raw W3C Baggage Headers across Security Boundaries 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 Ingestion and Downstream Propagation of Raw W3C Baggage Headers across Security Boundaries	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 sanitize or strip unauthenticated incoming W3C Baggage (`baggage` header) at perimeter API gateways and zero-trust perimeter boundaries.

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.