prompt-sanitizer 0.1.0

data/lib/prompt_sanitizer/result.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module PromptSanitizer
+  # Represents a single detected PII entity.
+  DetectedEntity = Struct.new(
+    :entity_type,   # Symbol — EntityType constant (e.g. :email)
+    :original,      # String — the raw PII value found in text
+    :replacement,   # String — the placeholder token (e.g. "[EMAIL_1]")
+    :start_pos,     # Integer — character offset in the *original* text
+    :end_pos,       # Integer — end offset (exclusive) in the *original* text
+    :confidence,    # Float — detection confidence 0.0..1.0
+    :layer,         # Symbol — :regex | :secrets | :ner
+    keyword_init: true
+  )
+
+  # Returned by Sanitizer#sanitize and Session#anonymize_with_result.
+  SanitizeResult = Struct.new(
+    :text,      # String  — sanitized text with PII replaced by tokens
+    :original,  # String  — the original unsanitized input
+    :entities,  # Array<DetectedEntity> — all entities found
+    keyword_init: true
+  ) do
+    # Number of PII entities detected.
+    def count = entities.size
+
+    # True if any PII was found.
+    def any? = entities.any?
+
+    # Entities filtered by type.
+    def by_type(type) = entities.select { |e| e.entity_type == type }
+
+    # Mapping of original values to their replacement tokens.
+    def mapping
+      entities.each_with_object({}) { |e, h| h[e.original] = e.replacement }
+    end
+  end
+end

data/lib/prompt_sanitizer/sanitizer.rb

