homographic_spoofing 0.1.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bf792d72d7ce23860e995427315130b5604dffb20473017e18419ab281413bbd
-  data.tar.gz: 5950f5c07494fc92f0bc437f7d3479444d36ba59c7333577ce41ce2c90961259
+  metadata.gz: e62f8de9bed530122d993c518081b18c90ff10a28b6a1890daa2181beff984aa
+  data.tar.gz: efee11ffe57495378d48a1ed545ff6fc9d51189168df8766edf5a09779e27692
 SHA512:
-  metadata.gz: 65d280b71972085510132dfe3f6c0c1e0ddfac067cf5e8cffe9b0681ab6999263c792fc16009d9c1e1279f38160ce506583a73e5f4b13bff26635b54fccffe5c
-  data.tar.gz: 51f1a8442291be6a92a8e22e32e7c196bd946f456755f745cdbe4df4c7ce18780b5716582d431a17b5913321772313c56723c4fa98fec301e88a7e81f8546fdc
+  metadata.gz: 0e00f735b4ebcaae22a5c9f85ce5701da7184b44c474015e2f9ca4af661e426cb61e743ee6879de997a01dc41a869a100f3e92b2d702001686eb6716e9d2e893
+  data.tar.gz: bc297a9087a1fcc45f10c4c570c4675932733f3be961ea445796da6a44bfa4f344bbc8d3585492829fd394a7dcbab94ff327ade354acc3746ab35d2acb3214fa

data/CHANGELOG.md

@@ -0,0 +1,56 @@
+# Changelog
+
+All notable changes to this project are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.2.0] - 2026-10-20
+
+### Changed
+
+- Sanitize uppercase and mixed-case confusable IDN domains.
+- Scan each domain label independently for script confusables.
+- Anchor allowed-TLD matching to whole TLD labels.
+- Disallow the characters Chromium removes as quotation-mark and letter look-alikes: U+0138 (kra), U+02BB (turned comma), U+02BC (apostrophe) and U+02EC (voicing).
+- Renamed `MOZILLA_DISALLOWED_CHARACTERS` to `DISALLOWED_CHARACTERS`, since the list now combines Mozilla's and Chromium's removals.
+- Apply the mixed-script, mixed-digit, digit and script-specific rules to each subdomain label separately rather than to the whole subdomain chain.
+- Flag a label that is only a CJK ideograph that looks like Latin or punctuation, such as `一` in `a.一.example.com`.
+- Sanitize an email address only within the part each detection came from, so a benign mailbox that equals a spoofed domain label is left intact.
+- Check the mailbox and each route domain of an address with an obsolete route separately instead of flagging the route itself.
+
+### Security
+
+- Pin GitHub Actions to commit SHAs and add an actionlint + zizmor audit job.
+
+## [0.1.2] - 2025-07-22
+
+### Added
+
+- `csv` gem dependency (extracted from the standard library in Ruby 3.4).
+
+### Changed
+
+- Regenerated the allowed-IDN-character and digit tables.
+- Renamed `MOZZILLA_DISALLOWED_CHARACTERS` to `MOZILLA_DISALLOWED_CHARACTERS`.
+
+## [0.1.1] - 2024-06-20
+
+### Added
+
+- `homepage_uri` and `source_code_uri` gem metadata.
+
+## [0.1.0] - 2024-06-20
+
+### Added
+
+- Initial release: detect and sanitize homographic spoofing attacks in URLs and
+  email addresses.
+
+[Unreleased]: https://github.com/basecamp/homographic_spoofing/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/basecamp/homographic_spoofing/compare/v0.1.2...v0.2.0
+[0.1.2]: https://github.com/basecamp/homographic_spoofing/compare/v0.1.1...v0.1.2
+[0.1.1]: https://github.com/basecamp/homographic_spoofing/compare/v0.1.0...v0.1.1
+[0.1.0]: https://github.com/basecamp/homographic_spoofing/releases/tag/v0.1.0

data/lib/homographic_spoofing/detector/detection.rb

@@ -1,2 +1,10 @@
-class HomographicSpoofing::Detector::Detection < Struct.new(:reason, :label)
+# `span` is the [offset, length] of the address component the detection came
+# from, in characters, within the field — so the sanitizer punycodes the
+# offending label only inside that component and never rewrites a matching label
+# in a sibling component (a local part equal to a spoofed domain label, say). It
+# is derived from the parsed address, not by re-scanning the raw string for an
+# "@", which trailing CFWS comments or a display name can carry spuriously. It
+# is nil for detectors that run against a standalone string (a bare IDN or
+# quoted string), where the whole field is the one component.
+class HomographicSpoofing::Detector::Detection < Struct.new(:reason, :label, :span)
 end

data/lib/homographic_spoofing/detector/email_address.rb

@@ -17,10 +17,12 @@ class HomographicSpoofing::Detector::EmailAddress
 
   def detections
     mail_address = mail_address_wrap(email_address)
+    spans = component_spans(mail_address)
     [].tap do |result|
-      result.concat detector_for(part: mail_address.name,   type: "quoted_string").detections if mail_address.name
-      result.concat detector_for(part: mail_address.local,  type: "local").detections if mail_address.local
-      result.concat detector_for(part: mail_address.domain, type: "idn").detections if mail_address.domain
+      result.concat detections_for(text: mail_address.name,   type: "quoted_string", span: spans[:name])
+      result.concat detections_for(text: mailbox(mail_address), type: "local",         span: spans[:local])
+      result.concat detections_for(text: mail_address.domain, type: "idn",           span: spans[:domain])
+      route_domains.each { |domain, span| result.concat detections_for(text: domain, type: "idn", span:) }
     end
   rescue Mail::Field::FieldError
     # Do not analyse invalid email addresses.
