zxcvbn-ruby 1.3.0 → 2.0.0

data/lib/zxcvbn/matchers/dictionary.rb

@@ -1,19 +1,26 @@
 # frozen_string_literal: true
 
-require 'zxcvbn/match'
+require 'zxcvbn/match_builder'
 
 module Zxcvbn
   module Matchers
-    # Given a password and a dictionary, match on any sequential segment of
-    # the lowercased password in the dictionary
-
+    # Matches any sequential segment of the lowercased password that appears in
+    # a ranked dictionary.
+    # @api private
     class Dictionary
+      # @param name [String] dictionary identifier used in match results
+      # @param ranked_dictionary [Hash{String => Integer}] lowercased word → rank
+      # @param trie [Trie, nil] optional prefix trie for faster lookups
       def initialize(name, ranked_dictionary, trie = nil)
         @name = name
         @ranked_dictionary = ranked_dictionary
         @trie = trie
       end
 
+      # Returns all dictionary matches found in password.
+      #
+      # @param password [String]
+      # @return [Array<MatchBuilder>] matches with pattern "dictionary"
       def matches(password)
         lowercased_password = password.downcase
 
@@ -56,12 +63,12 @@ module Zxcvbn
       end
 
       def build_match(matched_word, token, start_pos, end_pos, rank)
