PasswordRuler

What does it do?

It helps you easily create a customized password complexity calculator, and furthermore, to build your own strength meter.

Why?

Because -almost- every company you work for has its own requirements & specifications.

Install

npm install --save password-ruler

Usage

Basic scenario

Let's say that you just want to have a basic complexity score:

const PasswordRuler = require('password-ruler');

// Constructor can take an object (one strength level)
// or an array of objects (length of array = number of levels).
// In this scenario, one strength level is fine:
const ruler = new PasswordRuler({
  minLength: { // a validator object has to have 2 props; "weight" & "validate"
    weight: 1, // basically the importance degree of validator
    validate: function(password) { // first argument is always the password
      return password.length > 3;
    }
  },
  containsAnUppercase: {
    weight: 2,
    validate: [Function]
  },
  containsASpecialCharacter: {
    weight: 2,
    validate: [Function]
  }
});

ruler.check('test');
// => {
//   score: 20,
//   strength: 0,
//   levels: [{
//     score: 20,
//     validator: {
//       minLength: true,
//       containsAnUppercase: false,
//       containsASpecialCharacter: false
//     }
//   }]
// }

ruler.check('Test');
// => {
//   score: 60,
//   strength: 0,
//   levels: [{
//     score: 60,
//     validator: {
//       minLength: true,
//       containsAnUppercase: true,
//       containsASpecialCharacter: false
//     }
//   }]
// }

ruler.check('Test*');
// => {
//   score: 100,
//   strength: 1,
//   levels: [{
//     score: 100,
//     validator: {
//       minLength: true,
//       containsAnUppercase: true,
//       containsASpecialCharacter: true
//     }
//   }]
// }

Multiple strength-levels

Let's rapidly create a password strength meter that has 3 levels, using PasswordRuler Add-ons:

const {
  containsUpperCase,
  containsDigit,
  containsSpecialChar,
  excludesSequentialDigits,
  excludesBirthDate
} = require('password-ruler-addons'); // see above link for all available methods

const ruler = new PasswordRuler([
  { // 1st level (Weak):
    uppercase: containsUpperCase(), // Add-ons methods always return a validator
    number: containsDigit()
  },
  { // 2nd level:
    special: containsSpecialChar(2, 3), // => weight: 3 (the value comes after required parameters sets the weight of validator)
    sequential: excludesSequentialDigits(4), // excludes 4 digits, weight is still 1 as default
  },
  { // 3rd level (Strong)
    birthdate: excludesBirthDate()
  }
]);

ruler.check('**Test1234');
// => {
//   score: 71, // overall score that is calculated based on validator weights
//   strength: 1, // makes only the 1st level: weak
//   levels: [
//     {
//       score: 100,
//       validator: {
//         uppercase: true,
//         number: true
//       }
//     },
//     {
//       score: 75, // individual level score
//       validator: {
//         special: true,
//         sequential: false
//       }
//     },
//     {
//       score: 0,
//       validator: {
//         birthdate: undefined
//       }
//     }
//   ]
// }

API

• PasswordRuler
  • instance
    • .addLevel(level) ⇒ PasswordRuler
    • .addValidator(name, validate, weight, [levelIndex]) ⇒ PasswordRuler
    • .check(password) ⇒ Object
  • static
    • .init(passwordRuler, levels)

addLevel(level) ⇒ PasswordRuler

Adds a new level on top of existing levels.

Kind: instance method of PasswordRuler Returns: PasswordRuler - PasswordRuler instance's itself

| Param | Type | Description | | --- | --- | --- | | level | Object | A level object with one or multiple validators |

addValidator(name, validate, weight, [levelIndex]) ⇒ PasswordRuler

Adds a new validator to the given or last level.

Kind: instance method of PasswordRuler Returns: PasswordRuler - PasswordRuler instance's itself

| Param | Type | Description | | --- | --- | --- | | name | String | Validator name | | validate | function | Validation function | | weight | Integer | Validator importance rate | | [levelIndex] | Integer | Index of level (If it is not available, validator will be added to the last level) |

check(password) ⇒ Object

Checks the given password & provides a result object

Kind: instance method of PasswordRuler Returns: Object - A result object that contains score, strenght & level props

| Param | Type | Description | | --- | --- | --- | | password | String | Password to check |

PasswordRuler.init(passwordRuler, levels)

Applies each given levels to the given PasswordRuler instance

Kind: static method of PasswordRuler

| Param | Type | Description | | --- | --- | --- | | passwordRuler | PasswordRuler | An instance of PasswordRuler | | levels | Array | Object | A level list with validators or a single level object |

Related

• PasswordRuler Add-ons
• common-password-rules

License

MIT http://tameraydin.mit-license.org/