@@ -30,10 +32,385 @@ class HomographicSpoofing::Detector::EmailAddress
   private
     attr_reader :email_address
 
-    def detector_for(type:, part:)
-      "HomographicSpoofing::Detector::#{type.camelize}".constantize.new(part)
+    # Tag each detection with the [offset, length] of the component it came from
+    # so the sanitizer scopes the punycode replacement to that component alone —
+    # a domain-label spoof never rewrites a benign local part that merely equals
+    # the same string.
+    def detections_for(text:, type:, span:)
+      if text
+        detector_for(type:, text:).detections.each { |detection| detection.span = span }
+      else
+        []
+      end
     end
 
+    def detector_for(type:, text:)
+      "HomographicSpoofing::Detector::#{type.camelize}".constantize.new(text)
+    end
+
+    # Derive each component's [offset, length] span from parser token boundaries,
+    # not by searching the raw field for the stripped parts. The addr-spec built
+    # from the parser's *raw* local and domain — which keep the CFWS the stripped
+    # forms drop — is by construction a contiguous substring of the field, so its
+    # offset pins the mailbox and host spans exactly even when a comment or stray
+    # whitespace sits inside the address. The offset is taken inside the structural
+    # angle-address when there is one, so a display name or comment that repeats
+    # the addr-spec cannot divert the recipient's replacement onto itself. Only the
+    # display name — never the recipient — is still located by text (outside any
+    # comment), since a mislocated name only misplaces a cosmetic fix. When the
+    # field is not a raw string (a Mail::Address handed straight to a detection
+    # query) there is nothing to sanitize, so spans are left nil.
+    def component_spans(mail_address)
+      local, domain, name = mail_address.local, mail_address.domain, mail_address.name
+      return {} unless email_address.is_a?(String)
+
+      raw_local, raw_domain = raw_addr_spec_parts
+      addr = "#{raw_local}@#{raw_domain}" if raw_local && raw_domain
+      at = addr_offset(addr) if addr
+
+      if at
+        { name:   (name_span(name, avoid: [ at, addr.length ]) if name),
+          local:  (local_span(at, raw_local) if local),
+          domain: ([ at + raw_local.length + 1, raw_domain.length ] if domain) }
+      else
+        structural_spans(local, domain, name)
+      end
+    end
+
+    # The raw local and domain of the addr-spec as they appear in the field, CFWS
+    # included, from the address parser — or nils when it cannot supply them.
+    def raw_addr_spec_parts
+      [ parsed_address&.local, parsed_address&.domain ]
+    end
+
+    def parsed_address
+      return @parsed_address if defined?(@parsed_address)
+      @parsed_address = Mail::Parsers::AddressListsParser.parse(email_address).addresses.first
+    rescue StandardError
+      @parsed_address = nil
+    end
+
+    # The mailbox. Mail::Address#local keeps an obsolete route ("@relay:" in
+    # "<@relay:local@domain>") in front of it; the route is a list of domains,
+    # not part of the mailbox, so it is set aside here and its domains are
+    # checked as domains (see #route_domains). Each part is then punycoded on its
+    # own, and the route's "@", "," and ":" stay as they are.
+    #
+    # Comments are set aside too: they are not part of the mailbox, and the
+    # parser may take the display name from one ("<local(Name)@host>"), so the
+    # name's replacement must not change the text the mailbox is matched by.
+    def mailbox(mail_address)
+      local, route = mail_address.local, parsed_address&.obs_domain_list
+      local = local.delete_prefix(route) if route.present? && local
+      without_comments(local)&.strip
+    end
+
+    # The text with its comments removed, honouring nesting, quoted strings and
+    # backslash escapes, in one pass.
+    def without_comments(text)
+      return text unless text&.include?("(")
+
+      bare, depth, quoted, escaped = +"", 0, false, false
+      text.each_char do |char|
+        commented = depth > 0
+        if escaped
+          escaped = false
+        elsif char == "\\" && (commented || quoted)
+          escaped = true
+        elsif commented
+          depth += 1 if char == "("
+          depth -= 1 if char == ")"
+        elsif quoted
+          quoted = false if char == '"'
+        elsif char == '"'
+          quoted = true
+        elsif char == "("
+          depth, commented = 1, true
+        end
+        bare << char unless commented
+      end
+      bare
+    end
+
+    # Each domain of an obsolete route, with its span in the field: the route
+    # sits inside the structural angle-address, before the addr-spec.
+    def route_domains
+      route = parsed_address&.obs_domain_list
+      return [] unless email_address.is_a?(String) && route.present?
+
+      lt, gt = angle_address
+      start = structural_index(route, from: lt + 1) if lt
+      return [] unless start && start + route.length <= gt
+
+      route_entries(route).filter_map do |domain, offset, length|
+        [ domain, [ start + offset, length ] ] if domain.present? && !domain.start_with?("[")
+      end
+    end
+
+    # Split a route ("@a.example, @b.example:") into its domains in one pass, on
+    # each "," or ":" outside comments and domain literals ("@[IPv6:2001:db8::1]"
+    # is one entry; a literal is no DNS name, so it is never checked as one).
+    # Each entry's span starts after its "@";
+    # its domain is checked with comments and whitespace set aside (the obsolete
+    # syntax allows both between labels), while the sanitizer, which also sets
+    # them aside per label, rewrites only the labels within the span.
+    def route_entries(route)
+      entries = []
+      bare, at, entry_start, depth, escaped, literal = +"", nil, 0, 0, false, false
+
+      route.each_char.with_index do |char, index|
+        commented = depth > 0
+        if escaped
+          escaped = false
+        elsif (commented || literal) && char == "\\"
+          escaped = true
+        elsif commented
+          depth += 1 if char == "("
+          depth -= 1 if char == ")"
+        elsif literal
+          literal = false if char == "]"
+        elsif char == "("
+          depth, commented = 1, true
+        elsif char == "["
+          literal = true
+        elsif char == "," || char == ":"
+          entries << [ bare.gsub(/\s/, ""), at || entry_start, index - (at || entry_start) ]
+          bare, at, entry_start = +"", nil, index + 1
+          next
+        elsif char == "@" && at.nil?
+          at = index + 1
+          next
+        end
+        bare << char unless commented || at.nil?
+      end
+
+      entries << [ bare.gsub(/\s/, ""), at || entry_start, route.length - (at || entry_start) ]
+    end
+
+    def local_span(at, raw_local)
+      [ at, raw_local.length ]
+    end
+
+    # The display name's span. When the name the parser reports is not in the
+    # field as written (it unescapes quoted pairs, so "\\x" reads as "x"), there
+    # is no text to rewrite safely: its span is empty, so the detection is still
+    # reported but the field is left as is rather than rewritten across an
+    # escape or onto the mailbox or host.
+    def name_span(name, avoid: nil)
+      locate(name, avoid:) || [ 0, 0 ]
+    end
+
+    # The addr-spec's offset in the field. When the field has a structural
+    # angle-address — its "<" outside every quoted string and comment, since a
+    # quoted display name or a comment may itself spell out "<local@domain>" — the
+    # addr-spec is searched for inside it rather than matched as "<addr>", because
+    # an obsolete route ("<@relay:local@domain>") may precede it; a copy of the
+    # addr-spec anywhere else in the field is never the recipient. Without an
+    # angle-address, the first bare occurrence outside any comment.
+    def addr_offset(addr)
+      lt, gt = angle_address
+      if lt
+        at = structural_index(addr, from: lt + 1)
+        at if at && at + addr.length <= gt
+      else
+        structural_index(addr)
+      end
+    end
+
+    # The offsets of the "<" and ">" of the structural angle-address, or nil when
+    # the field has none.
+    def angle_address
+      lt = structural_index("<")
+      gt = structural_index(">", from: lt) if lt
+      [ lt, gt ] if lt && gt
+    end
+
+    # The first occurrence of `needle` at or after `from` that starts outside
+    # every quoted string, domain literal and comment in the field.
+    def structural_index(needle, from: 0)
+      enclosed, commented, _unsearchable = enclosures
+      while (at = index_in_field(needle, from))
+        return at unless enclosed[at] || commented[at]
+        from = at + 1
+      end
+      nil
+    end
+
+    # Which character offsets of the field sit inside a quoted string or a domain
+    # literal, and which inside a (nestable) comment. Each opening delimiter is
+    # outside its own enclosure, so a needle may begin with one ('"john"@host');
+    # the closing delimiter is inside. Backslash escapes are honored in all
+    # three, and inside a comment neither quotes nor literals have structure —
+    # only nesting parentheses do. The third table marks what a replacement must
+    # never include: quoted pairs, and every parenthesis inside a comment (a
+    # nested comment's delimiters and the closing one).
+    def enclosures
+      @enclosures ||= begin
+        length = email_address.length
+        enclosed, commented, unsearchable = Array.new(length, false), Array.new(length, false), Array.new(length, false)
+        closer, depth, escaped = nil, 0, false
+        email_address.each_char.with_index do |char, i|
+          enclosed[i], commented[i] = !closer.nil?, depth > 0
+          if escaped
+            escaped = false
+            unsearchable[i] = true
+          elsif char == "\\" && (closer || depth > 0)
+            escaped = true
+            unsearchable[i] = true
+          elsif closer
+            closer = nil if char == closer
+          elsif depth > 0
+            depth += 1 if char == "("
+            depth -= 1 if char == ")"
+            unsearchable[i] = true if char == "(" || char == ")"
+          elsif char == '"'
+            closer = '"'
+          elsif char == "["
+            closer = "]"
+          elsif char == "("
+            depth = 1
+          end
+        end
+        [ enclosed, commented, unsearchable ]
+      end
+    end
+
+    # Fallback when the parser yields no raw addr-spec: bound the components by the
+    # structural delimiters instead. The addr-spec sits between the angle brackets
+    # when present (split at its last "@", past any obsolete route), otherwise it
+    # is the whole field, split at the first "@".
+    def structural_spans(local, domain, name)
+      lt, gt = angle_address
+      at = lt ? last_structural_at(lt, gt) : structural_index("@")
+
+      if lt && at && at < gt
+        { name:   (name_span(name, avoid: [ lt, gt - lt + 1 ]) if name),
+          local:  ([ lt + 1, at - lt - 1 ] if local),
+          domain: ([ at + 1, gt - at - 1 ] if domain) }
+      elsif at
+        { name:   (name_span(name) if name),
+          local:  ([ 0, at ] if local),
+          domain: (bare_domain_span(at, domain) if domain) }
+      else
+        {}
+      end
+    end
+
+    # Everything after the "@" — unless the domain the parser reports carries an
+    # "@" itself, which it does when it folds the mailbox into the domain
+    # ("а(comment).b@(note)safe.com"). The boundary between the parts is then
+    # unknown, so the domain spans the whole field, as every detection did
+    # before spans existed.
+    def bare_domain_span(at, domain)
+      [ at + 1, char_count - at - 1 ] unless domain.include?("@")
+    end
+
+    # The addr-spec's "@" inside the angle-address: the last structural one, since
+    # an obsolete route ("<@relay:local@domain>") puts its own before it.
+    def last_structural_at(lt, gt)
+      last = nil
+      while (at = structural_index("@", from: (last || lt) + 1)) && at < gt
+        last = at
+      end
+      last
+    end
+
+    # The first occurrence of `text` in the field at or after `from` that lies
+    # wholly outside every comment and outside `avoid` (the addr-spec, when
+    # locating a display name that shares a spelling with the mailbox or host);
+    # leading CFWS may repeat a display name. Failing that, the first occurrence
+    # wholly inside one comment: the parser takes a display name from a trailing
+    # comment ("user@host (Name)"), which its raw domain token also carries, and
+    # a comment is never the mailbox or host even when it sits inside `avoid`.
+    # An occurrence that crosses a comment's edge is neither, so it never sends
+    # a display name's replacement into the mailbox.
+    def locate(text, from: 0, avoid: nil)
+      outside = comment_runs(commented: false).flat_map { |range| outside_of(range, avoid) }
+      search_ranges(text, outside, from:) || search_ranges(text, comment_runs(commented: true), from:)
+    end
+
+    # The maximal [start, finish) runs of characters inside (or outside)
+    # comments, without the parentheses that open and close each comment or any
+    # comment nested in it, and without quoted pairs ("\\(" and the like), so a
+    # display name's replacement can never move a comment's edge or separate an
+    # escape from what it escapes.
+    # The parser unescapes quoted pairs in the name it reports, so a name that
+    # carries one is not in the field as written anyway.
+    def comment_runs(commented:)
+      @comment_runs ||= begin
+        char_to_byte, _byte_to_char = offset_tables
+        delimiter = ->(index) { field_bytes.getbyte(char_to_byte[index]) }
+        _enclosed, inside_comment, unsearchable = enclosures
+        keys = inside_comment.each_with_index.map { |inside, index| unsearchable[index] ? :unsearchable : inside }
+        keys.each_with_index.chunk_while { |(a, _), (b, _)| a == b }.filter_map do |run|
+          inside, start, finish = run.first.first, run.first.last, run.last.last + 1
+          next if inside == :unsearchable
+
+          finish -= 1 if !inside && finish < char_to_byte.length - 1 && delimiter.(finish - 1) == "(".ord
+          [ inside, start, finish ]
+        end
+      end
+      @comment_runs.filter_map { |inside, start, finish| [ start, finish ] if inside == commented && start < finish }
+    end
+
+    def outside_of((start, finish), avoid)
+      return [ [ start, finish ] ] unless avoid
+
+      [ [ start, [ finish, avoid[0] ].min ], [ [ start, avoid[0] + avoid[1] ].max, finish ] ].reject { |a, b| a >= b }
+    end
+
+    # The first occurrence of `text` wholly inside one of `ranges`, searching
+    # each range once, so the cost stays linear however often `text` overlaps
+    # itself.
+    def search_ranges(text, ranges, from:)
+      char_to_byte, byte_to_char = offset_tables
+      needle, length = text.b, text.length
+      ranges.each do |start, finish|
+        start = [ start, from ].max
+        next if finish - start < length
+
+        at = field_bytes.byteslice(char_to_byte[start]...char_to_byte[finish]).index(needle)
+        return [ byte_to_char[char_to_byte[start] + at], length ] if at
+      end
+      nil
+    end
+
+    # The first occurrence of `needle` at or after character offset `from`.
+    # String#index converts a character offset by walking a multibyte string
+    # from its start on every call, so a loop of searches over a long field turns
+    # quadratic. Search the field's bytes instead, where an offset costs nothing
+    # and a UTF-8 match always starts on a character boundary, and map between
+    # bytes and characters through tables built once.
+    def index_in_field(needle, from)
+      char_to_byte, byte_to_char = offset_tables
+      return nil if from >= char_to_byte.length
+
+      at = field_bytes.index(needle.b, char_to_byte[from])
+      byte_to_char[at] if at
+    end
+
+    def char_count
+      offset_tables.first.length - 1
+    end
+
+    def field_bytes
+      @field_bytes ||= email_address.b
+    end
+
+    def offset_tables
+      @offset_tables ||= begin
+        char_to_byte, byte_to_char = [], []
+        email_address.each_char.with_index do |char, index|
+          char_to_byte << byte_to_char.length
+          char.bytesize.times { byte_to_char << index }
+        end
+        char_to_byte << byte_to_char.length
+        byte_to_char << email_address.length
+        [ char_to_byte, byte_to_char ]
+      end
+    end
+
+
     def mail_address_wrap(email_address)
       email_address.is_a?(Mail::Address) ? email_address : Mail::Address.new(email_address)
     end

