Skip to content

Password helpers

The plugin-owned password wiring now lives in Configuration. PasswordHelper is the hashing boundary itself. Use PasswordHelper.from_defaults() when you want the library's default pwdlib configuration: Argon2 only for new hashes and verification. Unsupported stored password hashes fail closed under that default, so rotate or reset those credentials before rollout. Use PasswordHelper(password_hash=...) only for deliberate application-owned custom pwdlib composition.

For plugin-managed apps that also hash or verify passwords in domain services, CLI tasks, or data migrations, call config.resolve_password_helper() once after constructing LitestarAuthConfig(...). That method returns the explicit user_manager_security.password_helper when you already supplied one; otherwise it memoizes PasswordHelper.from_defaults() on the config, and the plugin injects that same memoized helper into every request-scoped manager so the plugin and app-owned code reuse the same instance.

litestar_auth.password

Password hashing helpers built on top of pwdlib.

PasswordHelper(password_hash=None)

Hash and verify passwords with a configurable pwdlib pipeline.

Initialize the helper with the provided pwdlib hash pipeline.

Source code in litestar_auth/password.py 
25
26
27
def __init__(self, password_hash: PasswordHash | None = None) -> None:
    """Initialize the helper with the provided pwdlib hash pipeline."""
    self.password_hash = password_hash or _build_default_password_hash()

from_defaults() classmethod

Return a helper configured with the library's default Argon2-only policy.

Source code in litestar_auth/password.py 
20
21
22
23
@classmethod
def from_defaults(cls) -> Self:
    """Return a helper configured with the library's default Argon2-only policy."""
    return cls(password_hash=_build_default_password_hash())

hash(password)

Return a salted password hash.

Source code in litestar_auth/password.py 
29
30
31
def hash(self, password: str) -> str:
    """Return a salted password hash."""
    return self.password_hash.hash(password)

verify(password, hashed)

Verify a password against a stored hash.

pwdlib delegates verification to the selected hasher, which performs constant-time comparison for password checks. Treat unsupported or malformed hashes, along with hasher-level validation failures, as authentication failures instead of bubbling an exception into the login flow.

Returns:

Type Description
bool

True when the password matches the stored hash, otherwise False.
Source code in litestar_auth/password.py 
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
def verify(self, password: str, hashed: str) -> bool:
    """Verify a password against a stored hash.

    pwdlib delegates verification to the selected hasher, which performs
    constant-time comparison for password checks. Treat unsupported or
    malformed hashes, along with hasher-level validation failures, as
    authentication failures instead of bubbling an exception into the
    login flow.

    Returns:
        ``True`` when the password matches the stored hash, otherwise ``False``.
    """
    try:
        return self.password_hash.verify(password, hashed)
    except (UnknownHashError, ValueError):
        return False

verify_and_update(password, hashed)

Verify a password and return an updated hash when the stored one is deprecated.

Uses pwdlib's verify_and_update: when the configured pipeline marks the stored hash as deprecated, pwdlib returns the new hash so the caller can persist it. When the hash is already current, unsupported, malformed, or the password is wrong, the second element is None.

Returns:

Type Description
bool

A pair (verified, new_hash). When verified is True and new_hash is not
str | None

None, the caller should update the stored hash to new_hash.
Source code in litestar_auth/password.py 
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
def verify_and_update(self, password: str, hashed: str) -> tuple[bool, str | None]:
    """Verify a password and return an updated hash when the stored one is deprecated.

    Uses pwdlib's ``verify_and_update``: when the configured pipeline marks the
    stored hash as deprecated, pwdlib returns the new hash so the caller can
    persist it. When the hash is already current, unsupported, malformed, or the
    password is wrong, the second element is ``None``.

    Returns:
        A pair (verified, new_hash). When ``verified`` is True and ``new_hash`` is not
        None, the caller should update the stored hash to ``new_hash``.
    """
    try:
        return self.password_hash.verify_and_update(password, hashed)
    except (UnknownHashError, ValueError):
        return (False, None)