lockly 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 lockly contributors
+
+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,128 @@
+# lockly
+
+Cryptographically secure password generator CLI.
+
+Generates unpredictable random passwords instantly using `node:crypto.getRandomValues()`.
+
+## Features
+
+- **Cryptographically secure** — CSPRNG via `node:crypto`
+- **Fast** — under 50ms response time
+- **Customizable** — length, character sets, count
+- **Pipe-friendly** — clean stdout output, no ANSI colors
+- **Zero install** — run instantly with `npx`
+
+## Install
+
+```bash
+# Run instantly with npx (recommended)
+npx lockly
+
+# Or install globally
+npm install -g lockly
+```
+
+## Usage
+
+### Basic
+
+```bash
+# Default: generate a 16-character password
+lockly
+
+# Set length (32 characters)
+lockly -l 32
+lockly --length 32
+
+# Generate multiple passwords (5)
+lockly -c 5
+lockly --count 5
+```
+
+### Character set filtering
+
+```bash
+# Exclude symbols
+lockly --no-symbols
+
+# Digits only (PIN)
+lockly --no-uppercase --no-lowercase --no-symbols -l 6
+
+# Uppercase and digits only
+lockly --no-lowercase --no-symbols
+```
+
+### Piping
+
+```bash
+# Copy to clipboard (macOS)
+lockly | pbcopy
+
+# Copy to clipboard (Linux)
+lockly | xclip -selection clipboard
+
+# Copy to clipboard (Windows PowerShell)
+lockly | Set-Clipboard
+
+# Save to file
+lockly -c 10 -l 32 > passwords.txt
+
+# Set as environment variable
+export DB_PASSWORD=$(lockly -l 24 --no-symbols)
+```
+
+## Options
+
+| Option | Description | Default | Range |
+|--------|-------------|---------|-------|
+| `-l, --length <number>` | Password length | 16 | 1–1024 |
+| `-c, --count <number>` | Number of passwords | 1 | 1+ |
+| `--no-uppercase` | Exclude uppercase (A-Z) | included | - |
+| `--no-lowercase` | Exclude lowercase (a-z) | included | - |
+| `--no-numbers` | Exclude digits (0-9) | included | - |
+| `--no-symbols` | Exclude symbols | included | - |
+| `-V, --version` | Show version | - | - |
+| `-h, --help` | Show help | - | - |
+
+## Security
+
+- **CSPRNG**: Uses `node:crypto.getRandomValues()` 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
+
+### Security tips
+
+- Store generated passwords immediately in a secure location (e.g. password manager)
+- Use piping to avoid passwords appearing in terminal history
+- Use `-l 32` or longer for high-security purposes (root accounts, financial services, etc.)
+
+## Programmatic API
+
+Use lockly as a library in your TypeScript/JavaScript project.
+
+```typescript
+import { generatePassword } from 'lockly';
+
+// Default usage
+const passwords = generatePassword();
+console.log(passwords[0]); // 16-character password
+
+// With options
+const customPasswords = generatePassword({
+  length: 32,
+  count: 5,
+  uppercase: true,
+  lowercase: true,
+  numbers: true,
+  symbols: false
+});
+```
+
+## Requirements
+
+- Node.js 20+
+
+## License
+
+MIT

