zxcvbn-ruby 1.3.0 → 2.0.0

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/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/clock.rbs

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

data/sig/zxcvbn/crack_time.rbs

@@ -0,0 +1,11 @@
+module Zxcvbn
+  module CrackTime
+    ATTACK_SCENARIOS: Hash[String, Float]
+
+    def estimate_attack_times: (Numeric guesses) -> { crack_times_seconds: Hash[String, Float], crack_times_display: Hash[String, String] }
+
+    def guesses_to_score: (Numeric guesses) -> Integer
+
+    def display_time: (Numeric seconds) -> String
+  end
+end

data/sig/zxcvbn/data.rbs

@@ -0,0 +1,40 @@
+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 }]
+
+    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]
+    @graph_stats: graph_stats
+
+    attr_reader dictionaries: Dictionaries
+    attr_reader adjacency_graphs: Hash[String, adjacency_graph]
+    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[untyped] list) -> void
+
+    private
+
+    def read_word_list: (String file) -> Array[String]
+
+    def build_tries: (Hash[String, ranked_dictionary] ranked) -> Hash[String, 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/feedback.rbs

@@ -0,0 +1,10 @@
+module Zxcvbn
+  class Feedback < Data
+    attr_reader warning: String
+    attr_reader suggestions: Array[String]
+
+    def initialize: (?warning: String, ?suggestions: Array[String]) -> void
+
+    def with: (?warning: String, ?suggestions: Array[String]) -> Feedback
+  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/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

@@ -0,0 +1,40 @@
+module Zxcvbn
+  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: (?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 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,21 @@
+module Zxcvbn
+  module Matchers
+    class Dictionary
+      @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,27 @@
+module Zxcvbn
+  module Matchers
+    class L33t
+      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

@@ -0,0 +1,9 @@
+module Zxcvbn
+  module Math
+    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,19 @@
+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, ?reference_year: Integer) -> Array[MatchBuilder]
+
+    private
+
+    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
+end

data/sig/zxcvbn/score.rbs

@@ -0,0 +1,26 @@
+module Zxcvbn
+  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
+
+    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

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

data/sig/zxcvbn/tester.rbs

@@ -0,0 +1,15 @@
+module Zxcvbn
+  class Tester
+    @data: Data
+    @omnimatch: Omnimatch
+    @max_password_length: Integer
+
+    def initialize: (data: Data, max_password_length: untyped) -> void
+
+    attr_reader max_password_length: Integer
+
+    def test: (String? password, ?(Array[untyped] | String)? user_inputs) -> Score
+
+    def inspect: () -> 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

@@ -0,0 +1,17 @@
+module Zxcvbn
+  class Trie
+    type node = Hash[untyped, untyped]
+
+    @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

@@ -0,0 +1,12 @@
+module Zxcvbn
+  class PasswordTooLong < ArgumentError
+  end
+
+  VERSION: String
+
+  type user_inputs = Array[String]
+
+  def self.test: (String? password, ?user_inputs user_inputs) -> Score
+
+  def self.tester_builder: () -> TesterBuilder
+end