Skip to content

~95% on SimpleQA (e.g. Qwen3.6-27B on a 3090). Supports all local and cloud LLMs (llama.cpp, Ollama, Google, ...). 10+ search engines - arXiv, PubMed, your private documents. Everything Local & Encrypted.

24.7 KB
Raw Blame
"""FastAPI replacements for the rate-limit coverage deleted in the
Flask -> FastAPI migration.

Audited against three files that existed on ``origin/main`` and were
removed by this branch:

* ``tests/security/test_rate_limiter.py`` (47 tests)
* ``tests/security/test_rate_limiter_deep_coverage.py`` (9 tests)
* ``tests/auth_tests/test_auth_rate_limiting.py`` (14 tests)

Most of that coverage already exists on this branch, in better form, under
``tests/web/dependencies/test_rate_limit_*.py``,
``tests/web/test_rate_limit_*.py`` and
``tests/web/routers/test_auth_rate_limits.py``. What follows is only the
residue: behaviour those files do NOT assert anywhere.

  1. ``limiter``'s key function is the spoof-guarded ``_get_client_ip``.
     ``test_rate_limit_keys.py`` exhaustively tests that function in
     isolation, but nothing pinned that the live ``Limiter`` actually
     keys on it. main pinned it (``limiter._key_func == get_client_ip``);
     if this regressed to slowapi's stock ``get_remote_address``, every
     forwarded-header test in the suite would still pass while the real
     deployment behind a proxy bucketed every user under the proxy's IP.
  2. A SUCCESSFUL login still consumes login quota
     (``test_successful_login_still_counts_toward_limit``). This is the
     credential-stuffing guard: if valid credentials bypassed or reset
     the bucket, an attacker who found one working password could keep
     hammering the endpoint for free. Only failing logins were exercised
     on this branch.
  3. The LOGIN 429's body + ``Retry-After`` / ``X-RateLimit-*`` headers.
     ``test_rate_limit_headers_on_429.py`` pins these for
     ``/auth/register`` only; main pinned them for ``/auth/login``, which
     is also the one endpoint where a 429 is ambiguous (account lockout
     returns 429 too, with a different body).
  4. Registration must not reveal whether a username exists
     (anti-enumeration). main tested this in the auth rate-limiting file
     because the generic message and the rate limit are the two halves of
     the same anti-enumeration defence.
  5. FUNCTIONAL enforcement of the dual per-user / per-IP upload buckets.
     ``test_rate_limit_coverage.py`` and
     ``test_router_sibling_consistency.py`` prove both decorators are
     APPLIED to the upload routes; nothing proved they actually block, or
     that the two buckets are keyed independently.
  6. A divergence found while auditing: ``_get_client_ip`` no longer
     strips whitespace from ``X-Real-IP`` (main did). Pinned, with the
     reasoning, in ``TestXRealIpWhitespaceDivergence``.

Idiom follows the branch's established rate-limit tests: the live
``limiter`` object is flipped on per-test (CI runs with
``LDR_DISABLE_RATE_LIMITING=true``) rather than reloading the module —
a reload would build a fresh ``Limiter`` while every router stays bound
to the original — and every client is pinned to its own private
``X-Forwarded-For`` so no two tests share a bucket. Starlette's
TestClient peer is the trusted ``testclient`` sentinel, so the forwarded
header is honored by ``_get_client_ip``.
"""

import uuid

import pytest
from fastapi import FastAPI, Request
from fastapi.testclient import TestClient
from slowapi.errors import RateLimitExceeded
from starlette.middleware.sessions import SessionMiddleware

from local_deep_research.web.dependencies.rate_limit import (
    LOGIN_RATE_LIMIT,
    REGISTRATION_RATE_LIMIT,
    UPLOAD_RATE_LIMIT_IP,
    UPLOAD_RATE_LIMIT_USER,
    _get_client_ip,
    _user_key,
    limiter,
    upload_rate_limit_ip,
    upload_rate_limit_user,
)