package/dist/cli.js

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { readFileSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+import { getRandomValues } from '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;
+}
+function generateSingle(length2, pool) {
+  const poolLength = pool.length;
+  const limit = 256 - 256 % poolLength;
+  const chars = [];
+  while (chars.length < length2) {
+    const remaining = length2 - chars.length;
+    const bufferSize = remaining * 2;
+    const randomBytes = new Uint8Array(bufferSize);
+    getRandomValues(randomBytes);
+    for (let i = 0; i < randomBytes.length && chars.length < length2; i++) {
+      const byte = randomBytes[i];
+      if (byte < limit) {
+        chars.push(pool[byte % poolLength]);
+      }
+    }
+  }
+  return chars.join("");
+}
+function validateOptions(options2) {
+  if (!Number.isInteger(options2.length) || options2.length < 1) {
+    throw new Error("\uAE38\uC774\uB294 1~1024 \uC0AC\uC774\uC5EC\uC57C \uD569\uB2C8\uB2E4");
+  }
+  if (options2.length > 1024) {
+    throw new Error("\uAE38\uC774\uB294 1~1024 \uC0AC\uC774\uC5EC\uC57C \uD569\uB2C8\uB2E4");
+  }
+  if (!Number.isInteger(options2.count) || options2.count < 1) {
+    throw new Error("count\uB294 1 \uC774\uC0C1\uC774\uC5B4\uC57C \uD569\uB2C8\uB2E4");
+  }
+  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");
+  }
+}
+function generatePassword(options2) {
+  const resolved = {
+    length: options2?.length ?? 16,
+    count: options2?.count ?? 1,
+    uppercase: options2?.uppercase ?? true,
+    lowercase: options2?.lowercase ?? true,
+    numbers: options2?.numbers ?? true,
+    symbols: options2?.symbols ?? true
+  };
+  validateOptions(resolved);
+  const pool = buildPool(resolved);
+  const passwords = [];
+  for (let i = 0; i < resolved.count; i++) {
+    passwords.push(generateSingle(resolved.length, pool));
+  }
+  return passwords;
+}
+
+// src/cli.ts
+var __filename2 = fileURLToPath(import.meta.url);
+var __dirname2 = dirname(__filename2);
+var packageJsonPath = join(__dirname2, "../package.json");
+var packageJson = JSON.parse(readFileSync(packageJsonPath, "utf-8"));
+var version = packageJson.version;
+var program = new Command();
+program.name("lockly").description("Cryptographically secure random password generator").version(version, "-V, --version", "\uBC84\uC804 \uD45C\uC2DC").option(
+  "-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");
+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)) {
+  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);
+}

package/dist/index.cjs

@@ -0,0 +1,68 @@
+'use strict';
+
+var crypto = require('crypto');
+
+// src/generator.ts
+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;
+}
+function generateSingle(length, pool) {
+  const poolLength = pool.length;
+  const limit = 256 - 256 % poolLength;
+  const chars = [];
+  while (chars.length < length) {
+    const remaining = length - chars.length;
+    const bufferSize = remaining * 2;
+    const randomBytes = new Uint8Array(bufferSize);
+    crypto.getRandomValues(randomBytes);
+    for (let i = 0; i < randomBytes.length && chars.length < length; i++) {
+      const byte = randomBytes[i];
+      if (byte < limit) {
+        chars.push(pool[byte % poolLength]);
+      }
+    }
+  }
+  return chars.join("");
+}
+function validateOptions(options) {
+  if (!Number.isInteger(options.length) || options.length < 1) {
+    throw new Error("\uAE38\uC774\uB294 1~1024 \uC0AC\uC774\uC5EC\uC57C \uD569\uB2C8\uB2E4");
+  }
+  if (options.length > 1024) {
+    throw new Error("\uAE38\uC774\uB294 1~1024 \uC0AC\uC774\uC5EC\uC57C \uD569\uB2C8\uB2E4");
+  }
+  if (!Number.isInteger(options.count) || options.count < 1) {
+    throw new Error("count\uB294 1 \uC774\uC0C1\uC774\uC5B4\uC57C \uD569\uB2C8\uB2E4");
+  }
+  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");
+  }
+}
+function generatePassword(options) {
+  const resolved = {
+    length: options?.length ?? 16,
+    count: options?.count ?? 1,
+    uppercase: options?.uppercase ?? true,
+    lowercase: options?.lowercase ?? true,
+    numbers: options?.numbers ?? true,
+    symbols: options?.symbols ?? true
+  };
+  validateOptions(resolved);
+  const pool = buildPool(resolved);
+  const passwords = [];
+  for (let i = 0; i < resolved.count; i++) {
+    passwords.push(generateSingle(resolved.length, pool));
+  }
+  return passwords;
+}
+
+exports.generatePassword = generatePassword;

