olyx-guardrails 1.0.0

data/lib/olyx/guardrails/policy/scan_result.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Olyx
+  module Guardrails
+    module PolicyComponents
+      # Presents policy matches as a scan decision.
+      module ScanResult
+        module_function
+
+        def call(findings)
+          violated = findings.any?
+          {
+            violated: violated,
+            blocked: violated && findings.any? { |finding| finding[:rule].block? },
+            findings: FindingPresenter.call(findings)
+          }
+        end
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/policy/secret_pattern_collection.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require_relative '../secret_scanner'
+require_relative '../validation'
+
+module Olyx
+  module Guardrails
+    module PolicyComponents
+      # Validates custom secret patterns once during policy construction.
+      module SecretPatternCollection
+        module_function
+
+        def call(values)
+          Validation.array_of!(values, String, name: 'policy secret_patterns')
+          patterns = values.map { |pattern| pattern.dup.freeze }.freeze
+          SecretScanner.scan('', custom_patterns: patterns)
+          patterns
+        end
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/policy/unmatched_segment_builder.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Olyx
+  module Guardrails
+    module PolicyComponents
+      # Accumulates transformed gaps and fixed policy replacements in source order.
+      class UnmatchedSegmentBuilder
+        def initialize(source, transform)
+          @source = source
+          @transform = transform
+          @cursor = 0
+          @parts = []
+        end
+
+        def append(span)
+          @parts << @transform.call(@source[@cursor...span[:start]])
+          @parts << span[:replacement]
+          @cursor = span[:end]
+        end
+
+        def finish
+          @parts << @transform.call(@source[@cursor..])
+          @parts.join
+        end
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/policy/unmatched_transformer.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative 'unmatched_segment_builder'
+
+module Olyx
+  module Guardrails
+    module PolicyComponents
+      # Applies a secondary transformation only outside policy spans.
+      module UnmatchedTransformer
+        module_function
+
+        def call(source, spans, transform)
+          builder = UnmatchedSegmentBuilder.new(source, transform)
+          spans.each { |span| builder.append(span) }
+          builder.finish
+        end
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/policy.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require_relative 'policy/configuration_hash'
+require_relative 'policy/configuration'
+
+module Olyx
+  module Guardrails
+    # Immutable enforcement configuration for decisions and transformations.
+    class Policy
+      def self.default
+        @default ||= new
+      end
+
+      def self.from_h(config)
+        new(**PolicyComponents::ConfigurationHash.call(config))
+      end
+
+      def initialize(
+        name: 'default',
+        max_input_length: 10_000,
+        block_pii: false,
+        block_injections: true,
+        block_secrets: false,
+        ai_failure_mode: :allow,
+        secret_patterns: [],
+        rules: []
+      )
+        @configuration = PolicyComponents::Configuration.new(
+          identity: [name, max_input_length],
+          blocking: [block_pii, block_injections, block_secrets],
+          restrictions: [ai_failure_mode, secret_patterns, rules]
+        )
+        freeze
+      end
+
+      def name = @configuration.identity.name
+      def max_input_length = @configuration.identity.max_input_length
+      def ai_failure_mode = @configuration.restrictions.ai_failure_mode
+      def secret_patterns = @configuration.restrictions.secret_patterns
+      def rules = @configuration.restrictions.rules
+      def block_pii? = @configuration.blocking.pii?
+      def block_injections? = @configuration.blocking.injections?
+      def block_secrets? = @configuration.blocking.secrets?
+    end
+  end
+end

data/lib/olyx/guardrails/policy_aware_redactor.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require_relative 'pii_scrubber'
+require_relative 'policy_scanner'
+require_relative 'secret_scanner'
+require_relative 'redaction/content_result'
+require_relative 'redaction/unrestricted_text'
+
+module Olyx
+  # Guardrail policy types and evaluation services.
+  module Guardrails
+    # Produces one policy-aware redaction result while preserving findings from
+    # the original source. Policy spans take precedence over narrower scanner
+    # substitutions; confidentiality markers remain fail-closed.
+    class PolicyAwareRedactor
+      def self.call(source, policy:)
+        new(source, policy).call
+      end
+
+      def initialize(source, policy)
+        @source = source.to_s
+        @policy = policy
+      end
+
+      def call
+        secret_scan = SecretScanner.scan(
+          @source,
+          custom_patterns: @policy.secret_patterns
+        )
+        policy_redaction = PolicyScanner.redact(@source, policy: @policy) do |text|
+          Redaction::UnrestrictedText.call(text, @policy)
+        end
+
+        Redaction::ContentResult.call(
+          @source, text: policy_redaction[:text], secret_scan: secret_scan, policy_redaction: policy_redaction
+        )
+      end
+    end
+
+    private_constant :PolicyAwareRedactor
+  end
+end

