zxcvbn-ruby 1.4.0 → 2.0.1

data/lib/zxcvbn.rb

@@ -1,22 +1,62 @@
 # frozen_string_literal: true
 
-require 'pathname'
 require 'zxcvbn/version'
 require 'zxcvbn/tester'
+require 'zxcvbn/tester_builder'
 
+# Ruby port of zxcvbn.js — realistic password strength estimation.
+#
+# Analyses a password against dictionary lists, keyboard patterns, dates,
+# sequences, and repeats to produce a {Score} with guess estimates and
+# human-readable crack-time display strings.
 module Zxcvbn
   module_function
 
-  DATA_PATH = Pathname(File.expand_path('../data', __dir__))
+  # Mutex protecting lazy initialisation of the shared default {Tester}.
+  DEFAULT_TESTER_MUTEX = Mutex.new
+  private_constant :DEFAULT_TESTER_MUTEX
 
-  # Returns a Zxcvbn::Score for the given password
+  # Returns a Zxcvbn::Score for the given password.
+  #
+  # Reuses a shared {Tester} instance across calls. For custom word lists or
+  # options, use {.tester_builder} to build a dedicated {Tester}.
+  #
+  # Raises {PasswordTooLong} (a subclass of +ArgumentError+) if the password
+  # exceeds the configured limit (default: 256 characters). Override process-wide
+  # via the +ZXCVBN_MAX_PASSWORD_LENGTH+ environment variable; for per-call limits,
+  # use {.tester_builder} with {TesterBuilder#max_password_length}.
   #
   # Example:
   #
   #   Zxcvbn.test("password").score #=> 0
-  def test(password, user_inputs = [], word_lists = {})
-    tester = Tester.new
-    tester.add_word_lists(word_lists)
-    tester.test(password, user_inputs)
+  #
+  # @param password [String] the password to evaluate
+  # @param user_inputs [Array<String>] caller-supplied words to treat as known
+  # @return [Score]
+  # @raise [PasswordTooLong] if the password exceeds the maximum length
+  def test(password, user_inputs = [])
+    default_tester.test(password, user_inputs)
+  end
+
+  # Returns a new {TesterBuilder} for constructing a {Tester} with custom
+  # word lists and options.
+  #
+  # Example:
+  #
+  #   tester = Zxcvbn
+  #     .tester_builder
+  #     .add_word_list('company', %w[acme corp])
+  #     .max_password_length(75)
+  #     .build
+  #
+  # @return [TesterBuilder]
+  def tester_builder
+    TesterBuilder.new
+  end
+
+  # @return [Tester] the shared default tester, constructed on first call
+  def default_tester
+    DEFAULT_TESTER_MUTEX.synchronize { @default_tester ||= tester_builder.build }
   end
+  private_class_method :default_tester
 end

data/sig/zxcvbn/case_helpers.rbs

@@ -0,0 +1,5 @@
+module Zxcvbn
+  module CaseHelpers
+    def self?.downcase_preserving_length: (String string) -> String
+  end
+end

data/sig/zxcvbn/clock.rbs

@@ -0,0 +1,5 @@
+module Zxcvbn
+  module Clock
+    def self.realtime: () { () -> void } -> Float
+  end
+end

data/sig/zxcvbn/crack_time.rbs

@@ -1,12 +1,10 @@
 module Zxcvbn
   module CrackTime
-    SINGLE_GUESS: Float
-    NUM_ATTACKERS: Integer
-    SECONDS_PER_GUESS: Float
+    ATTACK_SCENARIOS: Hash[String, Float]
 
-    def entropy_to_crack_time: (Numeric entropy) -> Float
+    def estimate_attack_times: (Numeric guesses) -> { crack_times_seconds: Hash[String, Float], crack_times_display: Hash[String, String] }
 
-    def crack_time_to_score: (Numeric seconds) -> Integer
+    def guesses_to_score: (Numeric guesses) -> Integer
 
     def display_time: (Numeric seconds) -> String
   end

data/sig/zxcvbn/data.rbs

