e11y 0.2.0 → 1.1.0

data/lib/e11y/logger/bridge.rb

@@ -8,7 +8,7 @@ module E11y
     #
     # Transparent wrapper around Rails.logger that:
     # 1. Delegates all calls to the original logger (preserves Rails behavior)
-    # 2. Tracks log calls as E11y events (when logger_bridge.enabled = true)
+    # 2. Tracks log calls as E11y events (when logger_bridge_enabled = true)
     #
     # **Why SimpleDelegator instead of full replacement:**
     # - ✅ Simpler: No need to reimplement entire Logger API
@@ -17,12 +17,12 @@ module E11y
     # - ✅ Rails Way: Extends functionality without replacing core components
     #
     # @example Basic usage
-    #   # Automatically enabled by E11y::Railtie if config.logger_bridge.enabled = true
+    #   # Automatically enabled by E11y::Railtie if config.logger_bridge_enabled = true
     #   Rails.logger = E11y::Logger::Bridge.new(Rails.logger)
     #
     # @example Manual setup
     #   E11y.configure do |config|
-    #     config.logger_bridge.enabled = true  # Wrap Rails.logger and send logs to E11y
+    #     config.logger_bridge_enabled = true  # Wrap Rails.logger and send logs to E11y
     #   end
     #
     # @see ADR-008 §7 (Rails.logger Migration)
@@ -34,7 +34,7 @@ module E11y
       #
       # @return [void]
       def self.setup!
-        return unless E11y.config.logger_bridge&.enabled
+        return unless E11y.config.logger_bridge_enabled
         return unless defined?(::Rails)
 
         # Wrap Rails.logger (preserves original behavior)
@@ -53,6 +53,8 @@ module E11y
           ::Logger::FATAL => :fatal,
           ::Logger::UNKNOWN => :warn
         }
+        @track_severities_set = build_track_severities_set(E11y.config.logger_bridge_track_severities)
+        @ignore_patterns = build_compiled_patterns(E11y.config.logger_bridge_ignore_patterns)
       end
 
       # Intercept logger methods to track to E11y
@@ -124,18 +126,22 @@ module E11y
       # @param message [String, nil] Log message
       # @yield Block that returns log message
       # @return [void]
-      # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
       # Logger tracking requires message extraction, validation, event class lookup, and error handling
       def track_to_e11y(severity, message = nil)
         # Extract message
         msg = message || (block_given? ? yield : nil)
         return if msg.nil? || (msg.respond_to?(:empty?) && msg.empty?)
 
+        msg_str = msg.to_s
+
+        return if @track_severities_set && !@track_severities_set.include?(severity)
+        return if @ignore_patterns.any? { |re| re.match?(msg_str) }
+
         # Track to E11y using severity-specific class
         require "e11y/events/rails/log"
         event_class = event_class_for_severity(severity)
         event_class.track(
-          message: msg.to_s,
+          message: msg_str,
           caller_location: extract_caller_location
         )
       rescue StandardError => e
@@ -143,7 +149,6 @@ module E11y
         # In development/test, you might want to log this
         warn "E11y logger tracking failed: #{e.message}" if defined?(::Rails) && ::Rails.env.development?
       end
-      # rubocop:enable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
 
       # Get event class for severity
       # @param severity [Symbol] E11y severity
@@ -162,6 +167,20 @@ module E11y
       end
       # rubocop:enable Lint/DuplicateBranch
 
+      def build_track_severities_set(severities)
+        return nil if severities.nil? || (severities.respond_to?(:empty?) && severities.empty?)
+
+        Set.new(Array(severities).map(&:to_sym))
+      end
+
+      def build_compiled_patterns(patterns)
+        return [] if patterns.nil? || !patterns.respond_to?(:any?) || patterns.none?
+
+        Array(patterns).map do |p|
+          p.is_a?(Regexp) ? p : Regexp.new(Regexp.escape(p.to_s))
+        end.freeze
+      end
+
       # Extract caller location (first caller outside E11y)
       # @return [String, nil] Caller location string
       def extract_caller_location

