olyx-guardrails 1.0.0

data/lib/olyx/guardrails/risk/ai_score.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Olyx
+  module Guardrails
+    module Risk
+      # Coerces an optional analyzer score into the supported range.
+      module AiScore
+        module_function
+
+        def call(result)
+          return unless result
+
+          score = Float(result[:risk_score], exception: false)
+          score.clamp(0.0, 1.0) if score&.finite?
+        end
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/risk/check_weights.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require_relative 'weights'
+
+module Olyx
+  module Guardrails
+    module Risk
+      # Sums risk weights for positive deterministic findings.
+      module CheckWeights
+        module_function
+
+        def call(checks)
+          Weights::FINDINGS.sum { |check, (finding, weight)| checks[check][finding] ? weight : 0.0 }
+        end
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/risk/deterministic_score.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative 'check_weights'
+
+module Olyx
+  module Guardrails
+    module Risk
+      # Computes the bounded score contributed by deterministic checks.
+      module DeterministicScore
+        module_function
+
+        def call(checks, ordered_checks)
+          score = CheckWeights.call(checks)
+          score += BLOCKED_RISK_WEIGHT if ordered_checks.any? { |check| !check[:allowed] }
+          score.clamp(0.0, 1.0).round(4)
+        end
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/risk/weights.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Olyx
+  module Guardrails
+    module Risk
+      # Owns the deterministic risk model shared by scoring and the public API.
+      module Weights
+        FINDINGS = {
+          injection: [:injection_attempt, 0.50],
+          secret: [:leaked, 0.25],
+          pii: [:detected, 0.10],
+          policy: [:violated, 0.25]
+        }.freeze
+        BLOCKED = 0.15
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/risk_scorer.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require_relative 'risk/ai_score'
+require_relative 'risk/deterministic_score'
+
+module Olyx
+  module Guardrails
+    # Computes the bounded heuristic risk score from merged check results and
+    # an optional analyzer score.
+    class RiskScorer
+      def self.call(checks, ordered_checks, ai_result)
+        new(checks, ordered_checks, ai_result).call
+      end
+
+      def initialize(checks, ordered_checks, ai_result)
+        @checks = checks
+        @ordered_checks = ordered_checks
+        @ai_result = ai_result
+      end
+
+      def call
+        deterministic = Risk::DeterministicScore.call(@checks, @ordered_checks)
+        ai_risk = Risk::AiScore.call(@ai_result)
+        ai_risk ? [deterministic, ai_risk].max.round(4) : deterministic
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/secret_finding_collector.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative 'secrets/custom_pattern_source'
+require_relative 'secrets/catalog_source'
+require_relative 'secrets/confidentiality_source'
+require_relative 'secrets/internal_endpoint_source'
+require_relative 'secrets/finding_order'
+require_relative 'secrets/source_set'
+require_relative 'secrets/normalized_source_set'
+
+module Olyx
+  module Guardrails
+    # Coordinates independent private secret-finding sources.
+    class SecretFindingCollector
+      def self.call(source, custom_patterns: [])
+        new(source.to_s, custom_patterns).call
+      end
+
+      def initialize(source, custom_patterns)
+        @source = source
+        @custom_patterns = custom_patterns
+      end
+
+      def call
+        findings = Secrets::SourceSet.call(@source, @custom_patterns) +
+                   Secrets::NormalizedSourceSet.call(@source, @custom_patterns)
+        Secrets::FindingOrder.call(findings)
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/secret_scanner.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require_relative 'secret_finding_collector'
+require_relative 'secrets/finding_presenter'
+require_relative 'secrets/redactor'
+require_relative 'secrets/blocked'
+
+module Olyx
+  module Guardrails
+    # Public detect, redact, and exception-driven secret operations.
+    class SecretScanner
+      Blocked = Secrets::Blocked
+
+      def self.scan(text, custom_patterns: [])
+        findings = collect(text, custom_patterns)
+        { leaked: findings.any?, findings: Secrets::FindingPresenter.call(findings) }
+      end
+
+      def self.redact(text, custom_patterns: [])
+        source = text.to_s
+        findings = collect(source, custom_patterns)
+        {
+          text: findings.empty? ? source : Secrets::Redactor.call(source, findings),
+          leaked: findings.any?,
+          findings: Secrets::FindingPresenter.call(findings)
+        }
+      end
+
+      def self.scan!(text, custom_patterns: [])
+        result = scan(text, custom_patterns: custom_patterns)
+        raise Blocked, result[:findings] if result[:leaked]
+
+        result
+      end
+
+      def self.collect(text, custom_patterns)
+        SecretFindingCollector.call(text.to_s, custom_patterns: custom_patterns)
+      end
+      private_class_method :collect
+    end
+  end
+end

data/lib/olyx/guardrails/secrets/blocked.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Olyx
+  module Guardrails
+    module Secrets
+      # Raised by SecretScanner.scan! when secret findings make input unsafe.
+      class Blocked < StandardError
+        attr_reader :findings
+
+        def initialize(findings)
+          @findings = findings
+          super('Response blocked: secret leakage detected')
+        end
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/secrets/catalog_source.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require_relative 'pattern_catalog'
+require_relative 'private_network_validator'
+require_relative 'regexp_finding_source'
+
+module Olyx
+  module Guardrails
+    module Secrets
+      # Finds catalog secrets and validates private-network candidates.
+      module CatalogSource
+        module_function
+
+        def call(source)
+          PatternCatalog::SIMPLE.flat_map { |category, pattern| findings(source, category, pattern) }
+        end
+
+        def findings(source, category, pattern)
+          matches = RegexpFindingSource.call(source, category, pattern)
+          return matches unless category == 'private_network_address'
+
+          matches.select { |finding| PrivateNetworkValidator.call(finding[:full]) }
+        end
+        private_class_method :findings
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/secrets/cloud_credential_patterns.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Olyx
+  module Guardrails
+    module Secrets
+      # Cloud and SaaS provider credential patterns.
+      module CloudCredentialPatterns
+        AWS_ACCESS_KEY = /\b(AKIA|ASIA|AROA|ABIA|ACCA|AIPA)[A-Z0-9]{16}\b/
+        AWS_SECRET_KEY = %r{(?:aws[_\-\s]?(?:secret[_\-\s]?)?(?:access[_\-\s]?)?key|secret[_\-\s]access[_\-\s]key)[\s=:"']+([A-Za-z0-9/+=]{40})\b}i
+        STRIPE_KEY = /\b(?:sk|rk)_(?:live|test)_[A-Za-z0-9]{16,}|\bwhsec_[A-Za-z0-9]{16,}/
+        GOOGLE_KEY = /\bAIza[0-9A-Za-z_-]{35}\b|\bGOCSPX-[0-9A-Za-z_-]{20,}\b/
+        AZURE_STORAGE_KEY = %r{(?:AccountKey|SharedAccessKey)=[A-Za-z0-9+/=]{40,}}i
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/secrets/confidentiality_source.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require_relative 'pattern_catalog'
+require_relative 'regexp_finding_source'
+
+module Olyx
+  module Guardrails
+    module Secrets
+      # Finds explicit confidentiality markers.
+      module ConfidentialitySource
+        module_function
+
+        def call(source)
+          PatternCatalog::CONFIDENTIALITY.flat_map do |pattern|
+            RegexpFindingSource.call(source, 'confidentiality_marker', pattern)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/secrets/custom_pattern_compiler.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Olyx
+  module Guardrails
+    module Secrets
+      # Compiles bounded, non-empty custom secret patterns.
+      module CustomPatternCompiler
+        TIMEOUT = 0.1
+
+        module_function
+
+        def call(pattern)
+          compiled = Regexp.new(pattern, Regexp::IGNORECASE, timeout: TIMEOUT)
+          raise ArgumentError, 'custom patterns must not match empty text' if compiled.match?('')
+
+          compiled
+        rescue RegexpError => error
+          raise ArgumentError, "invalid custom pattern #{pattern.inspect}: #{error.message}"
+        end
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/secrets/custom_pattern_source.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative '../validation'
+require_relative 'custom_pattern_compiler'
+require_relative 'regexp_finding_source'
+
+module Olyx
+  module Guardrails
+    module Secrets
+      # Compiles bounded custom patterns and returns their internal findings.
+      module CustomPatternSource
+        TIMEOUT_ERROR = defined?(Regexp::TimeoutError) ? Regexp::TimeoutError : RegexpError
+
+        module_function
+
+        def call(source, patterns)
+          Validation.array_of!(patterns, String, name: 'custom_patterns')
+          patterns.flat_map { |pattern| findings(source, CustomPatternCompiler.call(pattern)) }
+        rescue TIMEOUT_ERROR
+          raise ArgumentError, 'custom pattern timed out'
+        end
+
+        def findings(source, pattern)
+          RegexpFindingSource.call(source, 'custom_pattern', pattern).reject { |finding| finding[:full].empty? }
+        end
+        private_class_method :findings
+      end
+    end
+  end
+end

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

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Olyx
+  module Guardrails
+    module Secrets
+      # Deduplicates and orders secret findings by private offsets and category.
+      module FindingOrder
+        module_function
+
+        def call(findings)
+          key = ->(finding) { [finding[:start], finding[:end], finding[:category]] }
+          findings.uniq(&key).sort_by(&key)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require 'digest'
+
+module Olyx
+  module Guardrails
+    module Secrets
+      # Converts private findings into safe correlation records.
+      module FindingPresenter
+        module_function
+
+        def call(findings)
+          findings.map { |finding| present(finding) }
+        end
+
+        def present(finding)
+          value = finding[:full]
+          {
+            category: finding[:category],
+            matched: mask(value),
+            fingerprint: "sha256:#{Digest::SHA256.hexdigest(value)[0, 12]}",
+            start: finding[:start],
+            end: finding[:end]
+          }
+        end
+
+        def mask(value)
+          value.length < 12 ? '[REDACTED]' : "#{value[0, 4]}…#{value[-4, 4]}"
+        end
+        private_class_method :present, :mask
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/secrets/generic_credential_patterns.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Olyx
+  module Guardrails
+    module Secrets
+      # Provider-independent credential and key material patterns.
+      module GenericCredentialPatterns
+        TOKEN = /\bghp_\w+|\bghs_\w+|\bgho_\w+|\bghr_\w+|\bxoxb-\S+|\bxoxp-\S+|\bxoxs-\S+|\bxoxe-\S+|\bglpat-\w+|\bgldt-\w+|\bnpm_\w+|\bSG\.[A-Za-z0-9._-]{20,}|\bey[A-Za-z0-9._-]{20,}\.[A-Za-z0-9._-]{20,}|\bsk-(?:ant-|proj-)?[A-Za-z0-9_-]{20,}|\bkey-\S+/i
+        JWT = /\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\b/
+        PRIVATE_KEY = /-----BEGIN (?:RSA |EC |OPENSSH |DSA )?PRIVATE KEY-----.*?-----END (?:RSA |EC |OPENSSH |DSA )?PRIVATE KEY-----/m
+        DATABASE_URL = %r{\b(?:postgres(?:ql)?|mysql|mongodb(?:\+srv)?|redis|amqp)://[^\s:@/]+:[^\s@/]+@[^\s]+}i
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/secrets/internal_endpoint_source.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require_relative 'network_patterns'
+
+module Olyx
+  module Guardrails
+    module Secrets
+      # Expands internal-host suffix matches to the complete endpoint token.
+      module InternalEndpointSource
+        module_function
+
+        def call(source)
+          source.to_enum(:scan, NetworkPatterns::INTERNAL_SUFFIX).map do
+            finding(source, Regexp.last_match)
+          end
+        end
+
+        def finding(source, match)
+          ending = match.end(0)
+          boundary = source[0...match.begin(0)].rindex(/[\s"']/)
+          start = boundary ? boundary + 1 : 0
+          { category: 'internal_endpoint', full: source[start...ending], start: start, end: ending }
+        end
+        private_class_method :finding
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/secrets/network_patterns.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Olyx
+  module Guardrails
+    module Secrets
+      # Patterns for private network coordinates that should not leave a trust boundary.
+      module NetworkPatterns
+        INTERNAL_SUFFIX = %r{\.internal\b|\.corp\b|\.intranet\b|\.local/|\bvpc\.|\.private\.|\.lan[/:]}i
+        PRIVATE_IP = %r{(?:https?://|://|host[=:\s]+|endpoint[=:\s]+|@)(?:10\.\d{1,3}\.\d{1,3}\.\d{1,3}|172\.(?:1[6-9]|2\d|3[01])\.\d{1,3}\.\d{1,3}|192\.168\.\d{1,3}\.\d{1,3})}i
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/secrets/normalized_source_set.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative '../text/mapped_normalization'
+
+module Olyx
+  module Guardrails
+    module Secrets
+      # Runs secret sources on normalized text and restores original offsets.
+      module NormalizedSourceSet
+        module_function
+
+        def call(source, custom_patterns)
+          mapped = Text::MappedNormalization.new(source)
+          return [] unless mapped.changed?
+
+          SourceSet.call(mapped.text, custom_patterns).map { |finding| restore(source, mapped, finding) }
+        end
+
+        def restore(source, mapped, finding)
+          starting, ending = mapped.original_span(finding[:start], finding[:end])
+          finding.merge(full: source[starting...ending], start: starting, end: ending)
+        end
+        private_class_method :restore
+      end
+    end
+  end
+end

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

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative 'cloud_credential_patterns'
+require_relative 'generic_credential_patterns'
+require_relative 'network_patterns'
+
+module Olyx
+  module Guardrails
+    module Secrets
+      # Declarative catalog for built-in confidentiality and credential forms.
+      module PatternCatalog
+        MARKERS = [
+          'confidential', 'proprietary', 'restricted', 'internal use only',
+          'not for distribution', 'do not share', 'do not distribute', 'top secret',
+          'trade secret', 'need to know', 'company confidential',
+          'attorney-client privilege', 'attorney client privilege', 'work product',
+          'privileged and confidential'
+        ].freeze
+        CONFIDENTIALITY = MARKERS.map do |marker|
+          Regexp.new(Regexp.escape(marker), Regexp::IGNORECASE)
+        end.freeze
+        SIMPLE = {
+          'private_network_address' => NetworkPatterns::PRIVATE_IP,
+          'aws_access_key' => CloudCredentialPatterns::AWS_ACCESS_KEY,
+          'aws_secret_key' => CloudCredentialPatterns::AWS_SECRET_KEY,
+          'secret_token' => GenericCredentialPatterns::TOKEN,
+          'jwt' => GenericCredentialPatterns::JWT,
+          'private_key' => GenericCredentialPatterns::PRIVATE_KEY,
+          'database_url' => GenericCredentialPatterns::DATABASE_URL,
+          'stripe_key' => CloudCredentialPatterns::STRIPE_KEY,
+          'google_key' => CloudCredentialPatterns::GOOGLE_KEY,
+          'azure_storage_key' => CloudCredentialPatterns::AZURE_STORAGE_KEY
+        }.freeze
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/secrets/private_network_validator.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Olyx
+  module Guardrails
+    module Secrets
+      # Rejects private-network candidates with impossible IPv4 octets.
+      module PrivateNetworkValidator
+        ADDRESS = /\b(?:10|172|192)\.(?:\d{1,3}\.){2}\d{1,3}\b/
+
+        module_function
+
+        def call(value)
+          address = value[ADDRESS]
+          address&.split('.')&.all? { |octet| octet.to_i.between?(0, 255) }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Olyx
+  module Guardrails
+    module Secrets
+      # Normalizes and merges overlapping secret redaction offsets.
+      module RedactionSpans
+        module_function
+
+        def call(findings)
+          spans = findings.filter_map { |finding| span(finding) }.sort
+          spans.each_with_object([]) { |candidate, merged| append(merged, candidate) }
+        end
+
+        def span(finding)
+          start = finding[:start]
+          ending = finding[:end]
+          [start, ending] if ending > start
+        end
+
+        def append(merged, candidate)
+          previous = merged.last
+          previous_end = previous&.last
+          return merged << candidate unless previous_end && candidate.first <= previous_end
+
+          previous[1] = [previous_end, candidate.last].max
+        end
+        private_class_method :span, :append
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/secrets/redactor.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative 'redaction_spans'
+
+module Olyx
+  module Guardrails
+    module Secrets
+      # Applies confidentiality-safe redaction to private findings.
+      module Redactor
+        module_function
+
+        def call(text, findings)
+          return '[REDACTED]' if confidential?(findings)
+
+          RedactionSpans.call(findings).reverse_each.with_object(text.dup) do |(start, ending), output|
+            output[start...ending] = '[REDACTED]'
+          end
+        end
+
+        def confidential?(findings)
+          findings.any? { |finding| finding[:category] == 'confidentiality_marker' }
+        end
+        private_class_method :confidential?
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/secrets/regexp_finding_source.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Olyx
+  module Guardrails
+    module Secrets
+      # Converts every Regexp match into an internal offset-aware finding.
+      module RegexpFindingSource
+        module_function
+
+        def call(source, category, pattern)
+          source.to_enum(:scan, pattern).map { finding(category, Regexp.last_match) }
+        end
+
+        def finding(category, match)
+          { category: category, full: match[0].to_s, start: match.begin(0), end: match.end(0) }
+        end
+        private_class_method :finding
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/secrets/source_set.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Olyx
+  module Guardrails
+    module Secrets
+      # Combines independent built-in and caller-defined secret sources.
+      module SourceSet
+        module_function
+
+        def call(source, custom_patterns)
+          ConfidentialitySource.call(source) +
+            InternalEndpointSource.call(source) +
+            CatalogSource.call(source) +
+            CustomPatternSource.call(source, custom_patterns)
+        end
+      end
+    end
+  end
+end

data/lib/olyx/guardrails/single_message_injection_detector.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative 'injection_patterns'
+require_relative 'message_content'
+require_relative 'text/detection_variants'
+
+module Olyx
+  module Guardrails
+    # Detects injection patterns within one chat message.
+    module SingleMessageInjectionDetector
+      module_function
+
+      def call(message)
+        content = MessageContent.text(message)
+        return [] if content.strip.empty?
+
+        role = MessageContent.role(message)
+        scan(content, role)
+      end
+
+      def scan(content, role)
+        findings = Text::DetectionVariants.call(content).flat_map do |variant|
+          InjectionPatterns::SINGLE_MESSAGE.filter_map { |pattern| finding(variant, role, pattern) }
+        end
+        findings.uniq { |finding| finding[:match] }
+      end
+
+      def finding(content, role, pattern)
+        match = content.match(pattern)
+        { role: role.empty? ? 'unknown' : role, match: match[0].strip } if match
+      end
+      private_class_method :finding, :scan
+    end
+  end
+end