homographic_spoofing 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d3e22e70c188a72a399579b20026066ff1dd07ea8f7cfd010433f4b92982dfb6
-  data.tar.gz: 2a6fc219983065d32076aee9caaef4795382466f71a39bc8ecb244efaf8cb28e
+  metadata.gz: e62f8de9bed530122d993c518081b18c90ff10a28b6a1890daa2181beff984aa
+  data.tar.gz: efee11ffe57495378d48a1ed545ff6fc9d51189168df8766edf5a09779e27692
 SHA512:
-  metadata.gz: 38f8c50d3106f1761859d6281459a1bafa2f3e9a3bdf79d87e1f2682a38710d891cc3f108194636db60aa794f90a30e901c0456445eab30bf18bc10117bc9ef8
-  data.tar.gz: db40328dd32d4aaa2f96adc19b06bcfa8df43538e486a3eabe2dd0cb51fe875c9da04aad02d254f5b0f3635435260b568105969ed15912952059d65406df440d
+  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"