data/lib/e11y/metrics/cardinality_protection.rb

@@ -7,11 +7,10 @@ module E11y
   module Metrics
     # Cardinality protection for metrics labels.
     #
-    # Implements 4-layer defense system to prevent cardinality explosions:
+    # Implements 3-layer defense system to prevent cardinality explosions:
     # 1. Universal Denylist - Block high-cardinality fields (user_id, order_id, etc.)
     # 2. Per-Metric Limits - Track unique values per metric, drop if exceeded
-    # 3. Dynamic Monitoring - Alert when approaching limits
-    # 4. Dynamic Actions - Auto-relabeling, alerting, or dropping on overflow
+    # 3. Dynamic Actions - Drop, alert, or relabel on overflow
     #
     # Now supports optional relabeling to reduce cardinality while preserving signal.
     #
@@ -37,7 +36,7 @@ module E11y
     # @see ADR-002 §4 (Cardinality Protection)
     # @see UC-013 (High Cardinality Protection)
     # rubocop:disable Metrics/ClassLength
-    # Cardinality protection is a cohesive 4-layer defense system against metric explosions
+    # Cardinality protection is a cohesive 3-layer defense system against metric explosions
     class CardinalityProtection
       # Universal denylist - high-cardinality fields that should NEVER be labels
       UNIVERSAL_DENYLIST = %i[
@@ -64,7 +63,7 @@ module E11y
       # Default per-metric cardinality limit
       DEFAULT_CARDINALITY_LIMIT = 1000
 
-      # Overflow strategies (Layer 4: Dynamic Actions)
+      # Overflow strategies (Layer 3: Dynamic Actions)
       OVERFLOW_STRATEGIES = %i[drop alert relabel].freeze
 
       # Default overflow strategy
@@ -85,7 +84,6 @@ module E11y
       # @option config [Float] :alert_threshold (0.8) Alert when cardinality reaches this ratio
       # @option config [Proc] :alert_callback Optional callback when alert triggered
       # @option config [Boolean] :auto_relabel (false) Auto-relabel to [OTHER] on overflow
-      # rubocop:disable Metrics/AbcSize
       # Cardinality protection initialization requires extracting multiple config options and setting up components
       def initialize(config = {})
         @cardinality_limit = config.fetch(:cardinality_limit, DEFAULT_CARDINALITY_LIMIT)
@@ -109,7 +107,6 @@ module E11y
         @overflow_counts = Hash.new(0)
         @overflow_mutex = Mutex.new
       end
-      # rubocop:enable Metrics/AbcSize
 
       # Define relabeling rule for a label
       #
@@ -222,7 +219,6 @@ module E11y
 
       # Check if approaching alert threshold (Layer 3: Monitoring)
       # @param metric_name [String] Metric name
-      # rubocop:disable Metrics/MethodLength
       # Alert threshold checking requires calculating ratio, checking conditions, and sending detailed alerts
       def check_alert_threshold(metric_name)
         return unless @alert_threshold
@@ -252,7 +248,6 @@ module E11y
         # Track metric
         track_cardinality_metric(metric_name, :threshold_exceeded, current_cardinality)
       end
-      # rubocop:enable Metrics/MethodLength
 
       # Handle overflow when cardinality limit exceeded (Layer 4: Dynamic Actions)
       # @param metric_name [String] Metric name
@@ -311,9 +306,11 @@ module E11y
           severity: :error
         )
 
-        # Also log warning
-        warn "E11y Metrics: Cardinality limit exceeded for #{metric_name}:#{key} " \
-             "(limit: #{@cardinality_limit}, current: #{current_cardinality})"
+        # Also log warning (via E11y.logger so it respects Rails.logger in test env)
+        E11y.logger&.warn(
+          "E11y Metrics: Cardinality limit exceeded for #{metric_name}:#{key} " \
+          "(limit: #{@cardinality_limit}, current: #{current_cardinality})"
+        )
       end
 
       # Handle relabel strategy - relabel to [OTHER]
@@ -385,7 +382,6 @@ module E11y
       # @param metric_name [String] Metric name
       # @param action [Symbol] Action type (:threshold_exceeded, :drop, :alert, :relabel)
       # @param value [Integer] Metric value
-      # rubocop:disable Metrics/MethodLength
       # Cardinality tracking requires incrementing overflow counters and updating gauge metrics
       def track_cardinality_metric(metric_name, action, value)
         return unless defined?(E11y::Metrics)
@@ -408,9 +404,8 @@ module E11y
         )
       rescue StandardError => e
         # Don't fail on metrics tracking errors
-        warn "E11y: Failed to track cardinality metric: #{e.message}"
+        E11y.logger&.warn("E11y: Failed to track cardinality metric: #{e.message}")
       end
-      # rubocop:enable Metrics/MethodLength
     end
     # rubocop:enable Metrics/ClassLength
   end

data/lib/e11y/metrics/cardinality_tracker.rb

@@ -33,13 +33,15 @@ module E11y
       # Records unique label values per metric+label combination.
       # Thread-safe operation.
       #
-      # @param metric_name [String] Metric name
+      # @param metric_name [String, Symbol] Metric name
       # @param label_key [Symbol, String] Label key
       # @param label_value [Object] Label value to track
       # @return [Boolean] true if within limit, false if limit exceeded
       def track(metric_name, label_key, label_value)
         @mutex.synchronize do
-          value_set = @tracker[metric_name][label_key]
+          # Normalize metric_name to string for consistent key access
+          metric_key = metric_name.to_s
+          value_set = @tracker[metric_key][label_key]
 
           # Allow if already tracked (existing value)
           return true if value_set.include?(label_value)
@@ -66,7 +68,9 @@ module E11y
       # @return [void]
       def force_track(metric_name, label_key, label_value)
         @mutex.synchronize do
-          value_set = @tracker[metric_name][label_key]
+          # Normalize metric_name to string for consistent key access
+          metric_key = metric_name.to_s
+          value_set = @tracker[metric_key][label_key]
           value_set.add(label_value) unless value_set.include?(label_value)
         end
       end
@@ -78,7 +82,9 @@ module E11y
       # @return [Boolean] true if at or above limit
       def exceeded?(metric_name, label_key)
         @mutex.synchronize do
-          @tracker.dig(metric_name, label_key)&.size.to_i >= @limit
+          # Normalize metric_name to string for consistent key access
+          metric_key = metric_name.to_s
+          @tracker.dig(metric_key, label_key)&.size.to_i >= @limit
         end
       end
 
@@ -89,7 +95,9 @@ module E11y
       # @return [Integer] Number of unique values tracked
       def cardinality(metric_name, label_key)
         @mutex.synchronize do
-          @tracker.dig(metric_name, label_key)&.size || 0
+          # Normalize metric_name to string for consistent key access
+          metric_key = metric_name.to_s
+          @tracker.dig(metric_key, label_key)&.size || 0
         end
       end
 
@@ -99,7 +107,9 @@ module E11y
       # @return [Hash{Symbol => Integer}] Label key => cardinality
       def cardinalities(metric_name)
         @mutex.synchronize do
-          metric_data = @tracker[metric_name]
+          # Normalize metric_name to string for consistent key access
+          metric_key = metric_name.to_s
+          metric_data = @tracker[metric_key]
           metric_data.transform_values(&:size)
         end
       end

data/lib/e11y/metrics/registry.rb

@@ -6,7 +6,7 @@ module E11y
   module Metrics
     # Registry for metric configurations.
     #
-    # Stores metric definitions and provides pattern-based matching.
+    # Stores metric definitions and provides event-name matching.
     # This is a singleton class - use Registry.instance to access it.
     # All metrics (global, event-level, preset) are registered here for validation.
     #
