e11y 0.1.0

data/lib/e11y/middleware/audit_signing.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+require "openssl"
+require "json"
+
+module E11y
+  module Middleware
+    # Audit Signing Middleware - HMAC-SHA256 signatures for audit events
+    #
+    # Signs audit events with HMAC-SHA256 before any transformations (including PII filtering).
+    # This ensures cryptographic proof of event authenticity for compliance.
+    #
+    # **Critical Design:**
+    # - Signs ORIGINAL data (before PII filtering) for legal compliance
+    # - Only processes events marked as audit events
+    # - Runs in :security zone BEFORE other middleware
+    #
+    # @example Audit Event
+    #   class Events::UserDeleted < E11y::Event::Base
+    #     audit_event true
+    #
+    #     schema do
+    #       required(:user_id).filled(:integer)
+    #       required(:deleted_by).filled(:integer)
+    #       required(:ip_address).filled(:string)
+    #     end
+    #   end
+    #
+    #   Events::UserDeleted.track(
+    #     user_id: 123,
+    #     deleted_by: 456,
+    #     ip_address: "192.168.1.1"  # Original IP preserved
+    #   )
+    #
+    #   # Result: Signed with HMAC-SHA256 before PII filtering
+    #
+    # @see ADR-006 §4.0 Audit Trail Security
+    # @see UC-012 Audit Trail
+    class AuditSigning < Base
+      middleware_zone :security
+
+      # HMAC signing key (from ENV or generated)
+      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
+
+        "development_key_#{SecureRandom.hex(32)}"
+      end
+
+      # Initialize audit signing middleware
+      #
+      # @param app [Proc] Next middleware in chain
+
+      # Process event and sign if it's an audit event
+      #
+      # @param event_data [Hash] Event data with payload
+      # @return [Hash] Event data with signature
+      def call(event_data)
+        # Only sign audit events that require signing
+        if audit_event?(event_data) && requires_signing?(event_data)
+          signed_data = sign_event(event_data)
+          @app.call(signed_data)
+        else
+          # Non-audit events OR signing disabled: pass through
+          @app.call(event_data)
+        end
+      end
+
+      # Verify signature (for testing/validation)
+      #
+      # @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 && canonical
+
+        actual_signature = OpenSSL::HMAC.hexdigest("SHA256", SIGNING_KEY, canonical)
+        actual_signature == expected_signature
+      end
+      # rubocop:enable Naming/PredicateMethod
+
+      private
+
+      # Check if event is marked as audit event
+      #
+      # @param event_data [Hash] Event data
+      # @return [Boolean] true if audit event
+      def audit_event?(event_data)
+        event_class = event_data[:event_class]
+        event_class.respond_to?(:audit_event?) && event_class.audit_event?
+      end
+
+      # Check if event requires signing
+      #
+      # Signing is enabled by default for all audit events.
+      # Can be disabled via `signing enabled: false` DSL.
+      #
+      # @param event_data [Hash] Event data
+      # @return [Boolean] true if signing required
+      def requires_signing?(event_data)
+        event_class = event_data[:event_class]
+
+        # Default: true (sign all audit events unless explicitly disabled)
+        return true unless event_class.respond_to?(:signing_enabled?)
+
+        event_class.signing_enabled?
+      end
+
+      # Sign event with HMAC-SHA256
+      #
+      # @param event_data [Hash] Event data
+      # @return [Hash] Event data with signature
+      def sign_event(event_data)
+        # 1. Create canonical representation (sorted JSON for consistency)
+        canonical = canonical_representation(event_data)
+
+        # 2. Generate HMAC-SHA256 signature
+        signature = generate_signature(canonical)
+
+        # 3. Add signature metadata
+        event_data.merge(
+          audit_signature: signature,
+          audit_signed_at: Time.now.utc.iso8601(6),
+          audit_canonical: canonical
+        )
+      end
+
+      # Create canonical representation for signing
+      #
+      # @param event_data [Hash] Event data
+      # @return [String] Canonical JSON string
+      def 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
+
+      # Generate HMAC-SHA256 signature
+      #
+      # @param data [String] Data to sign
+      # @return [String] Hex-encoded signature
+      def generate_signature(data)
+        OpenSSL::HMAC.hexdigest("SHA256", SIGNING_KEY, data)
+      end
+
+      # Sort hash recursively for deterministic JSON
+      #
+      # @param obj [Object] Object to sort
+      # @return [Object] Sorted object
+      def 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
+    end
+  end
+end

