securemix

Cryptographically Secure Password Generation & Mutation — for Node.js, React, Vue, and the Browser

Built by Innoartive Labs · Zero Dependencies

What is securemix?

securemix is a production-grade developer security toolkit that works universally across Node.js, React, Vue, and all modern browsers. It generates cryptographically secure passwords, mutates weak strings into hardened credentials, evaluates password strength, and supports template-based generation — all with zero runtime dependencies.

In browser environments it uses the native Web Crypto API (crypto.getRandomValues). In Node.js it falls back to the built-in crypto module. The same API, everywhere.

It is not a toy library. It was built for:

• React & Vue frontends that need client-side secure password generation without a server round-trip
• Authentication systems generating initial credentials, session tokens, or reset links
• SaaS platforms provisioning per-user API keys or secrets
• DevOps pipelines generating secrets for staging environments or CI/CD variables
• CLI tooling where developers need on-demand secure credentials at the terminal
• Developers who want to harden user-provided passwords without replacing them

Why You Should Switch to securemix

Most Node.js packages handle password generation carelessly. Here is what they get wrong, and what securemix does differently.

1. Most Packages Use Math.random(). That Is a Security Vulnerability.

Math.random() is a Pseudorandom Number Generator (PRNG). It is seeded deterministically and its output can be predicted given enough samples. In a 2022 analysis, a V8 engine PRNG was fully reconstructed from just 5 consecutive outputs.

Any password generated with Math.random() is not cryptographically secure.

securemix uses the Web Crypto API (crypto.getRandomValues) in browsers and crypto.randomBytes() in Node.js — both are interfaces to the operating system's entropy pool (/dev/urandom on Linux/macOS, BCryptGenRandom on Windows). This is the same source used by TLS handshakes and SSH key generation. It cannot be predicted or reconstructed.

2. Most Packages Have Modulo Bias. Your Passwords Are Not Truly Uniform.

When you do charset[randomByte % charset.length], you introduce a statistical bias. Characters at the start of the charset appear slightly more often than characters at the end. For a charset of 90 characters (typical for complex passwords), this creates a measurable skew in the character distribution.

securemix uses rejection sampling — values that fall outside a multiple of the charset length are discarded and a new random byte is requested. Every character in the charset has an exactly equal and independent probability of selection. This is the mathematically correct approach.

3. Most Packages Have No Anti-Pattern Intelligence.

A password like Abcdefg1! passes most validators. It has uppercase, lowercase, a number, and a symbol. But it contains a sequential run (Abcdef), which is trivially crackable with rule-based attacks in tools like Hashcat.

securemix detects and rejects:

• Sequential alphabetical runs (abc, xyz)
• Sequential numeric runs (123, 456)
• Reverse sequences (cba, 321)
• Common keyboard walk patterns (qwerty, asdf)
• Repeated character blocks (aaaa, 1111)
• Known weak strings (password, admin, root, login)

If a generated password matches any of these patterns, it is automatically discarded and regenerated. You never receive a predictable output.

4. No Other Package Has a Mutation Engine.

Most developers face a real-world problem: users choose weak passwords. Forcing a random 20-character string on them creates friction and support tickets. Generating one and emailing it is fine once, but users will immediately change it to a weaker one.

securemix solves this with enhancePassword() — a Password Mutation Engine that takes any string (even a weak, memorable one) and transforms it into a cryptographically hardened credential. The mutation uses ASCII code mirroring (not clichéd leet-speak), reflecting each character to its structural opposite within the printable ASCII range.

This is unique to securemix.

5. Zero Dependencies. No Supply Chain Risk.

Every dependency you add is a potential attack surface. In 2021, the ua-parser-js package was compromised. In 2022, node-ipc contained a deliberate destructive payload. In 2023, xz-utils was backdoored.

securemix has no runtime dependencies. Installing it adds one package to your node_modules. There is no transitive dependency chain. The entire source is auditable in a single file.

Installation

npm install securemix

