zxcvbn-ts

zxcvbn-ts is a TypeScript rewrite of the original Dropbox zxcvbn password strength estimator. It uses pattern matching and conservative estimation to recognize common passwords, names, Wikipedia words, and various patterns (dates, repeats, sequences, keyboard patterns, and l33t speak) across multiple languages.

Instead of using rigid password composition policies (e.g., "must contain one symbol and one number"), zxcvbn-ts provides an algorithmic alternative that measures actual entropy and complexity. This approach is more secure, flexible for different password styles like passphrases, and provides better user experience through targeted verbal feedback.

zxcvbn-ts is a TypeScript-based password strength estimator. Key features include:

• Password strength estimation: Analyze how strong a password is.
• Password scoring: Receive a score from 0 to 4.
• Internationalization (I18n): Support for multiple languages for feedback translations and dictionaries.
• Customization: Ability to customize dictionaries, the l33t table, and keyboard layouts.
• TypeScript support: Built entirely in TypeScript for full type safety.

zxcvbn-ts is a password strength estimator inspired by password crackers. It uses pattern matching and conservative estimation to analyze password complexity.

Key capabilities include:

• Recognizing over 40,000 common passwords.
• Filtering out common names, Wikipedia words, and cultural commonalities.
• Identifying patterns like dates, repetitions (e.g., 'aaa'), sequences (e.g., 'abcd'), keyboard smashes (e.g., 'qwertyuiop'), and l33t speak.

It is designed as an algorithmic alternative to traditional password composition policies (e.g., requiring special characters or numbers), providing more secure, flexible, and user-friendly feedback.

zxcvbn-ts provides several capabilities for password security analysis:

• Strength Estimation: Estimate the strength of a password and retrieve a numerical score.
• Asynchronous Matching: Check passwords asynchronously when using API-based matchers (like haveibeenpwned).
• i18n Support: Internationalization for both dictionaries and verbal feedback translations.
• Extensibility: Extend existing dictionaries with your own data or implement custom matchers.
• Dictionary-less Mode: Can be used without dictionaries, though scoring efficiency is significantly reduced.
• Type Safety: Full TypeScript support.
• Pwned Matcher: Includes a matcher for the haveibeenpwned service.

The crack time estimation output has been unified. Instead of separate crackTimesSeconds and crackTimesDisplay objects, all information is contained within a crackTimes object where each key contains seconds, display, and an optional base value.

{
  "crackTimes": {
    "onlineThrottlingXPerHour": {
      "base": null,
      "seconds": 3600,
      "display": "1 hour"
    },
    "onlineNoThrottlingXPerSecond": {
      "base": null,
      "seconds": 1,
      "display": "1 second"
    },
    "offlineSlowHashingXPerSecond": {
      "base": null,
      "seconds": 100,
      "display": "1 minute"
    },
    "offlineFastHashingXPerSecond": {
      "base": null,
      "seconds": 0.1,
      "display": "less than a second"
    }
  }
}

Compared to the original JavaScript zxcvbn library, zxcvbn-ts introduces several architectural improvements:

• Modular Language Packages: The core library (@zxcvbn-ts/core) is decoupled from dictionaries. You must include language-specific packages (e.g., @zxcvbn-ts/language-en) to use them. This keeps the core bundle small.
• I18n Support: Feedback, dictionaries, and keyboard patterns support internationalization. Feedback is returned as keys by default.
• Customizable Keyboards: You can overwrite or extend the default keyboard layouts (e.g., adding Cyrillic layouts for a Russian website).
• Extensible Matchers: Supports both synchronous and asynchronous matchers. Asynchronous matchers allow for external API calls (e.g., checking against HaveIBeenPwned).
• Bundle Optimization: Dictionaries are compressed to reduce bundle size by up to 33%.

When migrating from the original Dropbox zxcvbn to zxcvbn-ts, users should expect slight variations in password strength scores. These differences are intentional and result from:

• Updated dictionaries: zxcvbn-ts generally uses more words and more up-to-date dictionaries.
• Bug fixes: Improvements to the scoring logic itself.
• Expanded keyboard layouts: Support for a wider variety of keyboard configurations.
• Additional matchers: More sophisticated pattern matching for identifying weak passwords.

If you encounter scoring that appears significantly incorrect or out of place, you are encouraged to open a discussion in the repository.

When providing custom timeEstimation translations, you can use a string with a {base} placeholder for simple cases, or a function for complex pluralization rules.

const translations = {
  warnings: {
    // ...
  },
  suggestions: {
    // ...
  },
  timeEstimation: {
    ltSecond: 'less than a second',
    second: '{base} second',
    seconds: (value) => {
      if (value === 2) return 'exactly two seconds'
      return `${value} seconds`
    },
    // ...
  },
}

Performing incremental searches (e.g., making an API request for every character typed) may allow a third party with access to inbound network requests (like a Cloudflare proxy) to observe enough information to discern the original password.

Mitigation: To reduce this risk, wait until the entire password is entered before performing the check (for example, by triggering the check on the blur event of the password input field).

Duplicate Entries

If your custom dictionaries contain overlapping entries with the built-in dictionaries, the algorithm automatically prioritizes the first match it finds. This ensures efficient processing without requiring manual deduplication.

Performance

Zxcvbn-ts is optimized for large datasets. Even with dictionaries containing over 100,000 words, the algorithm typically processes results in under 100ms, making it suitable for real-time application use.

zxcvbn-ts typically operates within 5-20ms for ~25 character passwords and ~100ms for ~100 character passwords on modern hardware.

To prevent runtime latency for very long inputs, you should:

1. Limit the input length passed to the check function (e.g., only check the first 100 characters).
2. Be aware that the library has a default maxLength of 256 characters for security reasons, which can be customized.