unicode_script_detector 0.0.9 → 0.0.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6177527dc52eecfb0fbeb31e8f901d1138eb3fa5df70317e52cfe82d5d4a1071
-  data.tar.gz: a4a289cb631b4099db822fa888183c29ef6c029b5a0d5f3e29fa177e243a5132
+  metadata.gz: 5552c7feac6b52cd98f1de0442768436f0cd801d8e491bffdac9509e87648490
+  data.tar.gz: 85ea21ac13d2c71e770802cd9a8259d74ee0542c86ee4d799470f311585c8dbe
 SHA512:
-  metadata.gz: b395eb587afebc6fbeeb834792bf6eff0d93a0c771290fb7aa27d771fbb443fc53acb4b95c0fc0674cb09cb12a917d612fe81455725ac78be6dfc77222eda4a2
-  data.tar.gz: 843f272dce94bcfc212965befc382e837d37c4a959389c836d829968fef6040de553b12b0e2c9b6da7d6625045877d9a6f310adb41f2c504cb99f730a8b07335
+  metadata.gz: 92f1a69dd82c2878830cd01d9370368d7590d074717df5f5fb61f05de946805a92c0a244b25f003d637f91ae9f754610141947de615fa8a8d9c4e8276cd3adc7
+  data.tar.gz: 3c0384fba23a30c4efd68eecba7a4e6db2396df46318c905af355cdf90aecfd8ffb29d634023bb8a9e18c33314d2ad8beb7410fe208edd708acd5a0159aaa1d8

data/README.md

