PasswordToolKit

The PasswordToolKit is a simple and easy-to-use class that allows generating and evaluating password strength.

Table of Contents

• Installation
• Importing
• Usage
• Type Definitions
  • PasswordToolKitSettings
  • OptionsValidation
  • GenerateOptions
• API
  • PasswordToolKit(settings)
  • PasswordToolKit#checkOptions(options)
  • PasswordToolKit#generate(options)
  • PasswordToolKit#evaluate(password)
• Contributing
• License

Installation

You can install PasswordToolKit via npm:

1npm install password-toolkit

Importing

To use PasswordToolKit in your JavaScript application, first import it:

1// Using ES6 imports
2import PasswordToolKit from 'password-toolkit';
3
4// Using Node.js `require()`
5const PasswordToolKit = require('password-toolkit');

Usage

The PasswordToolKit module is a class that needs to be instantiated with a settings a object with configuration settings, before it can be used. Once instantiated, you can use the create() and evaluate() methods to create and evaluate passwords.

1// Import the PasswordToolKit module
2const PasswordToolKit = require('password-toolkit');
3
4// Create an instance of PasswordToolKit
5const passwordToolKit = new PasswordToolKit();
6
7// It is equivalent
8const passwordToolKit = new PasswordToolKit({
9  maximum: 30,
10  suggestions: [
11    'The password must have at least 8 characters.',
12    'Add uppercase and lowercase letters to make the password more secure.',
13    'Add numbers to make the password more secure.',
14    'Add symbols to make the password more secure.',
15    'Avoid using repeated characters in the password.',
16    'Avoid using common password patterns.',
17    'Excellent! The password is secure.',
18  ],
19  qualities: ['insecure', 'low', 'medium', 'high', 'perfect'],
20});
21
22// Or You can translate the messages for the evaluation of the password
23const passwordToolKit = new PasswordToolKit({
24  maximum: 30,
25  suggestions: [
26    'La contraseña debe tener al menos 8 caracteres.',
27    'Agregue letras mayúsculas y minúsculas para que la contraseña sea más segura.',
28    'Agregue números para que la contraseña sea más segura.',
29    'Agregue símbolos para que la contraseña sea más segura.',
30    'Evitar el uso de caracteres repetidos en la contraseña.',
31    'Evitar el uso de patrones de contraseña comunes.',
32    '¡Excelente! La contraseña es segura.',
33  ],
34  qualities: ['Inseguro', 'Bajo', 'Medio', 'Alto', 'Perfecto'],
35});
36
37// Generate a password
38const options = {
39  size: 12,
40  numbers: true,
41  symbols: true,
42  uppercases: true,
43  lowercases: true
44};
45
46const validation = passwordToolKit.checkOptions(options);
47
48if (validation.ok) {
49  const password = passwordToolKit.create(options);
50  // Evaluate the security of a password
51  const evaluation = passwordToolKit.evaluate(password);
52
53  // Output the results
54  console.log('Generated Password:', password);
55  console.log('Password Evaluation:', evaluation);
56} else {
57  throw new Error(validation.reason);
58}

Type Definitions

PasswordToolKitSettings

The options for the PasswordToolKit instance.

type: Object

Property	Type	Description
maximum	number	The maximum length allowed for a password.
suggestions	Array.<string>	Texts offering suggestions to improve password security.
qualities	Array.<string>	Quality levels for password strength.

OptionsValidation

The result of validating password options.

type: Object

Property	Type	Description
ok	boolean	Indicates whether the validation passed true or failed false.
reason	string	Reason for the validation result.

GenerateOptions

Configuration options to generate passwords.

type: Object

Property	Type	Description
size	number	The desired size of the password.
numbers	boolean	Indicates whether numbers are allowed in the password.
symbols	boolean	Indicates whether symbols are allowed in the password.
uppercases	boolean	Indicates whether uppercase letters are allowed in the password.
lowercases	boolean	Indicates whether lowercase letters are allowed in the password.

PasswordEvaluation

The result of validating a password's security.

type: Object

Property	Type	Description
level	number	A number indicating the security level of the password (0-5).
suggestion	string	Text offering suggestions to improve password security.
quality	string	The quality level of the password.

API

PasswordToolKit(settings)

Creates an instance of the PasswordToolKit class.

Arguments

Name	Type	Description
settings	object	The options for the PasswordToolKit instance.
settings.maximum	number	The maximum length allowed for a password.
settings.suggestions	Array.<string>	Text offering suggestions to improve password security.
settings.qualities	Array.<string>	Array of quality levels for password strength.

Throws

Type	Description
TypeError	if the options parameter is not an object.
TypeError	if the suggestions value is not an array.
TypeError	if the qualities value is not an array.
TypeError	if the maximum value is not a number.
TypeError	if any suggestions value is not a string.
TypeError	if any qualities value is not a string.
RangeError	if the suggestions array length is not 7.
RangeError	if the qualities array length is not 5.

Example

1const PasswordToolKit = require('password-toolkit');
2
3const passwordToolKit = new PasswordToolKit();
4
5// or
6
7

PasswordToolKit#checkOptions(options)

Checks if the provided options for generating a password are valid.

Arguments

Name	Type	Description
options	object	The options for the password to be generated.
options.size	number	The desired size of the password.
options.numbers	boolean	Indicates whether numbers are allowed in the password.
options.symbols	boolean	Indicates whether symbols are allowed in the password.
options.uppercases	boolean	Indicates whether uppercase letters are allowed in the password.
options.lowercases	boolean	Indicates whether lowercase letters are allowed in the password.

Returns

An object with the following properties:

Property	Type	Description
ok	boolean	Indicates whether the validation passed true or failed false.
reason	string	Reason for the validation result.

Example

1const PasswordToolKit = require('password-toolkit');
2
3const passwordToolKit = new PasswordToolKit();
4const options = {
5  size: 12,
6  numbers: true,
7  symbols: true,
8  uppercases: true,
9  lowercases: true
10};
11const validation = passwordToolKit.checkOptions(options);

PasswordToolKit#generate(options)

The generate() method generates a new password with the provided options. It accepts an options object with the following properties:

Arguments

Name	Type	Description
options	object	The options for the password to be generated.
options.size	number	The desired size of the password.
options.numbers	boolean	Indicates whether numbers are allowed in the password.
options.symbols	boolean	Indicates whether symbols are allowed in the password.
options.uppercases	boolean	Indicates whether uppercase letters are allowed in the password.
options.lowercases	boolean	Indicates whether lowercase letters are allowed in the password.

Returns

The method returns the generated password as a string, or null if the provided options are invalid.

Example

1const options = {
2  size: 12,
3  numbers: true,
4  symbols: true,
5  uppercases: true,
6  lowercases: true
7};
8
9const password = passwordToolKit.create(options);

PasswordToolKit#evaluate(password)

The evaluate() method evaluates the security level of a password. It accepts a password string as input.

Arguments

Name	Type	Description
password	string	The password to be evaluated.

Returns

An object with the following properties:

Property	Type	Description
level	number	A number indicating the security level of the password (0-5).
suggestion	string	Text offering suggestions to improve password security.
quality	string	The quality level of the password.

Throws

Type	Description
TypeError	If the password value is not a string.

Example

1const evaluation = passwordToolKit.evaluate('MySecurePassword123!');
2

Contributing

If you encounter any bugs or issues with PasswordToolKit, issues and feature requests are welcome. Feel free to check issues page if you want to contribute.

License

Distributed under the MIT License. See LICENSE for more information.