OpenTelemetry Cryptographic Baggage Provenance and Redaction Guardrail

--- description: OpenTelemetry Cryptographic Baggage Provenance and Redaction Guardrail - Enforces strict cryptographic verification and allowlist redaction on incoming W3C Baggage headers at microservice network perimeters. Prevents trace context spoofing, tenant boundary violations, and accidental leakage of sensitive tokens across distributed boundaries by requiring signed contextual metadata and scrubbing unapproved attributes. globs: src/telemetry/**/*.ts, src/tracing/**/*.ts, src/middleware/**/*.ts, src/interceptors/**/*.ts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/otel-cryptographic-baggage-provenance-guardrail" --- # OpenTelemetry Cryptographic Baggage Provenance and Redaction Guardrail > **Severity**: CRITICAL | **Category**: devops > **Anti-Pattern Warning**: Blind Ingestion and Unrestricted Propagation of Unsigned W3C Baggage Across Trust Boundaries ## System Constraints You are a Principal Security & Observability Architect enforcing OpenTelemetry Cryptographic Baggage Provenance and Redaction. Mandate invariants that prevent unsanitized or unsigned distributed tracing baggage from crossing security boundaries. Enforce HMAC-based baggage integrity checks and strict allowlist sanitization before propagation. ## Strict Guidelines - Services MUST NEVER blindly ingest incoming W3C Baggage headers at ingress boundaries without cryptographic provenance validation and allowlist filtering. - Engineers MUST ALWAYS sign critical tenant baggage attributes (e.g., `tenant.id`, `user.roles`) with HMAC-SHA256 at ingress gateways before propagating downstream. - Downstream services MUST verify the baggage signature against a distributed secret or key store before using baggage values in tenant-scoped routing or authorization. - Engineers MUST configure a strict allowlist for baggage keys; any key matching credential patterns (e.g., `auth`, `token`, `secret`, `jwt`, `cookie`) or absent from the allowlist MUST be stripped immediately. - Custom OpenTelemetry Propagators MUST reject or quarantine spans containing malformed, oversized, or unverified baggage rather than silently falling back to insecure defaults. ## Bad vs Good Implementations ### Baggage Ingress Processing: Blind Propagation vs Cryptographic Verification & Allowlist Filtering #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: This implementation extracts W3C Baggage directly from raw HTTP request headers without verification. Attackers can inject forged tenant boundaries, manipulate audit logs, or propagate stolen access tokens downstream through observability pipelines. ```typescript import { Context, defaultTextMapGetter, propagation } from '@opentelemetry/api'; import { Request, Response, NextFunction } from 'express'; // ANTI-PATTERN: Blindly extracting and propagating untrusted client baggage. // Attackers can inject arbitrary tenant IDs, spoof roles, or exfiltrate credentials. export function insecureTelemetryMiddleware(req: Request, res: Response, next: NextFunction): void { const extractedContext: Context = propagation.extract(propagation.getBaggage(req.headers as any) as any, req.headers, defaultTextMapGetter); // Unfiltered baggage is directly accepted into current execution context // No validation of tenant authenticity or credential stripping occurs next(); } ``` #### Production Standard (Correct) > **Standard**: The secure implementation filters all baggage against an explicit allowlist and verifies the HMAC signature of critical context keys (tenant.id) before binding the sanitized baggage to the execution context. ```typescript import { Context, context, defaultTextMapGetter, propagation, baggageEntryMetadataSymbol } from '@opentelemetry/api'; import { createHmac, timingSafeEqual } from 'crypto'; import { Request, Response, NextFunction } from 'express'; const BAGGAGE_ALLOWLIST = new Set(['tenant.id', 'deployment.env', 'request.origin']); const BAGGAGE_HMAC_SECRET = process.env.OTEL_BAGGAGE_SIGNING_SECRET || ''; function verifyHmac(payload: string, signature: string): boolean { if (!BAGGAGE_HMAC_SECRET || !signature) return false; const expected = createHmac('sha256', BAGGAGE_HMAC_SECRET).update(payload).digest('hex'); return expected.length === signature.length && timingSafeEqual(Buffer.from(expected), Buffer.from(signature)); } export function secureTelemetryMiddleware(req: Request, res: Response, next: NextFunction): void { const extractedContext: Context = propagation.extract(context.active(), req.headers, defaultTextMapGetter); const incomingBaggage = propagation.getBaggage(extractedContext); let sanitizedBaggage = propagation.createBaggage(); if (incomingBaggage) { const tenantId = incomingBaggage.getEntry('tenant.id')?.value; const signature = incomingBaggage.getEntry('provenance.sig')?.value; const isAuthentic = tenantId && signature ? verifyHmac(tenantId, signature) : false; for (const [key, entry] of incomingBaggage.getAllEntries()) { // Strictly enforce allowlist and ensure cryptographic integrity for tenant scoping if (!BAGGAGE_ALLOWLIST.has(key)) continue; if (key === 'tenant.id' && !isAuthentic) continue; sanitizedBaggage = sanitizedBaggage.setEntry(key, entry); } } const secureContext = propagation.setBaggage(extractedContext, sanitizedBaggage); context.with(secureContext, () => next()); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: OpenTelemetry Cryptographic Baggage Provenance and Redaction Guardrail

OpenTelemetry Cryptographic Baggage Provenance and Redaction Guardrail defines an industrial-grade behavioral standard for devops engineering. Enforces strict cryptographic verification and allowlist redaction on incoming W3C Baggage headers at microservice network perimeters. Prevents trace context spoofing, tenant boundary violations, and accidental leakage of sensitive tokens across distributed boundaries by requiring signed contextual metadata and scrubbing unapproved attributes. 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: Blind Ingestion and Unrestricted Propagation of Unsigned W3C Baggage Across 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	Blind Ingestion and Unrestricted Propagation of Unsigned W3C Baggage Across 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:

Services MUST NEVER blindly ingest incoming W3C Baggage headers at ingress boundaries without cryptographic provenance validation and allowlist filtering.

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.