# [DEF:backend.src.core.auth.security:Module]
#
# @SEMANTICS: security, password, hashing, bcrypt
# @PURPOSE:   Utility for password hashing and verification using Passlib.
# @LAYER:     Core
# @RELATION:  DEPENDS_ON -> passlib
#
# @INVARIANT: Uses bcrypt for hashing with standard work factor.

# [SECTION: IMPORTS]
import bcrypt
# [/SECTION]

# [DEF:verify_password:Function]
# @PURPOSE: Verifies a plain password against a hashed password.
# @PRE:     plain_password is a string, hashed_password is a bcrypt hash.
# @POST:    Returns True if password matches, False otherwise.
#
# @PARAM:   plain_password (str) - The unhashed password.
# @PARAM:   hashed_password (str) - The stored hash.
# @RETURN:  bool - Verification result.
def verify_password(plain_password: str, hashed_password: str) -> bool:
    if not hashed_password:
        return False
    try:
        return bcrypt.checkpw(
            plain_password.encode("utf-8"),
            hashed_password.encode("utf-8"),
        )
    except Exception:
        return False
# [/DEF:verify_password:Function]

# [DEF:get_password_hash:Function]
# @PURPOSE: Generates a bcrypt hash for a plain password.
# @PRE:     password is a string.
# @POST:    Returns a secure bcrypt hash string.
#
# @PARAM:   password (str) - The password to hash.
# @RETURN:  str - The generated hash.
def get_password_hash(password: str) -> str:
    return bcrypt.hashpw(password.encode("utf-8"), bcrypt.gensalt()).decode("utf-8")
# [/DEF:get_password_hash:Function]

# [/DEF:backend.src.core.auth.security:Module]