data/lib/e11y/middleware/base.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+module E11y
+  module Middleware
+    # Base class for all E11y middlewares.
+    #
+    # Provides the contract for middleware chain pattern and zone-based organization.
+    # All middlewares must inherit from this class.
+    #
+    # @abstract Subclasses must implement {#call} to process events.
+    #
+    # @example Basic Middleware
+    #   class MyMiddleware < E11y::Middleware::Base
+    #     middleware_zone :pre_processing
+    #
+    #     def call(event_data)
+    #       # Process event
+    #       event_data[:custom_field] = "value"
+    #
+    #       # Continue chain
+    #       @app.call(event_data)
+    #     end
+    #   end
+    #
+    # @example Zone-Aware Middleware
+    #   class SafeEnrichment < E11y::Middleware::Base
+    #     middleware_zone :pre_processing
+    #     modifies_fields :metadata, :context
+    #
+    #     def call(event_data)
+    #       validate_zone_rules!(event_data)
+    #
+    #       event_data[:payload][:metadata] = fetch_metadata
+    #       @app.call(event_data)
+    #     end
+    #   end
+    #
+    # @see ADR-015 Middleware Execution Order
+    # @see ADR-015 §3.4 Middleware Zones & Modification Rules
+    class Base
+      # Valid middleware zones in execution order
+      VALID_ZONES = %i[
+        pre_processing
+        security
+        routing
+        post_processing
+        adapters
+      ].freeze
+
+      class << self
+        # Declare which zone this middleware belongs to.
+        #
+        # Zones define execution order and modification constraints:
+        # - `:pre_processing` - Add fields before PII filtering
+        # - `:security` - PII filtering (critical zone)
+        # - `:routing` - Rate limiting, sampling (read-only decisions)
+        # - `:post_processing` - Add metadata after PII filtering
+        # - `:adapters` - Route to buffers and adapters
+        #
+        # @param zone [Symbol] The zone this middleware belongs to
+        # @return [Symbol] The assigned zone
+        # @raise [ArgumentError] if zone is not valid
+        #
+        # @example
+        #   class MyMiddleware < E11y::Middleware::Base
+        #     middleware_zone :pre_processing
+        #   end
+        #
+        # @see ADR-015 §3.4.2 Middleware Zones
+        def middleware_zone(zone = nil)
+          if zone
+            unless VALID_ZONES.include?(zone)
+              raise ArgumentError,
+                    "Invalid middleware zone: #{zone.inspect}. " \
+                    "Must be one of #{VALID_ZONES.inspect}"
+            end
+            @middleware_zone = zone
+          end
+
+          # Return zone (getter if no argument provided)
+          @middleware_zone || inherited_zone
+        end
+
+        # Declare which fields this middleware modifies.
+        #
+        # Used for zone validation and documentation.
+        #
+        # @param fields [Array<Symbol>] Field names this middleware modifies
+        # @return [Array<Symbol>] The declared modified fields
+        #
+        # @example
+        #   class MyMiddleware < E11y::Middleware::Base
+        #     modifies_fields :trace_id, :timestamp
+        #   end
+        def modifies_fields(*fields)
+          @modifies_fields = fields if fields.any?
+          @modifies_fields || []
+        end
+
+        private
+
+        # Get zone from parent class if not explicitly set on current class
+        # @return [Symbol, nil]
+        def inherited_zone
+          return nil unless superclass.respond_to?(:middleware_zone, true)
+          return nil if superclass == E11y::Middleware::Base
+
+          superclass.middleware_zone
+        end
+      end
+
+      # Initialize middleware with the next middleware in chain.
+      #
+      # @param app [#call] The next middleware or final endpoint in the chain
+      def initialize(app)
+        @app = app
+      end
+
+      # Process an event and pass it to the next middleware.
+      #
+      # @abstract Subclasses must implement this method
+      # @param event_data [Hash] The event hash to process
+      # @return [void]
+      # @raise [NotImplementedError] if not implemented by subclass
+      #
+      # @example
+      #   def call(event_data)
+      #     # Pre-processing
+      #     event_data[:processed_at] = Time.now.utc
+      #
+      #     # Continue chain
+      #     @app.call(event_data)
+      #   end
+      def call(_event_data)
+        raise NotImplementedError,
+              "#{self.class.name} must implement #call(event_data)"
+      end
+    end
+  end
+end