def _first_amount(limit_value) -> int:
    """``"5 per 15 minutes"`` -> 5; ``"60 per minute;1000 per hour"`` -> 60.

    Parsed from the live module constants so these tests exercise whatever
    limit is actually wired (env overrides included) rather than hardcoding
    the shipped defaults.
    """
    return int(str(limit_value).split(";")[0].strip().split()[0])


LOGIN_ATTEMPTS = _first_amount(LOGIN_RATE_LIMIT)
REGISTER_ATTEMPTS = _first_amount(REGISTRATION_RATE_LIMIT)
UPLOAD_USER_ATTEMPTS = _first_amount(UPLOAD_RATE_LIMIT_USER)
UPLOAD_IP_ATTEMPTS = _first_amount(UPLOAD_RATE_LIMIT_IP)


def _require_at_most(n: int, ceiling: int, what: str) -> None:
    """Keep runtime bounded if an env override cranked a limit way up."""
    if n > ceiling:
        pytest.skip(
            f"{what} limit is {n} in this environment — too many requests "
            "to exercise the threshold quickly"
        )


def _require_at_least(n: int, floor: int, what: str) -> None:
    """Skip when an env override made a limit too small for the scenario."""
    if n < floor:
        pytest.skip(
            f"{what} limit is {n} in this environment — this test needs at "
            f"least {floor} requests before the bucket closes"
        )


@pytest.fixture(autouse=True)
def rate_limiting_enforced():
    """Force slowapi enforcement ON for each test, then restore.

    The enabled flag is resolved from env at import time, so flip the live
    limiter object rather than reloading the module. Counters are cleared
    afterwards so buckets these tests exhaust can't leak into later suites
    running in the same process.
    """
    original = limiter.enabled
    limiter.enabled = True
    yield
    limiter.enabled = original
    try:
        limiter.reset()
    except Exception:
        pass


def _unique_ip() -> str:
    """A private (therefore trusted-range) IP nobody else's bucket uses."""
    parts = [uuid.uuid4().int % 254 + 1 for _ in range(3)]
    return f"10.{parts[0]}.{parts[1]}.{parts[2]}"


def _unique_username() -> str:
    return f"rl_{uuid.uuid4().hex[:12]}"


def _make_client(app, ip: str) -> TestClient:
    """Fresh client pinned to one forwarded IP, with a CSRF token armed.

    CSRFMiddleware runs before routing, so a POST rejected for CSRF would
    never reach the limit decorator — without the default header, form
    POSTs would not count toward their bucket at all and every negative
    assertion here would pass vacuously.
    """
    client = TestClient(app, raise_server_exceptions=False)
    client.headers.update({"X-Forwarded-For": ip})
    client.get("/auth/login")
    _refresh_csrf(client)
    return client


def _refresh_csrf(client: TestClient) -> None:
    """Re-arm the CSRF header from the client's CURRENT session.

    Logging in rotates the session, which invalidates the previously
    issued token; without a refresh the next POST would be rejected by
    CSRFMiddleware before ever reaching the rate limiter.
    """
    token = client.get("/auth/csrf-token").json()["csrf_token"]
    client.headers.update({"X-CSRFToken": token})


# Invalid-form payloads: fail validation fast (400) with no DB work, while
# still counting toward the route's bucket (slowapi's decorator increments
# before the endpoint body runs).
_BAD_LOGIN = {"username": "", "password": ""}
_STRONG_PASSWORD = "TestPass123"  # noqa: S105


def _register(client: TestClient, username: str, password: str):
    _refresh_csrf(client)
    return client.post(
        "/auth/register",
        data={
            "username": username,
            "password": password,
            "confirm_password": password,
            "acknowledge": "true",
        },
        follow_redirects=False,
    )


def _login(client: TestClient, username: str, password: str):
    _refresh_csrf(client)
    return client.post(
        "/auth/login",
        data={"username": username, "password": password},
        follow_redirects=False,
    )


class TestLimiterKeyFunction:
    """The live Limiter must key on the spoof-guarded client IP.

    main asserted ``limiter._key_func == get_client_ip``. The equivalent
    here is the last link nothing else checks: every unit test in
    ``test_rate_limit_keys.py`` calls ``_get_client_ip`` directly, so all
    of them would still pass if the Limiter had been built with slowapi's
    stock ``get_remote_address`` — and every user behind a reverse proxy
    would then share one bucket keyed on the proxy's address.
    """

    def test_limiter_keys_on_the_spoof_guarded_client_ip(self):
        assert limiter._key_func is _get_client_ip

    def test_key_func_is_wired_end_to_end_through_the_limiter(self):
        """Not just identity: the Limiter's key function, invoked the way
        slowapi invokes it, must honor a forwarded header from a trusted
        peer (i.e. it is the guarded resolver, not ``request.client``)."""
        from starlette.requests import Request as StarletteRequest

        request = StarletteRequest(
            {
                "type": "http",
                "method": "POST",
                "path": "/auth/login",
                "query_string": b"",
                "headers": [(b"x-forwarded-for", b"93.184.216.34")],
                "client": ("10.0.0.5", 51234),
            }
        )
        assert limiter._key_func(request) == "93.184.216.34"


class TestLoginBucket429Contract:
    """The LOGIN 429 must be distinguishable from an account-lockout 429
    and must carry retry timing.

    ``/auth/login`` returns 429 for TWO different reasons: this rate limit,
    and ``AccountLockoutManager.is_locked`` (an HTML page). main pinned the
    rate-limit shape here specifically; the branch only pinned it for
    ``/auth/register``.
    """

    def test_login_429_has_the_json_body_and_retry_headers(self, app):
        _require_at_most(LOGIN_ATTEMPTS, 15, "login")
        client = _make_client(app, _unique_ip())

        for i in range(LOGIN_ATTEMPTS):
            resp = client.post(
                "/auth/login", data=_BAD_LOGIN, follow_redirects=False
            )
            assert resp.status_code == 400, (
                f"attempt {i + 1}/{LOGIN_ATTEMPTS} must be a validation "
                f"400, not rate-limited yet; got {resp.status_code}"
            )

        resp = client.post(
            "/auth/login", data=_BAD_LOGIN, follow_redirects=False
        )
        assert resp.status_code == 429, (
            f"attempt {LOGIN_ATTEMPTS + 1} must be rate-limited; got "
            f"{resp.status_code}"
        )
        # JSON body — the lockout 429 renders an HTML template instead, so
        # this also proves WHICH 429 fired.
        assert resp.json() == {
            "error": "Too many requests",
            "message": "Too many attempts. Please try again later.",
        }
        assert "retry-after" in resp.headers, (
            f"login 429 missing Retry-After: {dict(resp.headers)}"
        )
        assert int(resp.headers["retry-after"]) >= 0
        assert resp.headers["x-ratelimit-limit"] == str(LOGIN_ATTEMPTS)
        assert "x-ratelimit-remaining" in resp.headers
        assert "x-ratelimit-reset" in resp.headers


class TestSuccessfulLoginsCountTowardTheLimit:
    """Credential-stuffing guard: valid credentials must not buy free
    attempts.

    slowapi's decorator checks and increments BEFORE the handler body
    runs, so this holds structurally — but only as long as the limit stays
    on the route rather than moving into the failure branch of the handler
    (which is exactly the "only count failures" refactor this test exists
    to block). Every other login test on this branch uses INVALID
    credentials, so none of them would notice.
    """

    def test_valid_credentials_still_consume_the_login_bucket(self, app):
        _require_at_most(LOGIN_ATTEMPTS, 8, "login")
        _require_at_least(REGISTER_ATTEMPTS, 1, "registration")

        ip = _unique_ip()
        client = _make_client(app, ip)
        username = _unique_username()

        resp = _register(client, username, _STRONG_PASSWORD)
        assert resp.status_code in (200, 302), (
            f"setup registration must succeed; got {resp.status_code}"
        )

        for i in range(LOGIN_ATTEMPTS):
            resp = _login(client, username, _STRONG_PASSWORD)
            assert resp.status_code == 302, (
                f"successful login {i + 1}/{LOGIN_ATTEMPTS} must redirect "
                f"(valid credentials); got {resp.status_code}"
            )

        resp = _login(client, username, _STRONG_PASSWORD)
        assert resp.status_code == 429, (
            "a successful login must still consume login quota — attempt "
            f"{LOGIN_ATTEMPTS + 1} with VALID credentials must be "
            f"rate-limited; got {resp.status_code}"
        )
        # Rate limit, not the account-lockout 429 (which cannot apply here:
        # every attempt used correct credentials, so the lockout counter
        # never incremented).
        assert resp.json()["error"] == "Too many requests"


