pii_scrubber 0.1.0

data/lib/pii_scrubber/detectors/iban.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module PiiScrubber
+  module Detectors
+    class Iban < Base
+      # Matches international bank account numbers (15-34 alphanumeric chars with optional spacing/hyphens)
+      IBAN_REGEX = /\b[A-Za-z]{2}\d{2}(?:[ -]?[A-Za-z0-9]{4}){2,7}(?:[ -]?[A-Za-z0-9]{1,4})?\b/
+
+      def initialize
+        super(name: :iban)
+      end
+
+      def patterns
+        [IBAN_REGEX]
+      end
+
+      def valid?(match)
+        sanitized = match.gsub(/[\s-]/, "").upcase
+        return false unless sanitized.length.between?(15, 34)
+        return false unless sanitized.match?(/\A[A-Z]{2}\d{2}[A-Z0-9]+\z/)
+
+        modulo97_valid?(sanitized)
+      end
+
+      def replace(match, strategy: :placeholder, mask_char: "*", hmac_salt: nil)
+        return super unless strategy == :mask
+
+        sanitized = match.gsub(/[\s-]/, "").upcase
+        return super if sanitized.length < 8
+
+        prefix = sanitized[0..3] # Country code + check digits
+        suffix = sanitized[-4..]
+        masked_middle = mask_char * (sanitized.length - 8)
+        "#{prefix}#{masked_middle}#{suffix}"
+      end
+
+      private
+
+      # ISO 7064 Modulo 97-10 checksum validation
+      def modulo97_valid?(iban)
+        # Move first 4 characters (country + check digits) to the end
+        rearranged = iban[4..] + iban[0..3]
+
+        # Convert letters to digits: A=10, B=11, ..., Z=35
+        num_str = rearranged.each_char.map do |ch|
+          if ch >= "A" && ch <= "Z"
+            (ch.ord - 55).to_s
+          else
+            ch
+          end
+        end.join
+
+        # Calculate remainder modulo 97
+        num_str.to_i % 97 == 1
+      end
+    end
+  end
+end

