zxcvbn-ruby 1.2.0 → 1.4.0

data/lib/zxcvbn/password_strength.rb

@@ -1,4 +1,6 @@
-require 'benchmark'
+# frozen_string_literal: true
+
+require 'zxcvbn/clock'
 require 'zxcvbn/feedback_giver'
 require 'zxcvbn/omnimatch'
 require 'zxcvbn/scorer'
@@ -11,9 +13,9 @@ module Zxcvbn
     end
 
     def test(password, user_inputs = [])
-      password = password || ''
+      password ||= ''
       result = nil
-      calc_time = Benchmark.realtime do
+      calc_time = Clock.realtime do
         matches = @omnimatch.matches(password, user_inputs)
         result = @scorer.minimum_entropy_match_sequence(password, matches)
       end
@@ -22,4 +24,4 @@ module Zxcvbn
       result
     end
   end
-end
+end

data/lib/zxcvbn/score.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Zxcvbn
   class Score
     attr_accessor :entropy, :crack_time, :crack_time_display, :score, :pattern,
@@ -12,4 +14,4 @@ module Zxcvbn
       @password           = options[:password]
     end
   end
-end
+end

data/lib/zxcvbn/scorer.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'zxcvbn/entropy'
 require 'zxcvbn/crack_time'
 require 'zxcvbn/score'
@@ -16,19 +18,22 @@ module Zxcvbn
 
     def minimum_entropy_match_sequence(password, matches)
       bruteforce_cardinality = bruteforce_cardinality(password) # e.g. 26 for lowercase
-      up_to_k = []      # minimum entropy up to k.
-      backpointers = [] # for the optimal sequence of matches up to k, holds the final match (match.j == k). null means the sequence ends w/ a brute-force character.
+      up_to_k = [] # minimum entropy up to k.
+      # for the optimal sequence of matches up to k, holds the final match (match.j == k).
+      # null means the sequence ends w/ a brute-force character.
+      backpointers = []
       (0...password.length).each do |k|
         # starting scenario to try and beat: adding a brute-force character to the minimum entropy sequence at k-1.
-        previous_k_entropy = k > 0 ? up_to_k[k-1] : 0
+        previous_k_entropy = k.positive? ? up_to_k[k - 1] : 0
         up_to_k[k] = previous_k_entropy + lg(bruteforce_cardinality)
         backpointers[k] = nil
         matches.select do |match|
           match.j == k
         end.each do |match|
-          i, j = match.i, match.j
+          i = match.i
+          j = match.j
           # see if best entropy up to i-1 + entropy of this match is less than the current minimum at j.
-          previous_i_entropy = i > 0 ? up_to_k[i-1] : 0
+          previous_i_entropy = i.positive? ? up_to_k[i - 1] : 0
           candidate_entropy = previous_i_entropy + calc_entropy(match)
           if up_to_k[j] && candidate_entropy < up_to_k[j]
             up_to_k[j] = candidate_entropy
@@ -54,29 +59,26 @@ module Zxcvbn
       score_for(password, match_sequence, up_to_k)
     end
 
-    def score_for password, match_sequence, up_to_k
-      min_entropy = up_to_k[password.length - 1] || 0  # or 0 corner case is for an empty password ''
+    def score_for(password, match_sequence, up_to_k)
+      min_entropy = up_to_k[password.length - 1] || 0 # or 0 corner case is for an empty password ''
       crack_time = entropy_to_crack_time(min_entropy)
 
       # final result object
       Score.new(
-        :password => password,
-        :entropy => min_entropy.round(3),
-        :match_sequence => match_sequence,
-        :crack_time => crack_time.round(3),
-        :crack_time_display => display_time(crack_time),
-        :score => crack_time_to_score(crack_time)
+        password: password,
+        entropy: min_entropy.round(3),
+        match_sequence: match_sequence,
+        crack_time: crack_time.round(3),
+        crack_time_display: display_time(crack_time),
+        score: crack_time_to_score(crack_time)
       )
     end
 
