📘 Password Handling: Hashing and Salting

🎯 Introduction

Welcome to this exciting tutorial on password handling in TypeScript! 🎉 In this guide, we’ll explore how to securely handle passwords using hashing and salting techniques.

You’ll discover how proper password handling can protect your users’ accounts and keep your applications secure. Whether you’re building web applications 🌐, APIs 🖥️, or authentication systems 🔐, understanding password security is essential for writing robust, secure code.

By the end of this tutorial, you’ll feel confident implementing secure password handling in your own projects! Let’s dive in! 🏊‍♂️

📚 Understanding Password Hashing and Salting

🤔 What is Password Hashing?

Password hashing is like a one-way meat grinder 🥩. Think of it as a magical blender that turns your password into an unrecognizable smoothie - you can’t turn the smoothie back into the original ingredients!

In TypeScript terms, hashing transforms a password into a fixed-length string of characters that cannot be reversed. This means you can:

✨ Store passwords safely without knowing the actual password
🚀 Verify passwords without storing them in plain text
🛡️ Protect user data even if your database is compromised

💡 Why Use Salting?

Here’s why developers love salting:

Rainbow Table Protection 🌈: Prevents pre-computed hash attacks
Unique Hashes 💻: Same password gets different hashes for different users
Extra Security Layer 📖: Makes brute force attacks much harder
Industry Standard 🔧: Required for compliance with security standards

Real-world example: Imagine building a user authentication system 👤. With proper hashing and salting, even if someone steals your database, they can’t recover the original passwords!

🔧 Basic Syntax and Usage

📝 Simple Example

Let’s start with a friendly example using bcrypt:

// 👋 Hello, secure passwords!
import bcrypt from 'bcryptjs';

// 🎨 Creating a password hasher
interface UserCredentials {
  email: string;      // 📧 User's email
  password: string;   // 🔑 Plain text password (never store this!)
  salt?: string;      // 🧂 Optional salt for extra flavor
}

// 🔐 Hash a password
async function hashPassword(password: string): Promise<string> {
  const saltRounds = 10; // 🎯 Cost factor
  const hashedPassword = await bcrypt.hash(password, saltRounds);
  return hashedPassword;
}

// ✅ Verify a password
async function verifyPassword(password: string, hash: string): Promise<boolean> {
  return await bcrypt.compare(password, hash);
}

💡 Explanation: Notice how we never store the plain password! The salt is automatically generated and embedded in the hash by bcrypt.

🎯 Common Patterns

Here are patterns you’ll use daily:

// 🏗️ Pattern 1: User registration
interface User {
  id: string;
  email: string;
  passwordHash: string; // 🔐 Never store plain passwords!
}

async function registerUser(email: string, password: string): Promise<User> {
  // 🎨 Hash the password
  const passwordHash = await hashPassword(password);
  
  // 💾 Save to database
  const user: User = {
    id: Date.now().toString(),
    email,
    passwordHash
  };
  
  console.log(`✅ User ${email} registered successfully!`);
  return user;
}

// 🔄 Pattern 2: User login
async function loginUser(email: string, password: string, user: User): Promise<boolean> {
  // 🔍 Verify the password
  const isValid = await verifyPassword(password, user.passwordHash);
  
  if (isValid) {
    console.log(`🎉 Welcome back, ${email}!`);
    return true;
  }
  
  console.log(`❌ Invalid credentials!`);
  return false;
}

// 🎨 Pattern 3: Password strength validation
function validatePasswordStrength(password: string): { valid: boolean; message: string; emoji: string } {
  if (password.length < 8) {
    return { valid: false, message: "Too short!", emoji: "😰" };
  }
  
  if (!/[A-Z]/.test(password) || !/[a-z]/.test(password) || !/[0-9]/.test(password)) {
    return { valid: false, message: "Add uppercase, lowercase, and numbers!", emoji: "🤔" };
  }
  
  return { valid: true, message: "Strong password!", emoji: "💪" };
}

💡 Practical Examples

🛒 Example 1: E-commerce User System

Let’s build something real:

// 🛍️ Define our secure user system
import bcrypt from 'bcryptjs';
import crypto from 'crypto';

interface SecureUser {
  id: string;
  username: string;
  email: string;
  passwordHash: string;
  createdAt: Date;
  lastLogin?: Date;
  failedAttempts: number;
}

// 🛒 User authentication service
class AuthService {
  private users: Map<string, SecureUser> = new Map();
  private readonly MAX_ATTEMPTS = 5; // 🚫 Lock after 5 failed attempts
  