# Or add to your project
npm install --save securemix

Quick Start

Node.js / CommonJS:

const { generatePassword, enhancePassword, evaluatePassword, generateFromPattern } = require('securemix');

// Generate a 16-character cryptographically secure password
const password = generatePassword(16);
// → e.g., "K#7{mP2@zX!qR4^v"

// Take a user's weak password and harden it
const hardened = enhancePassword("mydog123");
// → e.g., "N>Sxp@:!B#N"

// Analyze any password for security risks
const analysis = evaluatePassword("p@ssword123");
// → { score: 1, strength: "weak", feedback: "..." }

// Generate a password matching a specific format
const serial = generateFromPattern("AA-9999-AA");
// → "XK-4821-ZP"

React (ESM):

import { generatePassword, evaluatePassword } from 'securemix';

function PasswordGenerator() {
  const [password, setPassword] = React.useState('');

  const generate = () => {
    const pwd = generatePassword({ length: 16, symbols: true });
    setPassword(pwd);
  };

  return (
    <div>
      <button onClick={generate}>Generate Password</button>
      <p>{password}</p>
    </div>
  );
}

Vue 3 (ESM):

<script setup>
import { ref } from 'vue';
import { generatePassword } from 'securemix';

const password = ref('');
const generate = () => {
  password.value = generatePassword({ length: 16, symbols: true });
};
</script>

<template>
  <button @click="generate">Generate Password</button>
  <p>{{ password }}</p>
</template>

CLI Usage

securemix ships with a built-in CLI. No global install required — use it anywhere via npx:

# Generate a standard secure password (12 characters)
npx securemix generate

# Control length and character sets explicitly
npx securemix generate --length 20 --symbols --numbers --uppercase

# Generate a batch of 10 passwords for provisioning
npx securemix generate --batch 10

# Exclude visually ambiguous characters (O, 0, l, I, 1) — ideal for printed credentials
npx securemix generate --length 16 --exclude-similar

# Transform a weak password into a strong one
npx securemix enhance "sunshine99"

# Get a structured strength evaluation in JSON
npx securemix evaluate "P@ssw0rd!"

# Pipe a password directly into a config file
npx securemix generate --json | jq '.result' >> .env

CLI Flag Reference

