security: add bcrypt password hashing helpers

Author: Saurabh Kumar Bajpai

backend/password_hashing.py

@@ -0,0 +1,87 @@
+"""
+Password hashing helpers for any repository-managed credential flow.
+
+The public app currently delegates user authentication to Supabase Auth. If a
+backend/admin flow ever stores local passwords, it must use these helpers
+rather than fast hashes such as MD5 or SHA variants.
+"""
+
+from __future__ import annotations
+
+import re
+
+import bcrypt
+
+BCRYPT_COST_FACTOR = 12
+_BCRYPT_HASH_PATTERN = re.compile(r"^\$2[aby]\$(\d{2})\$[./A-Za-z0-9]{53}$")
+
+
+def _to_password_bytes(password: str) -> bytes:
+    if not isinstance(password, str) or not password:
+        raise ValueError("Password must be a non-empty string.")
+    return password.encode("utf-8")
+
+
+def hash_password(
+    password: str,
+    *,
+    cost_factor: int = BCRYPT_COST_FACTOR,
+) -> str:
+    """
+    Hash a plaintext password with bcrypt.
+
+    bcrypt cost 12 is the project baseline. Higher values may be passed by
+    callers after performance testing, but lower values are rejected.
+    """
+
+    if cost_factor < BCRYPT_COST_FACTOR:
+        raise ValueError(
+            f"bcrypt cost factor must be at least {BCRYPT_COST_FACTOR}."
+        )
+
+    password_bytes = _to_password_bytes(password)
+    return bcrypt.hashpw(
+        password_bytes,
+        bcrypt.gensalt(rounds=cost_factor),
+    ).decode("ascii")
+
+
+def verify_password(password: str, password_hash: str) -> bool:
+    """
+    Verify a plaintext password against a bcrypt hash.
+
+    Malformed hashes, legacy MD5/SHA digests, and empty inputs fail closed.
+    """
+
+    if not isinstance(password_hash, str) or not is_bcrypt_hash(password_hash):
+        return False
+
+    try:
+        return bcrypt.checkpw(
+            _to_password_bytes(password),
+            password_hash.encode("ascii"),
+        )
+    except (TypeError, ValueError):
+        return False
+
+
+def is_bcrypt_hash(password_hash: str) -> bool:
+    """Return whether a value has bcrypt's expected modular crypt format."""
+
+    return isinstance(password_hash, str) and bool(
+        _BCRYPT_HASH_PATTERN.fullmatch(password_hash)
+    )
+
+
+def password_hash_needs_rehash(
+    password_hash: str,
+    *,
+    cost_factor: int = BCRYPT_COST_FACTOR,
+) -> bool:
+    """Return true when a bcrypt hash is missing or uses a weaker cost."""
+
+    match = _BCRYPT_HASH_PATTERN.fullmatch(password_hash or "")
+    if not match:
+        return True
+
+    return int(match.group(1)) < cost_factor

requirements.txt

@@ -14,6 +14,7 @@ redis>=5.0.1
 python-dotenv>=1.0.1
 pytest-env>=1.1.3
 bleach
+bcrypt>=4.1.0
 faiss-cpu>=1.8.0
 
 # Pre-commit hooks

tests/test_password_hashing.py

@@ -0,0 +1,59 @@
+import hashlib
+
+import pytest
+
+from backend.password_hashing import (
+    BCRYPT_COST_FACTOR,
+    hash_password,
+    is_bcrypt_hash,
+    password_hash_needs_rehash,
+    verify_password,
+)
+
+
+def test_hash_password_uses_bcrypt_cost_factor_12():
+    password_hash = hash_password("Correct Horse Battery Staple")
+
+    assert is_bcrypt_hash(password_hash)
+    assert password_hash.startswith(f"$2b${BCRYPT_COST_FACTOR}$")
+    assert "Correct Horse Battery Staple" not in password_hash
+
+
+def test_verify_password_accepts_valid_password_and_rejects_invalid_password():
+    password_hash = hash_password("s3cure-pa55word")
+
+    assert verify_password("s3cure-pa55word", password_hash) is True
+    assert verify_password("wrong-password", password_hash) is False
+
+
+def test_verify_password_fails_closed_for_md5_and_malformed_hashes():
+    legacy_md5_hash = hashlib.md5(b"s3cure-pa55word").hexdigest()
+
+    assert verify_password("s3cure-pa55word", legacy_md5_hash) is False
+    assert verify_password("s3cure-pa55word", "not-a-bcrypt-hash") is False
+    assert verify_password("", legacy_md5_hash) is False
+
+
+def test_hash_password_rejects_weak_cost_factors_and_empty_passwords():
+    with pytest.raises(ValueError):
+        hash_password("s3cure-pa55word", cost_factor=BCRYPT_COST_FACTOR - 1)
+
+    with pytest.raises(ValueError):
+        hash_password("")
+
+
+def test_password_hash_needs_rehash_detects_missing_or_weak_hashes():
+    current_hash = hash_password("s3cure-pa55word")
+    weak_hash = hash_password(
+        "s3cure-pa55word",
+        cost_factor=BCRYPT_COST_FACTOR,
+    )
+
+    assert password_hash_needs_rehash(current_hash) is False
+    assert password_hash_needs_rehash(
+        weak_hash,
+        cost_factor=BCRYPT_COST_FACTOR + 1,
+    ) is True
+    assert password_hash_needs_rehash(
+        "5f4dcc3b5aa765d61d8327deb882cf99"
+    ) is True