data/lib/olyx/guardrails/policy_redactor.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require_relative 'policy/redaction_spans'
+require_relative 'policy/unmatched_transformer'
+
+module Olyx
+  # Policy-driven safety checks and redaction for Ruby applications.
+  module Guardrails
+    # Applies offset-aware replacements for private policy findings.
+    class PolicyRedactor
+      def self.call(source, findings, transform: nil)
+        spans = PolicyComponents::RedactionSpans.call(findings)
+        return PolicyComponents::UnmatchedTransformer.call(source, spans, transform) if transform
+
+        replace(source, spans)
+      end
+
+      def self.replace(source, spans)
+        spans.reverse_each.with_object(source.dup) do |span, output|
+          output[span[:start]...span[:end]] = span[:replacement]
+        end
+      end
+      private_class_method :replace
+    end
+
+    private_constant :PolicyRedactor
+  end
+end

data/lib/olyx/guardrails/policy_rule/configuration.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require_relative 'match_mode'
+require_relative 'pattern_compiler'
+require_relative 'values'
+
+module Olyx
+  module Guardrails
+    module PolicyRuleComponents
+      # Validated identity and descriptive policy-rule fields.
+      class IdentityConfiguration
+        attr_reader :name, :description
+
+        def initialize(name, description)
+          @name = Values.name(name)
+          @description = Values.description(description)
+          freeze
+        end
+      end
+
+      # Validated policy-rule matching configuration.
+      class MatchConfiguration
+        attr_reader :mode, :patterns
+
+        def initialize(patterns, terms, match)
+          @mode = MatchMode.call(match)
+          @patterns = PatternCompiler.call(patterns: patterns, terms: terms, match: @mode)
+          freeze
+        end
+      end
+
+      # Validated policy-rule enforcement behavior.
+      class EnforcementConfiguration
+        attr_reader :replacement
+
+        def initialize(block, replacement)
+          @block = Values.boolean(block)
+          @replacement = Values.replacement(replacement)
+          freeze
+        end
+
+        def block? = @block
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/policy_rule/description_value.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Olyx
+  module Guardrails
+    module PolicyRuleComponents
+      # Validates an optional human-readable rule description.
+      module DescriptionValue
+        module_function
+
+        def call(value)
+          return nil if value.nil?
+          return value.dup.freeze if valid?(value)
+
+          raise ArgumentError, 'policy rule description must be a String of 1..500 characters or nil'
+        end
+
+        def valid?(value)
+          value.is_a?(String) && !value.strip.empty? && value.length <= 500
+        end
+        private_class_method :valid?
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/policy_rule/match_mode.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require_relative '../enum_value'
+
+module Olyx
+  module Guardrails
+    module PolicyRuleComponents
+      # Validates how configured terms are interpreted.
+      MatchMode = EnumValue.new(
+        allowed: %i[substring whole_word regexp],
+        error: 'policy rule match must be substring, whole_word, or regexp'
+      )
+    end
+  end
+end

