aboutsummaryrefslogtreecommitdiff
path: root/webmentions_ssg/auth.py
diff options
context:
space:
mode:
Diffstat (limited to 'webmentions_ssg/auth.py')
-rw-r--r--webmentions_ssg/auth.py26
1 files changed, 22 insertions, 4 deletions
diff --git a/webmentions_ssg/auth.py b/webmentions_ssg/auth.py
index a5f3089..08abaa1 100644
--- a/webmentions_ssg/auth.py
+++ b/webmentions_ssg/auth.py
@@ -28,7 +28,13 @@ MIN_PASSWORD_LENGTH = 8
@cache
def dummy_password_hash() -> str:
- """Lazily generate a reusable hash for unknown login usernames."""
+ """Lazily generate a reusable hash for unknown login usernames.
+
+ The hash is calculated once and reused so missing accounts follow a comparable
+ password-check path.
+
+ :returns: Reusable password hash for timing-safe unknown-user authentication.
+ """
return generate_password_hash(secrets.token_urlsafe())
@@ -37,6 +43,10 @@ def validate_password(password: str) -> None:
Allow Unicode, whitespace-only passwords, and arbitrarily long passphrases,
but reject empty passwords and control characters.
+
+ :param password: Proposed new password to validate.
+ :raises ValueError: If the password is empty, too short, or contains control
+ characters.
"""
if not password:
raise ValueError("Password must not be empty.")
@@ -53,7 +63,7 @@ def load_user(session_id: object) -> User | None:
"""Load a user from the database by identifier.
:param session_id: Database ID and password-hash fingerprint stored in the session.
- :return: Matching user, or ``None`` if no user exists with the identifier.
+ :returns: Matching user, or ``None`` if no user exists with the identifier.
"""
if not isinstance(session_id, str):
return None
@@ -69,7 +79,11 @@ def load_user(session_id: object) -> User | None:
def login_username_limit_key() -> str:
- """Group usernames across IPs without exposing plaintext to rate-limit storage."""
+ """Group usernames across IPs without exposing plaintext to rate-limit storage.
+
+ :returns: Hashed username rate-limit key, or an IP-specific key if no username was
+ submitted.
+ """
username = request.form.get("username", "").strip().casefold()
if not username:
return f"missing-username:{get_remote_address()}"
@@ -78,7 +92,11 @@ def login_username_limit_key() -> str:
def is_safe_next_url(next_url: str) -> bool:
- """Allow redirects only to paths on this site."""
+ """Allow redirects only to paths on this site.
+
+ :param next_url: Requested post-login redirect path.
+ :returns: ``True`` if the redirect is a safe site-local path.
+ """
if "\\" in next_url or not next_url.startswith("/") or next_url.startswith("//"):
return False
try: