diceware-pass-gen 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ricco020
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,96 @@
+# diceware-pass-gen
+
+Generate strong, memorable **diceware passphrases** from the official [EFF large wordlist](https://www.eff.org/dice) (7776 words), with the resulting **entropy computed and displayed**. CLI **and** library, **zero runtime dependencies**, cryptographically secure.
+
+A diceware passphrase is built by picking random words from a fixed list. With the 7776-word EFF list, each word contributes `log2(7776) ≈ 12.92` bits of entropy, so the default 6-word passphrase carries about **77.5 bits** — easy to type and remember, hard to guess.
+
+## Why this exists
+
+Random character strings are strong but hard to remember; people end up reusing weak passwords. Diceware passphrases are both strong and memorable. This tool makes the entropy explicit so you can see exactly how strong a passphrase is, instead of trusting a vague "strength meter".
+
+## Install
+
+```bash
+# Run without installing
+npx diceware-pass-gen
+
+# Or install globally for the CLI
+npm install -g diceware-pass-gen
+
+# Or add as a library
+npm install diceware-pass-gen
+```
+
+Requires Node.js >= 14.
+
+## CLI usage
+
+```bash
+$ diceware-pass-gen
+truffle-hazard-rewire-skincare-payback-mascot
+  entropy: 77.55 bits (6 words from 7776-word EFF list)
+
+$ diceware-pass-gen --words 5 --separator " " --capitalize
+Anchor Voucher Mural Reissue Linger
+  entropy: 64.62 bits (5 words from 7776-word EFF list)
+
+$ diceware-pass-gen -w 7 -n -C 3 -q
+unzip-cardboard-shrunk-eclipse-stunt-sappy-zucchini-4
+...
+```
+
+### Options
+
+| Option | Alias | Description | Default |
+| --- | --- | --- | --- |
+| `--words <n>` | `-w` | Number of words | `6` |
+| `--separator <str>` | `-s` | String between words | `-` |
+| `--capitalize` | `-c` | Capitalize the first letter of each word | off |
+| `--number` | `-n` | Append a random digit at the end | off |
+| `--count <n>` | `-C` | How many passphrases to generate | `1` |
+| `--quiet` | `-q` | Print only the passphrase(s) | off |
+| `--help` | `-h` | Show help | |
+| `--version` | `-v` | Show version | |
+
+## Library usage
+
+```js
+const { generate, entropyBits } = require('diceware-pass-gen');
+
+const result = generate({ words: 6, separator: '-', capitalize: false, number: false });
+console.log(result.passphrase);   // e.g. "truffle-hazard-rewire-skincare-payback-mascot"
+console.log(result.entropyBits);  // 77.55
+console.log(result.words);        // ["truffle", "hazard", ...]
+
+// Compute entropy for an arbitrary word count
+entropyBits(8); // 103.4 (8 * log2(7776))
+```
+
+## How it works
+
+- **Wordlist**: the official EFF large wordlist (7776 words), chosen for memorable, distinct, typo-resistant words.
+- **Randomness**: words are selected with Node's `crypto.randomBytes`, using **rejection sampling** to eliminate modulo bias, so every word is equally likely. There is no `Math.random()` anywhere in the generation path.
+- **Entropy**: reported as `wordCount × log2(7776)` bits (plus `log2(10)` for the optional trailing digit). This assumes uniform, independent word selection — which is exactly what this tool does.
+
+## Choosing a length
+
+| Words | Entropy | Rough guidance |
+| --- | --- | --- |
+| 4 | ~51.7 bits | low — only for low-value accounts |
+| 5 | ~64.6 bits | reasonable for everyday accounts |
+| 6 | ~77.5 bits | strong, good default |
+| 7+ | ~90.5+ bits | high-value accounts, master passwords |
+
+## Storing your passphrases
+
+A strong passphrase is only useful if you don't reuse it and store it safely. For a hands-on **password generator**, an explanation of how password strength is measured, and guidance on using a password manager, see PwdFortress:
+
+**[PwdFortress — Password Generator & strength guidance](https://www.pwdfortress.com/en/tools/password-generator)**
+
+## Credits
+
+The EFF large wordlist is created by the [Electronic Frontier Foundation](https://www.eff.org/dice) and released under [CC BY 3.0](https://creativecommons.org/licenses/by/3.0/). This project bundles that wordlist unmodified.
+
+## License
+
+[MIT](./LICENSE)

package/bin/cli.js

@@ -0,0 +1,129 @@
+#!/usr/bin/env node
+'use strict';
+
+const { generate, WORDLIST_SIZE } = require('../lib/index');
+const pkg = require('../package.json');
+
+function printHelp() {
+  console.log(`diceware-pass-gen v${pkg.version}
+Generate strong, memorable passphrases from the EFF large wordlist (${WORDLIST_SIZE} words).
+
+USAGE:
+  diceware-pass-gen [options]
+
+OPTIONS:
+  -w, --words <n>        Number of words (default: 6)
+  -s, --separator <str>  Separator between words (default: "-")
+  -c, --capitalize       Capitalize the first letter of each word
+  -n, --number           Append a random digit at the end
+  -C, --count <n>        Number of passphrases to generate (default: 1)
+  -q, --quiet            Print only the passphrase(s), no entropy line
+  -h, --help             Show this help
+  -v, --version          Show version
+
+EXAMPLES:
+  diceware-pass-gen
+  diceware-pass-gen -w 5 -s " " --capitalize
+  diceware-pass-gen --words 7 --number --count 3 --quiet
+
+Entropy is computed as words x log2(${WORDLIST_SIZE}) ~ 12.9 bits per word.
+Randomness uses Node's crypto.randomBytes with rejection sampling (no modulo bias).
+
+Learn how to create and store strong passwords:
+  https://www.pwdfortress.com/en/tools/password-generator
+`);
+}
+
+function parseArgs(argv) {
+  const opts = {
+    words: 6,
+    separator: '-',
+    capitalize: false,
+    number: false,
+    count: 1,
+    quiet: false,
+    help: false,
+    version: false,
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    switch (a) {
+      case '-w':
+      case '--words':
+        opts.words = parseInt(argv[++i], 10);
+        break;
+      case '-s':
+      case '--separator':
+        opts.separator = argv[++i];
+        break;
+      case '-c':
+      case '--capitalize':
+        opts.capitalize = true;
+        break;
+      case '-n':
+      case '--number':
+        opts.number = true;
+        break;
+      case '-C':
+      case '--count':
+        opts.count = parseInt(argv[++i], 10);
+        break;
+      case '-q':
+      case '--quiet':
+        opts.quiet = true;
+        break;
+      case '-h':
+      case '--help':
+        opts.help = true;
+        break;
+      case '-v':
+      case '--version':
+        opts.version = true;
+        break;
+      default:
+        console.error(`Unknown option: ${a}`);
+        console.error('Run "diceware-pass-gen --help" for usage.');
+        process.exit(1);
+    }
+  }
+  return opts;
+}
+
+function main() {
+  const opts = parseArgs(process.argv.slice(2));
+
+  if (opts.help) {
+    printHelp();
+    return;
+  }
+  if (opts.version) {
+    console.log(pkg.version);
+    return;
+  }
+
+  if (!Number.isInteger(opts.words) || opts.words < 1) {
+    console.error('Error: --words must be a positive integer.');
+    process.exit(1);
+  }
+  if (!Number.isInteger(opts.count) || opts.count < 1) {
+    console.error('Error: --count must be a positive integer.');
+    process.exit(1);
+  }
+
+  for (let i = 0; i < opts.count; i++) {
+    const result = generate({
+      words: opts.words,
+      separator: opts.separator,
+      capitalize: opts.capitalize,
+      number: opts.number,
+    });
+    if (opts.quiet) {
+      console.log(result.passphrase);
+    } else {
+      console.log(result.passphrase);
+      console.log(`  entropy: ${result.entropyBits} bits (${result.words.length} words from ${result.wordlistSize}-word EFF list)`);
+    }
+  }
+}
+
+main();

package/lib/index.js

@@ -0,0 +1,102 @@
+'use strict';
+
+const crypto = require('crypto');
+const WORDLIST = require('./wordlist');
+
+const WORDLIST_SIZE = WORDLIST.length; // 7776 (EFF large wordlist)
+
+/**
+ * Return a cryptographically secure random integer in [0, max)
+ * using rejection sampling to avoid modulo bias.
+ * @param {number} max - exclusive upper bound (must be > 0)
+ * @returns {number}
+ */
+function secureRandomInt(max) {
+  if (!Number.isInteger(max) || max <= 0) {
+    throw new RangeError('max must be a positive integer');
+  }
+  // Smallest number of bytes that can represent (max - 1).
+  const bytesNeeded = Math.ceil(Math.log2(max) / 8) || 1;
+  const range = 2 ** (8 * bytesNeeded);
+  // Largest multiple of `max` that fits in `range`; values at or above are rejected.
+  const limit = range - (range % max);
+  let value;
+  do {
+    value = 0;
+    const buf = crypto.randomBytes(bytesNeeded);
+    for (let i = 0; i < bytesNeeded; i++) {
+      value = value * 256 + buf[i];
+    }
+  } while (value >= limit);
+  return value % max;
+}
+
+/**
+ * Entropy in bits for a passphrase drawn uniformly from a wordlist.
+ * Each word contributes log2(wordlistSize) bits.
+ * @param {number} wordCount
+ * @param {number} [wordlistSize=WORDLIST_SIZE]
+ * @returns {number} entropy in bits
+ */
+function entropyBits(wordCount, wordlistSize = WORDLIST_SIZE) {
+  if (!Number.isInteger(wordCount) || wordCount <= 0) {
+    throw new RangeError('wordCount must be a positive integer');
+  }
+  return wordCount * Math.log2(wordlistSize);
+}
+
+/**
+ * Generate a diceware passphrase from the EFF large wordlist.
+ * @param {object} [opts]
+ * @param {number} [opts.words=6]       - number of words
+ * @param {string} [opts.separator='-'] - string between words
+ * @param {boolean}[opts.capitalize=false] - capitalize the first letter of each word
+ * @param {boolean}[opts.number=false]  - append a random digit (0-9) at the end
+ * @returns {{ passphrase: string, words: string[], entropyBits: number, wordlistSize: number }}
+ */
+function generate(opts = {}) {
+  const {
+    words = 6,
+    separator = '-',
+    capitalize = false,
+    number = false,
+  } = opts;
+
+  if (!Number.isInteger(words) || words < 1) {
+    throw new RangeError('words must be a positive integer');
+  }
+  if (typeof separator !== 'string') {
+    throw new TypeError('separator must be a string');
+  }
+
+  const picked = [];
+  for (let i = 0; i < words; i++) {
+    let w = WORDLIST[secureRandomInt(WORDLIST_SIZE)];
+    if (capitalize) w = w.charAt(0).toUpperCase() + w.slice(1);
+    picked.push(w);
+  }
+
+  let passphrase = picked.join(separator);
+  let bits = entropyBits(words);
+
+  if (number) {
+    const digit = secureRandomInt(10);
+    passphrase += separator + digit;
+    bits += Math.log2(10); // one extra uniform digit
+  }
+
+  return {
+    passphrase,
+    words: picked,
+    entropyBits: Math.round(bits * 100) / 100,
+    wordlistSize: WORDLIST_SIZE,
+  };
+}
+
+module.exports = {
+  generate,
+  entropyBits,
+  secureRandomInt,
+  WORDLIST,
+  WORDLIST_SIZE,
+};