e11y 0.2.0 → 1.0.0

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

data/lib/e11y/middleware/event_slo.rb

@@ -69,23 +69,30 @@ module E11y
         # Skip if SLO not enabled for this event
         # Support explicit event_class (for testing) or resolve from event_name
         event_class = event_data[:event_class] || resolve_event_class(event_data)
-        return event_data unless event_class.respond_to?(:slo_config)
-        return event_data unless event_class.slo_config&.enabled?
+        unless event_class.respond_to?(:slo_config) && event_class.slo_config&.enabled?
+          # Pass to next middleware even if SLO not enabled
+          return @app&.call(event_data) || event_data
+        end
 
         # Compute slo_status from payload
         slo_status = compute_slo_status(event_class, event_data[:payload])
-        return event_data unless slo_status
+        unless slo_status
+          # Pass to next middleware even if slo_status is nil
+          return @app&.call(event_data) || event_data
+        end
 
-        # Emit SLO metric
-        emit_slo_metric(event_class, slo_status, event_data[:payload])
+        # Emit SLO metric (with sampling correction when stratified sampling enabled)
+        emit_slo_metric(event_class, slo_status, event_data[:payload], event_data)
 
-        event_data # Passthrough (never modify event_data)
+        # Pass to next middleware (Routing writes to adapters)
+        @app&.call(event_data) || event_data
       rescue StandardError => e
         # Never fail event tracking due to SLO processing
         E11y.logger.error(
           "[E11y::Middleware::EventSlo] SLO processing failed for #{event_data[:event_name]}: #{e.message}"
         )
-        event_data
+        # Still pass to next middleware even on error
+        @app&.call(event_data) || event_data
       end
 
       private
@@ -124,15 +131,22 @@ module E11y
       end
 
       # Emit SLO metric to Yabeda/Prometheus.
+      # C11: Applies stratified sampling correction when event was sampled.
       #
       # @param event_class [Class] Event class
       # @param slo_status [String] 'success' or 'failure'
       # @param payload [Hash] Event payload
+      # @param event_data [Hash] Full event data (for sample_rate)
       # @return [void]
-      def emit_slo_metric(event_class, slo_status, payload)
+      def emit_slo_metric(event_class, slo_status, payload, _event_data = {})
         labels = build_slo_labels(event_class, slo_status, payload)
 
-        E11y::Metrics.increment(:slo_event_result_total, labels)
+        # C11: Apply sampling correction for accurate SLO with stratified sampling
+        stratum = slo_status == "success" ? :success : :error
+        correction = E11y::Sampling.stratified_tracker.sampling_correction(stratum)
+        value = (correction * 100).round / 100.0 # Round to 2 decimals for Prometheus
+
+        E11y::Metrics.increment(:slo_event_result_total, labels, value: value)
       rescue StandardError => e
         E11y.logger.error(
           "[E11y::Middleware::EventSlo] Failed to emit SLO metric for #{event_class.name}: #{e.message}"

data/lib/e11y/middleware/otel_span.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module E11y
+  module Middleware
+    # OtelSpan middleware — creates OpenTelemetry spans from events (ADR-007 §6, F2).
+    #
+    # When config.opentelemetry_span_creation_patterns is set, creates OTel spans
+    # for matching events. Errors/fatal always create spans.
+    #
+    # @see E11y::OpenTelemetry::SpanCreator
+    # @see ADR-007 §6 Traces Signal Export
+    class OtelSpan < Base
+      middleware_zone :adapters
+
+      def call(event_data)
+        if defined?(::OpenTelemetry::Trace) && defined?(E11y::OpenTelemetry::SpanCreator)
+          E11y::OpenTelemetry::SpanCreator.create_span_from_event(event_data)
+        end
+        @app.call(event_data)
+      end
+    end
+  end
+end

data/lib/e11y/middleware/pii_filter.rb

@@ -1,18 +1,20 @@
 # frozen_string_literal: true
 
+require "active_support/parameter_filter"
+
 module E11y
   module Middleware
-    # PII Filter Middleware - 3-Tier Strategy
+    # PII Filter Middleware
     #
     # Filters Personally Identifiable Information (PII) from event payloads
-    # before they reach adapters. Implements ADR-006 3-tier security model.
+    # before they reach adapters. Implements ADR-006 security model.
     #
-    # **Three-Tier Strategy:**
-    # - Tier 1: No PII (`contains_pii false`) - Skip filtering (0ms overhead)
-    # - Tier 2: Default - Rails filters only (~0.05ms overhead)
-    # - Tier 3: Explicit PII (`contains_pii true`) - Deep filtering (~0.2ms overhead)
+    # **Filtering modes:**
+    # - :no_pii — Skip filtering (contains_pii false, 0ms overhead)
+    # - :rails_filters — Rails filter_parameters only (~0.05ms overhead)
+    # - :explicit_pii — Field strategies, optionally per-adapter via exclude_adapters (~0.2ms)
     #
-    # @example Basic Usage (Tier 2 - Default)
+    # @example Basic Usage (:rails_filters - default)
     #   class Events::OrderCreated < E11y::Event::Base
     #     schema do
     #       required(:order_id).filled(:string)
@@ -20,12 +22,12 @@ module E11y
     #     end
     #   end
     #
-    # @example Tier 1: No PII (High Performance)
+    # @example :no_pii (skip filtering)
     #   class Events::HealthCheck < E11y::Event::Base
-    #     contains_pii false  # Skip all filtering
+    #     contains_pii false
     #   end
     #
-    # @example Tier 3: Explicit PII (Deep Filtering)
+    # @example :explicit_pii (field strategies)
     #   class Events::UserRegistered < E11y::Event::Base
     #     contains_pii true
     #
@@ -40,7 +42,6 @@ module E11y
     # @see UC-007 PII Filtering
     # @see E11y::PII::Patterns
     # rubocop:disable Metrics/ClassLength
-    # PII filter is a cohesive security component with 3-tier filtering strategy
     class PIIFilter < Base
       middleware_zone :security
 
@@ -53,27 +54,24 @@ module E11y
         @config = config
       end
 
-      # Process event and filter PII based on tier
+      # Process event and filter PII based on filtering mode
       #
       # @param event_data [Hash] Event data with payload
       # @return [Hash] Processed event data
       # rubocop:disable Lint/DuplicateBranch
-      # Unknown tiers intentionally fallback to no filtering (same as tier1)
       def call(event_data)
-        # Determine filtering tier
-        tier = determine_tier(event_data)
+        return @app.call(event_data) if event_data[:dlq_replayed]
+
+        mode = filtering_mode(event_data)
 
-        case tier
-        when :tier1
-          # Tier 1: No PII - Skip filtering (0ms overhead)
+        case mode
+        when :no_pii
           @app.call(event_data)
-        when :tier2
-          # Tier 2: Rails filters only (~0.05ms overhead)
+        when :rails_filters
           filtered_data = apply_rails_filters(event_data)
           @app.call(filtered_data)
-        when :tier3
-          # Tier 3: Deep filtering (~0.2ms overhead)
-          filtered_data = apply_deep_filtering(event_data)
+        when :explicit_pii
+          filtered_data = apply_explicit_pii_filtering(event_data)
           @app.call(filtered_data)
         else
           @app.call(event_data)
@@ -83,16 +81,11 @@ module E11y
 
       private
 
-      # Determine PII filtering tier for event
-      #
-      # @param event_data [Hash] Event data
-      # @return [Symbol] :tier1, :tier2, or :tier3
-      def determine_tier(event_data)
+      def filtering_mode(event_data)
         event_class = event_data[:event_class]
-        return :tier2 unless event_class.respond_to?(:pii_tier)
+        return :rails_filters unless event_class.respond_to?(:pii_filtering_mode)
 
-        # Return tier directly from event class
-        event_class.pii_tier
+        event_class.pii_filtering_mode
       end
 
       # Apply Rails filter_parameters (Tier 2)
@@ -109,52 +102,71 @@ module E11y
         filtered_data
       end
 
-      # Apply deep PII filtering (Tier 3)
-      #
-      # @param event_data [Hash] Event data
-      # @return [Hash] Filtered event data
-      def apply_deep_filtering(event_data)
+      # :explicit_pii — field strategies, optionally payload_rewrites when exclude_adapters present.
+      def apply_explicit_pii_filtering(event_data)
         event_class = event_data[:event_class]
         return event_data unless event_class
 
-        # Clone to avoid modifying original
-        filtered_data = deep_dup(event_data)
-
-        # Get PII filtering config from event class
         pii_config = event_class.pii_filtering_config if event_class.respond_to?(:pii_filtering_config)
-        return filtered_data unless pii_config
+        return event_data unless pii_config
+
+        # 1. Base payload (most restrictive)
+        base_payload = apply_field_strategies(deep_dup(event_data[:payload]), pii_config, nil)
+        base_payload = apply_pattern_filtering(base_payload, pii_config, [])
 
-        # Apply field-level strategies
-        filtered_data[:payload] = apply_field_strategies(
-          filtered_data[:payload],
-          pii_config
-        )
+        filtered_data = deep_dup(event_data)
+        filtered_data[:payload] = base_payload
 
-        # Apply pattern-based filtering
-        filtered_data[:payload] = apply_pattern_filtering(
-          filtered_data[:payload]
-        )
+        # 2. payload_rewrites: per-adapter overrides for exclude_adapters fields only
+        has_exclude_adapters = pii_config[:fields]&.any? { |_, v| v[:exclude_adapters]&.any? }
+        filtered_data[:payload_rewrites] = build_payload_rewrites(event_data, pii_config) if has_exclude_adapters
 
         filtered_data
       end
 
+      # Build payload_rewrites: { adapter_name => { field => original_value } }
+      # Only fields with exclude_adapters.include?(adapter) get original value.
+      def build_payload_rewrites(event_data, pii_config)
+        adapters = AdapterResolver.resolve(event_data)
+        return {} unless adapters.any?
+
+        original_payload = event_data[:payload] || {}
+        rewrites = {}
+
+        adapters.each do |adapter_name|
+          adapter_rewrites = {}
+          pii_config[:fields]&.each do |field, opts|
+            next unless opts[:exclude_adapters]&.include?(adapter_name)
+
+            key = original_payload.key?(field) ? field : field.to_s
+            adapter_rewrites[key] = original_payload[key] if original_payload.key?(key)
+          end
+          rewrites[adapter_name] = adapter_rewrites if adapter_rewrites.any?
+        end
+        rewrites
+      end
+
       # Apply field-level filtering strategies
       #
       # @param payload [Hash] Payload to filter
       # @param config [Hash] PII configuration
+      # @param adapter_name [Symbol, nil] When set, use :skip for fields with exclude_adapters.include?(adapter_name)
       # @return [Hash] Filtered payload
-      # rubocop:disable Metrics/CyclomaticComplexity, Metrics/MethodLength
-      # Field strategies require case/when for each PII filtering strategy type
-      def apply_field_strategies(payload, config)
+      # rubocop:disable Metrics/MethodLength
+      def apply_field_strategies(payload, config, adapter_name = nil)
         return payload unless config
 
         filtered = {}
 
         payload.each do |key, value|
-          strategy = config.dig(:fields, key, :strategy) || :allow
+          normalized_key = key.is_a?(Symbol) ? key : key.to_sym
+          field_config = config.dig(:fields, normalized_key) || {}
+          strategy = field_config[:strategy] || :allow
+
+          # Per-adapter: use :skip for excluded adapters (e.g. audit gets original)
+          strategy = :allow if adapter_name && field_config[:exclude_adapters]&.include?(adapter_name)
 
           # rubocop:disable Lint/DuplicateBranch
-          # Unknown strategies intentionally fallback to allow (same as :allow)
           filtered[key] = case strategy
                           when :mask
                             "[FILTERED]"
@@ -164,7 +176,7 @@ module E11y
                             partial_mask(value)
                           when :redact
                             nil
-                          when :allow
+                          when :allow, :skip
                             value
                           else
                             value
@@ -174,34 +186,45 @@ module E11y
 
         filtered
       end
-      # rubocop:enable Metrics/CyclomaticComplexity, Metrics/MethodLength
+      # rubocop:enable Metrics/MethodLength
 
       # Apply pattern-based filtering to string values
-      #
-      # @param data [Object] Data to filter (recursively)
-      # @return [Object] Filtered data
-      def apply_pattern_filtering(data)
+      def apply_pattern_filtering(data, pii_config = nil, path = [])
         case data
-        when Hash
-          data.transform_values { |v| apply_pattern_filtering(v) }
-        when Array
-          data.map { |v| apply_pattern_filtering(v) }
-        when String
-          filter_string_patterns(data)
-        else
-          data
+        when Hash then apply_pattern_filtering_hash(data, pii_config, path)
+        when Array then data.map { |v| apply_pattern_filtering(v, pii_config, path) }
+        when String then filter_string_if_needed(data, path, pii_config)
+        else data
         end
       end
 
-      # Filter PII patterns in string
+      def apply_pattern_filtering_hash(data, pii_config, path)
+        data.each_with_object({}) do |(k, v), acc|
+          key_sym = k.is_a?(Symbol) ? k : k.to_sym
+          acc[k] = apply_pattern_filtering(v, pii_config, path + [key_sym])
+        end
+      end
+
+      def filter_string_if_needed(str, path, pii_config)
+        path_under_allowed_key?(path, pii_config) ? str : filter_string_patterns(str)
+      end
+
+      # Check if any ancestor key in path is explicitly allowed
+      def path_under_allowed_key?(path, pii_config)
+        return false unless pii_config && pii_config[:fields]
+
+        allowed_keys = pii_config[:fields].select { |_k, v| %i[allow skip].include?(v[:strategy]) }.keys
+        path.any? { |p| allowed_keys.include?(p) }
+      end
+
+      # Filter PII patterns in string (VALUE_PATTERNS only, not PASSWORD_FIELDS)
       #
       # @param str [String] String to filter
       # @return [String] Filtered string
       def filter_string_patterns(str)
         result = str.dup
 
-        # Apply all PII patterns
-        E11y::PII::Patterns::ALL.each do |pattern|
+        E11y::PII::Patterns::VALUE_PATTERNS.each do |pattern|
           result = result.gsub(pattern, "[FILTERED]")
         end
 
@@ -261,12 +284,18 @@ module E11y
       # Get Rails parameter filter
       #
       # Uses Rails.application.config.filter_parameters for PII filtering.
+      # When Rails is not loaded (e.g. unit tests), uses empty filter (no-op).
       #
       # @return [ActiveSupport::ParameterFilter] Parameter filter
       def parameter_filter
-        @parameter_filter ||= ActiveSupport::ParameterFilter.new(
-          Rails.application.config.filter_parameters
-        )
+        return @parameter_filter if defined?(@parameter_filter) && !@parameter_filter.nil?
+
+        filters = if defined?(Rails) && Rails.application
+                    Rails.application.config.filter_parameters
+                  else
+                    []
+                  end
+        @parameter_filter = ActiveSupport::ParameterFilter.new(filters)
       end
     end
     # rubocop:enable Metrics/ClassLength