feat(security): opt-in per-account login lockout

Add AccountLockoutConfig (disabled by default) that locks an account
after N failed password logins for a TTL window. Pluggable
AccountLockoutStore with in-memory and Redis (atomic Lua) backends;
account keys are non-reversible keyed digests. Locked accounts return the
generic bad-credentials response within the existing response-time padding
(non-enumerating, no timing oracle). Complements, not replaces,
IP/identifier rate limiting. Existing apps unaffected unless enabled.

Author: shepilov-vladislav

CHANGELOG.md

@@ -1,3 +1,26 @@
+## Unreleased
+
+### Added
+
+- **Opt-in per-account login lockout.** New `AccountLockoutConfig` on `LitestarAuthConfig`
+  (`account_lockout_config`, disabled by default) locks an account key after `failure_threshold`
+  failed password logins (default **5**) for a `window_seconds` TTL (default **900s**). Lockout state lives behind the new
+  `AccountLockoutStore` protocol with bundled `InMemoryAccountLockoutStore` and `RedisAccountLockoutStore`
+  backends (or a custom `store_factory`), all exported from `litestar_auth.ratelimit`. Account keys are
+  non-reversible keyed digests of the login identifier (`account_lockout_key`), so the store never holds a
+  plaintext email/username; enabling lockout requires an `account_lockout_key_secret` (startup fails closed
+  with `ConfigurationError` otherwise). This complements — it does not replace — the existing IP/identifier
+  rate limiting, covering distributed brute force against a single account that per-IP limits miss.
+
+### Security
+
+- **Account lockout is non-enumerating and timing-safe.** A locked account, a wrong password, and an
+  unknown identifier all return the same generic bad-credentials response, and the lockout check runs inside
+  the existing minimum-response-time padding so the short-circuited locked path is not a timing oracle. The
+  failure counter resets on successful authentication; the Redis backend increments and checks atomically via
+  Lua so multi-worker deployments share one consistent count (the in-memory backend is process-local and
+  warns when used across workers).
+
 ## 5.0.3 (2026-06-13)
 
 ### Added

docs/configuration/security.md

@@ -14,6 +14,7 @@ Use this page for CSRF settings, token downgrade policy, schemas, dependency key
 | `verify_minimum_response_seconds` | `0.4` | Minimum wall-clock duration for plugin-owned `POST /auth/verify` success and invalid-token responses. |
 | `request_verify_minimum_response_seconds` | `0.4` | Minimum wall-clock duration for plugin-owned `POST /auth/request-verify-token` responses, including manager failures after rate-limit accounting runs. |
 | `id_parser` | `None` | Parse path/query user ids (e.g. `UUID`). Effective parser: `user_manager_security.id_parser` when set; otherwise `LitestarAuthConfig.id_parser` is applied (including the no-`user_manager_security` default builder path). |
+| `account_lockout_config` | `AccountLockoutConfig()` | Opt-in per-account password-login lockout. Disabled by default; when enabled it uses `failure_threshold=5`, `window_seconds=900.0`, and an in-memory store unless `store_factory` supplies a shared store. |
 
 ### CSRF cookie name and login telemetry
 