@@ -0,0 +1,221 @@
+# frozen_string_literal: true
+
+module PromptSanitizer
+  # Core sanitization class — the main public interface.
+  #
+  # Ties together RegexEngine, SecretsEngine, optional NEREngine,
+  # SyntheticEngine, Vault, and AuditLog.
+  #
+  # Usage (one-shot):
+  #
+  #   s = PromptSanitizer::Sanitizer.new(mode: :fast)
+  #   result = s.sanitize("Email me at john@acme.com")
+  #   result.text     # => "Email me at [EMAIL_1]"
+  #   result.any?     # => true
+  #
+  # Usage (multi-turn with session):
+  #
+  #   sess = s.session(session_id: "user-42")
+  #   clean = sess.anonymize(user_prompt)
+  #   raw_response = call_llm(clean)
+  #   final = sess.deanonymize(raw_response)
+  class Sanitizer
+    # @param mode       [Symbol]  :fast (default), :smart, :full
+    # @param locale     [String]  Faker locale (e.g. "en", "fr")
+    # @param entities   [Array<Symbol>, nil]  whitelist; nil = all
+    # @param on_detect  [Symbol]  :redact (default), :warn, :block
+    # @param audit_log  [Audit::Base, nil]  custom audit backend
+    # @param ner_backend [Symbol] :informers (default) or :mitie
+    # @param ner_model   [String] NER model variant
+    def initialize(
+      mode: :fast,
+      locale: "en",
+      entities: nil,
+      on_detect: :redact,
+      audit_log: nil,
+      ner_backend: :informers,
+      ner_model: "distilbert"
+    )
+      unless Mode.valid?(mode)
+        raise ConfigurationError, "Invalid mode: #{mode.inspect}. Use :fast, :smart, or :full"
+      end
+
+      @mode      = mode
+      @locale    = locale
+      @on_detect = on_detect.to_sym
+      @allowed   = entities ? Array(entities).map(&:to_sym).to_set : nil
+
+      @regex   = Engines::RegexEngine.new
+      @secrets = Engines::SecretsEngine.new
+      @ner     = mode == :fast ? nil : Engines::NEREngine.new(backend: ner_backend, model: ner_model)
+
+      @synthetic = SyntheticEngine.new(locale: locale)
+
+      @audit = if audit_log && audit_log != :none
+                 audit_log
+               elsif mode == :full
+                 Audit::MemoryAuditLog.new
+               end
+    end
+
+    # @return [Symbol] active detection mode
+    attr_reader :mode
+
+    # @return [Audit::Base, nil]
+    attr_reader :audit
+
+    # ── Public API ─────────────────────────────────────────────────────────────
+
+    # Sanitize +text+ in a single-use vault. Returns a SanitizeResult.
+    #
+    # @param text       [String]
+    # @param session_id [String, nil]  included in audit events
+    # @return [SanitizeResult]
+    def sanitize(text, session_id: nil)
+      _run(text, Vault.new, session_id: session_id)
+    end
+
+    # Sanitize a list of texts, each with its own vault.
+    #
+    # @param texts      [Array<String>]
+    # @param session_id [String, nil]
+    # @return [Array<SanitizeResult>]
+    def sanitize_batch(texts, session_id: nil)
+      texts.map { |t| sanitize(t, session_id: session_id) }
+    end
+
+    # Create a Session for multi-turn anonymize/deanonymize workflows.
+    # The session maintains a shared vault so the same PII always maps
+    # to the same token, and LLM responses can be deanonymized.
+    #
+    # Without a block, returns a Session you manage yourself.
+    # With a block, yields the Session and clears the vault after the block.
+    #
+    # @param session_id [String, nil]
+    # @yieldparam sess [Session]
+    # @return [Session, Object] the Session (no block) or block return value
+    def session(session_id: nil, &block)
+      sess = Session.new(self, session_id: session_id)
+      return sess unless block_given?
+
+      sess.use(&block)
+    end
+
+    # Register a custom regex pattern.
+    #
+    # @param entity_type [Symbol]  e.g. :custom or any EntityType
+    # @param pattern     [String]  Ruby regex string
+    # @param confidence  [Float]
+    def add_pattern(entity_type, pattern, confidence: 0.85)
+      @regex.add_pattern(entity_type.to_sym, pattern, confidence: confidence)
+    end
+
+    # Convenience: restore vault tokens in +text+ back to originals.
+    # Useful when you hold a vault externally.
+    #
+    # @param text  [String]
+    # @param vault [Vault]
+    # @return [String]
+    def restore(text, vault:)
+      vault.restore(text)
+    end
+
+    # ── Internal pipeline (called by Session too) ──────────────────────────────
+
+    # @api private
+    def _run(text, vault, session_id: nil) # rubocop:disable Naming/MethodParameterName
+      return SanitizeResult.new(text: text, original: text, entities: []) if text.nil? || text.empty?
+
+      # 1. Collect detections from all active layers
+      raw = []
+      raw.concat(@regex.detect(text))
+      raw.concat(@secrets.detect(text))
+      raw.concat(@ner.detect(text)) if @ner
+
+      # 2. Filter to allowed entity types
+      raw = raw.select { |e| @allowed.include?(e.entity_type) } if @allowed
+
+      # 3. Deduplicate overlapping spans
+      entities = _deduplicate(raw)
+
+      # 4. Handle on_detect modes
+      if @on_detect == :block && entities.any?
+        raise PIIDetectedError, entities
+      end
+
+      if @on_detect == :warn
+        return SanitizeResult.new(text: text, original: text, entities: entities)
+      end
+
+      # on_detect == :redact (default)
+
+      # 5. Assign replacements — reuse vault entry when same PII seen before
+      entities.each do |entity|
+        existing = vault.replacement_for(entity.original)
+        if existing
+          entity.replacement = existing
+        else
+          replacement = if @mode == :full
+                          @synthetic.generate(entity.entity_type, entity.original)
+                        else
+                          @synthetic.placeholder(entity.entity_type)
+                        end
+          entity.replacement = vault.add(entity.original, replacement)
+        end
+      end
+
+      # 6. Reconstruct text right-to-left to preserve byte offsets
+      chars = text.dup
+      entities.reverse_each do |entity|
+        chars[entity.start_pos...entity.end_pos] = entity.replacement.to_s
+      end
+
+      # 7. Record audit events
+      if @audit
+        entities.each do |entity|
+          method = entity.replacement.to_s.start_with?("[") ? :placeholder : :synthetic
+          @audit.record(
+            Audit::AuditEvent.new(
+              timestamp:        Audit.now_iso,
+              entity_type:      entity.entity_type,
+              confidence:       entity.confidence,
+              layer:            entity.layer,
+              redaction_method: method,
+              text_hash:        Audit.hash_value(entity.original),
+              session_id:       session_id
+            )
+          )
+        end
+      end
+
+      SanitizeResult.new(text: chars, original: text, entities: entities)
+    end
+
+    private
+
+    # Remove overlapping DetectedEntity spans.
+    # Strategy: highest confidence first (then longest span), greedy non-overlap.
+    # Returns entities sorted by start_pos.
+    def _deduplicate(entities)
+      return entities if entities.empty?
+
+      ranked = entities.sort_by { |e| [-e.confidence, -(e.end_pos - e.start_pos)] }
+
+      kept       = []
+      kept_spans = []
+
+      ranked.each do |entity|
+        overlaps = kept_spans.any? do |s, e|
+          !(entity.end_pos <= s || entity.start_pos >= e)
+        end
+
+        unless overlaps
+          kept << entity
+          kept_spans << [entity.start_pos, entity.end_pos]
+        end
+      end
+
+      kept.sort_by(&:start_pos)
+    end
+  end
+end