data/lib/homographic_spoofing/detector/idn.rb

@@ -16,6 +16,7 @@ class HomographicSpoofing::Detector::Idn
   end
 
   def initialize(domain)
+    @original_domain = domain
     @domain = domain.downcase
   end
 
@@ -25,15 +26,42 @@ class HomographicSpoofing::Detector::Idn
 
   def detections
     rules.select(&:attack_detected?).map do |rule|
-      HomographicSpoofing::Detector::Detection.new(rule.reason, rule.label)
+      HomographicSpoofing::Detector::Detection.new(rule.reason, original_case(rule.label, rule.occurrence))
     end
   rescue PublicSuffix::Error
     # Invalid IDN is a spoof.
-    [ HomographicSpoofing::Detector::Detection.new("invalid_domain", domain) ]
+    [ HomographicSpoofing::Detector::Detection.new("invalid_domain", original_domain) ]
   end
 
   private
-    attr_reader :domain
+    attr_reader :domain, :original_domain
+
+    # Detection runs on the lowercased domain, so labels come back lowercased.
+    # Recover the original-cased spelling of the label at its own position, so
+    # the sanitizer can substitute by exact match instead of regexp case folding,
+    # which both over-matches (folds unrelated ASCII, e.g. ſ/s) and under-matches
+    # (misses case pairs folding omits, e.g. Ⱥ/ⱥ). A label repeated in the domain
+    # resolves to the casing of its own occurrence, counted left to right.
+    def original_case(label, occurrence = 0)
+      original_labels.fetch(label, [])[occurrence] || label
+    end
+
+    # Every whole label of the raw domain, in its original casing, grouped by its
+    # lowercased form in left-to-right order. Labels are bounded by ".", never by
+    # a match inside a longer sibling ("з" inside "магаЗин"), and keep any
+    # whitespace inside them as PublicSuffix does; only the whitespace it strips
+    # from the ends of the domain is set aside. Built in one pass, so resolving
+    # every detection stays linear in the domain's length.
+    def original_labels
+      @original_labels ||= begin
+        originals = original_domain.split(".", -1)
+        originals[0] = originals[0].lstrip if originals.any?
+        originals[-1] = originals[-1].rstrip if originals.any?
+        originals.each_with_object({}) do |original, labels|
+          (labels[original.downcase] ||= []) << original
+        end
+      end
+    end
 
     def rules
       @rules ||= contexts.flat_map { |ctx| rules_for(ctx) }