  // 🔐 Register new user
  async register(username: string, email: string, password: string): Promise<SecureUser | null> {
    // 💡 Check password strength
    const strength = this.checkPasswordStrength(password);
    if (!strength.valid) {
      console.log(`❌ Weak password: ${strength.message} ${strength.emoji}`);
      return null;
    }
    
    // 🎨 Generate secure hash
    const saltRounds = 12; // 🔒 Higher = more secure but slower
    const passwordHash = await bcrypt.hash(password, saltRounds);
    
    // 👤 Create user
    const user: SecureUser = {
      id: crypto.randomUUID(),
      username,
      email,
      passwordHash,
      createdAt: new Date(),
      failedAttempts: 0
    };
    
    this.users.set(email, user);
    console.log(`🎉 Welcome ${username}! Your account is secured with military-grade encryption 🛡️`);
    return user;
  }
  
  // 🔍 Authenticate user
  async login(email: string, password: string): Promise<{ success: boolean; user?: SecureUser; message: string }> {
    const user = this.users.get(email);
    
    if (!user) {
      // 🕵️ Don't reveal if user exists
      await this.fakeHashDelay(); // Prevent timing attacks
      return { success: false, message: "Invalid credentials 🚫" };
    }
    
    // 🚫 Check if account is locked
    if (user.failedAttempts >= this.MAX_ATTEMPTS) {
      return { success: false, message: "Account locked! Contact support 🔒" };
    }
    
    // ✅ Verify password
    const isValid = await bcrypt.compare(password, user.passwordHash);
    
    if (isValid) {
      user.lastLogin = new Date();
      user.failedAttempts = 0;
      console.log(`🎊 Welcome back ${user.username}!`);
      return { success: true, user, message: "Login successful! 🚀" };
    }
    
    // ❌ Invalid password
    user.failedAttempts++;
    const remaining = this.MAX_ATTEMPTS - user.failedAttempts;
    return { 
      success: false, 
      message: `Invalid credentials. ${remaining} attempts remaining ⚠️` 
    };
  }
  
  // 💪 Check password strength
  private checkPasswordStrength(password: string): { valid: boolean; message: string; emoji: string } {
    const checks = [
      { test: password.length >= 8, message: "8+ characters", emoji: "📏" },
      { test: /[A-Z]/.test(password), message: "uppercase letter", emoji: "🔠" },
      { test: /[a-z]/.test(password), message: "lowercase letter", emoji: "🔡" },
      { test: /[0-9]/.test(password), message: "number", emoji: "🔢" },
      { test: /[^A-Za-z0-9]/.test(password), message: "special character", emoji: "✨" }
    ];
    
    const failed = checks.filter(check => !check.test);
    
    if (failed.length === 0) {
      return { valid: true, message: "Super strong password!", emoji: "💪" };
    }
    
    const missing = failed.map(f => f.message).join(", ");
    return { valid: false, message: `Add: ${missing}`, emoji: "🤔" };
  }
  
  // 🕐 Fake delay to prevent timing attacks
  private async fakeHashDelay(): Promise<void> {
    const fakePassword = "dummy_password_for_timing";
    await bcrypt.hash(fakePassword, 10);
  }
}

// 🎮 Let's use it!
const auth = new AuthService();
await auth.register("CodeNinja", "[email protected]", "SuperSecret123!");
await auth.login("[email protected]", "SuperSecret123!");

🎯 Try it yourself: Add a password reset feature with secure tokens!

🎮 Example 2: Game Account Security

Let’s make it fun:

// 🏆 Secure game account system
interface GameAccount {
  playerId: string;
  username: string;
  passwordHash: string;
  securityQuestions: SecurityQuestion[];
  twoFactorEnabled: boolean;
  achievements: string[];
}

interface SecurityQuestion {
  question: string;
  answerHash: string; // 🔐 Hash the answers too!
}

class GameSecurity {
  private accounts: Map<string, GameAccount> = new Map();
  
  // 🎮 Create secure game account
  async createAccount(username: string, password: string): Promise<GameAccount> {
    // 🎲 Generate unique player ID
    const playerId = `PLAYER_${Date.now()}_${Math.random().toString(36).substring(7)}`;
    
    // 🔐 Hash with extra security for gamers
    const saltRounds = 14; // 💪 Gamers deserve extra security!
    const passwordHash = await bcrypt.hash(password, saltRounds);
    
    const account: GameAccount = {
      playerId,
      username,
      passwordHash,
      securityQuestions: [],
      twoFactorEnabled: false,
      achievements: ["🌟 First Steps", "🛡️ Security Conscious"]
    };
    
    this.accounts.set(username, account);
    console.log(`🎮 Player ${username} joined the game! Achievement unlocked: ${account.achievements[0]}`);
    
    return account;
  }
  
