@systemix/password

@systemix/password is a customizable, lightweight, and cryptographically secure password generator for JavaScript and TypeScript. Built for maximum security, it relies entirely on Node.js built-in crypto modules, ensuring zero external dependencies and a low supply-chain risk profile.

Features

• Secure: Uses crypto.getRandomValues() with bias-free distribution for maximum security.
• Character Guarantees: Ensure a minimum number of uppercase, lowercase, numbers, or symbols.
• Custom Charsets: Pass your own character sets for generation.
• Entropy Calculation: Built-in utility to calculate technical password entropy.
• Zero Dependencies: Purely built with Node.js built-ins.
• TypeScript Ready: Full type definitions included.

Installation

pnpm add @systemix/password

or

npm install @systemix/password

From GitHub Packages (add to .npmrc: @shahadathhs:registry=https://npm.pkg.github.com):

pnpm add @shahadathhs/password

Use @shahadathhs/password in imports.

Usage

Simple Example

import { generatePassword } from '@systemix/password';

const password = generatePassword({
  length: 16,
  useNumbers: true,
  useSymbols: true,
});

console.log(password); // Example: "Z#kM@4p*J!h2X&b7"

Guarantees and Character Sets

const securePass = generatePassword({
  length: 12,
  minNumbers: 2,
  minSymbols: 2,
  useUppercase: true,
  customSymbols: '!@#$%^&*', // Use specific symbols only
});

Entropy Calculation

import { calculatePasswordEntropy } from '@systemix/password';

const entropy = calculatePasswordEntropy(12, 62); // length, charset size
console.log(`Entropy: ${entropy} bits`);

API Reference

generatePassword(props?: PasswordProps): string | string[]

| Property | Type | Default | Description | | :------------------------- | :-------- | :-------- | :------------------------------------ | | length | number | 12 | Password length (1 to 100). | | useNumbers | boolean | true | Include 0-9. | | useUppercase | boolean | true | Include A-Z. | | useLowercase | boolean | true | Include a-z. | | useSymbols | boolean | false | Include special characters. | | minNumbers | number | 0 | Minimum numbers to include. | | minUppercase | number | 0 | Minimum uppercase letters to include. | | minLowercase | number | 0 | Minimum lowercase letters to include. | | minSymbols | number | 0 | Minimum symbols to include. | | customNumbers | string | 0-9 | Custom number set. | | customUppercase | string | A-Z | Custom uppercase set. | | customLowercase | string | a-z | Custom lowercase set. | | customSymbols | string | Special | Custom symbol set. | | excludeSimilarCharacters | boolean | false | Exclude visually similar characters. | | exclude | string | "" | Specific characters to exclude. | | count | number | 1 | Number of passwords to generate. |

calculatePasswordEntropy(length: number, charsetSize: number): number

Calculates the theoretical entropy of a password (H = L * log2(N)).

License

MIT © shahadathhs