@@ -55,8 +83,29 @@ class HomographicSpoofing::Detector::Idn
     end
 
     def contexts
-      [ public_suffix.sld, public_suffix.trd ].compact.map do |label|
-        HomographicSpoofing::Detector::Rule::Idn::Context.new(label: label, tld: public_suffix.tld)
+      tld, tld_allowances = public_suffix.tld, {}
+      labels.map do |label, occurrence|
+        HomographicSpoofing::Detector::Rule::Idn::Context.new(label:, tld:, occurrence:, tld_allowances:)
+      end
+    end
+
+    # `trd` is the full subdomain chain ("a.b" in a.b.example.com). Split it on
+    # the same dot the renderer draws so each rule sees one real label rather
+    # than a chain. The mixed-script, confusable and digit rules are per-label:
+    # a combined chain both hides attacks (a benign sibling dilutes an
+    # all-look-alike label out of detection) and invents them (two single-script
+    # sibling labels look "mixed" together though each is safe on its own).
+    #
+    # Labels are kept in left-to-right domain order and paired with the index of
+    # their occurrence among identical labels, so a repeated label recovers the
+    # casing of its own position (see #original_case).
+    def labels
+      ordered = [ *public_suffix.trd&.split("."), public_suffix.sld ].compact.reject(&:empty?)
+      seen = Hash.new(0)
+      ordered.map do |label|
+        occurrence = seen[label]
+        seen[label] += 1
+        [ label, occurrence ]
       end
     end
 

