bcryptjs

bcryptjs is a pure JavaScript implementation of the bcrypt password hashing algorithm with zero dependencies and TypeScript support. It provides both synchronous and asynchronous APIs for secure password hashing, salt generation, and verification. Compatible with the C++ bcrypt binding but runs entirely in JavaScript, making it suitable for both Node.js and browser environments.

Package Information

• Package Name: bcryptjs
• Package Type: npm
• Language: JavaScript with TypeScript definitions
• Installation: npm install bcryptjs

Core Imports

import bcrypt from "bcryptjs";

Named imports:

import { hash, compare, genSalt, hashSync, compareSync, genSaltSync } from "bcryptjs";

For CommonJS:

const bcrypt = require("bcryptjs");

Basic Usage

import bcrypt from "bcryptjs";

// Generate salt and hash password (async)
const salt = await bcrypt.genSalt(10);
const hash = await bcrypt.hash("myPassword", salt);

// Or auto-generate salt
const hash2 = await bcrypt.hash("myPassword", 10);

// Verify password
const isValid = await bcrypt.compare("myPassword", hash);
console.log(isValid); // true

// Synchronous operations
const saltSync = bcrypt.genSaltSync(10);
const hashSync = bcrypt.hashSync("myPassword", saltSync);
const isValidSync = bcrypt.compareSync("myPassword", hashSync);

Architecture

bcryptjs implements the bcrypt algorithm with these key components:

• Adaptive Hashing: Configurable iteration count (rounds) for future-proof security
• Salt Generation: Cryptographically secure random salt generation
• Dual APIs: Both synchronous and asynchronous operation modes
• Cross-platform: Pure JavaScript works in Node.js and browsers
• Type Safety: Full TypeScript definitions included
• Performance: Chunked async execution to prevent blocking

Capabilities

Password Hashing

Core password hashing functionality with both synchronous and asynchronous APIs. Supports auto-salt generation and custom salt input.

function hashSync(password: string, salt?: number | string): string;
function hash(password: string, salt: number | string): Promise<string>;
function hash(
  password: string,
  salt: number | string,
  callback?: Callback<string>,
  progressCallback?: ProgressCallback
): void;

Password Hashing

Password Verification

Password verification functions for comparing plain text passwords against bcrypt hashes.

function compareSync(password: string, hash: string): boolean;
function compare(password: string, hash: string): Promise<boolean>;
function compare(
  password: string,
  hash: string,
  callback?: Callback<boolean>,
  progressCallback?: ProgressCallback
): void;

Password Verification

Salt Generation

Cryptographically secure salt generation with configurable rounds for controlling computation cost.

function genSaltSync(rounds?: number): string;
function genSalt(rounds?: number): Promise<string>;
function genSalt(callback: Callback<string>): void;
function genSalt(rounds: number, callback: Callback<string>): void;

Salt Generation

Utility Functions

Helper functions for working with bcrypt hashes, password validation, and algorithm configuration.

function getRounds(hash: string): number;
function getSalt(hash: string): string;
function truncates(password: string): boolean;
function setRandomFallback(random: RandomFallback): void;
function encodeBase64(b: Readonly<ArrayLike<number>>, len: number): string;
function decodeBase64(s: string, len: number): number[];

Utility Functions

Types

type Callback<T> = (err: Error | null, result?: T) => void;
type ProgressCallback = (percentage: number) => void;
type RandomFallback = (length: number) => number[];

Security Considerations

• Maximum Input Length: Passwords are limited to 72 bytes when encoded as UTF-8
• Salt Generation: Uses Web Crypto API or Node.js crypto module for secure randomness
• Adaptive Security: Higher rounds increase computation time to resist brute-force attacks
• Timing Attacks: Implementation includes protections against timing-based attacks

Browser Compatibility

When using in browsers, the crypto import should be stubbed out using an import map or bundler configuration. bcryptjs will automatically use the Web Crypto API when available.

Command Line Interface

bcryptjs includes a command-line tool for hashing passwords directly from the terminal.

Installation and Usage:

# After installing bcryptjs package
npx bcrypt <password> [rounds|salt]

# Or if installed globally
bcrypt <password> [rounds|salt]

Examples:

# Hash password with default 10 rounds
bcrypt "myPassword"
# Output: $2b$10$N9qo8uLOickgx2ZMRZoMyeIjZAgcfl7p92ldGxad68LJZdL17lhWy

# Hash password with custom rounds
bcrypt "myPassword" 12
# Output: $2b$12$X8qo9uLOickgx2ZMRZoMyeYjZAgcfl7p92ldGxad68LJZdL17lhWy

# Hash password with pre-generated salt
bcrypt "myPassword" '$2b$10$N9qo8uLOickgx2ZMRZoMye'
# Output: $2b$10$N9qo8uLOickgx2ZMRZoMyeIjZAgcfl7p92ldGxad68LJZdL17lhWy

Parameters:

• <password>: The password to hash (required)
• [rounds|salt]: Optional parameter that can be:
  • A number (4-31): Number of rounds to use for salt generation
  • A salt string: Pre-generated salt to use for hashing

The CLI tool is useful for quick password hashing in scripts, testing, or administrative tasks.