lex-privatecore 0.1.6 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 68cb796e6e99ce901512ecf159fc1b4abf151d59b14d3acd212ec38374ab584c
-  data.tar.gz: e780847abcbd06b0f5ffb67dffa96b9cdc1c11c48448b4078b7d3d8bbd0cabca
+  metadata.gz: 0a5caecc722556ab9de44e192040ce1445eb96741e40e3ae18a6132af59a9d6a
+  data.tar.gz: '09f8d7852b8cd3f75f081fa7aa17a2fbd76156ed8a058ad942a0e982ffc8a2a0'
 SHA512:
-  metadata.gz: 82b5a79904f3b653de6896c54f603323a2fcf175359acce3d7d98f51329f2879335aea31597f7d694d50c600b3efcd14d6597f9f3eb5623929bd33b112939f4b
-  data.tar.gz: 3f7dd3c81e36f114190c6382156b746a937226829c70559a9445b0db58d7ed864c5e77d0f342935dd3905e4ae4170f008f74b0f0ec2f7cd72d3badec11c1f872
+  metadata.gz: b26c19b98e4adf30b439d6ef01c4f920b51ef200c94d83e50e789dac6b65519d89e9765b7ad6b38c8239c307f78e9f00384285cbccb4a65bdf953b526a106952
+  data.tar.gz: f38425334a86061f4e7e21ce91bcb77298c547ee414df1aeca80a2cde5e4dc8d929d01f69aed2dca6d69b919724cef9945573d4c493011bd4d5863ea7b8c62ce

data/lex-privatecore.gemspec

@@ -33,4 +33,6 @@ Gem::Specification.new do |spec|
   spec.add_dependency 'legion-logging',   '>= 1.3.2'
   spec.add_dependency 'legion-settings',  '>= 1.3.14'
   spec.add_dependency 'legion-transport', '>= 1.3.9'
+
+  spec.add_dependency 'faraday', '>= 2.0'
 end

data/lib/legion/extensions/privatecore/client.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require 'legion/extensions/privatecore/helpers/patterns'
+require 'legion/extensions/privatecore/helpers/redactor'
+require 'legion/extensions/privatecore/helpers/ner_client'
 require 'legion/extensions/privatecore/helpers/boundary'
 require 'legion/extensions/privatecore/helpers/erasure'
 require 'legion/extensions/privatecore/helpers/similarity'

data/lib/legion/extensions/privatecore/helpers/boundary.rb

@@ -5,15 +5,6 @@ module Legion
     module Privatecore
       module Helpers
         module Boundary
-          # PII patterns to strip before boundary crossing
-          PII_PATTERNS = {
-            email: /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b/,
-            phone: /\b\d{3}[-.]?\d{3}[-.]?\d{4}\b/,
-            ssn:   /\b\d{3}-\d{2}-\d{4}\b/,
-            ip:    /\b\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}\b/
-          }.freeze
-
-          # Probe detection patterns (attempts to extract private data)
           PROBE_PATTERNS = [
             /what (?:does|did) .+ tell you/i,
             /share .+ private/i,
@@ -25,16 +16,48 @@ module Legion
           REDACTION_MARKER    = '[REDACTED]'
           MAX_AUDIT_LOG_SIZE  = 1000
 
+          DEFAULT_ENABLED    = %i[email phone ssn ip].freeze
+          DEFAULT_MODE       = :redact
+
           module_function
 
-          def strip_pii(text)
-            return text unless text.is_a?(String)
+          def strip_pii(text, mode: nil, service_url: nil)
+            return { cleaned: text, mapping: {}, detections: [], source: :none } unless text.is_a?(String)
+
+            effective_mode    = resolve_setting(mode, :redaction, :mode) || DEFAULT_MODE
+            effective_enabled = resolve_setting(nil, :patterns, :enabled) || DEFAULT_ENABLED
+            effective_validation = resolve_setting(nil, :patterns, :validation) || {}
+
+            detections = Patterns.detect(text, enabled: effective_enabled, validation: effective_validation)
+            ner_fallback = apply_ner(detections, text, service_url)
+
+            result = Redactor.redact(text, detections: detections, mode: effective_mode)
+            source = determine_source(detections, ner_fallback)
+            mapping_key = persist_mapping_if_configured(result[:mapping])
+
+            result.merge(source: source, mapping_key: mapping_key)
+          end
+
+          def contains_pii?(text, service_url: nil)
+            return false unless text.is_a?(String)
+
+            effective_enabled = resolve_setting(nil, :patterns, :enabled) || DEFAULT_ENABLED
+            effective_validation = resolve_setting(nil, :patterns, :validation) || {}
 
-            result = text.dup
-            PII_PATTERNS.each_value do |pattern|
-              result.gsub!(pattern, REDACTION_MARKER)
+            detections = Patterns.detect(text, enabled: effective_enabled, validation: effective_validation)
+            return true unless detections.empty?
+
+            if service_url || ner_enabled?
+              ner_result = run_ner(text, service_url)
+              ner_detections = if ner_result.is_a?(Hash) && ner_result[:fallback]
+                                 ner_result[:detections]
+                               else
+                                 ner_result
+                               end
+              return true unless ner_detections.empty?
             end
-            result
+
+            false
           end
 
           def detect_probe(text)
@@ -43,10 +66,91 @@ module Legion
             PROBE_PATTERNS.any? { |p| p.match?(text) }
           end
 
-          def contains_pii?(text)
-            return false unless text.is_a?(String)
+          def apply_ner(detections, text, service_url)
+            return false unless service_url || ner_enabled?
 
-            PII_PATTERNS.any? { |_, pattern| pattern.match?(text) }
+            ner_result = run_ner(text, service_url)
+            if ner_result.is_a?(Hash) && ner_result[:fallback]
+              ner_detections = ner_result[:detections]
+              detections.replace(merge_detections(detections, ner_detections))
+              true
+            else
+              detections.replace(merge_detections(detections, ner_result))
+              false
+            end
+          end
+
+          def determine_source(detections, ner_fallback)
+            has_ner = detections.any? { |d| d[:source] == :ner }
+            has_regex = detections.any? { |d| d[:source] != :ner }
+
+            if detections.empty?
+              :none
+            elsif ner_fallback
+              :regex_fallback
+            elsif has_ner && has_regex
+              :ner_and_regex
+            elsif has_ner
+              :ner
+            else
+              :regex
+            end
+          end
+
+          def persist_mapping_if_configured(mapping)
+            return nil if mapping.empty?
+            return nil unless resolve_setting(nil, :redaction, :cache_mappings) == true
+
+            cache_ttl = resolve_setting(nil, :redaction, :cache_ttl) || 3600
+            Redactor.persist_mapping(mapping: mapping, key: nil, ttl: cache_ttl)
+          end
+
+          def resolve_setting(override, *keys)
+            return override unless override.nil?
+            return nil unless defined?(Legion::Settings)
+
+            Legion::Settings.dig(:privatecore, *keys)
+          end
+
+          def ner_enabled?
+            return false unless defined?(Legion::Settings)
+
+            Legion::Settings.dig(:privatecore, :ner, :enabled) == true
+          end
+
+          def run_ner(text, service_url)
+            url = service_url || resolve_setting(nil, :ner, :service_url)
+            return [] unless url
+
+            allow_http = resolve_setting(nil, :ner, :allow_http) == true
+            return [] unless allow_http || url.start_with?('https://')
+
+            timeout  = resolve_setting(nil, :ner, :timeout) || 5
+            fallback = resolve_setting(nil, :ner, :fallback) || :transparent
+            conn = NerClient.build_connection(service_url: url, timeout: timeout)
+            NerClient.analyze(text: text, connection: conn, fallback: fallback, timeout: timeout)
+          end
+
+          def merge_detections(regex_detections, ner_detections)
+            return regex_detections if ner_detections.empty?
+            return ner_detections if regex_detections.empty?
+
+            all = regex_detections.map { |d| d.merge(source: :regex) } +
+                  ner_detections
+            all.sort_by! { |d| [d[:start], -(d[:end] - d[:start])] }
+
+            merged = []
+            all.each do |detection|
+              if merged.empty? || detection[:start] >= merged.last[:end]
+                merged << detection
+              else
+                prev = merged.last
+                det_span = detection[:end] - detection[:start]
+                prev_span = prev[:end] - prev[:start]
+                merged[-1] = detection if det_span > prev_span
+              end
+            end
+            merged
           end
         end
       end

data/lib/legion/extensions/privatecore/helpers/ner_client.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require 'faraday'
+require 'json'
+
+module Legion
+  module Extensions
+    module Privatecore
+      module Helpers
+        module NerClient
+          class NerServiceUnavailable < StandardError; end
+
+          ENTITY_MAP = {
+            'EMAIL_ADDRESS'     => :email,
+            'PHONE_NUMBER'      => :phone,
+            'US_SSN'            => :ssn,
+            'IP_ADDRESS'        => :ip,
+            'CREDIT_CARD'       => :credit_card,
+            'DATE_TIME'         => :dob,
+            'MEDICAL_LICENSE'   => :mrn,
+            'PERSON'            => :person_name,
+            'ORGANIZATION'      => :organization,
+            'LOCATION'          => :location,
+            'IBAN_CODE'         => :iban,
+            'US_PASSPORT'       => :passport,
+            'US_DRIVER_LICENSE' => :drivers_license,
+            'CRYPTO'            => :crypto,
+            'NRP'               => :national_id
+          }.freeze
+
+          NER_CATEGORIES = {
+            person_name:  :personal,
+            organization: :entity,
+            location:     :location,
+            national_id:  :government_id,
+            crypto:       :crypto
+          }.freeze
+
+          module_function
+
+          def analyze(text:, connection:, fallback: :transparent, timeout: 5)
+            response = connection.post do |req|
+              req.headers['Content-Type'] = 'application/json'
+              req.body = ::JSON.generate(text: text, language: 'en')
+              req.options.timeout = timeout
+            end
+
+            parse_response(response, text)
+          rescue Faraday::Error, ::JSON::ParserError => e
+            handle_fallback(fallback, e)
+          end
+
+          def available?(connection:)
+            response = connection.get('/health')
+            response.status == 200
+          rescue Faraday::Error => e
+            Legion::Logging.warn "[privatecore] NER health check failed: #{e.message}" # rubocop:disable Legion/HelperMigration/DirectLogging
+            false
+          end
+
+          def build_connection(service_url:, timeout: 5)
+            require 'faraday'
+            Faraday.new(url: service_url) do |f|
+              f.options.timeout = timeout
+              f.options.open_timeout = timeout
+              f.adapter Faraday.default_adapter
+            end
+          end
+
+          def parse_response(response, text)
+            return [] unless response.status == 200
+
+            entities = ::JSON.parse(response.body)
+            entities.filter_map do |entity|
+              type = ENTITY_MAP[entity['entity_type']]
+              next unless type
+
+              category = NER_CATEGORIES[type]
+              if category.nil?
+                begin
+                  category = Patterns::PATTERNS.dig(type, :category) || :unknown
+                rescue NameError => _e
+                  category = :unknown
+                end
+              end
+
+              {
+                type:     type,
+                category: category,
+                start:    entity['start'],
+                end:      entity['end'],
+                match:    text[entity['start']...entity['end']],
+                score:    entity['score'],
+                source:   :ner
+              }
+            end
+          end
+
+          def handle_fallback(fallback, error)
+            case fallback
+            when :transparent
+              { fallback: true, detections: [] }
+            when :strict
+              raise NerServiceUnavailable, "NER service unavailable: #{error.message}"
+            else
+              []
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/privatecore/helpers/patterns.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Privatecore
+      module Helpers
+        module Patterns
+          PATTERNS = {
+            email:           { regex:    /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/,
+                               category: :contact },
+            phone:           { regex:    /\b\d{3}[-.]?\d{3}[-.]?\d{4}\b/,
+                               category: :contact },
+            ssn:             { regex:    /\b\d{3}-\d{2}-\d{4}\b/,
+                               category: :government_id },
+            ip:              { regex:    /\b\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}\b/,
+                               category: :network },
+            credit_card:     { regex: /\b(?:\d[ -]*?){13,19}\b/,
+                               category: :financial, checksum: :luhn },
+            dob:             { regex:    %r{(?:DOB|date of birth)\s*:\s*(\d{1,4}[-/]\d{1,2}[-/]\d{1,4})}i,
+                               category: :personal },
+            mrn:             { regex:    /(?:MRN|medical record)\s*:\s*(\d{5,15})/i,
+                               category: :medical },
+            passport:        { regex:    /\b[A-Z]\d{8}\b/,
+                               category: :government_id },
+            iban:            { regex: /\b[A-Z]{2}\d{2}[A-Z0-9]{11,30}\b/,
+                               category: :financial, checksum: :iban },
+            drivers_license: { regex:    /\b[A-Z]\d{3}-?\d{4}-?\d{4}\b/,
+                               category: :government_id },
+            url:             { regex:    %r{https?://[^\s<>"{}|\\^`\[\]]+},
+                               category: :network },
+            btc_address:     { regex: /\b[13][a-km-zA-HJ-NP-Z1-9]{25,34}\b/,
+                               category: :crypto, checksum: :base58check },
+            eth_address:     { regex:    /\b0x[0-9a-fA-F]{40}\b/,
+                               category: :crypto },
+            itin:            { regex:    /\b9\d{2}-[7-9]\d-\d{4}\b/,
+                               category: :government_id },
+            aadhaar:         { regex: /\b[2-9]\d{3}\s?\d{4}\s?\d{4}\b/,
+                               category: :government_id, checksum: :verhoeff },
+            api_key:         { regex:    /\b(?:sk|pk|rk)_(?:live|test)_[A-Za-z0-9]{20,}\b/,
+                               category: :credential },
+            bearer_token:    { regex:    %r{Bearer\s+[A-Za-z0-9\-._~+/]+=*},
+                               category: :credential },
+            aws_key:         { regex:    /\bAKIA[0-9A-Z]{16}\b/,
+                               category: :credential }
+          }.freeze
+
+          module_function
+
+          CHECKSUM_VALIDATORS = {
+            luhn:        ->(digits) { luhn_valid?(digits) },
+            iban:        ->(text) { iban_valid?(text) },
+            verhoeff:    ->(digits) { verhoeff_valid?(digits) },
+            base58check: ->(addr) { base58check_valid?(addr) }
+          }.freeze
+
+          def detect(text, enabled:, validation:)
+            return [] unless text.is_a?(String)
+
+            detections = []
+            PATTERNS.each do |type, meta|
+              next unless enabled.include?(type)
+
+              text.scan(meta[:regex]) do
+                md = Regexp.last_match
+                capture_index = md.captures.each_index.find { |index| !md[index + 1].nil? }
+                match_index = capture_index ? capture_index + 1 : 0
+                matched_text = md[match_index]
+                next if validation[type] == :checksum && !validate_checksum(type, matched_text)
+
+                detections << {
+                  type:     type,
+                  category: meta[:category],
+                  start:    md.begin(match_index),
+                  end:      md.end(match_index),
+                  match:    matched_text
+                }
+              end
+            end
+            detections
+          end
+
+          def validate_checksum(type, match)
+            meta = PATTERNS[type]
+            return true unless meta && meta[:checksum]
+
+            validator = CHECKSUM_VALIDATORS[meta[:checksum]]
+            return true unless validator
+
+            cleaned = match.gsub(/[\s-]/, '')
+            validator.call(cleaned)
+          end
+
+          def luhn_valid?(number)
+            digits = number.chars.map(&:to_i)
+            sum = 0
+            digits.reverse.each_with_index do |d, i|
+              d *= 2 if i.odd?
+              d -= 9 if d > 9
+              sum += d
+            end
+            (sum % 10).zero?
+          end
+
+          def iban_valid?(iban)
+            rearranged = iban[4..] + iban[0..3]
+            numeric = rearranged.chars.map { |c| c.match?(/\d/) ? c : (c.upcase.ord - 55).to_s }.join
+            (numeric.to_i % 97) == 1
+          end
+
+          VERHOEFF_D = [
+            [0, 1, 2, 3, 4, 5, 6, 7, 8, 9], [1, 2, 3, 4, 0, 6, 7, 8, 9, 5],
+            [2, 3, 4, 0, 1, 7, 8, 9, 5, 6], [3, 4, 0, 1, 2, 8, 9, 5, 6, 7],
+            [4, 0, 1, 2, 3, 9, 5, 6, 7, 8], [5, 9, 8, 7, 6, 0, 4, 3, 2, 1],
+            [6, 5, 9, 8, 7, 1, 0, 4, 3, 2], [7, 6, 5, 9, 8, 2, 1, 0, 4, 3],
+            [8, 7, 6, 5, 9, 3, 2, 1, 0, 4], [9, 8, 7, 6, 5, 4, 3, 2, 1, 0]
+          ].freeze
+
+          VERHOEFF_P = [
+            [0, 1, 2, 3, 4, 5, 6, 7, 8, 9], [1, 5, 7, 6, 2, 8, 3, 0, 9, 4],
+            [5, 8, 0, 3, 7, 9, 6, 1, 4, 2], [8, 9, 1, 6, 0, 4, 3, 5, 2, 7],
+            [9, 4, 5, 3, 1, 2, 6, 8, 7, 0], [4, 2, 8, 6, 5, 7, 3, 9, 0, 1],
+            [2, 7, 9, 3, 8, 0, 6, 4, 1, 5], [7, 0, 4, 6, 9, 1, 3, 2, 5, 8]
+          ].freeze
+
+          def verhoeff_valid?(number)
+            digits = number.chars.map(&:to_i).reverse
+            c = 0
+            digits.each_with_index { |d, i| c = VERHOEFF_D[c][VERHOEFF_P[i % 8][d]] }
+            c.zero?
+          end
+
+          BASE58_ALPHABET = '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz'
+
+          def base58check_valid?(address)
+            return false unless address.match?(/\A[13][a-km-zA-HJ-NP-Z1-9]{25,34}\z/)
+
+            # Decode Base58 to integer
+            num = 0
+            address.each_char do |char|
+              index = BASE58_ALPHABET.index(char)
+              return false if index.nil?
+
+              num = (num * 58) + index
+            end
+
+            # Convert to variable-length big-endian bytes, then restore
+            # leading zero bytes represented by leading '1' characters.
+            bytes = []
+            while num.positive?
+              bytes.unshift(num & 0xff)
+              num >>= 8
+            end
+
+            leading_ones = address.each_char.take_while { |char| char == '1' }.size
+            bytes = ([0] * leading_ones) + bytes
+
+            # Base58Check P2PKH/P2SH addresses decode to:
+            # 1 version byte + 20 payload bytes + 4 checksum bytes.
+            return false unless bytes.size == 25
+
+            payload  = bytes[0...-4]
+            checksum = bytes[-4..]
+
+            # Double SHA-256 of payload; compare first 4 bytes
+            require 'digest'
+            first_hash  = Digest::SHA256.digest(payload.pack('C*'))
+            second_hash = Digest::SHA256.digest(first_hash)
+            second_hash.unpack('C*').first(4) == checksum
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/privatecore/helpers/redactor.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module Privatecore
+      module Helpers
+        module Redactor
+          REDACTION_MARKER = '[REDACTED]'
+
+          module_function
+
+          def redact(text, detections:, mode:)
+            return { cleaned: text, mapping: {}, detections: detections } unless text.is_a?(String)
+            return { cleaned: text, mapping: {}, detections: detections } if detections.empty?
+
+            mapping = {}
+            type_counters = Hash.new(0)
+            cleaned = text.dup
+
+            sorted = detections.sort_by { |d| -d[:start] }
+
+            sorted.each do |detection|
+              replacement = build_replacement(detection, mode, type_counters, mapping)
+              cleaned[detection[:start]...detection[:end]] = replacement
+            end
+
+            { cleaned: cleaned, mapping: mapping, detections: detections }
+          end
+
+          def build_replacement(detection, mode, type_counters, mapping)
+            case mode
+            when :placeholder
+              type_counters[detection[:type]] += 1
+              tag = "[#{detection[:type].upcase}_#{type_counters[detection[:type]]}]"
+              mapping[tag] = detection[:match]
+              tag
+            when :mask
+              mask_value(detection[:match])
+            when :synthetic
+              fake = generate_synthetic(detection[:type], detection[:match])
+              mapping[fake] = detection[:match]
+              fake
+            else
+              REDACTION_MARKER
+            end
+          end
+
+          def mask_value(original)
+            original.gsub(/[A-Za-z]/, '*').gsub(/\d/, '*')
+          end
+
+          def generate_synthetic(type, original)
+            case type
+            when :ssn, :itin
+              "#{rand(100..999)}-#{rand(10..99)}-#{rand(1000..9999)}"
+            when :phone
+              "#{rand(200..999)}-#{rand(200..999)}-#{rand(1000..9999)}"
+            when :email
+              "user#{rand(1000..9999)}@example.net"
+            when :credit_card
+              generate_luhn_number(16)
+            when :ip
+              "#{rand(1..254)}.#{rand(0..255)}.#{rand(0..255)}.#{rand(1..254)}"
+            when :aadhaar
+              "#{rand(2000..9999)} #{rand(1000..9999)} #{rand(1000..9999)}"
+            when :passport
+              "#{('A'..'Z').to_a.sample}#{rand(10_000_000..99_999_999)}"
+            when :aws_key
+              "AKIA#{Array.new(16) { (('0'..'9').to_a + ('A'..'Z').to_a).sample }.join}"
+            else
+              SecureRandom.hex([((original.length + 1) / 2), 1].max)
+            end
+          end
+
+          def generate_luhn_number(length)
+            digits = Array.new(length - 1) { rand(0..9) }
+            sum = 0
+            digits.reverse.each_with_index do |d, i|
+              v = i.even? ? d * 2 : d
+              v -= 9 if v > 9
+              sum += v
+            end
+            check = (10 - (sum % 10)) % 10
+            (digits << check).join
+          end
+
+          def restore(text:, mapping:)
+            return text if mapping.nil? || mapping.empty?
+
+            result = text.dup
+            mapping.each { |placeholder, original| result.gsub!(placeholder, original) }
+            result
+          end
+
+          def persist_mapping(mapping:, key:, ttl:)
+            actual_key = key || SecureRandom.uuid
+            Legion::Cache.set("privatecore:mapping:#{actual_key}", mapping, ttl: ttl) if defined?(Legion::Cache) # rubocop:disable Legion/HelperMigration/DirectCache
+            actual_key
+          end
+
+          def retrieve_mapping(key:)
+            return nil unless defined?(Legion::Cache)
+
+            Legion::Cache.get("privatecore:mapping:#{key}") # rubocop:disable Legion/HelperMigration/DirectCache
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/privatecore/runners/privatecore.rb

@@ -8,23 +8,28 @@ module Legion
           include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers, false) &&
                                                       Legion::Extensions::Helpers.const_defined?(:Lex, false)
 