-
     def pad_with_bruteforce_matches(match_sequence, password, bruteforce_cardinality)
       k = 0
       match_sequence_copy = []
       match_sequence.each do |match|
-        if match.i > k
-          match_sequence_copy << make_bruteforce_match(password, k, match.i - 1, bruteforce_cardinality)
-        end
+        match_sequence_copy << make_bruteforce_match(password, k, match.i - 1, bruteforce_cardinality) if match.i > k
         k = match.j + 1
         match_sequence_copy << match
       end
@@ -85,17 +87,18 @@ module Zxcvbn
       end
       match_sequence_copy
     end
+
     # fill in the blanks between pattern matches with bruteforce "matches"
     # that way the match sequence fully covers the password:
     # match1.j == match2.i - 1 for every adjacent match1, match2.
     def make_bruteforce_match(password, i, j, bruteforce_cardinality)
       Match.new(
-        :pattern => 'bruteforce',
-        :i => i,
-        :j => j,
-        :token => password[i..j],
-        :entropy => lg(bruteforce_cardinality ** (j - i + 1)),
-        :cardinality => bruteforce_cardinality
+        pattern: 'bruteforce',
+        i: i,
+        j: j,
+        token: password.slice(i, j - i + 1),
+        entropy: lg(bruteforce_cardinality**(j - i + 1)),
+        cardinality: bruteforce_cardinality
       )
     end
   end

data/lib/zxcvbn/tester.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
-require "zxcvbn/data"
-require "zxcvbn/password_strength"
+require 'zxcvbn/data'
+require 'zxcvbn/password_strength'
 
 module Zxcvbn
   # Allows you to test the strength of multiple passwords without reading and

data/lib/zxcvbn/trie.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Zxcvbn
+  # A trie (prefix tree) data structure for efficient dictionary matching.
+  # Provides fast prefix-based lookups to eliminate unnecessary substring checks.
+  #
+  # @see https://en.wikipedia.org/wiki/Trie
+  class Trie
+    def initialize
+      @root = {}
+    end
+
+    # Insert a word and its rank into the trie
+    # @param word [String] the word to insert
+    # @param rank [Integer] the rank/frequency of the word
+    def insert(word, rank)
+      node = @root
+      word.each_char do |char|
+        node[char] ||= {}
+        node = node[char]
+      end
+      node[:rank] = rank
+    end
+
+    # Search for all words in the text starting from a given position
+    # @param text [String] the text to search in
+    # @param start_pos [Integer] the starting position
+    # @return [Array<Array>] array of [word, rank, start, end] tuples
+    def search_prefixes(text, start_pos)
+      results = []
+      node = @root
+
+      (start_pos...text.length).each do |i|
+        char = text[i]
+        break unless node[char]
+
+        node = node[char]
+        results << [text[start_pos..i], node[:rank], start_pos, i] if node[:rank]
+      end
+
+      results
+    end
+  end
+end

data/lib/zxcvbn/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Zxcvbn
-  VERSION = '1.2.0'
+  VERSION = '1.4.0'
 end

data/lib/zxcvbn.rb

@@ -1,11 +1,13 @@
+# frozen_string_literal: true
+
 require 'pathname'
 require 'zxcvbn/version'
 require 'zxcvbn/tester'
 
 module Zxcvbn
-  extend self
+  module_function
 
-  DATA_PATH = Pathname(File.expand_path('../../data', __FILE__))
+  DATA_PATH = Pathname(File.expand_path('../data', __dir__))
 
   # Returns a Zxcvbn::Score for the given password
   #

data/sig/README.md