@@ -4,27 +4,36 @@ module Zxcvbn
     type adjacency_graph = Hash[String, Array[String?]]
     type graph_stats = Hash[String, { average_degree: Float, starting_positions: Integer }]
 
-    @ranked_dictionaries: Hash[String, ranked_dictionary]
+    class Dictionaries
+      attr_reader ranked: Hash[String, ranked_dictionary]
+      attr_reader tries: Hash[String, Trie]
+
+      def initialize: (ranked: Hash[String, ranked_dictionary], tries: Hash[String, Trie]) -> void
+    end
+
+    RESERVED_NAMES: Array[String]
+
+    @dictionaries: Dictionaries
     @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 dictionaries: Dictionaries
     attr_reader adjacency_graphs: Hash[String, adjacency_graph]
-    attr_reader dictionary_tries: Hash[String, Trie]
     attr_reader graph_stats: graph_stats
 
+    def ranked_dictionaries: () -> Hash[String, ranked_dictionary]
+
+    def dictionary_tries: () -> Hash[String, Trie]
+
     def initialize: () -> void
 
-    def add_word_list: (String name, Array[String] list) -> void
+    def add_word_list: (String name, Array[untyped] 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 build_tries: (Hash[String, ranked_dictionary] ranked) -> Hash[String, Trie]
 
     def compute_graph_stats: () -> graph_stats
   end

data/sig/zxcvbn/feedback.rbs

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

data/sig/zxcvbn/guesses.rbs

@@ -0,0 +1,36 @@
+module Zxcvbn
+  module Guesses
+    MIN_GUESSES_BEFORE_GROWING_SEQUENCE: Integer
+    MIN_SUBMATCH_GUESSES_SINGLE_CHAR: Integer
+    MIN_SUBMATCH_GUESSES_MULTI_CHAR: Integer
+    BRUTEFORCE_CARDINALITY: Integer
+    MIN_YEAR_SPACE: Integer
+
+    START_UPPER: Regexp
+    END_UPPER: Regexp
+    ALL_UPPER: Regexp
+    ALL_LOWER: Regexp
+
+    attr_reader reference_year: Integer
+
+    def estimate_guesses: (MatchBuilder match, String password) -> Numeric
+
+    def bruteforce_guesses: (MatchBuilder match) -> Numeric
+
+    def sequence_guesses: (MatchBuilder match) -> Numeric
+
+    def digits_guesses: (MatchBuilder match) -> Integer
+
+    def year_guesses: (MatchBuilder match) -> Integer
+
+    def date_guesses: (MatchBuilder match) -> Numeric
+
+    def spatial_guesses: (MatchBuilder match) -> Numeric
+
+    def dictionary_guesses: (MatchBuilder match) -> Numeric
+
+    def uppercase_variations: (MatchBuilder match) -> Integer
+
+    def l33t_variations: (MatchBuilder match) -> Integer
+  end
+end

data/sig/zxcvbn/match.rbs

@@ -1,38 +1,40 @@
 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?
+  class Match < Data
+    attr_reader pattern: String?
+    attr_reader i: Integer?
+    attr_reader j: Integer?
+    attr_reader token: String?
+    attr_reader matched_word: String?
+    attr_reader rank: Integer?
+    attr_reader dictionary_name: String?
+    attr_reader reversed: bool?
+    attr_reader l33t: bool?
+    attr_reader sub: Hash[String, String]?
+    attr_reader sub_display: String?
+    attr_reader guesses: Numeric?
+    attr_reader guesses_log10: Float?
+    attr_reader base_guesses: Numeric?
+    attr_reader uppercase_variations: Numeric?
+    attr_reader l33t_variations: Numeric?
+    attr_reader base_token: String?
+    attr_reader repeat_count: Integer?
+    attr_reader sequence_name: String?
+    attr_reader sequence_space: Integer?
+    attr_reader ascending: bool?
+    attr_reader graph: String?
+    attr_reader turns: Integer?
+    attr_reader shifted_count: Integer?
+    attr_reader year: Integer?
+    attr_reader month: Integer?
+    attr_reader day: Integer?
+    attr_reader separator: String?
 
-    def initialize: (**untyped attributes) -> void
+    def initialize: (?pattern: String?, ?i: Integer?, ?j: Integer?, ?token: String?, ?matched_word: String?, ?rank: Integer?, ?dictionary_name: String?, ?reversed: bool?, ?l33t: bool?, ?sub: Hash[String, String]?, ?sub_display: String?, ?guesses: Numeric?, ?guesses_log10: Float?, ?base_guesses: Numeric?, ?uppercase_variations: Numeric?, ?l33t_variations: Numeric?, ?base_token: String?, ?repeat_count: Integer?, ?sequence_name: String?, ?sequence_space: Integer?, ?ascending: bool?, ?graph: String?, ?turns: Integer?, ?shifted_count: Integer?, ?year: Integer?, ?month: Integer?, ?day: Integer?, ?separator: String?) -> void
 
-    def to_hash: () -> Hash[String, untyped]
+    def with: (**untyped) -> Match
+
+    def inspect: () -> String
+
+    def pretty_print: (untyped pp) -> void
   end
 end

data/sig/zxcvbn/match_builder.rbs

@@ -0,0 +1,36 @@
+module Zxcvbn
+  class MatchBuilder
+    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 guesses: Numeric?
+    attr_accessor guesses_log10: Float?
+    attr_accessor base_guesses: Numeric?
+    attr_accessor uppercase_variations: Numeric?
+    attr_accessor l33t_variations: Numeric?
+    attr_accessor base_token: String?
+    attr_accessor repeat_count: Integer?
+    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 year: Integer?
+    attr_accessor month: Integer?
+    attr_accessor day: Integer?
+    attr_accessor separator: String?
+
+    def initialize: (?pattern: String?, ?i: Integer?, ?j: Integer?, ?token: String?, ?matched_word: String?, ?rank: Integer?, ?dictionary_name: String?, ?reversed: bool?, ?l33t: bool?, ?sub: Hash[String, String]?, ?sub_display: String?, ?guesses: Numeric?, ?guesses_log10: Float?, ?base_guesses: Numeric?, ?uppercase_variations: Numeric?, ?l33t_variations: Numeric?, ?base_token: String?, ?repeat_count: Integer?, ?sequence_name: String?, ?sequence_space: Integer?, ?ascending: bool?, ?graph: String?, ?turns: Integer?, ?shifted_count: Integer?, ?year: Integer?, ?month: Integer?, ?day: Integer?, ?separator: String?) -> void
+
+    def build: () -> Match
+  end
+end

data/sig/zxcvbn/matchers/date.rbs

@@ -0,0 +1,23 @@
+module Zxcvbn
+  module Matchers
+    class Date
+      MAYBE_DATE_WITH_SEP: Regexp
+      MAYBE_DATE_WITHOUT_SEP: Regexp
+      DATE_SPLITS: Hash[Integer, Array[[Integer, Integer]]]
+      DATE_MIN_YEAR: Integer
+      DATE_MAX_YEAR: Integer
+
+      def matches: (String password, ?reference_year: Integer) -> Array[MatchBuilder]
+
+      def match_with_separator: (String password) -> Array[MatchBuilder]
+
+      def match_without_separator: (String password, ?reference_year: Integer) -> Array[MatchBuilder]
+
+      def map_ints_to_dmy: (Integer int1, Integer int2, Integer int3) -> { year: Integer, month: Integer, day: Integer }?
+
+      def map_ints_to_dm: (Integer day_val, Integer month_val) -> { day: Integer, month: Integer }?
+
+      def expand_year: (Integer year) -> Integer
+    end
+  end
+end

data/sig/zxcvbn/matchers/dictionary.rbs

@@ -0,0 +1,23 @@
+module Zxcvbn
+  module Matchers
+    class Dictionary
+      include CaseHelpers
+
+      @name: String
+      @ranked_dictionary: Data::ranked_dictionary
+      @trie: Trie?
+
+      def initialize: (String name, Data::ranked_dictionary ranked_dictionary, ?Trie? trie) -> void
+
+      def matches: (String password) -> Array[MatchBuilder]
+
+      private
+
+      def trie_matches: (String password, String lowercased_password) -> Array[MatchBuilder]
+
+      def hash_matches: (String password, String lowercased_password) -> Array[MatchBuilder]
+
+      def build_match: (String matched_word, String token, Integer start_pos, Integer end_pos, Integer rank) -> MatchBuilder
+    end
+  end
+end

data/sig/zxcvbn/matchers/digits.rbs

@@ -0,0 +1,11 @@
+module Zxcvbn
+  module Matchers
+    class Digits
+      include RegexHelpers
+
+      DIGITS_REGEX: Regexp
+
+      def matches: (String password) -> Array[MatchBuilder]
+    end
+  end
+end

data/sig/zxcvbn/matchers/l33t.rbs

@@ -0,0 +1,29 @@
+module Zxcvbn
+  module Matchers
+    class L33t
+      include CaseHelpers
+
+      L33T_TABLE: Hash[String, Array[String]]
+
+      @dictionary_matchers: Array[Dictionary]
+
+      def initialize: (Array[Dictionary] dictionary_matchers) -> void
+
+      def matches: (String password) -> Array[MatchBuilder]
+
+      def translate: (String password, Hash[String, String] sub) -> String
+
+      def relevent_l33t_subtable: (String password) -> Hash[String, Array[String]]
+
+      def l33t_subs: (Hash[String, Array[String]] table) -> Array[Hash[String, String]]
+
+      private
+
+      def process_match: (MatchBuilder match, String password, Hash[String, String] substitution, Array[MatchBuilder] matches) -> void
+
+      def find_substitutions: (Array[untyped] subs, Hash[String, Array[String]] table, Array[String] keys) -> Array[untyped]
+
+      def dedup: (Array[untyped] subs) -> Array[untyped]
+    end
+  end
+end

data/sig/zxcvbn/matchers/regex_helpers.rbs

@@ -0,0 +1,7 @@
+module Zxcvbn
+  module Matchers
+    module RegexHelpers
+      def re_match_all: (Regexp regex, String password) { (MatchBuilder, MatchData) -> void } -> void
+    end
+  end
+end

data/sig/zxcvbn/matchers/repeat.rbs

@@ -0,0 +1,11 @@
+module Zxcvbn
+  module Matchers
+    class Repeat
+      GREEDY: Regexp
+      LAZY: Regexp
+      LAZY_ANCHORED: Regexp
+
+      def matches: (String password) -> Array[MatchBuilder]
+    end
+  end
+end

data/sig/zxcvbn/matchers/sequences.rbs

@@ -0,0 +1,16 @@
+module Zxcvbn
+  module Matchers
+    class Sequences
+      MAX_DELTA: Integer
+      ALL_LOWER: Regexp
+      ALL_UPPER: Regexp
+      ALL_DIGITS: Regexp
+
+      def matches: (String password) -> Array[MatchBuilder]
+
+      private
+
+      def classify: (String token) -> [String, Integer]
+    end
+  end
+end

data/sig/zxcvbn/matchers/spatial.rbs

@@ -0,0 +1,15 @@
+module Zxcvbn
+  module Matchers
+    class Spatial
+      SHIFTED_RX: Regexp
+
+      @graphs: Hash[String, Data::adjacency_graph]
+
+      def initialize: (Hash[String, Data::adjacency_graph] graphs) -> void
+
+      def matches: (String password) -> Array[MatchBuilder]
+
+      def matches_for_graph: (Data::adjacency_graph graph, String graph_name, String password) -> Array[MatchBuilder]
+    end
+  end
+end

data/sig/zxcvbn/matchers/year.rbs

@@ -0,0 +1,11 @@
+module Zxcvbn
+  module Matchers
+    class Year
+      include RegexHelpers
+
+      YEAR_REGEX: Regexp
+
+      def matches: (String password) -> Array[MatchBuilder]
+    end
+  end
+end

data/sig/zxcvbn/math.rbs

@@ -1,9 +1,5 @@
 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

data/sig/zxcvbn/omnimatch.rbs

@@ -1,15 +1,18 @@
 module Zxcvbn
   class Omnimatch
     @data: Data
+    @dictionary_matchers: Array[Matchers::Dictionary]
     @matchers: Array[untyped]
 
     def initialize: (Data data) -> void
 
-    def matches: (String password, ?Array[String] user_inputs) -> Array[Match]
+    def matches: (String password, ?Array[String] user_inputs, ?reference_year: Integer) -> Array[MatchBuilder]
 
     private
 
-    def user_input_matchers: (Array[String] user_inputs) -> Array[untyped]
+    def user_input_matchers: (Array[untyped] user_inputs) -> Array[untyped]
+
+    def reverse_dictionary_matches: (String password, ?Array[untyped] user_inputs) -> Array[MatchBuilder]
 
     def build_matchers: () -> Array[untyped]
   end

data/sig/zxcvbn/score.rbs

@@ -1,15 +1,26 @@
 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?
+  class Score < ::Data
+    def self.new: (
+      password: String,
+      guesses: Numeric,
+      sequence: Array[Match],
+      crack_times_seconds: Hash[String, Float],
+      crack_times_display: Hash[String, String],
+      score: Integer,
+      ?calc_time: Float?,
+      ?feedback: Feedback?
+    ) -> instance
 
-    def initialize: (?entropy: Numeric?, ?crack_time: Numeric?, ?crack_time_display: String?, ?score: Integer?, ?match_sequence: Array[Match]?, ?password: String?) -> void
+    attr_reader password: String?
+    attr_reader guesses: Numeric?
+    attr_reader sequence: Array[Match]?
+    attr_reader crack_times_seconds: Hash[String, Float]?
+    attr_reader crack_times_display: Hash[String, String]?
+    attr_reader score: Integer?
+    attr_reader calc_time: Float?
+    attr_reader feedback: Feedback?
+
+    def guesses_log10: () -> Float?
+    def with: (**untyped) -> instance
   end
 end

data/sig/zxcvbn/scorer.rbs

@@ -1,20 +1,19 @@
 module Zxcvbn
   class Scorer
-    include Entropy
+    include Guesses
     include CrackTime
 
     @data: Data
+    @omnimatch: Omnimatch
+    @reference_year: Integer
+    @repeat_cache: Hash[String, Numeric]
 
     attr_reader data: Data
 
-    def initialize: (Data data) -> void
+    def initialize: (Data data, Omnimatch omnimatch, Integer reference_year) -> void
 
-    def minimum_entropy_match_sequence: (String password, Array[Match] matches) -> Score
+    def most_guessable_match_sequence: (String password, Array[MatchBuilder] matches, ?exclude_additive: bool) -> 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
+    def repeat_guesses: (MatchBuilder match) -> Numeric
   end
 end

data/sig/zxcvbn/tester.rbs

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

data/sig/zxcvbn/tester_builder.rbs

@@ -0,0 +1,16 @@
+module Zxcvbn
+  class TesterBuilder
+    DEFAULT_MAX_PASSWORD_LENGTH: Integer
+
+    @word_lists: Hash[String, Array[untyped]]
+    @max_password_length: Integer?
+
+    def initialize: () -> void
+
+    def add_word_list: (String name, ?(Array[untyped] | String)? words) -> TesterBuilder
+
+    def max_password_length: (Integer length) -> TesterBuilder
+
+    def build: () -> Tester
+  end
+end

data/sig/zxcvbn/trie.rbs

@@ -4,10 +4,14 @@ module Zxcvbn
 
     @root: node
 
+    def self.from_ranked: (Data::ranked_dictionary ranked_dictionary) -> Trie
+
     def initialize: () -> void
 
     def insert: (String word, Integer rank) -> void
 
+    def freeze: () -> self
+
     def search_prefixes: (String text, Integer start_pos) -> Array[[String, Integer?, Integer, Integer]]
   end
 end

data/sig/zxcvbn.rbs

@@ -1,10 +1,12 @@
 module Zxcvbn
-  VERSION: String
+  class PasswordTooLong < ArgumentError
+  end
 
-  DATA_PATH: Pathname
+  VERSION: String
 
-  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
+  def self.test: (String? password, ?user_inputs user_inputs) -> Score
+
+  def self.tester_builder: () -> TesterBuilder
 end