data/lib/pii_scrubber/detectors/indian_aadhaar.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module PiiScrubber
+  module Detectors
+    class IndianAadhaar < Base
+      # Matches 12-digit Indian Aadhaar numbers starting with 2-9
+      AADHAAR_REGEX = /\b[2-9][0-9]{3}[ -]?[0-9]{4}[ -]?[0-9]{4}\b/
+
+      # Verhoeff algorithm multiplication table
+      D_TABLE = [
+        [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 algorithm permutation table
+      P_TABLE = [
+        [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 initialize
+        super(name: :indian_aadhaar)
+      end
+
+      def patterns
+        [AADHAAR_REGEX]
+      end
+
+      def valid?(match)
+        digits = match.scan(/\d/).map(&:to_i)
+        return false unless digits.size == 12
+
+        # First digit cannot be 0 or 1
+        return false if [0, 1].include?(digits.first)
+
+        verhoeff_valid?(digits)
+      end
+
+      def replace(match, strategy: :placeholder, mask_char: "*", hmac_salt: nil)
+        return super unless strategy == :mask
+
+        digits = match.scan(/\d/)
+        return super if digits.size != 12
+
+        last_four = digits.last(4).join
+        "#{mask_char * 4}-#{mask_char * 4}-#{last_four}"
+      end
+
+      private
+
+      # Validates 12-digit number using Verhoeff checksum algorithm
+      def verhoeff_valid?(digits)
+        checksum = 0
+        digits.reverse.each_with_index do |digit, index|
+          checksum = D_TABLE[checksum][P_TABLE[index % 8][digit]]
+        end
+        checksum.zero?
+      end
+    end
+  end
+end

data/lib/pii_scrubber/detectors/indian_pan.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module PiiScrubber
+  module Detectors
+    class IndianPan < Base
+      # Matches 10-character Indian Permanent Account Numbers (e.g. ABCDE1234F)
+      PAN_REGEX = /\b[A-Za-z]{5}[0-9]{4}[A-Za-z]\b/
+
+      VALID_HOLDER_TYPES = %w[C P H F A T B L J G].freeze
+
+      def initialize
+        super(name: :indian_pan)
+      end
+
+      def patterns
+        [PAN_REGEX]
+      end
+
+      def valid?(match)
+        pan = match.upcase
+        return false unless pan.length == 10
+
+        holder_type = pan[3]
+        VALID_HOLDER_TYPES.include?(holder_type)
+      end
+
+      def replace(match, strategy: :placeholder, mask_char: "*", hmac_salt: nil)
+        return super unless strategy == :mask
+
+        pan = match.upcase
+        return super if pan.length != 10
+
+        prefix = pan[0..2]
+        digits = pan[5..8]
+        suffix = pan[9]
+        "#{prefix}#{mask_char * 2}#{digits}#{suffix}"
+      end
+    end
+  end
+end

data/lib/pii_scrubber/detectors/ip_address.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module PiiScrubber
+  module Detectors
+    class IpAddress < Base
+      IPV4_REGEX = /\b(?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\b/
+      IPV6_REGEX = /\b(?:[0-9a-fA-F]{1,4}:){7}[0-9a-fA-F]{1,4}\b/
+
+      def initialize
+        super(name: :ip_address)
+      end
+
+      def patterns
+        [IPV4_REGEX, IPV6_REGEX]
+      end
+
+      def valid?(match)
+        # Optional check: skip localhost (127.0.0.1 or ::1) if needed, otherwise valid IP
+        true
+      end
+
+      def replace(match, strategy: :placeholder, mask_char: "*", hmac_salt: nil)
+        return super unless strategy == :mask
+
+        if match.include?(".") # IPv4
+          octets = match.split(".")
+          "#{octets[0]}.#{octets[1]}.#{mask_char * 3}.#{mask_char * 3}"
+        else
+          super
+        end
+      end
+    end
+  end
+end

data/lib/pii_scrubber/detectors/phone.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module PiiScrubber
+  module Detectors
+    class Phone < Base
+      # Matches international and common domestic phone number formats
+      PHONE_REGEX = /(?:\+|\b)(?:[0-9]{1,3}[ -]?)?\(?[0-9]{3}\)?[ -]?[0-9]{3}[ -]?[0-9]{4}\b/
+
+      def initialize
+        super(name: :phone)
+      end
+
+      def patterns
+        [PHONE_REGEX]
+      end
+
+      def valid?(match)
+        # Ensure it has between 10 and 15 digits
+        digits = match.gsub(/\D/, "")
+        digits.length >= 10 && digits.length <= 15
+      end
+    end
+  end
+end

data/lib/pii_scrubber/detectors/ssn.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module PiiScrubber
+  module Detectors
+    class Ssn < Base
+      SSN_REGEX = /\b(?!000|666|9\d{2})\d{3}[ -]?(?!00)\d{2}[ -]?(?!0000)\d{4}\b/
+
+      def initialize
+        super(name: :ssn)
+      end
+
+      def patterns
+        [SSN_REGEX]
+      end
+
+      def replace(match, strategy: :placeholder, mask_char: "*", hmac_salt: nil)
+        return super unless strategy == :mask
+
+        digits = match.scan(/\d/)
+        return super if digits.size < 4
+
+        last_four = digits.last(4).join
+        "***-**-#{last_four}"
+      end
+    end
+  end
+end

data/lib/pii_scrubber/detectors/uk_nino.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module PiiScrubber
+  module Detectors
+    class UkNino < Base
+      # Matches UK National Insurance numbers (e.g., QQ123456A, QQ 12 34 56 A, QQ-12-34-56-A)
+      UK_NINO_REGEX = /\b[A-Za-z]{2}[ -]?[0-9]{2}[ -]?[0-9]{2}[ -]?[0-9]{2}[ -]?[A-Da-d]\b/
+
+      DISALLOWED_PREFIXES = %w[GB BG NK KN TN NT ZZ].freeze
+      DISALLOWED_CHARS = %w[D F I U V].freeze
+
+      def initialize
+        super(name: :uk_nino)
+      end
+
+      def patterns
+        [UK_NINO_REGEX]
+      end
+
+      def valid?(match)
+        sanitized = match.gsub(/[\s-]/, "").upcase
+        return false unless sanitized.length == 9
+
+        prefix = sanitized[0..1]
+        return false if DISALLOWED_PREFIXES.include?(prefix)
+
+        # Characters D, F, I, U, V are disallowed in first or second position
+        # Character O is disallowed in second position
+        return false if DISALLOWED_CHARS.include?(sanitized[0])
+        return false if (DISALLOWED_CHARS + ["O"]).include?(sanitized[1])
+
+        true
+      end
+
+      def replace(match, strategy: :placeholder, mask_char: "*", hmac_salt: nil)
+        return super unless strategy == :mask
+
+        sanitized = match.gsub(/[\s-]/, "").upcase
+        return super if sanitized.length != 9
+
+        prefix = sanitized[0..1]
+        suffix = sanitized[-1]
+        "#{prefix}#{mask_char * 6}#{suffix}"
+      end
+    end
+  end
+end

data/lib/pii_scrubber/integrations/faraday_middleware.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module PiiScrubber
+  module Integrations
+    class FaradayMiddleware
+      SENSITIVE_HEADERS = %w[authorization cookie x-api-key x-auth-token set-cookie].freeze
+
+      attr_reader :app, :options
+
+      def initialize(app, options = {})
+        @app = app
+        @options = options
+      end
+
+      def call(env)
+        sanitize_request(env)
+
+        @app.call(env).on_complete do |response_env|
+          sanitize_response(response_env)
+        end
+      end
+
+      private
+
+      def sanitize_request(env)
+        if env.request_headers
+          SENSITIVE_HEADERS.each do |hdr|
+            env.request_headers.keys.each do |key|
+              if key.to_s.downcase == hdr
+                env.request_headers[key] = PiiScrubber.scrub(env.request_headers[key].to_s, **options)
+              end
+            end
+          end
+        end
+
+        if env.body.is_a?(String) || env.body.is_a?(Hash)
+          env.body = PiiScrubber.scrub(env.body, **options)
+        end
+      end
+
+      def sanitize_response(env)
+        if env.response_body.is_a?(String) || env.response_body.is_a?(Hash)
+          env.response_body = PiiScrubber.scrub(env.response_body, **options)
+        end
+      end
+    end
+  end
+end

data/lib/pii_scrubber/integrations/logger_formatter.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "logger"
+
+module PiiScrubber
+  module Integrations
+    class LoggerFormatter < ::Logger::Formatter
+      attr_reader :original_formatter, :options
+
+      def initialize(original_formatter = nil, **options)
+        super()
+        @original_formatter = original_formatter || ::Logger::Formatter.new
+        @options = options
+      end
+
+      def call(severity, time, program_name, message)
+        scrubbed_msg = format_message(message)
+        if original_formatter.respond_to?(:call)
+          original_formatter.call(severity, time, program_name, scrubbed_msg)
+        else
+          super(severity, time, program_name, scrubbed_msg)
+        end
+      end
+
+      private
+
+      def format_message(msg)
+        case msg
+        when String
+          PiiScrubber.scrub(msg, **options)
+        when Hash, Array
+          PiiScrubber.scrub(msg, **options)
+        when Exception
+          "#{msg.class}: #{PiiScrubber.scrub(msg.message, **options)}"
+        else
+          msg.inspect
+        end
+      end
+    end
+  end
+end

data/lib/pii_scrubber/integrations/rack_middleware.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module PiiScrubber
+  module Integrations
+    class RackMiddleware
+      attr_reader :app, :options
+
+      def initialize(app, options = {})
+        @app = app
+        @options = options
+      end
+
+      def call(env)
+        sanitize_rack_env(env)
+        @app.call(env)
+      end
+
+      private
+
+      def sanitize_rack_env(env)
+        # Sanitize query string parameters
+        if env["QUERY_STRING"] && !env["QUERY_STRING"].empty?
+          env["QUERY_STRING"] = PiiScrubber.scrub(env["QUERY_STRING"], **options)
+        end
+
+        # Sanitize Rack request params (ActionDispatch / Rack::Request)
+        if env["rack.request.form_hash"].is_a?(Hash)
+          env["rack.request.form_hash"] = PiiScrubber.scrub(env["rack.request.form_hash"], **options)
+        end
+
+        if env["action_dispatch.request.parameters"].is_a?(Hash)
+          env["action_dispatch.request.parameters"] = PiiScrubber.scrub(env["action_dispatch.request.parameters"], **options)
+        end
+      end
+    end
+  end
+end

data/lib/pii_scrubber/scrubber.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+require "json"
+
+module PiiScrubber
+  class Scrubber
+    BUILT_IN_DETECTORS = {
+      email: Detectors::Email,
+      phone: Detectors::Phone,
+      ssn: Detectors::Ssn,
+      credit_card: Detectors::CreditCard,
+      api_key: Detectors::ApiKey,
+      ip_address: Detectors::IpAddress,
+      iban: Detectors::Iban,
+      uk_nino: Detectors::UkNino,
+      canadian_sin: Detectors::CanadianSin,
+      indian_pan: Detectors::IndianPan,
+      indian_aadhaar: Detectors::IndianAadhaar,
+      database_url: Detectors::DatabaseUrl
+    }.freeze
+
+    attr_reader :config
+
+    def initialize(config = PiiScrubber.configuration)
+      @config = config
+      @active_detectors = build_detectors
+    end
+
+    def scrub(data, **override_options)
+      strategy = override_options[:strategy] || config.strategy
+      mask_char = override_options[:mask_char] || config.mask_char
+      hmac_salt = override_options[:hmac_salt] || config.hmac_salt
+      ignored_keys = (override_options[:ignored_keys] || config.ignored_keys).map(&:to_s)
+
+      case data
+      when String
+        scrub_string(data, strategy: strategy, mask_char: mask_char, hmac_salt: hmac_salt)
+      when Hash
+        scrub_hash(data, strategy: strategy, mask_char: mask_char, hmac_salt: hmac_salt, ignored_keys: ignored_keys)
+      when Array
+        data.map { |item| scrub(item, **override_options) }
+      else
+        data
+      end
+    end
+
+    private
+
+    def build_detectors
+      detectors = []
+      enabled_names = config.detectors.map(&:to_sym)
+
+      enabled_names.each do |name|
+        detector_class = BUILT_IN_DETECTORS[name]
+        detectors << detector_class.new if detector_class
+      end
+
+      config.custom_rules.each do |rule|
+        if rule.is_a?(Detectors::Base)
+          detectors << rule
+        elsif rule.is_a?(Hash) && rule[:name] && rule[:pattern]
+          detectors << create_custom_detector(rule[:name], rule[:pattern], rule[:validator])
+        end
+      end
+
+      detectors
+    end
+
+    def create_custom_detector(name, pattern, validator = nil)
+      detector = Detectors::Base.new(name: name)
+      pattern_arr = Array(pattern)
+      detector.define_singleton_method(:patterns) { pattern_arr }
+      if validator
+        detector.define_singleton_method(:valid?) { |match| validator.call(match) }
+      end
+      detector
+    end
+
+    def scrub_string(str, strategy:, mask_char:, hmac_salt:)
+      return str if str.nil? || str.empty?
+
+      # If string is valid JSON, attempt JSON-aware scrubbing first
+      if json_string?(str)
+        begin
+          parsed = JSON.parse(str)
+          scrubbed = scrub(parsed, strategy: strategy, mask_char: mask_char, hmac_salt: hmac_salt)
+          return JSON.generate(scrubbed)
+        rescue JSON::ParserError
+          # Fallback to normal string replacement if parsing fails
+        end
+      end
+
+      result = str.dup
+
+      @active_detectors.each do |detector|
+        detector.patterns.each do |pattern|
+          result.gsub!(pattern) do |match|
+            if detector.valid?(match)
+              detector.replace(match, strategy: strategy, mask_char: mask_char, hmac_salt: hmac_salt)
+            else
+              match
+            end
+          end
+        end
+      end
+
+      result
+    end
+
+    def scrub_hash(hash, strategy:, mask_char:, hmac_salt:, ignored_keys:)
+      hash.each_with_object({}) do |(key, value), acc|
+        str_key = key.to_s
+        if ignored_keys.include?(str_key)
+          acc[key] = value
+        elsif config.redact_sensitive_hash_keys && sensitive_key?(str_key)
+          acc[key] = redact_sensitive_value(value, key_name: str_key, strategy: strategy, mask_char: mask_char, hmac_salt: hmac_salt)
+        else
+          acc[key] = scrub(value, strategy: strategy, mask_char: mask_char, hmac_salt: hmac_salt, ignored_keys: ignored_keys)
+        end
+      end
+    end
+
+    def sensitive_key?(key_str)
+      config.sensitive_key_patterns.any? { |pattern| key_str.match?(pattern) }
+    end
+
+    def redact_sensitive_value(value, key_name:, strategy:, mask_char:, hmac_salt:)
+      detector = Detectors::Base.new(name: key_name)
+      if value.is_a?(String)
+        detector.replace(value, strategy: strategy, mask_char: mask_char, hmac_salt: hmac_salt)
+      else
+        "[REDACTED:#{key_name.upcase}]"
+      end
+    end
+
+    def json_string?(str)
+      trimmed = str.strip
+      (trimmed.start_with?("{") && trimmed.end_with?("}")) || (trimmed.start_with?("[") && trimmed.end_with?("]"))
+    end
+  end
+end

data/lib/pii_scrubber/vault/session.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "time"
+
+module PiiScrubber
+  class Vault
+    class Session
+      attr_reader :id, :text, :mappings, :created_at
+
+      def initialize(text:, mappings:, id: nil, created_at: nil)
+        @id = id || SecureRandom.hex(8)
+        @text = text
+        @mappings = mappings || {}
+        @created_at = created_at || Time.now.utc
+      end
+
+      # Restores original values in text, hashes, or arrays containing vault placeholders
+      def restore(data)
+        case data
+        when String
+          restore_string(data)
+        when Hash
+          restore_hash(data)
+        when Array
+          data.map { |item| restore(item) }
+        else
+          data
+        end
+      end
+
+      # Serializes session for storing in Redis, Memcached, or Rails sessions
+      def to_h
+        {
+          "id" => id,
+          "text" => text,
+          "mappings" => mappings,
+          "created_at" => created_at.iso8601
+        }
+      end
+
+      # Deserializes session from Hash
+      def self.from_h(hash)
+        return nil if hash.nil?
+
+        new(
+          id: hash["id"] || hash[:id],
+          text: hash["text"] || hash[:text],
+          mappings: hash["mappings"] || hash[:mappings] || {},
+          created_at: hash["created_at"] ? Time.parse(hash["created_at"].to_s) : Time.now.utc
+        )
+      end
+
+      private
+
+      def restore_string(str)
+        return str if str.nil? || str.empty? || mappings.empty?
+
+        result = str.dup
+        mappings.each do |placeholder, original_value|
+          result.gsub!(placeholder, original_value.to_s)
+        end
+        result
+      end
+
+      def restore_hash(hash)
+        hash.each_with_object({}) do |(key, value), acc|
+          acc[key] = restore(value)
+        end
+      end
+    end
+  end
+end