data/lib/olyx/guardrails/policy_rule/name_value.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Olyx
+  module Guardrails
+    module PolicyRuleComponents
+      # Validates and freezes a policy-rule identifier.
+      module NameValue
+        FORMAT = /\A[a-z][a-z0-9_.:-]*\z/i
+
+        module_function
+
+        def call(value)
+          normalized = value.to_s
+          valid = (value.is_a?(String) || value.is_a?(Symbol)) && normalized.match?(FORMAT)
+          raise ArgumentError, 'policy rule name must be a String or Symbol identifier' unless valid
+
+          normalized.dup.freeze
+        end
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/policy_rule/pattern_compiler.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require_relative 'regexp_compiler'
+require_relative 'term_compiler'
+
+module Olyx
+  module Guardrails
+    module PolicyRuleComponents
+      # Compiles bounded policy regexes and rejects empty matching patterns.
+      module PatternCompiler
+        module_function
+
+        def call(patterns:, terms:, match:)
+          validate_collections!(patterns, terms)
+          compiled = patterns.map { |value| RegexpCompiler.call(value) }
+          compiled.concat(terms.map { |term| TermCompiler.call(term, mode: match) }).freeze
+        end
+
+        def validate_collections!(patterns, terms)
+          valid = patterns.is_a?(Array) && terms.is_a?(Array) && !(patterns.empty? && terms.empty?)
+          raise ArgumentError, 'policy rule patterns or terms must be a non-empty Array' unless valid
+        end
+
+        private_class_method :validate_collections!
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/policy_rule/regexp_compiler.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Olyx
+  module Guardrails
+    module PolicyRuleComponents
+      # Compiles bounded regular-expression policy patterns.
+      module RegexpCompiler
+        TIMEOUT = 0.1
+
+        module_function
+
+        def call(value)
+          pattern = build(value)
+          raise ArgumentError, 'policy rule patterns must not match empty text' if pattern.match?('')
+
+          pattern
+        rescue RegexpError => error
+          raise ArgumentError, "invalid policy rule pattern #{value.inspect}: #{error.message}"
+        end
+
+        def build(value)
+          return Regexp.new(value, Regexp::IGNORECASE, timeout: TIMEOUT) if value.is_a?(String)
+          return Regexp.new(value.source, value.options, timeout: TIMEOUT) if value.is_a?(Regexp)
+
+          raise ArgumentError, 'policy rule patterns must contain only Strings or Regexps'
+        end
+        private_class_method :build
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/policy_rule/replacement_value.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Olyx
+  module Guardrails
+    module PolicyRuleComponents
+      # Validates a bounded single-line rule replacement.
+      module ReplacementValue
+        module_function
+
+        def call(value)
+          return value.dup.freeze if valid?(value)
+
+          raise ArgumentError, 'policy rule replacement must be a single-line String of 1..100 characters'
+        end
+
+        def valid?(value)
+          value.is_a?(String) && bounded?(value) && single_line?(value)
+        end
+
+        def bounded?(value) = !value.empty? && value.length <= 100
+        def single_line?(value) = !value.match?(/[\r\n\t]/)
+        private_class_method :bounded?, :single_line?, :valid?
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/policy_rule/term_compiler.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative 'regexp_compiler'
+
+module Olyx
+  module Guardrails
+    module PolicyRuleComponents
+      # Compiles literal terms without exposing regex semantics.
+      module TermCompiler
+        module_function
+
+        def call(term, mode:)
+          validate!(term)
+          return RegexpCompiler.call(term) if mode == :regexp
+
+          Regexp.new(source(term, mode), Regexp::IGNORECASE, timeout: RegexpCompiler::TIMEOUT)
+        end
+
+        def source(term, mode)
+          escaped = Regexp.escape(term)
+          mode == :whole_word ? "(?<![[:alnum:]_])#{escaped}(?![[:alnum:]_])" : escaped
+        end
+
+        def validate!(term)
+          return if term.is_a?(String) && !term.empty?
+
+          raise ArgumentError, 'policy rule terms must contain only non-empty Strings'
+        end
+        private_class_method :source, :validate!
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/policy_rule/text_values.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require_relative 'description_value'
+require_relative 'replacement_value'
+
+module Olyx
+  module Guardrails
+    module PolicyRuleComponents
+      # Validates human-readable rule description and replacement values.
+      module TextValues
+        module_function
+
+        def description(value)
+          DescriptionValue.call(value)
+        end
+
+        def replacement(value)
+          ReplacementValue.call(value)
+        end
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/policy_rule/values.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative 'name_value'
+require_relative 'text_values'
+
+module Olyx
+  module Guardrails
+    module PolicyRuleComponents
+      # Validates non-pattern policy-rule values.
+      module Values
+        module_function
+
+        def name(value)
+          NameValue.call(value)
+        end
+
+        def boolean(value)
+          return value if [true, false].include?(value)
+
+          raise ArgumentError, 'policy rule block must be true or false'
+        end
+
+        def description(value)
+          TextValues.description(value)
+        end
+
+        def replacement(value)
+          TextValues.replacement(value)
+        end
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/policy_rule.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative 'policy_rule/configuration'
+
+module Olyx
+  module Guardrails
+    # Immutable named restricted-content rule.
+    class PolicyRule
+      def initialize(name:, patterns: [], terms: [], match: :substring, block: true, description: nil, replacement: nil)
+        @identity = PolicyRuleComponents::IdentityConfiguration.new(name, description)
+        @matching = PolicyRuleComponents::MatchConfiguration.new(patterns, terms, match)
+        @enforcement = PolicyRuleComponents::EnforcementConfiguration.new(block, replacement || default_replacement)
+        freeze
+      end
+
+      def name = @identity.name
+      def description = @identity.description
+      def match = @matching.mode
+      def patterns = @matching.patterns
+      def replacement = @enforcement.replacement
+      def block? = @enforcement.block?
+
+      private
+
+      def default_replacement
+        "[RESTRICTED:#{@identity.name.upcase}]"
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/policy_scanner.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require_relative 'policy/finding_presenter'
+require_relative 'policy/match_collector'
+require_relative 'policy/redaction_result'
+require_relative 'policy/scan_result'
+require_relative 'policy_redactor'
+
+module Olyx
+  # Policy-driven safety checks and redaction for Ruby applications.
+  module Guardrails
+    # Presents restricted-content decisions while keeping matched text private.
+    class PolicyScanner
+      def self.scan(text, policy:)
+        new(text, policy).scan
+      end
+
+      def self.redact(text, policy:, &transform)
+        new(text, policy).redact(&transform)
+      end
+
+      def initialize(text, policy)
+        @source = text.to_s
+        @policy = policy
+      end
+
+      def scan
+        PolicyComponents::ScanResult.call(raw_findings)
+      end
+
+      def redact(&transform)
+        PolicyComponents::RedactionResult.call(@source, raw_findings, transform)
+      end
+
+      private
+
+      def raw_findings
+        PolicyComponents::MatchCollector.call(@source, @policy.rules)
+      end
+    end
+
+    private_constant :PolicyScanner
+  end
+end