@@ -0,0 +1,65 @@
+# RBS Type Signatures
+
+This directory contains [RBS](https://github.com/ruby/rbs) type signatures for the zxcvbn-ruby gem.
+
+## What is RBS?
+
+RBS is Ruby's type signature language. It provides a way to describe the structure of Ruby programs with:
+- Class and module definitions
+- Method signatures with parameter and return types
+- Instance variables and constants
+- Duck typing and union types
+
+## Usage
+
+### Validating Type Signatures
+
+To validate that the RBS files are syntactically correct:
+
+```bash
+bundle exec rake rbs:validate
+```
+
+### Runtime Type Checking
+
+To run runtime type checking against the actual Ruby code during tests:
+
+```bash
+bundle exec rake rbs:test
+```
+
+This runs the RSpec test suite with RBS type checking enabled, verifying that method calls match their type signatures at runtime. Note: This takes about 2 minutes to run.
+
+### Other Useful Commands
+
+List all Zxcvbn types:
+```bash
+bundle exec rake rbs:list
+```
+
+Check syntax of RBS files:
+```bash
+bundle exec rake rbs:parse
+```
+
+## File Structure
+
+The signatures mirror the structure of the `lib/` directory:
+
+- `sig/zxcvbn.rbs` - Main Zxcvbn module
+- `sig/zxcvbn/*.rbs` - Core classes (Tester, Score, Match, etc.)
+- `sig/zxcvbn/matchers/*.rbs` - Pattern matcher classes
+
+## Adding New Signatures
+
+When adding new classes or methods to the codebase, remember to:
+
+1. Create or update the corresponding `.rbs` file in the `sig/` directory
+2. Run `bundle exec rake rbs_validate` to ensure the syntax is correct
+3. Keep type signatures in sync with the actual implementation
+
+## Resources
+
+- [RBS Documentation](https://github.com/ruby/rbs)
+- [RBS Syntax Guide](https://github.com/ruby/rbs/blob/master/docs/syntax.md)
+- [Ruby Signature Collection](https://github.com/ruby/gem_rbs_collection)

data/sig/zxcvbn/crack_time.rbs

@@ -0,0 +1,13 @@
+module Zxcvbn
+  module CrackTime
+    SINGLE_GUESS: Float
+    NUM_ATTACKERS: Integer
+    SECONDS_PER_GUESS: Float
+
+    def entropy_to_crack_time: (Numeric entropy) -> Float
+
+    def crack_time_to_score: (Numeric seconds) -> Integer
+
+    def display_time: (Numeric seconds) -> String
+  end
+end

data/sig/zxcvbn/data.rbs

@@ -0,0 +1,31 @@
+module Zxcvbn
+  class Data
+    type ranked_dictionary = Hash[String, Integer]
+    type adjacency_graph = Hash[String, Array[String?]]
+    type graph_stats = Hash[String, { average_degree: Float, starting_positions: Integer }]
+
+    @ranked_dictionaries: Hash[String, ranked_dictionary]
+    @adjacency_graphs: Hash[String, adjacency_graph]
+    @dictionary_tries: Hash[String, Trie]
+    @graph_stats: graph_stats
+
+    attr_reader ranked_dictionaries: Hash[String, ranked_dictionary]
+    attr_reader adjacency_graphs: Hash[String, adjacency_graph]
+    attr_reader dictionary_tries: Hash[String, Trie]
+    attr_reader graph_stats: graph_stats
+
+    def initialize: () -> void
+
+    def add_word_list: (String name, Array[String] list) -> void
+
+    private
+
+    def read_word_list: (String file) -> Array[String]
+
+    def build_tries: () -> Hash[String, Trie]
+
+    def build_trie: (ranked_dictionary ranked_dictionary) -> Trie
+
+    def compute_graph_stats: () -> graph_stats
+  end
+end

data/sig/zxcvbn/dictionary_ranker.rbs

@@ -0,0 +1,7 @@
+module Zxcvbn
+  class DictionaryRanker
+    def self.rank_dictionaries: (Hash[String | Symbol, Array[String]] lists) -> Hash[String | Symbol, Hash[String, Integer]]
+
+    def self.rank_dictionary: (Array[String] words) -> Hash[String, Integer]
+  end
+end

data/sig/zxcvbn/entropy.rbs

@@ -0,0 +1,33 @@
+module Zxcvbn
+  module Entropy
+    include Zxcvbn::Math
+
+    def calc_entropy: (Match match) -> Float
+
+    def repeat_entropy: (Match match) -> Float
+
+    def sequence_entropy: (Match match) -> Float
+
+    def digits_entropy: (Match match) -> Float
+
+    def year_entropy: (Match? match) -> Float
+
+    def date_entropy: (Match match) -> Float
+
+    def dictionary_entropy: (Match match) -> Float
+
+    def extra_uppercase_entropy: (Match match) -> Numeric
+
+    def extra_l33t_entropy: (Match match) -> Numeric
+
+    def spatial_entropy: (Match match) -> Float
+
+    NUM_YEARS: Integer
+    NUM_MONTHS: Integer
+    NUM_DAYS: Integer
+    START_UPPER: Regexp
+    END_UPPER: Regexp
+    ALL_UPPER: Regexp
+    ALL_LOWER: Regexp
+  end
+end

data/sig/zxcvbn/feedback.rbs

@@ -0,0 +1,8 @@
+module Zxcvbn
+  class Feedback
+    attr_accessor warning: String?
+    attr_accessor suggestions: Array[String]
+
+    def initialize: (?warning: String?, ?suggestions: Array[String]) -> void
+  end
+end

data/sig/zxcvbn/feedback_giver.rbs

@@ -0,0 +1,13 @@
+module Zxcvbn
+  class FeedbackGiver
+    NAME_DICTIONARIES: Array[String]
+    DEFAULT_FEEDBACK: Feedback
+    EMPTY_FEEDBACK: Feedback
+
+    def self.get_feedback: (Integer? score, Array[Match] sequence) -> Feedback
+
+    def self.get_match_feedback: (Match match, bool is_sole_match) -> Feedback?
+
+    def self.get_dictionary_match_feedback: (Match match, bool is_sole_match) -> Feedback
+  end
+end

data/sig/zxcvbn/match.rbs

@@ -0,0 +1,38 @@
+module Zxcvbn
+  class Match
+    attr_accessor pattern: String?
+    attr_accessor i: Integer?
+    attr_accessor j: Integer?
+    attr_accessor token: String?
+    attr_accessor matched_word: String?
+    attr_accessor rank: Integer?
+    attr_accessor dictionary_name: String?
+    attr_accessor reversed: bool?
+    attr_accessor l33t: bool?
+    attr_accessor sub: Hash[String, String]?
+    attr_accessor sub_display: String?
+    attr_accessor l: Integer?
+    attr_accessor entropy: Numeric?
+    attr_accessor base_entropy: Numeric?
+    attr_accessor uppercase_entropy: Numeric?
+    attr_accessor l33t_entropy: Numeric?
+    attr_accessor repeated_char: String?
+    attr_accessor sequence_name: String?
+    attr_accessor sequence_space: Integer?
+    attr_accessor ascending: bool?
+    attr_accessor graph: String?
+    attr_accessor turns: Integer?
+    attr_accessor shifted_count: Integer?
+    attr_accessor shiffted_count: Integer?
+    attr_accessor year: Integer?
+    attr_accessor month: Integer?
+    attr_accessor day: Integer?
+    attr_accessor separator: String?
+    attr_accessor cardinality: Integer?
+    attr_accessor offset: Integer?
+
+    def initialize: (**untyped attributes) -> void
+
+    def to_hash: () -> Hash[String, untyped]
+  end
+end

data/sig/zxcvbn/math.rbs

@@ -0,0 +1,13 @@
+module Zxcvbn
+  module Math
+    def bruteforce_cardinality: (String password) -> Integer
+
+    def lg: (Numeric n) -> Float
+
+    def nCk: (Integer n, Integer k) -> Integer
+
+    def average_degree_for_graph: (String graph_name) -> Float
+
+    def starting_positions_for_graph: (String graph_name) -> Integer
+  end
+end

data/sig/zxcvbn/omnimatch.rbs

@@ -0,0 +1,16 @@
+module Zxcvbn
+  class Omnimatch
+    @data: Data
+    @matchers: Array[untyped]
+
+    def initialize: (Data data) -> void
+
+    def matches: (String password, ?Array[String] user_inputs) -> Array[Match]
+
+    private
+
+    def user_input_matchers: (Array[String] user_inputs) -> Array[untyped]
+
+    def build_matchers: () -> Array[untyped]
+  end
+end

data/sig/zxcvbn/password_strength.rbs

@@ -0,0 +1,10 @@
+module Zxcvbn
+  class PasswordStrength
+    @omnimatch: Omnimatch
+    @scorer: Scorer
+
+    def initialize: (Data data) -> void
+
+    def test: (String? password, ?Array[untyped] user_inputs) -> Score
+  end
+end

data/sig/zxcvbn/score.rbs

@@ -0,0 +1,15 @@
+module Zxcvbn
+  class Score
+    attr_accessor entropy: Numeric?
+    attr_accessor crack_time: Numeric?
+    attr_accessor crack_time_display: String?
+    attr_accessor score: Integer?
+    attr_accessor pattern: String?
+    attr_accessor match_sequence: Array[Match]?
+    attr_accessor password: String?
+    attr_accessor calc_time: Float?
+    attr_accessor feedback: Feedback?
+
+    def initialize: (?entropy: Numeric?, ?crack_time: Numeric?, ?crack_time_display: String?, ?score: Integer?, ?match_sequence: Array[Match]?, ?password: String?) -> void
+  end
+end

data/sig/zxcvbn/scorer.rbs

@@ -0,0 +1,20 @@
+module Zxcvbn
+  class Scorer
+    include Entropy
+    include CrackTime
+
+    @data: Data
+
+    attr_reader data: Data
+
+    def initialize: (Data data) -> void
+
+    def minimum_entropy_match_sequence: (String password, Array[Match] matches) -> Score
+
+    def score_for: (String password, Array[Match] match_sequence, Array[Float] up_to_k) -> Score
+
+    def pad_with_bruteforce_matches: (Array[Match] match_sequence, String password, Integer bruteforce_cardinality) -> Array[Match]
+
+    def make_bruteforce_match: (String password, Integer i, Integer j, Integer bruteforce_cardinality) -> Match
+  end
+end

data/sig/zxcvbn/tester.rbs

@@ -0,0 +1,17 @@
+module Zxcvbn
+  class Tester
+    @data: Data
+
+    def initialize: () -> void
+
+    def test: (String? password, ?Array[untyped] user_inputs) -> Score
+
+    def add_word_lists: (Hash[String, Array[untyped]] lists) -> void
+
+    def inspect: () -> String
+
+    private
+
+    def sanitize: (Array[untyped] user_inputs) -> Array[String]
+  end
+end

data/sig/zxcvbn/trie.rbs

@@ -0,0 +1,13 @@
+module Zxcvbn
+  class Trie
+    type node = Hash[untyped, untyped]
+
+    @root: node
+
+    def initialize: () -> void
+
+    def insert: (String word, Integer rank) -> void
+
+    def search_prefixes: (String text, Integer start_pos) -> Array[[String, Integer?, Integer, Integer]]
+  end
+end

data/sig/zxcvbn.rbs

@@ -0,0 +1,10 @@
+module Zxcvbn
+  VERSION: String
+
+  DATA_PATH: Pathname
+
+  type word_list = Hash[String, Array[String]]
+  type user_inputs = Array[String]
+
+  def self.test: (String? password, ?user_inputs user_inputs, ?word_list word_lists) -> Score
+end