@@ -144,7 +144,6 @@ module E11y
       # Validate metric configuration
       # @param config [Hash] Metric configuration
       # @raise [ArgumentError] if configuration is invalid
-      # rubocop:disable Metrics/AbcSize
       def validate_config!(config)
         raise ArgumentError, "Metric type is required" unless config[:type]
         raise ArgumentError, "Invalid metric type: #{config[:type]}" unless %i[counter histogram
@@ -156,14 +155,13 @@ module E11y
 
         raise ArgumentError, "Value extractor is required for #{config[:type]} metrics"
       end
-      # rubocop:enable Metrics/AbcSize
 
       # Validate that new metric doesn't conflict with existing one
       # @param existing [Hash] Existing metric configuration
       # @param new_config [Hash] New metric configuration
       # @raise [TypeConflictError] if types don't match
       # @raise [LabelConflictError] if labels don't match
-      # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+      # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
       # Conflict validation requires checking type and labels with detailed error messages
       def validate_no_conflicts!(existing, new_config)
         # Check 1: Type must match
@@ -215,7 +213,7 @@ module E11y
           Using existing buckets.
         WARNING
       end
-      # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+      # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
 
       # Compile glob pattern to regex
       # @param pattern [String] Glob pattern (e.g., "order.*", "user.*.created")

data/lib/e11y/metrics/test_backend.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module E11y
+  module Metrics
+    # In-memory metrics backend for tests.
+    #
+    # Records all metric calls so test assertions can verify what was tracked
+    # without using mocks on E11y::Metrics directly.
+    #
+    # @example
+    #   backend = E11y::Metrics::TestBackend.new
+    #   E11y::Metrics.instance_variable_set(:@backend, backend)
+    #
+    #   MyService.call
+    #
+    #   expect(backend.increment_count(:orders_total)).to eq(1)
+    #   expect(backend.increments).to include(hash_including(name: :orders_total))
+    class TestBackend
+      attr_reader :increments, :histograms, :gauges
+
+      def initialize
+        reset!
+      end
+
+      # @param name [Symbol] Metric name
+      # @param labels [Hash] Metric labels
+      # @param value [Integer] Increment amount
+      def increment(name, labels = {}, value: 1)
+        @increments << { name: name, labels: labels, value: value }
+      end
+
+      # @param name [Symbol] Metric name
+      # @param value [Numeric] Observed value
+      # @param labels [Hash] Metric labels
+      def histogram(name, value, labels = {}, buckets: nil) # rubocop:todo Lint/UnusedMethodArgument
+        @histograms << { name: name, value: value, labels: labels }
+      end
+
+      # @param name [Symbol] Metric name
+      # @param value [Numeric] Gauge value
+      # @param labels [Hash] Metric labels
+      def gauge(name, value, labels = {})
+        @gauges << { name: name, value: value, labels: labels }
+      end
+
+      # Reset all recorded metrics.
+      def reset!
+        @increments = []
+        @histograms = []
+        @gauges     = []
+      end
+
+      # Count how many times a counter was incremented (any labels).
+      #
+      # @param name [Symbol] Metric name
+      # @return [Integer]
+      def increment_count(name)
+        @increments.count { |r| r[:name] == name }
+      end
+    end
+  end
+end

data/lib/e11y/metrics.rb

@@ -21,18 +21,41 @@ module E11y
   # @see ADR-002 §3 (Metrics Integration)
   # @see ADR-016 §3 (Self-Monitoring Metrics)
   module Metrics
+    # No-op metrics backend used when no real backend (e.g. Yabeda) is configured.
+    # Accepts all metric calls and silently discards them so callers never
+    # need to guard against a nil backend.
+    class NullBackend
+      def increment(_name, _labels = {}, value: 1); end
+      def histogram(_name, _value, _labels = {}, buckets: nil); end
+      def gauge(_name, _value, _labels = {}); end
+    end
+
     class << self
       # Track a counter metric (monotonically increasing value).
       #
-      # @param name [Symbol] Metric name (e.g., :http_requests_total)
+      # Accepts dotted names (e.g., "e11y.ephemeral_buffer.flushed") and normalizes to
+      # underscores. DLQ metrics get _total suffix. Labels[:events] is used as value if present.
+      # Safe: no-op when backend unavailable, rescues errors.
+      #
+      # @param name [Symbol, String] Metric name (e.g., :http_requests_total or "e11y.ephemeral_buffer.flushed")
       # @param labels [Hash] Metric labels (e.g., { method: 'GET', status: 200 })
-      # @param value [Integer] Increment value (default: 1)
+      # @param value [Integer] Increment value (default: 1, overridden by labels[:events] if present)
       # @return [void]
       #
       # @example
-      #   E11y::Metrics.increment(:e11y_events_tracked, { event_type: 'order.created' })
-      def increment(name, labels = {}, value: 1)
-        backend&.increment(name, labels, value: value)
+      #   E11y::Metrics.increment(:e11y_events_tracked, event_type: 'order.created')
+      #   E11y::Metrics.increment("e11y.ephemeral_buffer.flushed_on_error", value: 5)
+      def increment(name, labels = {}, value: 1, **labels_kw)
+        return unless backend
+
+        labels = labels.merge(labels_kw) unless labels_kw.empty?
+        value = labels.delete(:events) if labels.key?(:events)
+        value ||= 1
+
+        normalized = normalized_metric_name(name)
+        backend.increment(normalized, labels, value: value)
+      rescue StandardError => e
+        E11y.logger&.debug("E11y metrics: #{e.message}")
       end
 
       # Track a histogram metric (distribution of values).
@@ -44,9 +67,15 @@ module E11y
       # @return [void]
       #
       # @example
-      #   E11y::Metrics.histogram(:e11y_track_duration_seconds, 0.0005, { event_type: 'order.created' })
-      def histogram(name, value, labels = {}, buckets: nil)
-        backend&.histogram(name, value, labels, buckets: buckets)
+      #   E11y::Metrics.histogram(:e11y_track_duration_seconds, 0.0005, event_type: 'order.created')
+      def histogram(name, value, labels = {}, buckets: nil, **labels_kw)
+        return unless backend
+
+        labels = labels.merge(labels_kw) unless labels_kw.empty?
+        normalized = normalized_metric_name(name)
+        backend.histogram(normalized, value, labels, buckets: buckets)
+      rescue StandardError => e
+        E11y.logger&.debug("E11y metrics: #{e.message}")
       end
 
       # Track a gauge metric (current value that can go up or down).
@@ -81,10 +110,27 @@ module E11y
       # @api private
       def reset_backend!
         remove_instance_variable(:@backend) if defined?(@backend)
+        @name_cache = nil if defined?(@name_cache)
       end
 
       private
 
+      # Normalize metric name: dots to underscores, DLQ metrics get _total suffix.
+      # Cached to avoid repeated string allocations for hot-path metrics.
+      #
+      # @param name [Symbol, String] Raw metric name
+      # @return [Symbol] Normalized name for Prometheus (e.g., e11y_ephemeral_buffer_flushed_on_error)
+      def normalized_metric_name(name)
+        @name_cache ||= {}
+        @name_cache[name] ||= compute_normalized_name(name)
+      end
+
+      def compute_normalized_name(name)
+        s = name.to_s.tr(".", "_")
+        s = "#{s}_total" if s.include?("e11y_dlq_") && !s.end_with?("_total")
+        s.to_sym
+      end
+
       # Detect the metrics backend from configured adapters.
       #
       # @return [Object, nil] Metrics backend or nil
@@ -99,8 +145,8 @@ module E11y
         # rubocop:enable Style/ClassEqualityComparison
         return yabeda_adapter if yabeda_adapter
 
-        # No backend configured → noop
-        nil
+        # No Yabeda adapter configured — fall back to NullBackend
+        NullBackend.new
       end
     end
   end

data/lib/e11y/middleware/adapter_resolver.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module E11y
+  module Middleware
+    # Resolves target adapter names for an event (shared by PIIFilter and Routing).
+    #
+    # @api private
+    module AdapterResolver
+      # Resolve target adapters for event_data (explicit or routing rules).
+      #
+      # @param event_data [Hash] Event data with :adapters, :audit_event, :retention_until, etc.
+      # @return [Array<Symbol>] Target adapter names
+      def self.resolve(event_data)
+        if event_data[:adapters]&.any?
+          Array(event_data[:adapters]).map(&:to_sym)
+        else
+          apply_routing_rules(event_data)
+        end
+      end
+
+      def self.apply_routing_rules(event_data)
+        matched_adapters = []
+        rules = E11y.configuration.routing_rules || []
+
+        rules.each do |rule|
+          result = rule.call(event_data)
+          matched_adapters.concat(Array(result)) if result
+        rescue StandardError => e
+          warn "[E11y] Routing rule error: #{e.message}"
+        end
+
+        if matched_adapters.any?
+          matched_adapters.uniq
+        else
+          E11y.configuration.fallback_adapters || [:stdout]
+        end
+      end
+    end
+  end
+end

data/lib/e11y/middleware/audit_signing.rb

@@ -44,9 +44,7 @@ module E11y
       def self.signing_key
         @signing_key ||= ENV.fetch("E11Y_AUDIT_SIGNING_KEY") do
           # Development fallback (NOT for production!)
-          if defined?(::Rails) && ::Rails.env.production?
-            raise E11y::Error, "E11Y_AUDIT_SIGNING_KEY must be set in production"
-          end
+          raise E11y::Error, "E11Y_AUDIT_SIGNING_KEY must be set in production" if defined?(::Rails) && ::Rails.env.production?
 
           "development_key_#{SecureRandom.hex(32)}"
         end
@@ -73,20 +71,59 @@ module E11y
 
       # Verify signature (for testing/validation)
       #
+      # Uses the stored audit_canonical to recompute the expected HMAC and compares
+      # against audit_signature. Detects tampering with the canonical representation
+      # (e.g., if someone modifies the stored canonical in the audit log).
+      #
       # @param event_data [Hash] Event data with signature
       # @return [Boolean] true if signature is valid
       # rubocop:disable Naming/PredicateMethod
       def self.verify_signature(event_data)
         expected_signature = event_data[:audit_signature]
-        canonical = event_data[:audit_canonical]
+        return false unless expected_signature
 
-        return false unless expected_signature && canonical
+        # Recompute canonical from CURRENT payload (detects payload tampering)
+        recomputed = canonical_representation(event_data)
+        # Verify stored canonical matches recomputed (detects canonical tampering)
+        return false if event_data[:audit_canonical] && event_data[:audit_canonical] != recomputed
 
-        actual_signature = OpenSSL::HMAC.hexdigest("SHA256", signing_key, canonical)
+        actual_signature = OpenSSL::HMAC.hexdigest("SHA256", signing_key, recomputed)
         actual_signature == expected_signature
       end
       # rubocop:enable Naming/PredicateMethod
 
+      # Create canonical representation for signing (class method for verification)
+      #
+      # @param event_data [Hash] Event data
+      # @return [String] Canonical JSON string
+      def self.canonical_representation(event_data)
+        # Extract fields that should be signed
+        signable_data = {
+          event_name: event_data[:event_name],
+          payload: event_data[:payload],
+          timestamp: event_data[:timestamp],
+          version: event_data[:version]
+        }
+
+        # Convert to sorted JSON (deterministic)
+        JSON.generate(sort_hash(signable_data))
+      end
+
+      # Sort hash recursively for deterministic JSON (class method)
+      #
+      # @param obj [Object] Object to sort
+      # @return [Object] Sorted object
+      def self.sort_hash(obj)
+        case obj
+        when Hash
+          obj.keys.sort.to_h { |k| [k, sort_hash(obj[k])] }
+        when Array
+          obj.map { |v| sort_hash(v) }
+        else
+          obj
+        end
+      end
+
       private
 
       # Check if event is marked as audit event

data/lib/e11y/middleware/baggage_protection.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module E11y
+  module Middleware
+    # BaggageProtection middleware — blocks PII from OpenTelemetry Baggage (ADR-006 §5.5, C08).
+    #
+    # When enabled, prepends an interceptor to OpenTelemetry::Baggage that blocks
+    # set_value calls for keys not in the allowlist. Prevents PII from propagating
+    # via W3C Baggage headers to downstream services.
+    #
+    # @example Configuration
+    #   E11y.configure do |config|
+    #     config.security_baggage_protection_enabled = true
+    #     config.security_baggage_protection_allowed_keys = %w[trace_id span_id request_id]
+    #     config.security_baggage_protection_block_mode = :warn  # :silent, :warn, :raise
+    #   end
+    #
+    # @see ADR-006 §5.5 OpenTelemetry Baggage PII Protection
+    # @see CONFLICT-ANALYSIS.md C08
+    class BaggageProtection < Base
+      middleware_zone :security
+
+      def initialize(app)
+        super
+        @protected = false
+      end
+
+      def call(event_data)
+        protect_baggage! if should_protect?
+        @app.call(event_data)
+      end
+
+      private
+
+      def should_protect?
+        return false unless defined?(OpenTelemetry::Baggage)
+        return false unless E11y.config&.security_baggage_protection_enabled
+
+        true
+      end
+
+      def protect_baggage!
+        return if @protected
+
+        @protected = true
+        cfg = E11y.config
+        allowed_keys = (cfg&.security_baggage_protection_allowed_keys || E11y::BAGGAGE_PROTECTION_DEFAULT_ALLOWED_KEYS).map(&:to_s)
+        block_mode = cfg&.security_baggage_protection_block_mode || :silent
+        logger = E11y.logger
+
+        interceptor = build_interceptor(allowed_keys, block_mode, logger)
+        # Baggage uses extend self, so prepend to the module (instance methods become singleton)
+        OpenTelemetry::Baggage.prepend(interceptor)
+      end
+
+      def build_interceptor(allowed_keys, block_mode, logger)
+        Module.new do
+          define_method(:set_value) do |key, value, metadata: nil, context: nil|
+            ctx = context || (defined?(OpenTelemetry::Context) && OpenTelemetry::Context.current)
+            unless allowed_keys.include?(key.to_s)
+              message = "[E11y] Blocked PII from OpenTelemetry baggage: key=#{key.inspect}"
+              case block_mode
+              when :silent then logger&.debug(message)
+              when :warn then logger&.warn(message)
+              when :raise then raise E11y::BaggagePiiError, "#{message}. Only allowed keys: #{allowed_keys.join(', ')}"
+              end
+              return ctx
+            end
+            super(key, value, metadata: metadata, context: ctx)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/e11y/middleware/dev_log_source.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module E11y
+  module Middleware
+    # Sets Thread.current[:e11y_source] = "web" during a web request.
+    # Cleared after the request completes (even on exception).
+    #
+    # Also propagates trace_id to Rack env for the Browser Overlay:
+    # env["e11y.trace_id"] is set from Thread.current[:e11y_trace_id].
+    class DevLogSource
+      def initialize(app)
+        @app = app
+      end
+
+      def call(env)
+        Thread.current[:e11y_source] = "web"
+        env["e11y.trace_id"] ||= Thread.current[:e11y_trace_id]
+        @app.call(env)
+      ensure
+        Thread.current[:e11y_source] = nil
+      end
+    end
+  end
+end