security.passwords

Check if argon2-cffi is available.

Hash password with scrypt, returning a PHC-format string.

Verify password against a scrypt PHC-format hash.

Build aPasswordHasherwith explicit, pinned argon2id cost params.

Cost factors follow RFC 9106 §4 (second recommended option) and are pinned to argon2-cffi's currentPasswordHasher()defaults so existing hashes still verify. The same construction is used for hashing and verifying so the two paths always agree.

Hash password with argon2id via argon2-cffi.

Verify password against an argon2 hash.

Fails closed: any argon2-cffi failure — a wrong password (VerificationError, an Argon2Errorsubclass) or a malformed/corrupt hash string (InvalidHashError, which derives from ValueError— NOT fromArgon2Error) — returns Falseinstead of propagating. Both are caught so any malformed-input failure fails closed, mirroring the scrypt path which returnsFalsefor unparseable hashes.

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.

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).

ReturnTrueif a scrypt hash's embedded cost is below current params.

Parsesn (and r) from the PHC string and compares to the current _SCRYPT_*constants. A malformed/unparseable hash is treated as stale (True) so a corrupt stored hash is re-derived on the next successful login rather than being trusted indefinitely.

Report whether a stored hash should be replaced on the next login.

Parameter staleness is reported by default: an argon2 hash whose embedded cost factors are below the current pinned params (per argon2-cffi's PasswordHasher.check_needs_rehash), or a scrypt hash whose embedded n/r is below the current _SCRYPT_*constants.

The algorithm upgrade clause — flagging a scrypt hash as stale only because argon2 is now installed and is the new default — is gated behind upgrade_algorithm and is off by default. Installing the auth extra must not silently mark every existing scrypt hash stale: on non-deterministic / autoscaled hosts that would trigger a fleet-wide rehash-write storm the first time each host serves a login. Opt in explicitly (e.g. a controlled migration window) when you want algorithm upgrades.

Verify a password and opportunistically return an upgraded hash.

Returns(ok, new_hash_or_None). new_hashis a freshly computed hash only when the password verified andneeds_rehash() reports the stored hash is stale.upgrade_algorithmis forwarded to needs_rehash() and defaults to False(parameter staleness only — scrypt→argon2 algorithm upgrades require an explicit opt-in). A hash is never re-derived for a wrong password, so a failed guess can never cause a database write.

Typical use on login (parameter upgrades only)::

ok, new_hash = verify_and_upgrade(password, user.password_hash)
if not ok:
    return reject()
if new_hash is not None:
    user.password_hash = new_hash  # persist the upgrade

Controlled scrypt→argon2 migration window::

ok, new_hash = verify_and_upgrade(
    password, user.password_hash, upgrade_algorithm=True
)
if not ok:
    return reject()
if new_hash is not None:
    user.password_hash = new_hash  # persist the upgrade

Return the process-wide decoy hash, computing it once (thread-safe).

Double-checked locking: the common (already-initialized) path reads the published value without taking the lock; only the first caller(s) contend on_DECOY_LOCKand exactly one performs the (expensive) hash.

Verify a login credential while resisting user-enumeration via timing.

For a known user, behaves likeverify_password(). For an unknown user (phc_hash is None) it still runs a full hash verification against a module-level decoy hash before returningFalse, so the unknown-user and wrong-password code paths take comparable time and an attacker cannot tell "no such user" from "wrong password" by latency.

Residual: the timing equivalence is approximate, not unconditional. In a mixed-algorithm corpus — legacy scrypt hashes stored while argon2 is now the default — the decoy is computed with the current default algorithm, so its verify cost differs from a stored scrypt verify. The defence removes the coarse known-vs-unknown signal; it does not promise byte-constant timing across algorithms. Re-deriving stale hashes (seeverify_and_upgrade()) converges the corpus toward a single algorithm over time.