| Flag | Applies To | Description | Default | | :--- | :--- | :--- | :--- | | --length <n> | generate | Password character length | 12 | | --symbols | generate | Include special characters (!@#$%...) | false | | --numbers | generate | Include numeric digits | false | | --uppercase | generate | Include uppercase letters | false | | --exclude-similar | generate | Remove ambiguous characters (O, 0, l, I, 1) | false | | --batch <n> | generate | Output n passwords, one per line | 1 | | --json | generate | Wrap output in a JSON object | false |

Default behavior: When no charset flags are provided, generate defaults to full complexity (uppercase + numbers + symbols) for maximum security.

API Reference

generatePassword(length?, options?) → string | string[]

Generates a cryptographically secure password using crypto.randomBytes() with rejection sampling and Fisher-Yates shuffle.

const { generatePassword } = require('securemix');

// Positional length
const p1 = generatePassword(16);

// Options object
const p2 = generatePassword({
  length: 24,
  symbols: true,
  numbers: true,
  uppercase: true,
  lowercase: true,
  excludeSimilar: false,
  customCharset: ''  // Override all charsets with your own string
});

// Batch — returns string[]
const batch = generatePassword({ length: 12, batch: 5 });
// → ['...', '...', '...', '...', '...']

// Legacy call signature (v1 compatible)
const legacy = require('securemix')(12, { excludeSimilar: true });

Options:

| Option | Type | Default | Description | | :--- | :--- | :--- | :--- | | length | number | 12 | Total password length. Minimum: 4. | | symbols | boolean | true | Include special characters. | | numbers | boolean | true | Include digits 0–9. | | uppercase | boolean | true | Include A–Z. | | lowercase | boolean | true | Include a–z. | | excludeSimilar | boolean | false | Remove O, 0, l, I, 1 from charset. | | customCharset | string | "" | Use only these characters. Overrides all other charset flags. | | batch | number | 1 | When > 1, returns an array of passwords. |

enhancePassword(password) → string

The Mutation Engine. Takes any string — even a weak, guessable one — and transforms it into a hardened credential using ASCII code mirroring and cryptographic symbol injection.

This is what makes securemix stand apart from every other package in this space.

How the mutation works:

1. Strategic Capitalization — The first character is forced to uppercase. Additional characters are randomly uppercased using crypto.randomBytes().
2. ASCII Mirror Mutation — Each character is reflected within the printable ASCII range (33–126) using the formula charCode → 159 - charCode. This maps A (65) to Z̃ (94), a (97) to > (62), 1 (49) to ~ (126), etc. The result is structurally unpredictable from the source character.
3. Symbol Injection — A cryptographically random symbol is inserted at a random position.
4. Entropy Padding — Two additional characters (one symbol + one uppercase) are appended to ensure minimum entropy compliance.

const { enhancePassword } = require('securemix');

const strong = enhancePassword("mydog123");
// Input:  "mydog123"
// Output: e.g., "N>Sxp!:B#N" (different every call — crypto random)

// Chain with evaluatePassword to verify the result
const { enhancePassword, evaluatePassword } = require('securemix');
const hardened = enhancePassword("sunshine99");
const strength = evaluatePassword(hardened);
console.log(strength.strength); // → "strong"

Important: The mutation is non-deterministic. The same input will produce a different output on every call. The original string is transformed, not stored.

generateFromPattern(pattern) → string

Generates passwords that conform to a structural format. Useful for generating region codes, license keys, employee IDs, or API key prefixes.

Token map:

| Token | Generates | | :--- | :--- | | A | A random uppercase letter (A–Z) | | a | A random lowercase letter (a–z) | | 9 | A random digit (0–9) | | @ | A random symbol from the special charset | | (any other char) | Passed through as-is |

const { generateFromPattern } = require('securemix');

generateFromPattern("AA-9999-AA");    // → "XK-4821-ZP"
generateFromPattern("9999-AAAA-9a"); // → "3847-QRTZ-6f"
generateFromPattern("@Aa9@Aa9");     // → "#Gm4!Bz7"
generateFromPattern("INV-9999-AA");  // → "INV-5820-TK"  (literal "INV-" preserved)

evaluatePassword(password) → EvaluationResult

Analyzes a password and returns a structured security report with a numeric score, strength label, and actionable feedback.

const { evaluatePassword } = require('securemix');

evaluatePassword("abc");
// { score: 0, strength: "weak", feedback: "Try a longer password. Use a mix of letters, numbers, and symbols." }

evaluatePassword("Sunshine2024");
// { score: 2, strength: "good", feedback: "Contains common patterns or sequential characters." }

evaluatePassword("K#7{mP2@zX!qR4^v");
// { score: 4, strength: "strong", feedback: "Perfectly secure!" }

Scoring breakdown:

| Criterion | Points | | :--- | :--- | | Length ≥ 8 characters | +1 | | Length ≥ 12 characters | +1 | | Contains ≥ 3 character types (upper, lower, digit, symbol) | +1 | | Contains all 4 character types | +1 | | Contains sequential runs, keyboard walks, or common patterns | −2 |

Result object:

{
  score: 0 | 1 | 2 | 3 | 4,
  strength: "weak" | "fair" | "good" | "strong",
  feedback: string
}

TypeScript Support

securemix ships complete TypeScript definitions with no additional @types packages required.

import {
  generatePassword,
  enhancePassword,
  generateFromPattern,
  evaluatePassword,
  PasswordOptions,
  EvaluationResult
} from 'securemix';

const token: string = generatePassword({ length: 32, symbols: true });
const batch: string[] = generatePassword({ length: 16, batch: 10 }) as string[];
const hardened: string = enhancePassword("mydog123");
const report: EvaluationResult = evaluatePassword(hardened);
const serial: string = generateFromPattern("AA-9999-@@");

ESM import is also supported:

import securemix from 'securemix';
// or
import { generatePassword } from 'securemix';

Real-World Use Cases

Generating a user's initial password on account creation:

const { generatePassword, evaluatePassword } = require('securemix');

function provisionUser(email) {
  const tempPassword = generatePassword({ length: 16, symbols: true });
  const strength = evaluatePassword(tempPassword);
  // strength.strength will always be "good" or "strong"
  sendWelcomeEmail(email, tempPassword);
}

Hardening a password a user chose themselves:

const { enhancePassword } = require('securemix');

app.post('/register', (req, res) => {
  const rawPassword = req.body.password;
  const securePassword = enhancePassword(rawPassword);
  const hashed = bcrypt.hashSync(securePassword, 12);
  db.users.create({ email: req.body.email, password: hashed });
});

Generating API keys with a readable format:

const { generateFromPattern } = require('securemix');

const apiKey = generateFromPattern("sk-9999-AAAA-9999-AAAA");
// → "sk-3874-XZMQ-5102-BVKP"

Batch-provisioning secrets for a deployment:

npx securemix generate --batch 5 --length 32 --json

Evaluating passwords before storing them:

const { evaluatePassword } = require('securemix');

function validatePasswordPolicy(pwd) {
  const { score, strength, feedback } = evaluatePassword(pwd);
  if (score < 3) throw new Error(`Password too weak: ${feedback}`);
}

Security Architecture

securemix is designed for environments where cryptographic correctness is non-negotiable.

Entropy Source All randomness originates from the Web Crypto API in browsers (globalThis.crypto.getRandomValues) and from crypto.randomBytes() in Node.js. The library auto-detects the environment at runtime — no configuration needed. Both sources call the OS kernel's CSPRNG: /dev/urandom (ChaCha20-based) on Linux/macOS and BCryptGenRandom on Windows. Both are conditioned, seeded entropy sources that are safe for cryptographic key material.

Uniform Character Selection securemix computes the largest multiple of the charset length that fits within 256 and rejects any byte value ≥ that boundary before taking modulo. This ensures every character has an identical 1/n probability of selection, eliminating the well-known modulo bias that affects naive implementations.

Fisher-Yates Shuffle After selecting required characters from each charset (to ensure composition), the full array is shuffled using a cryptographically seeded Fisher-Yates algorithm. This prevents first-character bias, where composition-enforcement logic would always place uppercase at index 0, lowercase at index 1, etc.

Anti-Pattern Regeneration A final pass validates the generated output against a list of known-weak patterns. If any weakness is detected, the password is discarded and regeneration begins from scratch. This is not a filter — it is a full regeneration loop.

ASCII Mirror Mutation The mutation engine maps each character c to String.fromCharCode(159 - c.charCodeAt(0)) within the printable ASCII range 33–126. This creates a non-guessable transformation that preserves the length and structure of the input string while making the output completely unpredictable from the source.

Comparison

| Feature | securemix | Most other packages | | :--- | :---: | :---: | | Browser / Frontend compatible | ✅ | ❌ | | Uses CSPRNG (Web Crypto / crypto.randomBytes) | ✅ | ❌ (many use Math.random()) | | Works in React & Vue (ESM) | ✅ | ❌ | | Rejection sampling (no modulo bias) | ✅ | ❌ | | Anti-pattern engine | ✅ | ❌ | | Password Mutation Engine | ✅ | ❌ | | Pattern-based generator | ✅ | Rarely | | Strength evaluator | ✅ | Rarely | | CLI included | ✅ | Rarely | | TypeScript definitions | ✅ | Sometimes | | Zero runtime dependencies | ✅ | Sometimes |

Changelog

See CHANGELOG.md for the full version history.

Author

Innoartive Labs Crafting professional-grade developer tools. github.com/Innoartive-Labs

License

MIT © Innoartive Labs