zxcvbn

zxcvbn is a client- and server-side JavaScript library for estimating password strength by pattern-matching against real-world attacker knowledge rather than blunt composition rules. Instead of scoring passwords by counting character classes, it recognizes tens of thousands of common passwords, common first and last names drawn from US census data, popular English words from Wikipedia and US television and film, and structural patterns like dates, repeats (aaa), sequences (abcd), keyboard walks (qwertyuiop), and l33t-speak substitutions.

For each pattern it finds, zxcvbn estimates the number of guesses an attacker would need and combines overlapping matches into the single most efficient (lowest-guess) explanation of the password using a dynamic-programming search. The result reports an integer score from 0-4, order-of-magnitude guess counts, back-of-the-envelope crack-time estimates under several attack scenarios (throttled online, unthrottled online, slow offline hashing, fast offline hashing), and targeted verbal feedback developers can surface directly in a signup form.

What You Get

• A single zxcvbn(password, user_inputs) function returning a score (0-4), guess estimates, and crack-time estimates for four attack scenarios
• Pattern-matching dictionaries for common passwords, English words, US census names, and pop-culture terms (TV/film)
• Keyboard-adjacency graphs (qwerty, dvorak, keypad, mac keypad) for detecting spatial patterns like walks and turns
• Targeted, human-readable feedback (warning + suggestions) for scores of 2 and below, ready to show directly in a UI
• A prebuilt, minified dist/zxcvbn.js bundle for direct <script> inclusion alongside the npm/CommonJS/AMD module forms

Common Use Cases

• Signup and password-reset forms - replace rigid composition rules (‘one uppercase, one number, one symbol’) with a live strength meter that rejects genuinely weak passwords and allows strong passphrases
• Enterprise password policy enforcement - gate account creation on a minimum zxcvbn score instead of guessable regex-based rules that both admit weak passwords and reject strong ones
• Personal-info-aware strength checks - pass a user’s name, email, or company name as user_inputs so passwords built from personal information score appropriately low
• Security research and password auditing - batch-score existing password dumps or policy proposals to estimate real-world crackability

Under The Hood

Architecture main.coffee orchestrates a linear, functional pipeline: matching.omnimatch(password) generates candidate pattern matches (dictionary, spatial, repeat, sequence, date, regex, l33t) each tagged with start/end indices and pattern type; scoring.most_guessable_match_sequence performs a dynamic-programming search over overlapping matches, partitioned by end index, to find the minimal-guess non-overlapping sequence; time_estimates.estimate_attack_times converts total guesses into crack-time buckets; feedback.get_feedback derives warning/suggestion strings from the winning sequence. The four modules communicate only through plain data, and the one piece of mutable state (the user-input dictionary) is explicitly reset per call, keeping the library stateless from a caller’s perspective — but there is no abstraction boundary between match generation and guess estimation, so changing the core scoring formula in scoring.coffee would ripple through every consumer of scores and crack times.

Tech Stack Written entirely in CoffeeScript, compiled via coffee -o lib to CommonJS for Node/npm and bundled with Browserify plus coffeeify and uglifyify into a standalone UMD dist/zxcvbn.js for direct <script> tags, AMD (RequireJS), and Bower consumption. A small Python data-scripts/ directory regenerates the frequency-list dictionaries (Wikipedia, US census names, US TV/film corpus) offline and plays no part in the runtime path. There are no runtime dependencies; devDependencies cover only the CoffeeScript build chain and the test chain. The deployment target is simply the published npm package, Bower component, or CDN-hosted dist bundle — there is no server or database involved anywhere in the library.

Code Quality Tests live in test/test-matching.coffee and test/test-scoring.coffee using the tape framework via coffeetape, with parametrized table-driven assertions covering core numeric helpers and match/scoring correctness; CI runs on Travis and cross-browser SauceLabs testing via zuul specifically for the browser environment. There is no type system — CoffeeScript is untyped — and no linter or formatter is configured. Error handling is minimal by design: the library operates on plain strings and returns a result object rather than throwing, which is appropriate for a synchronous, I/O-free scoring function. Naming is consistent snake_case throughout, matching CoffeeScript community convention.

API Design The entire public surface is a single function, zxcvbn(password, user_inputs = []), returning one plain object with score, guesses, crack time estimates, sequence, and feedback — essentially zero boilerplate to get a usable password-strength meter running. The user_inputs parameter is a notably good ergonomic touch, letting callers cheaply fold personal-info-aware scoring into the same call rather than requiring a separate pass. The tradeoff is bundle size, dominated by dictionary data, which the README documents candidly alongside several lazy-loading strategies for mitigating page-load latency.