lockly 0.1.0 → 0.2.0

package/README.md

@@ -2,13 +2,14 @@
 
 Cryptographically secure password generator CLI.
 
-Generates unpredictable random passwords instantly using `node:crypto.getRandomValues()`.
+Generates unpredictable random passwords instantly using the Web Crypto API (`crypto.getRandomValues()`).
 
 ## Features
 
-- **Cryptographically secure** — CSPRNG via `node:crypto`
+- **Cryptographically secure** — CSPRNG via Web Crypto API
+- **Browser compatible** — works in Node.js and browsers
 - **Fast** — under 50ms response time
-- **Customizable** — length, character sets, count
+- **Customizable** — length, character sets, count, charset inclusion guarantee (`--ensure`)
 - **Pipe-friendly** — clean stdout output, no ANSI colors
 - **Zero install** — run instantly with `npx`
 
@@ -52,6 +53,16 @@ lockly --no-uppercase --no-lowercase --no-symbols -l 6
 lockly --no-lowercase --no-symbols
 ```
 
+### Ensure charset inclusion
+
+```bash
+# Guarantee at least one character from each active charset
+lockly --ensure
+
+# Short password with guaranteed diversity
+lockly --ensure -l 4
+```
+
 ### Piping
 
 ```bash
@@ -81,12 +92,13 @@ export DB_PASSWORD=$(lockly -l 24 --no-symbols)
 | `--no-lowercase` | Exclude lowercase (a-z) | included | - |
 | `--no-numbers` | Exclude digits (0-9) | included | - |
 | `--no-symbols` | Exclude symbols | included | - |
+| `--ensure` | Guarantee at least one char from each active charset | off | - |
 | `-V, --version` | Show version | - | - |
 | `-h, --help` | Show help | - | - |
 
 ## Security
 
-- **CSPRNG**: Uses `node:crypto.getRandomValues()` instead of `Math.random()`
+- **CSPRNG**: Uses `crypto.getRandomValues()` (Web Crypto API) instead of `Math.random()`
 - **Local execution**: No network requests — passwords are generated locally
 - **Stateless**: Generated passwords are never stored
 - **No modulo bias**: Rejection sampling ensures uniform distribution
@@ -117,11 +129,17 @@ const customPasswords = generatePassword({
   numbers: true,
   symbols: false
 });