data/lib/olyx/guardrails/rails/action_cable.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require_relative 'ingress'
+
+module Olyx
+  module Guardrails
+    module Rails
+      # Opt-in enforcement helpers for Action Cable channel payloads.
+      module ActionCable
+        include Ingress
+
+        private
+
+        alias guardrails_check_cable! guardrails_check_ingress!
+        alias guardrails_check_cable_output! guardrails_check_ingress_output!
+
+        def guardrails_ingress_key = :channel
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/rails/active_job_handler.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative 'job_reference'
+require_relative 'queue_name'
+
+module Olyx
+  module Guardrails
+    module Rails
+      # Adapts immutable notification events to any Active Job-compatible job.
+      class ActiveJobHandler
+        def initialize(job:, queue: nil)
+          @job = JobReference.new(job)
+          @queue = QueueName.call(queue)
+          freeze
+        end
+
+        def call(event)
+          raise ArgumentError, 'Active Job notification event must be a Hash' unless event.is_a?(Hash)
+
+          target = @job.resolve
+          target = target.set(queue: @queue) if @queue
+          target.perform_later(event)
+        end
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/rails/active_model_validator.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require 'active_model'
+
+# Explicit Active Model validator for AI-bound text attributes.
+class OlyxGuardrailsValidator < ActiveModel::EachValidator
+  def validate_each(record, attribute, value)
+    result = evaluate(record, attribute, value)
+    return if result[:allowed]
+
+    record.errors.add(attribute, options.fetch(:message, 'was rejected by guardrail policy'))
+  end
+
+  private
+
+  def evaluate(record, attribute, value)
+    policy = options[:policy]
+    return Olyx::Guardrails.check(value, policy: policy) if policy
+
+    metadata = { model: record.class.name, attribute: attribute }
+    Olyx::Guardrails::Rails.check(value, metadata: metadata)
+  end
+end

data/lib/olyx/guardrails/rails/check_telemetry.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative 'instrumentation'
+
+module Olyx
+  module Guardrails
+    module Rails
+      # Publishes check and violation telemetry from one decision summary.
+      module CheckTelemetry
+        module_function
+
+        def call(result, duration)
+          Instrumentation.publish_check(result, duration)
+          Instrumentation.publish_violation(result, duration) if result[:risk_score].to_f.positive?
+        end
+      end
+    end
+  end
+end