pwgen-core

A secure password generator using word lists, configurable and easy to use.

Description

This package provides a flexible function to generate secure passphrases based on word lists. You can control the number of words, minimum length, capitalization, separators, and whether to append numbers.

It uses cryptographically secure random number generation and is compatible with both Node.js and browser environments, making it suitable for use in server-side applications, command-line tools, or web applications (React, Vue, Svelte, etc.).

Installation

npm install pwgen-core
# or
yarn add pwgen-core
# or
pnpm add pwgen-core

Usage

import {
  generatePassword,
  basicWordList,
  jargonWordList,
  scienceTermList
} from 'pwgen-core';

// Default usage (uses basicWordList implicitly by options)
const defaultPassword = generatePassword({ wordlist: basicWordList });
console.log('Default (Basic):', defaultPassword);

// Use the Jargon wordlist
const jargonPassword = generatePassword({
  wordlist: jargonWordList,
  numWords: 3,
  separator: '_',
  capitalize: false,
});
console.log('Jargon:', jargonPassword);

// Use the Science Terms wordlist
const sciencePassword = generatePassword({
  wordlist: scienceTermList,
  numWords: 4,
  capitalize: true,
  appendNumber: true,
});
console.log('Science:', sciencePassword);

// Custom options
const customPassword = generatePassword({
  wordlist: basicWordList, // Required: provide your own array of strings
  numWords: 5,
  minLength: 20,
  separator: '-',
  capitalize: true,
  appendNumber: true,
});
console.log('Custom:', customPassword); // e.g., 'Alpha-Bravo-Charlie-Delta-Echo99'

// Simple, 4 words, space separated
const simplePassword = generatePassword({
  wordlist: basicWordList,
  numWords: 4,
  minLength: 0, // Disable min length check if only word count matters
  separator: ' ',
  capitalize: false,
  appendNumber: false,
});
console.log('Simple:', simplePassword); // e.g., 'uniform uniform november hotel'

Options

The generatePassword function accepts an options object with the following properties:

| Option | Type | Default | Description | |----------------|-----------|-------------|-----------------------------------------------------------------------------| | wordlist | string[]| Required| An array of words to choose from. | | numWords | number | 2 | The minimum number of words to include. | | minLength | number | 12 | The minimum length the final passphrase must have. | | separator | string | "" | The string used to join words. Empty string means direct concatenation. | | capitalize | boolean | true | Whether to capitalize the first letter of each word. | | appendNumber | boolean | true | Whether to append a random two-digit number (10-99) to the end. |

Note: The generator ensures both numWords and minLength criteria are met. It will keep adding words until the chosen words joined by the separator reach the minLength.

Included Wordlists

For convenience, several wordlists are exported:

• basicWordList: Derived from the NATO phonetic alphabet (26 words).
• jargonWordList: A list of technical/computer jargon.
• scienceTermList: A list of scientific terms.

You are encouraged to provide your own, larger wordlist for better security.

import {
  basicWordList,
  jargonWordList,
  scienceTermList
} from 'pwgen-core';

console.log('Basic count:', basicWordList.length);
console.log('Jargon count:', jargonWordList.length);
console.log('Science count:', scienceTermList.length);

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

License

MIT