Password Hashing and User Registration

Passwords must never be stored in plain text or with fast hashing algorithms like MD5 or SHA256. A database breach that exposes password hashes must not also expose the actual passwords. bcrypt is the industry standard for password hashing — it is intentionally slow (making brute-force attacks expensive), includes a random salt (making rainbow table attacks impossible), and has a configurable work factor (making it future-proof as hardware gets faster). The passlib library provides a clean Python interface to bcrypt and other password hashing schemes.

Password Hashing with passlib #

pip install passlib[bcrypt]

# app/auth/password.py
from passlib.context import CryptContext

# CryptContext handles hashing, verification, and upgrading schemes
pwd_context = CryptContext(
    schemes    = ["bcrypt"],
    deprecated = "auto",   # automatically upgrade old hashes on verify
)

def hash_password(plain_password: str) -> str:
    """Hash a plain-text password. Returns a bcrypt hash string."""
    return pwd_context.hash(plain_password)

def verify_password(plain_password: str, hashed_password: str) -> bool:
    """
    Verify a plain-text password against a stored hash.
    Returns True if they match, False otherwise.
    """
    return pwd_context.verify(plain_password, hashed_password)

# ── Usage ─────────────────────────────────────────────────────────────────────
hash1 = hash_password("mysecretpassword")
# "$2b$12$K9Wd6GrDnM2TjflWz2xHb.5bx7YoRyLqTCTJakrQ3P8M6MZGNJbJm"
# $2b = bcrypt, $12 = work factor (2^12 = 4096 iterations)
# The hash includes the algorithm, work factor, and random salt

verify_password("mysecretpassword", hash1)   # True
verify_password("wrong_password",   hash1)   # False
# Two hashes of the same password are DIFFERENT (different random salts):
hash2 = hash_password("mysecretpassword")
hash1 != hash2   # True — different hashes, same password

User Registration Endpoint #

# app/routers/auth.py
from fastapi import APIRouter, Depends, HTTPException, status
from sqlalchemy.orm import Session
from sqlalchemy.exc import IntegrityError
from pydantic import BaseModel, Field, field_validator
from app.dependencies import get_db
from app.models.user import User
from app.models.user_profile import UserProfile
from app.auth.password import hash_password

router = APIRouter(prefix="/auth", tags=["Auth"])

class RegisterRequest(BaseModel):
    email:    str   = Field(..., pattern=r"^[\w.+-]+@[\w-]+\.[a-zA-Z]{2,}$")
    name:     str   = Field(..., min_length=2, max_length=100)
    password: str   = Field(..., min_length=8, max_length=128)

    @field_validator("email")
    @classmethod
    def normalise_email(cls, v: str) -> str:
        return v.strip().lower()

    @field_validator("password")
    @classmethod
    def validate_password_strength(cls, v: str) -> str:
        if not any(c.isupper() for c in v):
            raise ValueError("Password must contain at least one uppercase letter")
        if not any(c.isdigit() for c in v):
            raise ValueError("Password must contain at least one digit")
        return v

class UserResponse(BaseModel):
    model_config = {"from_attributes": True}
    id:    int
    email: str
    name:  str
    role:  str

@router.post("/register", response_model=UserResponse, status_code=201)
def register(data: RegisterRequest, db: Session = Depends(get_db)):
    try:
        user = User(
            email         = data.email,
            name          = data.name,
            password_hash = hash_password(data.password),
            role          = "user",
        )
        db.add(user)
        db.flush()   # get user.id

        # Auto-create empty profile
        profile = UserProfile(user_id=user.id)
        db.add(profile)
        db.flush()
        db.refresh(user)
        return user

    except IntegrityError:
        db.rollback()
        raise HTTPException(
            status_code = status.HTTP_409_CONFLICT,
            detail      = "An account with this email already exists",
        )

Common Mistakes #

Mistake 1 — Storing plain text password #

❌ Wrong — catastrophic on data breach:

user = User(email=data.email, password=data.password)   # NEVER store plain text!

✅ Correct:

user = User(email=data.email, password_hash=hash_password(data.password))   # ✓

Mistake 2 — Using SHA256/MD5 for password hashing #

❌ Wrong — fast hashes are crackable in seconds with GPU rigs:

import hashlib
password_hash = hashlib.sha256(password.encode()).hexdigest()   # insecure!

✅ Correct — use bcrypt (slow, salted, purpose-built).

Mistake 3 — Not returning 409 on duplicate email (leaking user existence) #

❌ Wrong — error message reveals which emails are registered:

raise HTTPException(400, f"Email {data.email} is already registered")   # user enumeration!

✅ Correct — generic message:

raise HTTPException(409, "An account with this email already exists")   # ✓

Quick Reference #