🧂 Password Hashing with bcrypt

Why Never Store Plaintext

Imagine your app's users table leaks — through a SQL injection, a misconfigured backup, or a stolen laptop. If passwords are stored as plaintext, the attacker instantly owns every account. Worse, because people reuse passwords, they now own those users' email, banking, and social accounts too. Your one breach becomes hundreds of breaches.

The fix is hashing: a one-way transformation. You never store the password — you store a fingerprint of it. When a user logs in, you hash what they typed and compare fingerprints. Done right, even the people running the server can't recover the original password.

The Evolution of Password Storage

Password storage improved in stages, each fixing the previous weakness. Understanding the ladder explains exactly why bcrypt sits at the top.

1. Plaintext — the cardinal sin

// NEVER do this. The breach IS the password list.
const user = { email: 'a@b.com', password: 'hunter2' };

2. Fast hashing — a half-measure

const crypto = require('crypto');
// MD5 / SHA-256 are FAST — great for file checksums, terrible for passwords.
const hash = crypto.createHash('sha256').update('hunter2').digest('hex');
// Problems:
//  - Attackers compute BILLIONS of these per second on a GPU.
//  - Precomputed "rainbow tables" reverse common passwords instantly.
//  - Identical passwords produce identical hashes -> patterns leak.

3. Salted hashing — closer

A salt is a unique random value mixed into each password before hashing. Now two users with the password hunter2 get different hashes, and prebuilt rainbow tables are useless. But plain salted SHA is still too fast to compute — a motivated attacker just brute-forces each salted hash directly.

4. Adaptive hashing — the answer

Adaptive (deliberately slow) hash functions add a tunable cost factor. They bake in salting and make each hash take a measurable amount of time — fast enough for one login, painfully slow for billions of guesses. The main choices are bcrypt, argon2, and PBKDF2. This course uses bcrypt; argon2id is an excellent modern alternative.

Salt & the Storage Model

Here's the mental model for what actually gets saved. bcrypt generates a random salt, combines it with the password, runs the slow hash, and stores the salt inside the resulting string — so you never manage the salt separately.

Anatomy of a bcrypt hash

A stored bcrypt hash is a single self-describing string. Every part you need to verify a password later is embedded in it:

// $2b$12$eImiTXuWVxfM37uY4JANjQ.9Tq0aFq7uS8mQ0oX0k8n1a2b3c4d5e
//  |  |  |                     |
//  |  |  |                     +-- 31-char digest (the actual hash)
//  |  |  +------------------------ 22-char salt (base64)
//  |  +--------------------------- cost factor: 12  (2^12 rounds)
//  +------------------------------ algorithm id: 2b (bcrypt)

Because the algorithm, cost, and salt all travel with the digest, bcrypt.compare can re-derive the hash from a plaintext guess with no extra bookkeeping on your side.

Understanding bcrypt

bcrypt is a password-hashing function based on the Blowfish cipher, designed specifically for storing passwords. Its defining feature is the cost factor (also called work factor or rounds).

The cost factor

• The cost is an exponent: cost n means 2^n internal rounds.
• Each +1 in cost roughly doubles the time to hash.
• Slow is the point: a legitimate login can afford ~250 ms; an attacker guessing billions cannot.
• As hardware gets faster, you raise the cost to keep pace.

*Times vary wildly by hardware — always benchmark on your production server and aim for roughly 250 ms.

Using bcrypt in Node.js