data/lib/prompt_sanitizer/session.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module PromptSanitizer
+  # Maintains a shared Vault across multiple anonymize/deanonymize calls.
+  #
+  # The same PII value always maps to the same replacement token within a
+  # session, and LLM responses can be deanonymized back to the originals.
+  #
+  # Usage:
+  #
+  #   sanitizer = PromptSanitizer::Sanitizer.new(mode: :smart)
+  #
+  #   # Single-use block (vault cleared on exit):
+  #   sanitizer.session(session_id: "user-42") do |sess|
+  #     clean    = sess.anonymize(user_prompt)
+  #     response = call_llm(clean)
+  #     puts sess.deanonymize(response)
+  #   end
+  #
+  #   # Long-lived (manage lifecycle yourself):
+  #   sess = sanitizer.session
+  #   loop { sess.anonymize(...) ... }
+  #   sess.reset
+  class Session
+    attr_reader :session_id, :vault
+
+    # @param sanitizer  [Sanitizer]
+    # @param session_id [String, nil]
+    def initialize(sanitizer, session_id: nil)
+      @sanitizer  = sanitizer
+      @session_id = session_id
+      @vault      = Vault.new
+    end
+
+    # Sanitize +text+ using the session's shared vault.
+    # Returns the redacted string.
+    #
+    # @param text [String]
+    # @return [String]
+    def anonymize(text)
+      @sanitizer._run(text, @vault, session_id: @session_id).text
+    end
+
+    # Like #anonymize but returns the full SanitizeResult.
+    #
+    # @param text [String]
+    # @return [SanitizeResult]
+    def anonymize_with_result(text)
+      @sanitizer._run(text, @vault, session_id: @session_id)
+    end
+
+    # Restore vault tokens in +text+ back to the original PII values.
+    # Pass the LLM's response here to get a human-readable output.
+    #
+    # @param text [String]
+    # @return [String]
+    def deanonymize(text)
+      @vault.restore(text)
+    end
+
+    # Snapshot of original → replacement mapping for this session.
+    #
+    # @return [Hash{String => String}]
+    def mapping
+      @vault.snapshot
+    end
+
+    # Number of unique PII values currently stored in the session vault.
+    #
+    # @return [Integer]
+    def size
+      @vault.snapshot.size
+    end
+
+    # Clear the vault, resetting the session for a fresh conversation.
+    def reset
+      @vault.clear
+    end
+
+    # Block form — vault is cleared after the block returns.
+    #
+    #   sanitizer.session { |s| s.anonymize(...) }
+    #
+    # @yieldparam session [Session] self
+    # @return the block's return value
+    def use
+      yield self
+    ensure
+      reset
+    end
+
+    def inspect
+      "#<PromptSanitizer::Session id=#{@session_id.inspect} mappings=#{size}>"
+    end
+    alias to_s inspect
+  end
+end

data/lib/prompt_sanitizer/synthetic.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+module PromptSanitizer
+  # Generates realistic fake replacement values per EntityType.
+  #
+  # When the +faker+ gem is installed, each call produces a
+  # contextually appropriate fake (names, emails, IPs, …).
+  # Without faker the engine falls back to sequential placeholder
+  # tokens: +[EMAIL_1]+, +[PERSON_2]+, etc.
+  #
+  # Determinism within a session is guaranteed by the Vault: the
+  # same original value always receives the same token/fake because
+  # Session#anonymize only calls +generate+ once per unique original.
+  #
+  # Usage:
+  #
+  #   engine = SyntheticEngine.new(locale: "en_US")
+  #   engine.generate(:email, "john@acme.com")   # => "xavier@mailnull.net"
+  #   engine.generate(:person, "Alice Smith")    # => "Carlos Rivera"
+  class SyntheticEngine
+    CHARS_ALPHA_NUM = ("a".."z").to_a + ("A".."Z").to_a + ("0".."9").to_a
+
+    begin
+      require "faker"
+      HAS_FAKER = true
+    rescue LoadError
+      HAS_FAKER = false
+    end
+
+    # @param locale [String] BCP-47 locale tag forwarded to Faker (e.g. "en", "fr", "de")
+    def initialize(locale: "en")
+      @locale   = locale
+      @counters = Hash.new(0) # entity_type Symbol → Integer
+      if HAS_FAKER
+        Faker::Config.locale = locale
+      end
+    end
+
+    # Returns a fake replacement string for +entity_type+.
+    #
+    # @param entity_type [Symbol]  one of the EntityType constants
+    # @param _original   [String]  original text (unused here; determinism via Vault)
+    # @return [String]
+    def generate(entity_type, _original = "")
+      if HAS_FAKER
+        faker_value(entity_type)
+      else
+        placeholder(entity_type)
+      end
+    end
+
+    # Force a placeholder token regardless of faker availability.
+    # Used by Session when the replacement must survive round-trips.
+    def placeholder(entity_type)
+      @counters[entity_type] += 1
+      "[#{entity_type.to_s.upcase}_#{@counters[entity_type]}]"
+    end
+
+    def reset!
+      @counters.clear
+    end
+
+    private
+
+    # rubocop:disable Metrics/MethodLength, Metrics/CyclomaticComplexity
+    def faker_value(entity_type) # rubocop:disable Metrics/AbcSize
+      case entity_type
+      when :person
+        Faker::Name.name
+      when :email
+        Faker::Internet.email
+      when :phone
+        Faker::PhoneNumber.phone_number
+      when :ssn
+        "#{rand(100..899).to_s.rjust(3, "0")}-" \
+          "#{rand(10..99).to_s.rjust(2, "0")}-" \
+          "#{rand(1000..9999)}"
+      when :credit_card
+        fake_luhn_card
+      when :iban
+        "GB#{rand(10..99)}MOCK" \
+          "#{rand(10_000_000..99_999_999)}" \
+          "#{rand(100_000_000_000..999_999_999_999)}"
+      when :ip_address
+        "#{rand(1..254)}.#{rand(0..255)}.#{rand(0..255)}.#{rand(1..254)}"
+      when :mac_address
+        Array.new(6) { rand(0..255).to_s(16).rjust(2, "0") }.join(":")
+      when :url
+        "https://#{Faker::Internet.domain_name}/#{Faker::Internet.slug}"
+      when :address
+        Faker::Address.full_address.tr("\n", ", ")
+      when :zip_code
+        Faker::Address.postcode
+      when :date
+        Faker::Date.between(from: "1990-01-01", to: "2020-12-31").strftime("%m/%d/%Y")
+      when :date_of_birth
+        Faker::Date.birthday(min_age: 18, max_age: 80).strftime("%m/%d/%Y")
+      when :crypto_address
+        "0x" + Array.new(40) { rand(0..15).to_s(16) }.join
+      when :passport
+        "#{("A".."Z").to_a.sample}#{rand(10_000_000..99_999_999)}"
+      when :driving_license
+        "#{("A".."Z").to_a.sample}#{rand(100_000..999_999)}"
+      when :organization
+        Faker::Company.name
+      when :location
+        Faker::Address.city
+      when :api_key
+        "sk-" + Array.new(48) { CHARS_ALPHA_NUM.sample }.join
+      when :jwt, :jwt_token
+        "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJSRURBQ1RFRCJ9.REDACTED_SIGNATURE"
+      when :bearer_token, :oauth_token
+        "REDACTED_" + Array.new(16) { (("A".."Z").to_a + ("0".."9").to_a).sample }.join
+      when :aws_access_key
+        "AKIA" + Array.new(16) { (("A".."Z").to_a + ("0".."9").to_a).sample }.join
+      when :aws_secret_key
+        Array.new(40) { (("a".."z").to_a + ("A".."Z").to_a + ("0".."9").to_a + ["+", "/"]).sample }.join
+      when :private_key
+        "-----BEGIN PRIVATE KEY-----\nREDACTED\n-----END PRIVATE KEY-----"
+      when :db_connection, :database_url
+        "postgresql://user:password@localhost:5432/#{Faker::Lorem.word}"
+      when :secret_key, :password
+        placeholder(entity_type)
+      else
+        placeholder(entity_type)
+      end
+    end
+    # rubocop:enable Metrics/MethodLength, Metrics/CyclomaticComplexity
+
+    # Generates a Luhn-valid 16-digit fake Visa card number.
+    def fake_luhn_card
+      digits = [4] + Array.new(14) { rand(0..9) }
+
+      # Calculate check digit — double digits at even indices (0,2,4,...,14)
+      # so that in the final 16-digit number they sit at even positions from
+      # the right (2,4,...,16) as required by the Luhn algorithm.
+      sum = digits.each_with_index.sum do |d, i|
+        if i.even?
+          doubled = d * 2
+          doubled > 9 ? doubled - 9 : doubled
+        else
+          d
+        end
+      end
+      check = (10 - (sum % 10)) % 10
+      digits << check
+
+      raw = digits.join
+      "#{raw[0, 4]} #{raw[4, 4]} #{raw[8, 4]} #{raw[12, 4]}"
+    end
+  end
+end