package/dist/index.d.cts

@@ -0,0 +1,64 @@
+/**
+ * Password generation core logic
+ * Uses node:crypto for cryptographically secure random generation
+ */
+/**
+ * Options for password generation
+ */
+interface GenerateOptions {
+    /**
+     * Password length (1-1024)
+     * @default 16
+     */
+    length?: number;
+    /**
+     * Number of passwords to generate
+     * @default 1
+     */
+    count?: number;
+    /**
+     * Include uppercase letters (A-Z)
+     * @default true
+     */
+    uppercase?: boolean;
+    /**
+     * Include lowercase letters (a-z)
+     * @default true
+     */
+    lowercase?: boolean;
+    /**
+     * Include numbers (0-9)
+     * @default true
+     */
+    numbers?: boolean;
+    /**
+     * Include special characters
+     * @default true
+     */
+    symbols?: boolean;
+}
+/**
+ * Generate one or more cryptographically secure random passwords.
+ *
+ * Uses `node:crypto.getRandomValues()` as the entropy source (REQ-1, NFR-1).
+ * Applies rejection sampling to avoid modulo bias when the character pool
+ * length is not a power of two.
+ *
+ * @param options - Password generation options. All fields are optional and
+ *   fall back to safe defaults (length=16, count=1, all charsets enabled).
+ * @returns An array of generated password strings. The array length equals
+ *   `options.count` (default 1).
+ * @throws {Error} If options validation fails (invalid length, count, or charsets)
+ *
+ * @example
+ * ```ts
+ * // Generate one 16-character password with all charsets
+ * const [pw] = generatePassword();
+ *
+ * // Generate three 32-character passwords without symbols
+ * const pws = generatePassword({ length: 32, count: 3, symbols: false });
+ * ```
+ */
+declare function generatePassword(options?: GenerateOptions): string[];
+
+export { type GenerateOptions, generatePassword };

package/dist/index.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Password generation core logic
+ * Uses node:crypto for cryptographically secure random generation
+ */
+/**
+ * Options for password generation
+ */
+interface GenerateOptions {
+    /**
+     * Password length (1-1024)
+     * @default 16
+     */
+    length?: number;
+    /**
+     * Number of passwords to generate
+     * @default 1
+     */
+    count?: number;
+    /**
+     * Include uppercase letters (A-Z)
+     * @default true
+     */
+    uppercase?: boolean;
+    /**
+     * Include lowercase letters (a-z)
+     * @default true
+     */
+    lowercase?: boolean;
+    /**
+     * Include numbers (0-9)
+     * @default true
+     */
+    numbers?: boolean;
+    /**
+     * Include special characters
+     * @default true
+     */
+    symbols?: boolean;
+}
+/**
+ * Generate one or more cryptographically secure random passwords.
+ *
+ * Uses `node:crypto.getRandomValues()` as the entropy source (REQ-1, NFR-1).
+ * Applies rejection sampling to avoid modulo bias when the character pool
+ * length is not a power of two.
+ *
+ * @param options - Password generation options. All fields are optional and
+ *   fall back to safe defaults (length=16, count=1, all charsets enabled).
+ * @returns An array of generated password strings. The array length equals
+ *   `options.count` (default 1).
+ * @throws {Error} If options validation fails (invalid length, count, or charsets)
+ *
+ * @example
+ * ```ts
+ * // Generate one 16-character password with all charsets
+ * const [pw] = generatePassword();
+ *
+ * // Generate three 32-character passwords without symbols
+ * const pws = generatePassword({ length: 32, count: 3, symbols: false });
+ * ```
+ */
+declare function generatePassword(options?: GenerateOptions): string[];
+
+export { type GenerateOptions, generatePassword };

