olyx-guardrails 1.0.0

data/lib/olyx/guardrails/pii/message_scrubber.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative '../validation'
+require_relative 'content_scrubber'
+require_relative 'hash_key'
+
+module Olyx
+  module Guardrails
+    module Pii
+      # Preserves chat message shape while redacting String content fields.
+      module MessageScrubber
+        module_function
+
+        def call(messages)
+          Validation.array_of!(messages, Hash, name: 'messages')
+          results = messages.map { |message| scrub_message(message) }
+          { messages: results.map(&:first), detected: results.any?(&:last) }
+        end
+
+        def scrub_message(message)
+          key = HashKey.call(message, 'content')
+          return [message, false] unless key
+
+          redacted, changed = ContentScrubber.call(message[key])
+          [changed ? message.merge(key => redacted) : message, changed]
+        end
+        private_class_method :scrub_message
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/pii/named_date_validator.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require 'date'
+
+module Olyx
+  module Guardrails
+    module Pii
+      # Validates English abbreviated or full month dates.
+      module NamedDateValidator
+        FORMATS = ['%B %d, %Y', '%B %d %Y', '%b %d, %Y', '%b %d %Y'].freeze
+
+        module_function
+
+        def call(value)
+          FORMATS.any? { |format| valid?(value.delete('.'), format) }
+        end
+
+        def valid?(value, format)
+          Date.strptime(value, format)
+          true
+        rescue Date::Error
+          false
+        end
+        private_class_method :valid?
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/pii/numeric_date_validator.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require_relative 'ambiguous_numeric_date'
+require_relative 'year_first_date'
+
+module Olyx
+  module Guardrails
+    module Pii
+      # Validates year-first or ambiguous day/month numeric dates.
+      module NumericDateValidator
+        PARTS = %r{\A(\d{1,4})[/-](\d{1,2})[/-](\d{1,4})\z}
+
+        module_function
+
+        def call(value)
+          parts = value.match(PARTS)&.captures
+          return false unless parts
+
+          return YearFirstDate.call(parts) if parts.first.length == 4
+
+          AmbiguousNumericDate.call(parts)
+        end
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/pii/pattern_catalog.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require_relative '../pii_validators'
+
+module Olyx
+  module Guardrails
+    module Pii
+      # Declarative PII pattern, replacement, and validator catalog.
+      module PatternCatalog
+        EMAIL = /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/
+        PHONE = /(?<!\d)(?:(?:\+|00)\d(?:[\s\-.]?\d){7,15}|\(?\d{3}\)?[\s\-.]\d{3}[\s\-.]\d{4})(?!\d)/
+        SSN = /\b\d{3}[- ]\d{2}[- ]\d{4}\b/
+        # Canadian Social Insurance Number: 9 digits, Luhn-checksummed like a
+        # card number, so (unlike SSN) it's not gated on a keyword — the
+        # checksum alone keeps false positives in line with CARD below.
+        SIN = /\b\d{3}[\s-]?\d{3}[\s-]?\d{3}\b/
+        CARD = /\b\d(?:[ -]?\d){12,18}\b/
+        IPV4 = /\b(?:\d{1,3}\.){3}\d{1,3}\b/
+        IPV6 = /(?<![A-Fa-f0-9:])(?:[A-Fa-f0-9]{0,4}:){2,7}[A-Fa-f0-9]{0,4}(?![A-Fa-f0-9:])/
+        TOKEN = /\b(?:Bearer\s+|sk-|ak_live_|fy-ent-)[A-Za-z0-9._-]{8,}\b/i
+        PASSPORT = /\b(?:passport(?:\s+(?:no|number|#))?[\s:]+)([A-Z]{1,2}\d{6,9})\b/i
+        IBAN = /\b(?:[A-Z]{2}\d{2}[A-Z0-9]{11,30}|[A-Z]{2}\d{2}(?: [A-Z0-9]{4}){2,7}(?: [A-Z0-9]{1,3})?)\b/
+        DOB = %r{\b(?:dob|date\s+of\s+birth|born\s+on|birthday)[\s:]+(?:\d{1,2}[/-]\d{1,2}[/-]\d{2,4}|\d{4}[/-]\d{1,2}[/-]\d{1,2}|(?:Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)[a-z]*\.?\s+\d{1,2},?\s+\d{4})}ix
+
+        ENTRIES = [
+          [EMAIL, '[EMAIL]'],
+          [SSN, '[SSN]', ->(value) { PiiValidators.ssn_valid?(value) }],
+          [SIN, '[SIN]', ->(value) { PiiValidators.sin_valid?(value) }],
+          [PASSPORT, '[PASSPORT]'],
+          [IBAN, '[IBAN]', ->(value) { PiiValidators.iban_valid?(value) }],
+          [DOB, '[DOB]', ->(value) { PiiValidators.date_valid?(value) }],
+          [IPV4, '[IP]', ->(value) { PiiValidators.ipv4_valid?(value) }],
+          [IPV6, '[IP]', ->(value) { PiiValidators.ipv6_valid?(value) }],
+          [TOKEN, '[TOKEN]'],
+          [CARD, '[CARD]', ->(value) { PiiValidators.luhn_valid?(value) }],
+          [PHONE, '[PHONE]']
+        ].freeze
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/pii/sin_validator.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require_relative 'luhn_checksum'
+
+module Olyx
+  module Guardrails
+    module Pii
+      # Validates Canadian Social Insurance Numbers with the same Luhn
+      # checksum as card numbers, but at SIN's fixed 9-digit length —
+      # {LuhnValidator} enforces its own 13-digit floor for card use, so this
+      # applies SIN's length rule against the shared {LuhnChecksum} directly.
+      module SinValidator
+        LENGTH = 9
+
+        module_function
+
+        def call(sin)
+          digits = LuhnChecksum.digits(sin)
+          digits.length == LENGTH && LuhnChecksum.valid?(digits)
+        end
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/pii/ssn_validator.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Olyx
+  module Guardrails
+    module Pii
+      # Rejects structurally impossible U.S. Social Security numbers.
+      module SsnValidator
+        INVALID_AREA = /\A(?:000|666|9\d{2})\z/
+
+        module_function
+
+        def call(ssn)
+          area, group, serial = ssn.split(/[- ]/)
+          return false unless area && group && serial
+
+          !area.match?(INVALID_AREA) && group != '00' && serial != '0000'
+        end
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/pii/text_scrubber.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require_relative 'pattern_catalog'
+
+module Olyx
+  module Guardrails
+    module Pii
+      # Redacts recognized PII from one String.
+      module TextScrubber
+        module_function
+
+        def call(text)
+          return text unless text.is_a?(String)
+
+          PatternCatalog::ENTRIES.reduce(text) { |output, entry| replace(output, entry) }
+        end
+
+        def replace(text, entry)
+          pattern, replacement, validator = entry
+          return text.gsub(pattern, replacement) unless validator
+
+          text.gsub(pattern) { |match| validator.call(match) ? replacement : match }
+        end
+        private_class_method :replace
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/pii/year_first_date.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require 'date'
+
+module Olyx
+  module Guardrails
+    module Pii
+      # Validates numeric dates whose first component is a four-digit year.
+      module YearFirstDate
+        module_function
+
+        def call(parts)
+          Date.valid_date?(*parts.map(&:to_i))
+        end
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/pii_scrubber.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require_relative 'pii/message_scrubber'
+require_relative 'pii/text_scrubber'
+
+module Olyx
+  module Guardrails
+    # Stable facade for free-text and chat-message PII redaction.
+    class PiiScrubber
+      def self.scrub(text)
+        Pii::TextScrubber.call(text)
+      end
+
+      def self.scrub_messages(messages)
+        scrub_messages_with_detection(messages)[:messages]
+      end
+
+      def self.scrub_messages_with_detection(messages)
+        Pii::MessageScrubber.call(messages)
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/pii_validators.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require_relative 'pii/iban_validator'
+require_relative 'pii/date_validator'
+require_relative 'pii/ipv4_validator'
+require_relative 'pii/ipv6_validator'
+require_relative 'pii/luhn_validator'
+require_relative 'pii/ssn_validator'
+require_relative 'pii/sin_validator'
+
+module Olyx
+  module Guardrails
+    # Stable facade over format-specific PII validators.
+    module PiiValidators
+      module_function
+
+      def luhn_valid?(value) = Pii::LuhnValidator.call(value)
+      def ssn_valid?(value) = Pii::SsnValidator.call(value)
+      def ipv4_valid?(value) = Pii::Ipv4Validator.call(value)
+      def ipv6_valid?(value) = Pii::Ipv6Validator.call(value)
+      def iban_valid?(value) = Pii::IbanValidator.call(value)
+      def date_valid?(value) = Pii::DateValidator.call(value)
+      def sin_valid?(value) = Pii::SinValidator.call(value)
+    end
+  end
+end

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

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require_relative '../enum_value'
+
+module Olyx
+  module Guardrails
+    module PolicyComponents
+      # Validates analyzer failure behavior.
+      AiFailureMode = EnumValue.new(
+        allowed: %i[allow block raise],
+        error: 'policy ai_failure_mode must be allow, block, or raise'
+      )
+    end
+  end
+end

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

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require_relative '../validation'
+require_relative 'ai_failure_mode'
+require_relative 'name'
+require_relative 'rule_collection'
+require_relative 'secret_pattern_collection'
+
+module Olyx
+  module Guardrails
+    module PolicyComponents
+      # Validated policy identity and bounded input limit.
+      class IdentityConfiguration
+        attr_reader :name, :max_input_length
+
+        def initialize(name, max_input_length)
+          @name = Name.call(name)
+          @max_input_length = Validation.non_negative_integer!(max_input_length, name: 'policy max_input_length')
+          freeze
+        end
+      end
+
+      # Validated built-in blocking switches.
+      class BlockingConfiguration
+        def initialize(pii, injections, secrets)
+          @pii = Validation.boolean!(pii, name: 'policy block_pii')
+          @injections = Validation.boolean!(injections, name: 'policy block_injections')
+          @secrets = Validation.boolean!(secrets, name: 'policy block_secrets')
+          freeze
+        end
+
+        def pii? = @pii
+        def injections? = @injections
+        def secrets? = @secrets
+      end
+
+      # Validated analyzer, secret, and restricted-content configuration.
+      class RestrictionConfiguration
+        attr_reader :ai_failure_mode, :secret_patterns, :rules
+
+        def initialize(ai_failure_mode, secret_patterns, rules)
+          @ai_failure_mode = AiFailureMode.call(ai_failure_mode)
+          @secret_patterns = SecretPatternCollection.call(secret_patterns)
+          @rules = RuleCollection.call(rules)
+          freeze
+        end
+      end
+
+      # Composes independent immutable policy configuration sections.
+      class Configuration
+        attr_reader :identity, :blocking, :restrictions
+
+        def initialize(identity:, blocking:, restrictions:)
+          @identity = IdentityConfiguration.new(*identity)
+          @blocking = BlockingConfiguration.new(*blocking)
+          @restrictions = RestrictionConfiguration.new(*restrictions)
+          freeze
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Olyx
+  module Guardrails
+    module PolicyComponents
+      # Normalizes String/Symbol keyed policy configuration hashes.
+      module ConfigurationHash
+        module_function
+
+        def call(config)
+          raise ArgumentError, 'policy configuration must be a Hash' unless config.is_a?(Hash)
+
+          config.to_h { |key, value| [key.to_sym, value] }
+        rescue NoMethodError
+          raise ArgumentError, 'policy configuration keys must be Strings or Symbols'
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Olyx
+  module Guardrails
+    module PolicyComponents
+      # Defines policy finding identity and deterministic ordering.
+      module FindingOrder
+        module_function
+
+        def identity(finding)
+          [finding[:rule].name, finding[:start], finding[:end]]
+        end
+
+        def key(finding)
+          [finding[:start], finding[:end], finding[:rule_index]]
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require 'digest'
+
+module Olyx
+  module Guardrails
+    module PolicyComponents
+      # Converts private policy matches to masked public findings.
+      module FindingPresenter
+        module_function
+
+        def call(findings)
+          findings.map { |finding| present(finding) }
+        end
+
+        def present(finding)
+          rule = finding[:rule]
+          identity(rule, finding).merge(location(finding)).compact
+        end
+
+        def identity(rule, finding)
+          {
+            rule: rule.name,
+            description: rule.description,
+            blocked: rule.block?,
+            matched: '[REDACTED]',
+            fingerprint: "sha256:#{Digest::SHA256.hexdigest(finding[:full])[0, 12]}"
+          }
+        end
+
+        def location(finding)
+          {
+            start: finding[:start],
+            end: finding[:end]
+          }
+        end
+        private_class_method :identity, :location, :present
+      end
+    end
+  end
+end

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

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative 'finding_order'
+require_relative 'rule_matcher'
+
+module Olyx
+  module Guardrails
+    module PolicyComponents
+      # Collects, deduplicates, and orders private policy matches.
+      module MatchCollector
+        module_function
+
+        def call(source, rules)
+          findings = rules.each_with_index.flat_map { |rule, index| RuleMatcher.call(source, rule, index) }
+          findings.uniq { |finding| FindingOrder.identity(finding) }.sort_by { |finding| FindingOrder.key(finding) }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Olyx
+  module Guardrails
+    module PolicyComponents
+      # Validates and freezes an operator-facing policy identifier.
+      module Name
+        module_function
+
+        def call(value)
+          return value.dup.freeze if valid?(value)
+
+          raise ArgumentError, 'policy name must be a String of 1..100 characters'
+        end
+
+        def valid?(value)
+          value.is_a?(String) && !value.strip.empty? && value.length <= 100
+        end
+        private_class_method :valid?
+      end
+    end
+  end
+end

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

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative '../text/mapped_normalization'
+
+module Olyx
+  module Guardrails
+    module PolicyComponents
+      # Finds normalized policy matches and maps them to original offsets.
+      module NormalizedPatternMatcher
+        module_function
+
+        def call(source, rule, index, pattern)
+          mapped = Text::MappedNormalization.new(source)
+          return [] unless mapped.changed?
+
+          findings(source, mapped, rule, index, pattern)
+        end
+
+        def findings(source, mapped, rule, index, pattern)
+          mapped.text.to_enum(:scan, pattern).map do
+            match = Regexp.last_match
+            finding(source, mapped, rule, index, match)
+          end
+        end
+
+        def finding(source, mapped, rule, index, match)
+          starting, ending = mapped.original_span(match.begin(0), match.end(0))
+          { rule: rule, rule_index: index, full: source[starting...ending], start: starting, end: ending }
+        end
+        private_class_method :finding, :findings
+      end
+    end
+  end
+end

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

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Olyx
+  module Guardrails
+    module PolicyComponents
+      # Enumerates private offsets for one compiled policy pattern.
+      module PatternMatcher
+        module_function
+
+        def call(source, rule, index, pattern)
+          source.to_enum(:scan, pattern).map do
+            match = Regexp.last_match
+            { rule: rule, rule_index: index, full: match[0].to_s, start: match.begin(0), end: match.end(0) }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Olyx
+  module Guardrails
+    module PolicyComponents
+      # Presents policy matches and their redacted output.
+      module RedactionResult
+        module_function
+
+        def call(source, findings, transform)
+          {
+            text: PolicyRedactor.call(source, findings, transform: transform),
+            violated: findings.any?,
+            findings: FindingPresenter.call(findings)
+          }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Olyx
+  module Guardrails
+    module PolicyComponents
+      # Merges overlapping policy findings while preserving the first rule.
+      module RedactionSpans
+        module_function
+
+        def call(findings)
+          findings.each_with_object([]) { |finding, spans| append(spans, finding) }
+        end
+
+        def append(spans, finding)
+          previous = spans.last
+          return spans << span(finding) unless overlaps?(previous, finding)
+
+          previous[:end] = [previous[:end], finding[:end]].max
+        end
+
+        def overlaps?(previous, finding)
+          previous && finding[:start] < previous[:end]
+        end
+
+        def span(finding)
+          { start: finding[:start], end: finding[:end], replacement: finding[:rule].replacement }
+        end
+        private_class_method :append, :overlaps?, :span
+      end
+    end
+  end
+end

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

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative '../policy_rule'
+require_relative 'configuration_hash'
+require_relative 'rule_normalizer'
+
+module Olyx
+  module Guardrails
+    module PolicyComponents
+      # Normalizes policy rules and enforces unique identifiers.
+      module RuleCollection
+        module_function
+
+        def call(values)
+          validate_collection!(values)
+
+          rules = values.map { |value| RuleNormalizer.call(value) }
+          validate_unique_names!(rules)
+          rules.freeze
+        end
+
+        def validate_collection!(values)
+          raise ArgumentError, RuleNormalizer::ERROR unless values.is_a?(Array)
+        end
+
+        def validate_unique_names!(rules)
+          names = rules.map(&:name)
+          raise ArgumentError, 'policy rule names must be unique' unless names.uniq.length == names.length
+        end
+        private_class_method :validate_collection!, :validate_unique_names!
+      end
+    end
+  end
+end

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

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative 'pattern_matcher'
+require_relative 'normalized_pattern_matcher'
+
+module Olyx
+  module Guardrails
+    module PolicyComponents
+      # Collects original and normalized matches for one policy rule.
+      module RuleMatcher
+        TIMEOUT_ERROR = defined?(Regexp::TimeoutError) ? Regexp::TimeoutError : RegexpError
+
+        module_function
+
+        def call(source, rule, index)
+          rule.patterns.flat_map { |pattern| matches(source, rule, index, pattern) }
+        rescue TIMEOUT_ERROR
+          raise ArgumentError, "policy rule #{rule.name.inspect} timed out"
+        end
+
+        def matches(source, rule, index, pattern)
+          PatternMatcher.call(source, rule, index, pattern) +
+            NormalizedPatternMatcher.call(source, rule, index, pattern)
+        end
+        private_class_method :matches
+      end
+    end
+  end
+end

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

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Olyx
+  module Guardrails
+    module PolicyComponents
+      # Converts policy rule Hashes into immutable PolicyRule values.
+      module RuleNormalizer
+        ERROR = 'policy rules must be an Array of PolicyRule or Hash values'
+
+        module_function
+
+        def call(value)
+          return value if value.is_a?(PolicyRule)
+          return PolicyRule.new(**ConfigurationHash.call(value)) if value.is_a?(Hash)
+
+          raise ArgumentError, ERROR
+        end
+      end
+    end
+  end
+end