Install the maintained native package. (bcryptjs is a pure-JS fallback with the same API if you can't build native modules.)

// npm install bcrypt

Hashing a password

Always use the async API in a web server — the sync version blocks the event loop for the whole ~250 ms, freezing every other request.

const bcrypt = require('bcrypt');

const SALT_ROUNDS = 12; // cost factor

async function hashPassword(plainPassword) {
  // bcrypt.hash generates a salt internally and embeds it in the output.
  const hash = await bcrypt.hash(plainPassword, SALT_ROUNDS);
  return hash; // e.g. "$2b$12$eImiTX...c4d5e"  -> store THIS
}

// Example
(async () => {
  const stored = await hashPassword('Str0ng!Pass');
  console.log(stored);
  // $2b$12$eImiTXuWVxfM37uY4JANjQ.9Tq0aFq7uS8mQ0oX0k8n1a2b3c4d5e
})();

Verifying a password

bcrypt.compare extracts the salt and cost from the stored hash, re-hashes the guess, and compares in constant time (resisting timing attacks). You never handle the salt yourself.

async function verifyPassword(plainPassword, storedHash) {
  // Returns true only if plainPassword hashes to storedHash.
  return bcrypt.compare(plainPassword, storedHash);
}

(async () => {
  const stored = await bcrypt.hash('Str0ng!Pass', 12);
  console.log(await verifyPassword('Str0ng!Pass', stored)); // true
  console.log(await verifyPassword('wrong-guess', stored));  // false
})();

true
false

Integrating with a User Model

In a real app you hash once, at the point a password is set, and verify on login. Here's a clean pattern with Mongoose that hashes in a pre('save') hook and never returns the hash to callers.

const mongoose = require('mongoose');
const bcrypt = require('bcrypt');

const SALT_ROUNDS = 12;

const userSchema = new mongoose.Schema({
  email: {
    type: String,
    required: true,
    unique: true,
    lowercase: true,   // normalize before storing
    trim: true,
  },
  password: {
    type: String,
    required: true,
    select: false,     // never returned by default queries
  },
});

// Hash the password whenever it is set or changed.
userSchema.pre('save', async function (next) {
  if (!this.isModified('password')) return next(); // skip if unchanged
  this.password = await bcrypt.hash(this.password, SALT_ROUNDS);
  next();
});

// Instance method to verify a login attempt.
userSchema.methods.verifyPassword = function (candidate) {
  return bcrypt.compare(candidate, this.password);
};

module.exports = mongoose.model('User', userSchema);

Using it on login — note the generic error and the explicit re-selection of the hidden password field:

async function login(req, res) {
  const email = String(req.body.email || '').toLowerCase().trim();
  const { password } = req.body;

  // Must re-select password because the schema hides it.
  const user = await User.findOne({ email }).select('+password');

  // Same generic message whether the email or the password was wrong,
  // so attackers cannot tell which emails are registered (no enumeration).
  const ok = user && (await user.verifyPassword(password));
  if (!ok) {
    return res.status(401).json({ message: 'Invalid credentials' });
  }

  // Success: issue a session or token here. NEVER return user.password.
  res.json({ message: 'Logged in' });
}

Practice & Quiz

const bcrypt = require('bcrypt');

async function register(password) {
    // TODO: return the bcrypt hash of password (cost 12)
}

async function checkLogin(password, storedHash) {
    // TODO: return true if password matches storedHash
}

const bcrypt = require('bcrypt');

async function register(password) {
    return bcrypt.hash(password, 12);
}

async function checkLogin(password, storedHash) {
    return bcrypt.compare(password, storedHash);
}

Best Practices & Pitfalls

✅ Do

• Use bcrypt (or argon2id) with a cost factor around 12
• Use the async API (bcrypt.hash / bcrypt.compare) so you don't block the event loop
• Let bcrypt generate the salt for you — it's embedded in the output
• Hash once when the password is set (e.g. a pre('save') hook)
• Store passwords with select: false and strip them from responses and logs
• Enforce a minimum password strength before hashing, and normalize email

❌ Don't

• Store plaintext, or "encrypt" passwords reversibly
• Use fast hashes (MD5/SHA-1/SHA-256) alone for passwords
• Reuse one global salt for every user — salts must be unique
• Roll your own hash-and-compare with === instead of bcrypt.compare
• Return a different error for "no such user" vs "wrong password" (enables enumeration)
• Log the hash, or send it in an API response

Summary

📚 Additional Resources

• OWASP — Password Storage Cheat Sheet
• bcrypt — npm package
• argon2 — npm package
• MDN — Web security

🚀 What's Next?

You can now store and verify credentials safely. Next you'll wire this into a complete User Registration Flow — validating and normalizing input, checking for duplicate accounts, hashing on the way in, and returning safe responses without ever exposing sensitive data.