@@ -28,6 +29,99 @@ Set optional `UserManagerSecurity.login_identifier_telemetry_secret` so structur
 an HMAC digest of the identifier on failures (no raw identifier in logs). Details:
 [Manager customization — Login failure telemetry secret](manager.md#login-failure-telemetry-secret).
 
+### Per-account password-login lockout
+
+`LitestarAuthConfig.account_lockout_config` enables a per-account counter for plugin-owned password
+login failures. It is separate from IP/request rate limiting: account lockout tracks the normalized
+login identifier behind a keyed digest, while `rate_limit_config.login` still throttles by its
+configured request identity.
+
+The shipped fields are:
+
+| `AccountLockoutConfig` field | Default | Meaning |
+| ---------------------------- | ------- | ------- |
+| `enabled` | `False` | Leaves account lockout inert unless explicitly enabled. |
+| `failure_threshold` | `5` | Number of failed password checks for the same account key before the key is locked. |
+| `window_seconds` | `900.0` | Counter TTL and lockout window in seconds. A successful password login before the threshold resets the counter. |
+| `store_factory` | `None` | Optional zero-argument factory returning an `AccountLockoutStore`. When omitted, the config memoizes an `InMemoryAccountLockoutStore`. |
+
+Plugin-managed lockout key derivation uses
+`UserManagerSecurity.login_identifier_telemetry_secret`. Set a high-entropy, role-separated value
+before enabling lockout:
+
+```python
+from litestar_auth import LitestarAuthConfig, UserManagerSecurity
+from litestar_auth.ratelimit import AccountLockoutConfig
+
+config = LitestarAuthConfig(
+    user_model=User,
+    user_manager_class=UserManager,
+    session_maker=session_maker,
+    account_lockout_config=AccountLockoutConfig(enabled=True),
+    user_manager_security=UserManagerSecurity(
+        login_identifier_telemetry_secret=login_identifier_secret,
+        reset_password_token_secret=reset_password_secret,
+        verification_token_secret=verification_token_secret,
+    ),
+)
+```
+
+The default `InMemoryAccountLockoutStore` is process-local. It is appropriate for single-process
+development, tests, and deployments that explicitly accept single-worker state. Production
+multi-worker deployments need a shared store such as `RedisAccountLockoutStore`; when
+`deployment_worker_count > 1`, plugin startup fails closed if enabled account lockout resolves to a
+process-local store.
+
+The in-memory store also has a bounded key capacity. If it reaches `max_keys` after expired counters
+are pruned, unknown account keys are treated as locked and the login path fails closed. That protects
+existing lockout counters from being dropped under capacity pressure, but a flood of distinct
+identifiers can deny new logins until counters expire. For publicly exposed, high-volume, or
+multi-tenant deployments, prefer `RedisAccountLockoutStore`; if you intentionally keep the in-memory
+store, supply it through `store_factory` with a `max_keys` sized for the expected identifier
+cardinality and memory budget:
+
+```python
+from litestar_auth.ratelimit import AccountLockoutConfig, InMemoryAccountLockoutStore
+
+account_lockout_config = AccountLockoutConfig(
+    enabled=True,
+    failure_threshold=5,
+    window_seconds=900.0,
+    store_factory=lambda: InMemoryAccountLockoutStore(
+        failure_threshold=5,
+        window_seconds=900.0,
+        max_keys=500_000,
+    ),
+)
+```
+
+```python
+from litestar_auth.ratelimit import AccountLockoutConfig, RedisAccountLockoutStore
+
+account_lockout_config = AccountLockoutConfig(
+    enabled=True,
+    failure_threshold=5,
+    window_seconds=900.0,
+    store_factory=lambda: RedisAccountLockoutStore(
+        redis=redis_client,
+        failure_threshold=5,
+        window_seconds=900.0,
+    ),
+)
+```
+
+Locked accounts intentionally receive the same `LOGIN_BAD_CREDENTIALS` response as a wrong password
+or missing user. The response has no lockout-specific status, error code, or `Retry-After` header, so
+attackers cannot distinguish account existence or lock state through the login endpoint.
+
+This non-enumerating property is *timing*-safe only while `login_minimum_response_seconds` dominates
+the Argon2 verification cost. A locked account short-circuits before password hashing, whereas wrong-password
+and unknown-account failures both pay the Argon2 verification; the shared response-time floor pads all three
+paths (including the locked short-circuit) to the same duration, masking the difference. The default `0.4s`
+floor comfortably exceeds typical Argon2 cost. If you lower it below your Argon2 verification time the locked
+path becomes timing-distinguishable, reopening account enumeration — plugin startup emits a `SecurityWarning`
+when account lockout is enabled and `login_minimum_response_seconds` is below `0.2s` for this reason.
+
 The plugin-managed JWT/TOTP security surfaces use the same shared posture wording as runtime startup and validation:
 
 --8<-- "docs/snippets/plugin_security_tradeoffs.md"

docs/roadmap.md

@@ -4,7 +4,7 @@ What this library aims to cover today, what it deliberately does not include, an
 
 ## In scope today
 
-Registration, login/logout, email verification and password reset, Bearer / cookie / API-key transports, JWT / database / Redis / API-key strategies, guards, role-derived permission authorization, optional user CRUD, TOTP, OAuth login and account linking, rate limiting, hooks, configurable login identifier (`email` or `username`). See [Features on the home page](index.md).
+Registration, login/logout, email verification and password reset, Bearer / cookie / API-key transports, JWT / database / Redis / API-key strategies, guards, role-derived permission authorization, optional user CRUD, TOTP, OAuth login and account linking, rate limiting, per-account password-login lockout, hooks, configurable login identifier (`email` or `username`). See [Features on the home page](index.md).
 
 Opt-in **multi-tenant organizations** (roadmap #10) are complete for the library's intended scope:
 global `User` plus `OrganizationMembership`, tenant resolution, verified current-organization
@@ -16,6 +16,12 @@ applications deliver the raw token from `on_after_organization_invitation`. Appl
 isolation remains the application's responsibility: the library does not add tenant foreign keys,
 mutate application queries, or filter application-owned tables.
 
+Opt-in **per-account brute-force protection** is delivered for plugin-owned password login through
+`AccountLockoutConfig`. The library ships digest-only account keys, process-local in-memory storage
+for single-worker deployments, Redis-backed shared storage for multi-worker deployments, generic
+non-enumerating login failures for locked accounts, and independent composition with auth endpoint
+rate limiting.
+
 ## Explicitly out of scope (library core)
 
 - Built-in **email transport** (use hooks).

docs/security.md

@@ -37,6 +37,12 @@ Before production rollout, verify the deployment-owned security contract in
 - **Failed-login telemetry** — failed-login logs never include the submitted email/username. Configure
   `UserManagerSecurity.login_identifier_telemetry_secret` when you want a stable, non-reversible
   `identifier_digest`; the digest is omitted when that dedicated secret is unset.
+- **Per-account lockout** — optional password-login brute-force protection through
+  `AccountLockoutConfig`. It is disabled by default; when enabled, login identifiers are normalized
+  and stored only as keyed digests, repeated failed password checks lock that account key for the
+  configured window, and a successful password login before lockout resets the counter. Locked
+  accounts deliberately return the same `LOGIN_BAD_CREDENTIALS` response as wrong credentials or a
+  missing user, without a distinct lockout code, status, or `Retry-After` header.
 - **Rate limiting** — optional per-endpoint limits; in-memory backend is single-process only and fails closed for new keys when its capacity cap is reached.
 - **Route-level role checks** — `is_superuser`, `has_any_role(...)`, and `has_all_roles(...)` reuse the same normalized flat-role semantics as persistence and manager writes, and they fail closed if the authenticated user does not expose the documented role-capable contract. Role guard matching uses fixed-work internal comparisons over normalized role strings to avoid role-membership short-circuit predicates; this is a defense-in-depth posture, not a claim of cryptographic constant-time behavior across Python or the network.
 
@@ -64,8 +70,9 @@ When you assemble `JWTStrategy` or `BaseUserManager` yourself, inspect the runti
   `TOTP_STEPUP_REQUIRED` 403 contract, default endpoint policies, recovery-code behavior, and the
   API-key transport rationale.
 - `BaseUserManager` uses `UserManagerSecurity.login_identifier_telemetry_secret` only for
-  failed-login identifier digests. It is optional; omitting it keeps logs correlation-safe by
-  leaving `identifier_digest` out rather than reusing another auth secret.
+  failed-login identifier digests and plugin-managed account-lockout key derivation. It is optional
+  while lockout is disabled; enabling `AccountLockoutConfig` without this secret is rejected. Omit it
+  only when you do not need correlated failed-login telemetry and do not enable account lockout.
 
 ## OAuth redirect-host DNS validation
 
@@ -124,6 +131,7 @@ Additional opt-ins to weaker behavior:
 | `CookieTransport(allow_insecure_cookie_auth=True)` | Allows cookie auth without CSRF for controlled non-browser scenarios only. |
 | `ApiKeyConfig(signing_enabled=True, secret_encryption_keyring=...)` | Enables request signing, but stores an encrypted copy of signing-required key secrets so signatures can be verified. |
 | `InMemoryApiKeyNonceStore` | Process-local API-key signing replay cache; use `RedisApiKeyNonceStore` for multi-worker deployments. |
+| `AccountLockoutConfig(enabled=True)` with the default in-memory store | Process-local per-account lockout counters; use `RedisAccountLockoutStore` for multi-worker deployments. |
 
 ## Bearer failure-code taxonomy
 
@@ -157,6 +165,10 @@ expired, timestamp-skewed, or nonce-replayed keys, still consume the limiter bef
 - No built-in **email** sending — you must implement hooks.
 - No **RBAC** or **WebAuthn** in core — the built-in role guards are flat membership checks only; extend in your application for permission matrices or object-level policy.
 - **Durable JWT revocation** requires a shared store — `JWTStrategy(secret=...)` without `denylist_store` or `allow_inmemory_denylist=True` fails closed at construction time. Use Redis (or equivalent) denylist for multi-worker production if you rely on revoke; reserve `allow_inmemory_denylist=True` for single-process development or tests.
+- **Per-account lockout** requires a shared store in multi-worker deployments. The default
+  `InMemoryAccountLockoutStore` is single-process only and is a development/single-worker tool; use
+  `RedisAccountLockoutStore` or a custom shared `AccountLockoutStore` when multiple workers can
+  receive login attempts for the same account.
 - **API keys** are user-owned delegated credentials only. Service-account-only keys, HKDF child keys,
   IP allowlists, per-key audit tables, and mTLS binding are outside this release.
 - API-key signing-secret rotation is operator-owned row processing. The library does not provide

litestar_auth/_keyed_digest.py

@@ -4,6 +4,13 @@
 
 import hashlib
 import hmac
+import unicodedata
+from typing import TYPE_CHECKING
+
+from litestar_auth._email import normalize_email
+
+if TYPE_CHECKING:
+    from litestar_auth.types import LoginIdentifier
 
 
 def keyed_bytes(key: bytes, payload: bytes) -> bytes:
@@ -19,6 +26,57 @@ def keyed_hex(key: bytes, *parts: bytes) -> str:
     return hmac_digest.hexdigest()
 
 
+def normalize_login_identifier(identifier: str) -> str:
+    """Return the canonical login identifier (stripped, casefolded) for keyed digests."""
+    return identifier.strip().casefold()
+
+
+def normalize_account_identifier(identifier: str, *, login_identifier: LoginIdentifier) -> str:
+    """Return the identifier normalized to mirror user-store identity resolution.
+
+    Account-keyed digests (e.g. lockout counters) must map 1:1 to the account the
+    store would resolve. Email mode applies the account email policy (NFKC +
+    lowercase); username mode applies the store's stripped + lowercase rule.
+    Mirroring the store -- rather than an independent ``casefold()`` -- closes two
+    normalization-drift gaps: an attacker can no longer mint multiple keys for one
+    account via NFKC/compatibility variants (lockout evasion), nor collide two
+    distinct accounts onto one key via casefold-vs-lower folding (e.g. German
+    sharp-s ``ß`` -> ``ss``).
+
+    Returns:
+        The store-equivalent normalized identifier.
+    """
+    if login_identifier == "email":
+        try:
+            return normalize_email(identifier)
+        except ValueError:
+            # Failed the stricter email policy, so the store lookup will also miss;
+            # fall back to the store-equivalent form (NFKC + lowercase) for a stable key.
+            return unicodedata.normalize("NFKC", identifier.strip()).lower()
+    # Username lookups intentionally skip NFKC to match UserPolicy.normalize_username_lookup.
+    return identifier.strip().lower()
+
+
+def keyed_account_identifier_hex(
+    key: str | bytes,
+    identifier: str,
+    *,
+    login_identifier: LoginIdentifier,
+    context: bytes,
+) -> str:
+    """Return a keyed digest for a login identifier under a domain-separation context.
+
+    The identifier is normalized to mirror user-store identity resolution (see
+    :func:`normalize_account_identifier`) so the digest is a faithful 1:1 account key.
+
+    Returns:
+        HMAC-SHA-256 hex digest of the store-normalized identifier under ``context``.
+    """
+    digest_key = key.encode("utf-8") if isinstance(key, str) else key
+    normalized_identifier = normalize_account_identifier(identifier, login_identifier=login_identifier).encode("utf-8")
+    return keyed_hex(digest_key, context, b"\x00", normalized_identifier)
+
+
 def hkdf_sha256_32(key_material: bytes, *, salt: bytes, info: bytes) -> bytes:
     """Derive a 32-byte HKDF-SHA256 output with explicit domain separation.
 

litestar_auth/_manager/construction.py

@@ -8,6 +8,7 @@
 from datetime import timedelta
 from typing import TYPE_CHECKING, Any, Protocol, TypedDict
 
+from litestar_auth._keyed_digest import normalize_login_identifier
 from litestar_auth._manager.security import validate_user_manager_security_secret_roles_are_distinct
 from litestar_auth._manager.user_policy import DEFAULT_CREATABLE_FIELDS, DEFAULT_UPDATABLE_FIELDS, UserFieldPolicy
 from litestar_auth._superuser_role import DEFAULT_SUPERUSER_ROLE_NAME
@@ -146,7 +147,7 @@ def resolve_oauth_account_store[UP: UserProtocol[Any], ID](
 
 def login_identifier_digest(identifier: str, *, key: str) -> str:
     """Return a keyed, non-reversible digest for login-failure correlation."""
-    normalized_identifier = identifier.strip().casefold()
+    normalized_identifier = normalize_login_identifier(identifier)
     digest_key = hashlib.sha256(key.encode()).digest()
     return hashlib.blake2b(
         normalized_identifier.encode(),

litestar_auth/_plugin/_hooks.py

@@ -99,6 +99,7 @@ class FeatureWiring:
         feature="core",
         before_startup=(
             "require_shared_rate_limit_backends_for_multiworker",
+            "require_shared_account_lockout_store_for_multiworker",
             "require_refreshable_strategy_when_enable_refresh",
             "warn_insecure_plugin_startup_defaults",
         ),

litestar_auth/_plugin/auth_controller.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 from collections.abc import Sequence
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from datetime import timedelta
 from typing import TYPE_CHECKING, Any
 
@@ -41,7 +41,7 @@
     from litestar.types import ExceptionHandlersMap
 
     from litestar_auth._plugin.config import StartupBackendInventory, StartupBackendTemplate
-    from litestar_auth.ratelimit import AuthRateLimitConfig
+    from litestar_auth.ratelimit import AccountLockoutConfig, AuthRateLimitConfig
     from litestar_auth.types import LoginIdentifier
 
 
@@ -57,6 +57,8 @@ class PluginAuthControllerSettings[UP: UserProtocol[Any], ID]:
     backend_inventory: StartupBackendInventory[UP, ID]
     backend_index: int
     rate_limit_config: AuthRateLimitConfig | None = None
+    account_lockout_config: AccountLockoutConfig | None = None
+    account_lockout_key_secret: str | None = field(default=None, repr=False)
     enable_refresh: bool = False
     requires_verification: bool = True
     login_identifier: LoginIdentifier = "email"
@@ -124,6 +126,8 @@ def _build_runtime_context(request_backend: AuthenticationBackend[UP, ID]) -> ob
             _AuthControllerSettings(
                 backend=request_backend,
                 rate_limit_config=settings.rate_limit_config,
+                account_lockout_config=settings.account_lockout_config,
+                account_lockout_key_secret=settings.account_lockout_key_secret,
                 enable_refresh=settings.enable_refresh,
                 requires_verification=settings.requires_verification,
                 login_identifier=settings.login_identifier,

litestar_auth/_plugin/config/__init__.py

@@ -82,6 +82,9 @@
 from litestar_auth._plugin.config._core import (
     OAUTH_ASSOCIATE_USER_MANAGER_DEPENDENCY_KEY as OAUTH_ASSOCIATE_USER_MANAGER_DEPENDENCY_KEY,
 )
+from litestar_auth._plugin.config._core import (
+    AccountLockoutConfig as AccountLockoutConfig,
+)
 from litestar_auth._plugin.config._core import (
     ApiKeyConfig as ApiKeyConfig,
 )