M4-T02: add exponential login back-off service and wire into login endpoint

app/api/routes/api/session.py

@@ -2,7 +2,7 @@ from __future__ import annotations
 
 import logging
 
-from fastapi import APIRouter, Depends, HTTPException, Response, status
+from fastapi import APIRouter, Depends, HTTPException, Request, Response, status
 from sqlalchemy.orm import Session
 
 from app.api.routes.api.deps import require_csrf, require_session
@@ -22,6 +22,7 @@ from app.services.auth import (
     create_session,
     revoke_session,
 )
+from app.services import login_throttle
 
 logger = logging.getLogger(__name__)
 
@@ -46,9 +47,26 @@ def get_session(
     return _build_session_response(auth)
 
 
+def _get_client_ip(request: Request, *, trust_forwarded_for: bool) -> str:
+    """Extract the client IP address from the request.
+
+    When ``trust_forwarded_for`` is True (reverse-proxy deployments) the
+    left-most value from the ``X-Forwarded-For`` header is used.  Otherwise the
+    direct socket IP (``request.client.host``) is used.
+    """
+    if trust_forwarded_for:
+        xff = request.headers.get("X-Forwarded-For", "")
+        if xff:
+            return xff.split(",")[0].strip()
+    if request.client is not None:
+        return request.client.host
+    return "unknown"
+
+
 @router.post("/auth/login", response_model=SessionResponse)
 def post_login(
     body: LoginRequest,
+    request: Request,
     response: Response,
     db: Session = Depends(get_db),
     settings: Settings = Depends(get_app_settings),
@@ -58,15 +76,37 @@ def post_login(
 
     On success, sets an HttpOnly session cookie and returns the session user + CSRF token.
     On failure, returns 401 with no cookie set.
+    Repeated failures trigger exponential back-off (429 + Retry-After).
     No X-CSRF-Token required (unauthenticated endpoint).
     """
+    client_ip = _get_client_ip(request, trust_forwarded_for=settings.auth_trust_forwarded_for)
+
+    # --- Throttle check (before any password verification) ---
+    if settings.auth_login_throttle_enabled:
+        wait_seconds = login_throttle.check_and_get_wait(
+            db, ip=client_ip, username=body.username
+        )
+        if wait_seconds > 0:
+            raise HTTPException(
+                status_code=status.HTTP_429_TOO_MANY_REQUESTS,
+                detail="too many failed login attempts; please try again later",
+                headers={"Retry-After": str(wait_seconds)},
+            )
+
+    # --- Password verification ---
     user = authenticate_user(db, username=body.username, password=body.password)
     if user is None:
+        if settings.auth_login_throttle_enabled:
+            login_throttle.register_failure(db, ip=client_ip, username=body.username)
         raise HTTPException(
             status_code=status.HTTP_401_UNAUTHORIZED,
             detail="invalid username or password",
         )
 
+    # --- Success: clear back-off state and issue session ---
+    if settings.auth_login_throttle_enabled:
+        login_throttle.clear(db, ip=client_ip, username=body.username)
+
     auth_session, raw_token = create_session(db, user=user, settings=settings)
     logger.info("Created API authenticated session for user '%s'", user.username)