class TestRegistrationAccountEnumeration:
    """A registration collision must not reveal that the username exists.

    Ported from main's ``test_account_enumeration_prevented``. main's
    version was itself broken (it depended on a user created by a sibling
    test against a function-scoped DB, so the collision never happened);
    this one registers the colliding user itself.
    """

    def test_duplicate_username_error_is_generic(self, app):
        # 3 registration POSTs: setup user, weak-password reject, collision.
        _require_at_least(REGISTER_ATTEMPTS, 3, "registration")

        client = _make_client(app, _unique_ip())
        existing = _unique_username()

        setup = _register(client, existing, _STRONG_PASSWORD)
        assert setup.status_code in (200, 302), (
            f"setup registration must succeed; got {setup.status_code}"
        )

        # A username that definitely does not exist, rejected on password
        # strength — the "no such account" control response.
        weak = _register(client, _unique_username(), "short")
        assert weak.status_code == 400, (
            f"weak-password registration must return 400; got "
            f"{weak.status_code}"
        )

        # The same request shape against a username that DOES exist.
        collision = _register(client, existing, _STRONG_PASSWORD)
        assert collision.status_code == 400, (
            "duplicate-username registration must return 400, not a "
            f"success or a distinct status; got {collision.status_code}"
        )

        body = collision.text
        assert "already exists" not in body.lower(), (
            "registration error reveals that the username exists"
        )
        assert existing not in body, (
            "registration error echoes the colliding username back"
        )
        assert (
            "Registration failed" in body or "try a different username" in body
        ), "duplicate registration must use the generic failure message"


# ---------------------------------------------------------------------------
# Dual-key upload limiting (functional).
#
# The real upload routes (``research.upload_pdf``,
# ``rag.upload_to_collection``) require an authenticated user and a real
# encrypted DB, and their default allowance is 60/minute — driving 60
# authenticated multipart uploads per assertion would be absurd. main
# solved the same problem by decorating a throwaway view with the real
# shared-limit decorators; the FastAPI equivalent is below.
#
# These use the REAL ``limiter`` object and the REAL ``_user_key``, so the
# buckets exercised here are the same buckets the real upload routes use
# (shared limits are keyed by (key, scope), not by route).
# ---------------------------------------------------------------------------


def _make_upload_app(app, decorators):
    """Build a throwaway app whose /upload route carries ``decorators``.

    ``decorators`` is applied outermost-first, matching how the real
    routes read::

        @upload_rate_limit_user
        @upload_rate_limit_ip
        async def upload_pdf(...)

    The endpoint gets a unique ``__name__`` because slowapi registers
    limits under ``f"{func.__module__}.{func.__name__}"`` and *extends*
    the existing list — two apps sharing a name would silently stack each
    other's limits.
    """
    endpoint_name = f"_upload_{uuid.uuid4().hex[:8]}"

    async def endpoint(request: Request):
        return {"ok": True}

    endpoint.__name__ = endpoint_name
    wrapped = endpoint
    for decorator in reversed(decorators):
        wrapped = decorator(wrapped)

    test_app = FastAPI()
    test_app.state.limiter = limiter
    # Reuse the REAL 429 handler so the body/header contract under test is
    # the deployed one, not a stand-in.
    test_app.add_exception_handler(
        RateLimitExceeded, app.exception_handlers[RateLimitExceeded]
    )
    # _user_key reads request.session; without SessionMiddleware the scope
    # has no "session" key and every request would fall back to the IP
    # bucket, making the per-user assertions vacuous.
    test_app.add_middleware(SessionMiddleware, secret_key="upload-limit-test")

    async def set_user(request: Request, username: str):
        request.session["username"] = username
        return {"ok": True}

    test_app.add_api_route("/_be", set_user, methods=["GET"])
    test_app.add_api_route("/upload", wrapped, methods=["POST"])
    return test_app, f"{endpoint.__module__}.{endpoint_name}"


