# [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]
from passlib.context import CryptContext
# [/SECTION]

# [DEF:pwd_context:Variable]
# @PURPOSE: Passlib CryptContext for password management.
pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")
# [/DEF:pwd_context:Variable]

# [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:
    return pwd_context.verify(plain_password, hashed_password)
# [/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 pwd_context.hash(password)
# [/DEF:get_password_hash:Function]

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