  // 🔒 Add security question
  async addSecurityQuestion(username: string, question: string, answer: string): Promise<void> {
    const account = this.accounts.get(username);
    if (!account) return;
    
    // 🎨 Hash the answer (normalize to lowercase first)
    const normalizedAnswer = answer.toLowerCase().trim();
    const answerHash = await bcrypt.hash(normalizedAnswer, 10);
    
    account.securityQuestions.push({ question, answerHash });
    account.achievements.push("🔐 Extra Secure");
    
    console.log(`✅ Security question added! You earned: 🔐 Extra Secure`);
  }
  
  // 🎯 Verify security answer
  async verifySecurityAnswer(
    username: string, 
    questionIndex: number, 
    answer: string
  ): Promise<boolean> {
    const account = this.accounts.get(username);
    if (!account || !account.securityQuestions[questionIndex]) {
      return false;
    }
    
    const normalizedAnswer = answer.toLowerCase().trim();
    const question = account.securityQuestions[questionIndex];
    
    const isValid = await bcrypt.compare(normalizedAnswer, question.answerHash);
    
    if (isValid) {
      console.log(`✅ Security answer correct! 🎉`);
      return true;
    }
    
    console.log(`❌ Wrong answer! Try again 🤔`);
    return false;
  }
  
  // 🚀 Change password securely
  async changePassword(
    username: string, 
    oldPassword: string, 
    newPassword: string
  ): Promise<boolean> {
    const account = this.accounts.get(username);
    if (!account) return false;
    
    // 🔍 Verify old password
    const isValid = await bcrypt.compare(oldPassword, account.passwordHash);
    if (!isValid) {
      console.log(`❌ Current password incorrect!`);
      return false;
    }
    
    // 💪 Check new password isn't the same
    const isSame = await bcrypt.compare(newPassword, account.passwordHash);
    if (isSame) {
      console.log(`⚠️ New password must be different!`);
      return false;
    }
    
    // 🎨 Hash new password
    account.passwordHash = await bcrypt.hash(newPassword, 14);
    account.achievements.push("🔄 Password Champion");
    
    console.log(`✅ Password changed successfully! Achievement unlocked: 🔄 Password Champion`);
    return true;
  }
}

🚀 Advanced Concepts

🧙‍♂️ Advanced Topic 1: Argon2 - The Gold Standard

When you’re ready to level up, try this advanced pattern:

// 🎯 Advanced password hashing with Argon2
import argon2 from 'argon2';

interface AdvancedHashOptions {
  memoryCost?: number;     // 💾 Memory usage
  timeCost?: number;       // ⏱️ Iterations
  parallelism?: number;    // 🔄 Threads
  hashLength?: number;     // 📏 Output length
}

class AdvancedPasswordManager {
  // 🪄 Hash with Argon2 (winner of Password Hashing Competition!)
  async hashPasswordAdvanced(
    password: string, 
    options?: AdvancedHashOptions
  ): Promise<string> {
    const defaultOptions = {
      memoryCost: 2 ** 16,  // 64 MB
      timeCost: 3,          // 3 iterations
      parallelism: 1,       // 1 thread
      hashLength: 32        // 32 bytes
    };
    
    const hash = await argon2.hash(password, {
      ...defaultOptions,
      ...options,
      type: argon2.argon2id // 🛡️ Best for password hashing
    });
    
    console.log(`✨ Password hashed with military-grade Argon2!`);
    return hash;
  }
  
  // 🔍 Verify with timing attack protection
  async verifyPasswordAdvanced(password: string, hash: string): Promise<boolean> {
    try {
      const isValid = await argon2.verify(hash, password);
      return isValid;
    } catch (error) {
      // 🚫 Hash format might be invalid
      console.log(`⚠️ Invalid hash format!`);
      return false;
    }
  }
}

🏗️ Advanced Topic 2: Pepper and Additional Security

For the brave developers:

// 🚀 Enterprise-level security with pepper
class EnterprisePasswordSecurity {
  private readonly pepper: string; // 🌶️ Secret server-side key
  
  constructor(pepper: string) {
    this.pepper = pepper;
  }
  
