From 7e3ae8897aaeb764f4e830c14d12e9efcab08c93 Mon Sep 17 00:00:00 2001
From: Anto Subash <antosubash@live.com>
Date: Mon, 19 Oct 2026 11:11:29 +0200
Subject: [PATCH 01/13] docs: login lockout design (#530)

Claude-Session: https://claude.ai/code/session_01M9neheZZEe3sVpDi2S3zT4
---
 .../specs/2026-10-19-login-lockout-design.md  | 141 ++++++++++++++++++
 1 file changed, 141 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-10-19-login-lockout-design.md

diff --git a/docs/superpowers/specs/2026-10-19-login-lockout-design.md b/docs/superpowers/specs/2026-10-19-login-lockout-design.md
new file mode 100644
index 000000000..1e322cc81
--- /dev/null
+++ b/docs/superpowers/specs/2026-10-19-login-lockout-design.md
@@ -0,0 +1,141 @@
+# Login lockout across workers and source IPs (GH #530)
+
+Approved 2026-10-19.
+
+## Problem
+
+`modules/users/users/auth_local/rate_limit.py` keeps failure counters and locks in
+process-local `TTLCache`s. The key is `username::ip`, and only
+`POST /api/users/auth/login` consults them. The consequences:
+
+- With N workers, the effective threshold is N× the configured one.
+- An attacker who rotates source IPs never trips the lock for an account.
+- A restart clears every lock.
+- `POST /api/users/auth/token` has no lockout and no throttle.
+- The stock fastapi-users route `/api/users/auth-inner/login` has no throttle.
+
+## Design
+
+### Tier 1 — account lock (database)
+
+New nullable columns on `users_user`, added by one Alembic migration in
+`host/migrations/versions/` that chains off the current users head:
+
+| column | type | default |
+|---|---|---|
+| `failed_login_count` | int, not null | `0` (server default) |
+| `last_failed_login_at` | `AwareDateTime`, nullable | — |
+| `locked_until` | `AwareDateTime`, nullable | — |
+
+On a failed password login for an existing user, a single
+`UPDATE users_user … RETURNING failed_login_count` does the bookkeeping:
+
+- It increments the count.
+- It resets the count to 1 when `last_failed_login_at` is older than
+  `login_rate_limit_window_seconds`.
+- It stamps `last_failed_login_at`.
+
+The update is atomic across workers. When the returned count reaches
+`login_lockout_account_failures`, the user row is loaded through the ORM and
+updated:
+
+- `locked_until` = now + `login_rate_limit_cooldown_seconds`;
+- `failed_login_count` = 0.
+
+Going through the ORM means the automatic audit capture records the lock.
+
+A successful login resets `failed_login_count` to 0 and clears
+`last_failed_login_at`.
+
+While `locked_until > now`, every password login for that account gets a 429,
+the correct password included. The response carries `Retry-After` and the
+existing detail, "Too many attempts — try again later".
+
+### Tier 2 — per-IP + account throttle (host rate-limit store)
+
+The existing "5 failures from one IP within the window" check moves onto the
+host's rate-limit `WindowStore`. That store is Redis-backed when `SM_REDIS_URL`
+is set and in-process otherwise. The framework exposes the store it already
+builds on `app.state.sm` (`rate_limit_store`); no new Redis client is created.
+
+The keys are:
+
+- `login:ip:<ip>:<username>` for failures from one IP.
+- `login:acct:<username>` for a username with **no** account. Unknown usernames
+  are counted against the account threshold here, so a 429 does not reveal
+  whether an account exists.
+
+A key that is over its limit refuses further attempts until its window ends.
+
+### Login paths
+
+Both login routes use one helper, `auth_local/lockout.py`:
+
+- **`/api/users/auth/login`** (session login).
+- **`/api/users/auth/token`** — gains both tiers. It returns 429 when locked, and
+  its existing 401 for bad credentials is unchanged.
+
+The steps, in order:
+
+1. Refuse if locked: tier 1 by `locked_until`, tier 2 by store keys.
+2. Authenticate.
+3. On failure, record it in both tiers.
+4. On success, reset tier 1.
+
+Two other changes to the login surface:
+
+- The stock `/api/users/auth-inner/login` is no longer mounted. Its logout
+  stays, unless nothing uses it either. The wrappers already shadow it, and its
+  callers are grepped first.
+- The in-process `LoginRateLimiter` is removed once nothing uses it.
+  `ThroughputLimiter` (register, forgot-password and the other routes) is
+  unchanged.
+
+### Settings (`UsersSettings`)
+
+- New: `login_lockout_account_failures: int = Field(10, ge=1)`.
+- Existing settings keep their meaning:
+  - `login_rate_limit_failures` (5) — tier-2 threshold.
+  - `login_rate_limit_window_seconds` (300) — window for both tiers.
+  - `login_rate_limit_cooldown_seconds` (900) — account lock length.
+
+The account default is 10 rather than the issue's 5. With 5, anyone who knows
+an email could lock its owner out from any network. Tier 2 still stops a single
+source after 5.
+
+### Admin
+
+- `PATCH /api/users/admin/{id}/unlock` clears `locked_until`,
+  `failed_login_count` and `last_failed_login_at` through the ORM, so the
+  unlock is audited.
+- `UserListItem` gains `locked_until`.
+- The user edit page shows "Locked until <time>" and an Unlock action.
+- The users list shows a "locked" badge.
+- All copy goes through i18n keys.
+
+### Audit
+
+Lock and unlock are ORM writes on `User`, so `snapshot_changes` records them.
+`failed_login_count` and `last_failed_login_at` are added to the excluded
+audit fields, so failed attempts don't flood the audit log.
+
+## Tests
+
+- **Acceptance:** with `login_lockout_account_failures=5`, five failures for
+  `alice` lock her. The failures come from 3 client IPs (via
+  `ASGITransport(client=…)`) and 2 app instances sharing one database file.
+  The lock survives building a fresh app on the same database.
+- `/auth/token` is refused with 429 while the account is locked.
+- A successful login resets the count, and an expired window restarts it.
+- Unknown usernames and locked accounts return the same 429.
+- Tier 2: 5 failures from one IP throttle that IP for that account, and a
+  different IP is still allowed until tier 1 trips.
+- Admin unlock clears the lock, and the lock and unlock audit rows exist. The
+  counter changes write no audit rows.
+- A vitest covers the edit page's locked state and the Unlock action.
+- Migration: `alembic check` is clean, and `make migrations-roundtrip-pg` passes
+  if Postgres is available.
+
+## Out of scope
+
+OAuth, Keycloak and invite-link sign-ins: they involve no password.

From b3b65bdae7a9465f6148701ef81623df691469c3 Mon Sep 17 00:00:00 2001
From: Anto Subash <antosubash@live.com>
Date: Mon, 19 Oct 2026 11:17:47 +0200
Subject: [PATCH 02/13] docs: login lockout implementation plan (#530)

Claude-Session: https://claude.ai/code/session_01M9neheZZEe3sVpDi2S3zT4
---
 .../plans/2026-10-19-login-lockout.md         | 680 ++++++++++++++++++
 1 file changed, 680 insertions(+)
 create mode 100644 docs/superpowers/plans/2026-10-19-login-lockout.md

diff --git a/docs/superpowers/plans/2026-10-19-login-lockout.md b/docs/superpowers/plans/2026-10-19-login-lockout.md
new file mode 100644
index 000000000..544761964
--- /dev/null
+++ b/docs/superpowers/plans/2026-10-19-login-lockout.md
@@ -0,0 +1,680 @@
+# Login Lockout Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Make password-login lockout hold across workers, source IPs and restarts, and cover every password login route (GH #530).
+
+**Architecture:** Tier 1 is an account lock stored on `users_user` (`failed_login_count`, `last_failed_login_at`, `locked_until`), bumped by one atomic `UPDATE … RETURNING` and locked through the ORM so the audit log sees it. Tier 2 is a per-IP-per-username throttle (plus an unknown-username counter) on the host's existing rate-limit `WindowStore`, which the framework now exposes as `app.state.sm.rate_limit_store`. One helper, `users/auth_local/lockout.py`, fronts `/api/users/auth/login` and `/api/users/auth/token`; the stock `/auth-inner` router and the in-process `LoginRateLimiter` go away.
+
+**Tech Stack:** FastAPI, SQLModel/SQLAlchemy 2 async, Alembic, Redis (optional, via the host store), React + Inertia + vitest.
+
+**Spec:** `docs/superpowers/specs/2026-10-19-login-lockout-design.md`
+
+## Global Constraints
+
+- New setting: `login_lockout_account_failures: int = Field(10, ge=1)` on `UsersSettings`.
+- Existing settings keep their meaning: `login_rate_limit_failures` (5) is the tier-2 threshold, `login_rate_limit_window_seconds` (300) is the window for both tiers, `login_rate_limit_cooldown_seconds` (900) is the account lock length.
+- Locked/throttled responses: HTTP 429, detail `"Too many attempts — try again later"`, `Retry-After` header (seconds, ≥ 1).
+- `/auth/token` keeps its 401 `"Invalid credentials"`; `/auth/login` keeps its 400 `LOGIN_BAD_CREDENTIALS`; `LOGIN_USER_NOT_VERIFIED` (400) never counts as a failure.
+- Store keys: `login:ip:<ip>:<username>` and `login:acct:<username>` (username lower-cased and stripped). No new Redis client.
+- Migration: one revision in `host/migrations/versions/`, `down_revision = "b5018b617142"` (the head of the chain holding the users revisions), no `branch_labels`.
+- `failed_login_count` and `last_failed_login_at` are excluded from audit diffs (`User.__audit_exclude_fields__`).
+- Admin unlock: `PATCH /api/users/admin/{id}/unlock`, ORM write, guarded by `users.manage` like its siblings.
+- 300-line cap on `.py`/`.ts`/`.tsx`; SQLModel only; framework never imports modules (SM009); every `.tsx` string through `t(keys…)`; test basenames globally unique (prefix `users_`).
+- Commit messages end with `Claude-Session: https://claude.ai/code/session_01M9neheZZEe3sVpDi2S3zT4`.
+
+## Review Focus
+
+1. Case/whitespace variants of the username (`Alice@Example.com `) must hit the same counters and the same lock as `alice@example.com`, on both routes. → Task 3 test `test_username_variants_share_one_counter`.
+2. Failure bookkeeping must survive the error response: the endpoint raises 400/401, the request session rolls back, and the count must still be there on the next request. → Task 4 test `test_failures_persist_across_requests` (the acceptance test also covers it).
+3. A Redis outage must not turn login into a 500 nor drop the throttle: `peek` must fall back to per-worker counters exactly like `hit`. → Task 1 test `test_peek_falls_back_when_redis_down`.
+4. A successful login of a different user must not reset someone else's counter, and a correct password during a lock must not reset the count. → Task 4 test `test_correct_password_while_locked_does_not_unlock`.
+5. A lock that has expired must not show as locked in the admin UI, and must not refuse logins. → Task 5 test `test_expired_lock_is_not_reported` and Task 3 test `test_expired_lock_allows_login`.
+
+---
+
+### Task 1: Framework exposes the rate-limit store, with a non-counting `peek`
+
+**Files:**
+- Modify: `framework/core/simple_module_core/rate_limit.py` (protocol + `InProcessWindowStore.peek`)
+- Modify: `framework/hosting/simple_module_hosting/_rate_limit.py` (`RedisWindowStore.peek`, shared `_eval`)
+- Modify: `framework/core/simple_module_core/services.py` (`rate_limit_store` field)
+- Modify: `framework/hosting/simple_module_hosting/_phase_helpers.py` (`install_middleware(..., rate_limit_store=)`)
+- Modify: `framework/hosting/simple_module_hosting/app_builder.py` (build the store once, pass to both)
+- Test: `framework/hosting/tests/test_rate_limit_store_shared.py`
+
+**Interfaces:**
+- Produces: `WindowStore.peek(key: str, spec: RateSpec) -> WindowResult` — reports the current window **without counting**; `allowed` means "one more hit would be within budget" (`count < spec.limit`); `retry_after` is seconds left in the window (0 when no window is live). `Services.rate_limit_store: WindowStore` (defaults to a fresh `InProcessWindowStore`). The same store instance backs `RateLimitMiddleware`.
+
+- [ ] **Step 1: Write the failing tests**
+
+```python
+"""The host's rate-limit store is shared with modules (GH #530)."""
+
+from __future__ import annotations
+
+from simple_module_core.rate_limit import InProcessWindowStore, RateSpec
+from simple_module_core.services import Services
+from simple_module_hosting._rate_limit import RateLimitMiddleware, RedisWindowStore
+
+
+class _Clock:
+    def __init__(self) -> None:
+        self.now = 1_000.0
+
+    def __call__(self) -> float:
+        return self.now
+
+
+async def test_peek_does_not_count() -> None:
+    store = InProcessWindowStore(clock=_Clock())
+    spec = RateSpec(2, 60)
+    assert (await store.peek("k", spec)).count == 0
+    await store.hit("k", spec)
+    await store.hit("k", spec)
+    first = await store.peek("k", spec)
+    second = await store.peek("k", spec)
+    assert (first.count, first.allowed) == (2, False)
+    assert second.count == 2
+
+
+async def test_peek_window_expires() -> None:
+    clock = _Clock()
+    store = InProcessWindowStore(clock=clock)
+    spec = RateSpec(1, 60)
+    await store.hit("k", spec)
+    assert (await store.peek("k", spec)).retry_after == 60
+    clock.now += 61
+    result = await store.peek("k", spec)
+    assert (result.count, result.allowed, result.retry_after) == (0, True, 0)
+
+
+class _FakeRedis:
+    def __init__(self) -> None:
+        self.counts: dict[str, int] = {}
+
+    async def eval(self, script: str, numkeys: int, key: str, *args):
+        if args:  # hit
+            self.counts[key] = self.counts.get(key, 0) + 1
+            return [self.counts[key], args[0]]
+        count = self.counts.get(key)
+        return [0, -2] if count is None else [count, 30_000]
+
+
+class _DeadRedis:
+    async def eval(self, *a, **k):
+        raise ConnectionError("redis down")
+
+
+async def test_redis_peek_reads_without_counting() -> None:
+    redis = _FakeRedis()
+    store = RedisWindowStore(redis)
+    spec = RateSpec(1, 60)
+    assert (await store.peek("k", spec)).allowed is True
+    await store.hit("k", spec)
+    result = await store.peek("k", spec)
+    assert (result.count, result.allowed, result.retry_after) == (1, False, 30)
+    assert redis.counts == {"sm:rl:k": 1}
+
+
+async def test_peek_falls_back_when_redis_down() -> None:
+    store = RedisWindowStore(_DeadRedis())
+    spec = RateSpec(1, 60)
+    await store.hit("k", spec)  # counted by the per-worker fallback
+    assert (await store.peek("k", spec)).allowed is False
+
+
+def test_services_default_store() -> None:
+    field = Services.__dataclass_fields__["rate_limit_store"]
+    assert isinstance(field.default_factory(), InProcessWindowStore)
+
+
+async def test_create_app_shares_one_store(app) -> None:
+    store = app.state.sm.rate_limit_store
+    node = app.middleware_stack
+    while node is not None and not isinstance(node, RateLimitMiddleware):
+        node = getattr(node, "app", None)
+    assert node is not None and node.store is store
+```
+
+- [ ] **Step 2: Run to verify it fails**
+
+Run: `uv run pytest framework/hosting/tests/test_rate_limit_store_shared.py -q`
+Expected: FAIL — `AttributeError: 'InProcessWindowStore' object has no attribute 'peek'`, `KeyError: 'rate_limit_store'`.
+
+- [ ] **Step 3: Implement**
+
+`simple_module_core/rate_limit.py`:
+
+```python
+class WindowStore(Protocol):
+    async def hit(self, key: str, spec: RateSpec) -> WindowResult:
+        """Count one request against *key* and report whether it is within budget."""
+        ...
+
+    async def peek(self, key: str, spec: RateSpec) -> WindowResult:
+        """Report *key*'s current window without counting.
+
+        ``allowed`` answers "would one more hit be within budget", so a caller
+        can refuse before doing work and count only what failed.
+        """
+        ...
+
+# InProcessWindowStore
+    async def peek(self, key: str, spec: RateSpec) -> WindowResult:
+        now = self._clock()
+        entry = self._windows.get(key)
+        if entry is None or entry[0] <= now * 1000:
+            return WindowResult(allowed=spec.limit > 0, retry_after=0, count=0)
+        end_ms, count = entry
+        retry = max(1, math.ceil(end_ms / 1000 - now))
+        return WindowResult(allowed=count < spec.limit, retry_after=retry, count=count)
+```
+
+`simple_module_hosting/_rate_limit.py` — factor the Redis call and its fail-open handling into `_eval`, add the read-only script:
+
+```python
+_PEEK_LUA = """
+local c = redis.call('GET', KEYS[1])
+if not c then return {0, 0} end
+return {tonumber(c), redis.call('PTTL', KEYS[1])}
+"""
+
+    async def _eval(self, script: str, key: str, *args: Any) -> Any:
+        """Run *script* on *key*; ``None`` means "use the per-worker fallback"."""
+        if self._clock() < self._down_until:
+            return None
+        try:
+            return await self._client.eval(script, 1, _KEY_PREFIX + key, *args)
+        except Exception as exc:
+            now = self._clock()
+            self._down_until = now + _BACKOFF
+            if now - self._last_warn >= _WARN_EVERY:
+                self._last_warn = now
+                logger.warning(
+                    "Rate limiter Redis unavailable (%s); using per-worker counters", exc
+                )
+            return None
+
+    async def hit(self, key: str, spec: RateSpec) -> WindowResult:
+        reply = await self._eval(_LUA, key, spec.period * 1000)
+        if reply is None:
+            return await self._fallback.hit(key, spec)
+        count, pttl = int(reply[0]), int(reply[1])
+        retry = max(1, -(-pttl // 1000)) if pttl > 0 else spec.period
+        return WindowResult(allowed=count <= spec.limit, retry_after=retry, count=count)
+
+    async def peek(self, key: str, spec: RateSpec) -> WindowResult:
+        reply = await self._eval(_PEEK_LUA, key)
+        if reply is None:
+            return await self._fallback.peek(key, spec)
+        count, pttl = int(reply[0]), int(reply[1])
+        retry = max(1, -(-pttl // 1000)) if pttl > 0 else 0
+        return WindowResult(allowed=count < spec.limit, retry_after=retry, count=count)
+```
+
+`services.py` — new field after `view_prefixes`:
+
+```python
+    #: The store behind ``RateLimitMiddleware`` (Redis when ``SM_REDIS_URL`` is
+    #: set), shared so a module throttling its own events — the users login
+    #: lockout — counts in the same place across workers instead of opening a
+    #: second Redis client. Defaulted for apps built outside ``create_app``.
+    rate_limit_store: WindowStore = field(default_factory=InProcessWindowStore)
+```
+
+with `from simple_module_core.rate_limit import InProcessWindowStore, WindowStore` at runtime import level.
+
+`_phase_helpers.install_middleware` gains a keyword `rate_limit_store: WindowStore` and passes `store=rate_limit_store`; `app_builder.create_app` builds `rate_limit_store = build_store(settings.redis_url)` just before Phase 8, passes it to `install_middleware` and to `Services(rate_limit_store=rate_limit_store)`.
+
+- [ ] **Step 4: Run to verify it passes**
+
+Run: `uv run pytest framework/hosting/tests/test_rate_limit_store_shared.py framework/hosting/tests/test_request_guard_rate_limit.py -q`
+Expected: PASS.
+
+- [ ] **Step 5: Commit** — `feat(hosting): share the rate-limit store on app.state.sm (#530)`
+
+---
+
+### Task 2: Lockout columns on `users_user` + migration + audit exclusions
+
+**Files:**
+- Modify: `modules/users/users/models/user.py`
+- Create: `host/migrations/versions/c8e4f1a2b6d9_users_login_lockout.py`
+- Test: `modules/users/tests/test_users_lockout_columns.py`
+
+**Interfaces:**
+- Produces: `User.failed_login_count: int` (server default `0`), `User.last_failed_login_at: datetime | None`, `User.locked_until: datetime | None` (all `AwareDateTime`); `User.__audit_exclude_fields__ = {"failed_login_count", "last_failed_login_at"}`.
+
+- [ ] **Step 1: Write the failing test**
+
+```python
+"""Lockout columns on users_user (GH #530)."""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+
+from simple_module_db.audit import snapshot_changes
+from sqlalchemy import select
+from users.models import User
+
+
+async def test_new_user_starts_unlocked(users_db) -> None:
+    user = (await users_db.execute(select(User).limit(1))).scalar_one()
+    assert user.failed_login_count == 0
+    assert user.last_failed_login_at is None
+    assert user.locked_until is None
+
+
+async def test_counter_fields_are_not_audited(users_db) -> None:
+    user = (await users_db.execute(select(User).limit(1))).scalar_one()
+    user.failed_login_count = 3
+    user.last_failed_login_at = datetime.now(UTC)
+    assert snapshot_changes(users_db.sync_session, None, None) == []
+    user.locked_until = datetime.now(UTC)
+    [record] = snapshot_changes(users_db.sync_session, None, None)
+    assert [c["field"] for c in record.changes] == ["locked_until"]
+```
+
+(Adjust the change-dict key to whatever `snapshot_changes` emits — read `framework/db/simple_module_db/audit.py` first.)
+
+- [ ] **Step 2: Run** `uv run pytest modules/users/tests/test_users_lockout_columns.py -q` — Expected: FAIL (`AttributeError: failed_login_count`).
+
+- [ ] **Step 3: Implement** — on `User`:
+
+```python
+    # Login lockout (GH #530). The counter is bumped by one atomic UPDATE per
+    # failed password login, restarting once ``last_failed_login_at`` is older
+    # than the window; reaching the threshold stamps ``locked_until`` through
+    # the ORM so the lock is audited. See ``users.auth_local.lockout``.
+    failed_login_count: int = Field(default=0, sa_column_kwargs={"server_default": text("0")})
+    last_failed_login_at: datetime | None = Field(default=None, sa_type=AwareDateTime())
+    locked_until: datetime | None = Field(default=None, sa_type=AwareDateTime())
+
+    # Every wrong password writes these two; auditing them would bury the
+    # lock/unlock rows that matter under one row per failed attempt.
+    __audit_exclude_fields__: ClassVar[set[str]] = {"failed_login_count", "last_failed_login_at"}
+```
+
+Migration:
+
+```python
+"""users: login lockout columns (GH #530)
+
+Revision ID: c8e4f1a2b6d9
+Revises: b5018b617142
+"""
+
+revision: str = "c8e4f1a2b6d9"
+down_revision: str | None = "b5018b617142"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    with op.batch_alter_table("users_user") as batch:
+        batch.add_column(sa.Column("failed_login_count", sa.Integer(), nullable=False, server_default=sa.text("0")))
+        batch.add_column(sa.Column("last_failed_login_at", sa.DateTime(timezone=True), nullable=True))
+        batch.add_column(sa.Column("locked_until", sa.DateTime(timezone=True), nullable=True))
+
+
+def downgrade() -> None:
+    with op.batch_alter_table("users_user") as batch:
+        batch.drop_column("locked_until")
+        batch.drop_column("last_failed_login_at")
+        batch.drop_column("failed_login_count")
+```
+
+- [ ] **Step 4: Verify** — the test passes; on a scratch SQLite file: `SM_DATABASE_URL=sqlite+aiosqlite:////tmp/claude-1001/lockout/m.db uv run --project host alembic -c host/alembic.ini upgrade heads` then `… check` (only the known `users_access_token.expires_at` drift may remain); `make migrations-roundtrip-pg` with `SM_MIGRATIONS_PG_URL` on a disposable DB if Postgres is reachable.
+
+- [ ] **Step 5: Commit** — `feat(users): lockout columns on users_user (#530)`
+
+---
+
+### Task 3: Lockout service `users/auth_local/lockout.py`
+
+**Files:**
+- Create: `modules/users/users/auth_local/lockout.py`
+- Modify: `modules/users/users/settings.py` (`login_lockout_account_failures`)
+- Test: `modules/users/tests/test_users_lockout_service.py`
+
+**Interfaces:**
+- Consumes: `app.state.sm.rate_limit_store` (`hit`/`peek`, Task 1); `User` columns (Task 2).
+- Produces:
+  - `LOCKED_DETAIL = "Too many attempts — try again later"`
+  - `LoginAttempt(username, ip, store, settings, now)` (frozen dataclass)
+  - `login_attempt(request: Request, username: str) -> LoginAttempt`
+  - `async refused_for(session, attempt) -> int | None` — seconds to wait, `None` to proceed
+  - `async record_failure(session, attempt) -> None` — commits the session
+  - `async record_success(session, user_id) -> None` — no commit (rides the request's unit of work)
+  - `too_many_attempts(retry_after: int) -> HTTPException`
+  - module-level `_utcnow()` — the clock; tests monkeypatch it or build `LoginAttempt` with an explicit `now`.
+
+- [ ] **Step 1: Write the failing tests** (`users_db` + a `_settings(**overrides)` helper building `UsersSettings`, an `InProcessWindowStore`, `LoginAttempt` built directly with explicit `now`):
+
+```python
+async def test_account_locks_at_threshold(users_db, alice) -> None:
+    attempt = _attempt("alice@example.com", now=T0, account=3)
+    for _ in range(3):
+        await record_failure(users_db, attempt)
+    await users_db.refresh(alice)
+    assert alice.locked_until == T0 + timedelta(seconds=900)
+    assert alice.failed_login_count == 0
+    assert await refused_for(users_db, attempt) == 900
+
+
+async def test_expired_window_restarts_count(users_db, alice) -> None:
+    await record_failure(users_db, _attempt("alice@example.com", now=T0))
+    await record_failure(users_db, _attempt("alice@example.com", now=T0 + timedelta(seconds=301)))
+    await users_db.refresh(alice)
+    assert alice.failed_login_count == 1
+
+
+async def test_expired_lock_allows_login(users_db, alice) -> None:
+    ...  # lock at T0, refused_for at T0+901s is None
+
+
+async def test_success_resets_count(users_db, alice) -> None:
+    ...  # two failures, record_success, count 0 and last_failed_login_at None
+
+
+async def test_ip_throttle_after_tier2_limit(users_db, alice) -> None:
+    store = InProcessWindowStore()
+    for _ in range(5):
+        await record_failure(users_db, _attempt("alice@example.com", ip="1.1.1.1", store=store))
+    assert await refused_for(users_db, _attempt("alice@example.com", ip="1.1.1.1", store=store))
+    assert await refused_for(users_db, _attempt("alice@example.com", ip="2.2.2.2", store=store)) is None
+
+
+async def test_unknown_username_counts_against_account_threshold(users_db) -> None:
+    ...  # 10 failures for ghost@example.com from 10 IPs → refused_for is not None
+
+
+async def test_username_variants_share_one_counter(users_db, alice) -> None:
+    ...  # failures as " Alice@Example.COM " and "alice@example.com" add up on one row
+```
+
+- [ ] **Step 2: Run** — Expected: FAIL (`ModuleNotFoundError: users.auth_local.lockout`).
+
+- [ ] **Step 3: Implement** — settings:
+
+```python
+    # Rate limit (login). ``login_rate_limit_failures`` throttles one source
+    # (IP + username) on the shared rate-limit store; the account threshold
+    # locks the account itself, whichever networks the failures come from.
+    # 10 rather than 5: anyone who knows an address could otherwise lock its
+    # owner out. ``…_cooldown_seconds`` is how long that lock lasts.
+    login_rate_limit_failures: int = 5
+    login_rate_limit_window_seconds: int = 300
+    login_rate_limit_cooldown_seconds: int = 900
+    login_lockout_account_failures: int = Field(10, ge=1)
+```
+
+`lockout.py` core:
+
+```python
+def _by_username(username: str) -> Any:
+    return func.lower(User.email) == username
+
+
+async def refused_for(session: AsyncSession, attempt: LoginAttempt) -> int | None:
+    waits: list[int] = []
+    stmt = select(User.locked_until).where(_by_username(attempt.username))
+    for locked_until in (await session.execute(stmt)).scalars():
+        if locked_until is not None and locked_until > attempt.now:
+            waits.append(math.ceil((locked_until - attempt.now).total_seconds()))
+    for key, spec in attempt.store_checks():
+        result = await attempt.store.peek(key, spec)
+        if not result.allowed:
+            waits.append(result.retry_after)
+    return max(waits) if waits else None
+
+
+async def record_failure(session: AsyncSession, attempt: LoginAttempt) -> None:
+    s = attempt.settings
+    await attempt.store.hit(attempt.ip_key, attempt.ip_spec)
+    window_start = attempt.now - timedelta(seconds=s.login_rate_limit_window_seconds)
+    stale = User.last_failed_login_at.is_(None) | (User.last_failed_login_at < window_start)
+    stmt = (
+        update(User)
+        .where(_by_username(attempt.username))
+        .values(
+            failed_login_count=case((stale, 1), else_=User.failed_login_count + 1),
+            last_failed_login_at=attempt.now,
+            updated_at=User.updated_at,  # a failed sign-in is not an edit of the account
+        )
+        .returning(User.id, User.failed_login_count)
+        .execution_options(synchronize_session=False)
+    )
+    rows = (await session.execute(stmt)).all()
+    if not rows:
+        await attempt.store.hit(attempt.account_key, attempt.account_spec)
+    for user_id, count in rows:
+        if count >= s.login_lockout_account_failures:
+            user = await session.get(User, user_id, populate_existing=True)
+            user.locked_until = attempt.now + timedelta(seconds=s.login_rate_limit_cooldown_seconds)
+            user.failed_login_count = 0
+    await session.commit()
+
+
+async def record_success(session: AsyncSession, user_id: uuid.UUID) -> None:
+    await session.execute(
+        update(User)
+        .where(User.id == user_id)
+        .where((User.failed_login_count != 0) | User.last_failed_login_at.is_not(None))
+        .values(failed_login_count=0, last_failed_login_at=None, updated_at=User.updated_at)
+        .execution_options(synchronize_session=False)
+    )
+
+
+def too_many_attempts(retry_after: int) -> HTTPException:
+    return HTTPException(
+        status_code=status.HTTP_429_TOO_MANY_REQUESTS,
+        detail=LOCKED_DETAIL,
+        headers={"Retry-After": str(max(1, retry_after))},
+    )
+```
+
+- [ ] **Step 4: Run** `uv run pytest modules/users/tests/test_users_lockout_service.py -q` — Expected: PASS.
+
+- [ ] **Step 5: Commit** — `feat(users): login lockout service backed by the DB and the shared store (#530)`
+
+---
+
+### Task 4: Wire both login routes; drop `/auth-inner` and `LoginRateLimiter`
+
+**Files:**
+- Modify: `modules/users/users/auth_local/api.py` (login uses lockout; remove `/auth-inner` mount and `get_rate_limiter`)
+- Modify: `modules/users/users/auth_local/token_api.py` (token login uses lockout)
+- Modify: `modules/users/users/auth_local/rate_limit.py` (delete `LoginRateLimiter`, fix module docstring)
+- Modify: `modules/users/users/startup.py`, `modules/users/users/state.py` (drop `rate_limiter`)
+- Modify: `modules/users/tests/test_rate_limit.py` (drop `LoginRateLimiter` tests), `modules/users/tests/_users_app_builders.py` (`database_url`/`overrides` params, `redis_url=None`)
+- Modify: comments naming `LoginRateLimiter` in `self_account.py`, `tests/test_profile_password.py`, `modules/site_lock/site_lock/rate_limit.py`
+- Test: `modules/users/tests/test_users_login_lockout.py`
+
+**Interfaces:**
+- Consumes: Task 3's `login_attempt`, `refused_for`, `record_failure`, `record_success`, `too_many_attempts`.
+- Produces: `_build_users_app(monkeypatch, *, allow_signup, seed_admin=True, database_url="sqlite+aiosqlite:///:memory:", overrides=None)`.
+
+- [ ] **Step 1: Write the failing tests**
+
+```python
+async def test_acceptance_three_ips_two_apps_survives_restart(monkeypatch, tmp_path) -> None:
+    url = f"sqlite+aiosqlite:///{tmp_path / 'lockout.db'}"
+    overrides = {"login_lockout_account_failures": ("5", "int")}
+    app_a, ctx_a = await _build_users_app(monkeypatch, allow_signup=False, database_url=url, overrides=overrides)
+    app_b, ctx_b = await _build_users_app(monkeypatch, allow_signup=False, database_url=url, overrides=overrides)
+    await _make_standard_user(app_a, "alice@example.com")
+    plan = [(app_a, "1.1.1.1"), (app_b, "2.2.2.2"), (app_a, "3.3.3.3"), (app_b, "1.1.1.1"), (app_a, "2.2.2.2")]
+    for app, ip in plan:
+        r = await _login(app, ip, "alice@example.com", "wrong")
+        assert r.status_code == 400
+    r = await _login(app_b, "9.9.9.9", "alice@example.com", "UserPass1!")
+    assert r.status_code == 429 and int(r.headers["Retry-After"]) > 0
+    # fresh app, same DB file
+    app_c, ctx_c = await _build_users_app(monkeypatch, allow_signup=False, database_url=url, overrides=overrides)
+    assert (await _login(app_c, "8.8.8.8", "alice@example.com", "UserPass1!")).status_code == 429
+    r = await _token(app_c, "8.8.8.8", "alice@example.com", "UserPass1!")
+    assert r.status_code == 429
+
+
+async def test_unknown_and_locked_look_the_same(...)        # same status + detail
+async def test_token_bad_credentials_still_401(...)          # 401 "Invalid credentials" until throttled, then 429
+async def test_failures_persist_across_requests(...)         # failed_login_count in DB after 2 bad logins
+async def test_correct_password_while_locked_does_not_unlock(...)
+async def test_success_resets_count(...)                     # 2 bad, 1 good → count 0
+async def test_auth_inner_login_is_gone(anon_client)          # POST /api/users/auth-inner/login → 404/405
+async def test_tier2_throttles_ip_not_account(...)            # 5 bad from IP A → 6th from A 429, IP B → 400
+```
+
+- [ ] **Step 2: Run** — Expected: FAIL (counts don't persist across apps; `/auth/token` never 429s; `/auth-inner/login` still answers).
+
+- [ ] **Step 3: Implement** — `login()`:
+
+```python
+    db: AsyncSession = Depends(get_db),
+):
+    attempt = login_attempt(request, credentials.username)
+    if (wait := await refused_for(db, attempt)) is not None:
+        raise too_many_attempts(wait)
+    ... authenticate ...
+    if user is None or not user.is_active:
+        await record_failure(db, attempt)
+        raise HTTPException(status_code=400, detail="LOGIN_BAD_CREDENTIALS")
+    ... verification check (unchanged, not counted) ...
+    await record_success(db, user.id)
+```
+
+`token_login()` — same shape around its existing checks: refuse first; `record_failure` before each 401; `record_success` once the password verified and the verification check passed.
+
+Remove the `auth_inner` include (the wrappers own `/auth/login` and `/auth/logout`; grep showed no callers of `/auth-inner` in code, tests, docs or JS). Delete `LoginRateLimiter`, `get_rate_limiter`, `UsersState.rate_limiter` and its construction in `_build_limiters`.
+
+- [ ] **Step 4: Run** `uv run pytest modules/users/tests -q -n 8` — Expected: PASS.
+
+- [ ] **Step 5: Commit** — `feat(users): lock accounts across workers and IPs on both login routes (#530)`
+
+---
+
+### Task 5: Admin unlock + locked state in the UI
+
+**Files:**
+- Modify: `modules/users/users/contracts/schemas.py` (`UserListItem.locked_until`)
+- Modify: `modules/users/users/admin/queries.py` (`to_list_item` reports only a live lock)
+- Modify: `modules/users/users/admin/service.py` (`unlock`)
+- Modify: `modules/users/users/admin/api.py` (`PATCH /{user_id}/unlock`)
+- Modify: `modules/users/users/admin/components/user-list-item.ts`, `UserRow.tsx`, `UserCards.tsx`, `StatusPill.tsx` (`LockedBadge`)
+- Modify: `modules/users/users/pages/Users/Edit.tsx`, `components/AccountCard.tsx`, `components/useUserActions.ts`
+- Modify: `modules/users/users/locales/en.json`; regenerate `packages/i18n/src/*.generated*.ts` with `make gen-i18n`
+- Test: `modules/users/tests/test_users_admin_unlock.py`, `modules/users/tests-js/AccountCardLocked.test.tsx`
+
+**Interfaces:**
+- Consumes: Task 2 columns; Task 3 `record_failure` (to lock in tests).
+- Produces: `UserService.unlock(user_id) -> User`; `UserListItem.locked_until: datetime | None` (None when not locked *now*); TS `UserListItem.locked_until?: string | null`; `useUserActions(...).lockedUntil`, `.unlock()`, `.savingUnlock`; `AccountCard` props `lockedUntil: string | null`, `savingUnlock: boolean`, `onUnlock: () => void`; `<LockedBadge />`.
+
+New i18n keys (`users` namespace): `metadata_card.locked_until` "Locked until", `account_status.unlock_button` "Unlock", `edit.toast_unlocked` "Account unlocked", `edit.toast_unlock_failed` "Could not unlock the account", `user_row.locked_badge` "locked".
+
+- [ ] **Step 1: Write the failing tests**
+
+```python
+async def test_unlock_clears_lock_and_is_audited(users_app, admin_client) -> None:
+    # lock alice via record_failure ×10, then:
+    r = await admin_client.patch(f"/api/users/admin/{alice_id}/unlock")
+    assert r.status_code == 200 and r.json()["locked_until"] is None
+    # DB: locked_until/failed_login_count/last_failed_login_at cleared
+    # audit_log: an "updated" entry with locked_until for the lock and one for the unlock;
+    # no entry whose only changes are failed_login_count / last_failed_login_at
+
+
+async def test_list_reports_locked_until(...)       # GET /api/users/admin → locked_until set
+async def test_expired_lock_is_not_reported(...)    # locked_until in the past → None
+async def test_unlock_requires_manage(user_client)  # 403
+```
+
+```tsx
+// tests-js/AccountCardLocked.test.tsx
+test('shows Locked until and calls onUnlock', () => {
+  const onUnlock = vi.fn();
+  render(<AccountCard {...base} lockedUntil="2026-10-19T12:00:00Z" onUnlock={onUnlock} />);
+  expect(screen.getByText('Locked until')).toBeInTheDocument();
+  fireEvent.click(screen.getByRole('button', { name: 'Unlock' }));
+  expect(onUnlock).toHaveBeenCalled();
+});
+test('no lock row when unlocked', () => { ... lockedUntil={null} → queryByText('Locked until') is null });
+```
+
+- [ ] **Step 2: Run** — Expected: FAIL (404 on `/unlock`; no `locked_until` key; no "Locked until").
+
+- [ ] **Step 3: Implement**
+
+```python
+    async def unlock(self, user_id: uuid.UUID) -> User:
+        user = await self._require_user(user_id)
+        user.locked_until = None
+        user.failed_login_count = 0
+        user.last_failed_login_at = None
+        await self._db.flush()
+        return user
+```
+
+```python
+@admin_router.patch("/{user_id}/unlock", response_model=UserListItem)
+async def admin_unlock_user(user_id: uuid.UUID, service: UserService = Depends(get_user_service)):
+    """Lift a login lockout early. An ORM write, so the audit log records it."""
+    try:
+        user = await service.unlock(user_id)
+    except UserNotFoundError:
+        raise HTTPException(status_code=404, detail="User not found") from None
+    return service.to_list_item(user)
+```
+
+`to_list_item`: `locked_until=_live_lock(user.locked_until)` where `_live_lock` returns the value only when it is after `datetime.now(UTC)`.
+
+`AccountCard`: when `lockedUntil` is set, a `Row` labelled `t(keys.users.metadata_card.locked_until)` showing `formatDateTime`-style local time plus an outline `Button` `t(keys.users.account_status.unlock_button)` calling `onUnlock`. `useUserActions` gains `lockedUntil` state (initialised from the prop) and `unlock()` (PATCH `/api/users/admin/${userId}/unlock`, toast, set `null`). `UserRow`/`UserCards` render `<LockedBadge />` next to the status pill when `user.locked_until` is set.
+
+- [ ] **Step 4: Run** `uv run pytest modules/users/tests/test_users_admin_unlock.py -q`, `npx vitest run modules/users/tests-js/AccountCardLocked.test.tsx`, `make gen-i18n`, `make ci-check-untranslated` — Expected: PASS.
+
+- [ ] **Step 5: Commit** — `feat(users): admin unlock and locked state in the users UI (#530)`
+
+---
+
+### Task 6: Docs + CHANGELOG
+
+**Files:**
+- Modify: `docs/modules/users.md` (lockout section, settings table, admin endpoint, remove the in-process-counter note)
+- Modify: `docs/framework/request-guards.md` (§ Not covered → the store is shared as `app.state.sm.rate_limit_store`; `peek`)
+- Modify: `CHANGELOG.md` `[Unreleased]`
+
+- [ ] **Step 1: Write** — `CHANGELOG.md`:
+
+```markdown
+### Changed
+- **Behaviour change (#530):** password-login lockout now holds across workers,
+  source IPs and restarts. Ten failures for one account (from anywhere) within
+  `login_rate_limit_window_seconds` lock it for `login_rate_limit_cooldown_seconds`
+  — the right password included — answering 429 with `Retry-After`. Five
+  failures from one IP for one username throttle that source for the window.
+  New setting `users.login_lockout_account_failures` (default 10). Counters live
+  on `users_user` and on the host rate-limit store (Redis when `SM_REDIS_URL`
+  is set); a migration adds three columns.
+- **Behaviour change (#530):** `POST /api/users/auth/token` is now covered by the
+  same lockout and throttle (429 when locked; bad credentials still 401).
+- **Behaviour change (#530):** the stock fastapi-users router at
+  `/api/users/auth-inner/*` is no longer mounted; use `/api/users/auth/login`
+  and `/api/users/auth/logout`.
+
+### Added
+- `PATCH /api/users/admin/{id}/unlock` lifts a lockout (audited); the user list
+  shows a "locked" badge and the edit page a "Locked until" row with Unlock.
+- `app.state.sm.rate_limit_store` and `WindowStore.peek()`.
+```
+
+- [ ] **Step 2: Verify** — `uv run ruff format --check docs/` and `make lint`.
+
+- [ ] **Step 3: Commit** — `docs(users): document login lockout (#530)`
+
+---
+
+## Final verification
+
+`rmdir /tmp/.git 2>/dev/null`; `uv run pytest -q -n 8`, `make test-js`, `make lint`, `make ci-check-untranslated`, `make doctor` — each redirected to `/tmp/claude-1001/lockout/<name>.log` with the real exit code recorded.

From 1d866a923429710bc895d808a9acc8ab307bb760 Mon Sep 17 00:00:00 2001
From: Anto Subash <antosubash@live.com>
Date: Mon, 19 Oct 2026 11:19:48 +0200
Subject: [PATCH 03/13] feat(hosting): share the rate-limit store on
 app.state.sm (#530)

The users login lockout needs a counter that every worker sees. The host
already builds one for RateLimitMiddleware (Redis when SM_REDIS_URL is set),
so expose that instance as Services.rate_limit_store instead of opening a
second client, and give WindowStore a non-counting peek() so a caller can
refuse before doing work and count only what failed.

Claude-Session: https://claude.ai/code/session_01M9neheZZEe3sVpDi2S3zT4
---
 .../core/simple_module_core/rate_limit.py     | 18 ++++
 framework/core/simple_module_core/services.py |  6 ++
 .../simple_module_hosting/_phase_helpers.py   |  6 +-
 .../simple_module_hosting/_rate_limit.py      | 32 +++++--
 .../simple_module_hosting/app_builder.py      |  6 +-
 .../tests/test_rate_limit_store_shared.py     | 90 +++++++++++++++++++
 6 files changed, 150 insertions(+), 8 deletions(-)
 create mode 100644 framework/hosting/tests/test_rate_limit_store_shared.py

diff --git a/framework/core/simple_module_core/rate_limit.py b/framework/core/simple_module_core/rate_limit.py
index 1430ff830..b5f7c4f97 100644
--- a/framework/core/simple_module_core/rate_limit.py
+++ b/framework/core/simple_module_core/rate_limit.py
@@ -94,6 +94,15 @@ async def hit(self, key: str, spec: RateSpec) -> WindowResult:
         """Count one request against *key* and report whether it is within budget."""
         ...
 
+    async def peek(self, key: str, spec: RateSpec) -> WindowResult:
+        """Report *key*'s current window without counting.
+
+        ``allowed`` answers "would one more hit be within budget", so a caller
+        can refuse before doing any work and count only what failed — the
+        login lockout counts wrong passwords, not attempts.
+        """
+        ...
+
 
 class InProcessWindowStore:
     """Per-process fixed-window counters. Not shared between workers."""
@@ -117,6 +126,15 @@ async def hit(self, key: str, spec: RateSpec) -> WindowResult:
         retry = max(1, math.ceil(end_ms / 1000 - now))
         return WindowResult(allowed=count <= spec.limit, retry_after=retry, count=count)
 
+    async def peek(self, key: str, spec: RateSpec) -> WindowResult:
+        now = self._clock()
+        entry = self._windows.get(key)
+        if entry is None or entry[0] <= now * 1000:
+            return WindowResult(allowed=spec.limit > 0, retry_after=0, count=0)
+        end_ms, count = entry
+        retry = max(1, math.ceil(end_ms / 1000 - now))
+        return WindowResult(allowed=count < spec.limit, retry_after=retry, count=count)
+
     def _sweep(self, now: float) -> None:
         now_ms = now * 1000
         self._windows = {k: v for k, v in self._windows.items() if v[0] > now_ms}
diff --git a/framework/core/simple_module_core/services.py b/framework/core/simple_module_core/services.py
index 5a1cd0a72..d4a704439 100644
--- a/framework/core/simple_module_core/services.py
+++ b/framework/core/simple_module_core/services.py
@@ -17,6 +17,7 @@
 from typing import TYPE_CHECKING
 
 from simple_module_core.invalidation import InvalidationBus
+from simple_module_core.rate_limit import InProcessWindowStore, WindowStore
 from simple_module_core.tenancy import TenancyMode
 
 if TYPE_CHECKING:
@@ -107,3 +108,8 @@ class Services:
     #: Module name -> ``view_prefix`` for modules whose view router received
     #: routes, in discovery order. ``""`` here means mounted at ``/`` (#435).
     view_prefixes: dict[str, str] = field(default_factory=dict)
+    #: The store behind ``RateLimitMiddleware`` (Redis when ``SM_REDIS_URL`` is
+    #: set), shared so a module throttling its own events — the users login
+    #: lockout — counts in the same place across workers instead of opening a
+    #: second Redis client. Defaulted for apps built outside ``create_app``.
+    rate_limit_store: WindowStore = field(default_factory=InProcessWindowStore)
diff --git a/framework/hosting/simple_module_hosting/_phase_helpers.py b/framework/hosting/simple_module_hosting/_phase_helpers.py
index 2c3c35950..fad84f834 100644
--- a/framework/hosting/simple_module_hosting/_phase_helpers.py
+++ b/framework/hosting/simple_module_hosting/_phase_helpers.py
@@ -33,7 +33,7 @@
 )
 from simple_module_hosting._inertia_cache import InertiaCacheMiddleware
 from simple_module_hosting._module_routes import wire_module_routes
-from simple_module_hosting._rate_limit import RateLimitMiddleware, build_store
+from simple_module_hosting._rate_limit import RateLimitMiddleware
 from simple_module_hosting.i18n_middleware import LocaleMiddleware
 from simple_module_hosting.maintenance import MaintenanceMiddleware
 from simple_module_hosting.middleware import (
@@ -52,6 +52,7 @@
     from simple_module_core.csp import CspSourceRegistry
     from simple_module_core.menu import MenuRegistry
     from simple_module_core.permissions import PermissionRegistry
+    from simple_module_core.rate_limit import WindowStore
 
 logger = logging.getLogger(__name__)
 
@@ -104,6 +105,7 @@ def install_middleware(
     menu_registry: MenuRegistry,
     perm_registry: PermissionRegistry,
     csp_registry: CspSourceRegistry,
+    rate_limit_store: WindowStore,
 ) -> None:
     """Install the full middleware pipeline.
 
@@ -139,7 +141,7 @@ def install_middleware(
         RateLimitMiddleware,
         public_rate=settings.rate_limit_public,
         authenticated_rate=settings.rate_limit_authenticated,
-        store=build_store(settings.redis_url),
+        store=rate_limit_store,
     )
     # Paired with InertiaLayoutDataMiddleware below, which is what puts this
     # user's auth, permissions and menus into every Inertia payload: this one
diff --git a/framework/hosting/simple_module_hosting/_rate_limit.py b/framework/hosting/simple_module_hosting/_rate_limit.py
index a59fafc04..97a8d73c6 100644
--- a/framework/hosting/simple_module_hosting/_rate_limit.py
+++ b/framework/hosting/simple_module_hosting/_rate_limit.py
@@ -58,6 +58,13 @@
 return {c, t}
 """
 
+# Read-only twin of ``_LUA``: a missing key is an empty window.
+_PEEK_LUA = """
+local c = redis.call('GET', KEYS[1])
+if not c then return {0, 0} end
+return {tonumber(c), redis.call('PTTL', KEYS[1])}
+"""
+
 
 class RedisWindowStore:
     """Fixed-window counters in Redis; shared across workers and processes.
@@ -84,11 +91,12 @@ def from_url(cls, url: str) -> RedisWindowStore:
         client = aioredis.from_url(url, socket_connect_timeout=0.5, socket_timeout=0.5)
         return cls(client)
 
-    async def hit(self, key: str, spec: RateSpec) -> WindowResult:
+    async def _eval(self, script: str, key: str, *args: Any) -> Any:
+        """Run *script* on *key*; ``None`` means "answer from the per-worker fallback"."""
         if self._clock() < self._down_until:
-            return await self._fallback.hit(key, spec)
+            return None
         try:
-            count, pttl = await self._client.eval(_LUA, 1, _KEY_PREFIX + key, spec.period * 1000)
+            return await self._client.eval(script, 1, _KEY_PREFIX + key, *args)
         except Exception as exc:
             now = self._clock()
             self._down_until = now + _BACKOFF
@@ -97,9 +105,23 @@ async def hit(self, key: str, spec: RateSpec) -> WindowResult:
                 logger.warning(
                     "Rate limiter Redis unavailable (%s); using per-worker counters", exc
                 )
+            return None
+
+    async def hit(self, key: str, spec: RateSpec) -> WindowResult:
+        reply = await self._eval(_LUA, key, spec.period * 1000)
+        if reply is None:
             return await self._fallback.hit(key, spec)
-        retry = max(1, -(-int(pttl) // 1000)) if int(pttl) > 0 else spec.period
-        return WindowResult(allowed=int(count) <= spec.limit, retry_after=retry, count=int(count))
+        count, pttl = int(reply[0]), int(reply[1])
+        retry = max(1, -(-pttl // 1000)) if pttl > 0 else spec.period
+        return WindowResult(allowed=count <= spec.limit, retry_after=retry, count=count)
+
+    async def peek(self, key: str, spec: RateSpec) -> WindowResult:
+        reply = await self._eval(_PEEK_LUA, key)
+        if reply is None:
+            return await self._fallback.peek(key, spec)
+        count, pttl = int(reply[0]), int(reply[1])
+        retry = max(1, -(-pttl // 1000)) if pttl > 0 else 0
+        return WindowResult(allowed=count < spec.limit, retry_after=retry, count=count)
 
 
 def build_store(redis_url: str | None) -> WindowStore:
diff --git a/framework/hosting/simple_module_hosting/app_builder.py b/framework/hosting/simple_module_hosting/app_builder.py
index 0175f6344..e863ac3b7 100644
--- a/framework/hosting/simple_module_hosting/app_builder.py
+++ b/framework/hosting/simple_module_hosting/app_builder.py
@@ -42,6 +42,7 @@
 )
 from simple_module_hosting._preapp_config import merge_host_settings
 from simple_module_hosting._project_root import resolve_project_root as _resolve_project_root
+from simple_module_hosting._rate_limit import build_store
 from simple_module_hosting._registrations import run_module_registrations
 from simple_module_hosting._secret_key import assert_not_placeholder
 from simple_module_hosting._settings_registration import (
@@ -248,8 +249,10 @@ def create_app(settings: Settings | None = None) -> FastAPI:
     register_exception_handlers(app, modules)
 
     # ── Phase 8: Middleware pipeline ───────────────────────
+    # Shared with modules via app.state.sm (the users login lockout counts here).
+    rate_limit_store = build_store(settings.redis_url)
     install_middleware(
-        app, settings, modules, menu_registry, perm_registry, csp_registry=csp_registry
+        app, settings, modules, menu_registry, perm_registry, csp_registry, rate_limit_store
     )
 
     # ── Phase 9: Routes, health, static files ──────────────
@@ -288,6 +291,7 @@ def create_app(settings: Settings | None = None) -> FastAPI:
         diagnostics=diagnostics_state,
         tenancy=mode_for(settings),
         view_prefixes=view_prefixes,
+        rate_limit_store=rate_limit_store,
     )
 
     return app
diff --git a/framework/hosting/tests/test_rate_limit_store_shared.py b/framework/hosting/tests/test_rate_limit_store_shared.py
new file mode 100644
index 000000000..07d510c06
--- /dev/null
+++ b/framework/hosting/tests/test_rate_limit_store_shared.py
@@ -0,0 +1,90 @@
+"""The host rate-limit store is shared with modules and readable without counting (#530)."""
+
+from __future__ import annotations
+
+from simple_module_core.rate_limit import InProcessWindowStore, RateSpec
+from simple_module_core.services import Services
+from simple_module_hosting._rate_limit import RateLimitMiddleware, RedisWindowStore
+
+
+class _Clock:
+    def __init__(self) -> None:
+        self.now = 1_000.0
+
+    def __call__(self) -> float:
+        return self.now
+
+
+async def test_peek_does_not_count() -> None:
+    store = InProcessWindowStore(clock=_Clock())
+    spec = RateSpec(2, 60)
+    assert (await store.peek("k", spec)).count == 0
+    await store.hit("k", spec)
+    await store.hit("k", spec)
+    first = await store.peek("k", spec)
+    second = await store.peek("k", spec)
+    assert (first.count, first.allowed) == (2, False)
+    assert second.count == 2
+
+
+async def test_peek_allows_while_under_the_limit() -> None:
+    store = InProcessWindowStore(clock=_Clock())
+    spec = RateSpec(2, 60)
+    await store.hit("k", spec)
+    assert (await store.peek("k", spec)).allowed is True
+
+
+async def test_peek_window_expires() -> None:
+    clock = _Clock()
+    store = InProcessWindowStore(clock=clock)
+    spec = RateSpec(1, 60)
+    await store.hit("k", spec)
+    assert (await store.peek("k", spec)).retry_after == 60
+    clock.now += 61
+    result = await store.peek("k", spec)
+    assert (result.count, result.allowed, result.retry_after) == (0, True, 0)
+
+
+class _FakeRedis:
+    def __init__(self) -> None:
+        self.counts: dict[str, int] = {}
+
+    async def eval(self, script: str, numkeys: int, key: str, *args):
+        if args:  # hit: INCR + PEXPIRE
+            self.counts[key] = self.counts.get(key, 0) + 1
+            return [self.counts[key], args[0]]
+        count = self.counts.get(key)
+        return [0, 0] if count is None else [count, 30_000]
+
+
+class _DeadRedis:
+    async def eval(self, *a, **k):
+        raise ConnectionError("redis down")
+
+
+async def test_redis_peek_reads_without_counting() -> None:
+    redis = _FakeRedis()
+    store = RedisWindowStore(redis)
+    spec = RateSpec(1, 60)
+    assert (await store.peek("k", spec)).allowed is True
+    await store.hit("k", spec)
+    result = await store.peek("k", spec)
+    assert (result.count, result.allowed, result.retry_after) == (1, False, 30)
+    assert redis.counts == {"sm:rl:k": 1}
+
+
+async def test_peek_falls_back_when_redis_down() -> None:
+    store = RedisWindowStore(_DeadRedis())
+    spec = RateSpec(1, 60)
+    await store.hit("k", spec)  # counted by the per-worker fallback
+    assert (await store.peek("k", spec)).allowed is False
+
+
+def test_services_default_store() -> None:
+    factory = Services.__dataclass_fields__["rate_limit_store"].default_factory
+    assert isinstance(factory(), InProcessWindowStore)  # ty: ignore[call-non-callable]
+
+
+async def test_create_app_shares_one_store(app) -> None:
+    [guard] = [m for m in app.user_middleware if m.cls is RateLimitMiddleware]
+    assert guard.kwargs["store"] is app.state.sm.rate_limit_store

From 3fccfcc20350e7b2f6c3b0e25b9af0ce967db972 Mon Sep 17 00:00:00 2001
From: Anto Subash <antosubash@live.com>
Date: Mon, 19 Oct 2026 11:21:02 +0200
Subject: [PATCH 04/13] feat(users): lockout columns on users_user (#530)

failed_login_count, last_failed_login_at and locked_until, plus the
migration. The two counter fields are excluded from audit diffs so failed
attempts don't flood the log; locked_until stays audited.

Claude-Session: https://claude.ai/code/session_01M9neheZZEe3sVpDi2S3zT4
---
 .../c8e4f1a2b6d9_users_login_lockout.py       | 47 +++++++++++++++++++
 .../users/tests/test_users_lockout_columns.py | 31 ++++++++++++
 modules/users/users/models/user.py            | 16 ++++++-
 3 files changed, 93 insertions(+), 1 deletion(-)
 create mode 100644 host/migrations/versions/c8e4f1a2b6d9_users_login_lockout.py
 create mode 100644 modules/users/tests/test_users_lockout_columns.py

diff --git a/host/migrations/versions/c8e4f1a2b6d9_users_login_lockout.py b/host/migrations/versions/c8e4f1a2b6d9_users_login_lockout.py
new file mode 100644
index 000000000..023158931
--- /dev/null
+++ b/host/migrations/versions/c8e4f1a2b6d9_users_login_lockout.py
@@ -0,0 +1,47 @@
+"""users login lockout columns
+
+Revision ID: c8e4f1a2b6d9
+Revises: b5018b617142
+Create Date: 2026-10-19 09:00:00.000000
+"""
+
+from collections.abc import Sequence
+
+import sqlalchemy as sa
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision: str = "c8e4f1a2b6d9"
+down_revision: str | None = "b5018b617142"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+# Login lockout moves from per-worker memory to the user row (GH #530), so it
+# holds across workers, source IPs and restarts. Every existing account starts
+# unlocked with a zero count; nothing to backfill.
+
+
+def upgrade() -> None:
+    op.add_column(
+        "users_user",
+        sa.Column(
+            "failed_login_count",
+            sa.Integer(),
+            server_default=sa.text("0"),
+            nullable=False,
+        ),
+    )
+    op.add_column(
+        "users_user",
+        sa.Column("last_failed_login_at", sa.DateTime(timezone=True), nullable=True),
+    )
+    op.add_column(
+        "users_user",
+        sa.Column("locked_until", sa.DateTime(timezone=True), nullable=True),
+    )
+
+
+def downgrade() -> None:
+    op.drop_column("users_user", "locked_until")
+    op.drop_column("users_user", "last_failed_login_at")
+    op.drop_column("users_user", "failed_login_count")
diff --git a/modules/users/tests/test_users_lockout_columns.py b/modules/users/tests/test_users_lockout_columns.py
new file mode 100644
index 000000000..8359f869e
--- /dev/null
+++ b/modules/users/tests/test_users_lockout_columns.py
@@ -0,0 +1,31 @@
+"""Login-lockout columns on ``users_user`` (GH #530)."""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+
+from simple_module_db.audit import snapshot_changes
+from sqlalchemy import select
+from users.models import User
+
+
+async def _admin(users_db) -> User:
+    return (await users_db.execute(select(User).limit(1))).scalar_one()
+
+
+async def test_existing_user_starts_unlocked(users_db) -> None:
+    user = await _admin(users_db)
+    assert user.failed_login_count == 0
+    assert user.last_failed_login_at is None
+    assert user.locked_until is None
+
+
+async def test_counter_fields_are_not_audited(users_db) -> None:
+    user = await _admin(users_db)
+    user.failed_login_count = 3
+    user.last_failed_login_at = datetime.now(UTC)
+    assert snapshot_changes(users_db.sync_session) == []
+
+    user.locked_until = datetime.now(UTC)
+    [record] = snapshot_changes(users_db.sync_session)
+    assert [c["field"] for c in record.changes] == ["locked_until"]
diff --git a/modules/users/users/models/user.py b/modules/users/users/models/user.py
index 75ae3af40..647db720d 100644
--- a/modules/users/users/models/user.py
+++ b/modules/users/users/models/user.py
@@ -12,7 +12,7 @@
 
 import uuid
 from datetime import datetime
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, ClassVar
 
 from fastapi_users_db_sqlalchemy.generics import GUID
 from simple_module_db.mixins import AuditMixin
@@ -85,6 +85,20 @@ class User(Base, AuditMixin, table=True):  # ty: ignore[unsupported-base]
         default=0,
         sa_column_kwargs={"server_default": text("0")},
     )
+    # Login lockout (GH #530). One atomic UPDATE per failed password login bumps
+    # the count, restarting it once ``last_failed_login_at`` is older than the
+    # window; reaching the threshold stamps ``locked_until`` through the ORM so
+    # the lock is audited. See ``users.auth_local.lockout``.
+    failed_login_count: int = Field(
+        default=0,
+        sa_column_kwargs={"server_default": text("0")},
+    )
+    last_failed_login_at: datetime | None = Field(default=None, sa_type=AwareDateTime())
+    locked_until: datetime | None = Field(default=None, sa_type=AwareDateTime())
+
+    # Every wrong password writes these two; auditing them would bury the
+    # lock and unlock entries that matter under one entry per failed attempt.
+    __audit_exclude_fields__: ClassVar[set[str]] = {"failed_login_count", "last_failed_login_at"}
 
     roles: list["Role"] = Relationship(
         link_model=UserRole,

From 89f60e871d66a250844b3fecb1e2664e02c8f6ec Mon Sep 17 00:00:00 2001
From: Anto Subash <antosubash@live.com>
Date: Mon, 19 Oct 2026 11:22:09 +0200
Subject: [PATCH 05/13] feat(users): login lockout service backed by the DB and
 the shared store (#530)

users.auth_local.lockout: refused_for / record_failure / record_success.
The account tier is one atomic UPDATE ... RETURNING on users_user with a
window reset, locking through the ORM at login_lockout_account_failures
(new setting, default 10). The source tier counts per IP+username, and
unknown usernames against the account threshold, on the host store.

Claude-Session: https://claude.ai/code/session_01M9neheZZEe3sVpDi2S3zT4
---
 .../users/tests/test_users_lockout_service.py | 120 ++++++++++++
 modules/users/users/auth_local/lockout.py     | 179 ++++++++++++++++++
 modules/users/users/settings.py               |   8 +-
 3 files changed, 306 insertions(+), 1 deletion(-)
 create mode 100644 modules/users/tests/test_users_lockout_service.py
 create mode 100644 modules/users/users/auth_local/lockout.py

diff --git a/modules/users/tests/test_users_lockout_service.py b/modules/users/tests/test_users_lockout_service.py
new file mode 100644
index 000000000..524dbe0c2
--- /dev/null
+++ b/modules/users/tests/test_users_lockout_service.py
@@ -0,0 +1,120 @@
+"""``users.auth_local.lockout`` — both tiers, driven directly (GH #530)."""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime, timedelta
+
+import pytest
+from _users_app_builders import _make_standard_user
+from simple_module_core.rate_limit import InProcessWindowStore
+from sqlalchemy import select
+from users.auth_local.lockout import (
+    LoginAttempt,
+    record_failure,
+    record_success,
+    refused_for,
+)
+from users.models import User
+from users.settings import UsersSettings
+
+T0 = datetime(2026, 10, 19, 12, 0, tzinfo=UTC)
+
+
+@pytest.fixture
+async def alice(users_app):
+    return await _make_standard_user(users_app, "alice@example.com")
+
+
+def _attempt(
+    username: str,
+    *,
+    now: datetime = T0,
+    ip: str = "1.1.1.1",
+    store: InProcessWindowStore | None = None,
+    account: int = 10,
+) -> LoginAttempt:
+    settings = UsersSettings(login_lockout_account_failures=account)
+    return LoginAttempt.build(username, ip, store or InProcessWindowStore(), settings, now)
+
+
+async def _row(users_db, user) -> User:
+    stmt = select(User).where(User.id == user.id).execution_options(populate_existing=True)
+    return (await users_db.execute(stmt)).scalar_one()
+
+
+async def test_account_locks_at_threshold(users_db, alice) -> None:
+    for i in range(3):
+        # A different IP every time: the account lock does not care where from.
+        await record_failure(users_db, _attempt("alice@example.com", ip=f"10.0.0.{i}", account=3))
+    row = await _row(users_db, alice)
+    assert row.locked_until == T0 + timedelta(seconds=900)
+    assert row.failed_login_count == 0
+    assert await refused_for(users_db, _attempt("alice@example.com", ip="9.9.9.9")) == 900
+
+
+async def test_below_threshold_is_not_locked(users_db, alice) -> None:
+    for i in range(2):
+        await record_failure(users_db, _attempt("alice@example.com", ip=f"10.0.0.{i}", account=3))
+    row = await _row(users_db, alice)
+    assert (row.failed_login_count, row.locked_until) == (2, None)
+    assert await refused_for(users_db, _attempt("alice@example.com", ip="9.9.9.9")) is None
+
+
+async def test_expired_window_restarts_count(users_db, alice) -> None:
+    await record_failure(users_db, _attempt("alice@example.com", now=T0))
+    await record_failure(users_db, _attempt("alice@example.com", now=T0 + timedelta(seconds=10)))
+    await record_failure(users_db, _attempt("alice@example.com", now=T0 + timedelta(seconds=400)))
+    row = await _row(users_db, alice)
+    assert row.failed_login_count == 1
+    assert row.last_failed_login_at == T0 + timedelta(seconds=400)
+
+
+async def test_expired_lock_allows_login(users_db, alice) -> None:
+    for i in range(3):
+        await record_failure(users_db, _attempt("alice@example.com", ip=f"10.0.0.{i}", account=3))
+    later = T0 + timedelta(seconds=901)
+    assert await refused_for(users_db, _attempt("alice@example.com", now=later)) is None
+
+
+async def test_success_resets_count(users_db, alice) -> None:
+    await record_failure(users_db, _attempt("alice@example.com"))
+    await record_failure(users_db, _attempt("alice@example.com"))
+    await record_success(users_db, alice.id)
+    await users_db.commit()
+    row = await _row(users_db, alice)
+    assert (row.failed_login_count, row.last_failed_login_at) == (0, None)
+
+
+async def test_failures_do_not_touch_updated_at(users_db, alice) -> None:
+    before = (await _row(users_db, alice)).updated_at
+    await record_failure(users_db, _attempt("alice@example.com"))
+    assert (await _row(users_db, alice)).updated_at == before
+
+
+async def test_ip_throttle_after_tier2_limit(users_db, alice) -> None:
+    store = InProcessWindowStore()
+    for _ in range(5):
+        await record_failure(users_db, _attempt("alice@example.com", ip="1.1.1.1", store=store))
+    wait = await refused_for(users_db, _attempt("alice@example.com", ip="1.1.1.1", store=store))
+    assert wait is not None and wait > 0
+    other_ip = _attempt("alice@example.com", ip="2.2.2.2", store=store)
+    assert await refused_for(users_db, other_ip) is None
+
+
+async def test_unknown_username_counts_against_account_threshold(users_db) -> None:
+    store = InProcessWindowStore()
+    for i in range(10):
+        await record_failure(users_db, _attempt("ghost@example.com", ip=f"10.0.0.{i}", store=store))
+    fresh_ip = _attempt("ghost@example.com", ip="9.9.9.9", store=store)
+    assert await refused_for(users_db, fresh_ip) is not None
+
+
+async def test_username_variants_share_one_counter(users_db, alice) -> None:
+    store = InProcessWindowStore()
+    await record_failure(users_db, _attempt(" Alice@Example.COM ", store=store))
+    await record_failure(users_db, _attempt("alice@example.com", store=store))
+    assert (await _row(users_db, alice)).failed_login_count == 2
+    # ...and the per-IP key is the same one too.
+    for _ in range(3):
+        await record_failure(users_db, _attempt("ALICE@example.com", store=store))
+    assert await refused_for(users_db, _attempt("alice@example.com", store=store)) is not None
diff --git a/modules/users/users/auth_local/lockout.py b/modules/users/users/auth_local/lockout.py
new file mode 100644
index 000000000..505e545b1
--- /dev/null
+++ b/modules/users/users/auth_local/lockout.py
@@ -0,0 +1,179 @@
+"""Password-login lockout that holds across workers, source IPs and restarts.
+
+Both password logins — the session ``/auth/login`` and the bearer
+``/auth/token`` — go through here (GH #530). Two tiers:
+
+* **Account lock**, on ``users_user``. A failure bumps ``failed_login_count``
+  with one atomic ``UPDATE … RETURNING``, restarting at 1 once the last failure
+  is older than the window, so every worker shares one count. Reaching
+  ``login_lockout_account_failures`` stamps ``locked_until`` through the ORM —
+  that is what puts the lock in the audit log. While it holds, every password
+  login for the account is refused, the right password included.
+* **Source throttle**, on the host's rate-limit store (Redis when configured).
+  ``login:ip:<ip>:<username>`` stops one source after
+  ``login_rate_limit_failures``; ``login:acct:<username>`` counts failures for a
+  username with *no* account against the account threshold, so a 429 says
+  nothing about whether the account exists.
+
+Only failures count. The caller refuses with :func:`refused_for` first, then
+records the outcome.
+"""
+
+from __future__ import annotations
+
+import math
+import uuid
+from collections.abc import Iterator
+from dataclasses import dataclass
+from datetime import UTC, datetime, timedelta
+from typing import TYPE_CHECKING, Any
+
+from fastapi import HTTPException, Request, status
+from simple_module_core.rate_limit import RateSpec, WindowStore
+from sqlalchemy import case, func, select, update
+
+from users.models import User
+
+if TYPE_CHECKING:
+    from sqlalchemy.ext.asyncio import AsyncSession
+
+    from users.settings import UsersSettings
+
+LOCKED_DETAIL = "Too many attempts — try again later"
+
+
+def _utcnow() -> datetime:
+    return datetime.now(UTC)
+
+
+@dataclass(frozen=True, slots=True)
+class LoginAttempt:
+    """One password login: who, from where, against which store, and when."""
+
+    username: str
+    ip: str
+    store: WindowStore
+    settings: UsersSettings
+    now: datetime
+
+    @classmethod
+    def build(
+        cls,
+        username: str,
+        ip: str,
+        store: WindowStore,
+        settings: UsersSettings,
+        now: datetime,
+    ) -> LoginAttempt:
+        # Normalised once, here: ``Alice@x `` and ``alice@x`` are one account
+        # to the user lookup, so they must be one counter too.
+        return cls(username.strip().lower(), ip, store, settings, now)
+
+    @property
+    def ip_key(self) -> str:
+        return f"login:ip:{self.ip}:{self.username}"
+
+    @property
+    def account_key(self) -> str:
+        return f"login:acct:{self.username}"
+
+    @property
+    def ip_spec(self) -> RateSpec:
+        s = self.settings
+        return RateSpec(s.login_rate_limit_failures, s.login_rate_limit_window_seconds)
+
+    @property
+    def account_spec(self) -> RateSpec:
+        s = self.settings
+        return RateSpec(s.login_lockout_account_failures, s.login_rate_limit_window_seconds)
+
+    def store_checks(self) -> Iterator[tuple[str, RateSpec]]:
+        yield self.ip_key, self.ip_spec
+        yield self.account_key, self.account_spec
+
+
+def login_attempt(request: Request, username: str) -> LoginAttempt:
+    """The :class:`LoginAttempt` for *username* arriving on *request*."""
+    return LoginAttempt.build(
+        username,
+        request.client.host if request.client else "unknown",
+        request.app.state.sm.rate_limit_store,
+        request.app.state.users.settings,
+        _utcnow(),
+    )
+
+
+def _by_username(username: str) -> Any:
+    # The same predicate ``UserDatabaseWithRoles.get_by_email`` signs in with.
+    return func.lower(User.email) == username
+
+
+async def refused_for(session: AsyncSession, attempt: LoginAttempt) -> int | None:
+    """Seconds the caller must wait, or ``None`` when the attempt may proceed."""
+    waits: list[int] = []
+    stmt = select(User.locked_until).where(_by_username(attempt.username))
+    for locked_until in (await session.execute(stmt)).scalars():
+        if locked_until is not None and locked_until > attempt.now:
+            waits.append(math.ceil((locked_until - attempt.now).total_seconds()))
+    for key, spec in attempt.store_checks():
+        result = await attempt.store.peek(key, spec)
+        if not result.allowed:
+            waits.append(result.retry_after)
+    return max(waits) if waits else None
+
+
+async def record_failure(session: AsyncSession, attempt: LoginAttempt) -> None:
+    """Count a failed password login in both tiers, locking at the threshold.
+
+    Commits *session*: the caller answers by raising, and the request's unit
+    of work rolls back on that path — the count has to be durable before then.
+    The request has only read by this point, so nothing else is committed.
+    """
+    s = attempt.settings
+    await attempt.store.hit(attempt.ip_key, attempt.ip_spec)
+    window_start = attempt.now - timedelta(seconds=s.login_rate_limit_window_seconds)
+    stale = User.last_failed_login_at.is_(None) | (User.last_failed_login_at < window_start)
+    stmt = (
+        update(User)
+        .where(_by_username(attempt.username))
+        .values(
+            failed_login_count=case((stale, 1), else_=User.failed_login_count + 1),
+            last_failed_login_at=attempt.now,
+            # A failed sign-in is not an edit of the account.
+            updated_at=User.updated_at,
+        )
+        .returning(User.id, User.failed_login_count)
+        .execution_options(synchronize_session=False)
+    )
+    rows = (await session.execute(stmt)).all()
+    if not rows:
+        await attempt.store.hit(attempt.account_key, attempt.account_spec)
+    for user_id, count in rows:
+        if count >= s.login_lockout_account_failures:
+            # Through the ORM, not the UPDATE above, so the audit log records it.
+            user = await session.get(User, user_id, populate_existing=True)
+            if user is not None:
+                cooldown = timedelta(seconds=s.login_rate_limit_cooldown_seconds)
+                user.locked_until = attempt.now + cooldown
+                user.failed_login_count = 0
+    await session.commit()
+
+
+async def record_success(session: AsyncSession, user_id: uuid.UUID) -> None:
+    """Clear the account's failure count. Rides the request's own commit."""
+    await session.execute(
+        update(User)
+        .where(User.id == user_id)
+        .where((User.failed_login_count != 0) | User.last_failed_login_at.is_not(None))
+        .values(failed_login_count=0, last_failed_login_at=None, updated_at=User.updated_at)
+        .execution_options(synchronize_session=False)
+    )
+
+
+def too_many_attempts(retry_after: int) -> HTTPException:
+    """The 429 for a locked account or a throttled source — deliberately identical."""
+    return HTTPException(
+        status_code=status.HTTP_429_TOO_MANY_REQUESTS,
+        detail=LOCKED_DETAIL,
+        headers={"Retry-After": str(max(1, retry_after))},
+    )
diff --git a/modules/users/users/settings.py b/modules/users/users/settings.py
index 2d853f518..293991ca9 100644
--- a/modules/users/users/settings.py
+++ b/modules/users/users/settings.py
@@ -108,10 +108,16 @@ def _non_empty_redirect(cls, value: str) -> str:
     smtp_from: str = "no-reply@localhost"
     smtp_tls: bool = True
 
-    # Rate limit (login — failure-based lockout)
+    # Login lockout (GH #530, ``users.auth_local.lockout``). Failures within the
+    # window: ``login_rate_limit_failures`` from one IP for one username
+    # throttle that source until the window ends; ``login_lockout_account_failures``
+    # from anywhere lock the account for ``login_rate_limit_cooldown_seconds``.
+    # 10 rather than 5 for the account: anyone who knows an address could
+    # otherwise lock its owner out from any network.
     login_rate_limit_failures: int = 5
     login_rate_limit_window_seconds: int = 300
     login_rate_limit_cooldown_seconds: int = 900
+    login_lockout_account_failures: int = Field(10, ge=1)
 
     # Rate limit (auth side-effects: forgot-password, register, accept-invite,
     # request-verify-token). Counts every attempt per IP per window.

From 0c249a0b52b73bc6d27be0aef524681a01832199 Mon Sep 17 00:00:00 2001
From: Anto Subash <antosubash@live.com>
Date: Mon, 19 Oct 2026 11:25:06 +0200
Subject: [PATCH 06/13] feat(users): lock accounts across workers and IPs on
 both login routes (#530)

/auth/login and /auth/token now share users.auth_local.lockout: refuse
when locked or throttled (429 + Retry-After), count every wrong password
in both tiers, clear the account count on success. /auth/token keeps its
401 for bad credentials.

The stock fastapi-users router at /auth-inner is no longer mounted: its
login bypassed every throttle and nothing called its logout. The
in-process LoginRateLimiter is gone; ThroughputLimiter is unchanged.

Claude-Session: https://claude.ai/code/session_01M9neheZZEe3sVpDi2S3zT4
---
 modules/site_lock/site_lock/rate_limit.py     |   7 +-
 modules/users/tests/_users_app_builders.py    |  29 +++-
 modules/users/tests/test_profile_password.py  |   4 +-
 modules/users/tests/test_rate_limit.py        | 108 +------------
 .../users/tests/test_users_login_lockout.py   | 142 ++++++++++++++++++
 modules/users/users/auth_local/api.py         |  49 +++---
 modules/users/users/auth_local/rate_limit.py  |  36 +----
 .../users/users/auth_local/self_account.py    |   4 +-
 modules/users/users/auth_local/token_api.py   |  15 ++
 modules/users/users/startup.py                |   7 +-
 modules/users/users/state.py                  |   3 +-
 11 files changed, 217 insertions(+), 187 deletions(-)
 create mode 100644 modules/users/tests/test_users_login_lockout.py

diff --git a/modules/site_lock/site_lock/rate_limit.py b/modules/site_lock/site_lock/rate_limit.py
index e84ef17ec..4df91f437 100644
--- a/modules/site_lock/site_lock/rate_limit.py
+++ b/modules/site_lock/site_lock/rate_limit.py
@@ -1,9 +1,8 @@
 """In-memory per-IP attempt limiter for the unlock endpoint.
 
-Deliberately process-local: it mirrors the existing ``users``
-``LoginRateLimiter`` and is adequate for the single-process staging
-deployments this module targets. ``users``' version is not reused because
-importing it would couple ``site_lock`` to the ``users`` module, and the
+Deliberately process-local: adequate for the single-process staging
+deployments this module targets. The ``users`` login lockout is not reused
+because importing it would couple ``site_lock`` to the ``users`` module, and the
 site lock must also work under the ``keycloak`` provider.
 """
 
diff --git a/modules/users/tests/_users_app_builders.py b/modules/users/tests/_users_app_builders.py
index 697e7be73..06d119f36 100644
--- a/modules/users/tests/_users_app_builders.py
+++ b/modules/users/tests/_users_app_builders.py
@@ -84,7 +84,9 @@ async def _seed_roles(application) -> None:
         await session.commit()
 
 
-async def _seed_users_settings(application, *, allow_signup: bool) -> None:
+async def _seed_users_settings(
+    application, *, allow_signup: bool, overrides: dict[str, tuple[str, str]] | None = None
+) -> None:
     """Write the test UsersSettings overrides to the DB before hydrate runs.
 
     Hydrate fires inside the lifespan ``__aenter__``, so this needs to land
@@ -95,7 +97,8 @@ async def _seed_users_settings(application, *, allow_signup: bool) -> None:
 
     async with application.state.sm.db.session_factory() as session:
         store = SettingsStore(SettingService(session))
-        for field, (raw, vtype) in _users_overrides(allow_signup=allow_signup).items():
+        rows = _users_overrides(allow_signup=allow_signup) | (overrides or {})
+        for field, (raw, vtype) in rows.items():
             await store.set_override("users", field, raw, vtype)
         await session.commit()
 
@@ -136,19 +139,33 @@ async def _make_standard_user(app, email: str = "user@example.com"):
     return user
 
 
-async def _build_users_app(monkeypatch, *, allow_signup: bool, seed_admin: bool = True):
-    """Build a test FastAPI app with DB created, settings seeded, lifespan started."""
+async def _build_users_app(
+    monkeypatch,
+    *,
+    allow_signup: bool,
+    seed_admin: bool = True,
+    database_url: str = "sqlite+aiosqlite:///:memory:",
+    overrides: dict[str, tuple[str, str]] | None = None,
+):
+    """Build a test FastAPI app with DB created, settings seeded, lifespan started.
+
+    ``database_url`` lets several apps share one SQLite file, standing in for
+    workers of one deployment; ``overrides`` adds ``UsersSettings`` rows.
+    """
     from simple_module_hosting.app_builder import create_app
 
     settings = Settings(
-        database_url="sqlite+aiosqlite:///:memory:",
+        database_url=database_url,
         environment="testing",
         secret_key="test-secret-key",
         multi_tenant=False,
+        # Explicit: a developer's .env pointing at the shared Redis would make
+        # login-lockout counters outlive the test that wrote them.
+        redis_url=None,
     )
     application = create_app(settings)
     await _setup_app_db(application)
-    await _seed_users_settings(application, allow_signup=allow_signup)
+    await _seed_users_settings(application, allow_signup=allow_signup, overrides=overrides)
 
     ctx = application.router.lifespan_context(application)
     await ctx.__aenter__()
diff --git a/modules/users/tests/test_profile_password.py b/modules/users/tests/test_profile_password.py
index 5bad394b0..b868a8969 100644
--- a/modules/users/tests/test_profile_password.py
+++ b/modules/users/tests/test_profile_password.py
@@ -149,8 +149,8 @@ async def test_profile_view_passes_the_real_user(self, admin_client):
 class TestChangePasswordIsRateLimited:
     """A live session plus a guessable current password is an online oracle.
 
-    Wrong guesses cost nothing here — ``LoginRateLimiter`` only fronts
-    ``/auth/login`` — so an attacker on an unattended browser could grind the
+    Wrong guesses cost nothing here — the login lockout only fronts
+    ``/auth/login`` and ``/auth/token`` — so an attacker on an unattended browser could grind the
     current password at whatever rate the hasher allows.
     """
 
diff --git a/modules/users/tests/test_rate_limit.py b/modules/users/tests/test_rate_limit.py
index 6698f23de..21e601531 100644
--- a/modules/users/tests/test_rate_limit.py
+++ b/modules/users/tests/test_rate_limit.py
@@ -1,112 +1,8 @@
-"""Tests for LoginRateLimiter and ThroughputLimiter."""
+"""Tests for ThroughputLimiter."""
 
 from __future__ import annotations
 
-import pytest
-from users.auth_local.rate_limit import LoginRateLimiter, ThroughputLimiter
-
-
-@pytest.fixture
-def limiter():
-    """A limiter with max 5 failures, very short TTLs for fast tests."""
-    return LoginRateLimiter(max_failures=5, window_seconds=60, cooldown_seconds=900)
-
-
-class TestIsLocked:
-    def test_not_locked_initially(self, limiter):
-        assert limiter.is_locked("user@example.com::1.2.3.4") is False
-
-    def test_not_locked_after_four_failures(self, limiter):
-        key = "user@example.com::1.2.3.4"
-        for _ in range(4):
-            limiter.record_failure(key)
-        assert limiter.is_locked(key) is False
-
-    def test_locked_after_five_failures(self, limiter):
-        key = "user@example.com::1.2.3.4"
-        for _ in range(5):
-            limiter.record_failure(key)
-        assert limiter.is_locked(key) is True
-
-    def test_sixth_request_still_locked(self, limiter):
-        """Once locked, subsequent calls don't unlock."""
-        key = "user@example.com::1.2.3.4"
-        for _ in range(6):
-            limiter.record_failure(key)
-        assert limiter.is_locked(key) is True
-
-
-class TestRecordFailure:
-    def test_failure_counter_increments(self, limiter):
-        key = "a::1"
-        limiter.record_failure(key)
-        limiter.record_failure(key)
-        # Not locked after 2 failures (max is 5)
-        assert limiter.is_locked(key) is False
-
-    def test_reaching_max_clears_fail_counter(self, limiter):
-        """After locking, the failure counter is removed (lock handles timeout)."""
-        key = "a::1"
-        for _ in range(5):
-            limiter.record_failure(key)
-        # Lock bucket holds the lock; fail bucket is cleared
-        assert limiter.is_locked(key) is True
-        # Further record_failure on a locked key doesn't raise
-        limiter.record_failure(key)
-        assert limiter.is_locked(key) is True
-
-
-class TestReset:
-    def test_reset_clears_failure_count(self, limiter):
-        key = "b::2"
-        for _ in range(4):
-            limiter.record_failure(key)
-        limiter.reset(key)
-        # After reset, another 4 failures should NOT lock
-        for _ in range(4):
-            limiter.record_failure(key)
-        assert limiter.is_locked(key) is False
-
-    def test_reset_clears_lock(self, limiter):
-        key = "b::2"
-        for _ in range(5):
-            limiter.record_failure(key)
-        assert limiter.is_locked(key) is True
-        limiter.reset(key)
-        assert limiter.is_locked(key) is False
-
-    def test_reset_on_unknown_key_does_not_raise(self, limiter):
-        limiter.reset("never-seen-key::0.0.0.0")
-
-    def test_successful_login_resets_counter(self, limiter):
-        """Simulates a successful login after some failures resetting state."""
-        key = "c::3"
-        for _ in range(3):
-            limiter.record_failure(key)
-        # Successful login → reset
-        limiter.reset(key)
-        # Now 5 fresh failures should lock
-        for _ in range(5):
-            limiter.record_failure(key)
-        assert limiter.is_locked(key) is True
-
-
-class TestPerKeyIsolation:
-    def test_different_keys_independent(self, limiter):
-        key1 = "alice@example.com::1.1.1.1"
-        key2 = "bob@example.com::2.2.2.2"
-        for _ in range(5):
-            limiter.record_failure(key1)
-        assert limiter.is_locked(key1) is True
-        assert limiter.is_locked(key2) is False
-
-    def test_same_email_different_ip_independent(self, limiter):
-        key1 = "user@example.com::1.1.1.1"
-        key2 = "user@example.com::2.2.2.2"
-        for _ in range(5):
-            limiter.record_failure(key1)
-        assert limiter.is_locked(key1) is True
-        assert limiter.is_locked(key2) is False
+from users.auth_local.rate_limit import ThroughputLimiter
 
 
 class TestThroughputLimiter:
diff --git a/modules/users/tests/test_users_login_lockout.py b/modules/users/tests/test_users_login_lockout.py
new file mode 100644
index 000000000..d2e478abe
--- /dev/null
+++ b/modules/users/tests/test_users_login_lockout.py
@@ -0,0 +1,142 @@
+"""Login lockout through the HTTP routes, across IPs and app instances (GH #530)."""
+
+from __future__ import annotations
+
+import httpx
+import pytest
+from _users_app_builders import _build_users_app, _make_standard_user
+from sqlalchemy import select
+from users.auth_local.lockout import LOCKED_DETAIL
+from users.models import User
+
+ALICE = "alice@example.com"
+PASSWORD = "UserPass1!"
+
+
+def _client(app, ip: str) -> httpx.AsyncClient:
+    transport = httpx.ASGITransport(app=app, client=(ip, 1))
+    return httpx.AsyncClient(transport=transport, base_url="http://testserver")
+
+
+async def _login(app, ip: str, username: str, password: str) -> httpx.Response:
+    async with _client(app, ip) as c:
+        return await c.post(
+            "/api/users/auth/login", data={"username": username, "password": password}
+        )
+
+
+async def _token(app, ip: str, email: str, password: str) -> httpx.Response:
+    async with _client(app, ip) as c:
+        return await c.post("/api/users/auth/token", json={"email": email, "password": password})
+
+
+async def _alice_row(app) -> User:
+    async with app.state.sm.db.session_factory() as session:
+        return (await session.execute(select(User).where(User.email == ALICE))).scalar_one()
+
+
+@pytest.fixture
+async def alice(users_app):
+    return await _make_standard_user(users_app, ALICE)
+
+
+async def test_acceptance_three_ips_two_apps_survives_restart(monkeypatch, tmp_path) -> None:
+    url = f"sqlite+aiosqlite:///{tmp_path / 'lockout.db'}"
+    overrides = {"login_lockout_account_failures": ("5", "int")}
+    contexts = []
+
+    async def build():
+        app, ctx = await _build_users_app(
+            monkeypatch, allow_signup=False, database_url=url, overrides=overrides
+        )
+        contexts.append(ctx)
+        return app
+
+    try:
+        app_a, app_b = await build(), await build()
+        await _make_standard_user(app_a, ALICE)
+        plan = [
+            (app_a, "1.1.1.1"),
+            (app_b, "2.2.2.2"),
+            (app_a, "3.3.3.3"),
+            (app_b, "1.1.1.1"),
+            (app_a, "2.2.2.2"),
+        ]
+        for app, ip in plan:
+            assert (await _login(app, ip, ALICE, "wrong")).status_code == 400
+
+        r = await _login(app_b, "9.9.9.9", ALICE, PASSWORD)
+        assert r.status_code == 429
+        assert r.json()["detail"] == LOCKED_DETAIL
+        assert 0 < int(r.headers["Retry-After"]) <= 900
+
+        app_c = await build()  # a restart: fresh process memory, same database
+        assert (await _login(app_c, "8.8.8.8", ALICE, PASSWORD)).status_code == 429
+        assert (await _token(app_c, "8.8.8.8", ALICE, PASSWORD)).status_code == 429
+    finally:
+        for ctx in reversed(contexts):
+            await ctx.__aexit__(None, None, None)
+
+
+async def test_failures_persist_across_requests(users_app, alice) -> None:
+    for _ in range(2):
+        assert (await _login(users_app, "1.1.1.1", ALICE, "wrong")).status_code == 400
+    assert (await _alice_row(users_app)).failed_login_count == 2
+
+
+async def test_token_failures_count_too(users_app, alice) -> None:
+    r = await _token(users_app, "1.1.1.1", ALICE, "wrong")
+    assert (r.status_code, r.json()["detail"]) == (401, "Invalid credentials")
+    assert (await _alice_row(users_app)).failed_login_count == 1
+
+
+async def test_success_resets_count(users_app, alice) -> None:
+    for _ in range(2):
+        await _login(users_app, "1.1.1.1", ALICE, "wrong")
+    assert (await _login(users_app, "1.1.1.1", ALICE, PASSWORD)).status_code == 204
+    row = await _alice_row(users_app)
+    assert (row.failed_login_count, row.last_failed_login_at) == (0, None)
+
+
+async def test_token_success_resets_count(users_app, alice) -> None:
+    await _token(users_app, "1.1.1.1", ALICE, "wrong")
+    assert (await _token(users_app, "1.1.1.1", ALICE, PASSWORD)).status_code == 200
+    assert (await _alice_row(users_app)).failed_login_count == 0
+
+
+async def test_correct_password_while_locked_does_not_unlock(users_app, alice) -> None:
+    for i in range(10):
+        await _login(users_app, f"10.0.0.{i}", ALICE, "wrong")
+    locked = (await _alice_row(users_app)).locked_until
+    assert locked is not None
+    assert (await _login(users_app, "9.9.9.9", ALICE, PASSWORD)).status_code == 429
+    assert (await _alice_row(users_app)).locked_until == locked
+
+
+async def test_unknown_and_locked_look_the_same(users_app, alice) -> None:
+    for i in range(10):
+        await _login(users_app, f"10.0.0.{i}", ALICE, "wrong")
+        await _login(users_app, f"10.0.0.{i}", "ghost@example.com", "wrong")
+    locked = await _login(users_app, "9.9.9.9", ALICE, PASSWORD)
+    unknown = await _login(users_app, "9.9.9.9", "ghost@example.com", "whatever")
+    assert locked.status_code == unknown.status_code == 429
+    assert locked.json()["detail"] == unknown.json()["detail"] == LOCKED_DETAIL
+
+
+async def test_tier2_throttles_ip_not_account(users_app, alice) -> None:
+    for _ in range(5):
+        assert (await _login(users_app, "1.1.1.1", ALICE, "wrong")).status_code == 400
+    assert (await _login(users_app, "1.1.1.1", ALICE, PASSWORD)).status_code == 429
+    assert (await _token(users_app, "1.1.1.1", ALICE, PASSWORD)).status_code == 429
+    assert (await _login(users_app, "2.2.2.2", ALICE, "wrong")).status_code == 400
+    assert (await _login(users_app, "2.2.2.2", ALICE, PASSWORD)).status_code == 204
+
+
+async def test_auth_inner_login_is_gone(users_app, alice) -> None:
+    r = await _login(users_app, "1.1.1.1", ALICE, PASSWORD)
+    assert r.status_code == 204  # the wrapper still works...
+    async with _client(users_app, "1.1.1.1") as c:
+        inner = await c.post(
+            "/api/users/auth-inner/login", data={"username": ALICE, "password": PASSWORD}
+        )
+    assert inner.status_code in (404, 405)  # ...the unthrottled stock route does not
diff --git a/modules/users/users/auth_local/api.py b/modules/users/users/auth_local/api.py
index ede5b77a7..c4f65a3e9 100644
--- a/modules/users/users/auth_local/api.py
+++ b/modules/users/users/auth_local/api.py
@@ -1,11 +1,11 @@
 """REST endpoints for local-credential auth + self profile.
 
 Routes owned here (all mounted by :meth:`UsersModule.register_routes`):
-  POST /api/users/auth/login          — rate-limited wrapper around fastapi-users
+  POST /api/users/auth/login          — lockout-guarded wrapper around fastapi-users
+  POST /api/users/auth/logout         — clears the access-token cookie and session
   POST /api/users/auth/accept-invite  — verify invite + set password + login
   GET  /api/users/me                  — current user
   PATCH /api/users/me                 — update current user
-  /api/users/auth-inner/*             — fastapi-users stock auth router
 """
 
 from __future__ import annotations
@@ -17,12 +17,18 @@
 from fastapi.security import OAuth2PasswordRequestForm
 from fastapi_users import exceptions as fu_exceptions
 from simple_module_core.redirect_safety import SESSION_NEXT_KEY
+from simple_module_db.deps import get_db
 from simple_module_hosting.session import SESSION_REMEMBER_KEY, stamp_session_expiry
-
-from users.auth_local.rate_limit import (
-    LoginRateLimiter,
-    enforce_auth_throughput_limit,
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from users.auth_local.lockout import (
+    login_attempt,
+    record_failure,
+    record_success,
+    refused_for,
+    too_many_attempts,
 )
+from users.auth_local.rate_limit import enforce_auth_throughput_limit
 from users.auth_local.self_account import router as self_account_router
 from users.backend import build_cookie_transport, build_strategy
 from users.constants import SESSION_USER_ID_KEY
@@ -50,14 +56,6 @@
 __all__ = ["enforce_auth_throughput_limit", "router"]
 
 
-# ── Rate limit ───────────────────────────────────────────────────────────────
-
-
-async def get_rate_limiter(request: Request) -> LoginRateLimiter:
-    """Return the per-app LoginRateLimiter built in UsersModule.on_startup."""
-    return request.app.state.users.rate_limiter
-
-
 async def require_signup_enabled(request: Request) -> None:
     """Gate the register endpoint at request time on ``allow_signup``.
 
@@ -104,12 +102,12 @@ async def login(
     user_manager: UserManager = Depends(get_user_manager),
     strategy=Depends(auth_backend.get_strategy),
     access_token_db=Depends(get_access_token_db),
-    limiter: LoginRateLimiter = Depends(get_rate_limiter),
+    db: AsyncSession = Depends(get_db),
 ):
-    """Rate-limited login wrapper. Sets sm_auth cookie + session user_id."""
-    key = f"{credentials.username.lower()}::{request.client.host if request.client else 'unknown'}"
-    if limiter.is_locked(key):
-        raise HTTPException(status_code=429, detail="Too many attempts — try again later")
+    """Lockout-guarded login wrapper. Sets sm_auth cookie + session user_id."""
+    attempt = login_attempt(request, credentials.username)
+    if (wait := await refused_for(db, attempt)) is not None:
+        raise too_many_attempts(wait)
 
     try:
         user = await user_manager.authenticate(
@@ -122,7 +120,7 @@ async def login(
         user = None
 
     if user is None or not user.is_active:
-        limiter.record_failure(key)
+        await record_failure(db, attempt)
         raise HTTPException(status_code=400, detail="LOGIN_BAD_CREDENTIALS")
 
     if not user.is_verified and request.app.state.users.settings.require_verification:
@@ -131,7 +129,7 @@ async def login(
         # accounts that signed up while it was on.
         raise HTTPException(status_code=400, detail="LOGIN_USER_NOT_VERIFIED")
 
-    limiter.reset(key)
+    await record_success(db, user.id)
     # Fire the login hook (updates last_login_at)
     await user_manager.on_after_login(user, request, response)
     # Set fastapi-users' cookie via auth_backend.login
@@ -162,13 +160,10 @@ async def login(
     return login_response
 
 
-# ── Mount fastapi-users stock routers ────────────────────────────────────────
+# ── Logout ───────────────────────────────────────────────────────────────────
 
-# The stock auth router (login + logout) is mounted at /auth-inner so its
-# endpoints remain accessible. Our wrappers at /auth/login and /auth/logout
-# shadow the stock endpoints to also manage the session cookie.
-auth_inner = fastapi_users.get_auth_router(auth_backend, requires_verification=True)
-router.include_router(auth_inner, prefix="/auth-inner")
+# The stock fastapi-users auth router is deliberately not mounted: its login
+# sits outside the lockout above (GH #530), and nothing called its logout.
 
 
 @router.post("/auth/logout", status_code=204)
diff --git a/modules/users/users/auth_local/rate_limit.py b/modules/users/users/auth_local/rate_limit.py
index 1fa89d616..9a5d03f8d 100644
--- a/modules/users/users/auth_local/rate_limit.py
+++ b/modules/users/users/auth_local/rate_limit.py
@@ -1,9 +1,9 @@
-"""In-process rate limiters — TTL caches, no Redis.
+"""In-process throughput limiter for auth side-effect endpoints — TTL caches, no Redis.
 
 Note: counters live in the worker process, so a multi-worker deployment (e.g.
 ``uvicorn --workers 4``) has independent counters per worker. Effective
-thresholds scale with worker count. Swap for a Redis-backed store when you
-deploy behind more than a single worker.
+thresholds scale with worker count. Password-login lockout is not here: it
+lives in :mod:`users.auth_local.lockout`, shared across workers.
 """
 
 from __future__ import annotations
@@ -12,40 +12,12 @@
 from fastapi import HTTPException, Request, status
 
 
-class LoginRateLimiter:
-    """Per-key failure counter with a cooldown window after N failures."""
-
-    def __init__(
-        self,
-        max_failures: int = 5,
-        window_seconds: int = 300,
-        cooldown_seconds: int = 900,
-    ) -> None:
-        self._fails: TTLCache = TTLCache(maxsize=10_000, ttl=window_seconds)
-        self._locks: TTLCache = TTLCache(maxsize=10_000, ttl=cooldown_seconds)
-        self._max = max_failures
-
-    def is_locked(self, key: str) -> bool:
-        return key in self._locks
-
-    def record_failure(self, key: str) -> None:
-        count = self._fails.get(key, 0) + 1
-        self._fails[key] = count
-        if count >= self._max:
-            self._locks[key] = True
-            self._fails.pop(key, None)
-
-    def reset(self, key: str) -> None:
-        self._fails.pop(key, None)
-        self._locks.pop(key, None)
-
-
 class ThroughputLimiter:
     """N requests per rolling window per key — counts every attempt.
 
     Used to dampen enumeration and email-spam on endpoints like
     ``/forgot-password`` and ``/register`` where a failure-based lockout
-    (``LoginRateLimiter``) isn't the right shape — the attacker is after the
+    (:mod:`users.auth_local.lockout`) isn't the right shape — the attacker is after the
     side-effect itself, not a correct credential.
     """
 
diff --git a/modules/users/users/auth_local/self_account.py b/modules/users/users/auth_local/self_account.py
index 1b63a2512..03a845a24 100644
--- a/modules/users/users/auth_local/self_account.py
+++ b/modules/users/users/auth_local/self_account.py
@@ -34,8 +34,8 @@
     "/me/password",
     status_code=204,
     # A live session plus a guessable current password is an online oracle,
-    # and wrong guesses cost nothing here: ``LoginRateLimiter`` only fronts
-    # ``/auth/login``. Same budget as the other credential-adjacent
+    # and wrong guesses cost nothing here: the login lockout only fronts
+    # ``/auth/login`` and ``/auth/token``. Same budget as the other credential-adjacent
     # endpoints, keyed on path + client IP.
     dependencies=[Depends(enforce_auth_throughput_limit)],
 )
diff --git a/modules/users/users/auth_local/token_api.py b/modules/users/users/auth_local/token_api.py
index 61633630a..271f68d69 100644
--- a/modules/users/users/auth_local/token_api.py
+++ b/modules/users/users/auth_local/token_api.py
@@ -16,6 +16,13 @@
 from sqlalchemy.ext.asyncio import AsyncSession
 from sqlmodel import SQLModel
 
+from users.auth_local.lockout import (
+    login_attempt,
+    record_failure,
+    record_success,
+    refused_for,
+    too_many_attempts,
+)
 from users.models import User
 from users.models.refresh_token import RefreshToken
 
@@ -59,6 +66,11 @@ async def token_login(
     from fastapi_users.password import PasswordHelper
 
     helper = PasswordHelper()
+    # Same lockout as the session login (GH #530): refused before any work,
+    # every wrong password counted, a success clearing the account's count.
+    attempt = login_attempt(request, body.email)
+    if (wait := await refused_for(db, attempt)) is not None:
+        raise too_many_attempts(wait)
 
     stmt = select(User).where(User.email == body.email)
     user = (await db.execute(stmt)).scalar_one_or_none()
@@ -77,10 +89,12 @@ async def token_login(
         # email enumeration (existing user + wrong password takes ~50ms for
         # bcrypt; missing user would be instant without this).
         helper.verify_and_update(body.password, _DUMMY_HASH)
+        await record_failure(db, attempt)
         raise HTTPException(status_code=401, detail="Invalid credentials")
 
     verified, updated_hash = helper.verify_and_update(body.password, user.hashed_password)
     if not verified:
+        await record_failure(db, attempt)
         raise HTTPException(status_code=401, detail="Invalid credentials")
     if updated_hash is not None:
         # A legacy-scheme hash (e.g. bcrypt) was accepted and re-hashed with the
@@ -94,6 +108,7 @@ async def token_login(
         # Same rule as the session login: a self-registered account that never
         # proved its address must not mint bearer tokens either (#547).
         raise HTTPException(status_code=400, detail="LOGIN_USER_NOT_VERIFIED")
+    await record_success(db, user.id)
     return await _create_token_pair(db, user.id, settings, user.session_version)
 
 
diff --git a/modules/users/users/startup.py b/modules/users/users/startup.py
index c7d77adbb..6516c81ed 100644
--- a/modules/users/users/startup.py
+++ b/modules/users/users/startup.py
@@ -114,13 +114,8 @@ def register_mailer_health_check(app: FastAPI, module_name: str) -> None:
 
 
 def _build_limiters(state, s) -> None:
-    from users.auth_local.rate_limit import LoginRateLimiter, ThroughputLimiter
+    from users.auth_local.rate_limit import ThroughputLimiter
 
-    state.rate_limiter = LoginRateLimiter(
-        max_failures=s.login_rate_limit_failures,
-        window_seconds=s.login_rate_limit_window_seconds,
-        cooldown_seconds=s.login_rate_limit_cooldown_seconds,
-    )
     state.auth_throughput_limiter = ThroughputLimiter(
         max_attempts=s.auth_rate_limit_attempts,
         window_seconds=s.auth_rate_limit_window_seconds,
diff --git a/modules/users/users/state.py b/modules/users/users/state.py
index da4b949a9..37f3df6b8 100644
--- a/modules/users/users/state.py
+++ b/modules/users/users/state.py
@@ -18,7 +18,7 @@
 if TYPE_CHECKING:
     import uuid
 
-    from users.auth_local.rate_limit import LoginRateLimiter, ThroughputLimiter
+    from users.auth_local.rate_limit import ThroughputLimiter
     from users.mailer import Mailer
     from users.oauth.providers import OAuthProvider
     from users.roles_cache import RoleSummary
@@ -31,7 +31,6 @@ class UsersState:
 
     settings: UsersSettings
     mailer: Mailer | None = None
-    rate_limiter: LoginRateLimiter | None = None
     auth_throughput_limiter: ThroughputLimiter | None = None
     roles_cache: list[RoleSummary] = field(default_factory=list)
     oauth_providers: list[dict[str, str]] = field(default_factory=list)

From 215693cc682bb1f5ce8d2ddf7efd07bdaf020155 Mon Sep 17 00:00:00 2001
From: Anto Subash <antosubash@live.com>
Date: Mon, 19 Oct 2026 11:29:29 +0200
Subject: [PATCH 07/13] feat(users): admin unlock and locked state in the users
 UI (#530)

PATCH /api/users/admin/{id}/unlock clears the lock and the counters
through the ORM, so the unlock is audited. UserListItem carries
locked_until (only while the lock holds); the users list shows a
"locked" badge and the edit page a "Locked until" row with Unlock.

Claude-Session: https://claude.ai/code/session_01M9neheZZEe3sVpDi2S3zT4
---
 .../users/tests-js/AccountCardLocked.test.tsx | 50 ++++++++++
 .../users/tests/test_users_admin_unlock.py    | 94 +++++++++++++++++++
 modules/users/users/admin/api.py              | 13 +++
 .../users/admin/components/StatusPill.tsx     | 18 ++++
 .../users/admin/components/UserCards.tsx      |  1 +
 .../users/users/admin/components/UserRow.tsx  |  3 +-
 .../users/admin/components/user-list-item.ts  |  2 +
 modules/users/users/admin/queries.py          | 17 +++-
 modules/users/users/admin/service.py          |  9 ++
 modules/users/users/contracts/schemas.py      |  2 +
 modules/users/users/locales/en.json           | 13 ++-
 modules/users/users/pages/Users/Edit.tsx      |  9 +-
 .../pages/Users/components/AccountCard.tsx    | 25 ++++-
 .../pages/Users/components/useUserActions.ts  | 18 +++-
 packages/i18n/src/generated-resources.ts      |  5 +
 packages/i18n/src/keys.generated.ts           |  5 +
 16 files changed, 274 insertions(+), 10 deletions(-)
 create mode 100644 modules/users/tests-js/AccountCardLocked.test.tsx
 create mode 100644 modules/users/tests/test_users_admin_unlock.py

diff --git a/modules/users/tests-js/AccountCardLocked.test.tsx b/modules/users/tests-js/AccountCardLocked.test.tsx
new file mode 100644
index 000000000..b423a442e
--- /dev/null
+++ b/modules/users/tests-js/AccountCardLocked.test.tsx
@@ -0,0 +1,50 @@
+import '@testing-library/jest-dom/vitest';
+import { configureI18n } from '@simple-module-py/i18n';
+import { fireEvent, render, screen } from '@testing-library/react';
+import { describe, expect, test, vi } from 'vitest';
+
+configureI18n({
+  locale: 'en',
+  messages: {
+    'users.metadata_card.locked_until': 'Locked until',
+    'users.account_status.unlock_button': 'Unlock',
+  },
+});
+
+import { AccountCard } from '../users/pages/Users/components/AccountCard';
+
+const base = {
+  email: 'alice@example.com',
+  isExternal: false,
+  createdAt: '2026-01-01T00:00:00Z',
+  disabledAt: null,
+  isActive: true,
+  isVerified: true,
+  savingStatus: false,
+  savingVerify: false,
+  onDisable: () => {},
+  onEnable: () => {},
+  onMarkVerified: () => {},
+  onCopyResetLink: () => {},
+};
+
+describe('AccountCard lockout', () => {
+  test('a locked account shows when the lock lifts and an Unlock action', () => {
+    const onUnlock = vi.fn();
+    render(<AccountCard {...base} lockedUntil="2026-10-19T12:30:00Z" onUnlock={onUnlock} />);
+    expect(screen.getByText('Locked until')).toBeInTheDocument();
+    fireEvent.click(screen.getByRole('button', { name: 'Unlock' }));
+    expect(onUnlock).toHaveBeenCalledTimes(1);
+  });
+
+  test('an unlocked account shows neither', () => {
+    render(<AccountCard {...base} lockedUntil={null} />);
+    expect(screen.queryByText('Locked until')).not.toBeInTheDocument();
+    expect(screen.queryByRole('button', { name: 'Unlock' })).not.toBeInTheDocument();
+  });
+
+  test('Unlock is disabled while a status change is saving', () => {
+    render(<AccountCard {...base} lockedUntil="2026-10-19T12:30:00Z" savingStatus />);
+    expect(screen.getByRole('button', { name: 'Unlock' })).toBeDisabled();
+  });
+});
diff --git a/modules/users/tests/test_users_admin_unlock.py b/modules/users/tests/test_users_admin_unlock.py
new file mode 100644
index 000000000..3878ca4b5
--- /dev/null
+++ b/modules/users/tests/test_users_admin_unlock.py
@@ -0,0 +1,94 @@
+"""Admin unlock and the locked state in the admin API (GH #530)."""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime, timedelta
+
+import httpx
+import pytest
+from _users_app_builders import _make_standard_user
+from sqlalchemy import select
+from users.models import User
+
+ALICE = "alice@example.com"
+
+
+@pytest.fixture
+async def alice(users_app):
+    return await _make_standard_user(users_app, ALICE)
+
+
+async def _lock_by_failing(users_app) -> None:
+    for i in range(10):
+        transport = httpx.ASGITransport(app=users_app, client=(f"10.0.0.{i}", 1))
+        async with httpx.AsyncClient(transport=transport, base_url="http://testserver") as c:
+            r = await c.post("/api/users/auth/login", data={"username": ALICE, "password": "no"})
+            assert r.status_code == 400
+
+
+async def _row(users_app) -> User:
+    async with users_app.state.sm.db.session_factory() as session:
+        return (await session.execute(select(User).where(User.email == ALICE))).scalar_one()
+
+
+async def _list_item(admin_client, user_id) -> dict:
+    r = await admin_client.get("/api/users/admin", params={"q": "alice"})
+    assert r.status_code == 200
+    [item] = [u for u in r.json() if u["id"] == str(user_id)]
+    return item
+
+
+async def test_list_reports_locked_until(users_app, admin_client, alice) -> None:
+    assert (await _list_item(admin_client, alice.id))["locked_until"] is None
+    await _lock_by_failing(users_app)
+    assert (await _list_item(admin_client, alice.id))["locked_until"] is not None
+
+
+async def test_expired_lock_is_not_reported(users_app, admin_client, alice) -> None:
+    async with users_app.state.sm.db.session_factory() as session:
+        row = await session.get(User, alice.id)
+        assert row is not None
+        row.locked_until = datetime.now(UTC) - timedelta(seconds=1)
+        await session.commit()
+    assert (await _list_item(admin_client, alice.id))["locked_until"] is None
+
+
+async def test_unlock_clears_lock_and_is_audited(users_app, admin_client, alice) -> None:
+    from audit_log.models import AuditEntry
+
+    await _lock_by_failing(users_app)
+    r = await admin_client.patch(f"/api/users/admin/{alice.id}/unlock")
+    assert r.status_code == 200
+    assert r.json()["locked_until"] is None
+
+    row = await _row(users_app)
+    assert (row.locked_until, row.failed_login_count, row.last_failed_login_at) == (None, 0, None)
+
+    async with users_app.state.sm.db.session_factory() as session:
+        stmt = select(AuditEntry).where(
+            AuditEntry.entity_type == "User", AuditEntry.entity_id == str(alice.id)
+        )
+        entries = [e for e in (await session.execute(stmt)).scalars() if e.action == "updated"]
+    fields = [sorted(c["field"] for c in e.changes) for e in entries]
+    # One entry for the lock, one for the unlock, nothing for the nine plain failures.
+    assert [f for f in fields if "locked_until" in f] == [["locked_until"], ["locked_until"]]
+    assert all("failed_login_count" not in f for f in fields)
+    assert len(entries) == 2
+
+    # The account signs in again.
+    transport = httpx.ASGITransport(app=users_app, client=("9.9.9.9", 1))
+    async with httpx.AsyncClient(transport=transport, base_url="http://testserver") as c:
+        login = await c.post(
+            "/api/users/auth/login", data={"username": ALICE, "password": "UserPass1!"}
+        )
+    assert login.status_code == 204
+
+
+async def test_unlock_unknown_user_is_404(admin_client) -> None:
+    r = await admin_client.patch("/api/users/admin/00000000-0000-0000-0000-000000000000/unlock")
+    assert r.status_code == 404
+
+
+async def test_unlock_requires_manage(user_client, alice) -> None:
+    r = await user_client.patch(f"/api/users/admin/{alice.id}/unlock")
+    assert r.status_code == 403
diff --git a/modules/users/users/admin/api.py b/modules/users/users/admin/api.py
index 0c4ee51a7..b23988595 100644
--- a/modules/users/users/admin/api.py
+++ b/modules/users/users/admin/api.py
@@ -206,6 +206,19 @@ async def admin_enable_user(
     return service.to_list_item(user)
 
 
+@admin_router.patch("/{user_id}/unlock", response_model=UserListItem)
+async def admin_unlock_user(
+    user_id: uuid.UUID,
+    service: UserService = Depends(get_user_service),
+):
+    """Lift a login lockout (GH #530) before its cooldown ends."""
+    try:
+        user = await service.unlock(user_id)
+    except UserNotFoundError:
+        raise HTTPException(status_code=404, detail="User not found") from None
+    return service.to_list_item(user)
+
+
 @admin_router.put("/{user_id}/roles", response_model=UserListItem)
 async def admin_set_roles(
     user_id: uuid.UUID,
diff --git a/modules/users/users/admin/components/StatusPill.tsx b/modules/users/users/admin/components/StatusPill.tsx
index 168f02072..356a5c22a 100644
--- a/modules/users/users/admin/components/StatusPill.tsx
+++ b/modules/users/users/admin/components/StatusPill.tsx
@@ -1,4 +1,5 @@
 import { keys, useT } from '@simple-module-py/i18n';
+import { Badge } from '@simple-module-py/ui/components/ui/badge';
 import { cn } from '@simple-module-py/ui/lib/utils';
 import { STATE_PILL, type UserState } from './user-list-item';
 
@@ -28,3 +29,20 @@ export function StatusPill({ state }: { state: UserState }) {
     </span>
   );
 }
+
+/**
+ * Shown beside the status pill while a login lockout holds. Not a state of its
+ * own: a locked account is still active, and unlocks itself when the cooldown
+ * ends.
+ */
+export function LockedBadge() {
+  const { t } = useT();
+  return (
+    <Badge
+      variant="outline"
+      className="border-red-200 bg-red-50 text-red-700 dark:border-red-900 dark:bg-red-950 dark:text-red-300"
+    >
+      {t(keys.users.user_row.locked_badge)}
+    </Badge>
+  );
+}
diff --git a/modules/users/users/admin/components/UserCards.tsx b/modules/users/users/admin/components/UserCards.tsx
index d92740e9c..6d6fb287e 100644
--- a/modules/users/users/admin/components/UserCards.tsx
+++ b/modules/users/users/admin/components/UserCards.tsx
@@ -35,6 +35,7 @@ export function UserCards({ users }: { users: UserListItem[] }) {
         invited: t(keys.users.user_row.status_invited),
         disabled: t(keys.users.user_row.status_disabled),
       }[user.state],
+      user.locked_until ? t(keys.users.user_row.locked_badge) : null,
       user.last_login_at ? ago(user.last_login_at) : null,
     ];
     return parts.filter(Boolean).join(' · ');
diff --git a/modules/users/users/admin/components/UserRow.tsx b/modules/users/users/admin/components/UserRow.tsx
index 6624bb9fc..f1e70f751 100644
--- a/modules/users/users/admin/components/UserRow.tsx
+++ b/modules/users/users/admin/components/UserRow.tsx
@@ -6,7 +6,7 @@ import { TableCell, TableRow } from '@simple-module-py/ui/components/ui/table';
 import { useRelativeTime } from '@simple-module-py/ui/hooks/use-relative-time';
 import { initials } from '@simple-module-py/ui/lib/initials';
 import { cn } from '@simple-module-py/ui/lib/utils';
-import { StatusPill } from './StatusPill';
+import { LockedBadge, StatusPill } from './StatusPill';
 import { UserRowMenu } from './UserRowMenu';
 import type { UserListItem } from './user-list-item';
 import type { UserRowActions } from './useUserRowActions';
@@ -116,6 +116,7 @@ export function UserRow({ user, actions }: Props) {
       <TableCell className="hidden sm:table-cell">
         <div className="flex items-center gap-1.5">
           <StatusPill state={user.state} />
+          {user.locked_until && <LockedBadge />}
           {user.is_external && (
             <Badge variant="outline" className="border-violet-200 bg-violet-50 text-violet-700">
               {t(keys.users.user_row.sso_badge)}
diff --git a/modules/users/users/admin/components/user-list-item.ts b/modules/users/users/admin/components/user-list-item.ts
index 6be0ba463..4aac86017 100644
--- a/modules/users/users/admin/components/user-list-item.ts
+++ b/modules/users/users/admin/components/user-list-item.ts
@@ -13,6 +13,8 @@ export interface UserListItem {
   invite_expires_at: string | null;
   /** Computed server-side so the pill, the filter and the count cannot drift. */
   state: UserState;
+  /** When a login lockout lifts; `null` unless one holds right now. */
+  locked_until?: string | null;
   roles: string[];
 }
 
diff --git a/modules/users/users/admin/queries.py b/modules/users/users/admin/queries.py
index a8a9cfad6..ca19fe66f 100644
--- a/modules/users/users/admin/queries.py
+++ b/modules/users/users/admin/queries.py
@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 import uuid
-from datetime import datetime, timedelta
+from datetime import UTC, datetime, timedelta
 
 from simple_module_db import LIKE_ESCAPE_CHAR, like_contains_pattern
 from sqlalchemy import func, or_, select
@@ -17,6 +17,17 @@
 from users.models import Role, User, UserRole
 
 
+def _live_lock(locked_until: datetime | None) -> datetime | None:
+    """*locked_until* while the lock holds, else ``None``.
+
+    An expired lock stays on the row until the next failure or an unlock; it
+    refuses nothing any more, so the admin screens must not show it.
+    """
+    if locked_until is not None and locked_until > datetime.now(UTC):
+        return locked_until
+    return None
+
+
 class _UserServiceBase:
     def __init__(
         self,
@@ -63,6 +74,7 @@ def to_list_item(self, user: User) -> UserListItem:
             invited_at=user.invited_at,
             invite_expires_at=self._invite_expiry(user.invited_at),
             state=user_state(user.is_active, user.is_verified, user.invited_at),
+            locked_until=_live_lock(user.locked_until),
             roles=[r.name for r in user.roles],
         )
 
@@ -132,6 +144,7 @@ async def list_users(
             User.last_login_at,
             User.created_at,
             User.invited_at,
+            User.locked_until,
         )
         count_stmt = select(func.count()).select_from(User)
 
@@ -208,7 +221,7 @@ async def list_users(
         # roles): unpack directly.
         items = [
             UserListItem(
-                **r._mapping,
+                **{**r._mapping, "locked_until": _live_lock(r.locked_until)},
                 invite_expires_at=self._invite_expiry(r.invited_at),
                 state=user_state(r.is_active, r.is_verified, r.invited_at),
                 roles=roles_by_user.get(r.id, []),
diff --git a/modules/users/users/admin/service.py b/modules/users/users/admin/service.py
index d8566cb9a..4ddc69110 100644
--- a/modules/users/users/admin/service.py
+++ b/modules/users/users/admin/service.py
@@ -220,6 +220,15 @@ async def enable(self, user_id: uuid.UUID) -> User:
         await self._db.flush()
         return user
 
+    async def unlock(self, user_id: uuid.UUID) -> User:
+        """Lift a login lockout early. An ORM write, so the audit log records it."""
+        user = await self._require_user(user_id)
+        user.locked_until = None
+        user.failed_login_count = 0
+        user.last_failed_login_at = None
+        await self._db.flush()
+        return user
+
     async def mark_verified(self, user_id: uuid.UUID) -> User:
         user = await self._require_user(user_id)
         if not user.is_verified:
diff --git a/modules/users/users/contracts/schemas.py b/modules/users/users/contracts/schemas.py
index ea667166c..9588a4435 100644
--- a/modules/users/users/contracts/schemas.py
+++ b/modules/users/users/contracts/schemas.py
@@ -150,6 +150,8 @@ class UserListItem(SQLModel):
     computed on read from the same setting that mints it."""
     state: str = "active"
     """One of :data:`USER_STATES`."""
+    locked_until: datetime | None = None
+    """When a login lockout lifts; ``None`` unless one holds right now."""
     roles: list[str] = []
 
 
diff --git a/modules/users/users/locales/en.json b/modules/users/users/locales/en.json
index 65c9ee888..ebd91214d 100644
--- a/modules/users/users/locales/en.json
+++ b/modules/users/users/locales/en.json
@@ -27,7 +27,8 @@
     "reset_confirm_title": "Generate reset link for {email}?",
     "reset_confirm_body": "A one-time password-reset URL will be copied to your clipboard. Any previously issued reset link for this user will be invalidated.",
     "reset_action": "Generate",
-    "external_note": "This account signs in through an external identity provider (SSO) and has no password, so there's no reset link to generate."
+    "external_note": "This account signs in through an external identity provider (SSO) and has no password, so there's no reset link to generate.",
+    "unlock_button": "Unlock"
   },
   "add_people": {
     "title": "Add people",
@@ -125,7 +126,9 @@
     "subtitle": "{email} · joined {joined} · last login {lastLogin}",
     "never": "never",
     "unsaved_changes_one": "{count} unsaved change",
-    "unsaved_changes_other": "{count} unsaved changes"
+    "unsaved_changes_other": "{count} unsaved changes",
+    "toast_unlocked": "Account unlocked",
+    "toast_unlock_failed": "Could not unlock the account"
   },
   "empty": {
     "solo_title": "You're the only account",
@@ -251,7 +254,8 @@
     "yes": "yes",
     "no": "no",
     "mark_verified": "Mark verified",
-    "external_value": "external · sso"
+    "external_value": "external · sso",
+    "locked_until": "Locked until"
   },
   "nav": {
     "logout": "Logout",
@@ -391,7 +395,8 @@
     "toast_reset_failed": "Failed to generate reset link",
     "toast_disabled": "User disabled",
     "toast_enabled": "User enabled",
-    "toast_status_failed": "Could not change the account status"
+    "toast_status_failed": "Could not change the account status",
+    "locked_badge": "locked"
   },
   "verify_email": {
     "head_title": "Verify email",
diff --git a/modules/users/users/pages/Users/Edit.tsx b/modules/users/users/pages/Users/Edit.tsx
index 295032188..b82f14bbf 100644
--- a/modules/users/users/pages/Users/Edit.tsx
+++ b/modules/users/users/pages/Users/Edit.tsx
@@ -54,7 +54,12 @@ function Edit() {
   const isSelf = auth?.user?.id === user.id;
 
   const form = useEditUserForm(user);
-  const actions = useUserActions(user.id, user.is_active, user.is_verified);
+  const actions = useUserActions(
+    user.id,
+    user.is_active,
+    user.is_verified,
+    user.locked_until ?? null,
+  );
 
   return (
     <>
@@ -105,10 +110,12 @@ function Edit() {
             disabledAt={user.disabled_at ?? null}
             isActive={actions.isActive}
             isVerified={actions.isVerified}
+            lockedUntil={actions.lockedUntil}
             savingStatus={actions.savingStatus}
             savingVerify={actions.savingVerify}
             onDisable={actions.disable}
             onEnable={actions.enable}
+            onUnlock={actions.unlock}
             onMarkVerified={actions.markVerified}
             onCopyResetLink={actions.copyResetLink}
           />
diff --git a/modules/users/users/pages/Users/components/AccountCard.tsx b/modules/users/users/pages/Users/components/AccountCard.tsx
index 8defca0cf..9e08b8c93 100644
--- a/modules/users/users/pages/Users/components/AccountCard.tsx
+++ b/modules/users/users/pages/Users/components/AccountCard.tsx
@@ -3,7 +3,7 @@ import { ConfirmActionDialog } from '@simple-module-py/ui/components/ConfirmActi
 import { SectionTitle } from '@simple-module-py/ui/components/SectionTitle';
 import { Button } from '@simple-module-py/ui/components/ui/button';
 import { Card, CardContent } from '@simple-module-py/ui/components/ui/card';
-import { formatDayMonthYear } from '@simple-module-py/ui/lib/date-format';
+import { formatDayMonthTime, formatDayMonthYear } from '@simple-module-py/ui/lib/date-format';
 import { Copy, KeyRound, UserX } from 'lucide-react';
 import type React from 'react';
 import { useState } from 'react';
@@ -15,10 +15,13 @@ interface Props {
   disabledAt: string | null;
   isActive: boolean;
   isVerified: boolean;
+  /** When the login lockout lifts; `null` when the account is not locked. */
+  lockedUntil?: string | null;
   savingStatus: boolean;
   savingVerify: boolean;
   onDisable: () => void;
   onEnable: () => void;
+  onUnlock?: () => void;
   onMarkVerified: () => void;
   onCopyResetLink: () => void;
 }
@@ -60,10 +63,12 @@ export function AccountCard({
   disabledAt,
   isActive,
   isVerified,
+  lockedUntil = null,
   savingStatus,
   savingVerify,
   onDisable,
   onEnable,
+  onUnlock,
   onMarkVerified,
   onCopyResetLink,
 }: Props) {
@@ -111,6 +116,24 @@ export function AccountCard({
           <Row label={t(keys.users.metadata_card.disabled_at)}>
             {formatDay(disabledAt, emptyValue)}
           </Row>
+          {lockedUntil && (
+            <Row label={t(keys.users.metadata_card.locked_until)}>
+              <span className="inline-flex items-center gap-2">
+                <span className="text-red-700 dark:text-red-400">
+                  {formatDayMonthTime(lockedUntil)}
+                </span>
+                <Button
+                  size="sm"
+                  variant="outline"
+                  onClick={onUnlock}
+                  disabled={savingStatus}
+                  className="max-lg:min-h-11"
+                >
+                  {t(keys.users.account_status.unlock_button)}
+                </Button>
+              </span>
+            </Row>
+          )}
         </div>
 
         <div className="mt-auto flex flex-wrap gap-2 pt-5">
diff --git a/modules/users/users/pages/Users/components/useUserActions.ts b/modules/users/users/pages/Users/components/useUserActions.ts
index a71b06805..def6ab7a2 100644
--- a/modules/users/users/pages/Users/components/useUserActions.ts
+++ b/modules/users/users/pages/Users/components/useUserActions.ts
@@ -10,10 +10,16 @@ import { toast } from 'sonner';
  * compromised account should not require finding a Save button. Keeping them
  * here leaves the page itself to own only the details/roles form.
  */
-export function useUserActions(userId: string, initialActive: boolean, initialVerified: boolean) {
+export function useUserActions(
+  userId: string,
+  initialActive: boolean,
+  initialVerified: boolean,
+  initialLockedUntil: string | null = null,
+) {
   const { t } = useT();
   const [isActive, setIsActive] = useState(initialActive);
   const [isVerified, setIsVerified] = useState(initialVerified);
+  const [lockedUntil, setLockedUntil] = useState(initialLockedUntil);
   const [savingStatus, setSavingStatus] = useState(false);
   const [savingVerify, setSavingVerify] = useState(false);
 
@@ -48,6 +54,14 @@ export function useUserActions(userId: string, initialActive: boolean, initialVe
       t(keys.users.edit.toast_enable_failed),
     );
 
+  const unlock = () =>
+    patch(
+      `/api/users/admin/${userId}/unlock`,
+      () => setLockedUntil(null),
+      t(keys.users.edit.toast_unlocked),
+      t(keys.users.edit.toast_unlock_failed),
+    );
+
   const markVerified = () => {
     setSavingVerify(true);
     fetch(`/api/users/admin/${userId}/verify`, { method: 'PATCH' })
@@ -80,10 +94,12 @@ export function useUserActions(userId: string, initialActive: boolean, initialVe
   return {
     isActive,
     isVerified,
+    lockedUntil,
     savingStatus,
     savingVerify,
     disable,
     enable,
+    unlock,
     markVerified,
     copyResetLink,
   };
diff --git a/packages/i18n/src/generated-resources.ts b/packages/i18n/src/generated-resources.ts
index a0dfe1631..fc73f4dc9 100644
--- a/packages/i18n/src/generated-resources.ts
+++ b/packages/i18n/src/generated-resources.ts
@@ -1049,6 +1049,7 @@ export default {
     'users.account_status.reset_action': '',
     'users.account_status.reset_confirm_body': '',
     'users.account_status.reset_confirm_title': '',
+    'users.account_status.unlock_button': '',
     'users.add_people.configure_smtp': '',
     'users.add_people.description': '',
     'users.add_people.error_create_failed': '',
@@ -1128,6 +1129,8 @@ export default {
     'users.edit.toast_reset_copied': '',
     'users.edit.toast_reset_failed': '',
     'users.edit.toast_saved': '',
+    'users.edit.toast_unlock_failed': '',
+    'users.edit.toast_unlocked': '',
     'users.edit.toast_verified': '',
     'users.edit.toast_verify_failed': '',
     'users.edit.unsaved_changes': '',
@@ -1237,6 +1240,7 @@ export default {
     'users.metadata_card.disabled_at': '',
     'users.metadata_card.external_value': '',
     'users.metadata_card.local_badge': '',
+    'users.metadata_card.locked_until': '',
     'users.metadata_card.mark_verified': '',
     'users.metadata_card.no': '',
     'users.metadata_card.sign_in': '',
@@ -1343,6 +1347,7 @@ export default {
     'users.user_row.action_enable': '',
     'users.user_row.actions_aria': '',
     'users.user_row.invited_meta': '',
+    'users.user_row.locked_badge': '',
     'users.user_row.open_aria': '',
     'users.user_row.resend': '',
     'users.user_row.resend_aria': '',
diff --git a/packages/i18n/src/keys.generated.ts b/packages/i18n/src/keys.generated.ts
index 34e2beaf3..cd630cd81 100644
--- a/packages/i18n/src/keys.generated.ts
+++ b/packages/i18n/src/keys.generated.ts
@@ -1340,6 +1340,7 @@ export const keys = {
       reset_action: 'users.account_status.reset_action',
       reset_confirm_body: 'users.account_status.reset_confirm_body',
       reset_confirm_title: 'users.account_status.reset_confirm_title',
+      unlock_button: 'users.account_status.unlock_button',
     },
     add_people: {
       configure_smtp: 'users.add_people.configure_smtp',
@@ -1433,6 +1434,8 @@ export const keys = {
       toast_reset_copied: 'users.edit.toast_reset_copied',
       toast_reset_failed: 'users.edit.toast_reset_failed',
       toast_saved: 'users.edit.toast_saved',
+      toast_unlock_failed: 'users.edit.toast_unlock_failed',
+      toast_unlocked: 'users.edit.toast_unlocked',
       toast_verified: 'users.edit.toast_verified',
       toast_verify_failed: 'users.edit.toast_verify_failed',
       unsaved_changes: 'users.edit.unsaved_changes',
@@ -1558,6 +1561,7 @@ export const keys = {
       disabled_at: 'users.metadata_card.disabled_at',
       external_value: 'users.metadata_card.external_value',
       local_badge: 'users.metadata_card.local_badge',
+      locked_until: 'users.metadata_card.locked_until',
       mark_verified: 'users.metadata_card.mark_verified',
       no: 'users.metadata_card.no',
       sign_in: 'users.metadata_card.sign_in',
@@ -1689,6 +1693,7 @@ export const keys = {
       action_enable: 'users.user_row.action_enable',
       actions_aria: 'users.user_row.actions_aria',
       invited_meta: 'users.user_row.invited_meta',
+      locked_badge: 'users.user_row.locked_badge',
       open_aria: 'users.user_row.open_aria',
       resend: 'users.user_row.resend',
       resend_aria: 'users.user_row.resend_aria',

From 21e6b4c8cdac2c564ad7a36f101181aa5018a905 Mon Sep 17 00:00:00 2001
From: Anto Subash <antosubash@live.com>
Date: Mon, 19 Oct 2026 11:30:23 +0200
Subject: [PATCH 08/13] docs(users): document login lockout (#530)

Users module: lockout section, columns, settings, unlock endpoint, token
and logout rows. Request guards: the shared store and peek(). CHANGELOG
[Unreleased] entries for the behaviour changes and the admin unlock.
The plan is aligned with what was built and ruff-formatted.

Claude-Session: https://claude.ai/code/session_01M9neheZZEe3sVpDi2S3zT4
---
 CHANGELOG.md                                  | 21 ++++++++
 docs/framework/request-guards.md              | 19 +++++--
 docs/modules/users.md                         | 33 +++++++++---
 .../plans/2026-10-19-login-lockout.md         | 51 ++++++++++++-------
 4 files changed, 94 insertions(+), 30 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 6e9b553fc..54734e6c1 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -12,6 +12,22 @@ All notable changes to this project are documented in this file. The format is b
 ## [Unreleased]
 
 ### Changed
+- **Behaviour change (#530):** password-login lockout now holds across workers,
+  source IPs and restarts. `users.login_lockout_account_failures` (new, default
+  10) failures for one account within `login_rate_limit_window_seconds`, from
+  any network, lock it for `login_rate_limit_cooldown_seconds`: every password
+  login for it answers 429 with `Retry-After`, the correct password included.
+  `login_rate_limit_failures` (5) failures from one IP for one username throttle
+  that source until the window ends, and unknown usernames are counted against
+  the account threshold so a 429 does not reveal whether an account exists.
+  Counters live on `users_user` (a migration adds `failed_login_count`,
+  `last_failed_login_at` and `locked_until`) and on the host rate-limit store
+  (Redis when `SM_REDIS_URL` is set). The per-worker `LoginRateLimiter` is gone.
+- **Behaviour change (#530):** `POST /api/users/auth/token` now has the same
+  lockout and throttle: 429 while locked; bad credentials are still 401.
+- **Behaviour change (#530):** the stock fastapi-users auth router is no longer
+  mounted, so `/api/users/auth-inner/login` and `/api/users/auth-inner/logout`
+  are gone. Use `/api/users/auth/login` and `/api/users/auth/logout`.
 - **Behaviour change (#543):** with `allow_signup` off, an OAuth sign-in no
   longer creates an account. It answers 403 `OAUTH_SIGNUP_DISABLED` unless the
   identity is already linked or its email matches an existing account, which
@@ -54,6 +70,11 @@ All notable changes to this project are documented in this file. The format is b
   previously served, and anonymous, in production.
 
 ### Added
+- `PATCH /api/users/admin/{id}/unlock` lifts a login lockout early (audited).
+  `UserListItem` carries `locked_until`; the users list shows a "locked" badge
+  and the edit page a "Locked until" row with an Unlock action (#530).
+- `app.state.sm.rate_limit_store` exposes the host's rate-limit store to
+  modules, and `WindowStore.peek()` reads a window without counting (#530).
 - Durable event delivery (#459). `bus.subscribe_durable(EventType, handler,
   name=...)` and `await bus.publish_durable(event, db)` in
   `simple_module_core.events`; handlers are called as
diff --git a/docs/framework/request-guards.md b/docs/framework/request-guards.md
index ed5a23836..726fa05fe 100644
--- a/docs/framework/request-guards.md
+++ b/docs/framework/request-guards.md
@@ -123,6 +123,17 @@ def register_public_routes(self, registry) -> None:
   recovery is automatic. The script also re-arms a counter that lost its TTL, so
   no key can block an IP permanently. The limiter never takes requests down.
 
+### Sharing the store
+
+`create_app` builds the store once and exposes it as `app.state.sm.rate_limit_store`
+(a `WindowStore`), so a module that throttles its own events counts in the same
+place, across workers, without opening a second Redis client. Besides `hit`,
+which counts, a store has `peek(key, spec)`, which reports the current window
+without counting: `allowed` answers "would one more hit be within budget", so a
+caller can refuse before doing any work and count only what failed. The users
+login lockout (`users/auth_local/lockout.py`) uses it that way. Keys are
+namespaced by the caller (`login:…`); Redis keys get the `sm:rl:` prefix.
+
 ### Response shape
 
 `429` with a `Retry-After` header (seconds until the window resets). API callers
@@ -130,10 +141,10 @@ get `{"detail": "...", "retry_after": N}`; browsers get the Inertia error page.
 
 ### Not covered
 
-`users/auth_local/rate_limit.py` (`LoginRateLimiter`, `ThroughputLimiter`) stays
-as it is: they are synchronous, per-key lockout and per-endpoint budget
-primitives used from FastAPI dependencies, a different shape from this
-middleware's async per-IP window.
+`users/auth_local/rate_limit.py` (`ThroughputLimiter`) stays as it is: a
+synchronous per-endpoint budget used from FastAPI dependencies, a different
+shape from this middleware's async per-IP window. Password-login lockout uses
+the shared store instead (see [Sharing the store](#sharing-the-store)).
 
 ## Where it lives
 
diff --git a/docs/modules/users.md b/docs/modules/users.md
index cef566d1b..5666d66ee 100644
--- a/docs/modules/users.md
+++ b/docs/modules/users.md
@@ -19,14 +19,15 @@ The module is built on [`fastapi-users`](https://fastapi-users.github.io/) for p
 - A signed session cookie (`sm_auth` by default) — the auth module's `AuthMiddleware` calls `UsersAuthProvider.resolve_user`, which reads it on every request and populates `request.state.user`. Bearer tokens (`Authorization: Bearer <token>`) resolve against `users_access_token`.
 - OAuth / OIDC sign-in (Google, GitHub, Microsoft/Entra ID, and any generic OIDC provider) — see [OAuth providers](#oauth-providers).
 - An invite flow — admins generate an invite link; the recipient sets their password via `POST /api/users/auth/accept-invite`.
-- `LoginRateLimiter` — N failures within a window triggers a cooldown per `email::ip` key.
+- Login lockout — see [Login lockout](#login-lockout). Shared across workers, source IPs and restarts.
 - `ThroughputLimiter` — per-IP rate limit across register / forgot-password / accept-invite / verify-token endpoints.
 
 ### Auth endpoints
 
 | Method + path | Body | Notes |
 |---|---|---|
-| `POST /api/users/auth/login` | `OAuth2PasswordRequestForm` | sets `sm_auth` cookie + `session["user_id"]`; rate-limited per email |
+| `POST /api/users/auth/login` | `OAuth2PasswordRequestForm` | sets `sm_auth` cookie + `session["user_id"]`; `400 LOGIN_BAD_CREDENTIALS`; `429` + `Retry-After` while locked — see [Login lockout](#login-lockout) |
+| `POST /api/users/auth/logout` | — | clears the `sm_auth` cookie and the session |
 | `POST /api/users/auth/register` | `UserCreate` | gated by `users.allow_signup`; rate-limited |
 | `POST /api/users/auth/forgot-password` | `PasswordReset` | rate-limited |
 | `POST /api/users/auth/reset-password` | `{token, password}` | |
@@ -34,7 +35,7 @@ The module is built on [`fastapi-users`](https://fastapi-users.github.io/) for p
 | `POST /api/users/auth/verify` | `VerifyRequest` | |
 | `POST /api/users/auth/accept-invite` | `AcceptInviteRequest` | sets password + signs the user in |
 | `POST /api/users/auth/demo/{role}` | — | one-click sign-in as a shared demo account (`role` ∈ `admin`, `user`); `404` unless that account is configured; rate-limited per role — see [Demo mode](#demo-mode-hosting-a-showcase-instance) |
-| `POST /api/users/auth/token` | `TokenRequest` (email + password) | bearer login for mobile / API clients → `{access_token, refresh_token, token_type, expires_in}`; `401` for external/SSO users |
+| `POST /api/users/auth/token` | `TokenRequest` (email + password) | bearer login for mobile / API clients → `{access_token, refresh_token, token_type, expires_in}`; `401` for bad credentials and external/SSO users; `429` + `Retry-After` while locked — see [Login lockout](#login-lockout) |
 | `POST /api/users/auth/token/refresh` | `RefreshRequest` (refresh_token) | rotates a refresh token into a new pair (old one revoked) |
 | `DELETE /api/users/auth/token` | `RefreshRequest` (refresh_token) | revokes a refresh token (idempotent) |
 | `GET /api/users/auth/{provider}/login` | — | OAuth: redirect to the IdP (`provider` ∈ configured set) |
@@ -58,6 +59,7 @@ The module is built on [`fastapi-users`](https://fastapi-users.github.io/) for p
 | `DELETE /api/users/admin/{user_id}` | → `204` (hard delete; an admin cannot delete their own account → `400`) |
 | `PATCH /api/users/admin/{user_id}/disable` | → `UserListItem` |
 | `PATCH /api/users/admin/{user_id}/enable` | → `UserListItem` |
+| `PATCH /api/users/admin/{user_id}/unlock` | → `UserListItem` — lifts a [login lockout](#login-lockout) and clears the failure count (audited) |
 | `PUT /api/users/admin/{user_id}/roles` | `RoleAssignment` → `UserListItem` |
 | `PATCH /api/users/admin/{user_id}/verify` | → `UserListItem` (mark verified; idempotent) |
 | `POST /api/users/admin/{user_id}/reset-password-link` | → `PasswordResetLink` (`409` for external/SSO users) |
@@ -142,6 +144,9 @@ from users.contracts.events import (
 | `tenant_id` | `str \| None` | indexed; only set when multi-tenant |
 | `disabled_at` | `datetime \| None` | |
 | `last_login_at` | `datetime \| None` | indexed |
+| `failed_login_count` | `int` | failed password logins in the current window; `server_default 0`; not audited |
+| `last_failed_login_at` | `datetime \| None` | when the window's last failure happened; not audited |
+| `locked_until` | `datetime \| None` | set while a [login lockout](#login-lockout) holds; audited |
 | `roles` | relationship → `Role` via `UserRole` | eagerly loaded by `AuthMiddleware` |
 
 `Role` (table `users_role`) — `id`, `name` (unique, indexed), `description`.
@@ -190,9 +195,10 @@ Everything else is DB-backed (initial values are pydantic defaults; edit under U
 | `mailer` | `"console"` (or `"smtp"`) |
 | `base_url` | `"http://localhost:8000"` |
 | `smtp_host` / `smtp_port` / `smtp_username` / `smtp_password` / `smtp_from` / `smtp_tls` | SMTP config when `mailer="smtp"` |
-| `login_rate_limit_failures` | `5` |
-| `login_rate_limit_window_seconds` | `300` |
-| `login_rate_limit_cooldown_seconds` | `900` |
+| `login_rate_limit_failures` | `5` — failures from one IP for one username before that source is throttled for the window |
+| `login_rate_limit_window_seconds` | `300` — the window for both lockout tiers |
+| `login_rate_limit_cooldown_seconds` | `900` — how long an account lock lasts |
+| `login_lockout_account_failures` | `10` (≥ 1) — failures for one account, from anywhere, before it locks |
 | `auth_rate_limit_attempts` | `10` |
 | `auth_rate_limit_window_seconds` | `300` |
 | `bootstrap_email`, `bootstrap_password`, `bootstrap_user_email`, `bootstrap_user_password` | `""` — see [Bootstrap](#bootstrap-the-first-admin) |
@@ -358,6 +364,19 @@ every settings load. Do not run it against a database you care about. Blanking
   (`smpy users create-admin`, or the `SM_USERS_BOOTSTRAP_*` vars), because a
   read-only demo session cannot complete the wizard.
 
+## Login lockout
+
+Both password logins — `POST /api/users/auth/login` and `POST /api/users/auth/token` — go through `users.auth_local.lockout` (GH #530). Two tiers, both counting only **wrong passwords** (an unverified-email `400` does not count):
+
+- **Account lock (database).** Each failure bumps `users_user.failed_login_count` with one atomic `UPDATE … RETURNING`, restarting at 1 when the previous failure is older than `login_rate_limit_window_seconds`. Every worker shares that count. When it reaches `login_lockout_account_failures` (default 10), `locked_until` is set to now + `login_rate_limit_cooldown_seconds` through the ORM, so the audit log records the lock. While it holds, every password login for the account answers `429` — the correct password included. A successful login clears the count.
+- **Source throttle (host rate-limit store).** `login:ip:<ip>:<username>` stops one source after `login_rate_limit_failures` (default 5) until the window ends. A username with **no** account is counted under `login:acct:<username>` against the account threshold, so a `429` does not reveal whether an account exists. The store is the host's `app.state.sm.rate_limit_store` — Redis when `SM_REDIS_URL` is set, per-worker counters otherwise (see [Request guards](../framework/request-guards.md#storage)).
+
+The refusal is always `429 {"detail": "Too many attempts — try again later"}` with a `Retry-After` header. The login page shows its "too many attempts" message for it.
+
+Admins see a **locked** badge on the users list and a "Locked until" row with an **Unlock** button on the edit page, backed by `PATCH /api/users/admin/{user_id}/unlock`. Unlocking is an ORM write and is audited; the failure counters are excluded from audit diffs so failed attempts do not flood the log.
+
+The account default is 10 rather than 5 because anyone who knows an address could otherwise lock its owner out from any network; the per-source throttle still stops a single source after 5. OAuth, Keycloak and invite-link sign-ins involve no password and are not counted. The stock fastapi-users router (`/api/users/auth-inner/*`) is not mounted.
+
 ## Mailer backends
 
 `mailer/` ships two implementations of the `Mailer` protocol:
@@ -447,5 +466,5 @@ Components (under `pages/Users/components/`):
 ## Notes
 
 - `cookie_secure` is automatically flipped to `False` in dev (`SM_ENVIRONMENT=development`) so login works over plain HTTP. Don't override it in non-dev environments.
-- `LoginRateLimiter` keys login attempts by `lowercased-email::client-ip`. Counters live in-process (no Redis), so a multi-worker deployment has independent counters per worker — swap for a Redis-backed store when running more than one worker.
+- `ThroughputLimiter` (register, forgot-password, accept-invite, verify-token, `/me/password`) counts in-process, so with N workers its budget is up to N times the configured one. Password-login lockout does not have that limit — see [Login lockout](#login-lockout).
 - The functional `lower(email)` index makes case-insensitive lookups fast on Postgres; on SQLite the lookup falls back to `LOWER(email) = ?` which still uses the regular index.
diff --git a/docs/superpowers/plans/2026-10-19-login-lockout.md b/docs/superpowers/plans/2026-10-19-login-lockout.md
index 544761964..388da3377 100644
--- a/docs/superpowers/plans/2026-10-19-login-lockout.md
+++ b/docs/superpowers/plans/2026-10-19-login-lockout.md
@@ -160,7 +160,8 @@ class WindowStore(Protocol):
         """
         ...
 
-# InProcessWindowStore
+
+class InProcessWindowStore:
     async def peek(self, key: str, spec: RateSpec) -> WindowResult:
         now = self._clock()
         entry = self._windows.get(key)
@@ -313,17 +314,22 @@ depends_on = None
 
 
 def upgrade() -> None:
-    with op.batch_alter_table("users_user") as batch:
-        batch.add_column(sa.Column("failed_login_count", sa.Integer(), nullable=False, server_default=sa.text("0")))
-        batch.add_column(sa.Column("last_failed_login_at", sa.DateTime(timezone=True), nullable=True))
-        batch.add_column(sa.Column("locked_until", sa.DateTime(timezone=True), nullable=True))
+    op.add_column(
+        "users_user",
+        sa.Column("failed_login_count", sa.Integer(), server_default=sa.text("0"), nullable=False),
+    )
+    op.add_column(
+        "users_user", sa.Column("last_failed_login_at", sa.DateTime(timezone=True), nullable=True)
+    )
+    op.add_column(
+        "users_user", sa.Column("locked_until", sa.DateTime(timezone=True), nullable=True)
+    )
 
 
 def downgrade() -> None:
-    with op.batch_alter_table("users_user") as batch:
-        batch.drop_column("locked_until")
-        batch.drop_column("last_failed_login_at")
-        batch.drop_column("failed_login_count")
+    op.drop_column("users_user", "locked_until")
+    op.drop_column("users_user", "last_failed_login_at")
+    op.drop_column("users_user", "failed_login_count")
 ```
 
 - [ ] **Step 4: Verify** — the test passes; on a scratch SQLite file: `SM_DATABASE_URL=sqlite+aiosqlite:////tmp/claude-1001/lockout/m.db uv run --project host alembic -c host/alembic.ini upgrade heads` then `… check` (only the known `users_access_token.expires_at` drift may remain); `make migrations-roundtrip-pg` with `SM_MIGRATIONS_PG_URL` on a disposable DB if Postgres is reachable.
@@ -343,7 +349,7 @@ def downgrade() -> None:
 - Consumes: `app.state.sm.rate_limit_store` (`hit`/`peek`, Task 1); `User` columns (Task 2).
 - Produces:
   - `LOCKED_DETAIL = "Too many attempts — try again later"`
-  - `LoginAttempt(username, ip, store, settings, now)` (frozen dataclass)
+  - `LoginAttempt(username, ip, store, settings, now)` (frozen dataclass); `LoginAttempt.build(username, ip, store, settings, now)` lower-cases and strips the username
   - `login_attempt(request: Request, username: str) -> LoginAttempt`
   - `async refused_for(session, attempt) -> int | None` — seconds to wait, `None` to proceed
   - `async record_failure(session, attempt) -> None` — commits the session
@@ -371,12 +377,14 @@ async def test_expired_window_restarts_count(users_db, alice) -> None:
     assert alice.failed_login_count == 1
 
 
-async def test_expired_lock_allows_login(users_db, alice) -> None:
-    ...  # lock at T0, refused_for at T0+901s is None
+async def test_expired_lock_allows_login(
+    users_db, alice
+) -> None: ...  # lock at T0, refused_for at T0+901s is None
 
 
-async def test_success_resets_count(users_db, alice) -> None:
-    ...  # two failures, record_success, count 0 and last_failed_login_at None
+async def test_success_resets_count(
+    users_db, alice
+) -> None: ...  # two failures, record_success, count 0 and last_failed_login_at None
 
 
 async def test_ip_throttle_after_tier2_limit(users_db, alice) -> None:
@@ -384,15 +392,20 @@ async def test_ip_throttle_after_tier2_limit(users_db, alice) -> None:
     for _ in range(5):
         await record_failure(users_db, _attempt("alice@example.com", ip="1.1.1.1", store=store))
     assert await refused_for(users_db, _attempt("alice@example.com", ip="1.1.1.1", store=store))
-    assert await refused_for(users_db, _attempt("alice@example.com", ip="2.2.2.2", store=store)) is None
+    assert (
+        await refused_for(users_db, _attempt("alice@example.com", ip="2.2.2.2", store=store))
+        is None
+    )
 
 
-async def test_unknown_username_counts_against_account_threshold(users_db) -> None:
-    ...  # 10 failures for ghost@example.com from 10 IPs → refused_for is not None
+async def test_unknown_username_counts_against_account_threshold(
+    users_db,
+) -> None: ...  # 10 failures for ghost@example.com from 10 IPs → refused_for is not None
 
 
-async def test_username_variants_share_one_counter(users_db, alice) -> None:
-    ...  # failures as " Alice@Example.COM " and "alice@example.com" add up on one row
+async def test_username_variants_share_one_counter(
+    users_db, alice
+) -> None: ...  # failures as " Alice@Example.COM " and "alice@example.com" add up on one row
 ```
 
 - [ ] **Step 2: Run** — Expected: FAIL (`ModuleNotFoundError: users.auth_local.lockout`).

From 1023e4995d4c02509f8b1755d2e48340820b9fd2 Mon Sep 17 00:00:00 2001
From: Anto Subash <antosubash@live.com>
Date: Mon, 19 Oct 2026 11:48:39 +0200
Subject: [PATCH 09/13] fix(users): close lockout enumeration and burst races
 (#530)

Enumeration: an unknown username now goes through the account rules on
the store - a sliding counter matching the row's restart rule and a
separate lock key held for the cooldown - so it trips on the same
attempt, with the same status, detail and Retry-After, for as long as a
real account. Before, it used a fixed window and unlocked after the
window (300s) instead of the cooldown (900s).

Races: attempts now take a slot before the password is checked (a
conditional atomic UPDATE on the row, a hit on the store) and a correct
password gives it back, so a parallel burst gets at most the threshold
of password checks. The failure that takes the last slot locks and is
answered 429. A success clears the count but never locked_until, and
the lock write only touches columns no counting UPDATE can reach while
the row has no free slot. Unverified-email 400s give their slot back.

WindowStore gains reset() and hit(..., sliding=True) for this.

Claude-Session: https://claude.ai/code/session_01M9neheZZEe3sVpDi2S3zT4
---
 CHANGELOG.md                                  |  14 +-
 docs/framework/request-guards.md              |   7 +-
 docs/modules/users.md                         |   9 +-
 .../core/simple_module_core/rate_limit.py     |  20 +-
 .../simple_module_hosting/_rate_limit.py      |  17 +-
 .../tests/test_rate_limit_store_shared.py     |  58 +++++
 .../users/tests/test_users_admin_unlock.py    |   2 +-
 .../tests/test_users_lockout_enumeration.py   | 133 ++++++++++
 .../users/tests/test_users_lockout_service.py | 157 ++++++++----
 .../users/tests/test_users_login_lockout.py   |   4 +-
 modules/users/users/auth_local/api.py         |  14 +-
 modules/users/users/auth_local/lockout.py     | 234 ++++++++++++------
 modules/users/users/auth_local/token_api.py   |  22 +-
 13 files changed, 534 insertions(+), 157 deletions(-)
 create mode 100644 modules/users/tests/test_users_lockout_enumeration.py

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 54734e6c1..6609db6ad 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -16,10 +16,13 @@ All notable changes to this project are documented in this file. The format is b
   source IPs and restarts. `users.login_lockout_account_failures` (new, default
   10) failures for one account within `login_rate_limit_window_seconds`, from
   any network, lock it for `login_rate_limit_cooldown_seconds`: every password
-  login for it answers 429 with `Retry-After`, the correct password included.
-  `login_rate_limit_failures` (5) failures from one IP for one username throttle
-  that source until the window ends, and unknown usernames are counted against
-  the account threshold so a 429 does not reveal whether an account exists.
+  login for it answers 429 with `Retry-After`, the correct password included;
+  the failure that trips the lock is itself answered 429. Attempts are counted
+  before the password is checked (a correct password gives the slot back), so
+  a parallel burst gets no more tries than the threshold.
+  `login_rate_limit_failures` (5) attempts from one IP for one username per
+  window are admitted. Unknown usernames go through the same rules on the rate
+  limit store, so a 429 does not reveal whether an account exists.
   Counters live on `users_user` (a migration adds `failed_login_count`,
   `last_failed_login_at` and `locked_until`) and on the host rate-limit store
   (Redis when `SM_REDIS_URL` is set). The per-worker `LoginRateLimiter` is gone.
@@ -74,7 +77,8 @@ All notable changes to this project are documented in this file. The format is b
   `UserListItem` carries `locked_until`; the users list shows a "locked" badge
   and the edit page a "Locked until" row with an Unlock action (#530).
 - `app.state.sm.rate_limit_store` exposes the host's rate-limit store to
-  modules, and `WindowStore.peek()` reads a window without counting (#530).
+  modules. `WindowStore` gains `peek()` (read without counting), `reset()` and
+  `hit(..., sliding=True)` (#530).
 - Durable event delivery (#459). `bus.subscribe_durable(EventType, handler,
   name=...)` and `await bus.publish_durable(event, db)` in
   `simple_module_core.events`; handlers are called as
diff --git a/docs/framework/request-guards.md b/docs/framework/request-guards.md
index 726fa05fe..4307e6dbe 100644
--- a/docs/framework/request-guards.md
+++ b/docs/framework/request-guards.md
@@ -129,9 +129,10 @@ def register_public_routes(self, registry) -> None:
 (a `WindowStore`), so a module that throttles its own events counts in the same
 place, across workers, without opening a second Redis client. Besides `hit`,
 which counts, a store has `peek(key, spec)`, which reports the current window
-without counting: `allowed` answers "would one more hit be within budget", so a
-caller can refuse before doing any work and count only what failed. The users
-login lockout (`users/auth_local/lockout.py`) uses it that way. Keys are
+without counting (`allowed` answers "would one more hit be within budget"),
+`reset(key)`, which forgets a window, and `hit(..., sliding=True)`, which
+restarts the window on every hit. The users login lockout
+(`users/auth_local/lockout.py`) uses all three. Keys are
 namespaced by the caller (`login:…`); Redis keys get the `sm:rl:` prefix.
 
 ### Response shape
diff --git a/docs/modules/users.md b/docs/modules/users.md
index 5666d66ee..190dda0f0 100644
--- a/docs/modules/users.md
+++ b/docs/modules/users.md
@@ -366,10 +366,13 @@ every settings load. Do not run it against a database you care about. Blanking
 
 ## Login lockout
 
-Both password logins — `POST /api/users/auth/login` and `POST /api/users/auth/token` — go through `users.auth_local.lockout` (GH #530). Two tiers, both counting only **wrong passwords** (an unverified-email `400` does not count):
+Both password logins — `POST /api/users/auth/login` and `POST /api/users/auth/token` — go through `users.auth_local.lockout` (GH #530). Each attempt **takes a slot before its password is checked** and a correct password gives it back, so checking for a free slot and taking it are one step: a parallel burst cannot get more password tries than the threshold. An unverified-email `400` gives its slot back too — it is not a failure.
 
-- **Account lock (database).** Each failure bumps `users_user.failed_login_count` with one atomic `UPDATE … RETURNING`, restarting at 1 when the previous failure is older than `login_rate_limit_window_seconds`. Every worker shares that count. When it reaches `login_lockout_account_failures` (default 10), `locked_until` is set to now + `login_rate_limit_cooldown_seconds` through the ORM, so the audit log records the lock. While it holds, every password login for the account answers `429` — the correct password included. A successful login clears the count.
-- **Source throttle (host rate-limit store).** `login:ip:<ip>:<username>` stops one source after `login_rate_limit_failures` (default 5) until the window ends. A username with **no** account is counted under `login:acct:<username>` against the account threshold, so a `429` does not reveal whether an account exists. The store is the host's `app.state.sm.rate_limit_store` — Redis when `SM_REDIS_URL` is set, per-worker counters otherwise (see [Request guards](../framework/request-guards.md#storage)).
+- **Account lock (database).** A conditional, atomic `UPDATE … RETURNING` on `users_user.failed_login_count` takes the slot. The count restarts at 1 when the previous attempt is older than `login_rate_limit_window_seconds`. Every worker shares that count. The attempt that takes the last of `login_lockout_account_failures` (default 10) slots and fails sets `locked_until` to now + `login_rate_limit_cooldown_seconds` through the ORM, so the audit log records the lock, and is itself answered `429`. While it holds, every password login for the account answers `429` — the correct password included. A success clears the count but never `locked_until`.
+- **Source throttle (host rate-limit store).** `login:ip:<ip>:<username>` admits `login_rate_limit_failures` (default 5) attempts per window; a correct password clears it.
+- **Unknown usernames.** A username with **no** account goes through the same account rules on the store — `login:acct:<username>` on a sliding window that matches the row's restart rule, `login:acct-lock:<username>` for the cooldown — so it trips on the same attempt, answers with the same status, detail and `Retry-After`, and stays locked for as long. The unknown path still spends a password hash, as fastapi-users already does.
+
+The store is the host's `app.state.sm.rate_limit_store` — Redis when `SM_REDIS_URL` is set, per-worker counters otherwise (see [Request guards](../framework/request-guards.md#storage)). Without Redis and with more than one worker, an unknown username's counters are per worker (and do not survive a restart) while an account's are not, so that deployment shape can still tell the two apart; run Redis with several workers.
 
 The refusal is always `429 {"detail": "Too many attempts — try again later"}` with a `Retry-After` header. The login page shows its "too many attempts" message for it.
 
diff --git a/framework/core/simple_module_core/rate_limit.py b/framework/core/simple_module_core/rate_limit.py
index b5f7c4f97..88f01f5fd 100644
--- a/framework/core/simple_module_core/rate_limit.py
+++ b/framework/core/simple_module_core/rate_limit.py
@@ -90,8 +90,13 @@ class WindowResult:
 
 
 class WindowStore(Protocol):
-    async def hit(self, key: str, spec: RateSpec) -> WindowResult:
-        """Count one request against *key* and report whether it is within budget."""
+    async def hit(self, key: str, spec: RateSpec, *, sliding: bool = False) -> WindowResult:
+        """Count one request against *key* and report whether it is within budget.
+
+        ``sliding`` restarts the window on every hit, so the count only resets
+        after a full ``spec.period`` with no hits — the shape of the users
+        account-lockout counter, which this must match hit for hit.
+        """
         ...
 
     async def peek(self, key: str, spec: RateSpec) -> WindowResult:
@@ -103,6 +108,10 @@ async def peek(self, key: str, spec: RateSpec) -> WindowResult:
         """
         ...
 
+    async def reset(self, key: str) -> None:
+        """Forget *key*'s window, as if it had never been hit."""
+        ...
+
 
 class InProcessWindowStore:
     """Per-process fixed-window counters. Not shared between workers."""
@@ -113,7 +122,7 @@ def __init__(self, *, clock: Callable[[], float] = time.time) -> None:
         self._clock = clock
         self._windows: dict[str, tuple[int, int]] = {}  # key -> (window_end_ms, count)
 
-    async def hit(self, key: str, spec: RateSpec) -> WindowResult:
+    async def hit(self, key: str, spec: RateSpec, *, sliding: bool = False) -> WindowResult:
         now = self._clock()
         entry = self._windows.get(key)
         if entry is None or entry[0] <= now * 1000:
@@ -121,6 +130,8 @@ async def hit(self, key: str, spec: RateSpec) -> WindowResult:
                 self._sweep(now)
             entry = (int(now * 1000) + spec.period * 1000, 0)
         end_ms, count = entry
+        if sliding:
+            end_ms = int(now * 1000) + spec.period * 1000
         count += 1
         self._windows[key] = (end_ms, count)
         retry = max(1, math.ceil(end_ms / 1000 - now))
@@ -135,6 +146,9 @@ async def peek(self, key: str, spec: RateSpec) -> WindowResult:
         retry = max(1, math.ceil(end_ms / 1000 - now))
         return WindowResult(allowed=count < spec.limit, retry_after=retry, count=count)
 
+    async def reset(self, key: str) -> None:
+        self._windows.pop(key, None)
+
     def _sweep(self, now: float) -> None:
         now_ms = now * 1000
         self._windows = {k: v for k, v in self._windows.items() if v[0] > now_ms}
diff --git a/framework/hosting/simple_module_hosting/_rate_limit.py b/framework/hosting/simple_module_hosting/_rate_limit.py
index 97a8d73c6..05ff61a07 100644
--- a/framework/hosting/simple_module_hosting/_rate_limit.py
+++ b/framework/hosting/simple_module_hosting/_rate_limit.py
@@ -51,13 +51,16 @@
 local c = redis.call('INCR', KEYS[1])
 local t = redis.call('PTTL', KEYS[1])
 -- t < 0 heals a counter that somehow lost its TTL, which would block that IP forever.
-if c == 1 or t < 0 then
+-- ARGV[2] == '1' is a sliding window: every hit restarts it.
+if c == 1 or t < 0 or ARGV[2] == '1' then
   redis.call('PEXPIRE', KEYS[1], ARGV[1])
   t = tonumber(ARGV[1])
 end
 return {c, t}
 """
 
+_RESET_LUA = "redis.call('DEL', KEYS[1]) return 0"
+
 # Read-only twin of ``_LUA``: a missing key is an empty window.
 _PEEK_LUA = """
 local c = redis.call('GET', KEYS[1])
@@ -107,10 +110,11 @@ async def _eval(self, script: str, key: str, *args: Any) -> Any:
                 )
             return None
 
-    async def hit(self, key: str, spec: RateSpec) -> WindowResult:
-        reply = await self._eval(_LUA, key, spec.period * 1000)
+    async def hit(self, key: str, spec: RateSpec, *, sliding: bool = False) -> WindowResult:
+        args = (spec.period * 1000, "1") if sliding else (spec.period * 1000,)
+        reply = await self._eval(_LUA, key, *args)
         if reply is None:
-            return await self._fallback.hit(key, spec)
+            return await self._fallback.hit(key, spec, sliding=sliding)
         count, pttl = int(reply[0]), int(reply[1])
         retry = max(1, -(-pttl // 1000)) if pttl > 0 else spec.period
         return WindowResult(allowed=count <= spec.limit, retry_after=retry, count=count)
@@ -123,6 +127,11 @@ async def peek(self, key: str, spec: RateSpec) -> WindowResult:
         retry = max(1, -(-pttl // 1000)) if pttl > 0 else 0
         return WindowResult(allowed=count < spec.limit, retry_after=retry, count=count)
 
+    async def reset(self, key: str) -> None:
+        # The fallback too: hits taken during an outage live there.
+        await self._fallback.reset(key)
+        await self._eval(_RESET_LUA, key)
+
 
 def build_store(redis_url: str | None) -> WindowStore:
     """Redis when configured and importable, else per-process counters."""
diff --git a/framework/hosting/tests/test_rate_limit_store_shared.py b/framework/hosting/tests/test_rate_limit_store_shared.py
index 07d510c06..36c3848c1 100644
--- a/framework/hosting/tests/test_rate_limit_store_shared.py
+++ b/framework/hosting/tests/test_rate_limit_store_shared.py
@@ -88,3 +88,61 @@ def test_services_default_store() -> None:
 async def test_create_app_shares_one_store(app) -> None:
     [guard] = [m for m in app.user_middleware if m.cls is RateLimitMiddleware]
     assert guard.kwargs["store"] is app.state.sm.rate_limit_store
+
+
+async def test_sliding_hit_restarts_the_window() -> None:
+    clock = _Clock()
+    store = InProcessWindowStore(clock=clock)
+    spec = RateSpec(10, 60)
+    await store.hit("k", spec, sliding=True)
+    clock.now += 50
+    await store.hit("k", spec, sliding=True)  # pushes the end to now + 60
+    clock.now += 50  # 100s after the first hit, 50s after the last
+    assert (await store.hit("k", spec, sliding=True)).count == 3
+    clock.now += 61
+    assert (await store.hit("k", spec, sliding=True)).count == 1
+
+
+async def test_fixed_hit_does_not_slide() -> None:
+    clock = _Clock()
+    store = InProcessWindowStore(clock=clock)
+    spec = RateSpec(10, 60)
+    await store.hit("k", spec)
+    clock.now += 50
+    await store.hit("k", spec)
+    clock.now += 50
+    assert (await store.hit("k", spec)).count == 1
+
+
+async def test_reset_forgets_the_window() -> None:
+    store = InProcessWindowStore(clock=_Clock())
+    spec = RateSpec(1, 60)
+    await store.hit("k", spec)
+    await store.reset("k")
+    assert (await store.peek("k", spec)).count == 0
+
+
+async def test_redis_sliding_flag_and_reset() -> None:
+    calls: list[tuple] = []
+
+    class _Recording(_FakeRedis):
+        async def eval(self, script: str, numkeys: int, key: str, *args):
+            calls.append((script, args))
+            if "DEL" in script:
+                self.counts.pop(key, None)
+                return 0
+            return await super().eval(script, numkeys, key, *args)
+
+    store = RedisWindowStore(_Recording())
+    await store.hit("k", RateSpec(5, 60), sliding=True)
+    assert calls[-1][1] == (60_000, "1")
+    await store.hit("k", RateSpec(5, 60))
+    assert calls[-1][1] == (60_000,)
+    await store.reset("k")
+    assert (await store.peek("k", RateSpec(5, 60))).count == 0
+
+
+def test_script_slides_on_flag() -> None:
+    from simple_module_hosting._rate_limit import _LUA
+
+    assert "ARGV[2] == '1'" in _LUA
diff --git a/modules/users/tests/test_users_admin_unlock.py b/modules/users/tests/test_users_admin_unlock.py
index 3878ca4b5..2fea74ea8 100644
--- a/modules/users/tests/test_users_admin_unlock.py
+++ b/modules/users/tests/test_users_admin_unlock.py
@@ -23,7 +23,7 @@ async def _lock_by_failing(users_app) -> None:
         transport = httpx.ASGITransport(app=users_app, client=(f"10.0.0.{i}", 1))
         async with httpx.AsyncClient(transport=transport, base_url="http://testserver") as c:
             r = await c.post("/api/users/auth/login", data={"username": ALICE, "password": "no"})
-            assert r.status_code == 400
+            assert r.status_code == (429 if i == 9 else 400)  # the 10th trips the lock
 
 
 async def _row(users_app) -> User:
diff --git a/modules/users/tests/test_users_lockout_enumeration.py b/modules/users/tests/test_users_lockout_enumeration.py
new file mode 100644
index 000000000..82e361181
--- /dev/null
+++ b/modules/users/tests/test_users_lockout_enumeration.py
@@ -0,0 +1,133 @@
+"""A locked unknown username is indistinguishable from a locked account (GH #530)."""
+
+from __future__ import annotations
+
+import asyncio
+import dataclasses
+from datetime import UTC, datetime, timedelta
+
+import httpx
+import pytest
+from _users_app_builders import _build_users_app, _make_standard_user
+from simple_module_core.rate_limit import InProcessWindowStore
+from sqlalchemy import select
+from users.auth_local import lockout
+from users.manager import UserManager
+from users.models import User
+
+ALICE = "alice@example.com"
+GHOST = "ghost@example.com"
+T0 = datetime(2026, 10, 19, 12, 0, tzinfo=UTC)
+
+
+class _Clock:
+    """One clock for the DB tier (``_utcnow``) and the store tier."""
+
+    def __init__(self) -> None:
+        self.offset = 0.0
+
+    def now(self) -> datetime:
+        return T0 + timedelta(seconds=self.offset)
+
+    def __call__(self) -> float:
+        return self.now().timestamp()
+
+
+@pytest.fixture
+def clock(users_app, monkeypatch) -> _Clock:
+    clock = _Clock()
+    monkeypatch.setattr(lockout, "_utcnow", clock.now)
+    store = InProcessWindowStore(clock=clock)
+    users_app.state.sm = dataclasses.replace(users_app.state.sm, rate_limit_store=store)
+    return clock
+
+
+async def _login(app, ip: str, username: str, password: str = "wrong") -> httpx.Response:
+    transport = httpx.ASGITransport(app=app, client=(ip, 1))
+    async with httpx.AsyncClient(transport=transport, base_url="http://testserver") as c:
+        return await c.post(
+            "/api/users/auth/login", data={"username": username, "password": password}
+        )
+
+
+def _shape(r: httpx.Response) -> tuple:
+    return r.status_code, r.json()["detail"], r.headers.get("Retry-After")
+
+
+async def test_same_count_same_answer_same_duration(users_app, clock) -> None:
+    await _make_standard_user(users_app, ALICE)
+    shapes: dict[str, list[tuple]] = {ALICE: [], GHOST: []}
+
+    async def both(ip: str) -> None:
+        for name in (ALICE, GHOST):
+            shapes[name].append(_shape(await _login(users_app, ip, name)))
+
+    # Spaced 250s apart — inside the 300s window of the previous failure, but
+    # beyond a fixed window opened by the first. Both tiers must keep counting.
+    for i in range(10):
+        await both(f"10.0.0.{i}")
+        clock.offset += 250 if i < 9 else 0
+    clock.offset += 899  # one second before either lock lifts
+    await both("10.0.1.1")
+    clock.offset += 2
+    await both("10.0.1.2")
+
+    assert shapes[ALICE] == shapes[GHOST]
+    trace = shapes[ALICE]
+    assert [s[0] for s in trace] == [400] * 9 + [429, 429, 400]
+    assert trace[9][2] == "900"  # the tripping attempt
+    assert trace[10][2] == "1"  # same duration on both
+
+
+async def test_known_and_unknown_take_the_same_password_path(users_app, monkeypatch) -> None:
+    """Timing: an unknown username still pays for a password hash."""
+    from fastapi_users.password import PasswordHelper
+
+    await _make_standard_user(users_app, ALICE)
+    calls: list[str] = []
+    real_hash, real_verify = PasswordHelper.hash, PasswordHelper.verify_and_update
+
+    def hash_(self, password):
+        calls.append("hash")
+        return real_hash(self, password)
+
+    def verify(self, plain, hashed):
+        calls.append("verify")
+        return real_verify(self, plain, hashed)
+
+    monkeypatch.setattr(PasswordHelper, "hash", hash_)
+    monkeypatch.setattr(PasswordHelper, "verify_and_update", verify)
+    await _login(users_app, "1.1.1.1", ALICE)
+    known, calls[:] = list(calls), []
+    await _login(users_app, "1.1.1.1", GHOST)
+    assert known and calls  # each spends one hashing operation
+    assert len(known) == len(calls) == 1
+
+
+async def test_parallel_burst_gets_at_most_threshold_password_checks(monkeypatch, tmp_path) -> None:
+    url = f"sqlite+aiosqlite:///{tmp_path / 'burst.db'}"
+    overrides = {"login_lockout_account_failures": ("4", "int")}
+    app, ctx = await _build_users_app(
+        monkeypatch, allow_signup=False, database_url=url, overrides=overrides
+    )
+    try:
+        await _make_standard_user(app, ALICE)
+        checks: list[str] = []
+        real = UserManager.authenticate
+
+        async def counting(self, credentials):
+            checks.append(credentials.username)
+            return await real(self, credentials)
+
+        monkeypatch.setattr(UserManager, "authenticate", counting)
+        responses = await asyncio.gather(*(_login(app, f"10.0.0.{i}", ALICE) for i in range(16)))
+        codes = sorted(r.status_code for r in responses)
+        assert len(checks) <= 4
+        assert codes.count(400) == 3 and codes.count(429) == 13
+        async with app.state.sm.db.session_factory() as session:
+            row = (await session.execute(select(User).where(User.email == ALICE))).scalar_one()
+        assert row.locked_until is not None
+        # The burst neither reset nor overshot the count; the lock reset it to 0.
+        assert row.failed_login_count == 0
+    finally:
+        await ctx.__aexit__(None, None, None)
diff --git a/modules/users/tests/test_users_lockout_service.py b/modules/users/tests/test_users_lockout_service.py
index 524dbe0c2..579336712 100644
--- a/modules/users/tests/test_users_lockout_service.py
+++ b/modules/users/tests/test_users_lockout_service.py
@@ -6,27 +6,30 @@
 
 import pytest
 from _users_app_builders import _make_standard_user
+from fastapi import HTTPException
 from simple_module_core.rate_limit import InProcessWindowStore
 from sqlalchemy import select
 from users.auth_local.lockout import (
+    Admission,
     LoginAttempt,
+    admit,
     record_failure,
     record_success,
-    refused_for,
 )
 from users.models import User
 from users.settings import UsersSettings
 
 T0 = datetime(2026, 10, 19, 12, 0, tzinfo=UTC)
+ALICE = "alice@example.com"
 
 
 @pytest.fixture
 async def alice(users_app):
-    return await _make_standard_user(users_app, "alice@example.com")
+    return await _make_standard_user(users_app, ALICE)
 
 
 def _attempt(
-    username: str,
+    username: str = ALICE,
     *,
     now: datetime = T0,
     ip: str = "1.1.1.1",
@@ -37,33 +40,41 @@ def _attempt(
     return LoginAttempt.build(username, ip, store or InProcessWindowStore(), settings, now)
 
 
+async def _fail(session, attempt: LoginAttempt) -> int:
+    """One wrong password: admit, then settle. Returns the status it would answer."""
+    try:
+        admission = await admit(session, attempt)
+    except HTTPException as exc:
+        return exc.status_code
+    locked = await record_failure(session, attempt, admission)
+    return locked.status_code if locked else 400
+
+
+async def _admit_or_status(session, attempt: LoginAttempt) -> Admission | int:
+    try:
+        return await admit(session, attempt)
+    except HTTPException as exc:
+        return exc.status_code
+
+
 async def _row(users_db, user) -> User:
     stmt = select(User).where(User.id == user.id).execution_options(populate_existing=True)
     return (await users_db.execute(stmt)).scalar_one()
 
 
-async def test_account_locks_at_threshold(users_db, alice) -> None:
-    for i in range(3):
-        # A different IP every time: the account lock does not care where from.
-        await record_failure(users_db, _attempt("alice@example.com", ip=f"10.0.0.{i}", account=3))
+async def test_account_locks_on_the_attempt_that_reaches_the_threshold(users_db, alice) -> None:
+    # A different IP every time: the account lock does not care where from.
+    codes = [await _fail(users_db, _attempt(ip=f"10.0.0.{i}", account=3)) for i in range(4)]
+    assert codes == [400, 400, 429, 429]
     row = await _row(users_db, alice)
     assert row.locked_until == T0 + timedelta(seconds=900)
     assert row.failed_login_count == 0
-    assert await refused_for(users_db, _attempt("alice@example.com", ip="9.9.9.9")) == 900
-
-
-async def test_below_threshold_is_not_locked(users_db, alice) -> None:
-    for i in range(2):
-        await record_failure(users_db, _attempt("alice@example.com", ip=f"10.0.0.{i}", account=3))
-    row = await _row(users_db, alice)
-    assert (row.failed_login_count, row.locked_until) == (2, None)
-    assert await refused_for(users_db, _attempt("alice@example.com", ip="9.9.9.9")) is None
 
 
 async def test_expired_window_restarts_count(users_db, alice) -> None:
-    await record_failure(users_db, _attempt("alice@example.com", now=T0))
-    await record_failure(users_db, _attempt("alice@example.com", now=T0 + timedelta(seconds=10)))
-    await record_failure(users_db, _attempt("alice@example.com", now=T0 + timedelta(seconds=400)))
+    await _fail(users_db, _attempt(now=T0))
+    await _fail(users_db, _attempt(now=T0 + timedelta(seconds=10)))
+    await _fail(users_db, _attempt(now=T0 + timedelta(seconds=400)))
     row = await _row(users_db, alice)
     assert row.failed_login_count == 1
     assert row.last_failed_login_at == T0 + timedelta(seconds=400)
@@ -71,50 +82,106 @@ async def test_expired_window_restarts_count(users_db, alice) -> None:
 
 async def test_expired_lock_allows_login(users_db, alice) -> None:
     for i in range(3):
-        await record_failure(users_db, _attempt("alice@example.com", ip=f"10.0.0.{i}", account=3))
+        await _fail(users_db, _attempt(ip=f"10.0.0.{i}", account=3))
     later = T0 + timedelta(seconds=901)
-    assert await refused_for(users_db, _attempt("alice@example.com", now=later)) is None
+    assert isinstance(
+        await _admit_or_status(users_db, _attempt(now=later, ip="9.9.9.9")), Admission
+    )
 
 
-async def test_success_resets_count(users_db, alice) -> None:
-    await record_failure(users_db, _attempt("alice@example.com"))
-    await record_failure(users_db, _attempt("alice@example.com"))
-    await record_success(users_db, alice.id)
+async def test_success_resets_count_and_source(users_db, alice) -> None:
+    store = InProcessWindowStore()
+    for _ in range(4):
+        await _fail(users_db, _attempt(store=store))
+    attempt = _attempt(store=store)
+    await record_success(users_db, attempt, await admit(users_db, attempt))
     await users_db.commit()
     row = await _row(users_db, alice)
     assert (row.failed_login_count, row.last_failed_login_at) == (0, None)
+    assert (await store.peek(attempt.ip_key, attempt.ip_spec)).count == 0
 
 
 async def test_failures_do_not_touch_updated_at(users_db, alice) -> None:
     before = (await _row(users_db, alice)).updated_at
-    await record_failure(users_db, _attempt("alice@example.com"))
+    await _fail(users_db, _attempt())
     assert (await _row(users_db, alice)).updated_at == before
 
 
 async def test_ip_throttle_after_tier2_limit(users_db, alice) -> None:
     store = InProcessWindowStore()
-    for _ in range(5):
-        await record_failure(users_db, _attempt("alice@example.com", ip="1.1.1.1", store=store))
-    wait = await refused_for(users_db, _attempt("alice@example.com", ip="1.1.1.1", store=store))
-    assert wait is not None and wait > 0
-    other_ip = _attempt("alice@example.com", ip="2.2.2.2", store=store)
-    assert await refused_for(users_db, other_ip) is None
+    codes = [await _fail(users_db, _attempt(ip="1.1.1.1", store=store)) for _ in range(6)]
+    assert codes == [400] * 5 + [429]
+    assert (await _row(users_db, alice)).failed_login_count == 5  # the 6th never counted
+    assert await _fail(users_db, _attempt(ip="2.2.2.2", store=store)) == 400
 
 
-async def test_unknown_username_counts_against_account_threshold(users_db) -> None:
+async def test_username_variants_share_one_counter(users_db, alice) -> None:
     store = InProcessWindowStore()
-    for i in range(10):
-        await record_failure(users_db, _attempt("ghost@example.com", ip=f"10.0.0.{i}", store=store))
-    fresh_ip = _attempt("ghost@example.com", ip="9.9.9.9", store=store)
-    assert await refused_for(users_db, fresh_ip) is not None
+    await _fail(users_db, _attempt(" Alice@Example.COM ", store=store))
+    await _fail(users_db, _attempt(ALICE, store=store))
+    assert (await _row(users_db, alice)).failed_login_count == 2
+    for _ in range(3):  # ...and the per-IP key is the same one too
+        await _fail(users_db, _attempt("ALICE@example.com", store=store))
+    assert await _fail(users_db, _attempt(ALICE, store=store)) == 429
 
 
-async def test_username_variants_share_one_counter(users_db, alice) -> None:
+# ── Concurrency: a slot is taken before the password is checked ─────────────
+
+
+async def test_burst_gets_at_most_threshold_password_tries(users_db, alice) -> None:
+    """Admissions taken concurrently (none settled yet) stop at the threshold."""
     store = InProcessWindowStore()
-    await record_failure(users_db, _attempt(" Alice@Example.COM ", store=store))
-    await record_failure(users_db, _attempt("alice@example.com", store=store))
-    assert (await _row(users_db, alice)).failed_login_count == 2
-    # ...and the per-IP key is the same one too.
-    for _ in range(3):
-        await record_failure(users_db, _attempt("ALICE@example.com", store=store))
-    assert await refused_for(users_db, _attempt("alice@example.com", store=store)) is not None
+    results = [
+        await _admit_or_status(users_db, _attempt(ip=f"10.0.0.{i}", store=store, account=3))
+        for i in range(8)
+    ]
+    admitted = [r for r in results if isinstance(r, Admission)]
+    assert [a.count for a in admitted] == [1, 2, 3]
+    assert results[3:] == [429] * 5
+    assert (await _row(users_db, alice)).failed_login_count == 3  # refused ones never counted
+
+
+async def test_unknown_burst_matches_known_burst(users_db, alice) -> None:
+    def statuses(results):
+        return [r.count if isinstance(r, Admission) else r for r in results]
+
+    store = InProcessWindowStore()
+    known = [
+        await _admit_or_status(users_db, _attempt(ALICE, ip=f"10.0.0.{i}", store=store, account=3))
+        for i in range(6)
+    ]
+    ghost = [
+        await _admit_or_status(
+            users_db, _attempt("ghost@example.com", ip=f"10.0.0.{i}", store=store, account=3)
+        )
+        for i in range(6)
+    ]
+    assert statuses(known) == statuses(ghost) == [1, 2, 3, 429, 429, 429]
+
+
+async def test_success_mid_burst_does_not_lift_a_lock(users_db, alice) -> None:
+    store = InProcessWindowStore()
+    await _fail(users_db, _attempt(ip="10.0.0.1", store=store, account=3))
+    owner = _attempt(ip="10.0.0.2", store=store, account=3)
+    owner_slot = await admit(users_db, owner)  # admitted before the lock
+    attacker = _attempt(ip="10.0.0.3", store=store, account=3)
+    locked = await record_failure(users_db, attacker, await admit(users_db, attacker))
+    assert locked is not None and locked.status_code == 429
+
+    await record_success(users_db, owner, owner_slot)  # the owner's password lands last
+    await users_db.commit()
+    assert (await _row(users_db, alice)).locked_until == T0 + timedelta(seconds=900)
+    assert await _admit_or_status(users_db, _attempt(ip="9.9.9.9", store=store)) == 429
+
+
+async def test_lock_write_survives_concurrent_counting(users_db, users_app, alice) -> None:
+    """A counting UPDATE from another worker between the lock's read and write cannot undo it."""
+    store = InProcessWindowStore()
+    for i in range(2):
+        await _fail(users_db, _attempt(ip=f"10.0.0.{i}", store=store, account=3))
+    last = _attempt(ip="10.0.0.9", store=store, account=3)
+    slot = await admit(users_db, last)
+    async with users_app.state.sm.db.session_factory() as other:  # another worker
+        assert await _admit_or_status(other, _attempt(ip="10.0.0.8", store=store, account=3)) == 429
+    await record_failure(users_db, last, slot)
+    assert (await _row(users_db, alice)).locked_until is not None
diff --git a/modules/users/tests/test_users_login_lockout.py b/modules/users/tests/test_users_login_lockout.py
index d2e478abe..654b79565 100644
--- a/modules/users/tests/test_users_login_lockout.py
+++ b/modules/users/tests/test_users_login_lockout.py
@@ -62,8 +62,8 @@ async def build():
             (app_b, "1.1.1.1"),
             (app_a, "2.2.2.2"),
         ]
-        for app, ip in plan:
-            assert (await _login(app, ip, ALICE, "wrong")).status_code == 400
+        codes = [(await _login(app, ip, ALICE, "wrong")).status_code for app, ip in plan]
+        assert codes == [400, 400, 400, 400, 429]  # the fifth trips the lock itself
 
         r = await _login(app_b, "9.9.9.9", ALICE, PASSWORD)
         assert r.status_code == 429
diff --git a/modules/users/users/auth_local/api.py b/modules/users/users/auth_local/api.py
index c4f65a3e9..90e687f54 100644
--- a/modules/users/users/auth_local/api.py
+++ b/modules/users/users/auth_local/api.py
@@ -22,11 +22,11 @@
 from sqlalchemy.ext.asyncio import AsyncSession
 
 from users.auth_local.lockout import (
+    admit,
     login_attempt,
     record_failure,
     record_success,
-    refused_for,
-    too_many_attempts,
+    release,
 )
 from users.auth_local.rate_limit import enforce_auth_throughput_limit
 from users.auth_local.self_account import router as self_account_router
@@ -106,8 +106,7 @@ async def login(
 ):
     """Lockout-guarded login wrapper. Sets sm_auth cookie + session user_id."""
     attempt = login_attempt(request, credentials.username)
-    if (wait := await refused_for(db, attempt)) is not None:
-        raise too_many_attempts(wait)
+    admission = await admit(db, attempt)
 
     try:
         user = await user_manager.authenticate(
@@ -120,16 +119,17 @@ async def login(
         user = None
 
     if user is None or not user.is_active:
-        await record_failure(db, attempt)
-        raise HTTPException(status_code=400, detail="LOGIN_BAD_CREDENTIALS")
+        locked = await record_failure(db, attempt, admission)
+        raise locked or HTTPException(status_code=400, detail="LOGIN_BAD_CREDENTIALS")
 
     if not user.is_verified and request.app.state.users.settings.require_verification:
         # Match fastapi-users' own behavior when requires_verification=True.
         # With the setting off nobody is asked to verify (#547) — including
         # accounts that signed up while it was on.
+        await release(db, attempt, admission)
         raise HTTPException(status_code=400, detail="LOGIN_USER_NOT_VERIFIED")
 
-    await record_success(db, user.id)
+    await record_success(db, attempt, admission)
     # Fire the login hook (updates last_login_at)
     await user_manager.on_after_login(user, request, response)
     # Set fastapi-users' cookie via auth_backend.login
diff --git a/modules/users/users/auth_local/lockout.py b/modules/users/users/auth_local/lockout.py
index 505e545b1..bd277769d 100644
--- a/modules/users/users/auth_local/lockout.py
+++ b/modules/users/users/auth_local/lockout.py
@@ -3,27 +3,33 @@
 Both password logins — the session ``/auth/login`` and the bearer
 ``/auth/token`` — go through here (GH #530). Two tiers:
 
-* **Account lock**, on ``users_user``. A failure bumps ``failed_login_count``
-  with one atomic ``UPDATE … RETURNING``, restarting at 1 once the last failure
-  is older than the window, so every worker shares one count. Reaching
-  ``login_lockout_account_failures`` stamps ``locked_until`` through the ORM —
-  that is what puts the lock in the audit log. While it holds, every password
-  login for the account is refused, the right password included.
-* **Source throttle**, on the host's rate-limit store (Redis when configured).
-  ``login:ip:<ip>:<username>`` stops one source after
-  ``login_rate_limit_failures``; ``login:acct:<username>`` counts failures for a
-  username with *no* account against the account threshold, so a 429 says
-  nothing about whether the account exists.
-
-Only failures count. The caller refuses with :func:`refused_for` first, then
-records the outcome.
+* **Account lock**, on ``users_user``. ``failed_login_count`` restarts at 1
+  once the last failure is older than the window, so every worker shares one
+  count. The attempt that reaches ``login_lockout_account_failures`` stamps
+  ``locked_until`` through the ORM — that is what puts the lock in the audit
+  log — and is itself answered with the 429. While the lock holds, every
+  password login for the account is refused, the right password included.
+* **Source throttle**, on the host's rate-limit store (Redis when configured):
+  ``login:ip:<ip>:<username>`` admits ``login_rate_limit_failures`` attempts
+  per window; a success clears it.
+
+A username with *no* account is put through the same account rules on the
+store instead (``login:acct:<username>`` counts on a sliding window, matching
+the row's restart rule, and ``login:acct-lock:<username>`` holds the lock for
+the cooldown), so its responses — status, detail, ``Retry-After``, the attempt
+that trips, how long it lasts — are those of a real account.
+
+**Counted before the password is checked.** :func:`admit` takes a slot in both
+tiers first and refuses when there is none; :func:`record_success` gives it
+back. Checking and counting in one step is what stops a parallel burst from
+getting more password tries than the threshold: of N concurrent attempts,
+exactly one can take the last slot.
 """
 
 from __future__ import annotations
 
 import math
 import uuid
-from collections.abc import Iterator
 from dataclasses import dataclass
 from datetime import UTC, datetime, timedelta
 from typing import TYPE_CHECKING, Any
@@ -70,26 +76,45 @@ def build(
         return cls(username.strip().lower(), ip, store, settings, now)
 
     @property
-    def ip_key(self) -> str:
-        return f"login:ip:{self.ip}:{self.username}"
+    def threshold(self) -> int:
+        return self.settings.login_lockout_account_failures
 
     @property
-    def account_key(self) -> str:
-        return f"login:acct:{self.username}"
+    def cooldown(self) -> int:
+        return self.settings.login_rate_limit_cooldown_seconds
+
+    @property
+    def ip_key(self) -> str:
+        return f"login:ip:{self.ip}:{self.username}"
 
     @property
     def ip_spec(self) -> RateSpec:
         s = self.settings
         return RateSpec(s.login_rate_limit_failures, s.login_rate_limit_window_seconds)
 
+    @property
+    def account_key(self) -> str:
+        return f"login:acct:{self.username}"
+
     @property
     def account_spec(self) -> RateSpec:
-        s = self.settings
-        return RateSpec(s.login_lockout_account_failures, s.login_rate_limit_window_seconds)
+        return RateSpec(self.threshold, self.settings.login_rate_limit_window_seconds)
 
-    def store_checks(self) -> Iterator[tuple[str, RateSpec]]:
-        yield self.ip_key, self.ip_spec
-        yield self.account_key, self.account_spec
+    @property
+    def lock_key(self) -> str:
+        return f"login:acct-lock:{self.username}"
+
+    @property
+    def lock_spec(self) -> RateSpec:
+        return RateSpec(1, self.cooldown)
+
+
+@dataclass(frozen=True, slots=True)
+class Admission:
+    """A slot taken by :func:`admit`: the account rows it counted against and the count."""
+
+    user_ids: tuple[uuid.UUID, ...]
+    count: int
 
 
 def login_attempt(request: Request, username: str) -> LoginAttempt:
@@ -103,77 +128,140 @@ def login_attempt(request: Request, username: str) -> LoginAttempt:
     )
 
 
+def too_many_attempts(retry_after: int) -> HTTPException:
+    """The 429 for a locked account or a throttled source — deliberately identical."""
+    return HTTPException(
+        status_code=status.HTTP_429_TOO_MANY_REQUESTS,
+        detail=LOCKED_DETAIL,
+        headers={"Retry-After": str(max(1, retry_after))},
+    )
+
+
 def _by_username(username: str) -> Any:
     # The same predicate ``UserDatabaseWithRoles.get_by_email`` signs in with.
     return func.lower(User.email) == username
 
 
-async def refused_for(session: AsyncSession, attempt: LoginAttempt) -> int | None:
-    """Seconds the caller must wait, or ``None`` when the attempt may proceed."""
-    waits: list[int] = []
-    stmt = select(User.locked_until).where(_by_username(attempt.username))
-    for locked_until in (await session.execute(stmt)).scalars():
-        if locked_until is not None and locked_until > attempt.now:
-            waits.append(math.ceil((locked_until - attempt.now).total_seconds()))
-    for key, spec in attempt.store_checks():
-        result = await attempt.store.peek(key, spec)
-        if not result.allowed:
-            waits.append(result.retry_after)
-    return max(waits) if waits else None
-
-
-async def record_failure(session: AsyncSession, attempt: LoginAttempt) -> None:
-    """Count a failed password login in both tiers, locking at the threshold.
-
-    Commits *session*: the caller answers by raising, and the request's unit
-    of work rolls back on that path — the count has to be durable before then.
-    The request has only read by this point, so nothing else is committed.
+async def admit(session: AsyncSession, attempt: LoginAttempt) -> Admission:
+    """Take a slot for this attempt in both tiers, or raise the 429.
+
+    Commits *session* when it counts against an account row, so other workers
+    see the slot taken before this one checks the password. The request has
+    only read by this point, so nothing else is committed with it.
     """
-    s = attempt.settings
-    await attempt.store.hit(attempt.ip_key, attempt.ip_spec)
-    window_start = attempt.now - timedelta(seconds=s.login_rate_limit_window_seconds)
+    source = await attempt.store.hit(attempt.ip_key, attempt.ip_spec)
+    if not source.allowed:
+        raise too_many_attempts(source.retry_after)
+    stmt = select(User.locked_until).where(_by_username(attempt.username))
+    rows = (await session.execute(stmt)).scalars().all()
+    if rows:
+        return await _admit_account(session, attempt, rows)
+    return await _admit_unknown(attempt)
+
+
+async def _admit_account(
+    session: AsyncSession, attempt: LoginAttempt, locks: list[datetime | None]
+) -> Admission:
+    live = [lock for lock in locks if lock is not None and lock > attempt.now]
+    if live:
+        raise too_many_attempts(math.ceil((max(live) - attempt.now).total_seconds()))
+    window_start = attempt.now - timedelta(seconds=attempt.settings.login_rate_limit_window_seconds)
     stale = User.last_failed_login_at.is_(None) | (User.last_failed_login_at < window_start)
     stmt = (
         update(User)
         .where(_by_username(attempt.username))
+        # Conditional, so checking for a free slot and taking it are one step:
+        # a row that is locked, or whose last slot is already taken (its lock
+        # is being written), is not counted again.
+        .where(User.locked_until.is_(None) | (User.locked_until <= attempt.now))
+        .where(stale | (User.failed_login_count < attempt.threshold))
         .values(
             failed_login_count=case((stale, 1), else_=User.failed_login_count + 1),
             last_failed_login_at=attempt.now,
-            # A failed sign-in is not an edit of the account.
+            # A sign-in attempt is not an edit of the account.
             updated_at=User.updated_at,
         )
         .returning(User.id, User.failed_login_count)
         .execution_options(synchronize_session=False)
     )
-    rows = (await session.execute(stmt)).all()
-    if not rows:
-        await attempt.store.hit(attempt.account_key, attempt.account_spec)
-    for user_id, count in rows:
-        if count >= s.login_lockout_account_failures:
-            # Through the ORM, not the UPDATE above, so the audit log records it.
+    counted = (await session.execute(stmt)).all()
+    await session.commit()
+    if not counted:
+        raise too_many_attempts(attempt.cooldown)
+    return Admission(tuple(row[0] for row in counted), max(row[1] for row in counted))
+
+
+async def _admit_unknown(attempt: LoginAttempt) -> Admission:
+    # The account rules above, replayed on the store for a username with no row.
+    store = attempt.store
+    lock = await store.peek(attempt.lock_key, attempt.lock_spec)
+    if not lock.allowed:
+        raise too_many_attempts(lock.retry_after)
+    counted = await store.hit(attempt.account_key, attempt.account_spec, sliding=True)
+    if counted.count > attempt.threshold:
+        raise too_many_attempts(attempt.cooldown)  # the last slot's lock is being written
+    lock = await store.peek(attempt.lock_key, attempt.lock_spec)
+    if not lock.allowed:  # locked while this attempt was counting
+        raise too_many_attempts(lock.retry_after)
+    return Admission((), counted.count)
+
+
+async def record_failure(
+    session: AsyncSession, attempt: LoginAttempt, admission: Admission
+) -> HTTPException | None:
+    """Settle a wrong password: the 429 to raise if it was the last slot, else ``None``.
+
+    The failure itself was counted by :func:`admit`. Locking commits *session*:
+    the caller answers by raising, and the request's unit of work rolls back on
+    that path.
+    """
+    if admission.count < attempt.threshold:
+        return None
+    if admission.user_ids:
+        for user_id in admission.user_ids:
+            # Through the ORM, not an UPDATE, so the audit log records the lock.
+            # Only ``locked_until`` and the count are written, so a concurrent
+            # counting UPDATE cannot undo it — and none can run: this row has
+            # no free slot until the lock lifts.
             user = await session.get(User, user_id, populate_existing=True)
             if user is not None:
-                cooldown = timedelta(seconds=s.login_rate_limit_cooldown_seconds)
-                user.locked_until = attempt.now + cooldown
+                user.locked_until = attempt.now + timedelta(seconds=attempt.cooldown)
                 user.failed_login_count = 0
-    await session.commit()
+        await session.commit()
+    else:
+        await attempt.store.hit(attempt.lock_key, attempt.lock_spec)
+        await attempt.store.reset(attempt.account_key)
+    return too_many_attempts(attempt.cooldown)
 
 
-async def record_success(session: AsyncSession, user_id: uuid.UUID) -> None:
-    """Clear the account's failure count. Rides the request's own commit."""
-    await session.execute(
-        update(User)
-        .where(User.id == user_id)
-        .where((User.failed_login_count != 0) | User.last_failed_login_at.is_not(None))
-        .values(failed_login_count=0, last_failed_login_at=None, updated_at=User.updated_at)
-        .execution_options(synchronize_session=False)
-    )
+async def record_success(session: AsyncSession, attempt: LoginAttempt, admission: Admission):
+    """Give the slots back after a correct password. Rides the request's own commit.
 
+    Clears the count, never ``locked_until``: an attempt admitted before a lock
+    landed must not lift it by succeeding afterwards.
+    """
+    await attempt.store.reset(attempt.ip_key)
+    if admission.user_ids:
+        await session.execute(
+            update(User)
+            .where(User.id.in_(admission.user_ids))
+            .values(failed_login_count=0, last_failed_login_at=None, updated_at=User.updated_at)
+            .execution_options(synchronize_session=False)
+        )
 
-def too_many_attempts(retry_after: int) -> HTTPException:
-    """The 429 for a locked account or a throttled source — deliberately identical."""
-    return HTTPException(
-        status_code=status.HTTP_429_TOO_MANY_REQUESTS,
-        detail=LOCKED_DETAIL,
-        headers={"Retry-After": str(max(1, retry_after))},
-    )
+
+async def release(session: AsyncSession, attempt: LoginAttempt, admission: Admission) -> None:
+    """Give back the account slot of an attempt that must not count.
+
+    For a correct password refused for another reason (an unverified email):
+    that answer is not a failure. Commits, since the caller raises next.
+    """
+    await attempt.store.reset(attempt.ip_key)
+    if admission.user_ids:
+        await session.execute(
+            update(User)
+            .where(User.id.in_(admission.user_ids), User.failed_login_count > 0)
+            .values(failed_login_count=User.failed_login_count - 1, updated_at=User.updated_at)
+            .execution_options(synchronize_session=False)
+        )
+        await session.commit()
diff --git a/modules/users/users/auth_local/token_api.py b/modules/users/users/auth_local/token_api.py
index 271f68d69..9207e151f 100644
--- a/modules/users/users/auth_local/token_api.py
+++ b/modules/users/users/auth_local/token_api.py
@@ -17,11 +17,11 @@
 from sqlmodel import SQLModel
 
 from users.auth_local.lockout import (
+    admit,
     login_attempt,
     record_failure,
     record_success,
-    refused_for,
-    too_many_attempts,
+    release,
 )
 from users.models import User
 from users.models.refresh_token import RefreshToken
@@ -66,11 +66,10 @@ async def token_login(
     from fastapi_users.password import PasswordHelper
 
     helper = PasswordHelper()
-    # Same lockout as the session login (GH #530): refused before any work,
-    # every wrong password counted, a success clearing the account's count.
+    # Same lockout as the session login (GH #530): a slot is taken before the
+    # password is checked, and a success gives it back.
     attempt = login_attempt(request, body.email)
-    if (wait := await refused_for(db, attempt)) is not None:
-        raise too_many_attempts(wait)
+    admission = await admit(db, attempt)
 
     stmt = select(User).where(User.email == body.email)
     user = (await db.execute(stmt)).scalar_one_or_none()
@@ -89,13 +88,13 @@ async def token_login(
         # email enumeration (existing user + wrong password takes ~50ms for
         # bcrypt; missing user would be instant without this).
         helper.verify_and_update(body.password, _DUMMY_HASH)
-        await record_failure(db, attempt)
-        raise HTTPException(status_code=401, detail="Invalid credentials")
+        locked = await record_failure(db, attempt, admission)
+        raise locked or HTTPException(status_code=401, detail="Invalid credentials")
 
     verified, updated_hash = helper.verify_and_update(body.password, user.hashed_password)
     if not verified:
-        await record_failure(db, attempt)
-        raise HTTPException(status_code=401, detail="Invalid credentials")
+        locked = await record_failure(db, attempt, admission)
+        raise locked or HTTPException(status_code=401, detail="Invalid credentials")
     if updated_hash is not None:
         # A legacy-scheme hash (e.g. bcrypt) was accepted and re-hashed with the
         # current scheme; persist it, as ``UserManager.authenticate`` does for
@@ -107,8 +106,9 @@ async def token_login(
     if not user.is_verified and settings.require_verification:
         # Same rule as the session login: a self-registered account that never
         # proved its address must not mint bearer tokens either (#547).
+        await release(db, attempt, admission)
         raise HTTPException(status_code=400, detail="LOGIN_USER_NOT_VERIFIED")
-    await record_success(db, user.id)
+    await record_success(db, attempt, admission)
     return await _create_token_pair(db, user.id, settings, user.session_version)
 
 

From e4ea89363d174948c5a863f412102442eb6bc1a4 Mon Sep 17 00:00:00 2001
From: Anto Subash <antosubash@live.com>
Date: Mon, 19 Oct 2026 11:49:43 +0200
Subject: [PATCH 10/13] test(users): 20-request burst against a threshold of 5,
 interleaving inside authenticate (#530)

Claude-Session: https://claude.ai/code/session_01M9neheZZEe3sVpDi2S3zT4
---
 modules/users/tests/test_users_lockout_enumeration.py | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

diff --git a/modules/users/tests/test_users_lockout_enumeration.py b/modules/users/tests/test_users_lockout_enumeration.py
index 82e361181..6d05b854f 100644
--- a/modules/users/tests/test_users_lockout_enumeration.py
+++ b/modules/users/tests/test_users_lockout_enumeration.py
@@ -106,7 +106,7 @@ def verify(self, plain, hashed):
 
 async def test_parallel_burst_gets_at_most_threshold_password_checks(monkeypatch, tmp_path) -> None:
     url = f"sqlite+aiosqlite:///{tmp_path / 'burst.db'}"
-    overrides = {"login_lockout_account_failures": ("4", "int")}
+    overrides = {"login_lockout_account_failures": ("5", "int")}
     app, ctx = await _build_users_app(
         monkeypatch, allow_signup=False, database_url=url, overrides=overrides
     )
@@ -117,13 +117,14 @@ async def test_parallel_burst_gets_at_most_threshold_password_checks(monkeypatch
 
         async def counting(self, credentials):
             checks.append(credentials.username)
+            await asyncio.sleep(0)  # let the other requests interleave mid-check
             return await real(self, credentials)
 
         monkeypatch.setattr(UserManager, "authenticate", counting)
-        responses = await asyncio.gather(*(_login(app, f"10.0.0.{i}", ALICE) for i in range(16)))
+        responses = await asyncio.gather(*(_login(app, f"10.0.0.{i}", ALICE) for i in range(20)))
         codes = sorted(r.status_code for r in responses)
-        assert len(checks) <= 4
-        assert codes.count(400) == 3 and codes.count(429) == 13
+        assert len(checks) <= 5
+        assert codes.count(400) == 4 and codes.count(429) == 16
         async with app.state.sm.db.session_factory() as session:
             row = (await session.execute(select(User).where(User.email == ALICE))).scalar_one()
         assert row.locked_until is not None

From 661758d7e66c645cda79cefc15f273b4e8ecf234 Mon Sep 17 00:00:00 2001
From: Anto Subash <antosubash@live.com>
Date: Mon, 19 Oct 2026 11:55:20 +0200
Subject: [PATCH 11/13] =?UTF-8?q?refactor(optimize):=20duplication=20?=
 =?UTF-8?q?=E2=80=94=20shared=20client=5Fip,=20lockout=20test=20helpers,?=
 =?UTF-8?q?=20window-store=20helpers?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- lockout reuses auth_local.rate_limit.client_ip (renamed from _client_ip)
- _client/_login/user_row/ALICE in _users_app_builders, one alice fixture in conftest
- InProcessWindowStore._live_entry/_retry_s; RedisWindowStore replies via _parse

Claude-Session: https://claude.ai/code/session_01M9neheZZEe3sVpDi2S3zT4
---
 .../core/simple_module_core/rate_limit.py     | 23 ++++++---
 .../simple_module_hosting/_rate_limit.py      | 16 +++++--
 modules/users/tests/_users_app_builders.py    | 30 ++++++++++++
 modules/users/tests/conftest.py               |  7 +++
 modules/users/tests/test_demo_account.py      | 26 +++++-----
 .../users/tests/test_users_admin_unlock.py    | 30 ++----------
 .../tests/test_users_lockout_enumeration.py   | 16 +------
 .../users/tests/test_users_lockout_service.py |  9 +---
 .../users/tests/test_users_login_lockout.py   | 47 ++++++-------------
 modules/users/users/auth_local/lockout.py     |  3 +-
 modules/users/users/auth_local/rate_limit.py  |  4 +-
 11 files changed, 103 insertions(+), 108 deletions(-)

diff --git a/framework/core/simple_module_core/rate_limit.py b/framework/core/simple_module_core/rate_limit.py
index 88f01f5fd..f77aac5a4 100644
--- a/framework/core/simple_module_core/rate_limit.py
+++ b/framework/core/simple_module_core/rate_limit.py
@@ -122,10 +122,21 @@ def __init__(self, *, clock: Callable[[], float] = time.time) -> None:
         self._clock = clock
         self._windows: dict[str, tuple[int, int]] = {}  # key -> (window_end_ms, count)
 
-    async def hit(self, key: str, spec: RateSpec, *, sliding: bool = False) -> WindowResult:
-        now = self._clock()
+    def _live_entry(self, key: str, now: float) -> tuple[int, int] | None:
+        """*key*'s ``(window_end_ms, count)``, or ``None`` if absent or expired."""
         entry = self._windows.get(key)
         if entry is None or entry[0] <= now * 1000:
+            return None
+        return entry
+
+    @staticmethod
+    def _retry_s(end_ms: int, now: float) -> int:
+        return max(1, math.ceil(end_ms / 1000 - now))
+
+    async def hit(self, key: str, spec: RateSpec, *, sliding: bool = False) -> WindowResult:
+        now = self._clock()
+        entry = self._live_entry(key, now)
+        if entry is None:
             if len(self._windows) >= self._MAX_KEYS:
                 self._sweep(now)
             entry = (int(now * 1000) + spec.period * 1000, 0)
@@ -134,16 +145,16 @@ async def hit(self, key: str, spec: RateSpec, *, sliding: bool = False) -> Windo
             end_ms = int(now * 1000) + spec.period * 1000
         count += 1
         self._windows[key] = (end_ms, count)
-        retry = max(1, math.ceil(end_ms / 1000 - now))
+        retry = self._retry_s(end_ms, now)
         return WindowResult(allowed=count <= spec.limit, retry_after=retry, count=count)
 
     async def peek(self, key: str, spec: RateSpec) -> WindowResult:
         now = self._clock()
-        entry = self._windows.get(key)
-        if entry is None or entry[0] <= now * 1000:
+        entry = self._live_entry(key, now)
+        if entry is None:
             return WindowResult(allowed=spec.limit > 0, retry_after=0, count=0)
         end_ms, count = entry
-        retry = max(1, math.ceil(end_ms / 1000 - now))
+        retry = self._retry_s(end_ms, now)
         return WindowResult(allowed=count < spec.limit, retry_after=retry, count=count)
 
     async def reset(self, key: str) -> None:
diff --git a/framework/hosting/simple_module_hosting/_rate_limit.py b/framework/hosting/simple_module_hosting/_rate_limit.py
index 05ff61a07..0d7a6497b 100644
--- a/framework/hosting/simple_module_hosting/_rate_limit.py
+++ b/framework/hosting/simple_module_hosting/_rate_limit.py
@@ -69,6 +69,16 @@
 """
 
 
+def _parse(reply: Any, empty_retry: int) -> tuple[int, int]:
+    """``(count, retry_after)`` from a script's ``{count, pttl}`` reply.
+
+    *empty_retry* is the answer when the key has no TTL left to report.
+    """
+    count, pttl = int(reply[0]), int(reply[1])
+    retry = max(1, -(-pttl // 1000)) if pttl > 0 else empty_retry
+    return count, retry
+
+
 class RedisWindowStore:
     """Fixed-window counters in Redis; shared across workers and processes.
 
@@ -115,16 +125,14 @@ async def hit(self, key: str, spec: RateSpec, *, sliding: bool = False) -> Windo
         reply = await self._eval(_LUA, key, *args)
         if reply is None:
             return await self._fallback.hit(key, spec, sliding=sliding)
-        count, pttl = int(reply[0]), int(reply[1])
-        retry = max(1, -(-pttl // 1000)) if pttl > 0 else spec.period
+        count, retry = _parse(reply, spec.period)
         return WindowResult(allowed=count <= spec.limit, retry_after=retry, count=count)
 
     async def peek(self, key: str, spec: RateSpec) -> WindowResult:
         reply = await self._eval(_PEEK_LUA, key)
         if reply is None:
             return await self._fallback.peek(key, spec)
-        count, pttl = int(reply[0]), int(reply[1])
-        retry = max(1, -(-pttl // 1000)) if pttl > 0 else 0
+        count, retry = _parse(reply, 0)
         return WindowResult(allowed=count < spec.limit, retry_after=retry, count=count)
 
     async def reset(self, key: str) -> None:
diff --git a/modules/users/tests/_users_app_builders.py b/modules/users/tests/_users_app_builders.py
index 06d119f36..3b8132b2a 100644
--- a/modules/users/tests/_users_app_builders.py
+++ b/modules/users/tests/_users_app_builders.py
@@ -7,9 +7,12 @@
 
 from __future__ import annotations
 
+import httpx
 from simple_module_hosting.settings import Settings
 from users.constants import ADMIN_ROLE_ID, USER_ROLE_ID
 
+ALICE = "alice@example.com"
+
 # ---------------------------------------------------------------------------
 
 
@@ -178,3 +181,30 @@ async def _build_users_app(
     if seed_admin:
         await _make_admin_user(application)
     return application, ctx
+
+
+# ---------------------------------------------------------------------------
+# Request and row helpers for the login-lockout tests
+# ---------------------------------------------------------------------------
+
+
+def _client(app, ip: str) -> httpx.AsyncClient:
+    """A client whose requests arrive from *ip*."""
+    transport = httpx.ASGITransport(app=app, client=(ip, 1))
+    return httpx.AsyncClient(transport=transport, base_url="http://testserver")
+
+
+async def _login(app, ip: str, username: str, password: str = "wrong") -> httpx.Response:
+    async with _client(app, ip) as c:
+        return await c.post(
+            "/api/users/auth/login", data={"username": username, "password": password}
+        )
+
+
+async def user_row(app, email: str):
+    """The ``User`` row for *email*, or ``None``, read in a fresh session."""
+    from sqlalchemy import select
+    from users.models import User
+
+    async with app.state.sm.db.session_factory() as session:
+        return (await session.execute(select(User).where(User.email == email))).scalar_one_or_none()
diff --git a/modules/users/tests/conftest.py b/modules/users/tests/conftest.py
index e6f3b702d..74bd60e9d 100644
--- a/modules/users/tests/conftest.py
+++ b/modules/users/tests/conftest.py
@@ -21,6 +21,7 @@
 # top-level modules on pytest's sys.path — same mechanism as the
 # _middleware_support plugin loaded at the bottom of this file.
 from _users_app_builders import (
+    ALICE,
     _build_users_app,
     _make_admin_user,
     _make_standard_user,
@@ -148,6 +149,12 @@ async def user_client(users_app) -> AsyncGenerator[httpx.AsyncClient, None]:
         yield c
 
 
+@pytest.fixture
+async def alice(users_app):
+    """A standard user, ``ALICE``, for the login-lockout tests."""
+    return await _make_standard_user(users_app, ALICE)
+
+
 # ---------------------------------------------------------------------------
 # DB session fixture scoped to users_app
 # ---------------------------------------------------------------------------
diff --git a/modules/users/tests/test_demo_account.py b/modules/users/tests/test_demo_account.py
index 4ab414dfe..2129b10af 100644
--- a/modules/users/tests/test_demo_account.py
+++ b/modules/users/tests/test_demo_account.py
@@ -9,6 +9,7 @@
 from __future__ import annotations
 
 from _demo_support import DEMO_ADMIN_EMAIL, DEMO_USER_EMAIL
+from _users_app_builders import user_row
 from sqlalchemy import select
 from users.constants import ADMIN_ROLE_NAME, USER_ROLE_NAME
 from users.demo import (
@@ -75,11 +76,6 @@ def test_read_only_is_the_default_posture():
 # ── seeding ─────────────────────────────────────────────────────────────────
 
 
-async def _row(app, email: str) -> User | None:
-    async with app.state.sm.db.session_factory() as session:
-        return (await session.execute(select(User).where(User.email == email))).scalar_one_or_none()
-
-
 async def _role_names(app, user_id) -> list[str]:
     async with app.state.sm.db.session_factory() as session:
         return list(
@@ -102,8 +98,8 @@ async def test_ensure_demo_users_seeds_both_accounts(users_app):
 
     assert len(ids) == 2
     assert users_app.state.users.demo_user_ids == ids
-    admin = await _row(users_app, DEMO_ADMIN_EMAIL)
-    user = await _row(users_app, DEMO_USER_EMAIL)
+    admin = await user_row(users_app, DEMO_ADMIN_EMAIL)
+    user = await user_row(users_app, DEMO_USER_EMAIL)
     assert admin is not None and admin.is_superuser
     assert user is not None and not user.is_superuser
     assert all(row.is_active and row.is_verified for row in (admin, user))
@@ -113,8 +109,8 @@ async def test_each_account_gets_its_own_role(users_app):
     users_app.state.users.settings.demo_mode = True
     await ensure_demo_users(users_app)
 
-    admin = await _row(users_app, DEMO_ADMIN_EMAIL)
-    user = await _row(users_app, DEMO_USER_EMAIL)
+    admin = await user_row(users_app, DEMO_ADMIN_EMAIL)
+    user = await user_row(users_app, DEMO_USER_EMAIL)
     assert await _role_names(users_app, admin.id) == [ADMIN_ROLE_NAME]
     assert await _role_names(users_app, user.id) == [USER_ROLE_NAME]
 
@@ -124,8 +120,8 @@ async def test_a_blank_password_still_produces_usable_accounts(users_app):
     users_app.state.users.settings.demo_mode = True
     await ensure_demo_users(users_app)
 
-    assert (await _row(users_app, DEMO_ADMIN_EMAIL)).hashed_password
-    assert (await _row(users_app, DEMO_USER_EMAIL)).hashed_password
+    assert (await user_row(users_app, DEMO_ADMIN_EMAIL)).hashed_password
+    assert (await user_row(users_app, DEMO_USER_EMAIL)).hashed_password
 
 
 async def test_a_generated_password_is_not_re_rolled_on_every_boot(users_app):
@@ -133,23 +129,23 @@ async def test_a_generated_password_is_not_re_rolled_on_every_boot(users_app):
     worker per restart, for no gain."""
     users_app.state.users.settings.demo_mode = True
     await ensure_demo_users(users_app)
-    first = (await _row(users_app, DEMO_ADMIN_EMAIL)).hashed_password
+    first = (await user_row(users_app, DEMO_ADMIN_EMAIL)).hashed_password
 
     await ensure_demo_users(users_app)
 
-    assert (await _row(users_app, DEMO_ADMIN_EMAIL)).hashed_password == first
+    assert (await user_row(users_app, DEMO_ADMIN_EMAIL)).hashed_password == first
 
 
 async def test_a_configured_password_is_reapplied(users_app):
     """Changing a demo password in the admin UI has to take effect."""
     users_app.state.users.settings.demo_mode = True
     await ensure_demo_users(users_app)
-    first = (await _row(users_app, DEMO_USER_EMAIL)).hashed_password
+    first = (await user_row(users_app, DEMO_USER_EMAIL)).hashed_password
 
     users_app.state.users.settings.demo_user_password = "a-published-demo-password"
     await ensure_demo_users(users_app)
 
-    assert (await _row(users_app, DEMO_USER_EMAIL)).hashed_password != first
+    assert (await user_row(users_app, DEMO_USER_EMAIL)).hashed_password != first
 
 
 async def test_demo_off_clears_the_cached_ids(users_app):
diff --git a/modules/users/tests/test_users_admin_unlock.py b/modules/users/tests/test_users_admin_unlock.py
index 2fea74ea8..6c0ba1a3e 100644
--- a/modules/users/tests/test_users_admin_unlock.py
+++ b/modules/users/tests/test_users_admin_unlock.py
@@ -4,31 +4,15 @@
 
 from datetime import UTC, datetime, timedelta
 
-import httpx
-import pytest
-from _users_app_builders import _make_standard_user
+from _users_app_builders import ALICE, _login, user_row
 from sqlalchemy import select
 from users.models import User
 
-ALICE = "alice@example.com"
-
-
-@pytest.fixture
-async def alice(users_app):
-    return await _make_standard_user(users_app, ALICE)
-
 
 async def _lock_by_failing(users_app) -> None:
     for i in range(10):
-        transport = httpx.ASGITransport(app=users_app, client=(f"10.0.0.{i}", 1))
-        async with httpx.AsyncClient(transport=transport, base_url="http://testserver") as c:
-            r = await c.post("/api/users/auth/login", data={"username": ALICE, "password": "no"})
-            assert r.status_code == (429 if i == 9 else 400)  # the 10th trips the lock
-
-
-async def _row(users_app) -> User:
-    async with users_app.state.sm.db.session_factory() as session:
-        return (await session.execute(select(User).where(User.email == ALICE))).scalar_one()
+        r = await _login(users_app, f"10.0.0.{i}", ALICE, "no")
+        assert r.status_code == (429 if i == 9 else 400)  # the 10th trips the lock
 
 
 async def _list_item(admin_client, user_id) -> dict:
@@ -61,7 +45,7 @@ async def test_unlock_clears_lock_and_is_audited(users_app, admin_client, alice)
     assert r.status_code == 200
     assert r.json()["locked_until"] is None
 
-    row = await _row(users_app)
+    row = await user_row(users_app, ALICE)
     assert (row.locked_until, row.failed_login_count, row.last_failed_login_at) == (None, 0, None)
 
     async with users_app.state.sm.db.session_factory() as session:
@@ -76,11 +60,7 @@ async def test_unlock_clears_lock_and_is_audited(users_app, admin_client, alice)
     assert len(entries) == 2
 
     # The account signs in again.
-    transport = httpx.ASGITransport(app=users_app, client=("9.9.9.9", 1))
-    async with httpx.AsyncClient(transport=transport, base_url="http://testserver") as c:
-        login = await c.post(
-            "/api/users/auth/login", data={"username": ALICE, "password": "UserPass1!"}
-        )
+    login = await _login(users_app, "9.9.9.9", ALICE, "UserPass1!")
     assert login.status_code == 204
 
 
diff --git a/modules/users/tests/test_users_lockout_enumeration.py b/modules/users/tests/test_users_lockout_enumeration.py
index 6d05b854f..0cbf00a46 100644
--- a/modules/users/tests/test_users_lockout_enumeration.py
+++ b/modules/users/tests/test_users_lockout_enumeration.py
@@ -8,14 +8,11 @@
 
 import httpx
 import pytest
-from _users_app_builders import _build_users_app, _make_standard_user
+from _users_app_builders import ALICE, _build_users_app, _login, _make_standard_user, user_row
 from simple_module_core.rate_limit import InProcessWindowStore
-from sqlalchemy import select
 from users.auth_local import lockout
 from users.manager import UserManager
-from users.models import User
 
-ALICE = "alice@example.com"
 GHOST = "ghost@example.com"
 T0 = datetime(2026, 10, 19, 12, 0, tzinfo=UTC)
 
@@ -42,14 +39,6 @@ def clock(users_app, monkeypatch) -> _Clock:
     return clock
 
 
-async def _login(app, ip: str, username: str, password: str = "wrong") -> httpx.Response:
-    transport = httpx.ASGITransport(app=app, client=(ip, 1))
-    async with httpx.AsyncClient(transport=transport, base_url="http://testserver") as c:
-        return await c.post(
-            "/api/users/auth/login", data={"username": username, "password": password}
-        )
-
-
 def _shape(r: httpx.Response) -> tuple:
     return r.status_code, r.json()["detail"], r.headers.get("Retry-After")
 
@@ -125,8 +114,7 @@ async def counting(self, credentials):
         codes = sorted(r.status_code for r in responses)
         assert len(checks) <= 5
         assert codes.count(400) == 4 and codes.count(429) == 16
-        async with app.state.sm.db.session_factory() as session:
-            row = (await session.execute(select(User).where(User.email == ALICE))).scalar_one()
+        row = await user_row(app, ALICE)
         assert row.locked_until is not None
         # The burst neither reset nor overshot the count; the lock reset it to 0.
         assert row.failed_login_count == 0
diff --git a/modules/users/tests/test_users_lockout_service.py b/modules/users/tests/test_users_lockout_service.py
index 579336712..430a4f74d 100644
--- a/modules/users/tests/test_users_lockout_service.py
+++ b/modules/users/tests/test_users_lockout_service.py
@@ -4,8 +4,7 @@
 
 from datetime import UTC, datetime, timedelta
 
-import pytest
-from _users_app_builders import _make_standard_user
+from _users_app_builders import ALICE
 from fastapi import HTTPException
 from simple_module_core.rate_limit import InProcessWindowStore
 from sqlalchemy import select
@@ -20,12 +19,6 @@
 from users.settings import UsersSettings
 
 T0 = datetime(2026, 10, 19, 12, 0, tzinfo=UTC)
-ALICE = "alice@example.com"
-
-
-@pytest.fixture
-async def alice(users_app):
-    return await _make_standard_user(users_app, ALICE)
 
 
 def _attempt(
diff --git a/modules/users/tests/test_users_login_lockout.py b/modules/users/tests/test_users_login_lockout.py
index 654b79565..df207ce3a 100644
--- a/modules/users/tests/test_users_login_lockout.py
+++ b/modules/users/tests/test_users_login_lockout.py
@@ -3,43 +3,24 @@
 from __future__ import annotations
 
 import httpx
-import pytest
-from _users_app_builders import _build_users_app, _make_standard_user
-from sqlalchemy import select
+from _users_app_builders import (
+    ALICE,
+    _build_users_app,
+    _client,
+    _login,
+    _make_standard_user,
+    user_row,
+)
 from users.auth_local.lockout import LOCKED_DETAIL
-from users.models import User
 
-ALICE = "alice@example.com"
 PASSWORD = "UserPass1!"
 
 
-def _client(app, ip: str) -> httpx.AsyncClient:
-    transport = httpx.ASGITransport(app=app, client=(ip, 1))
-    return httpx.AsyncClient(transport=transport, base_url="http://testserver")
-
-
-async def _login(app, ip: str, username: str, password: str) -> httpx.Response:
-    async with _client(app, ip) as c:
-        return await c.post(
-            "/api/users/auth/login", data={"username": username, "password": password}
-        )
-
-
 async def _token(app, ip: str, email: str, password: str) -> httpx.Response:
     async with _client(app, ip) as c:
         return await c.post("/api/users/auth/token", json={"email": email, "password": password})
 
 
-async def _alice_row(app) -> User:
-    async with app.state.sm.db.session_factory() as session:
-        return (await session.execute(select(User).where(User.email == ALICE))).scalar_one()
-
-
-@pytest.fixture
-async def alice(users_app):
-    return await _make_standard_user(users_app, ALICE)
-
-
 async def test_acceptance_three_ips_two_apps_survives_restart(monkeypatch, tmp_path) -> None:
     url = f"sqlite+aiosqlite:///{tmp_path / 'lockout.db'}"
     overrides = {"login_lockout_account_failures": ("5", "int")}
@@ -81,36 +62,36 @@ async def build():
 async def test_failures_persist_across_requests(users_app, alice) -> None:
     for _ in range(2):
         assert (await _login(users_app, "1.1.1.1", ALICE, "wrong")).status_code == 400
-    assert (await _alice_row(users_app)).failed_login_count == 2
+    assert (await user_row(users_app, ALICE)).failed_login_count == 2
 
 
 async def test_token_failures_count_too(users_app, alice) -> None:
     r = await _token(users_app, "1.1.1.1", ALICE, "wrong")
     assert (r.status_code, r.json()["detail"]) == (401, "Invalid credentials")
-    assert (await _alice_row(users_app)).failed_login_count == 1
+    assert (await user_row(users_app, ALICE)).failed_login_count == 1
 
 
 async def test_success_resets_count(users_app, alice) -> None:
     for _ in range(2):
         await _login(users_app, "1.1.1.1", ALICE, "wrong")
     assert (await _login(users_app, "1.1.1.1", ALICE, PASSWORD)).status_code == 204
-    row = await _alice_row(users_app)
+    row = await user_row(users_app, ALICE)
     assert (row.failed_login_count, row.last_failed_login_at) == (0, None)
 
 
 async def test_token_success_resets_count(users_app, alice) -> None:
     await _token(users_app, "1.1.1.1", ALICE, "wrong")
     assert (await _token(users_app, "1.1.1.1", ALICE, PASSWORD)).status_code == 200
-    assert (await _alice_row(users_app)).failed_login_count == 0
+    assert (await user_row(users_app, ALICE)).failed_login_count == 0
 
 
 async def test_correct_password_while_locked_does_not_unlock(users_app, alice) -> None:
     for i in range(10):
         await _login(users_app, f"10.0.0.{i}", ALICE, "wrong")
-    locked = (await _alice_row(users_app)).locked_until
+    locked = (await user_row(users_app, ALICE)).locked_until
     assert locked is not None
     assert (await _login(users_app, "9.9.9.9", ALICE, PASSWORD)).status_code == 429
-    assert (await _alice_row(users_app)).locked_until == locked
+    assert (await user_row(users_app, ALICE)).locked_until == locked
 
 
 async def test_unknown_and_locked_look_the_same(users_app, alice) -> None:
diff --git a/modules/users/users/auth_local/lockout.py b/modules/users/users/auth_local/lockout.py
index bd277769d..7708a2f1e 100644
--- a/modules/users/users/auth_local/lockout.py
+++ b/modules/users/users/auth_local/lockout.py
@@ -38,6 +38,7 @@
 from simple_module_core.rate_limit import RateSpec, WindowStore
 from sqlalchemy import case, func, select, update
 
+from users.auth_local.rate_limit import client_ip
 from users.models import User
 
 if TYPE_CHECKING:
@@ -121,7 +122,7 @@ def login_attempt(request: Request, username: str) -> LoginAttempt:
     """The :class:`LoginAttempt` for *username* arriving on *request*."""
     return LoginAttempt.build(
         username,
-        request.client.host if request.client else "unknown",
+        client_ip(request),
         request.app.state.sm.rate_limit_store,
         request.app.state.users.settings,
         _utcnow(),
diff --git a/modules/users/users/auth_local/rate_limit.py b/modules/users/users/auth_local/rate_limit.py
index 9a5d03f8d..011da610e 100644
--- a/modules/users/users/auth_local/rate_limit.py
+++ b/modules/users/users/auth_local/rate_limit.py
@@ -32,7 +32,7 @@ def check_and_record(self, key: str) -> bool:
         return count <= self._max
 
 
-def _client_ip(request: Request) -> str:
+def client_ip(request: Request) -> str:
     return request.client.host if request.client else "unknown"
 
 
@@ -49,7 +49,7 @@ async def enforce_auth_throughput_limit(request: Request) -> None:
     the dependency has to sit below both, not beside one of them.
     """
     limiter: ThroughputLimiter = request.app.state.users.auth_throughput_limiter
-    key = f"{request.url.path}::{_client_ip(request)}"
+    key = f"{request.url.path}::{client_ip(request)}"
     if not limiter.check_and_record(key):
         raise HTTPException(
             status_code=status.HTTP_429_TOO_MANY_REQUESTS,

From 92d32671aaaf329413853819cfe80542e876af3c Mon Sep 17 00:00:00 2001
From: Anto Subash <antosubash@live.com>
Date: Mon, 19 Oct 2026 11:57:27 +0200
Subject: [PATCH 12/13] =?UTF-8?q?refactor(optimize):=20over-engineering=20?=
 =?UTF-8?q?=E2=80=94=20inline=20account=5Fspec,=20drop=20unused=20prop=20d?=
 =?UTF-8?q?efaults?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- lockout._admit_unknown builds its one RateSpec inline; no store alias
- useUserActions initialLockedUntil and AccountCard lockedUntil are required

Claude-Session: https://claude.ai/code/session_01M9neheZZEe3sVpDi2S3zT4
---
 modules/users/users/auth_local/lockout.py            | 12 ++++--------
 .../users/pages/Users/components/AccountCard.tsx     |  4 ++--
 .../users/pages/Users/components/useUserActions.ts   |  2 +-
 3 files changed, 7 insertions(+), 11 deletions(-)

diff --git a/modules/users/users/auth_local/lockout.py b/modules/users/users/auth_local/lockout.py
index 7708a2f1e..43495a901 100644
--- a/modules/users/users/auth_local/lockout.py
+++ b/modules/users/users/auth_local/lockout.py
@@ -97,10 +97,6 @@ def ip_spec(self) -> RateSpec:
     def account_key(self) -> str:
         return f"login:acct:{self.username}"
 
-    @property
-    def account_spec(self) -> RateSpec:
-        return RateSpec(self.threshold, self.settings.login_rate_limit_window_seconds)
-
     @property
     def lock_key(self) -> str:
         return f"login:acct-lock:{self.username}"
@@ -194,14 +190,14 @@ async def _admit_account(
 
 async def _admit_unknown(attempt: LoginAttempt) -> Admission:
     # The account rules above, replayed on the store for a username with no row.
-    store = attempt.store
-    lock = await store.peek(attempt.lock_key, attempt.lock_spec)
+    lock = await attempt.store.peek(attempt.lock_key, attempt.lock_spec)
     if not lock.allowed:
         raise too_many_attempts(lock.retry_after)
-    counted = await store.hit(attempt.account_key, attempt.account_spec, sliding=True)
+    account_spec = RateSpec(attempt.threshold, attempt.settings.login_rate_limit_window_seconds)
+    counted = await attempt.store.hit(attempt.account_key, account_spec, sliding=True)
     if counted.count > attempt.threshold:
         raise too_many_attempts(attempt.cooldown)  # the last slot's lock is being written
-    lock = await store.peek(attempt.lock_key, attempt.lock_spec)
+    lock = await attempt.store.peek(attempt.lock_key, attempt.lock_spec)
     if not lock.allowed:  # locked while this attempt was counting
         raise too_many_attempts(lock.retry_after)
     return Admission((), counted.count)
diff --git a/modules/users/users/pages/Users/components/AccountCard.tsx b/modules/users/users/pages/Users/components/AccountCard.tsx
index 9e08b8c93..d0a0afc3f 100644
--- a/modules/users/users/pages/Users/components/AccountCard.tsx
+++ b/modules/users/users/pages/Users/components/AccountCard.tsx
@@ -16,7 +16,7 @@ interface Props {
   isActive: boolean;
   isVerified: boolean;
   /** When the login lockout lifts; `null` when the account is not locked. */
-  lockedUntil?: string | null;
+  lockedUntil: string | null;
   savingStatus: boolean;
   savingVerify: boolean;
   onDisable: () => void;
@@ -63,7 +63,7 @@ export function AccountCard({
   disabledAt,
   isActive,
   isVerified,
-  lockedUntil = null,
+  lockedUntil,
   savingStatus,
   savingVerify,
   onDisable,
diff --git a/modules/users/users/pages/Users/components/useUserActions.ts b/modules/users/users/pages/Users/components/useUserActions.ts
index def6ab7a2..8c31cbf2d 100644
--- a/modules/users/users/pages/Users/components/useUserActions.ts
+++ b/modules/users/users/pages/Users/components/useUserActions.ts
@@ -14,7 +14,7 @@ export function useUserActions(
   userId: string,
   initialActive: boolean,
   initialVerified: boolean,
-  initialLockedUntil: string | null = null,
+  initialLockedUntil: string | null,
 ) {
   const { t } = useT();
   const [isActive, setIsActive] = useState(initialActive);

From 20b89def5dd7045a4832e4fba3bd0029bed46c83 Mon Sep 17 00:00:00 2001
From: Anto Subash <antosubash@live.com>
Date: Mon, 19 Oct 2026 12:13:27 +0200
Subject: [PATCH 13/13] fix: address code review findings (round 1, pass 1)

- lockout: usernames over 254 chars are hashed in store keys, so a large
  body cannot park a large Redis key (reviewer fix, now tested).
- lockout: when the conditional slot UPDATE misses because the account was
  locked meanwhile, Retry-After reports the remaining lock time, matching
  the unknown-username lock; enumeration parity test checks mid-lock.
- manager: a successful password reset clears locked_until and the failure
  counters through the ORM (audited), so mailbox control unlocks.
- token_api: the bearer login looks the email up case-insensitively, like
  the session login; dummy-hash timing equaliser kept and tested.
- docs/CHANGELOG: lockout trade-offs (targeted lockout, dead requests still
  count, in-process store eviction without Redis); reset unlocks.

Claude-Session: https://claude.ai/code/session_01M9neheZZEe3sVpDi2S3zT4
---
 CHANGELOG.md                                  |  5 ++-
 docs/modules/users.md                         |  9 +++++
 .../users/tests/test_users_admin_unlock.py    | 28 ++++++++++++-
 .../tests/test_users_lockout_enumeration.py   |  9 +++--
 .../users/tests/test_users_lockout_service.py | 22 +++++++++++
 .../users/tests/test_users_login_lockout.py   | 26 +++++++++++++
 modules/users/users/auth_local/lockout.py     | 39 +++++++++++++++----
 modules/users/users/auth_local/token_api.py   |  6 ++-
 modules/users/users/manager.py                | 13 +++++++
 9 files changed, 143 insertions(+), 14 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 6609db6ad..0cc8b5a5b 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -26,8 +26,11 @@ All notable changes to this project are documented in this file. The format is b
   Counters live on `users_user` (a migration adds `failed_login_count`,
   `last_failed_login_at` and `locked_until`) and on the host rate-limit store
   (Redis when `SM_REDIS_URL` is set). The per-worker `LoginRateLimiter` is gone.
+  A successful password reset lifts the lock and clears the failure count
+  (audited, like an admin unlock).
 - **Behaviour change (#530):** `POST /api/users/auth/token` now has the same
-  lockout and throttle: 429 while locked; bad credentials are still 401.
+  lockout and throttle: 429 while locked; bad credentials are still 401. Its
+  email lookup is now case-insensitive, matching the session login.
 - **Behaviour change (#530):** the stock fastapi-users auth router is no longer
   mounted, so `/api/users/auth-inner/login` and `/api/users/auth-inner/logout`
   are gone. Use `/api/users/auth/login` and `/api/users/auth/logout`.
diff --git a/docs/modules/users.md b/docs/modules/users.md
index 190dda0f0..6ffe74841 100644
--- a/docs/modules/users.md
+++ b/docs/modules/users.md
@@ -380,6 +380,15 @@ Admins see a **locked** badge on the users list and a "Locked until" row with an
 
 The account default is 10 rather than 5 because anyone who knows an address could otherwise lock its owner out from any network; the per-source throttle still stops a single source after 5. OAuth, Keycloak and invite-link sign-ins involve no password and are not counted. The stock fastapi-users router (`/api/users/auth-inner/*`) is not mounted.
 
+A successful password reset (`POST /api/users/auth/reset-password`, from the emailed link or an admin's reset link) also lifts the lock and clears the failure count: proving control of the mailbox is the standard way out of a lockout. Like an admin unlock it is an ORM write, so the audit log records it. The per-source throttle keys are left to expire, since they are keyed by an address the reset request does not know.
+
+Trade-offs to know about:
+
+- **Anyone can lock a known address.** The lock holds against the right password, so whoever knows an account's email can keep its owner out of password login for the cooldown, from any network. This is mitigated by the threshold of 10, by the per-source throttle (one source gets 5), by admin unlock, and by password reset now lifting the lock; OAuth/Keycloak sign-in is unaffected.
+- **A dead request still counts.** An attempt takes its slot before the password is checked; if the request dies (client disconnect, worker crash) after taking it and before settling, the slot stays counted until the window passes. If it held the last slot, the account answers `429` until `login_rate_limit_window_seconds` after that attempt — no `locked_until` is written, since only a settled failure writes it.
+- **Without Redis, entries can be evicted.** The in-process store caps its key count and evicts under that pressure, so a flood of distinct usernames can drop an unknown username's lock or a source's throttle early. Account locks live on the row and are unaffected. Set `SM_REDIS_URL` in production.
+- Login values longer than an address can be (254 characters) are hashed before they become store keys, so a large request body cannot park a large key in Redis.
+
 ## Mailer backends
 
 `mailer/` ships two implementations of the `Mailer` protocol:
diff --git a/modules/users/tests/test_users_admin_unlock.py b/modules/users/tests/test_users_admin_unlock.py
index 6c0ba1a3e..a35770da2 100644
--- a/modules/users/tests/test_users_admin_unlock.py
+++ b/modules/users/tests/test_users_admin_unlock.py
@@ -4,7 +4,7 @@
 
 from datetime import UTC, datetime, timedelta
 
-from _users_app_builders import ALICE, _login, user_row
+from _users_app_builders import ALICE, _client, _login, user_row
 from sqlalchemy import select
 from users.models import User
 
@@ -72,3 +72,29 @@ async def test_unlock_unknown_user_is_404(admin_client) -> None:
 async def test_unlock_requires_manage(user_client, alice) -> None:
     r = await user_client.patch(f"/api/users/admin/{alice.id}/unlock")
     assert r.status_code == 403
+
+
+async def test_password_reset_lifts_the_lock(users_app, admin_client, alice) -> None:
+    """Proving control of the mailbox is the way out of a lockout."""
+    from audit_log.models import AuditEntry
+
+    await _lock_by_failing(users_app)
+    assert (await _login(users_app, "9.9.9.9", ALICE, "UserPass1!")).status_code == 429
+    link = await admin_client.post(f"/api/users/admin/{alice.id}/reset-password-link")
+    token = link.json()["link"].split("token=", 1)[1]
+    async with _client(users_app, "7.7.7.7") as c:
+        reset = await c.post(
+            "/api/users/auth/reset-password", json={"token": token, "password": "NewPass1!x"}
+        )
+    assert reset.status_code == 200, reset.text
+
+    row = await user_row(users_app, ALICE)
+    assert (row.locked_until, row.failed_login_count, row.last_failed_login_at) == (None, 0, None)
+    assert (await _login(users_app, "9.9.9.9", ALICE, "NewPass1!x")).status_code == 204
+
+    async with users_app.state.sm.db.session_factory() as session:
+        stmt = select(AuditEntry).where(
+            AuditEntry.entity_id == str(alice.id), AuditEntry.action == "updated"
+        )
+        changes = [c for e in (await session.execute(stmt)).scalars() for c in e.changes]
+    assert [c["field"] for c in changes].count("locked_until") == 2  # the lock and the unlock
diff --git a/modules/users/tests/test_users_lockout_enumeration.py b/modules/users/tests/test_users_lockout_enumeration.py
index 0cbf00a46..2ac1b6d7b 100644
--- a/modules/users/tests/test_users_lockout_enumeration.py
+++ b/modules/users/tests/test_users_lockout_enumeration.py
@@ -56,16 +56,19 @@ async def both(ip: str) -> None:
     for i in range(10):
         await both(f"10.0.0.{i}")
         clock.offset += 250 if i < 9 else 0
-    clock.offset += 899  # one second before either lock lifts
+    clock.offset += 337.5  # part-way through the cooldown
+    await both("10.0.1.0")
+    clock.offset += 561.5  # one second before either lock lifts
     await both("10.0.1.1")
     clock.offset += 2
     await both("10.0.1.2")
 
     assert shapes[ALICE] == shapes[GHOST]
     trace = shapes[ALICE]
-    assert [s[0] for s in trace] == [400] * 9 + [429, 429, 400]
+    assert [s[0] for s in trace] == [400] * 9 + [429, 429, 429, 400]
     assert trace[9][2] == "900"  # the tripping attempt
-    assert trace[10][2] == "1"  # same duration on both
+    assert trace[10][2] == "563"  # mid-lock: the time left (ceil), not the full cooldown
+    assert trace[11][2] == "1"  # same duration on both
 
 
 async def test_known_and_unknown_take_the_same_password_path(users_app, monkeypatch) -> None:
diff --git a/modules/users/tests/test_users_lockout_service.py b/modules/users/tests/test_users_lockout_service.py
index 430a4f74d..426c87103 100644
--- a/modules/users/tests/test_users_lockout_service.py
+++ b/modules/users/tests/test_users_lockout_service.py
@@ -8,6 +8,7 @@
 from fastapi import HTTPException
 from simple_module_core.rate_limit import InProcessWindowStore
 from sqlalchemy import select
+from users.auth_local import lockout
 from users.auth_local.lockout import (
     Admission,
     LoginAttempt,
@@ -178,3 +179,24 @@ async def test_lock_write_survives_concurrent_counting(users_db, users_app, alic
         assert await _admit_or_status(other, _attempt(ip="10.0.0.8", store=store, account=3)) == 429
     await record_failure(users_db, last, slot)
     assert (await _row(users_db, alice)).locked_until is not None
+
+
+async def test_lock_landing_after_the_read_reports_the_time_left(users_db, alice) -> None:
+    """The conditional UPDATE misses on a lock another worker wrote after the read."""
+    for i in range(3):
+        await _fail(users_db, _attempt(ip=f"10.0.0.{i}", account=3))  # locked until T0+900
+    mid = _attempt(now=T0 + timedelta(seconds=300), ip="9.9.9.9", account=3)
+    try:
+        await lockout._admit_account(users_db, mid, [None])  # read before the lock landed
+    except HTTPException as exc:
+        assert (exc.status_code, exc.headers) == (429, {"Retry-After": "600"})
+    else:
+        raise AssertionError("a locked row was admitted")
+
+
+def test_overlong_username_is_hashed_in_store_keys() -> None:
+    long_name = _attempt("a" * 300 + "@example.com")
+    assert len(long_name.key_name) == 64
+    assert "a" * 100 not in long_name.ip_key + long_name.account_key + long_name.lock_key
+    assert _attempt("b" * 300).key_name != long_name.key_name
+    assert _attempt(ALICE).key_name == ALICE  # an address-length name is kept as-is
diff --git a/modules/users/tests/test_users_login_lockout.py b/modules/users/tests/test_users_login_lockout.py
index df207ce3a..5a62d6ed6 100644
--- a/modules/users/tests/test_users_login_lockout.py
+++ b/modules/users/tests/test_users_login_lockout.py
@@ -121,3 +121,29 @@ async def test_auth_inner_login_is_gone(users_app, alice) -> None:
             "/api/users/auth-inner/login", data={"username": ALICE, "password": PASSWORD}
         )
     assert inner.status_code in (404, 405)  # ...the unthrottled stock route does not
+
+
+async def test_token_lookup_ignores_case_like_session_login(users_app, alice) -> None:
+    for email in (ALICE, "Alice@Example.COM"):
+        assert (await _token(users_app, "1.1.1.1", email, PASSWORD)).status_code == 200
+        assert (await _login(users_app, "1.1.1.1", email, PASSWORD)).status_code == 204
+    # A wrong password under either spelling counts against the one account.
+    for email in (ALICE, "ALICE@example.com"):
+        assert (await _token(users_app, "2.2.2.2", email, "wrong")).status_code == 401
+    assert (await user_row(users_app, ALICE)).failed_login_count == 2
+
+
+async def test_token_unknown_user_still_pays_for_a_hash(users_app, alice, monkeypatch) -> None:
+    from fastapi_users.password import PasswordHelper
+
+    calls: list[str] = []
+    real = PasswordHelper.verify_and_update
+
+    def verify(self, plain, hashed):
+        calls.append(hashed)
+        return real(self, plain, hashed)
+
+    monkeypatch.setattr(PasswordHelper, "verify_and_update", verify)
+    r = await _token(users_app, "1.1.1.1", "ghost@example.com", PASSWORD)
+    assert r.status_code == 401
+    assert len(calls) == 1  # the dummy-hash equaliser ran
diff --git a/modules/users/users/auth_local/lockout.py b/modules/users/users/auth_local/lockout.py
index 43495a901..37ce58506 100644
--- a/modules/users/users/auth_local/lockout.py
+++ b/modules/users/users/auth_local/lockout.py
@@ -28,6 +28,7 @@
 
 from __future__ import annotations
 
+import hashlib
 import math
 import uuid
 from dataclasses import dataclass
@@ -84,9 +85,21 @@ def threshold(self) -> int:
     def cooldown(self) -> int:
         return self.settings.login_rate_limit_cooldown_seconds
 
+    @property
+    def key_name(self) -> str:
+        """The username as it appears in store keys.
+
+        The body limit is 10 MiB, so an unauthenticated caller could otherwise
+        park a megabyte-long key in Redis per request. Anything longer than an
+        address can be (254) is hashed; it matches no account either way.
+        """
+        if len(self.username) <= 254:
+            return self.username
+        return hashlib.sha256(self.username.encode()).hexdigest()
+
     @property
     def ip_key(self) -> str:
-        return f"login:ip:{self.ip}:{self.username}"
+        return f"login:ip:{self.ip}:{self.key_name}"
 
     @property
     def ip_spec(self) -> RateSpec:
@@ -95,11 +108,11 @@ def ip_spec(self) -> RateSpec:
 
     @property
     def account_key(self) -> str:
-        return f"login:acct:{self.username}"
+        return f"login:acct:{self.key_name}"
 
     @property
     def lock_key(self) -> str:
-        return f"login:acct-lock:{self.username}"
+        return f"login:acct-lock:{self.key_name}"
 
     @property
     def lock_spec(self) -> RateSpec:
@@ -156,12 +169,18 @@ async def admit(session: AsyncSession, attempt: LoginAttempt) -> Admission:
     return await _admit_unknown(attempt)
 
 
+def _lock_remaining(locks: list[datetime | None], now: datetime) -> int | None:
+    """Seconds until the latest live lock in *locks* lifts, or ``None`` if none holds."""
+    live = [lock for lock in locks if lock is not None and lock > now]
+    return math.ceil((max(live) - now).total_seconds()) if live else None
+
+
 async def _admit_account(
     session: AsyncSession, attempt: LoginAttempt, locks: list[datetime | None]
 ) -> Admission:
-    live = [lock for lock in locks if lock is not None and lock > attempt.now]
-    if live:
-        raise too_many_attempts(math.ceil((max(live) - attempt.now).total_seconds()))
+    remaining = _lock_remaining(locks, attempt.now)
+    if remaining is not None:
+        raise too_many_attempts(remaining)
     window_start = attempt.now - timedelta(seconds=attempt.settings.login_rate_limit_window_seconds)
     stale = User.last_failed_login_at.is_(None) | (User.last_failed_login_at < window_start)
     stmt = (
@@ -184,7 +203,13 @@ async def _admit_account(
     counted = (await session.execute(stmt)).all()
     await session.commit()
     if not counted:
-        raise too_many_attempts(attempt.cooldown)
+        # Locked by another worker since the read above: report the time left,
+        # as the unknown-username lock does, or ``Retry-After`` would tell the
+        # two apart. Otherwise the last slot is taken and its lock is being
+        # written — the full cooldown, as on the unknown path.
+        stmt = select(User.locked_until).where(_by_username(attempt.username))
+        locks = list((await session.execute(stmt)).scalars().all())
+        raise too_many_attempts(_lock_remaining(locks, attempt.now) or attempt.cooldown)
     return Admission(tuple(row[0] for row in counted), max(row[1] for row in counted))
 
 
diff --git a/modules/users/users/auth_local/token_api.py b/modules/users/users/auth_local/token_api.py
index 9207e151f..3bdbb1ba7 100644
--- a/modules/users/users/auth_local/token_api.py
+++ b/modules/users/users/auth_local/token_api.py
@@ -12,7 +12,7 @@
 
 from fastapi import APIRouter, Depends, HTTPException, Request
 from simple_module_db.deps import get_db
-from sqlalchemy import select
+from sqlalchemy import func, select
 from sqlalchemy.ext.asyncio import AsyncSession
 from sqlmodel import SQLModel
 
@@ -71,7 +71,9 @@ async def token_login(
     attempt = login_attempt(request, body.email)
     admission = await admit(db, attempt)
 
-    stmt = select(User).where(User.email == body.email)
+    # Case-insensitive, like ``UserDatabaseWithRoles.get_by_email`` behind the
+    # session login, so ``Alice@X`` reaches the account it is counted against.
+    stmt = select(User).where(func.lower(User.email) == body.email.lower())
     user = (await db.execute(stmt)).scalar_one_or_none()
     if (
         user is None
diff --git a/modules/users/users/manager.py b/modules/users/users/manager.py
index 944f547ea..ad893640d 100644
--- a/modules/users/users/manager.py
+++ b/modules/users/users/manager.py
@@ -163,6 +163,19 @@ async def on_after_forgot_password(
     ) -> None:
         await self.mailer.send_password_reset(user.email, token)
 
+    async def on_after_reset_password(self, user: User, request: Request | None = None) -> None:
+        """Lift a login lockout (GH #530): proving control of the mailbox is the way out.
+
+        Through ``user_db.update`` — an ORM write — so the audit log records the
+        unlock, as it does an admin's. The per-IP throttle keys are left alone:
+        they are keyed by source address, which this request does not know.
+        """
+        if user.locked_until is None and not user.failed_login_count:
+            return
+        await self.user_db.update(
+            user, {"locked_until": None, "failed_login_count": 0, "last_failed_login_at": None}
+        )
+
     async def on_after_request_verify(
         self, user: User, token: str, request: Request | None = None
     ) -> None: