OpenTelemetry Baggage Cryptographic Integrity and Secret Redaction Standard

--- description: OpenTelemetry Baggage Cryptographic Integrity and Secret Redaction Standard - Enforces boundary-level cryptographic HMAC verification and strict PII/secret scrubbing on W3C Baggage context before inbound extraction and outbound cross-service propagation. Prevents telemetry injection attacks, downstream trace poisoning, and accidental exfiltration of confidential credentials across distributed service boundaries. globs: src/telemetry/**/*.ts, src/instrumentation/**/*.ts, src/middleware/**/*.ts, src/common/tracing/**/*.ts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/opentelemetry-baggage-integrity-secret-redaction" --- # OpenTelemetry Baggage Cryptographic Integrity and Secret Redaction Standard > **Severity**: CRITICAL | **Category**: devops > **Anti-Pattern Warning**: Unvalidated and Unredacted W3C Baggage Forwarding Across Distributed Trust Boundaries ## System Constraints You are a Principal Software Architect and Systems Security Specialist enforcing OpenTelemetry semantic baggage integrity and distributed context propagation invariants. You must reject any code that directly injects or blindly forwards unvalidated W3C Baggage headers. Mandate strict schema-based allowlists, high-entropy secret detection, and cryptographic HMAC-SHA256 validation for cross-boundary contextual baggage attributes. ## Strict Guidelines - Engineers MUST ALWAYS enforce a strict allowlist of permitted OpenTelemetry Baggage keys based on standard semantic conventions before propagating context downstream. - Engineers MUST NOT blindly forward raw inbound W3C `baggage` headers across network boundaries without boundary-level sanitization and cryptographic verification. - Services MUST cryptographically sign trusted operational baggage items using HMAC-SHA256 and reject untrusted or mismatched signatures at ingress ingress boundaries. - Components NEVER store sensitive credentials (e.g., Bearer tokens, API keys, passwords) or unhashed PII (e.g., email, SSN) within the distributed Baggage context. - Code SHOULD sanitize string values using automated regex patterns for common secret formats (e.g., JWT, AWS keys, UUIDs mapped to sensitive entities) and truncate values exceeding maximum RFC 7230 limits. ## Bad vs Good Implementations ### Inbound Baggage Sanitization and HMAC Verification Propagator #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Accepts untrusted baggage headers directly from incoming requests without validating allowed keys, checking cryptographic signatures, or redacting secrets. An attacker can inject arbitrary span tags or exfiltrate session tokens downstream. ```typescript import { Context, TextMapGetter, TextMapPropagator, defaultTextMapGetter, propagation } from '@opentelemetry/api'; // ANTI-PATTERN: Blindly extracting and forwarding inbound baggage without verification export class PassThroughBaggagePropagator implements TextMapPropagator { inject(context: Context, carrier: unknown): void { // Re-injects all ambient baggage including potential malicious injections or leaked secrets propagation.getBaggage(context); } extract(context: Context, carrier: unknown, getter: TextMapGetter = defaultTextMapGetter): Context { const rawBaggage = getter.get(carrier, 'baggage'); if (typeof rawBaggage === 'string') { // Blindly parses and accepts all client-supplied baggage items into context const baggage = propagation.createBaggage(); rawBaggage.split(',').forEach(entry => { const [key, value] = entry.trim().split('='); if (key && value) baggage.setEntry(key, { value }); }); return propagation.setBaggage(context, baggage); } return context; } fields(): string[] { return ['baggage']; } } ``` #### Production Standard (Correct) > **Standard**: Implements an allowlist-enforcing propagator that verifies HMAC-SHA256 signatures for every baggage entry and drops sensitive patterns (e.g. JWTs, tokens). Prevents context tampering and trace parameter pollution. ```typescript import { Context, TextMapGetter, TextMapPropagator, defaultTextMapGetter, propagation, BaggageEntry } from '@opentelemetry/api'; import { createHmac, timingSafeEqual } from 'crypto'; const ALLOWED_BAGGAGE_KEYS = new Set(['tenant.id', 'routing.region', 'client.version']); const SECRET_REGEX = /^(bearer\s+[a-zA-Z0-9._-]+|ey[a-zA-Z0-9._-]+|[A-Za-z0-9+/]{40,}={0,2})$/i; const HMAC_SECRET = process.env.BAGGAGE_SIGNING_SECRET || 'ephemeral-cluster-secret'; export class SecureBoundaryBaggagePropagator implements TextMapPropagator { private sign(value: string): string { return createHmac('sha256', HMAC_SECRET).update(value).digest('base64url'); } private verify(value: string, signature: string): boolean { const expected = this.sign(value); return expected.length === signature.length && timingSafeEqual(Buffer.from(expected), Buffer.from(signature)); } inject(context: Context, carrier: Record<string, string>): void { const baggage = propagation.getBaggage(context); if (!baggage) return; const serializedEntries: string[] = []; for (const [key, entry] of baggage.getAllEntries()) { if (!ALLOWED_BAGGAGE_KEYS.has(key) || SECRET_REGEX.test(entry.value)) { continue; } const signature = this.sign(`${key}:${entry.value}`); serializedEntries.push(`${encodeURIComponent(key)}=${encodeURIComponent(entry.value)};sig=${signature}`); } if (serializedEntries.length > 0) { carrier['baggage'] = serializedEntries.join(', '); } } extract(context: Context, carrier: unknown, getter: TextMapGetter = defaultTextMapGetter): Context { const rawHeader = getter.get(carrier, 'baggage'); const headerVal = Array.isArray(rawHeader) ? rawHeader[0] : rawHeader; if (typeof headerVal !== 'string') return context; let sanitizedBaggage = propagation.getBaggage(context) || propagation.createBaggage(); for (const item of headerVal.split(',')) { const [pair, ...metadata] = item.trim().split(';'); const [rawKey, rawValue] = pair.split('='); if (!rawKey || !rawValue) continue; const key = decodeURIComponent(rawKey.trim()); const value = decodeURIComponent(rawValue.trim()); const sigMeta = metadata.find(m => m.trim().startsWith('sig=')); const signature = sigMeta ? sigMeta.trim().replace(/^sig=/, '') : ''; if (!ALLOWED_BAGGAGE_KEYS.has(key) || SECRET_REGEX.test(value)) continue; if (!signature || !this.verify(`${key}:${value}`, signature)) continue; sanitizedBaggage = sanitizedBaggage.setEntry(key, { value }); } return propagation.setBaggage(context, sanitizedBaggage); } fields(): string[] { return ['baggage']; } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: OpenTelemetry Baggage Cryptographic Integrity and Secret Redaction Standard

OpenTelemetry Baggage Cryptographic Integrity and Secret Redaction Standard defines an industrial-grade behavioral standard for devops engineering. Enforces boundary-level cryptographic HMAC verification and strict PII/secret scrubbing on W3C Baggage context before inbound extraction and outbound cross-service propagation. Prevents telemetry injection attacks, downstream trace poisoning, and accidental exfiltration of confidential credentials across distributed service boundaries. 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 and Unredacted W3C Baggage Forwarding Across Distributed Trust 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 and Unredacted W3C Baggage Forwarding Across Distributed Trust 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:

Engineers MUST ALWAYS enforce a strict allowlist of permitted OpenTelemetry Baggage keys based on standard semantic conventions before propagating context downstream.

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.