Merge pull request #2 from benjreinhart/passphrases

Add support for memorable passphrases

Author: benjreinhart

README.md

@@ -1,6 +1,6 @@
 # secure-password-utilities ![Github CI](https://github.com/benjreinhart/secure-password-utilities/workflows/Github%20CI/badge.svg)
 
-Secure, zero-dependency utilities for generating passwords, pins, and more.
+Secure, zero-dependency utilities for generating passwords, passphrases, pins, and more.
 
 * 0️⃣ Zero dependencies
 * 💯 Works in browsers (using _webcrypto_) and node 12.x+ (using _node:crypto_)
@@ -30,6 +30,7 @@ console.log(pin); // 036919
 
 - [secure-password-utilities](#secure-password-utilities)
   - [generatePassword](#generatepassword)
+  - [generatePassphrase](#generatepassphrase)
   - [generatePin](#generatepin)
   - [generateCharacters](#generatecharacters)
 - [secure-password-utilities/constants](#secure-password-utilitiesconstants)
@@ -40,13 +41,17 @@ console.log(pin); // 036919
 - [secure-password-utilities/csprng](#secure-password-utilitiescsprng)
   - [getRandomBytes](#getrandombytes)
 - [secure-password-utilities/random](#secure-password-utilitiesrandom)
+  - [getRandomNumbersInRange](#getrandomnumbersinrange)
   - [getRandomValues](#getrandomvalues)
   - [randomizeCharacters](#randomizecharacters)
+- [secure-password-utilities/wordlists](#secure-password-utilitieswordlists)
+  - [DEFAULT_WORDLIST](#default_wordlist)
+  - [EFF_LONG_WORDLIST](#eff_long_wordlist)
 
 ### secure-password-utilities
 
 ```ts
-import {generatePassword, generatePin, generateCharacters} from 'secure-password-utilities'
+import {generatePassword, generatePassphrase, generatePin, generateCharacters} from 'secure-password-utilities'
 ```
 
 #### generatePassword
@@ -57,8 +62,6 @@ function generatePassword(length: number, options?: PasswordOptionsType): string
 
 Generates a random password.
 
-Uses a CSPRNG for randomness.
-
 `PasswordOptionsType` is defined as:
 
 ```ts
@@ -129,6 +132,29 @@ const evenDigitPassword = generatePassword(12, {
 console.log(evenDigitPassword); // e6V8zy0kfTAN
 ```
 
+#### generatePassphrase
+
+```ts
+function generatePassphrase(length: number, wordlist: readonly string[], sep?: string): string
+```
+
+Generate a memorable passphrase comprised of words chosen randomly from the given wordlist.
+
+There are wordlists available in the [wordlist module](#secure-password-utilitieswordlists), or you can provide your own.
+
+```ts
+import {DEFAULT_WORDLIST} from 'secure-password-utilities/wordlists';
+
+generatePassphrase(6, DEFAULT_WORDLIST); // canopener-uncanny-hatchet-murky-agony-traitor
+generatePassphrase(6, DEFAULT_WORDLIST); // backpack-craftwork-sweat-postcard-imaging-litter
+```
+
+The word separator defaults to a dash (`-`), but you can customize this behavior using the third argument.
+
+```ts
+generatePassphrase(6, DEFAULT_WORDLIST, '_'); // goldfish_scorpion_antiviral_pursuit_demanding_motto
+```
+
 #### generatePin
 
 ```ts
@@ -137,8 +163,6 @@ function generatePin(length: number): string
 
 Generate a random digit pin.
 
-Uses a CSPRNG for randomness.
-
 ```ts
 generatePin(6); // 036919
 generatePin(8); // 45958396
@@ -152,8 +176,6 @@ function generateCharacters(length: number, charset: string): string
 
 Generate a string of `length` characters chosen randomly from the given `charset`.
 
-Uses a CSPRNG for randomness.
-
 ```ts
 generateCharacters(4, '$%^&');                          // &$&^
 generateCharacters(6, '0123456789');                    // 947682
@@ -211,11 +233,29 @@ Generates random bytes. This is a wrapper around the platform's native CSPRNG. I
 ### secure-password-utilities/random
 
 ```ts
-import {getRandomValues, randomizeCharacters} from 'secure-password-utilities/random'
+import {getRandomNumbersInRange, getRandomValues, randomizeCharacters} from 'secure-password-utilities/random'
+```
+
+#### getRandomNumbersInRange
+
+```ts
+function getRandomNumbersInRange(length: number, start: number, end: number): number[]
+```
+
+Get a list of random numbers where each number is greater than or equal to `start` and less than `end`.
+
+The `end` of the range must be less than or equal to 2^16.
+
+```ts
+getRandomNumbersInRange(6, 0, 10) // [8, 2, 1, 3, 5, 0]
+getRandomNumbersInRange(6, 10, 20); // [ 18, 10, 13, 12, 12, 19 ]
+getRandomNumbersInRange(6, 0, 1000); // [111, 752, 41, 420, 360, 630]
 ```
 
 #### getRandomValues
 
+*Note: This is deprecated, use `getRandomNumbersInRange` instead.*
+
 ```ts
 function getRandomValues(numValues: number, rangeMax?: number): Uint8Array
 ```
@@ -232,14 +272,41 @@ function randomizeCharacters(characters: string): string
 
 Randomize the ordering of the characters in the given string.
 
-Uses a CSPRNG for randomness.
-
 ```ts
 randomizeCharacters('randomize me');     // e znmaedimro
 randomizeCharacters('randomize me');     // arndimz moee
 randomizeCharacters('randomize me');     // ai emdonmrze
 ```
 
+### secure-password-utilities/wordlists
+
+```ts
+import {DEFAULT_WORDLIST, EFF_LONG_WORDLIST} from 'secure-password-utilities/wordlists'
+```
+
+#### DEFAULT_WORDLIST
+
+```ts
+const DEFAULT_WORDLIST = Object.freeze([/* EFF long wordlist minus a few entries (see below) */]);
+```
+
+This is the "default" wordlist for use with this library. It is the same as the EFF long wordlist but with the following entries removed:
+
+* drop-down
+* flet-tip
+* t-shirt
+* yo-yo
+
+The reason for this is that a frequent passphrase separator is the "-" which can then result in ambiguous word separations. This keeps the resulting passphrase prettier (in the case where it's joined by dashes) with an unambiguous and deterministic number of dashes.
+
+#### EFF_LONG_WORDLIST
+
+```ts
+const EFF_LONG_WORDLIST = Object.freeze([/* EFF long wordlist, see https://www.eff.org/files/2016/07/18/eff_large_wordlist.txt */]);
+```
+
+The [EFF recommended wordlist](https://www.eff.org/deeplinks/2016/07/new-wordlists-random-passphrases) for passphrases.
+
 ## License
 
 The MIT License (MIT). See [LICENSE file](LICENSE).

package.json

@@ -1,7 +1,7 @@
 {
   "name": "secure-password-utilities",
   "version": "0.1.0",
-  "description": "Secure, zero-dependency utilities for generating passwords, pins, and more",
+  "description": "Secure, zero-dependency utilities for generating passwords, passphrases, pins, and more",
   "keywords": [
     "password",
     "pin",

src/index.ts

@@ -1,4 +1,8 @@
-import { getRandomValues, randomizeCharacters } from 'secure-password-utilities/random';
+import {
+  getRandomValues,
+  getRandomNumbersInRange,
+  randomizeCharacters,
+} from 'secure-password-utilities/random';
 import {
   DIGIT_CHARSET,
   LOWERCASE_CHARSET,
@@ -30,7 +34,7 @@ export type PasswordOptionsType = {
 /**
  * Generate a random password.
  *
- * Uses a CSPRNG for randomness.
+ * Examples:
  *
  *     generatePassword(12); // l[Nz8UfU.o4g
  *     generatePassword(8, { symbols: false, digits: 2 }); // k9WTkaP6
@@ -212,7 +216,7 @@ function validateCharsetOption(name: string, charset: string) {
 /**
  * Generate a random digit pin.
  *
- * Uses a CSPRNG for randomness.
+ * Examples:
  *
  *     generatePin(6); // 036919
  *     generatePin(8); // 45958396
@@ -233,7 +237,7 @@ export function generatePin(length: number) {
 /**
  * Generate a string of `length` characters chosen randomly from the given `charset`.
  *
- * Uses a CSPRNG for randomness.
+ * Examples:
  *
  *     generateCharacters(4, '$%^&');                          // &$&^
  *     generateCharacters(6, '0123456789');                    // 947682
@@ -260,3 +264,44 @@ export function generateCharacters(length: number, charset: string) {
     return characters + charset[i];
   }, '');
 }
+
+/**
+ * Generate a memorable passphrase comprised of words chosen randomly from the given `wordlist`.
+ *
+ * There are wordlists available in the wordlists module, or you can provide your own.
+ *
+ * The word separator defaults to a dash (`-`), but you can customize this behavior using the third argument. "-"
+ *
+ * Examples:
+ *
+ *     generatePassphrase(6, DEFAULT_WORDLIST); // canopener-uncanny-hatchet-murky-agony-traitor
+ *     generatePassphrase(6, DEFAULT_WORDLIST); // backpack-craftwork-sweat-postcard-imaging-litter
+ *     generatePassphrase(6, DEFAULT_WORDLIST, '_'); // goldfish_scorpion_antiviral_pursuit_demanding_motto
+ *
+ * @param length The number of words selected at random.
+ * @param wordlist The list of words to sample from.
+ * @param sep The separator to use when joining the words in the passphrase. Defaults to '-'.
+ * @returns A memorable passphrase.
+ */
+export function generatePassphrase(length: number, wordlist: readonly string[], sep = '-') {
+  if (typeof length !== 'number' || length < 1) {
+    throw new Error(
+      'Invalid argument: length argument must be a number greater than or equal to 1'
+    );
+  }
+
+  if (!Array.isArray(wordlist) || wordlist.length < 2) {
+    throw new Error(
+      'Invalid argument: wordlist argument must be an array with length greater than or equal to 2'
+    );
+  }
+
+  if (typeof sep !== 'string') {
+    throw new Error('Invalid argument: sep argument must be a string');
+  }
+
+  return getRandomNumbersInRange(length, 0, wordlist.length).reduce((passphrase, value, i) => {
+    const word = wordlist[value];
+    return passphrase + (i === 0 ? word : sep + word);
+  }, '');
+}