name: auth-patterns
description: Use when implementing authentication. Use when storing passwords. Use when asked to store credentials insecurely.

Authentication Patterns

Overview

Never store plain passwords. Use proven auth patterns. Security is not optional.

Authentication is the front door to your system. Get it wrong and everything else is compromised.

When to Use

• Implementing login/registration
• Storing user credentials
• Verifying user identity
• Working with sessions or tokens

The Iron Rule

NEVER store passwords in plain text. ALWAYS use slow hashing.

No exceptions:
- Not for "internal users only"
- Not for "we'll encrypt later"
- Not for "it's behind a firewall"
- Not for "just for development"

Detection: Insecure Auth Smell

If passwords aren't properly hashed, STOP:

// ❌ VIOLATION: Plain text password
await db.users.create({
  email,
  password: password  // Stored as-is!
});

// ❌ VIOLATION: Fast hash (crackable)
const hashed = crypto.createHash('sha256').update(password).digest('hex');

// ❌ VIOLATION: Reversible encryption
const encrypted = encrypt(password, key);  // Can be decrypted!

The Correct Pattern: Bcrypt/Argon2

// ✅ CORRECT: Slow, salted hashing with bcrypt
import bcrypt from 'bcrypt';

const SALT_ROUNDS = 12;  // Adjust based on your hardware

async function hashPassword(plain: string): Promise<string> {
  return bcrypt.hash(plain, SALT_ROUNDS);
}

async function verifyPassword(plain: string, hashed: string): Promise<boolean> {
  return bcrypt.compare(plain, hashed);
}

// Registration
app.post('/register', async (req, res) => {
  const { email, password } = validated(req.body);

  const hashedPassword = await hashPassword(password);

  await db.users.create({
    email,
    password: hashedPassword  // Store the hash
  });

  res.status(201).json({ success: true });
});

// Login
app.post('/login', async (req, res) => {
  const { email, password } = validated(req.body);

  const user = await db.users.findByEmail(email);

  // Constant-time comparison to prevent timing attacks
  // Always verify even if user not found
  const dummyHash = '$2b$12$dummy.hash.here';
  const isValid = await verifyPassword(password, user?.password ?? dummyHash);

  if (!user || !isValid) {
    // Same error for both cases - prevents user enumeration
    return res.status(401).json({ error: 'Invalid credentials' });
  }

  const token = generateToken(user);
  res.json({ token });
});

Authentication Checklist

Password Storage

• [ ] Use bcrypt or Argon2 (slow hash)
• [ ] Salt rounds ≥ 12 for bcrypt
• [ ] Never store plain text
• [ ] Never use MD5/SHA1/SHA256 alone

Login Security

• [ ] Constant-time comparison
• [ ] Same error for "user not found" and "wrong password"
• [ ] Rate limiting on login endpoint
• [ ] Account lockout after N failures

Session/Token Security

• [ ] JWTs: short expiry, secure secret
• [ ] Sessions: secure, httpOnly cookies
• [ ] Implement token refresh properly
• [ ] Invalidate on logout/password change

Pressure Resistance Protocol

1. "We'll Encrypt Later"

Pressure: "Just store it for now, we'll add encryption"

Response: Plain text passwords get leaked. Breaches happen fast.

Action: Hash from day one. It's 3 lines of code.

2. "It's Behind a Firewall"

Pressure: "Internal network, no one can access it"

Response: Firewalls get breached. Insiders exist. Defense in depth.

Action: Hash regardless of network security.

3. "SHA256 Is Secure"

Pressure: "SHA256 is a strong hash"

Response: SHA256 is fast - billions per second on GPU. Bcrypt is intentionally slow.

Action: Use bcrypt or Argon2. Speed is the enemy.

4. "Just for Development"

Pressure: "Dev database doesn't need security"

Response: Dev code becomes prod code. Dev habits become prod habits.

Action: Use proper hashing in all environments.

Red Flags - STOP and Reconsider

• password column without "hash" in name
• Using crypto.createHash for passwords
• Comparing passwords with ===
• Same error messages reveal user existence
• No rate limiting on auth endpoints

All of these mean: Fix the auth implementation.

Quick Reference

Common Rationalizations (All Invalid)

The Bottom Line

Hash passwords with bcrypt. Use constant-time comparison. Return generic errors.

Password security is non-negotiable. Use slow hashes (bcrypt, Argon2). Prevent timing attacks. Don't leak user existence. Rate limit everything.