@pytest.fixture()
def upload_app_factory(app):
    """Yields a builder; unregisters every limit it registered afterwards.

    Leaving entries behind would pollute the shared limiter registry that
    ``tests/web/test_rate_limit_coverage.py`` inspects.
    """
    registered: list[str] = []

    def _build(decorators):
        test_app, name = _make_upload_app(app, decorators)
        registered.append(name)
        return test_app

    yield _build

    marked = limiter._Limiter__marked_for_limiting
    for name in registered:
        limiter._route_limits.pop(name, None)
        limiter._dynamic_route_limits.pop(name, None)
        marked.pop(name, None)


def _upload_client(test_app, ip: str, username: str | None = None):
    client = TestClient(test_app, raise_server_exceptions=False)
    client.headers.update({"X-Forwarded-For": ip})
    if username is not None:
        resp = client.get("/_be", params={"username": username})
        assert resp.status_code == 200
    return client


class TestUploadDualBucketEnforcement:
    def test_real_upload_limits_block_after_their_threshold(
        self, upload_app_factory
    ):
        """The REAL ``upload_rate_limit_user`` / ``upload_rate_limit_ip``
        pair, stacked exactly as on ``upload_pdf``, must allow their
        configured allowance and then 429.

        The registry tests elsewhere prove the decorators are attached;
        this proves attaching them actually blocks anything.
        """
        threshold = min(UPLOAD_USER_ATTEMPTS, UPLOAD_IP_ATTEMPTS)
        _require_at_most(threshold, 120, "upload")

        test_app = upload_app_factory(
            [upload_rate_limit_user, upload_rate_limit_ip]
        )
        client = _upload_client(test_app, _unique_ip(), _unique_username())

        for i in range(threshold):
            resp = client.post("/upload")
            assert resp.status_code == 200, (
                f"upload {i + 1}/{threshold} must pass; got {resp.status_code}"
            )

        resp = client.post("/upload")
        assert resp.status_code == 429, (
            f"upload {threshold + 1} must be rate-limited; got "
            f"{resp.status_code}"
        )
        assert resp.json()["error"] == "Too many requests"

    def test_per_user_bucket_is_independent_between_users_on_one_ip(
        self, upload_app_factory
    ):
        """Two users behind the same NAT must not share the per-user
        upload bucket.

        Uses low, test-owned limits on the REAL limiter with the REAL
        ``_user_key`` — the same shape main used (``user_limit="3 per
        minute", ip_limit="100 per minute"``), which keeps the per-IP
        bucket well clear so only the per-user keying is under test.
        """
        scope = uuid.uuid4().hex[:8]
        test_app = upload_app_factory(
            [
                limiter.shared_limit(
                    "3 per minute",
                    scope=f"test_upload_user_{scope}",
                    key_func=_user_key,
                ),
                limiter.shared_limit(
                    "100 per minute", scope=f"test_upload_ip_{scope}"
                ),
            ]
        )

        shared_ip = _unique_ip()
        user_a = _upload_client(test_app, shared_ip, _unique_username())
        for i in range(3):
            assert user_a.post("/upload").status_code == 200, (
                f"user A upload {i + 1}/3 must pass"
            )
        assert user_a.post("/upload").status_code == 429, (
            "user A's 4th upload must exhaust their per-user bucket"
        )

        user_b = _upload_client(test_app, shared_ip, _unique_username())
        assert user_b.post("/upload").status_code == 200, (
            "user B shares only the IP, not the per-user bucket — their "
            "first upload must pass"
        )

        # And A is still blocked: B's request keyed elsewhere, it did not
        # reset anything.
        assert user_a.post("/upload").status_code == 429, (
            "user A must remain blocked after user B's request"
        )

    def test_per_ip_bucket_blocks_even_a_user_with_a_fresh_user_bucket(
        self, upload_app_factory
    ):
        """The per-IP half must bite too.

        main only ever asserted the per-user half, so a per-IP limit that
        silently did nothing (wrong key func, wrong scope, decorator not
        applied) would have gone unnoticed. Here the per-user allowance is
        deliberately huge and the per-IP one tiny: a brand-new user on the
        exhausted IP must still be refused, while the SAME user from a
        different IP goes through.
        """
        scope = uuid.uuid4().hex[:8]
        test_app = upload_app_factory(
            [
                limiter.shared_limit(
                    "100 per minute",
                    scope=f"test_upload_user_{scope}",
                    key_func=_user_key,
                ),
                limiter.shared_limit(
                    "3 per minute", scope=f"test_upload_ip_{scope}"
                ),
            ]
        )

        shared_ip = _unique_ip()
        user_a = _upload_client(test_app, shared_ip, _unique_username())
        for i in range(3):
            assert user_a.post("/upload").status_code == 200, (
                f"user A upload {i + 1}/3 must pass"
            )
        assert user_a.post("/upload").status_code == 429, (
            "user A's 4th upload must exhaust the per-IP bucket"
        )

        username_b = _unique_username()
        user_b = _upload_client(test_app, shared_ip, username_b)
        assert user_b.post("/upload").status_code == 429, (
            "a fresh user on an IP whose upload bucket is exhausted must "
            "still be refused — otherwise the per-IP limit is decorative"
        )

        elsewhere = _upload_client(test_app, _unique_ip(), username_b)
        assert elsewhere.post("/upload").status_code == 200, (
            "the same user from a different IP must have a fresh per-IP bucket"
        )


