zxcvbn-ruby 1.4.0 → 2.0.0

data/lib/zxcvbn/clock.rb

@@ -1,7 +1,13 @@
 # frozen_string_literal: true
 
 module Zxcvbn
+  # Monotonic-clock utility for measuring elapsed time.
+  # @api private
   module Clock
+    # Yields to the block and returns the elapsed time in seconds.
+    #
+    # @yield block whose execution time is measured
+    # @return [Float] elapsed seconds as a monotonic-clock duration
     def self.realtime
       start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
       yield

data/lib/zxcvbn/crack_time.rb

@@ -1,30 +1,56 @@
 # frozen_string_literal: true
 
 module Zxcvbn
+  # Mixin that converts a guess count into estimated crack times and scores.
+  #
+  # Provides {estimate_attack_times}, {guesses_to_score}, and {display_time}
+  # mirroring the crack-time logic from zxcvbn.js v4.
+  # @api private
   module CrackTime
-    SINGLE_GUESS = 0.010
-    NUM_ATTACKERS = 100
+    ATTACK_SCENARIOS = {
+      'online_throttling_100_per_hour' => 100.0 / 3600,
+      'online_no_throttling_10_per_second' => 10.0,
+      'offline_slow_hashing_1e4_per_second' => 1e4,
+      'offline_fast_hashing_1e10_per_second' => 1e10
+    }.freeze
 
-    SECONDS_PER_GUESS = SINGLE_GUESS / NUM_ATTACKERS
-
-    def entropy_to_crack_time(entropy)
-      0.5 * (2**entropy) * SECONDS_PER_GUESS
+    # Returns the estimated seconds and display strings for each attack scenario.
+    #
+    # @param guesses [Numeric] estimated guess count
+    # @return [Hash] with :crack_times_seconds and :crack_times_display
+    def estimate_attack_times(guesses)
+      seconds = ATTACK_SCENARIOS.transform_values { |rate| [guesses / rate, Float::MAX].min }
+      display = seconds.transform_values { |s| display_time(s) }
+      { crack_times_seconds: seconds, crack_times_display: display }
     end
 
-    def crack_time_to_score(seconds)
-      if seconds < 10**2
+    # Convert a guess count to a 0–4 score using zxcvbn.js v4 thresholds.
+    #
+    # A small delta (5) is added to each threshold so that passwords just at
+    # a boundary are not bumped up to the next score band by floating-point
+    # noise in the guess count.
+    #
+    # @param guesses [Numeric] estimated number of guesses to crack the password
+    # @return [Integer] score in the range 0..4
+    def guesses_to_score(guesses)
+      delta = 5
+      if guesses < 1_000 + delta
         0
-      elsif seconds < 10**4
+      elsif guesses < 1_000_000 + delta
         1
-      elsif seconds < 10**6
+      elsif guesses < 100_000_000 + delta
         2
-      elsif seconds < 10**8
+      elsif guesses < 10_000_000_000 + delta
         3
       else
         4
       end
     end
 
+    # Convert a number of seconds into a human-readable display string.
+    #
+    # @param seconds [Numeric] duration in seconds
+    # @return [String] e.g. "instant", "3 minutes", "centuries"
     def display_time(seconds)
       minute  = 60
       hour    = minute * 60
@@ -33,18 +59,26 @@ module Zxcvbn
       year    = month * 12
       century = year * 100
 
-      if seconds < minute
-        'instant'
+      if seconds < 1
+        'less than a second'
+      elsif seconds < minute
+        t = seconds.round
+        "#{t} second#{'s' unless t == 1}"
       elsif seconds < hour
-        "#{1 + (seconds / minute).ceil} minutes"
+        t = (seconds / minute).round
+        "#{t} minute#{'s' unless t == 1}"
       elsif seconds < day
-        "#{1 + (seconds / hour).ceil} hours"
+        t = (seconds / hour).round
+        "#{t} hour#{'s' unless t == 1}"
       elsif seconds < month
-        "#{1 + (seconds / day).ceil} days"
+        t = (seconds / day).round
+        "#{t} day#{'s' unless t == 1}"
       elsif seconds < year
-        "#{1 + (seconds / month).ceil} months"
+        t = (seconds / month).round
+        "#{t} month#{'s' unless t == 1}"
       elsif seconds < century
-        "#{1 + (seconds / year).ceil} years"
+        t = (seconds / year).round
+        "#{t} year#{'s' unless t == 1}"
       else
         'centuries'
       end

data/lib/zxcvbn/data.rb

@@ -1,30 +1,76 @@
 # frozen_string_literal: true
 
 require 'json'
+require 'pathname'
 require 'zxcvbn/dictionary_ranker'
 require 'zxcvbn/trie'
 
 module Zxcvbn
+  # Holds all loaded frequency lists, adjacency graphs, tries, and graph stats
+  # used by the matchers and scorer.
+  #
+  # @attr_reader adjacency_graphs [Hash{String => Hash}] keyboard adjacency data
+  # @attr_reader graph_stats [Hash{String => Hash}] precomputed average degree and key count
+  # @attr_reader dictionaries [#ranked, #tries] consistent snapshot of ranked dictionaries and
+  #   their tries; use this for concurrent reads to guarantee the pair is always in sync
+  # @api private
   class Data
+    DATA_PATH = Pathname(File.expand_path('../../data', __dir__))
+    private_constant :DATA_PATH
+
+    # Consistent named pair of ranked dictionaries and their tries.
+    Dictionaries = ::Data.define(:ranked, :tries) do
+      def inspect = "#<#{self.class}:0x#{__id__.to_s(16)}>"
+    end
+    private_constant :Dictionaries
+
+    # Built-in dictionary names and the reserved per-call key.
+    # These names cannot be passed to {TesterBuilder#add_word_list}.
+    RESERVED_NAMES = %w[
+      english_wikipedia female_names male_names passwords surnames us_tv_and_film user_inputs
+    ].freeze
+
+    # Loads all built-in frequency lists and adjacency graphs from disk.
     def initialize
-      @ranked_dictionaries = DictionaryRanker.rank_dictionaries(
-        'english' => read_word_list('english.txt'),
+      ranked = DictionaryRanker.rank_dictionaries(
+        'english_wikipedia' => read_word_list('english_wikipedia.txt'),
         'female_names' => read_word_list('female_names.txt'),
         'male_names' => read_word_list('male_names.txt'),
         'passwords' => read_word_list('passwords.txt'),
-        'surnames' => read_word_list('surnames.txt')
-      )
-      @adjacency_graphs = JSON.parse(DATA_PATH.join('adjacency_graphs.json').read)
-      @dictionary_tries = build_tries
-      @graph_stats = compute_graph_stats
+        'surnames' => read_word_list('surnames.txt'),
+        'us_tv_and_film' => read_word_list('us_tv_and_film.txt')
+      ).tap { |r| r.each_value(&:freeze) }.freeze
+      tries = build_tries(ranked).tap { |t| t.each_value(&:freeze) }.freeze
+      @dictionaries = Dictionaries.new(ranked:, tries:)
+      @adjacency_graphs =
+        JSON.parse(DATA_PATH.join('adjacency_graphs.json').read)
+            .tap { |gs| gs.each_value { |g| g.each_value { |a| a.each(&:freeze).freeze }.freeze } }
+            .freeze
+      @graph_stats = compute_graph_stats.each_value(&:freeze).freeze
     end
 
-    attr_reader :ranked_dictionaries, :adjacency_graphs, :dictionary_tries, :graph_stats
+    attr_reader :adjacency_graphs, :graph_stats, :dictionaries
+
+    def inspect = "#<#{self.class}:0x#{__id__.to_s(16)}>"
 
+    # @return [Hash{String => Hash{String => Integer}}] word → rank maps
+    def ranked_dictionaries = @dictionaries.ranked
+
+    # @return [Hash{String => Trie}] prefix tries per dictionary
+    def dictionary_tries = @dictionaries.tries
+
+    # Adds a custom word list and builds a trie for it.
+    #
+    # @param name [String] dictionary name (used as a key in {#ranked_dictionaries})
+    # @param list [Array<String>] ordered words (most common first)
+    # @return [void]
     def add_word_list(name, list)
-      ranked_dict = DictionaryRanker.rank_dictionary(list)
-      @ranked_dictionaries[name] = ranked_dict
-      @dictionary_tries[name] = build_trie(ranked_dict)
+      ranked_dict = DictionaryRanker.rank_dictionary(list.select { |w| w.is_a?(String) }).freeze
+      trie = Trie.from_ranked(ranked_dict).freeze
+      @dictionaries = @dictionaries.with(
+        ranked: @dictionaries.ranked.merge(name => ranked_dict).freeze,
+        tries: @dictionaries.tries.merge(name => trie).freeze
+      )
     end
 
     private
@@ -33,14 +79,8 @@ module Zxcvbn
       DATA_PATH.join('frequency_lists', file).read.split
     end
 