package/dist/index.js

@@ -0,0 +1,66 @@
+import { getRandomValues } from 'crypto';
+
+// src/generator.ts
+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;
+}
+function generateSingle(length, pool) {
+  const poolLength = pool.length;
+  const limit = 256 - 256 % poolLength;
+  const chars = [];
+  while (chars.length < length) {
+    const remaining = length - chars.length;
+    const bufferSize = remaining * 2;
+    const randomBytes = new Uint8Array(bufferSize);
+    getRandomValues(randomBytes);
+    for (let i = 0; i < randomBytes.length && chars.length < length; i++) {
+      const byte = randomBytes[i];
+      if (byte < limit) {
+        chars.push(pool[byte % poolLength]);
+      }
+    }
+  }
+  return chars.join("");
+}
+function validateOptions(options) {
+  if (!Number.isInteger(options.length) || options.length < 1) {
+    throw new Error("\uAE38\uC774\uB294 1~1024 \uC0AC\uC774\uC5EC\uC57C \uD569\uB2C8\uB2E4");
+  }
+  if (options.length > 1024) {
+    throw new Error("\uAE38\uC774\uB294 1~1024 \uC0AC\uC774\uC5EC\uC57C \uD569\uB2C8\uB2E4");
+  }
+  if (!Number.isInteger(options.count) || options.count < 1) {
+    throw new Error("count\uB294 1 \uC774\uC0C1\uC774\uC5B4\uC57C \uD569\uB2C8\uB2E4");
+  }
+  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");
+  }
+}
+function generatePassword(options) {
+  const resolved = {
+    length: options?.length ?? 16,
+    count: options?.count ?? 1,
+    uppercase: options?.uppercase ?? true,
+    lowercase: options?.lowercase ?? true,
+    numbers: options?.numbers ?? true,
+    symbols: options?.symbols ?? true
+  };
+  validateOptions(resolved);
+  const pool = buildPool(resolved);
+  const passwords = [];
+  for (let i = 0; i < resolved.count; i++) {
+    passwords.push(generateSingle(resolved.length, pool));
+  }
+  return passwords;
+}
+
+export { generatePassword };

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "lockly",
+  "version": "0.1.0",
+  "description": "Cryptographically secure random password generator CLI",
+  "license": "MIT",
+  "type": "module",
+  "author": "Daniel Kyojun Ku <d@nielku.com>",
+  "keywords": [
+    "password",
+    "generator",
+    "cli",
+    "crypto",
+    "random",
+    "secure"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/kjunine/lockly.git"
+  },
+  "bugs": {
+    "url": "https://github.com/kjunine/lockly/issues"
+  },
+  "homepage": "https://github.com/kjunine/lockly#readme",
+  "bin": {
+    "lockly": "./dist/cli.js"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.cjs",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsup",
+    "lint": "eslint src tests",
+    "format": "prettier --write \"src/**/*.ts\" \"tests/**/*.ts\"",
+    "format:check": "prettier --check \"src/**/*.ts\" \"tests/**/*.ts\"",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "check": "pnpm run lint && pnpm run format:check && pnpm run build && pnpm run test"
+  },
+  "dependencies": {
+    "commander": "^14.0.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.0.0",
+    "@types/node": "^22.0.0",
+    "@vitest/coverage-v8": "^4.0.0",
+    "eslint": "^9.0.0",
+    "eslint-config-prettier": "^10.1.8",
+    "prettier": "^3.2.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.3.0",
+    "typescript-eslint": "^8.0.0",
+    "vitest": "^4.0.0"
+  },
+  "packageManager": "pnpm@10.29.3+sha512.498e1fb4cca5aa06c1dcf2611e6fafc50972ffe7189998c409e90de74566444298ffe43e6cd2acdc775ba1aa7cc5e092a8b7054c811ba8c5770f84693d33d2dc"
+}