orfeas_lyra 0.6.0

data/lib/lyra/privacy/pii_detector.rb

@@ -0,0 +1,85 @@
+module Lyra
+  module Privacy
+    # Detects personally identifiable information (PII) in data
+    #
+    # This class delegates to PamDsl::PIIDetector for the core PII detection logic,
+    # providing a unified implementation across both Lyra and PAM DSL.
+    #
+    # @example Detect PII in attributes
+    #   PIIDetector.detect({ email: "test@example.com", name: "John" })
+    #   # => { email: { type: :email, value: "test@example.com", sensitive: false }, ... }
+    #
+    # @example Check if a field contains PII
+    #   PIIDetector.contains_pii?(:email)  # => true
+    #   PIIDetector.contains_pii?(:count)  # => false
+    #
+    class PIIDetector
+      class << self
+        # Detect PII in attributes
+        #
+        # @param attributes [Hash] Key-value pairs to check for PII
+        # @return [Hash] Keys that contain PII, with their type, value, and sensitivity
+        #
+        def detect(attributes)
+          PamDsl::PIIDetector.detect(attributes)
+        end
+
+        # Check if a field contains PII
+        #
+        # @param field_name [String, Symbol] Field name to check
+        # @return [Boolean] true if field contains PII
+        #
+        def contains_pii?(field_name)
+          PamDsl::PIIDetector.contains_pii?(field_name)
+        end
+
+        # Mask PII for display
+        #
+        # @param value [Object] The value to mask
+        # @param pii_type [Symbol] The type of PII
+        # @return [String] Masked value
+        #
+        def mask(value, pii_type)
+          PamDsl::PIIDetector.mask(value, pii_type)
+        end
+
+        # Extract all PII from event stream
+        #
+        # This is a convenience wrapper around PamDsl::PIIDetector.extract_pii_from_records
+        # that provides Lyra-specific extractors for Lyra::Event objects.
+        #
+        # @param events [Array<Lyra::Event>] Events to scan for PII
+        # @return [Hash] PII inventory grouped by type
+        #
+        # @example
+        #   events = Lyra.config.event_store.read.stream("User$123").to_a
+        #   pii = PIIDetector.extract_from_event_stream(events)
+        #   # => { email: [{ field: :email, value: "...", event_id: "...", ... }], ... }
+        #
+        def extract_from_event_stream(events)
+          PamDsl::PIIDetector.extract_pii_from_records(
+            events,
+            attribute_extractor: ->(e) { e.attributes },
+            metadata_extractor: ->(e) {
+              {
+                event_id: e.event_id,
+                timestamp: e.timestamp,
+                model_class: e.model_class,
+                model_id: e.model_id
+              }
+            }
+          )
+        end
+
+        # Check if a PII type is considered sensitive
+        #
+        # @param pii_type [Symbol] The PII type
+        # @return [Boolean]
+        #
+        def sensitive?(pii_type)
+          PamDsl::PIIDetector.sensitive?(pii_type)
+        end
+      end
+    end
+  end
+end

data/lib/lyra/privacy/pii_masker.rb

@@ -0,0 +1,66 @@
+module Lyra
+  module Privacy
+    # Masks PII in attribute hashes
+    #
+    # This class delegates to PamDsl::PIIMasker for the core masking logic,
+    # providing a unified implementation across both Lyra and PAM DSL.
+    #
+    # @example Mask all PII in attributes
+    #   PIIMasker.mask({ email: "test@example.com", name: "John" })
+    #   # => { email: "t***@example.com", name: "John ***" }
+    #
+    # @example Full redaction
+    #   PIIMasker.mask({ email: "test@example.com" }, strategy: :full)
+    #   # => { email: "[REDACTED]" }
+    #
+    class PIIMasker
+      class << self
+        # Mask all PII fields in an attributes hash
+        #
+        # @param attributes [Hash] Key-value pairs to mask
+        # @param strategy [Symbol] Masking strategy (:partial, :full, :redact_sensitive)
+        # @return [Hash] New hash with PII fields masked
+        #
+        def mask(attributes, strategy: :partial)
+          PamDsl::PIIMasker.mask(attributes, strategy: strategy)
+        end
+
+        # Mask specific field
+        #
+        # @param value [Object] The value to mask
+        # @param field_name [String, Symbol] Field name to determine PII type
+        # @return [Object] Masked value, or original if not PII
+        #
+        def mask_field(value, field_name)
+          PamDsl::PIIMasker.mask_field(value, field_name)
+        end
+
+        # Mask all PII in a collection of Lyra events
+        #
+        # @param events [Array<Lyra::Event>] Events to mask
+        # @param strategy [Symbol] Masking strategy
+        # @return [Array] Events with masked attributes
+        #
+        def mask_events(events, strategy: :partial)
+          PamDsl::PIIMasker.mask_records(
+            events,
+            attribute_extractor: ->(e) { e.attributes },
+            attribute_setter: ->(e, masked) {
+              Lyra::Event.new(
+                event_id: e.event_id,
+                operation: e.operation,
+                model_class: e.model_class,
+                model_id: e.model_id,
+                attributes: masked,
+                changes: e.changes,
+                timestamp: e.timestamp,
+                metadata: e.metadata
+              )
+            },
+            strategy: strategy
+          )
+        end
+      end
+    end
+  end
+end

