zxcvbn-ruby 1.4.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 43a759e1040848c8da4bea8d1e871eb7d811d5cab0ebf962255990963b796f75
-  data.tar.gz: c78d0453bb8c92d1f3b21c37f1493f305a6667f24e6ae85a621841a9396fb584
+  metadata.gz: da4a05d3abd0061434bb0bcedfa1992a9e975c479a0fa9679f9b7c139ea1fa1a
+  data.tar.gz: c7a0a8aa222f29b4550e636701e23069599497290c0fb23edddfc7dbfc37fec5
 SHA512:
-  metadata.gz: 552d40a11c071613eefb14819b4dabbd3abc6a1f2d336e6bf9bfbc873a34640a229b3bedcc0bd77aca6ffe5e43e31fefec74fe94d74f3cdaebd4e7169610ec02
-  data.tar.gz: 84c006df22e0224da4a891f8fa923c81b69229f2b99e5d60ba29104473e566c83a36fbcc404defe980d80cfb176964864f00dbdfa02d655e05eaac7753e64360
+  metadata.gz: 5fcabd8ce5ebe85f5127225c27f1fea83bf26c80885e7f4470d037f8d2c35bda07c8886f185627ee1fdf99feabb7d29ccafba80322257b1724b2c6fc7fc1352a
+  data.tar.gz: 559d0b16b68a68890e898992ef11c2e45c499ab0772d928313a3ab01767c8c251002e136b80eb7ac90d8155ea7e2432d9fb6bae1c47f0d3876b8f623a1bde9bc

data/CHANGELOG.md