data/lib/homographic_spoofing/detector/rule/base.rb

@@ -1,5 +1,5 @@
 class HomographicSpoofing::Detector::Rule::Base
-  delegate :scripts, :label, :label_set, to: :@context
+  delegate :scripts, :label, :label_set, :occurrence, to: :@context
 
   def initialize(context)
     @context = context

data/lib/homographic_spoofing/detector/rule/context.rb

@@ -1,8 +1,12 @@
 class HomographicSpoofing::Detector::Rule::Context
-  attr_reader :label
+  attr_reader :label, :occurrence
 
-  def initialize(label:)
+  # `occurrence` disambiguates labels that repeat within a domain: it is the
+  # zero-based index of this label among identical labels, in left-to-right
+  # order, so the original casing of the right occurrence can be recovered.
+  def initialize(label:, occurrence: 0)
     @label = label
+    @occurrence = occurrence
   end
 
   SCRIPT_COMMON = "Common"

data/lib/homographic_spoofing/detector/rule/disallowed_characters.rb

@@ -1,15 +1,22 @@
 # 3. and 4. of Google Chrome IDN policy See https://util.unicode.org/UnicodeJsps/list-unicodeset.jsp?a=%5B%3AIdentifierStatus%3DAllowed%3A&abb=on&g=&i=
 class HomographicSpoofing::Detector::Rule::DisallowedCharacters < HomographicSpoofing::Detector::Rule::Base
   class << self