@@ -62,9 +62,38 @@ Latin: you (3 characters)
 Punctuation: ? (1 characters)
 ```
 
+## Get a homographic spoof analysis
+```ruby
+UnicodeScriptDetector.spoof_analysis "Раypal"
+=>
+[
+  #<struct UnicodeScriptDetector::SpoofDetector::Detection
+  type=:confusable,
+  message="Found 2 character(s) from non-Latin scripts that visually resemble Latin letters",
+  characters=[
+    #<struct UnicodeScriptDetector::SpoofDetector::ConfusableChar char="Р", script="Cyrillic", looks_like="P", position=0>,
+    #<struct UnicodeScriptDetector::SpoofDetector::ConfusableChar char="а", script="Cyrillic", looks_like="a", position=1>
+  ],
+  severity=:high>,
+  
+  #<struct UnicodeScriptDetector::SpoofDetector::Detection
+  type=:mixed_scripts,
+  message="Text contains a mix of 2 scripts: Cyrillic, Latin",
+  characters=["Cyrillic", "Latin"],
+  severity=:medium>
+]
+```
+
+## Check whether a homograph spoof is detected
+```ruby
+UnicodeScriptDetector.spoofed? "Раypal"
+=> true
+```
+
 ## Development
-Start the console with `bin/console`.
-Run the tests with `bin/test`.
+- Start the console with `bin/console`.
+- Run the tests with `bin/test`.
+- Update confusables list from unicode.org with `rake update_confusables`
 
 ## Contributing
 You're welcome to contribute to this project. See https://github.com/davidarendsen/unicode_script_detector.

data/lib/unicode_script_detector/confusables.rb

@@ -0,0 +1,178 @@
+require 'set'
+
+module UnicodeScriptDetector
+  module Confusables
+    # Curated mapping of characters that visually resemble Latin letters.
+    # AUTO-GENERATED from https://unicode.org/Public/security/latest/confusables.txt
+    # Run `rake update_confusables` to regenerate.
+    MAPPING = {
+
+      # Cyrillic → Latin
+      'Ѕ' => 'S',   # U+0405
+      'І' => 'l',   # U+0406
+      'Ј' => 'J',   # U+0408
+      'А' => 'A',   # U+0410
+      'В' => 'B',   # U+0412
+      'Е' => 'E',   # U+0415
+      'З' => '3',   # U+0417
+      'К' => 'K',   # U+041A
+      'М' => 'M',   # U+041C
+      'Н' => 'H',   # U+041D
+      'О' => 'O',   # U+041E
+      'Р' => 'P',   # U+0420
+      'С' => 'C',   # U+0421
+      'Т' => 'T',   # U+0422
+      'У' => 'Y',   # U+0423
+      'Х' => 'X',   # U+0425
+      'Ь' => 'b',   # U+042C
+      'а' => 'a',   # U+0430
+      'б' => '6',   # U+0431
+      'г' => 'r',   # U+0433
+      'е' => 'e',   # U+0435
+      'о' => 'o',   # U+043E
+      'р' => 'p',   # U+0440
+      'с' => 'c',   # U+0441
+      'у' => 'y',   # U+0443
+      'х' => 'x',   # U+0445
+      'ш' => 'w',   # U+0448
+      'ѕ' => 's',   # U+0455
+      'і' => 'i',   # U+0456
+      'ј' => 'j',   # U+0458
+      'ѡ' => 'w',   # U+0461
+      'Ѵ' => 'V',   # U+0474
+      'ѵ' => 'v',   # U+0475
+      'Ү' => 'Y',   # U+04AE
+      'ү' => 'y',   # U+04AF
+      'һ' => 'h',   # U+04BB
+      'ҽ' => 'e',   # U+04BD
+      'Ӏ' => 'l',   # U+04C0
+      'ӏ' => 'l',   # U+04CF
+      'Ӡ' => '3',   # U+04E0
+      'ԁ' => 'd',   # U+0501
+      'Ԍ' => 'G',   # U+050C
+      'ԛ' => 'q',   # U+051B
+      'Ԝ' => 'W',   # U+051C
+      'ԝ' => 'w',   # U+051D
+
+      # Greek → Latin
+      'ͺ' => 'i',   # U+037A
+      'Ϳ' => 'J',   # U+037F
+      'Α' => 'A',   # U+0391
+      'Β' => 'B',   # U+0392
+      'Ε' => 'E',   # U+0395
+      'Ζ' => 'Z',   # U+0396
+      'Η' => 'H',   # U+0397
+      'Ι' => 'l',   # U+0399
+      'Κ' => 'K',   # U+039A
+      'Μ' => 'M',   # U+039C
+      'Ν' => 'N',   # U+039D
+      'Ο' => 'O',   # U+039F
+      'Ρ' => 'P',   # U+03A1
+      'Τ' => 'T',   # U+03A4
+      'Υ' => 'Y',   # U+03A5
+      'Χ' => 'X',   # U+03A7
+      'α' => 'a',   # U+03B1
+      'γ' => 'y',   # U+03B3
+      'ι' => 'i',   # U+03B9
+      'ν' => 'v',   # U+03BD
+      'ο' => 'o',   # U+03BF
+      'ρ' => 'p',   # U+03C1
+      'σ' => 'o',   # U+03C3
+      'υ' => 'u',   # U+03C5
+      'ϒ' => 'Y',   # U+03D2
+      'Ϝ' => 'F',   # U+03DC
+      'Ϩ' => '2',   # U+03E8
+      'Ϭ' => '6',   # U+03EC
+      'ϭ' => 'o',   # U+03ED
+      'ϱ' => 'p',   # U+03F1
+      'ϲ' => 'c',   # U+03F2
+      'ϳ' => 'j',   # U+03F3
+      'ϸ' => 'p',   # U+03F8
+      'Ϲ' => 'C',   # U+03F9
+      'Ϻ' => 'M',   # U+03FA
+
+      # Armenian → Latin
+      'Ս' => 'U',   # U+054D
+      'Տ' => 'S',   # U+054F
+      'Օ' => 'O',   # U+0555
+      'ա' => 'w',   # U+0561
+      'գ' => 'q',   # U+0563
+      'զ' => 'q',   # U+0566
+      'հ' => 'h',   # U+0570
+      'ո' => 'n',   # U+0578
+      'ռ' => 'n',   # U+057C
+      'ս' => 'u',   # U+057D
+      'ց' => 'g',   # U+0581
+      'ւ' => 'i',   # U+0582
+      'ք' => 'f',   # U+0584
+      'օ' => 'o',   # U+0585
+
+      # Georgian → Latin
+      'ყ' => 'y',   # U+10E7
+      'ჿ' => 'o',   # U+10FF
+
+      # Hebrew → Latin
+      '׀' => 'l',   # U+05C0
+      'ו' => 'l',   # U+05D5
+      'ט' => 'v',   # U+05D8
+      'ן' => 'l',   # U+05DF
+      'ס' => 'o',   # U+05E1
+
+      # Ethiopic → Latin
+      'ሀ' => 'U',   # U+1200
+      'ዐ' => 'O',   # U+12D0
+    }.freeze
+
+    INVISIBLE_CHARACTERS = [
+      "\u200B", # Zero-width space
+      "\u200C", # Zero-width non-joiner
+      "\u200D", # Zero-width joiner
+      "\u200E", # Left-to-right mark
+      "\u200F", # Right-to-left mark
+      "\uFEFF", # Zero-width no-break space (BOM)
+      "\u2060", # Word joiner
+      "\u00AD", # Soft hyphen
+      "\u180E", # Mongolian vowel separator
+      "\u2061", # Function application
+      "\u2062", # Invisible times
+      "\u2063", # Invisible separator
+      "\u2064" # Invisible plus
+    ].freeze
+
+    DIRECTIONAL_OVERRIDES = [
+      "\u202A", # Left-to-right embedding
+      "\u202B", # Right-to-left embedding
+      "\u202C", # Pop directional formatting
+      "\u202D", # Left-to-right override
+      "\u202E" # Right-to-left override
+    ].freeze
+
+    SAFE_SCRIPT_COMBINATIONS = [
+      Set[:Latin, :Han, :Hiragana, :Katakana],
+      Set[:Latin, :Han, :Bopomofo],
+      Set[:Latin, :Han, :Hangul],
+      Set[:Hiragana, :Katakana, :Han],
+      Set[:Latin, :Inherited],
+      Set[:Latin, :Common],
+      Set[:Latin, :Punctuation],
+      Set[:Latin, :Digit],
+      Set[:Latin, :Whitespace]
+    ].freeze
+
+    def self.confusable?(char)
+      MAPPING.key?(char)
+    end
+
+    def self.looks_like(char)
+      MAPPING[char]
+    end
+
+    def self.invisible?(char)
+      INVISIBLE_CHARACTERS.include?(char)
+    end
+
+    def self.directional_override?(char)
+      DIRECTIONAL_OVERRIDES.include?(char)
+    end
+  end
+end

data/lib/unicode_script_detector/spoof_detector.rb

@@ -0,0 +1,172 @@
+module UnicodeScriptDetector
+  class SpoofDetector
+    Detection = Struct.new(:type, :message, :characters, :severity, keyword_init: true)
+    ConfusableChar = Struct.new(:char, :script, :looks_like, :position, keyword_init: true)
+    InvisibleChar = Struct.new(:char, :codepoint, :name, :position, keyword_init: true)
+
+    SEVERITY_HIGH = :high
+    SEVERITY_MEDIUM = :medium
+    SEVERITY_LOW = :low
+
+    def initialize(string)
+      @string = string.to_s
+      @detections = nil
+    end
+
+    # Returns all spoof detections found in the string
+    def detections
+      @detections ||= [
+        detect_confusables,
+        detect_invisible_characters,
+        detect_directional_overrides,
+        detect_mixed_scripts
+      ].compact
+    end
+
+    # Returns true if any spoofing is detected
+    def spoofed?
+      detections.any?
+    end
+
+    # Returns only confusable character detections
+    def confusables
+      detections.select { |d| d.type == :confusable }
+    end
+
+    # Returns only invisible character detections
+    def invisible_characters
+      detections.select { |d| d.type == :invisible }
+    end
+
+    # Returns only mixed script detections
+    def mixed_scripts
+      detections.select { |d| d.type == :mixed_scripts }
+    end
+
+    private
+
+    attr_reader :string
+
+    def detect_confusables
+      found = []
+
+      string.chars.each_with_index do |char, idx|
+        if Confusables.confusable?(char)
+          script = detect_script_for_char(char)
+          found << ConfusableChar.new(
+            char: char,
+            script: script[:name],
+            looks_like: Confusables.looks_like(char),
+            position: idx
+          )
+        end
+      end
+
+      return nil if found.empty?
+
+      Detection.new(
+        type: :confusable,
+        message: "Found #{found.length} character(s) from non-Latin scripts that visually resemble Latin letters",
+        characters: found,
+        severity: SEVERITY_HIGH
+      )
+    end
+
+    def detect_invisible_characters
+      found = []
+
+      string.chars.each_with_index do |char, idx|
+        if Confusables.invisible?(char)
+          found << InvisibleChar.new(
+            char: char,
+            codepoint: format("U+%04X", char.ord),
+            name: invisible_char_name(char),
+            position: idx
+          )
+        end
+      end
+
+      return nil if found.empty?
+
+      Detection.new(
+        type: :invisible,
+        message: "Found #{found.length} invisible character(s)",
+        characters: found,
+        severity: SEVERITY_HIGH
+      )
+    end
+
+    def detect_directional_overrides
+      found = []
+
+      string.chars.each_with_index do |char, idx|
+        if Confusables.directional_override?(char)
+          found << InvisibleChar.new(
+            char: char,
+            codepoint: format("U+%04X", char.ord),
+            name: "Bidirectional override",
+            position: idx
+          )
+        end
+      end
+
+      return nil if found.empty?
+
+      Detection.new(
+        type: :directional_override,
+        message: "Found #{found.length} bidirectional override character(s)",
+        characters: found,
+        severity: SEVERITY_HIGH
+      )
+    end
+
+    def detect_mixed_scripts
+      detector = Detector.new(string)
+      scripts = detector.scripts.reject { |s| ignored_script?(s) }
+
+      return nil if scripts.size <= 1
+
+      script_set = scripts.to_set
+
+      # Check if it's a known safe combination
+      return nil if Confusables::SAFE_SCRIPT_COMBINATIONS.any? { |safe| script_set.subset?(safe) }
+
+      Detection.new(
+        type: :mixed_scripts,
+        message: "Text contains a mix of #{scripts.size} scripts: #{scripts.map(&:to_s).join(", ")}",
+        characters: scripts.map(&:to_s),
+        severity: SEVERITY_MEDIUM
+      )
+    end
+
+    def detect_script_for_char(char)
+      Scripts::LIST.each do |script_data|
+        return script_data if char.match?(script_data[:regex])
+      end
+      { script: :Other, name: "Other" }
+    end
+
+    def ignored_script?(script)
+      %i[Common Inherited Whitespace Punctuation Digit New_Line Tab].include?(script)
+    end
+
+    def invisible_char_name(char)
+      names = {
+        "\u200B" => "Zero-width space",
+        "\u200C" => "Zero-width non-joiner",
+        "\u200D" => "Zero-width joiner",
+        "\u200E" => "Left-to-right mark",
+        "\u200F" => "Right-to-left mark",
+        "\uFEFF" => "Zero-width no-break space",
+        "\u2060" => "Word joiner",
+        "\u00AD" => "Soft hyphen",
+        "\u180E" => "Mongolian vowel separator",
+        "\u2061" => "Function application",
+        "\u2062" => "Invisible times",
+        "\u2063" => "Invisible separator",
+        "\u2064" => "Invisible plus",
+      }
+      names[char] || "Unknown invisible character"
+    end
+  end
+end

data/lib/unicode_script_detector/version.rb

@@ -1,3 +1,3 @@
 module UnicodeScriptDetector
-  VERSION = "0.0.9"
+  VERSION = "0.0.10"
 end

data/lib/unicode_script_detector.rb

@@ -20,5 +20,13 @@ module UnicodeScriptDetector
     def contains_only?(string, scripts)
       UnicodeScriptDetector::Detector.new(string).contains_only?(scripts)
     end
+
+    def spoof_analysis(string)
+      UnicodeScriptDetector::SpoofDetector.new(string).detections
+    end
+
+    def spoofed?(string)
+      UnicodeScriptDetector::SpoofDetector.new(string).spoofed?
+    end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: unicode_script_detector
 version: !ruby/object:Gem::Version
-  version: 0.0.9
+  version: 0.0.10
 platform: ruby
 authors:
 - David Arendsen
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-01-09 00:00:00.000000000 Z
+date: 2026-05-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: zeitwerk
@@ -54,9 +54,11 @@ files:
 - README.md
 - lib/unicode_script_detector.rb
 - lib/unicode_script_detector/character.rb
+- lib/unicode_script_detector/confusables.rb
 - lib/unicode_script_detector/detector.rb
 - lib/unicode_script_detector/script_group.rb
 - lib/unicode_script_detector/scripts.rb
+- lib/unicode_script_detector/spoof_detector.rb
 - lib/unicode_script_detector/version.rb
 homepage: https://github.com/davidarendsen/unicode_script_detector
 licenses:
@@ -73,7 +75,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.1.0
+      version: 3.2.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="