Skip to content

Latest commit

 

History

History
86 lines (61 loc) · 4.71 KB

README.md

File metadata and controls

86 lines (61 loc) · 4.71 KB
Raw

Buttercup Password Generator

Build Status npm version

A password generator that's used in Buttercup.

Usage

You can generate a generic password by simply running the following:

const { generatePassword, getConfig } = require("@buttercup/generator");

const config = getConfig(); // Generic config
generatePassword(config).then(password => {
    // password is a string
});

You can change what types of passwords are generated by manipulating the config object.

Generation errors

Errors may occur for a variety of reasons, primarily due to user options being too restrictive (or just by random chance). Each predictable error should have a code (thrownError.code) associated with it:

  • BAD_MODE: An invalid generation mode was selected.
  • NO_CHARSETS: No character sets were enabled - so no password could be generated.
  • MAX_RETRIES: An attempt at generating a password was made, but due to the selected character sets, restrictive repeat rules (config.randomCharacters.allowRepeatingCharacters and config.randomCharacters.allowRepeatingSets) and random chance, no password could be generated within the allowed number of retries.

Configuration

After getting a configuration object by running getConfig(), you can set config.mode to one of the two following behaviours:

  • characters: Generate a password made up of random characters. Character sets are used to customise the output. This is the default mode.
  • words: Generate a password made up of random words.

Random character configuration

You can set the length of the password by changing config.randomCharacters.length. You can change the repetition behaviour of the password by changing the two following values:

  • config.randomCharacters.allowRepeatingCharacters: Whether or not to allow repeating characters in the generated password. The default is false.
  • config.randomCharacters.allowRepeatingSets: Whether or not to allow repeating character sets. The default is true.

You can set what character sets are used to generate the random-character passwords. The available character sets are available on the object config.randomCharacters.characterSets. The enabled character sets are set on config.randomCharacters.enabledCharacterSets, which is an array of the names of enabled character sets.

For example, the following allows for generation of passwords that are 20 characters long with only letters and numbers:

const config = getConfig();
config.randomCharacters.length = 20;
config.randomCharacters.enabledCharacterSets = ["UPPERCASE", "LOWERCASE", "DIGITS"];
generatePassword(config).then(password => {
    // do something with the password
});

Similarly, you could enable the use of all character sets by using:

config.randomCharacters.enabledCharacterSets = Object.keys(config.randomCharacters.characterSets);

Important note: Limiting the character sets, as well as enforcing strict non-repeat rules, may cause the password generator to throw. You should gracefully handle thrown errors in any interface this component is used.

Random word configuration

After setting config.mode to "words", you can use the config.randomWords object to configure the generation. Set the number of generated words by using config.randomWords.length to the desired count. The words are joined by the string config.randomWords.separator.

Setup for platforms other than NodeJS

An asynchronous random number generator is used so that other platforms may easily be supported. Random number generation doesn't work well in the browser (in a broad sense), and doesn't really work at all in React-Native (crypto PRNG).

You should override the random number generation on platforms where better solutions are available (when compared to this library's built in generator). The override function should take an array of objects that resemble { min, max }, where min and max are bounds for random number generation. For each item in the array, a random number should be generated between the provided range (bounds inclusive). For example:

const { setRNG } = require("@buttercup/generator");

// Overriden method must return a Promise with an array of the
// generated numbers
setRNG(items => {
    return Promise.all(items.map(item => {
        return someRandomNumberGenerator(item.min, item.max);
    }));
});

Installation

Install the library by running:

npm install @buttercup/generator --save