quart-security 1.3.0__tar.gz → 1.4.1__tar.gz

quart_security-1.3.0/README.md → quart_security-1.4.1/PKG-INFO

@@ -1,3 +1,31 @@
+Metadata-Version: 2.4
+Name: quart-security
+Version: 1.4.1
+Summary: Native async auth for Quart
+Author: quart-security maintainers
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: quart>=0.20.0
+Requires-Dist: sqlalchemy>=2.0
+Requires-Dist: libpass>=1.9
+Requires-Dist: pyotp>=2.9
+Requires-Dist: qrcode>=8.0
+Requires-Dist: webauthn>=2.7
+Requires-Dist: wtforms>=3.1
+Requires-Dist: aiosmtplib>=3.0
+Requires-Dist: blinker>=1.7
+Requires-Dist: email-validator>=2.0
+Requires-Dist: argon2-cffi>=23.1
+Requires-Dist: httpx>=0.27
+Requires-Dist: pytest>=8.0 ; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23 ; extra == "dev"
+Requires-Dist: ruff>=0.6 ; extra == "dev"
+Project-URL: Homepage, https://github.com/level09/quart-security
+Project-URL: Issues, https://github.com/level09/quart-security/issues
+Project-URL: Repository, https://github.com/level09/quart-security
+Provides-Extra: dev
+
 # quart-security
 
 `quart-security` is a native async authentication extension for Quart.
@@ -108,20 +136,30 @@ Optional for lockout support:
 - `failed_login_count`
 - `locked_until`
 
+These fields are required when login or MFA lockout is enabled. The built-in
+counter limits account-level guesses. Deploy an application or edge rate limiter
+for source IP and distributed abuse controls.
+
 ## Key Configuration
 
 The extension uses `SECURITY_*` keys for migration-friendly configuration.
 
 Core:
-- `SECURITY_PASSWORD_HASH` (default: `pbkdf2_sha512`)
+- `SECURITY_PASSWORD_HASH` (default: `argon2` / argon2id; set to `pbkdf2_sha512` to keep old behavior)
 - `SECURITY_PASSWORD_SALT` (recommended)
 - `SECURITY_PASSWORD_LENGTH_MIN` (default: `12`)
+- `SECURITY_PASSWORD_BREACH_CHECK` (default: `True`) - HIBP k-anonymity check on register/change
+- `SECURITY_PASSWORD_BREACH_COUNT_MIN` (default: `1`) - minimum breach count to reject
+- `SECURITY_ARGON2_MEMORY_COST` / `SECURITY_ARGON2_TIME_COST` / `SECURITY_ARGON2_PARALLELISM` - override argon2 params (production defaults: 19456/2/1)
 - `SECURITY_LOGIN_MAX_ATTEMPTS` (default: `5`)
 - `SECURITY_LOCKOUT_MINUTES` (default: `15`)
 - `SECURITY_REGISTERABLE`
 - `SECURITY_CHANGEABLE`
 - `SECURITY_TRACKABLE`
 - `SECURITY_CSRF_PROTECT` (default: `True`)
+- `SECURITY_FRESHNESS` (default: `60` minutes)
+
+Existing pbkdf2_sha512 and bcrypt hashes continue to verify after the argon2 default change. They are transparently rehashed to argon2id on the user's next successful login.
 
 2FA:
 - `SECURITY_TWO_FACTOR`
@@ -129,6 +167,10 @@ Core:
 - `SECURITY_MULTI_FACTOR_RECOVERY_CODES`
 - `SECURITY_MULTI_FACTOR_RECOVERY_CODES_N`
 
+Recovery codes are displayed only when generated and are stored as keyed hashes.
+Existing plaintext codes remain valid until their next successful use, when the
+remaining codes are migrated.
+
 WebAuthn:
 - `SECURITY_WEBAUTHN`
 - `SECURITY_WAN_ALLOW_AS_FIRST_FACTOR`
@@ -147,7 +189,7 @@ Routing:
 Core:
 - `/login`
 - `/register`
-- `/logout`
+- `/logout` (POST only)
 - `/change`
 
 2FA:
@@ -225,3 +267,4 @@ Run this in a HTTPS staging environment with production-like hostnames and real
 - Run behind HTTPS for WebAuthn in non-local environments.
 - Set explicit WebAuthn RP values (`SECURITY_WAN_RP_ID`, `SECURITY_WAN_EXPECTED_ORIGIN`) when behind proxies or multiple domains.
 - Keep CSRF protection enabled unless you have a deliberate replacement.