  // 🔐 Hash with pepper (extra spicy security!)
  async hashWithPepper(password: string): Promise<string> {
    // 🎨 Add pepper to password
    const pepperedPassword = password + this.pepper;
    
    // 🧂 Generate salt and hash
    const saltRounds = 12;
    const hash = await bcrypt.hash(pepperedPassword, saltRounds);
    
    return hash;
  }
  
  // ✅ Verify peppered password
  async verifyWithPepper(password: string, hash: string): Promise<boolean> {
    const pepperedPassword = password + this.pepper;
    return await bcrypt.compare(pepperedPassword, hash);
  }
  
  // 🎯 Password history check
  async checkPasswordHistory(
    newPassword: string, 
    previousHashes: string[]
  ): Promise<boolean> {
    // 🔄 Check against previous passwords
    for (const oldHash of previousHashes) {
      const isSame = await this.verifyWithPepper(newPassword, oldHash);
      if (isSame) {
        console.log(`❌ Password was used before! Choose a new one 🔄`);
        return false;
      }
    }
    
    console.log(`✅ Password is unique! 🌟`);
    return true;
  }
}

⚠️ Common Pitfalls and Solutions

😱 Pitfall 1: Storing Plain Passwords

// ❌ Wrong way - NEVER do this!
interface InsecureUser {
  username: string;
  password: string; // 💥 This is a security disaster!
}

const badUser: InsecureUser = {
  username: "victim",
  password: "myPassword123" // 😰 Anyone can read this!
};

// ✅ Correct way - always hash!
interface SecureUser {
  username: string;
  passwordHash: string; // 🛡️ Safe and secure!
}

async function createSecureUser(username: string, password: string): Promise<SecureUser> {
  const passwordHash = await bcrypt.hash(password, 12);
  return { username, passwordHash };
}

🤯 Pitfall 2: Using Weak Hashing Algorithms

// ❌ Dangerous - MD5/SHA1 are broken!
import crypto from 'crypto';

function badHash(password: string): string {
  return crypto.createHash('md5').update(password).digest('hex'); // 💥 Crackable in seconds!
}

// ✅ Safe - use bcrypt, scrypt, or argon2!
async function goodHash(password: string): Promise<string> {
  return await bcrypt.hash(password, 12); // ✅ Secure and future-proof!
}

🛠️ Best Practices

🎯 Use Strong Algorithms: bcrypt, scrypt, or Argon2 - never MD5 or SHA1!
📝 Salt Everything: Always use unique salts (bcrypt does this automatically)
🛡️ Increase Work Factor: Use cost factor 12+ for bcrypt
🎨 Validate Password Strength: Enforce minimum requirements
✨ Never Log Passwords: Not even for debugging!

🧪 Hands-On Exercise

🎯 Challenge: Build a Secure Password Reset System

Create a type-safe password reset system:

📋 Requirements:

✅ Generate secure reset tokens
🏷️ Token expiration (1 hour max)
👤 Email verification before reset
📅 Track reset attempts
🎨 Prevent token reuse!

🚀 Bonus Points:

Add rate limiting for reset requests
Implement magic link authentication
Create password strength meter

💡 Solution

🔍 Click to see solution

// 🎯 Our secure password reset system!
import crypto from 'crypto';
import bcrypt from 'bcryptjs';

interface ResetToken {
  token: string;
  email: string;
  expiresAt: Date;
  used: boolean;
}

interface PasswordResetRequest {
  id: string;
  email: string;
  requestedAt: Date;
  ipAddress: string;
}

class PasswordResetService {
  private resetTokens: Map<string, ResetToken> = new Map();
  private resetRequests: PasswordResetRequest[] = [];
  private readonly TOKEN_EXPIRY_MINUTES = 60; // ⏰ 1 hour
  private readonly MAX_REQUESTS_PER_HOUR = 3; // 🚫 Rate limiting
  
  // 🎲 Generate secure reset token
  generateResetToken(email: string): string | null {
    // 🛡️ Check rate limit
    if (!this.checkRateLimit(email)) {
      console.log(`⚠️ Too many reset requests! Try again later 🕐`);
      return null;
    }
    
    // 🎯 Generate cryptographically secure token
    const token = crypto.randomBytes(32).toString('hex');
    const hashedToken = crypto
      .createHash('sha256')
      .update(token)
      .digest('hex');
    
    // 💾 Store token details
    const resetToken: ResetToken = {
      token: hashedToken,
      email,
      expiresAt: new Date(Date.now() + this.TOKEN_EXPIRY_MINUTES * 60 * 1000),
      used: false
    };
    
    this.resetTokens.set(hashedToken, resetToken);
    
    // 📝 Log request
    this.resetRequests.push({
      id: crypto.randomUUID(),
      email,
      requestedAt: new Date(),
      ipAddress: "127.0.0.1" // In real app, get from request
    });
    
    console.log(`📧 Password reset token sent to ${email}!`);
    return token; // Return unhashed token for email
  }
  
  // ✅ Validate reset token
  validateToken(token: string): { valid: boolean; email?: string; message: string } {
    const hashedToken = crypto
      .createHash('sha256')
      .update(token)
      .digest('hex');
    
    const resetToken = this.resetTokens.get(hashedToken);
    
    if (!resetToken) {
      return { valid: false, message: "Invalid token 🚫" };
    }
    
    if (resetToken.used) {
      return { valid: false, message: "Token already used 🔄" };
    }
    
    if (new Date() > resetToken.expiresAt) {
      return { valid: false, message: "Token expired ⏰" };
    }
    
    return { 
      valid: true, 
      email: resetToken.email, 
      message: "Token valid ✅" 
    };
  }
  
  // 🔐 Reset password with token
  async resetPassword(token: string, newPassword: string): Promise<boolean> {
    const validation = this.validateToken(token);
    
    if (!validation.valid) {
      console.log(`❌ Reset failed: ${validation.message}`);
      return false;
    }
    
    // 💪 Check password strength
    const strength = this.checkPasswordStrength(newPassword);
    if (!strength.valid) {
      console.log(`❌ Weak password: ${strength.message}`);
      return false;
    }
    
    // 🎨 Hash new password
    const hashedPassword = await bcrypt.hash(newPassword, 12);
    
    // 🚀 Mark token as used
    const hashedToken = crypto
      .createHash('sha256')
      .update(token)
      .digest('hex');
    
    const resetToken = this.resetTokens.get(hashedToken)!;
    resetToken.used = true;
    
    console.log(`✅ Password reset successful for ${validation.email}! 🎉`);
    return true;
  }
  
  // 🚦 Rate limiting check
  private checkRateLimit(email: string): boolean {
    const oneHourAgo = new Date(Date.now() - 60 * 60 * 1000);
    const recentRequests = this.resetRequests.filter(
      req => req.email === email && req.requestedAt > oneHourAgo
    );
    
    return recentRequests.length < this.MAX_REQUESTS_PER_HOUR;
  }
  
  // 💪 Password strength checker
  private checkPasswordStrength(password: string): { valid: boolean; message: string } {
    if (password.length < 8) {
      return { valid: false, message: "Too short! Need 8+ characters 📏" };
    }
    
    const hasUpper = /[A-Z]/.test(password);
    const hasLower = /[a-z]/.test(password);
    const hasNumber = /[0-9]/.test(password);
    const hasSpecial = /[^A-Za-z0-9]/.test(password);
    
    const strength = [hasUpper, hasLower, hasNumber, hasSpecial].filter(Boolean).length;
    
    if (strength < 3) {
      return { valid: false, message: "Add more variety! 🎨" };
    }
    
    return { valid: true, message: "Strong password! 💪" };
  }
  
  // 🧹 Clean expired tokens
  cleanExpiredTokens(): void {
    const now = new Date();
    let cleaned = 0;
    
    for (const [hash, token] of this.resetTokens) {
      if (now > token.expiresAt || token.used) {
        this.resetTokens.delete(hash);
        cleaned++;
      }
    }
    
    console.log(`🧹 Cleaned ${cleaned} expired tokens!`);
  }
}

// 🎮 Test it out!
const resetService = new PasswordResetService();
const token = resetService.generateResetToken("[email protected]");
if (token) {
  await resetService.resetPassword(token, "NewSecurePass123!");
}

🎓 Key Takeaways

You’ve learned so much! Here’s what you can now do:

✅ Implement secure password hashing with confidence 💪
✅ Avoid common security mistakes that compromise user data 🛡️
✅ Apply best practices for password handling 🎯
✅ Debug authentication issues like a pro 🐛
✅ Build secure authentication systems with TypeScript! 🚀

Remember: Security is not optional - it’s your responsibility to protect your users’ data! 🤝

🤝 Next Steps

Congratulations! 🎉 You’ve mastered password hashing and salting!

Here’s what to do next:

💻 Practice with the exercises above
🏗️ Build a complete authentication system
📚 Move on to our next tutorial: JWT Implementation and Session Management
🌟 Share your secure coding journey with others!

Remember: Every security expert was once a beginner. Keep coding, keep learning, and most importantly, keep your users safe! 🚀

Happy secure coding! 🎉🚀✨

Prerequisites

What you'll learn