mask-pii 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4b8364569252025ebce46522149831dccc170b742f479a4549ea8396fba350f3
+  data.tar.gz: 5fb7d89b4ae0638f8bdf348af4640713c5e812f51174769543cdbde7c37d4bd7
+SHA512:
+  metadata.gz: 4f2ce3d554d77719f8961b186daa21f6bc57e286387094e0190ca783d5c10f98604aed271889d9180770a8e13dfc58fb97fb23d41bfa4426c046099018251c5a
+  data.tar.gz: 7ea311f2d8be27f324cbf671e9f63db98ed2c13cb03949089492ec00d0c5a656ccb6cc4526fdd9b081401da49547922479099c2d0583c50bd76f064d09e0fa2a

data/README.md

@@ -0,0 +1,85 @@
+# mask-pii (Ruby)
+
+Version: 0.2.0
+
+A lightweight, customizable Ruby library for masking Personally Identifiable Information (PII) such as **email addresses** and **phone numbers**.
+
+It is designed to be safe, fast, and easy to integrate into logging or data processing pipelines.
+
+Official website: [https://finitefield.org/en/oss/mask-pii](https://finitefield.org/en/oss/mask-pii)
+Developed by: [Finite Field, K.K.](https://finitefield.org)
+
+## Features
+
+- **Email Masking:** Masks the local part while preserving the domain (e.g., `a****@example.com`).
+- **Global Phone Masking:** Detects international phone formats and masks all digits except the last 4.
+- **Customizable:** Change the masking character (default is `*`).
+- **Zero Unnecessary Dependencies:** Pure Ruby implementation.
+
+## Installation
+
+Add this to your `Gemfile`:
+
+```ruby
+gem "mask-pii", path: "../mask-pii/ruby"
+```
+
+Or install from a packaged gem:
+
+```bash
+gem install mask-pii
+```
+
+## Publishing
+
+From the `ruby` directory:
+
+```bash
+gem build mask-pii.gemspec
+gem push mask-pii-0.1.0.gem
+```
+
+## Usage
+
+```ruby
+require "mask_pii"
+
+masker = MaskPII::Masker.new
+  .mask_emails
+  .mask_phones
+  .with_mask_char("#")
+
+input = "Contact: alice@example.com or 090-1234-5678."
+output = masker.process(input)
+
+puts output
+# => "Contact: a####@example.com or 090-####-5678."
+```
+
+## Configuration
+
+The `Masker` class uses a builder-style API. By default, `Masker.new` performs **no masking** (pass-through).
+
+### Builder Methods
+
+| Method | Description | Default |
+| --- | --- | --- |
+| `mask_emails` | Enables detection and masking of email addresses. | Disabled |
+| `mask_phones` | Enables detection and masking of global phone numbers. | Disabled |
+| `with_mask_char(char)` | Sets the character used for masking (e.g., `"*"`, `"#"`, `"x"`). | `"*"` |
+
+### Masking Logic Details
+
+**Emails**
+- **Pattern:** Detects standard email formats.
+- **Behavior:** Keeps the first character of the local part and the domain. Masks the rest of the local part.
+- **Example:** `alice@example.com` -> `a****@example.com`
+- **Short Emails:** If the local part is 1 character, it is fully masked (e.g., `a@b.com` -> `*@b.com`).
+
+**Phones (Global Support)**
+- **Pattern:** Detects sequences of digits that look like phone numbers (supports international `+81...`, US `(555)...`, and hyphenated `090-...`).
+- **Behavior:** Preserves formatting (hyphens, spaces, parentheses) and the **last 4 digits**. All other digits are replaced.
+- **Examples:**
+  - `090-1234-5678` -> `090-****-5678`
+  - `+1 (800) 123-4567` -> `+1 (***) ***-4567`
+  - `12345` -> `*2345`

data/lib/mask_pii/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module MaskPII
+  # The current version of the mask-pii Ruby gem.
+  VERSION = "0.2.0"
+end

data/lib/mask_pii.rb

@@ -0,0 +1,230 @@
+# frozen_string_literal: true
+
+require "mask_pii/version"
+
+# Top-level namespace for the mask-pii Ruby library.
+module MaskPII
+  # A configurable masker for common PII such as emails and phone numbers.
+  class Masker
+    # Create a new masker with all masks disabled by default.
+    def initialize
+      @mask_email = false
+      @mask_phone = false
+      @mask_char = "*"
+    end
+
+    # Enable email address masking.
+    # @return [Masker] the current masker instance
+    def mask_emails
+      @mask_email = true
+      self
+    end
+
+    # Enable phone number masking.
+    # @return [Masker] the current masker instance
+    def mask_phones
+      @mask_phone = true
+      self
+    end
+
+    # Set the character used for masking.
+    # @param char [String] a single-character string to use for masking
+    # @return [Masker] the current masker instance
+    def with_mask_char(char)
+      @mask_char = char.to_s[0] || "*"
+      self
+    end
+
+    # Process input text and mask enabled PII patterns.
+    # @param input [String] text to scan and mask
+    # @return [String] masked output text
+    def process(input)
+      result = input.to_s.dup
+
+      result = mask_emails_in_text(result) if @mask_email
+      result = mask_phones_in_text(result) if @mask_phone
+
+      result
+    end
+
+    private
+
+    def mask_emails_in_text(text)
+      bytes = text.bytes
+      len = bytes.length
+      output = String.new(encoding: text.encoding)
+      last = 0
+      i = 0
+
+      while i < len
+        if bytes[i] == 64
+          local_start = i
+          while local_start > 0 && local_char?(bytes[local_start - 1])
+            local_start -= 1
+          end
+          local_end = i
+
+          domain_start = i + 1
+          domain_end = domain_start
+          while domain_end < len && domain_char?(bytes[domain_end])
+            domain_end += 1
+          end
+
+          if local_start < local_end && domain_start < domain_end
+            candidate_end = domain_end
+            matched_domain_end = nil
+            while candidate_end > domain_start
+              domain = slice_bytes(text, domain_start, candidate_end - domain_start)
+              if valid_domain?(domain)
+                matched_domain_end = candidate_end
+                break
+              end
+              candidate_end -= 1
+            end
+
+            if matched_domain_end
+              local = slice_bytes(text, local_start, local_end - local_start)
+              domain = slice_bytes(text, domain_start, matched_domain_end - domain_start)
+              output << slice_bytes(text, last, local_start - last)
+              output << mask_local(local)
+              output << "@"
+              output << domain
+              last = matched_domain_end
+              i = matched_domain_end
+              next
+            end
+          end
+        end
+
+        i += 1
+      end
+
+      output << slice_bytes(text, last, len - last)
+      output
+    end
+
+    def mask_phones_in_text(text)
+      bytes = text.bytes
+      len = bytes.length
+      output = String.new(encoding: text.encoding)
+      last = 0
+      i = 0
+
+      while i < len
+        if phone_start?(bytes[i])
+          end_index = i
+          while end_index < len && phone_char?(bytes[end_index])
+            end_index += 1
+          end
+
+          digit_count = 0
+          last_digit = nil
+          idx = i
+          while idx < end_index
+            if digit?(bytes[idx])
+              digit_count += 1
+              last_digit = idx
+            end
+            idx += 1
+          end
+
+          if last_digit && digit_count >= 5
+            candidate_end = last_digit + 1
+            candidate = slice_bytes(text, i, candidate_end - i)
+            output << slice_bytes(text, last, i - last)
+            output << mask_phone_candidate(candidate)
+            last = candidate_end
+            i = candidate_end
+            next
+          end
+
+          i = end_index
+          next
+        end
+
+        i += 1
+      end
+
+      output << slice_bytes(text, last, len - last)
+      output
+    end
+
+    def mask_local(local)
+      if local.bytesize > 1
+        slice_bytes(local, 0, 1) + (@mask_char * (local.bytesize - 1))
+      else
+        @mask_char
+      end
+    end
+
+    def mask_phone_candidate(candidate)
+      bytes = candidate.bytes
+      digit_count = bytes.count { |byte| digit?(byte) }
+      current_index = 0
+      output = String.new(encoding: candidate.encoding)
+
+      bytes.each do |byte|
+        if digit?(byte)
+          current_index += 1
+          if digit_count > 4 && current_index <= digit_count - 4
+            output << @mask_char
+          else
+            output << byte
+          end
+        else
+          output << byte
+        end
+      end
+
+      output
+    end
+
+    def slice_bytes(text, start_index, length)
+      slice = text.byteslice(start_index, length)
+      slice.force_encoding(text.encoding)
+    end
+
+    def local_char?(byte)
+      alpha?(byte) || digit?(byte) || byte == 46 || byte == 95 || byte == 37 || byte == 43 || byte == 45
+    end
+
+    def domain_char?(byte)
+      alpha?(byte) || digit?(byte) || byte == 45 || byte == 46
+    end
+
+    def valid_domain?(domain)
+      return false if domain.start_with?(".") || domain.end_with?(".")
+
+      parts = domain.split(".")
+      return false if parts.length < 2
+
+      parts.each do |part|
+        return false if part.empty?
+        return false if part.start_with?("-") || part.end_with?("-")
+        return false unless part.bytes.all? { |byte| alpha?(byte) || digit?(byte) || byte == 45 }
+      end
+
+      tld = parts.last
+      return false if tld.length < 2
+      return false unless tld.bytes.all? { |byte| alpha?(byte) }
+
+      true
+    end
+
+    def phone_start?(byte)
+      digit?(byte) || byte == 43 || byte == 40
+    end
+
+    def phone_char?(byte)
+      digit?(byte) || byte == 32 || byte == 45 || byte == 40 || byte == 41 || byte == 43
+    end
+
+    def digit?(byte)
+      byte >= 48 && byte <= 57
+    end
+
+    def alpha?(byte)
+      (byte >= 65 && byte <= 90) || (byte >= 97 && byte <= 122)
+    end
+  end
+end

data/test/test_mask_pii.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+require "minitest/autorun"
+require "mask_pii"
+
+class TestMaskPII < Minitest::Test
+  def test_email_basic_cases
+    masker = MaskPII::Masker.new.mask_emails
+    assert_cases(
+      masker,
+      "alice@example.com" => "a****@example.com",
+      "a@b.com" => "*@b.com",
+      "ab@example.com" => "a*@example.com",
+      "a.b+c_d@example.co.jp" => "a******@example.co.jp"
+    )
+  end
+
+  def test_email_mixed_text
+    masker = MaskPII::Masker.new.mask_emails
+    assert_cases(
+      masker,
+      "Contact: alice@example.com." => "Contact: a****@example.com.",
+      "alice@example.com and bob@example.org" => "a****@example.com and b**@example.org"
+    )
+  end
+
+  def test_email_edge_cases
+    masker = MaskPII::Masker.new.mask_emails
+    assert_cases(
+      masker,
+      "alice@example" => "alice@example",
+      "alice@localhost" => "alice@localhost",
+      "alice@@example.com" => "alice@@example.com",
+      "first.last+tag@sub.domain.com" => "f*************@sub.domain.com"
+    )
+  end
+
+  def test_phone_basic_formats
+    masker = MaskPII::Masker.new.mask_phones
+    assert_cases(
+      masker,
+      "090-1234-5678" => "***-****-5678",
+      "Call (555) 123-4567" => "Call (***) ***-4567",
+      "Intl: +81 3 1234 5678" => "Intl: +** * **** 5678",
+      "+1 (800) 123-4567" => "+* (***) ***-4567"
+    )
+  end
+
+  def test_phone_short_and_boundary_lengths
+    masker = MaskPII::Masker.new.mask_phones
+    assert_cases(
+      masker,
+      "1234" => "1234",
+      "12345" => "*2345",
+      "12-3456" => "**-3456"
+    )
+  end
+
+  def test_phone_mixed_text
+    masker = MaskPII::Masker.new.mask_phones
+    assert_cases(
+      masker,
+      "Tel: 090-1234-5678 ext. 99" => "Tel: ***-****-5678 ext. 99",
+      "Numbers: 111-2222 and 333-4444" => "Numbers: ***-2222 and ***-4444"
+    )
+  end
+
+  def test_phone_edge_cases
+    masker = MaskPII::Masker.new.mask_phones
+    assert_cases(
+      masker,
+      "abcdef" => "abcdef",
+      "+" => "+",
+      "(12) 345 678" => "(**) **5 678"
+    )
+  end
+
+  def test_combined_masking
+    masker = MaskPII::Masker.new.mask_emails.mask_phones
+    assert_cases(
+      masker,
+      "Contact: alice@example.com or 090-1234-5678." => "Contact: a****@example.com or ***-****-5678.",
+      "Email bob@example.org, phone +1 (800) 123-4567" => "Email b**@example.org, phone +* (***) ***-4567"
+    )
+  end
+
+  def test_custom_mask_character
+    email_masker = MaskPII::Masker.new.mask_emails.with_mask_char("#")
+    phone_masker = MaskPII::Masker.new.mask_phones.with_mask_char("#")
+    combined = MaskPII::Masker.new.mask_emails.mask_phones.with_mask_char("#")
+
+    assert_cases(
+      email_masker,
+      "alice@example.com" => 'a####@example.com'
+    )
+
+    assert_cases(
+      phone_masker,
+      "090-1234-5678" => "###-####-5678"
+    )
+
+    assert_equal 'Contact: a####@example.com or ###-####-5678.',
+                 combined.process("Contact: alice@example.com or 090-1234-5678.")
+  end
+
+  def test_masker_configuration
+    input = "alice@example.com 090-1234-5678"
+
+    assert_equal input, MaskPII::Masker.new.process(input)
+
+    email_only = MaskPII::Masker.new.mask_emails
+    assert_equal "a****@example.com 090-1234-5678", email_only.process(input)
+
+    phone_only = MaskPII::Masker.new.mask_phones
+    assert_equal "alice@example.com ***-****-5678", phone_only.process(input)
+
+    both = MaskPII::Masker.new.mask_emails.mask_phones
+    assert_equal "a****@example.com ***-****-5678", both.process(input)
+  end
+
+  def test_non_ascii_text_is_preserved
+    masker = MaskPII::Masker.new.mask_emails.mask_phones
+    input = "連絡先: alice@example.com と 090-1234-5678"
+    expected = "連絡先: a****@example.com と ***-****-5678"
+    assert_equal expected, masker.process(input)
+  end
+
+  private
+
+  def assert_cases(masker, cases)
+    cases.each do |input, expected|
+      assert_equal expected, masker.process(input)
+    end
+  end
+end

metadata

@@ -0,0 +1,51 @@
+--- !ruby/object:Gem::Specification
+name: mask-pii
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- Finite Field, K.K.
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-01-28 00:00:00.000000000 Z
+dependencies: []
+description: A lightweight, customizable Ruby library for masking PII such as email
+  addresses and phone numbers.
+email:
+- dev@finitefield.org
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/mask_pii.rb
+- lib/mask_pii/version.rb
+- test/test_mask_pii.rb
+homepage: https://finitefield.org/en/oss/mask-pii
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://finitefield.org/en/oss/mask-pii
+  source_code_uri: https://github.com/finitefield-org/mask-pii
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.9
+signing_key:
+specification_version: 4
+summary: A lightweight library to mask PII (emails and phone numbers).
+test_files: []