+

quart_security-1.3.0/PKG-INFO → quart_security-1.4.1/README.md

@@ -1,29 +1,3 @@
-Metadata-Version: 2.1
-Name: quart-security
-Version: 1.3.0
-Summary: Native async auth for Quart
-Author: quart-security maintainers
-Requires-Python: >=3.11
-Description-Content-Type: text/markdown
-Requires-Dist: quart>=0.20.0
-Requires-Dist: sqlalchemy>=2.0
-Requires-Dist: libpass>=1.9
-Requires-Dist: pyotp>=2.9
-Requires-Dist: qrcode>=8.0
-Requires-Dist: webauthn>=2.0
-Requires-Dist: wtforms>=3.1
-Requires-Dist: aiosmtplib>=3.0
-Requires-Dist: blinker>=1.7
-Requires-Dist: itsdangerous>=2.1
-Requires-Dist: email-validator>=2.0
-Requires-Dist: pytest>=8.0 ; extra == "dev"
-Requires-Dist: pytest-asyncio>=0.23 ; extra == "dev"
-Requires-Dist: ruff>=0.6 ; extra == "dev"
-Project-URL: Homepage, https://github.com/level09/quart-security
-Project-URL: Issues, https://github.com/level09/quart-security/issues
-Project-URL: Repository, https://github.com/level09/quart-security
-Provides-Extra: dev
-
 # quart-security
 
 `quart-security` is a native async authentication extension for Quart.
@@ -134,20 +108,30 @@ Optional for lockout support:
 - `failed_login_count`
 - `locked_until`
 
+These fields are required when login or MFA lockout is enabled. The built-in
+counter limits account-level guesses. Deploy an application or edge rate limiter
+for source IP and distributed abuse controls.
+
 ## Key Configuration
 
 The extension uses `SECURITY_*` keys for migration-friendly configuration.
 
 Core:
-- `SECURITY_PASSWORD_HASH` (default: `pbkdf2_sha512`)
+- `SECURITY_PASSWORD_HASH` (default: `argon2` / argon2id; set to `pbkdf2_sha512` to keep old behavior)
 - `SECURITY_PASSWORD_SALT` (recommended)
 - `SECURITY_PASSWORD_LENGTH_MIN` (default: `12`)
+- `SECURITY_PASSWORD_BREACH_CHECK` (default: `True`) - HIBP k-anonymity check on register/change
+- `SECURITY_PASSWORD_BREACH_COUNT_MIN` (default: `1`) - minimum breach count to reject
+- `SECURITY_ARGON2_MEMORY_COST` / `SECURITY_ARGON2_TIME_COST` / `SECURITY_ARGON2_PARALLELISM` - override argon2 params (production defaults: 19456/2/1)
 - `SECURITY_LOGIN_MAX_ATTEMPTS` (default: `5`)
 - `SECURITY_LOCKOUT_MINUTES` (default: `15`)
 - `SECURITY_REGISTERABLE`
 - `SECURITY_CHANGEABLE`
 - `SECURITY_TRACKABLE`
 - `SECURITY_CSRF_PROTECT` (default: `True`)
+- `SECURITY_FRESHNESS` (default: `60` minutes)
+
+Existing pbkdf2_sha512 and bcrypt hashes continue to verify after the argon2 default change. They are transparently rehashed to argon2id on the user's next successful login.
 
 2FA:
 - `SECURITY_TWO_FACTOR`
@@ -155,6 +139,10 @@ Core:
 - `SECURITY_MULTI_FACTOR_RECOVERY_CODES`
 - `SECURITY_MULTI_FACTOR_RECOVERY_CODES_N`
 
+Recovery codes are displayed only when generated and are stored as keyed hashes.
+Existing plaintext codes remain valid until their next successful use, when the
+remaining codes are migrated.
+
 WebAuthn:
 - `SECURITY_WEBAUTHN`
 - `SECURITY_WAN_ALLOW_AS_FIRST_FACTOR`
@@ -173,7 +161,7 @@ Routing:
 Core:
 - `/login`
 - `/register`
-- `/logout`
+- `/logout` (POST only)
 - `/change`
 
 2FA:
@@ -251,4 +239,3 @@ Run this in a HTTPS staging environment with production-like hostnames and real
 - Run behind HTTPS for WebAuthn in non-local environments.
 - Set explicit WebAuthn RP values (`SECURITY_WAN_RP_ID`, `SECURITY_WAN_EXPECTED_ORIGIN`) when behind proxies or multiple domains.
 - Keep CSRF protection enabled unless you have a deliberate replacement.
