README

PWD-Phrase

A simple password phrase generator.

Getting Started

There are different ways to use PWD-Phrase:

From CDN

The easiest way to use PWD-Phrase is to include the script from a CDN:

<!DOCTYPE html>
<html>
    <head>
        ...
    </head>
    <body>
        ...

        <script 
            src="https://cdn.jsdelivr.net/npm/pwd-phrase@2.3.1/dist/pwd-phrase.js" 
            integrity="sha256-M02/PtuFUNerJnzLtUfw5eBhqh9TA4eJeLD7aqCaLS8=" 
            crossorigin="anonymous">
        </script>

        <script>
            var pwdPhrase = PwdPhrase({ ... });

            ...
        </script>
    </body>
</html>

To be sure that the DOM is ready when you instantiate PWD-Phrase, place the <script> tag right before the closing </body> tag.

Local Install

$ npm install pwd-phrase --save

Now you can import and use PWD-Phrase like the following:

UMD - Universal Module Definition

import PwdPhrase from 'pwd-phrase';

const pwdPhrase = PwdPhrase({ ... });

// ...

AMD - Asynchronous Module Definition

require(['path/to/dist/pwd-phrase.amd'], function (PwdPhrase) {
    const pwdPhrase = PwdPhrase({ ... });

    // ...
});

CJS - CommonJS

const PwdPhrase = require('pwd-phrase');

const pwdPhrase = PwdPhrase({ ... });

// ...

Questions about integration? Maybe you'll find the answers here.

Nice to know:

PWD-Phrase use external modules, depends on the environment:

Web Cryptography API for UMD and AMD
Crypto for CJS

If you use a bundler like Webpack, the external library should be excluded from the bundle. Instead, the created bundle relies on that dependency to be present in the consumer's (end-user application) environment.

For Webpack the externals configuration option can be used. Check the Webpack configuration file for an example.

Configuration

PWD-Phrase can be configured easily:

const pwdPhrase = PwdPhrase({
    // ...
    phraseQuality  : 6,
    phraseQuantity : 9,
    // ...
});

The configuration properties in detail:

Property	Type	Required	Default	Description
indexCollection	string[]	✗	`['lowercase', 'uppercase', 'digit', 'symbol']`	a list of charsets used in the password index, use `lowercase`, `uppercase`, `digit`, `symbol` and/or `custom`
indexExclude	string	✗	`''`	a string of custom characters to exclude from the password index
indexInclude	string	✓*	`''`	a string of custom characters used in the password index, *only considered if `indexCollection` contains `custom`
indexSimilars	boolean	✗	`true`	use similar characters in the password index or not
phraseCollection	string[]	✗	`['lowercase', 'uppercase', 'digit', 'symbol']`	a list of charsets used in the password phrase, use `lowercase`, `uppercase`, `digit`, `symbol` and/or `custom`
phraseExclude	string	✗	`''`	a string of custom characters to exclude from the password phrase
phraseInclude	string	✓*	`''`	a string of custom characters used in the password phrase, *only considered if `phraseCollection` contains `custom`
phraseQuality	number	✗	`8`	the password strength
phraseQuantity	number	✗	`1`	number of generated passwords per index item
phraseSimilars	boolean	✗	`false`	use similar characters in the password phrase or not

Charsets

lowercase - [a-z]
uppercase - [A-Z]
digit - [0-9]
symbol - ! ? @ # § $ % & * + - = _ ( ) { } [ ] /

Similar Characters

i I l L o O 0 - _

Recipes

Customized index:

const pwdPhrase = PwdPhrase({
    indexCollection : ['custom'],
    indexInclude    : 'abc123',
    phraseQuality   : 4,
    phraseQuantity  : 2
});

// Result:

pwdPhrase = [
    { index : 'a', pwd : ['!?@x', 'Hp7?'] },
    { index : 'b', pwd : ['2z]w', 'f*§/'] },
    { index : 'c', pwd : ['2QEF', 'at%d'] },
    { index : '1', pwd : ['W8PR', 'bBfa'] },
    { index : '2', pwd : ['$[[&', '{szX'] },
    { index : '3', pwd : ['=bwC', 'V*n3'] }
];

Exclude from index:

const pwdPhrase = PwdPhrase({
    indexCollection : ['uppercase', 'lowercase'],
    indexExclude    : 'bcAD'
});

// Result:

pwdPhrase = [
    { index : 'B', pwd : ['uKD*WenZ'] },
    { index : 'C', pwd : ['wPtJpY?

] },
    { index : 'E', pwd : ['K!&gHp7?'] },

    // ...

    { index : 'a', pwd : ['[HP@cM14'] },
    { index : 'd', pwd : ['7a5E3vNK'] },
    { index : 'e', pwd : ['ATK!&Bbz'] },

    // ...
];

Alphabetical phrase:

const pwdPhrase = PwdPhrase({
    indexCollection  : ['lowercase', 'uppercase'],
    phraseCollection : ['lowercase', 'uppercase'],
    phraseQuality    : 3,
    phraseQuantity   : 3
});

// Result:

pwdPhrase = [
    { index : 'a', pwd : ['Bdn', 'Fcr', 'cRQ'] },
    { index : 'b', pwd : ['ppF', 'shy', 'pdV'] },

    // ...

    { index : 'y', pwd : ['KKs', 'NBa', 'EEE'] },
    { index : 'z', pwd : ['qfG', 'zRh', 'Dvh'] },
    { index : 'A', pwd : ['DkZ', 'aCF', 'TwV'] },
    { index : 'B', pwd : ['upU', 'TpC', 'bQM'] },

    // ...

    { index : 'Y', pwd : ['vjJ', 'Vct', 'jey'] },
    { index : 'Z', pwd : ['EzY', 'yYP', 'QVm'] }
];

Numeric phrase:

const pwdPhrase = PwdPhrase({
    indexCollection  : ['digit'],
    phraseCollection : ['digit'],
    phraseQuality    : 1,
    phraseQuantity   : 6,
    phraseSimilars   : true
});

// Result:

pwdPhrase = [
    { index : '0', pwd : ['5', '1', '3', '3', '8', '0'] },
    { index : '1', pwd : ['7', '2', '6', '6', '0', '6'] },

    // ...

    { index : '8', pwd : ['8', '4', '0', '9', '5', '2'] },
    { index : '9', pwd : ['4', '1', '7', '8', '3', '4'] }
];

Have a nice day... :v:

Usage no npm install needed!