-          def enforce_boundary(text:, direction: :outbound, **)
+          def enforce_boundary(text:, direction: :outbound, mode: nil, service_url: nil, **)
             case direction
             when :outbound
-              pii_found = Helpers::Boundary.contains_pii?(text)
-              stripped = Helpers::Boundary.strip_pii(text)
-              log.debug "[privatecore] boundary outbound: length=#{text.length} pii_found=#{pii_found}"
+              result = Helpers::Boundary.strip_pii(text, mode: mode, service_url: service_url)
+              pii_found = !result[:detections].empty?
+              text_length = text.is_a?(String) ? text.length : 0
+              log.debug "[privatecore] boundary outbound: length=#{text_length} pii_found=#{pii_found}"
               log.warn '[privatecore] PII stripped from outbound text' if pii_found
+              safe_detections = result[:detections].map { |d| d.except(:match) }
               {
-                original_length: text.length,
-                cleaned:         stripped,
+                original_length: text_length,
+                cleaned:         result[:cleaned],
                 pii_found:       pii_found,
-                direction:       direction
+                direction:       direction,
+                detections:      safe_detections,
+                mapping:         result[:mapping],
+                mapping_key:     result[:mapping_key]
               }
             when :inbound
               probe = Helpers::Boundary.detect_probe(text)
               action = probe ? :flag_and_log : :allow