-

{quart_security-1.3.0 → quart_security-1.4.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "flit_core.buildapi"
 
 [project]
 name = "quart-security"
-version = "1.3.0"
+version = "1.4.1"
 description = "Native async auth for Quart"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -18,12 +18,13 @@ dependencies = [
   "libpass>=1.9",
   "pyotp>=2.9",
   "qrcode>=8.0",
-  "webauthn>=2.0",
+  "webauthn>=2.7",
   "wtforms>=3.1",
   "aiosmtplib>=3.0",
   "blinker>=1.7",
-  "itsdangerous>=2.1",
   "email-validator>=2.0",
+  "argon2-cffi>=23.1",
+  "httpx>=0.27",
 ]
 
 [project.optional-dependencies]
@@ -45,6 +46,7 @@ name = "quart_security"
 dev = [
   "pytest>=8.0",
   "pytest-asyncio>=0.23",
+  "respx>=0.23.1",
   "ruff>=0.6",
 ]
 

{quart_security-1.3.0 → quart_security-1.4.1}/quart_security/__init__.py

@@ -4,7 +4,12 @@ from .core import Security
 from .datastore import SQLAlchemyUserDatastore
 from .decorators import auth_required, roles_required
 from .models import RoleMixin, UserMixin
-from .password import hash_password, verify_password
+from .password import (
+    hash_password,
+    hash_password_async,
+    verify_password,
+    verify_password_async,
+)
 from .proxies import current_user
 from .signals import (
     password_changed,
@@ -23,7 +28,9 @@ __all__ = [
     "UserMixin",
     "RoleMixin",
     "hash_password",
+    "hash_password_async",
     "verify_password",
+    "verify_password_async",
     "current_user",
     "user_authenticated",
     "user_logged_out",

quart_security-1.4.1/quart_security/breach.py

@@ -0,0 +1,61 @@
+"""HIBP k-anonymity breach check (NIST 800-63B-4 SHALL)."""
+
+from __future__ import annotations
+
+import hashlib
+import logging
+
+import httpx
+
+logger = logging.getLogger(__name__)
+
+_HIBP_URL = "https://api.pwnedpasswords.com/range/{prefix}"
+_TIMEOUT = 3.0
+
+
+async def password_is_breached(password: str, *, count_min: int = 1) -> bool | None:
+    """Check whether *password* appears in the HIBP breach corpus.
+
+    Uses the k-anonymity range API: sends only the first 5 hex chars of the
+    SHA-1 digest. The full digest never leaves the process.
+
+    Returns:
+        True  - password appears >= count_min times.
+        False - password not found in response.
+        None  - network/HTTP error; caller should fail-open (allow the password).
+    """
+    sha1 = (
+        hashlib.sha1(password.encode("utf-8"), usedforsecurity=False)
+        .hexdigest()
+        .upper()
+    )
+    prefix, suffix = sha1[:5], sha1[5:]
+
+    try:
+        async with httpx.AsyncClient(timeout=_TIMEOUT) as client:
+            response = await client.get(
+                _HIBP_URL.format(prefix=prefix),
+                headers={"Add-Padding": "true"},
+            )
+            response.raise_for_status()
+    except Exception as exc:
+        logger.warning(
+            "HIBP breach check failed (%s: %s); failing open",
+            type(exc).__name__,
+            exc,
+        )
+        return None
+
+    for line in response.text.splitlines():
+        parts = line.split(":", 1)
+        if len(parts) != 2:
+            continue
+        candidate, raw_count = parts[0].strip(), parts[1].strip()
+        if candidate == suffix:
+            try:
+                count = int(raw_count)
+            except ValueError:
+                continue
+            return count >= count_min
+
+    return False

{quart_security-1.3.0 → quart_security-1.4.1}/quart_security/core.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import secrets
+import time
 from datetime import timedelta
 
 from quart import current_app, g, request, session
@@ -111,14 +112,15 @@ class Security:
     @staticmethod
     def _load_defaults(app):
         defaults = {
-            "SECURITY_PASSWORD_HASH": "pbkdf2_sha512",
+            "SECURITY_PASSWORD_HASH": "argon2",
+            "SECURITY_PASSWORD_BREACH_CHECK": True,
+            "SECURITY_PASSWORD_BREACH_COUNT_MIN": 1,
             "SECURITY_PASSWORD_LENGTH_MIN": 12,
             "SECURITY_REGISTERABLE": True,
             "SECURITY_CHANGEABLE": True,
             "SECURITY_TRACKABLE": True,
             "SECURITY_TWO_FACTOR": True,
             "SECURITY_WEBAUTHN": True,
-            "SECURITY_TWO_FACTOR_ENABLED_METHODS": ["authenticator"],
             "SECURITY_TOTP_ISSUER": "Quart",
             "SECURITY_MULTI_FACTOR_RECOVERY_CODES": True,
             "SECURITY_MULTI_FACTOR_RECOVERY_CODES_N": 3,
@@ -135,9 +137,7 @@ class Security:
             "SECURITY_POST_LOGIN_VIEW": "/",
             "SECURITY_POST_REGISTER_VIEW": "/login",
             "SECURITY_EMAIL_SENDER": "noreply@example.com",
-            "SECURITY_SEND_PASSWORD_CHANGE_EMAIL": False,
             "SECURITY_CSRF_PROTECT": True,
-            "SECURITY_API_ENABLED_METHODS": ["session"],
         }
 
         for key, value in defaults.items():
@@ -150,7 +150,11 @@ class Security:
             return
 
         user = await maybe_await(self.datastore.find_user(fs_uniquifier=user_id))
-        g._current_user = user or AnonymousUser()
+        if user is None or not getattr(user, "active", True):
+            session.clear()
+            g._current_user = AnonymousUser()
+            return
+        g._current_user = user
 
     async def login_user(self, user, fresh=True):
         app = current_app._get_current_object()
@@ -161,9 +165,14 @@ class Security:
         if not user_id:
             raise RuntimeError("User must have fs_uniquifier/get_id for session login")
 
+        # Regenerate session to prevent fixation: discard pre-login state,
+        # then write only the login keys into a clean session.
+        session.clear()
         session["_user_id"] = user_id
         session["_fresh"] = bool(fresh)
+        session["_auth_at"] = int(time.time())
         session["_id"] = secrets.token_hex(16)
+        session.modified = True
         g._current_user = user
 
         if app.config.get("SECURITY_TRACKABLE", True):

{quart_security-1.3.0 → quart_security-1.4.1}/quart_security/datastore.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+from contextvars import ContextVar
 from uuid import uuid4
 
 from sqlalchemy import select
@@ -15,10 +16,19 @@ class SQLAlchemyUserDatastore:
         self.user_model = user_model
         self.role_model = role_model
         self.webauthn_model = webauthn_model
+        self._active_session = ContextVar("quart_security_session", default=None)
 
     @property
     def session(self):
-        return self.session_factory()
+        source = self.session_factory
+        configured = getattr(source, "session", None)
+        if configured is not None:
+            return configured
+        active = self._active_session.get()
+        if active is None:
+            active = source() if callable(source) else source
+            self._active_session.set(active)
+        return active
 
     async def _first(self, model, **kwargs):
         stmt = select(model).filter_by(**kwargs)
@@ -130,6 +140,18 @@ class SQLAlchemyUserDatastore:
                 return credential
         return None
 
+    async def find_user_for_webauthn_credential(self, credential):
+        related_user = getattr(credential, "user", None)
+        if related_user is not None:
+            return related_user
+        owner_id = getattr(credential, "user_id", None)
+        if owner_id is None:
+            return None
+        user = await self.find_user(fs_webauthn_user_handle=owner_id)
+        if user is None and hasattr(self.user_model, "id"):
+            user = await self.find_user(id=owner_id)
+        return user
+
     async def create_webauthn_credential(self, user, **kwargs):
         if self.webauthn_model is None:
             raise RuntimeError("webauthn_model is required for WebAuthn credentials")
@@ -168,4 +190,8 @@ class SQLAlchemyUserDatastore:
         return True
 
     async def commit(self):
-        await self.session.commit()
+        active = self.session
+        try:
+            await active.commit()
+        finally:
+            self._active_session.set(None)

{quart_security-1.3.0 → quart_security-1.4.1}/quart_security/decorators.py

@@ -1,14 +1,16 @@
 """Authentication and authorization decorators."""
 
+import datetime
+import time
 from functools import wraps
 
-from quart import abort, current_app, redirect, request
+from quart import abort, current_app, redirect, request, session
 
 from .proxies import current_user
 from .utils import url_for_security
 
 
-def auth_required(*methods):
+def auth_required(*methods, fresh=False):
     """Require an authenticated user for a route."""
 
     allowed_methods = methods or ("session",)
@@ -22,6 +24,15 @@ def auth_required(*methods):
                 if request.is_json:
                     abort(401)
                 return redirect(url_for_security("login", next=request.url))
+            if fresh:
+                freshness = current_app.config.get(
+                    "SECURITY_FRESHNESS", datetime.timedelta(minutes=60)
+                )
+                max_age = freshness.total_seconds()
+                authenticated_at = session.get("_auth_at", 0)
+                is_stale = time.time() - authenticated_at > max_age
+                if not session.get("_fresh") or is_stale:
+                    abort(401)
             return await current_app.ensure_async(func)(*args, **kwargs)
 
         return wrapper

{quart_security-1.3.0 → quart_security-1.4.1}/quart_security/forms.py

@@ -109,5 +109,4 @@ class WebAuthnRegisterForm(QuartForm):
 
 class WebAuthnVerifyForm(QuartForm):
     identity = StringField("Email", validators=[Optional()])
-    remember = BooleanField("Remember me")
     credential = StringField("Credential", validators=[Optional()])

quart_security-1.4.1/quart_security/password.py

@@ -0,0 +1,90 @@
+"""Password hashing and validation helpers."""
+
+import asyncio
+
+from passlib.context import CryptContext
+
+_pwd_context: CryptContext | None = None
+_password_salt: str | None = None
+
+# OWASP 2025 minimum argon2id parameters
+_ARGON2_MEMORY_COST = 19456  # KiB
+_ARGON2_TIME_COST = 2
+_ARGON2_PARALLELISM = 1
+
+
+def init_password_context(app):
+    """Initialize passlib context from app config.
+
+    Default scheme is argon2id (OWASP 2025). Existing pbkdf2_sha512 and bcrypt
+    hashes continue to verify and are transparently rehashed on next login when
+    password_needs_rehash() returns True.
+
+    Set SECURITY_PASSWORD_HASH to override the default scheme.
+    Set SECURITY_ARGON2_MEMORY_COST / _TIME_COST / _PARALLELISM to override
+    argon2 parameters (useful for test environments).
+    """
+    global _pwd_context, _password_salt
+
+    scheme = app.config.get("SECURITY_PASSWORD_HASH", "argon2")
+    _password_salt = app.config.get("SECURITY_PASSWORD_SALT")
+
+    memory_cost = app.config.get("SECURITY_ARGON2_MEMORY_COST", _ARGON2_MEMORY_COST)
+    time_cost = app.config.get("SECURITY_ARGON2_TIME_COST", _ARGON2_TIME_COST)
+    parallelism = app.config.get("SECURITY_ARGON2_PARALLELISM", _ARGON2_PARALLELISM)
+
+    # Build context: argon2 with OWASP params, legacy schemes deprecated.
+    # CryptContext handles per-scheme kwargs via <scheme>__<param> notation.
+    _pwd_context = CryptContext(
+        schemes=["argon2", "pbkdf2_sha512", "bcrypt"],
+        default=scheme,
+        deprecated="auto",
+        argon2__memory_cost=memory_cost,
+        argon2__time_cost=time_cost,
+        argon2__parallelism=parallelism,
+        argon2__type="id",
+    )
+
+
+def _ensure_context() -> CryptContext:
+    if _pwd_context is None:
+        raise RuntimeError("Password context is not initialized")
+    return _pwd_context
+
+
+def hash_password(password: str) -> str:
+    return _ensure_context().hash(password)
+
+
+def verify_password(password: str, password_hash: str) -> bool:
+    context = _ensure_context()
+    if context.verify(password, password_hash):
+        return True
+    # Optional fallback for deployments that previously mixed in app salt.
+    if _password_salt:
+        return context.verify(f"{password}{_password_salt}", password_hash)
+    return False
+
+
+def password_needs_rehash(password_hash: str) -> bool:
+    """Return True if the hash was made with a deprecated/weaker scheme.
+
+    Call this after a successful verify to decide whether to upgrade the
+    stored hash transparently on login.
+    """
+    return _ensure_context().needs_update(password_hash)
+
+
+async def hash_password_async(password: str) -> str:
+    return await asyncio.to_thread(hash_password, password)
+
+
+async def verify_password_async(password: str, password_hash: str) -> bool:
+    return await asyncio.to_thread(verify_password, password, password_hash)
+
+
+def validate_password(password: str, min_length: int = 12) -> list[str]:
+    errors: list[str] = []
+    if len(password) < min_length:
+        errors.append(f"Password must be at least {min_length} characters")
+    return errors

{quart_security-1.3.0 → quart_security-1.4.1}/quart_security/templates/security/mf_recovery_codes.html

@@ -8,6 +8,6 @@
   {% endfor %}
 </ul>
 <form method="post" action="{{ url_for_security('mf_recovery_codes') }}">
-  <input id="csrf_token" name="csrf_token" type="hidden" value="{{ csrf_token }}">
+  {{ mf_recovery_codes_form.hidden_tag() }}
   <button type="submit">Regenerate codes</button>
 </form>

quart_security-1.4.1/quart_security/totp.py

@@ -0,0 +1,110 @@
+"""TOTP and recovery-code helpers."""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import hmac
+import io
+import secrets
+
+
+def _require_pyotp():
+    try:
+        import pyotp
+    except ImportError as exc:
+        raise RuntimeError("pyotp is required for TOTP support") from exc
+    return pyotp
+
+
+def generate_totp_secret() -> str:
+    pyotp = _require_pyotp()
+    return pyotp.random_base32()
+
+
+def get_totp_uri(secret: str, email: str, issuer: str) -> str:
+    pyotp = _require_pyotp()
+    return pyotp.totp.TOTP(secret).provisioning_uri(name=email, issuer_name=issuer)
+
+
+def generate_qr_code(uri: str) -> str:
+    try:
+        import qrcode
+    except ImportError as exc:
+        raise RuntimeError("qrcode is required for QR generation") from exc
+
+    image = qrcode.make(uri)
+    buffer = io.BytesIO()
+    image.save(buffer, format="PNG")
+    b64 = base64.b64encode(buffer.getvalue()).decode("utf-8")
+    return f"data:image/png;base64,{b64}"
+
+
+def verify_totp(secret: str, token: str) -> bool:
+    pyotp = _require_pyotp()
+    totp = pyotp.TOTP(secret)
+    return bool(totp.verify(token, valid_window=1))
+
+
+def generate_recovery_codes(n: int = 3) -> list[str]:
+    codes = []
+    for _ in range(n):
+        raw = secrets.token_hex(5)
+        codes.append(f"{raw[:5]}-{raw[5:]}")
+    return codes
+
+
+_RECOVERY_HASH_PREFIX = "hmac-sha256$"
+
+
+def _normalize_recovery_code(code: str) -> str:
+    return code.strip().lower().replace("-", "").replace(" ", "")
+
+
+def _recovery_digest(code: str, secret_key: bytes | str) -> str:
+    if isinstance(secret_key, str):
+        secret_key = secret_key.encode()
+    digest = hmac.new(
+        secret_key, _normalize_recovery_code(code).encode(), hashlib.sha256
+    ).hexdigest()
+    return f"{_RECOVERY_HASH_PREFIX}{digest}"
+
+
+def hash_recovery_codes(codes: list[str], secret_key: bytes | str) -> list[str]:
+    return [_recovery_digest(code, secret_key) for code in codes]
+
+
+def ensure_hashed_recovery_codes(
+    codes: list[str], secret_key: bytes | str
+) -> list[str]:
+    return [
+        code if is_hashed_recovery_code(code) else _recovery_digest(code, secret_key)
+        for code in codes
+    ]
+
+
+def is_hashed_recovery_code(code: str) -> bool:
+    return code.startswith(_RECOVERY_HASH_PREFIX)
+
+
+def verify_recovery_code(
+    code: str, stored_codes: list[str], *, secret_key: bytes | str = b""
+) -> tuple[bool, list[str]]:
+    normalized = code.strip().lower().replace("-", "").replace(" ", "")
+    submitted_hash = _recovery_digest(code, secret_key)
+    matched_index = -1
+    for i, stored in enumerate(stored_codes):
+        stored_normalized = _normalize_recovery_code(stored)
+        # compare_digest on every entry — no early exit
+        matches_plaintext = not is_hashed_recovery_code(
+            stored
+        ) and secrets.compare_digest(normalized, stored_normalized)
+        matches_hash = is_hashed_recovery_code(stored) and secrets.compare_digest(
+            submitted_hash, stored
+        )
+        if matches_plaintext or matches_hash:
+            matched_index = i
+    if matched_index >= 0:
+        remaining = [item for i, item in enumerate(stored_codes) if i != matched_index]
+        return True, remaining
+    return False, stored_codes