-        Match.new(
-          matched_word: matched_word,
-          token: token,
+        MatchBuilder.new(
+          matched_word:,
+          token:,
           i: start_pos,
           j: end_pos,
-          rank: rank,
+          rank:,
           pattern: 'dictionary',
           dictionary_name: @name
         )

data/lib/zxcvbn/matchers/digits.rb

@@ -4,11 +4,16 @@ require 'zxcvbn/matchers/regex_helpers'
 
 module Zxcvbn
   module Matchers
+    # Matches runs of 3 or more consecutive digits in the password.
+    # @api private
     class Digits
       include RegexHelpers
 
-      DIGITS_REGEX = /\d{3,}/.freeze
+      # Matches runs of 3 or more consecutive digits.
+      DIGITS_REGEX = /\d{3,}/
 
+      # @param password [String]
+      # @return [Array<MatchBuilder>] matches with pattern "digits"
       def matches(password)
         result = []
         re_match_all(DIGITS_REGEX, password) do |match|

data/lib/zxcvbn/matchers/l33t.rb

@@ -1,10 +1,12 @@
 # frozen_string_literal: true
 
-require 'set'
-
 module Zxcvbn
   module Matchers
+    # Matches dictionary words after substituting common l33t-speak character
+    # replacements (e.g. "@" for "a", "3" for "e").
+    # @api private
     class L33t
+      # Mapping from plain letter to the l33t characters that can represent it.
       L33T_TABLE = {
         'a' => ['4', '@'].freeze,
         'b' => ['8'].freeze,
@@ -20,10 +22,15 @@ module Zxcvbn
         'z' => ['2'].freeze
       }.freeze
 
+      # @param dictionary_matchers [Array<Dictionary>] matchers to run against substituted passwords
       def initialize(dictionary_matchers)
         @dictionary_matchers = dictionary_matchers
       end
 
+      # Returns l33t-substituted dictionary matches found in password.
+      #
+      # @param password [String]
+      # @return [Array<MatchBuilder>] matches with pattern "dictionary" and l33t: true
       def matches(password)
         matches = []
         lowercased_password = password.downcase
@@ -44,14 +51,19 @@ module Zxcvbn
         matches
       end
 
+      # Returns a copy of password with each character replaced according to sub.
+      #
+      # @param password [String]
+      # @param sub [Hash{String => String}] character substitution map
+      # @return [String]
       def translate(password, sub)
-        result = String.new
-        password.each_char do |chr|
-          result << (sub[chr] || chr)
-        end
-        result
+        password.gsub(Regexp.union(sub.keys), sub)
       end
 
+      # Returns the subset of {L33T_TABLE} whose l33t characters appear in password.
+      #
+      # @param password [String] lowercased password
+      # @return [Hash{String => Array<String>}]
       def relevent_l33t_subtable(password)
         filtered = {}
         L33T_TABLE.each do |letter, subs|
@@ -61,19 +73,15 @@ module Zxcvbn
         filtered
       end
 
+      # Enumerates all possible substitution combinations for the given l33t subtable.
+      #
+      # @param table [Hash{String => Array<String>}] relevant l33t subtable
+      # @return [Array<Hash{String => String}>] list of substitution maps to try
       def l33t_subs(table)
         keys = table.keys
         subs = [[]]
         subs = find_substitutions(subs, table, keys)
-        new_subs = []
-        subs.each do |sub|
-          hash = {}
-          sub.each do |l33t_char, chr|
-            hash[l33t_char] = chr
-          end
-          new_subs << hash
-        end
-        new_subs
+        subs.map(&:to_h)
       end
 
       private
@@ -83,16 +91,11 @@ module Zxcvbn
         token = password.slice(match.i, length)
         return if token.downcase == match.matched_word.downcase
 
-        match_substitutions = {}
-        substitution.each do |s, letter|
-          match_substitutions[s] = letter if token.include?(s)
-        end
+        match_substitutions = substitution.select { |s, _| token.include?(s) }
         match.l33t = true
         match.token = token
         match.sub = match_substitutions
-        match.sub_display = match_substitutions.map do |k, v|
-          "#{k} -> #{v}"
-        end.join(', ')
+        match.sub_display = match_substitutions.map { |k, v| "#{k} -> #{v}" }.join(', ')
         matches << match
       end
 
@@ -100,21 +103,14 @@ module Zxcvbn
         return subs if keys.empty?
 
         first_key = keys[0]
-        rest_keys = keys[1..-1]
+        rest_keys = keys[1..]
         next_subs = []
         table[first_key].each do |l33t_char|
           subs.each do |sub|
-            dup_l33t_index = -1
-            (0...sub.length).each do |i|
-              if sub[i][0] == l33t_char
-                dup_l33t_index = i
-                break
-              end
-            end
+            dup_l33t_index = sub.find_index { |pair| pair[0] == l33t_char }
 
-            if dup_l33t_index == -1
-              sub_extension = sub + [[l33t_char, first_key]]
-              next_subs << sub_extension
+            if dup_l33t_index.nil?
+              next_subs << (sub + [[l33t_char, first_key]])
             else
               sub_alternative = sub.dup
               sub_alternative[dup_l33t_index, 1] = [[l33t_char, first_key]]

data/lib/zxcvbn/matchers/regex_helpers.rb

@@ -1,10 +1,22 @@
 # frozen_string_literal: true
 
-require 'zxcvbn/match'
+require 'zxcvbn/match_builder'
 
 module Zxcvbn
+  # Namespace for all password pattern matchers.
+  # @api private
   module Matchers
+    # Shared helper for iterating non-overlapping regex matches over a password.
+    # @api private
     module RegexHelpers
+      # Yields a {Match} and the underlying MatchData for every non-overlapping
+      # occurrence of regex in password.
+      #
+      # @param regex [Regexp] pattern to search for
+      # @param password [String] the password to search
+      # @yieldparam match [MatchBuilder] match with i, j, and token set
+      # @yieldparam re_match [MatchData] the underlying MatchData object
+      # @return [void]
       def re_match_all(regex, password)
         pos = 0
         while (re_match = regex.match(password, pos))
@@ -12,11 +24,7 @@ module Zxcvbn
           pos = j
           j -= 1
 
-          match = Match.new(
-            i: i,
-            j: j,
-            token: password.slice(i, j - i + 1)
-          )
+          match = MatchBuilder.new(i:, j:, token: password.slice(i, j - i + 1))
           yield match, re_match
         end
       end

data/lib/zxcvbn/matchers/repeat.rb

@@ -1,30 +1,61 @@
 # frozen_string_literal: true
 
-require 'zxcvbn/match'
+require 'zxcvbn/match_builder'
 
 module Zxcvbn
   module Matchers
+    # Finds repeated substrings in a password (e.g. "abcabc", "aaaa").
+    #
+    # Uses a greedy/lazy regex disambiguation strategy from zxcvbn.js v4:
+    # prefer the greedier match unless the lazy match is longer, then use
+    # LAZY_ANCHORED to extract the minimal repeating unit (base_token).
+    # @api private
     class Repeat
+      # Greedily matches the longest repeated substring.
+      GREEDY        = /(.+)\1+/
+      # Lazily matches the shortest repeated substring.
+      LAZY          = /(.+?)\1+/
+      # Anchored lazy pattern used to extract the minimal base token.
+      LAZY_ANCHORED = /^(.+?)\1+$/
+
+      # Find all repeated-substring matches in the password.
+      #
+      # @param password [String] the password to search
+      # @return [Array<MatchBuilder>] matches with pattern 'repeat', each containing
+      #   base_token (the repeated unit) and repeat_count
       def matches(password)
         result = []
-        i = 0
-        while i < password.length
-          cur_char = password[i]
-          j = i + 1
-          j += 1 while cur_char == password[j]
-
-          if j - i > 2 # don't consider length 1 or 2 chains.
-            result << Match.new(
-              pattern: 'repeat',
-              i: i,
-              j: j - 1,
-              token: password.slice(i, j - i),
-              repeated_char: cur_char
-            )
+        last_index = 0
+
+        while last_index < password.length
+          greedy_match = GREEDY.match(password, last_index)
+          lazy_match   = LAZY.match(password, last_index)
+          break unless greedy_match
+
+          if greedy_match[0].length > lazy_match[0].length
+            rx_match   = greedy_match
+            base_token = LAZY_ANCHORED.match(rx_match[0])[1]
+          else
+            rx_match   = lazy_match
+            base_token = rx_match[1]
           end
 
-          i = j
+          i     = rx_match.begin(0)
+          j     = rx_match.end(0) - 1
+          token = rx_match[0]
+
+          result << MatchBuilder.new(
+            pattern: 'repeat',
+            i:,
+            j:,
+            token:,
+            base_token:,
+            repeat_count: token.length / base_token.length
+          )
+
+          last_index = j + 1
         end
+
         result
       end
     end

data/lib/zxcvbn/matchers/sequences.rb

@@ -1,67 +1,77 @@
 # frozen_string_literal: true
 
-require 'zxcvbn/match'
+require 'zxcvbn/match_builder'
 
 module Zxcvbn
   module Matchers
+    # Matches monotonically incrementing or decrementing character sequences,
+    # such as "abcde", "54321", or "ZYXW".
+    # @api private
     class Sequences
-      SEQUENCES = {
-        'lower' => 'abcdefghijklmnopqrstuvwxyz',
-        'upper' => 'ABCDEFGHIJKLMNOPQRSTUVWXYZ',
-        'digits' => '01234567890'
-      }.freeze
+      # Maximum absolute step between adjacent characters for a valid sequence.
+      MAX_DELTA  = 5
+      # Matches tokens that are all lowercase letters.
+      ALL_LOWER  = /^[a-z]+$/
+      # Matches tokens that are all uppercase letters.
+      ALL_UPPER  = /^[A-Z]+$/
+      # Matches tokens that are all digits.
+      ALL_DIGITS = /^\d+$/
 
-      def seq_match_length(password, from, direction, seq)
-        index_from = seq.index(password[from])
-        j = 1
-        while from + j < password.length &&
-              password[from + j] == seq[index_from + direction * j]
-          j += 1
-        end
-        j
-      end
+      # @param password [String]
+      # @return [Array<MatchBuilder>] matches with pattern "sequence"
+      def matches(password)
+        return [] if password.length < 2
 
-      # find the first matching sequence, and return with
-      # direction, if characters are one apart in the sequence
-      def applicable_sequence(password, i)
-        SEQUENCES.each do |name, sequence|
-          index1 = sequence.index(password[i])
-          index2 = sequence.index(password[i + 1])
-          next unless index1 && index2
+        result = []
+        start = 0
+        last_delta = nil
 
-          seq_direction = index2 - index1
-          return [name, sequence, seq_direction] if [-1, 1].include?(seq_direction)
+        emit = lambda do |seq_end, delta|
+          return if delta.nil?
 
-          return nil
+          abs_delta = delta.abs
+          return unless abs_delta.positive? && abs_delta <= MAX_DELTA
+
+          len = seq_end - start + 1
+          return unless len > 2 || abs_delta == 1
+
+          token = password[start, len]
+          seq_name, seq_space = classify(token)
+          result << MatchBuilder.new(
+            pattern: 'sequence',
+            i: start,
+            j: seq_end,
+            token:,
+            sequence_name: seq_name,
+            sequence_space: seq_space,
+            ascending: delta.positive?
+          )
         end
-      end
 
-      def matches(password)
-        result = []
-        i = 0
-        while i < password.length - 1
-          seq_name, seq, seq_direction = applicable_sequence(password, i)
+        (1...password.length).each do |i|
+          delta = password[i].ord - password[i - 1].ord
+          last_delta = delta if last_delta.nil?
+          next if delta == last_delta
 
-          if seq
-            length = seq_match_length(password, i, seq_direction, seq)
-            if length > 2
-              result << Match.new(
-                pattern: 'sequence',
-                i: i,
-                j: i + length - 1,
-                token: password[i, length],
-                sequence_name: seq_name,
-                sequence_space: seq.length,
-                ascending: seq_direction == 1
-              )
-            end
-            i += length - 1
-          else
-            i += 1
-          end
+          emit.call(i - 1, last_delta)
+          start = i - 1
+          last_delta = delta
         end
+        emit.call(password.length - 1, last_delta)
+
         result
       end
+
+      private
+
+      def classify(token)
+        case token
+        when ALL_LOWER  then ['lower', 26]
+        when ALL_UPPER  then ['upper', 26]
+        when ALL_DIGITS then ['digits', 10]
+        else                 ['unicode', 26]
+        end
+      end
     end
   end
 end

data/lib/zxcvbn/matchers/spatial.rb

@@ -1,14 +1,23 @@
 # frozen_string_literal: true
 
-require 'zxcvbn/match'
+require 'zxcvbn/match_builder'
 
 module Zxcvbn
   module Matchers
+    # Matches keyboard spatial patterns (e.g. "qwerty", "asdf") across all
+    # configured adjacency graphs.
+    # @api private
     class Spatial
+      # Matches characters that require the Shift key on a standard keyboard.
+      SHIFTED_RX = /[~!@#$%^&*()_+QWERTYUIOP{}|ASDFGHJKL:"ZXCVBNM<>?]/
+
+      # @param graphs [Hash{String => Hash}] adjacency graph data keyed by graph name
       def initialize(graphs)
         @graphs = graphs
       end
 
+      # @param password [String]
+      # @return [Array<MatchBuilder>] matches with pattern "spatial" across all graphs
       def matches(password)
         results = []
         @graphs.each do |graph_name, graph|
@@ -17,14 +26,21 @@ module Zxcvbn
         results
       end
 
+      # Returns spatial matches found in password using a single adjacency graph.
+      #
+      # @param graph [Hash] adjacency map for each key character
+      # @param graph_name [String] name of the graph (e.g. "qwerty")
+      # @param password [String]
+      # @return [Array<MatchBuilder>] matches with pattern "spatial"
       def matches_for_graph(graph, graph_name, password)
         result = []
+        keyboard_graph = %w[qwerty dvorak].include?(graph_name)
         i = 0
         while i < password.length - 1
           j = i + 1
           last_direction = nil
           turns = 0
-          shifted_count = 0
+          shifted_count = keyboard_graph && SHIFTED_RX.match?(password[i]) ? 1 : 0
           loop do
             prev_char = password[j - 1]
             found = false
@@ -60,14 +76,14 @@ module Zxcvbn
             else
               # otherwise push the pattern discovered so far, if any...
               if j - i > 2 # don't consider length 1 or 2 chains.
-                result << Match.new(
+                result << MatchBuilder.new(
                   pattern: 'spatial',
-                  i: i,
+                  i:,
                   j: j - 1,
                   token: password.slice(i, j - i),
                   graph: graph_name,
-                  turns: turns,
-                  shifted_count: shifted_count
+                  turns:,
+                  shifted_count:
                 )
               end
               # ...and then start a new search for the rest of the password.

data/lib/zxcvbn/matchers/year.rb

@@ -4,11 +4,16 @@ require 'zxcvbn/matchers/regex_helpers'
 
 module Zxcvbn
   module Matchers
+    # Matches 4-digit year substrings (1900–2019) in the password.
+    # @api private
     class Year
       include RegexHelpers
 
-      YEAR_REGEX = /19\d\d|200\d|201\d/.freeze
+      # Matches years from 1900 to 2019, matching zxcvbn.js v4.
+      YEAR_REGEX = /19\d\d|200\d|201\d/
 
+      # @param password [String]
+      # @return [Array<MatchBuilder>] matches with pattern "year"
       def matches(password)
         result = []
         re_match_all(YEAR_REGEX, password) do |match|

data/lib/zxcvbn/math.rb

@@ -1,35 +1,14 @@
 # frozen_string_literal: true
 
 module Zxcvbn
+  # Mathematical utilities used by the guess estimation logic.
+  # @api private
   module Math
-    def bruteforce_cardinality(password)
-      is_type_of = {}
-
-      password.each_byte do |ordinal|
-        case ordinal
-        when (48..57)
-          is_type_of['digits'] = true
-        when (65..90)
-          is_type_of['upper'] = true
-        when (97..122)
-          is_type_of['lower'] = true
-        else
-          is_type_of['symbols'] = true
-        end
-      end
-
-      cardinality = 0
-      cardinality += 10 if is_type_of['digits']
-      cardinality += 26 if is_type_of['upper']
-      cardinality += 26 if is_type_of['lower']
-      cardinality += 33 if is_type_of['symbols']
-      cardinality
-    end
-
-    def lg(n)
-      ::Math.log(n, 2)
-    end
-
+    # Computes the binomial coefficient C(n, k) ("n choose k").
+    #
+    # @param n [Integer]
+    # @param k [Integer]
+    # @return [Integer]
     def nCk(n, k)
       return 0 if k > n
       return 1 if k.zero?
@@ -47,10 +26,18 @@ module Zxcvbn
       r
     end
 
+    # Returns the precomputed average key-adjacency degree for a keyboard graph.
+    #
+    # @param graph_name [String] e.g. "qwerty" or "keypad"
+    # @return [Float]
     def average_degree_for_graph(graph_name)
       data.graph_stats[graph_name][:average_degree]
     end
 
+    # Returns the number of starting positions (keys) in a keyboard graph.
+    #
+    # @param graph_name [String] e.g. "qwerty" or "keypad"
+    # @return [Integer]
     def starting_positions_for_graph(graph_name)
       data.graph_stats[graph_name][:starting_positions]
     end