better-auth-plugin-zxcvbn

A Better Auth plugin that validates password strength using zxcvbn-ts.

Installation

npm install better-auth-plugin-zxcvbn
# or
pnpm add better-auth-plugin-zxcvbn
# or
yarn add better-auth-plugin-zxcvbn
# or
bun add better-auth-plugin-zxcvbn

Usage

Basic Setup

import { betterAuth } from "better-auth"
import { zxcvbnPlugin } from "better-auth-plugin-zxcvbn"

export const auth = betterAuth({
  // ... your other config
  plugins: [
    zxcvbnPlugin()
  ]
})

Custom Options

You can customize the zxcvbn configuration:

import { zxcvbnPlugin } from "better-auth-plugin-zxcvbn"
import * as zxcvbnEnPackage from "@zxcvbn-ts/language-en"

export const auth = betterAuth({
  plugins: [
    zxcvbnPlugin({
      zxcvbnOptionsOverride: {
        dictionary: {
          ...zxcvbnEnPackage.dictionary,
        },
        graphs: zxcvbnEnPackage.adjacencyGraphs,
        translations: zxcvbnEnPackage.translations
      }
    })
  ]
})

How It Works

The plugin automatically validates passwords during:

• User sign up
• Password changes
• Password resets

Password Requirements:

• Minimum zxcvbn score of 3 (out of 4)
• Rejects common passwords (password, 123456, etc.)
• Rejects patterns and sequences
• Provides helpful feedback messages when validation fails

Examples

Client-side handling:

const { data, error } = await authClient.signUp.email({
  email: "[email protected]",
  password: "weak123",
  name: "User"
})

if (error) {
  console.error(error.message) 
  // "The provided password is too weak. Add another word or two..."
}

For more information on password strength scoring and patterns, see the zxcvbn-ts documentation.

Configuration

zxcvbnOptionsOverride

Optional configuration to override zxcvbn settings. See the zxcvbn-ts documentation for all available options.

interface ZxcvbnPluginOptions {
  zxcvbnOptionsOverride?: {
    dictionary?: {
      // Custom dictionaries
    }
    graphs?: {
      // Custom keyboard layouts
    }
    translations?: {
      // Custom translations
    }
    // ... other zxcvbn options
  }
}

License

MIT