@@ -6,7 +6,65 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-[Unreleased]: https://github.com/envato/zxcvbn-ruby/compare/v1.4.0...HEAD
+[Unreleased]: https://github.com/envato/zxcvbn-ruby/compare/v2.0.0...HEAD
+
+## [2.0.0] - 2026-05-28
+
+### Fixed
+ - User-input dictionary matchers now use the Trie path, preventing O(n²) slowdowns on long passwords ([#89])
+
+### Added
+ - `Zxcvbn::TesterBuilder`: fluent builder for constructing a `Tester` with custom word lists and options. Obtain a builder via `Zxcvbn.tester_builder`, then chain `add_word_list`, `max_password_length`, and `build`.
+ - `Zxcvbn::Guesses` module with per-pattern guess estimation formulas matching zxcvbn.js v4: bruteforce, dictionary (with uppercase and l33t variation multipliers), spatial, repeat, sequence, digits, year, and date ([#69])
+ - `us_tv_and_film` frequency list (19,160 entries) introduced in zxcvbn.js v4 ([#69])
+ - Reverse dictionary matching in `Omnimatch` so reversed words (e.g. "drowssap") are detected and scored ([#69])
+ - `guesses` and `guesses_log10` fields on `Zxcvbn::Score` ([#69])
+ - `guesses`, `guesses_log10`, `base_token`, `repeat_count`, and `base_guesses` fields on `Zxcvbn::Match` ([#69])
+ - YARD documentation for all public classes, modules, and methods ([#72])
+
+### Changed
+ - **Breaking**: `Zxcvbn::Tester.new` now requires `data:` and `max_password_length:` keyword arguments with no defaults. Use `Zxcvbn.tester_builder.build` to construct a `Tester`.
+ - **Breaking**: English frequency list dictionary name renamed from `english` to `english_wikipedia`, matching the zxcvbn.js source. Affects `match.dictionary_name` in results ([#90])
+ - `Zxcvbn.test` now reuses a shared `Tester` instance across calls, avoiding repeated dictionary parsing ([#80])
+ - Repeat base tokens are now scored without `user_inputs`, matching zxcvbn.js v4. Previously, user-supplied words were propagated into the recursive scoring of a repeat's base token, causing repeat matches of user-supplied words to score lower than JS would report ([#83])
+ - `Zxcvbn::Score` is now an immutable value object backed by Ruby's `Data`. Attribute setters (`calc_time=`, `feedback=`, etc.) have been removed. Instances now support structural equality (`==`/`eql?`/`hash`) and the `with` method for creating modified copies ([#74])
+ - **Breaking**: `Zxcvbn::Match` is now an immutable value object backed by Ruby's `Data`. Attribute setters have been removed. Instances now support structural equality (`==`/`eql?`/`hash`) and the `with` method for creating modified copies ([#92])
+ - **Breaking**: `Match#to_hash` has been removed. Use `match.to_h` instead — note the shape differs: keys are symbols (not strings), all 28 attributes are included (not just those that were set), and order follows the member definition rather than being sorted alphabetically. To replicate the old behaviour: `match.to_h.transform_keys(&:to_s).compact.sort.to_h`. Additionally, `to_hash` was Ruby's implicit-conversion hook, so any code that splatted a match (`**match`) or passed it to `Hash()` will now raise `TypeError` — use `match.to_h` explicitly instead ([#92])
+ - **Breaking**: `Zxcvbn::Feedback` is now an immutable value object backed by Ruby's `Data`. Attribute setters (`warning=`, `suggestions=`) have been removed. Instances now support structural equality (`==`/`eql?`/`hash`) and the `with` method for creating modified copies ([#77])
+ - **Breaking**: Scoring algorithm aligned with zxcvbn.js v4.4.2. The dynamic programming step now minimises total guesses (`factorial(l) × cumulative_product + MIN_GUESSES^(l-1)` penalty) instead of entropy bits. Scores for many passwords will change ([#69])
+ - **Breaking**: Bruteforce cardinality is now fixed at 10 (digits only), matching zxcvbn.js v4. Previously it was computed dynamically from the character classes present in the password (10–95), so bruteforce guesses for passwords containing letters or symbols will change ([#69])
+ - **Breaking**: `Repeat` matcher now detects multi-character repeating units (e.g. `abcabc`). The `base_token` field holds the repeating unit (which may be more than one character); `repeated_char` has been removed ([#69])
+ - **Breaking**: `Match#entropy`, `Match#base_entropy`, `Match#uppercase_entropy`, and `Match#l33t_entropy` have been removed. Use `Match#guesses` and `Match#guesses_log10` instead ([#69])
+ - `crack_time_to_score` replaced by `guesses_to_score` with v4 thresholds: 0 (<1,005 guesses), 1 (<1,000,005), 2 (<100,000,005), 3 (<10,000,000,005), 4 (≥10,000,000,005) ([#69])
+ - `Sequence` matcher ported to the zxcvbn.js v4 delta-based algorithm. Sequences are now detected using codepoint deltas up to ±5 (was ±1 only), enabling matches like `"ace"` (delta 2) or Unicode runs like `"αβγ"`. Sequence type is classified by character class (`lower`/`upper`/`digits`/`unicode`) rather than a lookup table ([#69])
+ - `Date` matcher year range extended to 1000–2050; 2-digit years are now expanded (>50 → 1900s, ≤50 → 2000s) ([#69])
+ - All frequency lists replaced with zxcvbn.js v4.4.2 versions: `passwords` (30k entries), `surnames` (10k), `female_names` (3,712), `male_names` (983), `english_wikipedia` (30k entries) ([#69])
+ - **Breaking**: `entropy` on `Zxcvbn::Score` has been removed. Use `Score#guesses` or `Math.log2(score.guesses)` instead ([#69])
+ - **Breaking**: `Score#crack_time` and `Score#crack_time_display` replaced by `Score#crack_times_seconds` and `Score#crack_times_display`, each a hash keyed by attack scenario (`online_throttling_100_per_hour`, `online_no_throttling_10_per_second`, `offline_slow_hashing_1e4_per_second`, `offline_fast_hashing_1e10_per_second`), matching the zxcvbn.js v4 output format ([#69])
+ - **Breaking**: `Score#match_sequence` renamed to `Score#sequence` to match the zxcvbn.js v4 field name ([#69])
+ - **Breaking**: `Feedback#warning` now returns `''` instead of `nil` when no warning applies, matching zxcvbn.js v4 ([#69])
+ - **Breaking**: The "This is similar to a commonly used password" warning is now only emitted when `match.guesses_log10 <= 4`, matching the zxcvbn.js v4 threshold. Previously it was emitted unconditionally for any l33t, reversed, or non-sole-match on the passwords dictionary ([#69])
+ - Repeat feedback now distinguishes single-char repeats (`"aaa"`) from multi-char repeats (`"abcabcabc"`), matching zxcvbn.js v4 ([#69])
+ - `year` pattern matches now produce a "Recent years are easy to guess" warning ([#69])
+ - Sole matches from the `english_wikipedia` dictionary now produce an "A word by itself is easy to guess" warning ([#69])
+ - **Breaking**: `Tester#test` and `Zxcvbn.test` now raise `Zxcvbn::PasswordTooLong` (a subclass of `ArgumentError`) for passwords longer than 256 characters (the default). Previously, long passwords were accepted and could cause super-quadratic runtime on adversarial repeat inputs to the `password` argument. The `user_inputs` parameter remains unbounded. Override the limit with the `ZXCVBN_MAX_PASSWORD_LENGTH` environment variable or `Zxcvbn.tester_builder.max_password_length(n).build`.
+
+### Removed
+ - **Breaking**: `Tester#add_word_lists`. Use `Zxcvbn.tester_builder.add_word_list(name, words).build` instead.
+ - **Breaking**: `word_lists:` argument to `Zxcvbn.test`. Use `Zxcvbn.tester_builder.add_word_list(name, words).build` to construct a tester with custom word lists.
+ - Support for Ruby versions below 3.3 ([#70])
+
+[2.0.0]: https://github.com/envato/zxcvbn-ruby/compare/v1.4.0...v2.0.0
+[#69]: https://github.com/envato/zxcvbn-ruby/pull/69
+[#70]: https://github.com/envato/zxcvbn-ruby/pull/70
+[#72]: https://github.com/envato/zxcvbn-ruby/pull/72
+[#74]: https://github.com/envato/zxcvbn-ruby/pull/74
+[#77]: https://github.com/envato/zxcvbn-ruby/pull/77
+[#80]: https://github.com/envato/zxcvbn-ruby/pull/80
+[#83]: https://github.com/envato/zxcvbn-ruby/pull/83
+[#89]: https://github.com/envato/zxcvbn-ruby/pull/89
+[#90]: https://github.com/envato/zxcvbn-ruby/pull/90
+[#92]: https://github.com/envato/zxcvbn-ruby/pull/92
 
 ## [1.4.0] - 2026-01-15
 

data/README.md

@@ -1,6 +1,6 @@
 # zxcvbn-ruby
 
-This is a Ruby port of Dropbox's [zxcvbn.js][zxcvbn.js] JavaScript library.
+This is a Ruby port of Dropbox's [zxcvbn.js][zxcvbn.js] JavaScript password strength estimator, providing **zxcvbn.js v4** compatibility.
 
 ## Development status [![CI Status](https://github.com/envato/zxcvbn-ruby/workflows/CI/badge.svg)](https://github.com/envato/zxcvbn-ruby/actions?query=workflow%3ACI)
 
@@ -32,94 +32,340 @@ $ irb
 >> require 'zxcvbn'
 => true
 >> pp Zxcvbn.test('@lfred2004', ['alfred'])
-#<Zxcvbn::Score:0x00007f7f590610c8
- @calc_time=0.0055760000250302255,
- @crack_time=0.012,
- @crack_time_display="instant",
- @entropy=7.895,
- @feedback=
-  #<Zxcvbn::Feedback:0x00007f7f59060150
-   @suggestions=
+#<data Zxcvbn::Score
+ password="@lfred2004",
+ guesses=15000.0,
+ sequence=
+  [#<data Zxcvbn::Match
+    pattern="dictionary",
+    i=0,
+    j=5,
+    token="@lfred",
+    matched_word="alfred",
+    rank=1,
+    dictionary_name="user_inputs",
+    l33t=true,
+    sub={"@" => "a"},
+    sub_display="@ -> a",
+    guesses=50,
+    guesses_log10=1.6989700043360187,
+    base_guesses=1,
+    uppercase_variations=1,
+    l33t_variations=2>,
+   #<data Zxcvbn::Match
+    pattern="year",
+    i=6,
+    j=9,
+    token="2004",
+    guesses=50,
+    guesses_log10=1.6989700043360187>],
+ crack_times_seconds=
+  {"online_throttling_100_per_hour" => 540000.0,
+   "online_no_throttling_10_per_second" => 1500.0,
+   "offline_slow_hashing_1e4_per_second" => 1.5,
+   "offline_fast_hashing_1e10_per_second" => 1.5e-06},
+ crack_times_display=
+  {"online_throttling_100_per_hour" => "6 days",
+   "online_no_throttling_10_per_second" => "25 minutes",
+   "offline_slow_hashing_1e4_per_second" => "2 seconds",
+   "offline_fast_hashing_1e10_per_second" => "less than a second"},
+ score=1,
+ calc_time=0.0007990000303834677,
+ feedback=
+  #<data Zxcvbn::Feedback
+   warning="",
+   suggestions=
     ["Add another word or two. Uncommon words are better.",
-     "Predictable substitutions like '@' instead of 'a' don't help very much"],
-   @warning=nil>,
- @match_sequence=
-  [#<Zxcvbn::Match matched_word="alfred", token="@lfred", i=0, j=5, rank=1, pattern="dictionary", dictionary_name="user_inputs", l33t=true, sub={"@"=>"a"}, sub_display="@ -> a", base_entropy=0.0, uppercase_entropy=0.0, l33t_entropy=1, entropy=1.0>,
-   #<Zxcvbn::Match i=6, j=9, token="2004", pattern="year", entropy=6.894817763307944>],
- @password="@lfred2004",
- @score=0>
-=> #<Zxcvbn::Score:0x00007f7f59060150>
+     "Predictable substitutions like '@' instead of 'a' don't help very much"]>>
 >> pp Zxcvbn.test('asdfghju7654rewq', ['alfred'])
-#<Zxcvbn::Score:0x00007f7f5a9e9248
- @calc_time=0.007504999986849725,
- @crack_time=46159.451,
- @crack_time_display="14 hours",
- @entropy=29.782,
- @feedback=
-  #<Zxcvbn::Feedback:0x00007f7f5a9e9130
-   @suggestions=
-    ["Add another word or two. Uncommon words are better.",
-     "Use a longer keyboard pattern with more turns"],
-   @warning="Short keyboard patterns are easy to guess">,
- @match_sequence=
-  [#<Zxcvbn::Match pattern="spatial", i=0, j=15, token="asdfghju7654rewq", graph="qwerty", turns=5, shifted_count=0, entropy=29.7820508329166>],
- @password="asdfghju7654rewq",
- @score=2>
-=> #<Zxcvbn::Score:0x00007f7f5a9e9248>
+#<data Zxcvbn::Score
+ password="asdfghju7654rewq",
+ guesses=923189026.4430684,
+ sequence=
+  [#<data Zxcvbn::Match
+    pattern="spatial",
+    i=0,
+    j=15,
+    token="asdfghju7654rewq",
+    guesses=923189025.4430684,
+    guesses_log10=8.965290633097352,
+    graph="qwerty",
+    turns=5,
+    shifted_count=0>],
+ crack_times_seconds=
+  {"online_throttling_100_per_hour" => 33234804951.950462,
+   "online_no_throttling_10_per_second" => 92318902.64430684,
+   "offline_slow_hashing_1e4_per_second" => 92318.90264430684,
+   "offline_fast_hashing_1e10_per_second" => 0.09231890264430684},
+ crack_times_display=
+  {"online_throttling_100_per_hour" => "centuries",
+   "online_no_throttling_10_per_second" => "3 years",
+   "offline_slow_hashing_1e4_per_second" => "1 day",
+   "offline_fast_hashing_1e10_per_second" => "less than a second"},
+ score=3,
+ calc_time=0.001090999983716756,
+ feedback=#<data Zxcvbn::Feedback warning="" suggestions=[]>>
 ```
 
-## Testing Multiple Passwords
+## Custom Testers
 
-The dictionaries used for password strength testing are loaded each request to `Zxcvbn.test`. If you you'd prefer to persist the dictionaries in memory (approx 20MB RSS) to perform lots of password tests in succession then you can use the `Zxcvbn::Tester` API:
+`Zxcvbn.test` reuses a shared `Tester` internally — dictionaries are loaded once and persist in memory. Use `Zxcvbn.tester_builder.build` to construct a standalone `Tester` you control:
 
 ```ruby
 $ irb
 >> require 'zxcvbn'
 => true
->> tester = Zxcvbn::Tester.new
+>> tester = Zxcvbn.tester_builder.build
 => #<Zxcvbn::Tester:0x3fe99d869aa4>
 >> pp tester.test('@lfred2004', ['alfred'])
-#<Zxcvbn::Score:0x00007f7f586fcf50
- @calc_time=0.00631899997824803,
- @crack_time=0.012,
- @crack_time_display="instant",
- @entropy=7.895,
- @feedback=
-  #<Zxcvbn::Feedback:0x00007f7f586fcac8
-   @suggestions=
-    ["Add another word or two. Uncommon words are better.",
-     "Predictable substitutions like '@' instead of 'a' don't help very much"],
-   @warning=nil>,
- @match_sequence=
-  [#<Zxcvbn::Match matched_word="alfred", token="@lfred", i=0, j=5, rank=1, pattern="dictionary", dictionary_name="user_inputs", l33t=true, sub={"@"=>"a"}, sub_display="@ -> a", base_entropy=0.0, uppercase_entropy=0.0, l33t_entropy=1, entropy=1.0>,
-   #<Zxcvbn::Match i=6, j=9, token="2004", pattern="year", entropy=6.894817763307944>],
- @password="@lfred2004",
- @score=0>
-=> #<Zxcvbn::Score:0x00007f7f586fcf50>
->> pp tester.test('@lfred2004', ['alfred'])
-#<Zxcvbn::Score:0x00007f7f56d57438
- @calc_time=0.001986999996006489,
- @crack_time=0.012,
- @crack_time_display="instant",
- @entropy=7.895,
- @feedback=
-  #<Zxcvbn::Feedback:0x00007f7f56d56bf0
-   @suggestions=
+#<data Zxcvbn::Score
+ password="@lfred2004",
+ guesses=15000.0,
+ sequence=
+  [#<data Zxcvbn::Match
+    pattern="dictionary",
+    i=0,
+    j=5,
+    token="@lfred",
+    matched_word="alfred",
+    rank=1,
+    dictionary_name="user_inputs",
+    l33t=true,
+    sub={"@" => "a"},
+    sub_display="@ -> a",
+    guesses=50,
+    guesses_log10=1.6989700043360187,
+    base_guesses=1,
+    uppercase_variations=1,
+    l33t_variations=2>,
+   #<data Zxcvbn::Match
+    pattern="year",
+    i=6,
+    j=9,
+    token="2004",
+    guesses=50,
+    guesses_log10=1.6989700043360187>],
+ crack_times_seconds=
+  {"online_throttling_100_per_hour" => 540000.0,
+   "online_no_throttling_10_per_second" => 1500.0,
+   "offline_slow_hashing_1e4_per_second" => 1.5,
+   "offline_fast_hashing_1e10_per_second" => 1.5e-06},
+ crack_times_display=
+  {"online_throttling_100_per_hour" => "6 days",
+   "online_no_throttling_10_per_second" => "25 minutes",
+   "offline_slow_hashing_1e4_per_second" => "2 seconds",
+   "offline_fast_hashing_1e10_per_second" => "less than a second"},
+ score=1,
+ calc_time=0.0008110000053420663,
+ feedback=
+  #<data Zxcvbn::Feedback
+   warning="",
+   suggestions=
     ["Add another word or two. Uncommon words are better.",
-     "Predictable substitutions like '@' instead of 'a' don't help very much"],
-   @warning=nil>,
- @match_sequence=
-  [#<Zxcvbn::Match matched_word="alfred", token="@lfred", i=0, j=5, rank=1, pattern="dictionary", dictionary_name="user_inputs", l33t=true, sub={"@"=>"a"}, sub_display="@ -> a", base_entropy=0.0, uppercase_entropy=0.0, l33t_entropy=1, entropy=1.0>,
-   #<Zxcvbn::Match i=6, j=9, token="2004", pattern="year", entropy=6.894817763307944>],
- @password="@lfred2004",
- @score=0>
-=> #<Zxcvbn::Score:0x00007f7f56d57438>
+     "Predictable substitutions like '@' instead of 'a' don't help very much"]>>
+```
+
+To add custom word lists, chain `add_word_list` before `build`:
+
+```ruby
+>> tester = Zxcvbn.tester_builder.add_word_list('company', %w[acme corp]).build
+=> #<Zxcvbn::Tester:0x3fe99d869bb8>
+>> tester.test('acme').score
+=> 0
+```
+
+Subsequent calls reuse the already-loaded dictionaries, so `calc_time` is significantly lower:
+
+```ruby
+>> tester.test('@lfred2004', ['alfred']).calc_time
+=> 0.0005759999621659517
+```
+
+> [!WARNING]
+> Scoring time grows with password length. For adversarial inputs such as
+> short repeated sequences (e.g. `"ab" * 500`), the internal pattern-matching
+> DP produces super-quadratic runtime. Both `Zxcvbn.test` and
+> `Zxcvbn::Tester#test` raise `Zxcvbn::PasswordTooLong` for passwords longer
+> than 256 characters (the default). Override the
+> limit with the `ZXCVBN_MAX_PASSWORD_LENGTH` environment variable, but be
+> aware that raising it re-exposes this runtime risk. The `user_inputs`
+> parameter is not length-bounded; apply your own limit to those values.
+
+> [!WARNING]
+> Storing the guesses or score for an encrypted or hashed value provides
+> information that can make cracking the value orders of magnitude easier for an
+> attacker. For this reason we advise you not to store the results of
+> `Zxcvbn::Tester#test`. Further reading: [A Tale of Security Gone Wrong](https://web.archive.org/web/20240715041147/http://gavinmiller.io/2016/a-tale-of-security-gone-wrong/).
+
+## Limitations
+
+The frequency lists bundled with this gem are English-only: English Wikipedia, US TV & film, English-derived names, and English-language password leaks. Passwords built from non-English words (e.g. `"รหัสผ่าน"`, Thai for "password") are scored against bruteforce rather than a localised dictionary, so their score will often be higher than the real-world risk warrants. If your users primarily choose passwords in a non-English language, treat the scores as a lower bound on strength, not an absolute measure.
+
+## Migrating from 1.x
+
+Version 2 aligns with the zxcvbn.js v4 algorithm and API. Scores will change for many passwords — this is expected. The sections below cover every breaking API change.
+
+### Ruby version
+
+Ruby 3.3 or later is required.
+
+### `Score` field changes
+
+The following attributes have been removed and will raise `NoMethodError`. Use the 2.x equivalents below:
+
+| Removed (1.x) | 2.x equivalent |
+|-----|-----|
+| `result.entropy` | `Math.log2(result.guesses)` or `result.guesses_log10 * Math.log2(10)` |
+| `result.crack_time` | `result.crack_times_seconds["online_no_throttling_10_per_second"]` (see [Attack scenarios](#attack-scenarios)) |
+| `result.crack_time_display` | `result.crack_times_display["online_no_throttling_10_per_second"]` |
+| `result.match_sequence` | `result.sequence` |
+
+1.x `crack_time` used 10 guesses/second (unthrottled online), corresponding to the `"online_no_throttling_10_per_second"` scenario. The entropy formula gives the same log-scale difficulty value, but the number will differ from 1.x because the underlying guessing algorithm has been rewritten.
+
+`Score` is now an immutable value object. Attribute setters (`calc_time=`, `feedback=`, etc.) have been removed. Use `result.with` to create a modified copy — `with` returns a **new** frozen object:
+
+```ruby
+# 1.x
+result.calc_time = 0.001
+
+# 2.x
+result = result.with(calc_time: 0.001)
+```
+
+#### Attack scenarios
+
+`crack_times_seconds` and `crack_times_display` are both hashes keyed by attack scenario:
+
+```ruby
+result.crack_times_display
+# => {
+#   "online_throttling_100_per_hour"       => "6 days",
+#   "online_no_throttling_10_per_second"   => "25 minutes",
+#   "offline_slow_hashing_1e4_per_second"  => "2 seconds",
+#   "offline_fast_hashing_1e10_per_second" => "less than a second"
+# }
+```
+
+### `Match` field changes
+
+The following attributes have been removed and will raise `NoMethodError`. Use the 2.x equivalents below:
+
+| Removed (1.x) | 2.x equivalent |
+|-----|-----|
+| `match.entropy` | `match.guesses_log10 * Math.log2(10)` |
+| `match.base_entropy` | `Math.log2(match.base_guesses)` (dictionary matches only — `base_guesses` is `nil` for other patterns) |
+| `match.uppercase_entropy` | `Math.log2(match.uppercase_variations)` (dictionary matches only — `uppercase_variations` is `nil` for other patterns) |
+| `match.l33t_entropy` | `Math.log2(match.l33t_variations)` (dictionary matches only — `l33t_variations` is `nil` for other patterns) |
+| `match.repeated_char` | `match.base_token` (now supports multi-character repeating units e.g. `"abcabc"`) |
+| `match.to_hash` | `match.to_h` — note: keys are now symbols (not strings), all 28 attributes are included (not just those that were set), and key order follows member definition rather than alphabetical. To replicate old behaviour: `match.to_h.transform_keys(&:to_s).compact.sort.to_h` |
+
+These translations give a log-scale difficulty value but are not numerically equivalent to 1.x — the underlying guess estimation formulas have been rewritten.
+
+`Match` is now an immutable value object. Attribute setters have been removed. Use `match.with(attr: value)` to derive a modified copy. Any code that splatted a match (`**match`) or passed it to `Hash()` will now raise `TypeError` — use `match.to_h` explicitly instead.
+
+### `Feedback` changes
+
+`Feedback#warning` now returns `''` instead of `nil` when no warning applies. Update `nil` checks accordingly:
+
+```ruby
+# 1.x
+if result.feedback.warning
+  show_warning(result.feedback.warning)
+end
+
+# 2.x
+unless result.feedback.warning.empty?
+  show_warning(result.feedback.warning)
+end
 ```
 
-**Note**: Storing the entropy of an encrypted or hashed value provides
-information that can make cracking the value orders of magnitude easier for an
-attacker. For this reason we advise you not to store the results of
-`Zxcvbn::Tester#test`. Further reading: [A Tale of Security Gone Wrong](https://web.archive.org/web/20240715041147/http://gavinmiller.io/2016/a-tale-of-security-gone-wrong/).
+Also update any `||` defaults on `warning` — `''` is truthy so the fallback no longer fires:
+
+```ruby
+# 1.x — worked because nil is falsy
+label = result.feedback.warning || "No issues"
+
+# 2.x
+label = result.feedback.warning.empty? ? "No issues" : result.feedback.warning
+```
+
+The "This is similar to a commonly used password" warning is now only emitted when `match.guesses_log10 <= 4` (previously it applied to any l33t, reversed, or non-sole-match on the passwords dictionary). Update any code that asserts on feedback content.
+
+`Feedback` is now an immutable value object. Attribute setters (`warning=`, `suggestions=`) have been removed. Use `result.feedback.with(warning: "...")` to derive a modified copy.
+
+### Dictionary name change
+
+The `english` frequency list has been renamed to `english_wikipedia`. If you filter matches by `dictionary_name`:
+
+```ruby
+# 1.x
+match.dictionary_name == "english"
+
+# 2.x
+match.dictionary_name == "english_wikipedia"
+```
+
+A new `us_tv_and_film` frequency list has also been added. Update any `dictionary_name` allowlists or case statements to include it.
+
+### Password length limit
+
+`Tester#test` and `Zxcvbn.test` now raise `Zxcvbn::PasswordTooLong` (a subclass of `ArgumentError`) for passwords longer than 256 characters (the default). Previously, long passwords were accepted without error. The `user_inputs` parameter remains unbounded.
+
+If your application accepts user-controlled input longer than 256 characters, either add a length check before calling the gem, construct a `Tester` with a custom limit, or adjust the process-wide default via the `ZXCVBN_MAX_PASSWORD_LENGTH` environment variable.
+
+To enforce your own limit before calling the gem (note: bcrypt's limit is 72 **bytes**, not characters):
+
+```ruby
+raise ArgumentError, "Password too long" if password.bytesize > 72 # bcrypt's 72-byte limit
+result = Zxcvbn.test(password)
+```
+
+To use a different limit for a specific tester without touching the environment:
+
+```ruby
+tester = Zxcvbn.tester_builder.max_password_length(128).build
+result = tester.test(password)
+```
+
+To adjust the process-wide default, set `ZXCVBN_MAX_PASSWORD_LENGTH` in the process environment before the process starts:
+
+```sh
+ZXCVBN_MAX_PASSWORD_LENGTH=1024 bundle exec rails server
+```
+
+The variable is read when `TesterBuilder#build` is called. For the shared tester backing `Zxcvbn.test`, that is the first call to `Zxcvbn.test`.
+
+Or export it from your shell profile, process manager, or platform environment config (Heroku, Docker, etc.). Note that raising the limit re-exposes the super-quadratic runtime for adversarial inputs to the `password` argument.
+
+### Custom word lists
+
+`Tester#add_word_lists` and the `word_lists:` argument to `Zxcvbn.test` have been removed. Use the `Zxcvbn.tester_builder` builder instead:
+
+```ruby
+# 1.x — no longer works
+result = Zxcvbn.test(password, user_inputs, word_lists: { 'company' => %w[acme corp] })
+tester.add_word_lists('company' => %w[acme corp])
+
+# 2.x
+tester = Zxcvbn.tester_builder.add_word_list('company', %w[acme corp]).build
+result = tester.test(password, user_inputs)
+```
+
+`Zxcvbn::Tester.new` is no longer a public construction path — it now requires `data:` and `max_password_length:` keyword arguments with no defaults. Use `Zxcvbn.tester_builder.build` (or the fluent builder) instead:
+
+```ruby
+# 1.x
+tester = Zxcvbn::Tester.new
+
+# 2.x
+tester = Zxcvbn.tester_builder.build
+```
+
+### Score values will change
+
+The scoring algorithm has been rewritten to match zxcvbn.js v4. It now minimises total guesses rather than entropy bits. Bruteforce cardinality is fixed at 10 regardless of the character classes in the password (previously 10–95 depending on which character classes were present). Scores (0–4) for many passwords will differ from 1.x — this is expected and intentional.
+
+Audit any code that gates on `result.score` (e.g. form validation thresholds), persists scores in a database, or asserts on score values in tests — these will need review after upgrading.
 
 ## Contact
 
@@ -130,7 +376,8 @@ attacker. For this reason we advise you not to store the results of
 
  - [Steve Hodgkiss](https://github.com/stevehodgkiss)
  - [Matthieu Aussaguel](https://github.com/matthieua)
- - [_et al._](https://github.com/envato/zxcvbn-ruby/graphs/contributors)
+ - [Orien Madgwick](https://github.com/orien)
+ - [_et al._](https://github.com/envato/zxcvbn-ruby/graphs/contributors?all=1)
 
 ## License [![license](https://img.shields.io/github/license/mashape/apistatus.svg?style=flat-square)](https://github.com/envato/zxcvbn-ruby/blob/HEAD/LICENSE.txt)