-    # See http://kb.mozillazine.org/Network.IDN.blacklist_chars
-    MOZILLA_DISALLOWED_CHARACTERS = Set[
+    # Characters removed from the allowed set. Combines Mozilla's blocklist
+    # (http://kb.mozillazine.org/Network.IDN.blacklist_chars) with the
+    # removals in Chromium's IDNSpoofChecker::SetAllowedUnicodeSet
+    # (components/url_formatter/spoof_checks/idn_spoof_checker.cc).
+    DISALLOWED_CHARACTERS = Set[
       "\u0020", # Space
       "\u00a0", # No-break space
       "\u00bc", # Vulgar fraction one quarter
       "\u00bd", # Vulgar fraction one half
       "\u00be", # Vulgar fraction three quarters
+      "\u0138", # Latin small letter kra (Chromium)
       "\u01c3", # Latin letter retroflex click
+      "\u02bb", # Modifier letter turned comma (Chromium)
+      "\u02bc", # Modifier letter apostrophe (Chromium)
       "\u02d0", # Modifier letter triangular colon
+      "\u02ec", # Modifier letter voicing (Chromium)
       "\u0337", # Combining short solidus overlay
       "\u0338", # Combining long solidus overlay
       "\u0589", # Armenian full stop
@@ -124,7 +131,7 @@ class HomographicSpoofing::Detector::Rule::DisallowedCharacters < HomographicSpo
     ]
 
     def allowed_chars_set
-      @@allowed_chars_set ||= (read_allowed_idn_chars.chars.to_set - MOZILLA_DISALLOWED_CHARACTERS)
+      @@allowed_chars_set ||= (read_allowed_idn_chars.chars.to_set - DISALLOWED_CHARACTERS)
     end
 
     private

data/lib/homographic_spoofing/detector/rule/idn/base.rb

@@ -1,3 +1,3 @@
 class HomographicSpoofing::Detector::Rule::Idn::Base < HomographicSpoofing::Detector::Rule::Base
-  delegate :tld, to: :@context
+  delegate :tld, :tld_allowances, to: :@context
 end

data/lib/homographic_spoofing/detector/rule/idn/context.rb

@@ -1,8 +1,14 @@
 class HomographicSpoofing::Detector::Rule::Idn::Context < HomographicSpoofing::Detector::Rule::Context
-  attr_reader :tld
+  attr_reader :tld, :tld_allowances
 
-  def initialize(label:, tld:)
+  # `tld_allowances` is shared by every label of one domain, so a decision that
+  # depends only on the TLD is made once per domain rather than once per label.
+  # Under a wildcard suffix such as "*.mm" the TLD carries a label the sender
+  # chose, and scanning it again for every label would cost the label count
+  # times its length.
+  def initialize(label:, tld:, occurrence: 0, tld_allowances: {})
     @tld = tld
-    super(label:)
+    @tld_allowances = tld_allowances
+    super(label:, occurrence:)
   end
 end

data/lib/homographic_spoofing/detector/rule/idn/dangerous_pattern.rb

@@ -16,6 +16,13 @@ class HomographicSpoofing::Detector::Rule::Idn::DangerousPattern < HomographicSp
     [\u30ce\u30f3\u30bd\u30be\u4e36\u4e40\u4e41\u4e3f]
     [^\p{kana}\p{hira}\p{hani}]/x,
 
+    /# Rules see one label at a time, so a label edge counts as a non-Japanese
+    # side too: the dot the renderer draws there is not Japanese either. Beside
+    # an edge, "ー" (U+30FC, Common to Unicode's Script property but Japanese in
+    # use) counts as Japanese, so words like "ノート" and "コーン" stay clear.
+    \A[\u30ce\u30f3\u30bd\u30be\u4e36\u4e40\u4e41\u4e3f](?:[^\p{kana}\p{hira}\p{hani}\u30fc]|\z)|
+    [^\p{kana}\p{hira}\p{hani}\u30fc][\u30ce\u30f3\u30bd\u30be\u4e36\u4e40\u4e41\u4e3f]\z/x,
+
       /# Disallow three Hiragana letters (U+307[8-A]) or Katakana letters
       # (U+30D[8-A]) that look exactly like each other when they're used
       # in a label otherwise entirely in Katakana or Hiragana.
@@ -49,6 +56,14 @@ class HomographicSpoofing::Detector::Rule::Idn::DangerousPattern < HomographicSp
       [\u4e00\u3127\u4e28\u4e5b\u4e03\u4e05\u5341\u3007\u3112\u311a\u311f\u3128\u3129\u3108\u31ba\u31b3\u5de5\u31b2\u8ba0\u4e01]
     [^\p{kana}\p{hira}\p{hani}\p{bopo}]/x,
 
+      /# Rules see one label at a time, so a label that is only one of these
+      # ideographs has the dots the renderer draws on both sides, and neither
+      # is CJK: "a.一.example.com" reads as "a.-.example.com". A longer label
+      # with one at its edge is already caught by the two patterns above when
+      # its other neighbour is non-CJK, and stays safe when it is CJK, as in
+      # "工行" or "一号店".
+      \A[一ㄧ丨乛七丅十〇ㄒㄚㄟㄨㄩㄈㆺㆳ工ㆲ讠丁]\z/x,
+
       /# Disallow combining diacritical mark (U+0300-U+0339) after a
       # non-LGC character. Other combining diacritical marks are not in
       # the allowed character set.

data/lib/homographic_spoofing/detector/rule/idn/invisible_characters.rb

@@ -9,6 +9,6 @@ class HomographicSpoofing::Detector::Rule::Idn::InvisibleCharacters < Homographi
       /\u0e48{2,}/,   # Thai tone repeated
       /\u0301{2,}/,   # accute accent repeated
       /\u00e1\u0301/, # 'a' with acuted accent + another acute accent
-      /^\u0300/,      # Combining mark at the beginning
+      /\A\p{M}/,      # Combining mark at the beginning of a label
     )
 end