data/lib/e11y/middleware/event_slo.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+require "e11y/middleware/base"
+require "e11y/slo/event_driven"
+
+module E11y
+  module Middleware
+    # EventSLO Middleware for Event-Driven SLO tracking (ADR-014).
+    #
+    # Automatically processes events with SLO configuration enabled,
+    # computes `slo_status` from payload, and emits metrics.
+    #
+    # **Features:**
+    # - Auto-detects events with `slo { enabled true }`
+    # - Calls `slo_status_from` proc to compute 'success'/'failure'
+    # - Emits `slo_event_result_total{slo_status}` metric to Yabeda
+    # - Never fails event tracking (graceful error handling)
+    #
+    # **Middleware Zone:** `:post_processing` (after routing, before adapters)
+    #
+    # **ADR References:**
+    # - ADR-014 §3 (Event SLO DSL)
+    # - ADR-014 §4 (SLO Status Calculation)
+    # - ADR-014 §6 (Metrics Export)
+    # - ADR-015 §3 (Middleware Order)
+    #
+    # **Use Case:** UC-014 (Event-Driven SLO)
+    #
+    # @example Configuration
+    #   E11y.configure do |config|
+    #     # Enable EventSLO middleware (auto-enabled if any Events have slo { enabled true })
+    #     config.pipeline.use E11y::Middleware::EventSlo, zone: :post_processing
+    #   end
+    #
+    # @example Event with SLO
+    #   module Events
+    #     class PaymentProcessed < E11y::Event::Base
+    #       schema do
+    #         required(:payment_id).filled(:string)
+    #         required(:status).filled(:string)
+    #       end
+    #
+    #       slo do
+    #         enabled true
+    #         slo_status_from do |payload|
+    #           case payload[:status]
+    #           when 'completed' then 'success'
+    #           when 'failed' then 'failure'
+    #           else nil  # Not counted
+    #           end
+    #         end
+    #       end
+    #     end
+    #   end
+    #
+    #   # Tracking will automatically emit SLO metric:
+    #   Events::PaymentProcessed.track(payment_id: 'p123', status: 'completed')
+    #   # → Emits: slo_event_result_total{event_name="payment.processed", slo_status="success"} +1
+    #
+    # @see ADR-014 for complete Event-Driven SLO architecture
+    class EventSlo < Base
+      middleware_zone :post_processing
+
+      # Process event and emit SLO metric if SLO is enabled.
+      #
+      # @param event_data [Hash] Event payload
+      # @return [Hash] Unchanged event_data (passthrough)
+      def call(event_data)
+        # 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?
+
+        # Compute slo_status from payload
+        slo_status = compute_slo_status(event_class, event_data[:payload])
+        return event_data unless slo_status
+
+        # Emit SLO metric
+        emit_slo_metric(event_class, slo_status, event_data[:payload])
+
+        event_data # Passthrough (never modify 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
+      end
+
+      private
+
+      # Resolve Event class from event_name.
+      #
+      # @param event_data [Hash] Event payload
+      # @return [Class, nil] Event class or nil if not found
+      def resolve_event_class(event_data)
+        event_name = event_data[:event_name]
+        return nil unless event_name
+
+        # Convert event_name to class name (e.g., "payment.processed" → "Events::PaymentProcessed")
+        # This assumes Rails autoloading or explicit requires
+        class_name = event_name.to_s.split(".").map(&:capitalize).join
+        "Events::#{class_name}".constantize
+      rescue NameError
+        # Event class not found (may be from external source)
+        nil
+      end
+
+      # Compute slo_status using event's slo_status_from proc.
+      #
+      # @param event_class [Class] Event class
+      # @param payload [Hash] Event payload
+      # @return [String, nil] 'success', 'failure', or nil
+      def compute_slo_status(event_class, payload)
+        return nil unless event_class.slo_config.slo_status_proc
+
+        event_class.slo_config.slo_status_proc.call(payload)
+      rescue StandardError => e
+        E11y.logger.error(
+          "[E11y::Middleware::EventSlo] Failed to compute slo_status for #{event_class.name}: #{e.message}"
+        )
+        nil
+      end
+
+      # Emit SLO metric to Yabeda/Prometheus.
+      #
+      # @param event_class [Class] Event class
+      # @param slo_status [String] 'success' or 'failure'
+      # @param payload [Hash] Event payload
+      # @return [void]
+      def emit_slo_metric(event_class, slo_status, payload)
+        labels = build_slo_labels(event_class, slo_status, payload)
+
+        E11y::Metrics.increment(:slo_event_result_total, labels)
+      rescue StandardError => e
+        E11y.logger.error(
+          "[E11y::Middleware::EventSlo] Failed to emit SLO metric for #{event_class.name}: #{e.message}"
+        )
+      end
+
+      # Build metric labels for SLO.
+      #
+      # @param event_class [Class] Event class
+      # @param slo_status [String] 'success' or 'failure'
+      # @param payload [Hash] Event payload
+      # @return [Hash] Metric labels
+      def build_slo_labels(event_class, slo_status, payload)
+        labels = {
+          event_name: event_class.event_name,
+          slo_status: slo_status
+        }
+
+        # Add custom SLO name if configured
+        labels[:slo_name] = event_class.slo_config.contributes_to_value if event_class.slo_config.contributes_to_value
+
+        # Add group_by field if configured
+        if event_class.slo_config.group_by_field
+          field = event_class.slo_config.group_by_field
+          labels[:group_by] = payload[field].to_s if payload[field]
+        end
+
+        labels
+      end
+    end
+  end
+end