-    def build_tries
-      @ranked_dictionaries.transform_values { |dict| build_trie(dict) }
-    end
-
-    def build_trie(ranked_dictionary)
-      trie = Trie.new
-      ranked_dictionary.each { |word, rank| trie.insert(word, rank) }
-      trie
+    def build_tries(ranked)
+      ranked.transform_values { |dict| Trie.from_ranked(dict) }
     end
 
     def compute_graph_stats
@@ -52,8 +92,8 @@ module Zxcvbn
         starting_positions = graph.length
 
         stats[graph_name] = {
-          average_degree: average_degree,
-          starting_positions: starting_positions
+          average_degree:,
+          starting_positions:
         }
       end
       stats

data/lib/zxcvbn/dictionary_ranker.rb

@@ -1,13 +1,23 @@
 # frozen_string_literal: true
 
 module Zxcvbn
+  # Converts raw word lists into frequency-ranked dictionaries for matcher use.
+  # @api private
   class DictionaryRanker
+    # Ranks multiple word lists, returning a hash of ranked dictionaries.
+    #
+    # @param lists [Hash{Symbol => Array<String>}] named word lists
+    # @return [Hash{Symbol => Hash{String => Integer}}] lowercased word → rank mappings
     def self.rank_dictionaries(lists)
       lists.transform_values do |words|
         rank_dictionary(words)
       end
     end
 
+    # Ranks a single word list; rank starts at 1 (most common).
+    #
+    # @param words [Array<String>] ordered words (most common first)
+    # @return [Hash{String => Integer}] lowercased word → 1-based rank
     def self.rank_dictionary(words)
       words
         .each_with_index

data/lib/zxcvbn/feedback.rb

@@ -1,12 +1,17 @@
 # frozen_string_literal: true
 
 module Zxcvbn
-  class Feedback
-    attr_accessor :warning, :suggestions
-
-    def initialize(options = {})
-      @warning     = options[:warning]
-      @suggestions = options[:suggestions] || []
+  # Human-readable feedback for a low-scoring password.
+  #
+  # @!attribute [r] warning
+  #   @return [String] a single warning message, or empty string
+  # @!attribute [r] suggestions
+  #   @return [Array<String>] ordered list of improvement tips
+  Feedback = ::Data.define(:warning, :suggestions) do
+    # @param warning [String] warning message (default: empty string)
+    # @param suggestions [Array<String>] improvement tips (default: [])
+    def initialize(warning: nil, suggestions: [])
+      super(warning: warning || '', suggestions: suggestions.freeze)
     end
   end
 end

data/lib/zxcvbn/feedback_giver.rb

@@ -1,9 +1,11 @@
 # frozen_string_literal: true
 
-require 'zxcvbn/entropy'
+require 'zxcvbn/guesses'
 require 'zxcvbn/feedback'
 
 module Zxcvbn
+  # Generates human-readable {Feedback} for a password given its score and match sequence.
+  # @api private
   class FeedbackGiver
     NAME_DICTIONARIES = %w[surnames male_names female_names].freeze
 
@@ -12,10 +14,15 @@ module Zxcvbn
         'Use a few words, avoid common phrases',
         'No need for symbols, digits, or uppercase letters'
       ]
-    ).freeze
+    )
 
-    EMPTY_FEEDBACK = Feedback.new.freeze
+    EMPTY_FEEDBACK = Feedback.new
 
+    # Returns feedback appropriate for the given score and match sequence.
+    #
+    # @param score [Integer] 0–4 score from the scorer
+    # @param sequence [Array<Match>] optimal match sequence
+    # @return [Feedback]
     def self.get_feedback(score, sequence)
       # starting feedback
       return DEFAULT_FEEDBACK if sequence.empty?
@@ -25,7 +32,7 @@ module Zxcvbn
 
       # tie feedback to the longest match for longer sequences
       longest_match = sequence[0]
-      sequence[1..-1].each do |match|
+      sequence[1..].each do |match|
         longest_match = match if match.token.length > longest_match.token.length
       end
 
@@ -33,36 +40,46 @@ module Zxcvbn
       extra_feedback = 'Add another word or two. Uncommon words are better.'
 
       if feedback.nil?
-        feedback = Feedback.new(suggestions: [extra_feedback])
+        Feedback.new(suggestions: [extra_feedback])
       else
-        feedback.suggestions.unshift extra_feedback
+        feedback.with(suggestions: [extra_feedback, *feedback.suggestions])
       end
-
-      feedback
     end
 
