Module

security.passwords

Password hashing utilities — argon2id with scrypt fallback.

Hashes passwords using the best available algorithm:

  1. argon2id viaargon2-cffi (preferred, pip install chirp[auth])
  2. scrypt via stdlibhashlib(fallback, always available)

Both produce PHC-format strings.verify_passwordauto-detects the algorithm from the hash prefix, so hashes are forward-compatible if the default changes.

Usage::

from chirp.security.passwords import hash_password, verify_password

hashed = hash_password("my-password")
ok = verify_password("my-password", hashed)
7Functions

Functions

_has_argon2 0 bool ▼
Check if argon2-cffi is available.
def _has_argon2() -> bool
Returns
bool
_hash_scrypt 1 str ▼
Hash password with scrypt, returning a PHC-format string.
def _hash_scrypt(password: str) -> str
Parameters
Name Type Description
password str
Returns
str
_verify_scrypt 2 bool ▼
Verify password against a scrypt PHC-format hash.
def _verify_scrypt(password: str, phc_hash: str) -> bool
Parameters
Name Type Description
password str
phc_hash str
Returns
bool
_hash_argon2 1 str ▼
Hash password with argon2id via argon2-cffi.
def _hash_argon2(password: str) -> str
Parameters
Name Type Description
password str
Returns
str
_verify_argon2 2 bool ▼
Verify password against an argon2 hash.
def _verify_argon2(password: str, phc_hash: str) -> bool
Parameters
Name Type Description
password str
phc_hash str
Returns
bool
hash_password 1 str ▼
Hash a password using the best available algorithm. Uses argon2id if ``argon2-…
def hash_password(password: str) -> str

Hash a password using the best available algorithm.

Uses argon2id ifargon2-cffi is installed (pip install chirp[auth]), otherwise falls back to scrypt (stdlib).

Returns a PHC-format string safe for database storage.

Parameters
Name Type Description
password str

The plaintext password to hash.
Returns
str
verify_password 2 bool ▼
Verify a password against a PHC-format hash. Auto-detects the algorithm from t…
def verify_password(password: str, phc_hash: str) -> bool

Verify a password against a PHC-format hash.

Auto-detects the algorithm from the hash prefix. This means hashes created with argon2 can be verified even if the default algorithm later changes (and vice versa).

Parameters
Name Type Description
password str

The plaintext password to check.
phc_hash str

The stored hash (fromhash_password).
Returns
bool