data/lib/homographic_spoofing/detector/rule/idn/script_confusable.rb

@@ -46,11 +46,23 @@ class HomographicSpoofing::Detector::Rule::Idn::ScriptConfusable < HomographicSp
       [ /\p{Mymr}/, /[ခဂငထပဝ၀၂ၔၜ\u1090\u1091\u1095\u1096\u1097]/, /[a-z]+\.mm/ ],
       # # Thai
       [ /\p{Thai}/, /[ทนบพรหเแ๐ดลปฟม]/, /th/ ]
-    ].map { Confusable.new(*_1) }
+    ]
+    # Anchor each allowed-TLD pattern so it only matches whole trailing labels
+    # of the TLD, never a substring of one. Unanchored, `/ru/` matched `.guru`,
+    # `/su/` matched `.surf`, `/by/` matched `.baby`/`.rugby`, etc., silently
+    # disabling single-script confusable detection on those TLDs. The
+    # `(?:\A|\.)…\z` boundary keeps multi-label public suffixes working —
+    # `co.th` still matches `/th/`, `com.mm` still matches `/[a-z]+\.mm/`.
+    .map do |script, latin_lookalike, allowed_tlds|
+      anchored_tlds = allowed_tlds && /(?:\A|\.)(?:#{allowed_tlds.source})\z/
+      Confusable.new script, latin_lookalike, anchored_tlds
+    end
 
     def is_script_confusable_allowed_for_tld?(confusable)
-      tld_contains_any_letter_from_script?(confusable.script) ||
-        confusable.allowed_tlds&.match?(tld)
+      tld_allowances.fetch(confusable) do
+        tld_allowances[confusable] = tld_contains_any_letter_from_script?(confusable.script) ||
+          confusable.allowed_tlds&.match?(tld) || false
+      end
     end
 
     def tld_contains_any_letter_from_script?(script)

data/lib/homographic_spoofing/sanitizer/base.rb

@@ -10,19 +10,153 @@ class HomographicSpoofing::Sanitizer::Base
   end
 
   def sanitize
-    result = field.dup
-    detector_class.new(field).detections.each do |detection|
-      log(detection.reason, detection.label)
-      result = punycode(result, detection.label)
-    end
-    result
+    detections = detector_class.new(field).detections
+    detections.each { |detection| log(detection.reason, detection.label) }
+    apply(field, detections)
   end
 
   private
     attr_reader :field
 
-    def punycode(source, label)
-      source.gsub(label, Dnsruby::Name.punycode(label))
+    # Punycode each offending label only within the component it came from. A
+    # spanned detection carries the [offset, length] of its component, so a
+    # domain-label spoof is confined to the domain and never rewrites a benign
+    # local part that merely equals the same string — this is what keeps
+    # "з@мир.з.example.com" punycoding the domain label "з" while leaving the "з"
+    # mailbox intact. Spans are disjoint or nested (a display name read from a
+    # comment the host's token carries), so they form a tree: each span's text is
+    # rebuilt with its inner spans already rewritten, then rewritten itself, in
+    # one pass over the field. A detection with no span (a bare IDN or quoted
+    # string) spans the whole field and is applied last, over what remains.
+    def apply(field, detections)
+      return field.dup if detections.empty?
+
+      whole, spanned = detections.partition { |detection| detection.span.nil? }
+      edits = spanned.group_by(&:span).map do |(offset, length), group|
+        Edit.new(offset, offset + length, group.map(&:label).uniq, [])
+      end
+      chars = field.chars
+      replace_labels(splice(chars, 0, chars.length, nest(edits)), whole.map(&:label).uniq)
+    end
+
+    Edit = Struct.new(:start, :finish, :labels, :inner)
+
+    # Arrange spans into a tree, outer before inner, in one pass over them sorted
+    # by start. A span that overlaps an earlier sibling without nesting in it is
+    # trimmed to start where that sibling ends.
+    def nest(edits)
+      outermost, open = [], []
+      edits.sort_by { |edit| [ edit.start, -edit.finish ] }.each do |edit|
+        open.pop while open.any? && open.last.finish < edit.finish
+        siblings = open.empty? ? outermost : open.last.inner
+        edit.start = [ edit.start, siblings.last.finish ].max if siblings.any?
+        next if edit.start > edit.finish
+
+        siblings << edit
+        open << edit
+      end
+      outermost
+    end
+
+    def splice(chars, start, finish, edits)
+      text, at = +"", start
+      edits.each do |edit|
+        text << chars[at...edit.start].join << replace_labels(splice(chars, edit.start, edit.finish, edit.inner), edit.labels)
+        at = edit.finish
+      end
+      text << chars[at...finish].join
+    end
+
+    # Replace each label where it is a whole "."-delimited component of the
+    # region, so an offending label is never rewritten as a substring of a benign
+    # sibling (the Cyrillic digit-look-alike "з" that also sits inside
+    # "магазин"), and every matching component is punycoded from its own
+    # spelling — case-exact, so a spoof repeated in different casing is handled
+    # per occurrence. A component is compared with its CFWS (comments and
+    # surrounding whitespace, which the parser drops from the label it reports)
+    # set aside, and only the label itself is rewritten, so "з(comment)" is
+    # punycoded at the label and a comment beside it never sends the replacement
+    # into a benign sibling. A label that is only a substring of a component (a
+    # display name carrying spaces) has no whole component to match and falls
+    # back to exact substring replacement.
+    #
+    # A label that keeps whitespace inside it, as PublicSuffix reports "а " in
+    # "А .com", matches its component as written.
+    #
+    # The region is scanned once for all labels, so sanitizing stays linear in
+    # its length however many labels were detected.
+    def replace_labels(region, labels)
+      return region if labels.empty?
+
+      components = label_components(region)
+      present = components.to_set(&:bare) | components.map(&:text)
+      whole, partial = labels.partition { |label| present.include?(label) }
+      whole = whole.to_set
+
+      result = components.map do |component|
+        if whole.include?(component.text) && component.bare
+          Dnsruby::Name.punycode(component.text)
+        elsif whole.include?(component.bare)
+          component.punycoded
+        else
+          component.text
+        end
+      end.join
+      partial.inject(result) { |text, label| text.gsub(label) { Dnsruby::Name.punycode(label) } }
+    end
+
+    # One "."-delimited component of a region: its text, the label it carries
+    # with CFWS set aside (`bare`), and where that label starts in the text, past
+    # any leading CFWS that may repeat it. Separators are components too, with no
+    # label.
+    Component = Struct.new(:text, :bare, :start) do
+      def punycoded
+        if text[start, bare.length] == bare
+          text[0, start] + Dnsruby::Name.punycode(bare) + text[(start + bare.length)..]
+        else
+          text
+        end
+      end
+    end
+
+    # Split a region into label components on each "." outside comments and
+    # quoted strings, in a single pass. Comments nest and honour backslash
+    # escapes, as RFC 5322 has them, so a comment's own dots or parentheses
+    # never split or end a label early.
+    def label_components(region)
+      components = []
+      text, bare, start = +"", +"", nil
+      depth, quoted, escaped = 0, false, false
+
+      region.each_char do |char|
+        commented = depth > 0
+        if escaped
+          escaped = false
+        elsif char == "\\" && (commented || quoted)
+          escaped = true
+        elsif commented
+          depth += 1 if char == "("
+          depth -= 1 if char == ")"
+        elsif quoted
+          quoted = false if char == '"'
+        elsif char == "("
+          depth, commented = 1, true
+        elsif char == '"'
+          quoted = true
+        elsif char == "."
+          components << Component.new(text, bare.strip, start || 0) << Component.new(char, nil, 0)
+          text, bare, start = +"", +"", nil
+          next
+        end
+
+        unless commented
+          start ||= text.length unless char.match?(/\s/)
+          bare << char
+        end
+        text << char
+      end
+
+      components << Component.new(text, bare.strip, start || 0)
     end
 
     def detector_class

data/lib/homographic_spoofing/sanitizer/idn.rb

@@ -7,4 +7,34 @@ class HomographicSpoofing::Sanitizer::Idn < HomographicSpoofing::Sanitizer::Base
     def spoofing_type
       "EmailIDN"
     end
+
+    # A bare domain has no comments or quoted strings: the detector splits it on
+    # every ".", so split it the same way. Honouring "(" or '"' here would let an
+    # unmatched one fold the rest of the domain into one component, and every
+    # detected label would then fall back to a substitution over the whole field.
+    #
+    # The detector reports labels as PublicSuffix does: with the domain's own
+    # leading and trailing padding set aside, but any whitespace inside the
+    # domain kept on its label ("А " in " А .А .com"). That padding is set apart
+    # as components with no label, so each label component reads as its label
+    # was reported.
+    def label_components(region)
+      core = region.strip
+      leading = core.empty? ? region : region[0, region.index(core)]
+      trailing = region[(leading.length + core.length)..]
+
+      [ padding(leading), *core.split(/(\.)/, -1).map { |text| component(text) }, padding(trailing) ].compact
+    end
+
+    def component(text)
+      if text == "."
+        Component.new(text, nil, 0)
+      else
+        Component.new(text, text.strip, text.index(/\S/) || 0)
+      end
+    end
+
+    def padding(text)
+      Component.new(text, nil, 0) unless text.empty?
+    end
 end

data/lib/homographic_spoofing/version.rb

@@ -1,3 +1,3 @@
 module HomographicSpoofing
-  VERSION = "0.1.2"
+  VERSION = "0.2.0"
 end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: homographic_spoofing
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.2.0
 platform: ruby
 authors:
 - Jacopo Beschi
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-07-22 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: zeitwerk
@@ -108,13 +107,13 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.3'
-description:
 email:
 - jacopo@37signals.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
 - MIT-LICENSE
 - README.md
 - lib/homographic_spoofing.rb
@@ -159,7 +158,9 @@ metadata:
   allowed_push_host: https://rubygems.org
   homepage_uri: https://github.com/basecamp/homographic_spoofing
   source_code_uri: https://github.com/basecamp/homographic_spoofing
-post_install_message:
+  changelog_uri: https://github.com/basecamp/homographic_spoofing/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/basecamp/homographic_spoofing/issues
+  rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
 - lib
@@ -174,8 +175,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.22
-signing_key:
+rubygems_version: 3.6.9
 specification_version: 4
 summary: A toolkit to both detect and sanitize homographic spoofing attacks in URLs
   and Email addresses