-              log.debug "[privatecore] boundary inbound: probe=#{!probe.nil?} action=#{action}"
+              log.debug "[privatecore] boundary inbound: probe=#{probe} action=#{action}"
               log.warn '[privatecore] PROBE DETECTED in inbound text' if probe
               {
                 text:      text,
@@ -35,22 +40,42 @@ module Legion
             end
           end
 
-          def check_pii(text:, **)
-            has_pii = Helpers::Boundary.contains_pii?(text)
+          def check_pii(text:, service_url: nil, **)
+            result = Helpers::Boundary.strip_pii(text, service_url: service_url)
+            has_pii = !result[:detections].empty?
             log.debug "[privatecore] pii check: contains_pii=#{has_pii}"
+            safe_detections = result[:detections].map { |d| d.except(:match) }
             {
               contains_pii: has_pii,
-              stripped:     Helpers::Boundary.strip_pii(text)
+              stripped:     result[:cleaned],
+              detections:   safe_detections
             }
           end
 
           def detect_probe(text:, **)
             probe = Helpers::Boundary.detect_probe(text)
-            log.debug "[privatecore] probe check: detected=#{!probe.nil?}"
-            Legion::Events.emit('privatecore.probe_detected', text_length: text.length) if probe && defined?(Legion::Events)
+            log.debug "[privatecore] probe check: detected=#{probe}"
+            Legion::Events.emit('privatecore.probe_detected', text_length: text.is_a?(String) ? text.length : 0) if probe && defined?(Legion::Events)
             { probe_detected: probe }
           end
 
+          def restore_text(text:, mapping: nil, mapping_key: nil, **)
+            if mapping
+              restored = Helpers::Redactor.restore(text: text, mapping: mapping)
+              { restored: restored, success: true }
+            elsif mapping_key
+              retrieved = Helpers::Redactor.retrieve_mapping(key: mapping_key)
+              if retrieved
+                restored = Helpers::Redactor.restore(text: text, mapping: retrieved)
+                { restored: restored, success: true }
+              else
+                { restored: nil, success: false, error: :mapping_not_found }
+              end
+            else
+              { restored: nil, success: false, error: :no_mapping }
+            end
+          end
+
           def erasure_audit(**)
             count = erasure_engine.audit_log.size
             log.debug "[privatecore] erasure audit: entries=#{count}"