northrook / password-validator
A zxcvbn-based password validator.
Requires
- php: >=8.1
- bjeavons/zxcvbn-php: ^1.3
- northrook/core: dev-main
Requires (Dev)
- northrook/dev-env: dev-main
This package is auto-updated.
Last update: 2024-12-22 14:45:53 UTC
README
A wrapper for the zxcvbn-php library.
This package offers a simple class for validating passwords against a zxcvbn-based strength score.
Important
This package is still in development.
While it is considered MVP and stable, it may still undergo breaking changes.
Slated features:
- Validate passwords using zxcvbn-php.
- Simple
timeToCrack
method - Optional hard limit on passed string, see issue#74.
- Integration with the UI Component Library
- Optional validation for the
<field:password ... >
component. - JavaScript version for real-time validation.
- Optional validation for the `<field:password ...
Installation
composer require northrook/password-validator
Usage
Initialize the PasswordValidator
class, with an optional global $context
array.
Use the validate()
method to validate a given password, returning a Result
object.
Caution
The zxcvbn library is used under the hood, and while it does provide decent insight, it is definite not perfect.
In the example below, we get a score of 3
, despite several matches in the $context
.
use Northrook\PasswordValidator; // Optional context for all validations. $globalContext = [ 'sitename' => 'Example Site', ]; $validator = new PasswordValidator( $globalContext ); $password = 'example-01-user'; $context = [ 'username' => 'Example User', 'email' => 'user@example.com', 'birthdate' => '1980-01-01', ]; $result = $validator->validate( $password, $context ) : Result
The Result
object validates the password using the zxcvbn-php
library, and sets the following read-only properties:
$pass:bool // `true` if the password is strong enough, else `false`. $strength:int // The strength score of the password. $label:string // A human-readable label for the strength score. $guesses:int // The number of guesses required to crack the password. $warning:?string // A warning message if the password is not strong enough, else `null`. $suggestions:[] // A list of suggestions to improve the password.
The Result
object also has twh methods:
// Validate the password against a given strength score. $result->validate( int $strength ):bool // Get the time to crack the password, in seconds by default. $time = $result->timeToCrack( ?string $scenario = 'online_throttling', // The zxcvbn-php scenario to use. string $return = 'RETURN_SECONDS', // RETURN_SECONDS, RETURN_LABEL, RETURN_BOTH as object{seconds:int, label:string}. ):int|string|obj $time->seconds; // 173052000000 $time->label; // "centuries"