# bcrypt.js — Industry-Standard Password Hashing for Node.js

> A native C++ bcrypt implementation for Node.js providing secure password hashing and verification.

## Install

Save in your project root:

# bcrypt.js — Industry-Standard Password Hashing for Node.js

## Quick Use
```bash
npm install bcrypt
```
```js
import bcrypt from 'bcrypt';
const saltRounds = 10;
const hash = await bcrypt.hash('myPassword', saltRounds);
const match = await bcrypt.compare('myPassword', hash); // => true
```

## Introduction
bcrypt for Node.js is a native addon that implements the bcrypt password hashing algorithm. bcrypt is deliberately slow and computationally expensive, making brute-force attacks impractical. This library is the standard choice for hashing and verifying user passwords in Node.js applications and has been battle-tested across thousands of production systems.

## What bcrypt Does
- Hashes passwords using the bcrypt algorithm with configurable cost factor
- Verifies plaintext passwords against stored bcrypt hashes
- Generates cryptographically secure random salts automatically
- Provides both async (Promise-based) and sync APIs
- Uses a native C++ binding for optimal performance

## Architecture Overview
The library wraps the OpenBSD bcrypt reference implementation in a C++ Node.js native addon via node-addon-api. When hashing, it generates a random 16-byte salt, applies the Blowfish-based key derivation function for 2^cost rounds, and produces a 60-character hash string encoding the algorithm version, cost factor, salt, and hash. The async API offloads the CPU-intensive hashing to a worker thread pool so the Node.js event loop is not blocked.

## Self-Hosting & Configuration
- Install via npm: `npm install bcrypt` (requires a C++ compiler for native build)
- Set the cost factor (salt rounds) based on your security needs: 10 is a common default
- Use the async API in web servers to avoid blocking: `await bcrypt.hash(password, 10)`
- For environments without native compilation, use the pure JS fallback: `npm install bcryptjs`
- The output hash string is self-describing, so no separate salt storage is needed

## Key Features
- Adaptive cost factor: increase rounds as hardware gets faster
- Automatic salt generation eliminates manual salt management
- Async API prevents event loop blocking during hashing
- Self-contained hash strings include algorithm version, cost, and salt
- Native C++ implementation for maximum throughput

## Comparison with Similar Tools
- **bcryptjs** — pure JavaScript implementation; slower but requires no native compilation
- **argon2** — newer algorithm (PHC winner); stronger but less universally supported
- **scrypt (crypto.scrypt)** — built into Node.js crypto; bcrypt has wider ecosystem adoption
- **PBKDF2** — available in Node.js crypto; bcrypt is more resistant to GPU-based attacks

## FAQ
**Q: What salt rounds value should I use?**
A: Start with 10. Each increment doubles the computation time. Benchmark on your hardware and aim for 250ms or more per hash.

**Q: Do I need to store the salt separately?**
A: No. The bcrypt hash string embeds the salt, algorithm version, and cost factor. Store only the hash.

**Q: Why does installation fail on some systems?**
A: bcrypt requires a C++ compiler and Python for node-gyp. If native builds are not possible, use the pure JavaScript bcryptjs package instead.

**Q: Is bcrypt still secure in 2025?**
A: Yes. With an appropriate cost factor (12+), bcrypt remains resistant to brute-force attacks. Argon2 is the newer standard but bcrypt is still widely trusted.

## Sources
- https://github.com/kelektiv/node.bcrypt.js
- https://github.com/kelektiv/node.bcrypt.js/blob/master/README.md

---
Source: https://tokrepo.com/en/workflows/asset-6738c344
Author: AI Open Source