+
+// Ensure at least one character from each active charset
+const ensured = generatePassword({
+  length: 16,
+  ensure: true
+});
 ```
 
 ## Requirements
 
-- Node.js 20+
+- Node.js 20+ or any modern browser with Web Crypto API support
 
 ## License
 

package/dist/cli.js

@@ -3,24 +3,76 @@ import { Command } from 'commander';
 import { readFileSync } from 'fs';
 import { fileURLToPath } from 'url';
 import { dirname, join } from 'path';
-import { getRandomValues } from 'crypto';
 
+// src/generator.ts
+var getRandomValues = globalThis.crypto.getRandomValues.bind(
+  globalThis.crypto
+);
 var UPPERCASE = "ABCDEFGHIJKLMNOPQRSTUVWXYZ";
 var LOWERCASE = "abcdefghijklmnopqrstuvwxyz";
 var NUMBERS = "0123456789";
 var SYMBOLS = "!@#$%^&*()_+-=[]{}|;:,.<>?";
 function buildPool(options2) {
   let pool = "";
-  if (options2.uppercase) pool += UPPERCASE;
-  if (options2.lowercase) pool += LOWERCASE;
-  if (options2.numbers) pool += NUMBERS;
-  if (options2.symbols) pool += SYMBOLS;
-  return pool;
+  const charsets = [];
+  if (options2.uppercase) {
+    pool += UPPERCASE;
+    charsets.push(UPPERCASE);
+  }
+  if (options2.lowercase) {
+    pool += LOWERCASE;
+    charsets.push(LOWERCASE);
+  }
+  if (options2.numbers) {
+    pool += NUMBERS;
+    charsets.push(NUMBERS);
+  }
+  if (options2.symbols) {
+    pool += SYMBOLS;
+    charsets.push(SYMBOLS);
+  }
+  return { pool, charsets };
+}
+function pickRandomChar(charset) {
+  const len = charset.length;
+  const limit = 256 - 256 % len;
+  for (; ; ) {
+    const randomBytes = new Uint8Array(2);
+    getRandomValues(randomBytes);
+    for (let i = 0; i < randomBytes.length; i++) {
+      if (randomBytes[i] < limit) {
+        return charset[randomBytes[i] % len];
+      }
+    }
+  }
 }
-function generateSingle(length2, pool) {
+function cryptoShuffle(arr) {
+  for (let i = arr.length - 1; i > 0; i--) {
+    const range = i + 1;
+    const limit = 256 - 256 % range;
+    let j;
+    for (; ; ) {
+      const randomBytes = new Uint8Array(1);
+      getRandomValues(randomBytes);
+      if (randomBytes[0] < limit) {
+        j = randomBytes[0] % range;
+        break;
+      }
+    }
+    const tmp = arr[i];
+    arr[i] = arr[j];
+    arr[j] = tmp;
+  }
+}
+function generateSingle(length2, pool, charsets) {
   const poolLength = pool.length;
   const limit = 256 - 256 % poolLength;
   const chars = [];
+  if (charsets) {
+    for (const charset of charsets) {
+      chars.push(pickRandomChar(charset));
+    }
+  }
   while (chars.length < length2) {
     const remaining = length2 - chars.length;
     const bufferSize = remaining * 2;
@@ -33,6 +85,9 @@ function generateSingle(length2, pool) {
       }
     }
   }
+  if (charsets) {
+    cryptoShuffle(chars);
+  }
   return chars.join("");
 }
 function validateOptions(options2) {
@@ -48,6 +103,14 @@ function validateOptions(options2) {
   if (!options2.uppercase && !options2.lowercase && !options2.numbers && !options2.symbols) {
     throw new Error("\uCD5C\uC18C 1\uAC1C \uC774\uC0C1\uC758 \uBB38\uC790\uC14B\uC744 \uD3EC\uD568\uD574\uC57C \uD569\uB2C8\uB2E4");
   }
+  if (options2.ensure) {
+    const activeCount = (options2.uppercase ? 1 : 0) + (options2.lowercase ? 1 : 0) + (options2.numbers ? 1 : 0) + (options2.symbols ? 1 : 0);
+    if (options2.length < activeCount) {
+      throw new Error(
+        `ensure \uBAA8\uB4DC\uC5D0\uC11C\uB294 \uAE38\uC774\uAC00 \uD65C\uC131 \uBB38\uC790\uC14B \uC218(${activeCount}) \uC774\uC0C1\uC774\uC5B4\uC57C \uD569\uB2C8\uB2E4`
+      );
+    }
+  }
 }
 function generatePassword(options2) {
   const resolved = {
@@ -56,13 +119,20 @@ function generatePassword(options2) {
     uppercase: options2?.uppercase ?? true,
     lowercase: options2?.lowercase ?? true,
     numbers: options2?.numbers ?? true,
-    symbols: options2?.symbols ?? true
+    symbols: options2?.symbols ?? true,
+    ensure: options2?.ensure ?? false
   };
   validateOptions(resolved);
-  const pool = buildPool(resolved);
+  const { pool, charsets } = buildPool(resolved);
   const passwords = [];
   for (let i = 0; i < resolved.count; i++) {
-    passwords.push(generateSingle(resolved.length, pool));
+    passwords.push(
+      generateSingle(
+        resolved.length,
+        pool,
+        resolved.ensure ? charsets : void 0
+      )
+    );
   }
   return passwords;
 }
@@ -78,37 +148,37 @@ program.name("lockly").description("Cryptographically secure random password gen
   "-l, --length <number>",
   "\uD328\uC2A4\uC6CC\uB4DC \uAE38\uC774 (\uAE30\uBCF8: 16, \uBC94\uC704: 1-1024)",
   "16"
-).option("-c, --count <number>", "\uC0DD\uC131 \uAC1C\uC218 (\uAE30\uBCF8: 1)", "1").option("--no-uppercase", "\uB300\uBB38\uC790(A-Z) \uC81C\uC678").option("--no-lowercase", "\uC18C\uBB38\uC790(a-z) \uC81C\uC678").option("--no-numbers", "\uC22B\uC790(0-9) \uC81C\uC678").option("--no-symbols", "\uD2B9\uC218\uBB38\uC790 \uC81C\uC678").helpOption("-h, --help", "\uB3C4\uC6C0\uB9D0");
+).option("-c, --count <number>", "\uC0DD\uC131 \uAC1C\uC218 (\uAE30\uBCF8: 1)", "1").option("--no-uppercase", "\uB300\uBB38\uC790(A-Z) \uC81C\uC678").option("--no-lowercase", "\uC18C\uBB38\uC790(a-z) \uC81C\uC678").option("--no-numbers", "\uC22B\uC790(0-9) \uC81C\uC678").option("--no-symbols", "\uD2B9\uC218\uBB38\uC790 \uC81C\uC678").option("--ensure", "\uAC01 \uBB38\uC790\uC14B\uC5D0\uC11C \uCD5C\uC18C 1\uC790 \uD3EC\uD568 \uBCF4\uC7A5").helpOption("-h, --help", "\uB3C4\uC6C0\uB9D0");
 program.parse();
 var options = program.opts();
 var length = parseInt(options.length, 10);
 var count = parseInt(options.count, 10);
 if (isNaN(length)) {
   console.error("\uC720\uD6A8\uD55C \uC22B\uC790\uB97C \uC785\uB825\uD574\uC8FC\uC138\uC694 (length)");
-  process.exit(1);
-}
-if (isNaN(count)) {
+  process.exitCode = 1;
+} else if (isNaN(count)) {
   console.error("\uC720\uD6A8\uD55C \uC22B\uC790\uB97C \uC785\uB825\uD574\uC8FC\uC138\uC694 (count)");
-  process.exit(1);
-}
-try {
-  const passwords = generatePassword({
-    length,
-    count,
-    uppercase: options.uppercase,
-    lowercase: options.lowercase,
-    numbers: options.numbers,
-    symbols: options.symbols
-  });
-  for (const password of passwords) {
-    console.log(password);
-  }
-  process.exit(0);
-} catch (error) {
-  if (error instanceof Error) {
-    console.error(error.message);
-  } else {
-    console.error("\uC54C \uC218 \uC5C6\uB294 \uC5D0\uB7EC\uAC00 \uBC1C\uC0DD\uD588\uC2B5\uB2C8\uB2E4");
-  }
-  process.exit(1);
+  process.exitCode = 1;
+} else {
+  try {
+    const passwords = generatePassword({
+      length,
+      count,
+      uppercase: options.uppercase,
+      lowercase: options.lowercase,
+      numbers: options.numbers,
+      symbols: options.symbols,
+      ensure: options.ensure
+    });
+    for (const password of passwords) {
+      console.log(password);
+    }
+  } catch (error) {
+    if (error instanceof Error) {
+      console.error(error.message);
+    } else {
+      console.error("\uC54C \uC218 \uC5C6\uB294 \uC5D0\uB7EC\uAC00 \uBC1C\uC0DD\uD588\uC2B5\uB2C8\uB2E4");
+    }
+    process.exitCode = 1;
+  }
 }

package/dist/index.cjs

@@ -1,29 +1,79 @@
 'use strict';
 
-var crypto = require('crypto');
-
 // src/generator.ts
+var getRandomValues = globalThis.crypto.getRandomValues.bind(
+  globalThis.crypto
+);
 var UPPERCASE = "ABCDEFGHIJKLMNOPQRSTUVWXYZ";
 var LOWERCASE = "abcdefghijklmnopqrstuvwxyz";
 var NUMBERS = "0123456789";
 var SYMBOLS = "!@#$%^&*()_+-=[]{}|;:,.<>?";
 function buildPool(options) {
   let pool = "";
-  if (options.uppercase) pool += UPPERCASE;
-  if (options.lowercase) pool += LOWERCASE;
-  if (options.numbers) pool += NUMBERS;
-  if (options.symbols) pool += SYMBOLS;
-  return pool;
+  const charsets = [];
+  if (options.uppercase) {
+    pool += UPPERCASE;
+    charsets.push(UPPERCASE);
+  }
+  if (options.lowercase) {
+    pool += LOWERCASE;
+    charsets.push(LOWERCASE);
+  }
+  if (options.numbers) {
+    pool += NUMBERS;
+    charsets.push(NUMBERS);
+  }
+  if (options.symbols) {
+    pool += SYMBOLS;
+    charsets.push(SYMBOLS);
+  }
+  return { pool, charsets };
+}
+function pickRandomChar(charset) {
+  const len = charset.length;
+  const limit = 256 - 256 % len;
+  for (; ; ) {
+    const randomBytes = new Uint8Array(2);
+    getRandomValues(randomBytes);
+    for (let i = 0; i < randomBytes.length; i++) {
+      if (randomBytes[i] < limit) {
+        return charset[randomBytes[i] % len];
+      }
+    }
+  }
 }
-function generateSingle(length, pool) {
+function cryptoShuffle(arr) {
+  for (let i = arr.length - 1; i > 0; i--) {
+    const range = i + 1;
+    const limit = 256 - 256 % range;
+    let j;
+    for (; ; ) {
+      const randomBytes = new Uint8Array(1);
+      getRandomValues(randomBytes);
+      if (randomBytes[0] < limit) {
+        j = randomBytes[0] % range;
+        break;
+      }
+    }
+    const tmp = arr[i];
+    arr[i] = arr[j];
+    arr[j] = tmp;
+  }
+}
+function generateSingle(length, pool, charsets) {
   const poolLength = pool.length;
   const limit = 256 - 256 % poolLength;
   const chars = [];
+  if (charsets) {
+    for (const charset of charsets) {
+      chars.push(pickRandomChar(charset));
+    }
+  }
   while (chars.length < length) {
     const remaining = length - chars.length;
     const bufferSize = remaining * 2;
     const randomBytes = new Uint8Array(bufferSize);
-    crypto.getRandomValues(randomBytes);
+    getRandomValues(randomBytes);
     for (let i = 0; i < randomBytes.length && chars.length < length; i++) {
       const byte = randomBytes[i];
       if (byte < limit) {
@@ -31,6 +81,9 @@ function generateSingle(length, pool) {
       }
     }
   }
+  if (charsets) {
+    cryptoShuffle(chars);
+  }
   return chars.join("");
 }
 function validateOptions(options) {
@@ -46,6 +99,14 @@ function validateOptions(options) {
   if (!options.uppercase && !options.lowercase && !options.numbers && !options.symbols) {
     throw new Error("\uCD5C\uC18C 1\uAC1C \uC774\uC0C1\uC758 \uBB38\uC790\uC14B\uC744 \uD3EC\uD568\uD574\uC57C \uD569\uB2C8\uB2E4");
   }
+  if (options.ensure) {
+    const activeCount = (options.uppercase ? 1 : 0) + (options.lowercase ? 1 : 0) + (options.numbers ? 1 : 0) + (options.symbols ? 1 : 0);
+    if (options.length < activeCount) {
+      throw new Error(
+        `ensure \uBAA8\uB4DC\uC5D0\uC11C\uB294 \uAE38\uC774\uAC00 \uD65C\uC131 \uBB38\uC790\uC14B \uC218(${activeCount}) \uC774\uC0C1\uC774\uC5B4\uC57C \uD569\uB2C8\uB2E4`
+      );
+    }
+  }
 }
 function generatePassword(options) {
   const resolved = {
@@ -54,13 +115,20 @@ function generatePassword(options) {
     uppercase: options?.uppercase ?? true,
     lowercase: options?.lowercase ?? true,
     numbers: options?.numbers ?? true,
-    symbols: options?.symbols ?? true
+    symbols: options?.symbols ?? true,
+    ensure: options?.ensure ?? false
   };
   validateOptions(resolved);
-  const pool = buildPool(resolved);
+  const { pool, charsets } = buildPool(resolved);
   const passwords = [];
   for (let i = 0; i < resolved.count; i++) {
-    passwords.push(generateSingle(resolved.length, pool));
+    passwords.push(
+      generateSingle(
+        resolved.length,
+        pool,
+        resolved.ensure ? charsets : void 0
+      )
+    );
   }
   return passwords;
 }

package/dist/index.d.cts

@@ -36,6 +36,12 @@ interface GenerateOptions {
      * @default true
      */
     symbols?: boolean;
+    /**
+     * Ensure at least one character from each enabled charset is included.
+     * When enabled, the password length must be >= the number of active charsets.
+     * @default false
+     */
+    ensure?: boolean;
 }
 /**
  * Generate one or more cryptographically secure random passwords.

package/dist/index.d.ts

@@ -36,6 +36,12 @@ interface GenerateOptions {
      * @default true
      */
     symbols?: boolean;
+    /**
+     * Ensure at least one character from each enabled charset is included.
+     * When enabled, the password length must be >= the number of active charsets.
+     * @default false
+     */
+    ensure?: boolean;
 }
 /**
  * Generate one or more cryptographically secure random passwords.

package/dist/index.js

@@ -1,22 +1,72 @@
-import { getRandomValues } from 'crypto';
-
 // src/generator.ts
+var getRandomValues = globalThis.crypto.getRandomValues.bind(
+  globalThis.crypto
+);
 var UPPERCASE = "ABCDEFGHIJKLMNOPQRSTUVWXYZ";
 var LOWERCASE = "abcdefghijklmnopqrstuvwxyz";
 var NUMBERS = "0123456789";
 var SYMBOLS = "!@#$%^&*()_+-=[]{}|;:,.<>?";
 function buildPool(options) {
   let pool = "";
-  if (options.uppercase) pool += UPPERCASE;
-  if (options.lowercase) pool += LOWERCASE;
-  if (options.numbers) pool += NUMBERS;
-  if (options.symbols) pool += SYMBOLS;
-  return pool;
+  const charsets = [];
+  if (options.uppercase) {
+    pool += UPPERCASE;
+    charsets.push(UPPERCASE);
+  }
+  if (options.lowercase) {
+    pool += LOWERCASE;
+    charsets.push(LOWERCASE);
+  }
+  if (options.numbers) {
+    pool += NUMBERS;
+    charsets.push(NUMBERS);
+  }
+  if (options.symbols) {
+    pool += SYMBOLS;
+    charsets.push(SYMBOLS);
+  }
+  return { pool, charsets };
+}
+function pickRandomChar(charset) {
+  const len = charset.length;
+  const limit = 256 - 256 % len;
+  for (; ; ) {
+    const randomBytes = new Uint8Array(2);
+    getRandomValues(randomBytes);
+    for (let i = 0; i < randomBytes.length; i++) {
+      if (randomBytes[i] < limit) {
+        return charset[randomBytes[i] % len];
+      }
+    }
+  }
 }
-function generateSingle(length, pool) {
+function cryptoShuffle(arr) {
+  for (let i = arr.length - 1; i > 0; i--) {
+    const range = i + 1;
+    const limit = 256 - 256 % range;
+    let j;
+    for (; ; ) {
+      const randomBytes = new Uint8Array(1);
+      getRandomValues(randomBytes);
+      if (randomBytes[0] < limit) {
+        j = randomBytes[0] % range;
+        break;
+      }
+    }
+    const tmp = arr[i];
+    arr[i] = arr[j];
+    arr[j] = tmp;
+  }
+}
+function generateSingle(length, pool, charsets) {
   const poolLength = pool.length;
   const limit = 256 - 256 % poolLength;
   const chars = [];
+  if (charsets) {
+    for (const charset of charsets) {
+      chars.push(pickRandomChar(charset));
+    }
+  }
   while (chars.length < length) {
     const remaining = length - chars.length;
     const bufferSize = remaining * 2;
@@ -29,6 +79,9 @@ function generateSingle(length, pool) {
       }
     }
   }
+  if (charsets) {
+    cryptoShuffle(chars);
+  }
   return chars.join("");
 }
 function validateOptions(options) {
@@ -44,6 +97,14 @@ function validateOptions(options) {
   if (!options.uppercase && !options.lowercase && !options.numbers && !options.symbols) {
     throw new Error("\uCD5C\uC18C 1\uAC1C \uC774\uC0C1\uC758 \uBB38\uC790\uC14B\uC744 \uD3EC\uD568\uD574\uC57C \uD569\uB2C8\uB2E4");
   }
+  if (options.ensure) {
+    const activeCount = (options.uppercase ? 1 : 0) + (options.lowercase ? 1 : 0) + (options.numbers ? 1 : 0) + (options.symbols ? 1 : 0);
+    if (options.length < activeCount) {
+      throw new Error(
+        `ensure \uBAA8\uB4DC\uC5D0\uC11C\uB294 \uAE38\uC774\uAC00 \uD65C\uC131 \uBB38\uC790\uC14B \uC218(${activeCount}) \uC774\uC0C1\uC774\uC5B4\uC57C \uD569\uB2C8\uB2E4`
+      );
+    }
+  }
 }
 function generatePassword(options) {
   const resolved = {
@@ -52,13 +113,20 @@ function generatePassword(options) {
     uppercase: options?.uppercase ?? true,
     lowercase: options?.lowercase ?? true,
     numbers: options?.numbers ?? true,
-    symbols: options?.symbols ?? true
+    symbols: options?.symbols ?? true,
+    ensure: options?.ensure ?? false
   };
   validateOptions(resolved);
-  const pool = buildPool(resolved);
+  const { pool, charsets } = buildPool(resolved);
   const passwords = [];
   for (let i = 0; i < resolved.count; i++) {
-    passwords.push(generateSingle(resolved.length, pool));
+    passwords.push(
+      generateSingle(
+        resolved.length,
+        pool,
+        resolved.ensure ? charsets : void 0
+      )
+    );
   }
   return passwords;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lockly",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Cryptographically secure random password generator CLI",
   "license": "MIT",
   "type": "module",