class TestXRealIpWhitespaceDivergence:
    """Regression test for a divergence from main, found during this audit
    and FIXED as part of it.

    main's ``get_client_ip`` did ``request.headers.get("X-Real-IP").strip()``
    and had a dedicated test (``test_strips_whitespace_from_real_ip``).
    This branch's ``_get_client_ip`` stripped the X-Forwarded-For entry
    it keyed on but returned ``X-Real-IP`` verbatim, so a
    padded value produces a DIFFERENT bucket key than the same address
    unpadded.

    Impact is low rather than nil: the header is only consulted at all
    when the direct peer is trusted (private/loopback or
    ``TRUST_PROXY_HEADERS=true``), and h11 — the parser uvicorn uses —
    strips optional whitespace from header values before they reach the
    ASGI scope, so a real deployment never sees a padded value. It is
    reachable through ASGI transports that do no such normalisation,
    including Starlette's TestClient.

    ``_get_client_ip`` has since grown the ``.strip()``, restoring parity
    with main, so this test asserts EQUALITY: a padded value and a clean
    one must key the same bucket. Removing the ``.strip()`` again makes it
    fail.
    """

    def test_padded_x_real_ip_keys_the_same_bucket(self):
        from starlette.requests import Request as StarletteRequest

        def key_for(raw_value: bytes) -> str:
            return _get_client_ip(
                StarletteRequest(
                    {
                        "type": "http",
                        "method": "GET",
                        "path": "/",
                        "query_string": b"",
                        "headers": [(b"x-real-ip", raw_value)],
                        "client": ("10.0.0.5", 51234),
                    }
                )
            )

        assert key_for(b"10.20.30.40") == "10.20.30.40"
        # Padding must NOT buy a fresh rate-limit bucket.
        assert key_for(b"  10.20.30.40  ") == "10.20.30.40"
        assert key_for(b"\t10.20.30.40 ") == "10.20.30.40"