+    # Returns pattern-specific feedback for a single match, or nil if none applies.
+    #
+    # @param match [Match]
+    # @param is_sole_match [Boolean] true when this is the only match in the sequence
+    # @return [Feedback, nil]
     def self.get_match_feedback(match, is_sole_match)
       case match.pattern
       when 'dictionary'
         get_dictionary_match_feedback match, is_sole_match
 
       when 'spatial'
-        warning = if match.turns == 1
-                    'Straight rows of keys are easy to guess'
-                  else
-                    'Short keyboard patterns are easy to guess'
-                  end
+        warning =
+          if match.turns == 1
+            'Straight rows of keys are easy to guess'
+          else
+            'Short keyboard patterns are easy to guess'
+          end
 
         Feedback.new(
-          warning: warning,
+          warning:,
           suggestions: [
             'Use a longer keyboard pattern with more turns'
           ]
         )
 
       when 'repeat'
+        warning =
+          if match.base_token.length == 1
+            'Repeats like "aaa" are easy to guess'
+          else
+            'Repeats like "abcabcabc" are only slightly harder to guess than "abc"'
+          end
         Feedback.new(
-          warning: 'Repeats like "aaa" are easy to guess',
+          warning:,
           suggestions: [
             'Avoid repeated words and characters'
           ]
@@ -76,6 +93,15 @@ module Zxcvbn
           ]
         )
 
+      when 'year'
+        Feedback.new(
+          warning: 'Recent years are easy to guess',
+          suggestions: [
+            'Avoid recent years',
+            'Avoid years that are associated with you'
+          ]
+        )
+
       when 'date'
         Feedback.new(
           warning: 'Dates are often easy to guess',
@@ -86,49 +112,48 @@ module Zxcvbn
       end
     end
 
+    # Returns feedback specific to a dictionary match.
+    #
+    # @param match [Match] a dictionary pattern match
+    # @param is_sole_match [Boolean] true when this is the only match in the sequence
+    # @return [Feedback]
     def self.get_dictionary_match_feedback(match, is_sole_match)
-      warning = if match.dictionary_name == 'passwords'
-                  if is_sole_match && !match.l33t && !match.reversed
-                    if match.rank <= 10
-                      'This is a top-10 common password'
-                    elsif match.rank <= 100
-                      'This is a top-100 common password'
-                    else
-                      'This is a very common password'
-                    end
-                  else
-                    'This is similar to a commonly used password'
-                  end
-                elsif NAME_DICTIONARIES.include? match.dictionary_name
-                  if is_sole_match
-                    'Names and surnames by themselves are easy to guess'
-                  else
-                    'Common names and surnames are easy to guess'
-                  end
-                end
+      warning =
+        if match.dictionary_name == 'passwords'
+          if is_sole_match && !match.l33t && !match.reversed
+            if match.rank <= 10
+              'This is a top-10 common password'
+            elsif match.rank <= 100
+              'This is a top-100 common password'
+            else
+              'This is a very common password'
+            end
+          elsif (match.guesses_log10 || 0) <= 4
+            'This is similar to a commonly used password'
+          end
+        elsif match.dictionary_name == 'english_wikipedia'
+          'A word by itself is easy to guess' if is_sole_match
+        elsif NAME_DICTIONARIES.include? match.dictionary_name
+          if is_sole_match
+            'Names and surnames by themselves are easy to guess'
+          else
+            'Common names and surnames are easy to guess'
+          end
+        end
 
       suggestions = []
       word = match.token
 
-      if word =~ Zxcvbn::Entropy::START_UPPER
-        suggestions.push "Capitalization doesn't help very much"
-      elsif word =~ Zxcvbn::Entropy::ALL_UPPER && word.downcase != word
-        suggestions.push(
-          'All-uppercase is almost as easy to guess as all-lowercase'
-        )
+      if word =~ Zxcvbn::Guesses::START_UPPER
+        suggestions.push("Capitalization doesn't help very much")
+      elsif word =~ Zxcvbn::Guesses::ALL_UPPER && word.downcase != word
+        suggestions.push('All-uppercase is almost as easy to guess as all-lowercase')
       end
 
-      if match.l33t
-        suggestions.push(
-          "Predictable substitutions like '@' instead of 'a' \
-don't help very much"
-        )
-      end
+      suggestions.push("Reversed words aren't much harder to guess") if match.reversed && match.token.length >= 4
+      suggestions.push("Predictable substitutions like '@' instead of 'a' don't help very much") if match.l33t
 
-      Feedback.new(
-        warning: warning,
-        suggestions: suggestions
-      )
+      Feedback.new(warning:, suggestions:)
     end
   end
 end