data/lib/prompt_sanitizer/vault.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module PromptSanitizer
+  # Thread-safe bidirectional in-memory store for a sanitization session.
+  #
+  # Maps original PII values → their replacement tokens and vice-versa.
+  # Deterministic within a session: the same original always maps to the
+  # same replacement. The vault is never persisted — it lives only in memory.
+  #
+  # Safe for use across Puma threads — all reads and writes are guarded by
+  # a Mutex.
+  class Vault
+    def initialize
+      @forward = {}  # original  → replacement
+      @reverse = {}  # replacement → original
+      @mutex   = Mutex.new
+    end
+
+    # ── Write ───────────────────────────────────────────────────────────────
+
+    # Store an original → replacement mapping.
+    # If the original is already mapped, the existing replacement is returned
+    # (determinism guarantee). Returns the active replacement string.
+    def add(original, replacement)
+      @mutex.synchronize do
+        unless @forward.key?(original)
+          @forward[original]    = replacement
+          @reverse[replacement] = original
+        end
+        @forward[original]
+      end
+    end
+
+    # ── Read ────────────────────────────────────────────────────────────────
+
+    def replacement_for(original)
+      @forward[original]
+    end
+
+    def original_for(replacement)
+      @reverse[replacement]
+    end
+
+    # ── Restore ─────────────────────────────────────────────────────────────
+
+    # Replace all known replacement tokens in +text+ with their originals.
+    # Tokens are substituted longest-first to avoid partial matches
+    # (e.g. "[EMAIL_1]" before "[EMAIL]").
+    def restore(text)
+      @mutex.synchronize do
+        result = text.dup
+        @reverse
+          .keys
+          .sort_by { |k| -k.length }
+          .each { |token| result.gsub!(token, @reverse[token]) }
+        result
+      end
+    end
+
+    # ── Lifecycle ───────────────────────────────────────────────────────────
+
+    def clear
+      @mutex.synchronize do
+        @forward.clear
+        @reverse.clear
+      end
+    end
+
+    # ── Introspection ────────────────────────────────────────────────────────
+
+    def size = @forward.size
+    alias length size
+
+    def empty? = @forward.empty?
+
+    def include?(original) = @forward.key?(original)
+
+    # Returns a frozen copy of the forward mapping (original → replacement).
+    # Safe to call from any thread.
+    def snapshot
+      @mutex.synchronize { @forward.dup.freeze }
+    end
+
+    def inspect
+      "#<#{self.class.name} size=#{size}>"
+    end
+  end
+end

data/lib/prompt_sanitizer/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module PromptSanitizer
+  VERSION = "0.1.0"
+end