data/lib/lyra/privacy/policy_integration.rb

@@ -0,0 +1,253 @@
+module Lyra
+  module Privacy
+    # Integration layer between Lyra and PAM DSL
+    #
+    # When PAM DSL is available, combines policy-defined fields with
+    # pattern-based PIIDetector for comprehensive PII detection.
+    #
+    # @example With policy and detector fallback (default)
+    #   integration = PolicyIntegration.new(:my_policy)
+    #   integration.detect_pii(attrs)  # Uses policy + detector
+    #
+    # @example Policy-only mode
+    #   integration = PolicyIntegration.new(:my_policy, use_detector: false)
+    #   integration.detect_pii(attrs)  # Only fields defined in policy
+    #
+    class PolicyIntegration
+      attr_reader :policy, :use_detector
+
+      def initialize(policy_name, use_detector: true)
+        @use_detector = use_detector
+        @policy = PamDsl.policy(policy_name)
+      rescue PamDsl::PolicyNotFoundError
+        @policy = nil
+      rescue NameError
+        # PAM DSL not available
+        @policy = nil
+        @use_detector = false
+      end
+
+      # Check if PAM DSL is available
+      def pam_dsl_available?
+        defined?(PamDsl)
+      end
+
+      # Check if policy is loaded
+      def policy_loaded?
+        !@policy.nil?
+      end
+
+      # Validate data access for a purpose
+      def validate_access!(field_names, purpose, consent_status = {})
+        return true unless policy_loaded?
+
+        @policy.validate_access!(
+          field_names,
+          purpose,
+          consent_granted: consent_status[:granted] || false,
+          consent_granted_at: consent_status[:granted_at]
+        )
+      end
+
+      # Get PII fields from attributes using policy and/or detector
+      #
+      # Priority:
+      # 1. Fields defined in policy (explicit configuration)
+      # 2. Fields detected by PIIDetector (pattern-based, if use_detector: true)
+      #
+      # @param attributes [Hash] Key-value pairs to check for PII
+      # @return [Hash] PII fields with type, value, sensitivity
+      #
+      def detect_pii(attributes)
+        return {} unless pam_dsl_available?
+
+        pii_fields = {}
+
+        attributes.each do |key, value|
+          field_name = key.to_sym
+
+          # Try policy first
+          if policy_loaded?
+            begin
+              field = @policy.get_field(field_name)
+              pii_fields[key] = {
+                type: field.type,
+                value: value,
+                sensitive: field.sensitive?,
+                sensitivity: field.sensitivity,
+                source: :policy
+              }
+              next
+            rescue PamDsl::InvalidFieldError
+              # Field not in policy, try detector below
+            end
+          end
+
+          # Fall back to PIIDetector if enabled
+          if @use_detector
+            detected = PamDsl::PIIDetector.detect({ key => value })
+            if detected[key]
+              pii_fields[key] = detected[key].merge(source: :detector)
+            end
+          end
+        end
+
+        pii_fields
+      end
+
+      # Mask PII using policy transformations or PIIDetector
+      #
+      # @param field_name [Symbol, String] Field name
+      # @param value [Object] Value to mask
+      # @param context [Symbol] Transformation context (default: :display)
+      # @return [Object] Masked value, or original if no masking available
+      #
+      def mask_pii(field_name, value, context = :display)
+        return value unless pam_dsl_available?
+
+        # Try policy transformation first
+        if policy_loaded?
+          begin
+            field = @policy.get_field(field_name)
+            return field.apply_transformation(context, value)
+          rescue PamDsl::InvalidFieldError
+            # Field not in policy, try detector below
+          end
+        end
+
+        # Fall back to PIIDetector masking if enabled
+        if @use_detector
+          pii_type = PamDsl::PIIDetector.pii_type(field_name)
+          return PamDsl::PIIDetector.mask(value, pii_type) if pii_type
+        end
+
+        value
+      end
+
+      # Get retention duration for model and field
+      # Returns nil if no policy loaded (infinite/manual retention)
+      def retention_duration(model_class, field_name: nil)
+        return nil unless policy_loaded?
+        @policy.retention_for(model_class, field_name: field_name)
+      end
+
+      # Check if consent is required for purpose
+      def consent_required?(purpose)
+        return false unless policy_loaded?
+
+        begin
+          purpose_obj = @policy.get_purpose(purpose)
+          purpose_obj.requires_consent?
+        rescue PamDsl::Error
+          false
+        end
+      end
+
+      # Get allowed purposes for a field
+      def allowed_purposes(field_name)
+        return [] unless policy_loaded?
+
+        begin
+          field = @policy.get_field(field_name)
+          field.purposes
+        rescue PamDsl::InvalidFieldError
+          []
+        end
+      end
+
+      # Check if field is allowed for purpose
+      def allowed?(field_name, purpose)
+        return true unless policy_loaded?
+        @policy.allowed?(field_name, purpose)
+      end
+
+      # Get all sensitive fields
+      def sensitive_fields
+        return [] unless policy_loaded?
+        @policy.sensitive_fields.map(&:name)
+      end
+
+      # Get all restricted fields
+      def restricted_fields
+        return [] unless policy_loaded?
+        @policy.restricted_fields.map(&:name)
+      end
+
+      # Get policy metadata
+      def metadata
+        return {} unless policy_loaded?
+        @policy.metadata
+      end
+
+      # Export policy information
+      def to_h
+        {
+          pam_dsl_available: pam_dsl_available?,
+          policy_loaded: policy_loaded?,
+          use_detector: @use_detector
+        }.tap do |info|
+          if policy_loaded?
+            info.merge!(
+              policy_name: @policy.name,
+              fields_count: @policy.fields.count,
+              purposes_count: @policy.purposes.count,
+              sensitive_fields: sensitive_fields,
+              restricted_fields: restricted_fields,
+              metadata: @policy.metadata
+            )
+          end
+        end
+      end
+    end
+
+    # Extend GDPRCompliance with policy integration
+    class GDPRCompliance
+      # Use privacy policy for PII detection if available
+      #
+      # @param attributes [Hash] Attributes to check
+      # @param policy_name [Symbol] Policy name
+      # @param use_detector [Boolean] Fall back to PIIDetector (default: true)
+      #
+      def detect_pii_with_policy(attributes, policy_name, use_detector: true)
+        integration = PolicyIntegration.new(policy_name, use_detector: use_detector)
+        integration.detect_pii(attributes)
+      end
+
+      # Check retention compliance with policy
+      # Returns nil for models without defined retention (infinite/manual)
+      def retention_compliance_with_policy(policy_name)
+        integration = PolicyIntegration.new(policy_name)
+        events = collect_all_events
+
+        events.group_by { |e| e.model_class }.map do |model_class, model_events|
+          retention_duration = integration.retention_duration(model_class)
+
+          # nil means infinite/manual retention - always compliant
+          if retention_duration.nil?
+            {
+              model_class: model_class,
+              total_events: model_events.count,
+              expired_events: 0,
+              retention_period: nil,
+              compliance_status: :manual,
+              expired_event_ids: []
+            }
+          else
+            expired = model_events.select do |event|
+              event.timestamp && event.timestamp < (Time.current - retention_duration)
+            end
+
+            {
+              model_class: model_class,
+              total_events: model_events.count,
+              expired_events: expired.count,
+              retention_period: retention_duration,
+              compliance_status: expired.empty? ? :compliant : :requires_action,
+              expired_event_ids: expired.map(&:event_id)
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/lyra/projection.rb

@@ -0,0 +1,94 @@
+module Lyra
+  # Base class for projections (read models)
+  class Projection
+    class << self
+      def handle(event)
+        new.handle(event)
+      end
+
+      def subscribe_to(*event_types)
+        event_types.each do |event_type|
+          Lyra.config.event_store.subscribe(self, to: [event_type])
+        end
+      end
+    end
+
+    def handle(event)
+      method_name = "apply_#{event.class.name.demodulize.underscore}"
+      send(method_name, event) if respond_to?(method_name, true)
+    end
+  end
+
+  # State projection that rebuilds current state from events
+  class StateProjection < Projection
+    def self.rebuild_state(model_class, model_id)
+      stream_name = "#{model_class.name}$#{model_id}"
+      events = Lyra.config.event_store.read.stream(stream_name).to_a
+
+      new.rebuild_from_events(events)
+    end
+
+    def rebuild_from_events(events)
+      state = {}
+
+      events.each do |event|
+        case event_operation(event)
+        when :created
+          state = event_attributes(event)
+        when :updated
+          state.merge!(event_changes(event).transform_values { |v| v.last })
+        when :destroyed
+          state[:deleted] = true
+          state[:deleted_at] = event_timestamp(event)
+        end
+      end
+
+      state
+    end
+
+    private
+
+    def event_operation(event)
+      return event.operation if event.respond_to?(:operation)
+      op = event.data[:operation] || event.data["operation"]
+      op.is_a?(String) ? op.to_sym : op
+    end
+
+    def event_attributes(event)
+      return event.attributes if event.respond_to?(:attributes) && !event.attributes.is_a?(Hash)
+      event.data[:attributes] || event.data["attributes"] || {}
+    end
+
+    def event_changes(event)
+      return event.changes if event.respond_to?(:changes) && event.method(:changes).owner != ActiveRecord::AttributeMethods::Dirty rescue event.changes
+      event.data[:changes] || event.data["changes"] || {}
+    end
+
+    def event_timestamp(event)
+      return event.timestamp if event.respond_to?(:timestamp) && event.timestamp
+      event.data[:timestamp] || event.data["timestamp"] || event.metadata[:timestamp]
+    end
+  end
+
+  # Audit trail projection
+  class AuditProjection < Projection
+    def self.audit_trail(model_class, model_id)
+      stream_name = "#{model_class.name}$#{model_id}"
+      events = Lyra.config.event_store.read.stream(stream_name).to_a
+
+      events.map do |event|
+        # Access data with both symbol and string keys (JSON serializer uses strings)
+        data = event.data
+        nested_metadata = data[:metadata] || data["metadata"] || {}
+
+        {
+          operation: data[:operation] || data["operation"],
+          timestamp: data[:timestamp] || data["timestamp"] || event.metadata[:timestamp],
+          user_id: nested_metadata[:user_id] || nested_metadata["user_id"],
+          changes: data[:changes] || data["changes"] || {},
+          attributes: data[:attributes] || data["attributes"] || {}
+        }
+      end
+    end
+  end
+end

data/lib/lyra/projections/async_projection_job.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Lyra
+  module Projections
+    # ActiveJob for asynchronous projection processing.
+    #
+    # When projection_mode is :async, events are projected to model tables
+    # in background jobs rather than synchronously during the request.
+    #
+    # Benefits:
+    # - Faster response times (don't wait for projection)
+    # - Better fault isolation (projection failures don't fail requests)
+    # - Retry capability for transient failures
+    #
+    # Trade-offs:
+    # - Eventual consistency (reads may not see latest writes immediately)
+    # - Requires background job infrastructure (Sidekiq, etc.)
+    #
+    # Usage:
+    #   AsyncProjectionJob.perform_later(event_id, 'Registration', :create)
+    #
+    class AsyncProjectionJob < ActiveJob::Base
+      queue_as :lyra_projections
+
+      # Retry with exponential backoff for transient failures
+      retry_on StandardError, wait: :polynomially_longer, attempts: 5
+
+      # Don't retry on permanent failures
+      discard_on ActiveRecord::RecordNotFound
+
+      def perform(event_id, model_class_name, operation)
+        event = load_event(event_id)
+        return unless event
+
+        model_class = model_class_name.constantize
+
+        # Build a CommandResult-like structure from the event
+        result = build_result_from_event(event, operation)
+
+        # Project to model table
+        ModelProjection.project(model_class, operation.to_sym, result)
+      end
+
+      private
+
+      def load_event(event_id)
+        Lyra.config.event_store.read.event(event_id)
+      rescue RubyEventStore::EventNotFound
+        Rails.logger.warn("Lyra::AsyncProjectionJob: Event #{event_id} not found")
+        nil
+      end
+
+      def build_result_from_event(event, operation)
+        # Create a simple struct that looks like CommandResult
+        Struct.new(:events, :attributes, :success?, keyword_init: true).new(
+          events: [event],
+          attributes: event.data[:attributes] || event.data["attributes"] || {},
+          success?: true
+        )
+      end
+    end
+  end
+end