vpndetection-fastapi 2.0.9__tar.gz → 2.1.0__tar.gz

{vpndetection_fastapi-2.0.9 → vpndetection_fastapi-2.1.0}/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 What each release changed for you, newest first. Each line is a commit's summary, linked to its full description and diff. Releases before 2.0.5 are described by their release commits.
 
+## 2.1.0 - 2026-10-03
+
+### Features
+
+- Add block_if, a FastAPI dependency refusing one endpoint to a matching visitor ([`c91eb21`](https://github.com/vpndetection-io/sdk-python-fastapi/commit/c91eb2118550e18ba6a5072193717c0e97f4f81c))
+
 ## 2.0.9 - 2026-10-02
 
 ### Fixes

{vpndetection_fastapi-2.0.9 → vpndetection_fastapi-2.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: vpndetection-fastapi
-Version: 2.0.9
+Version: 2.1.0
 Summary: Official FastAPI and Starlette middleware for the VPNDetection API. Detect VPNs, proxies, Tor, hosting and CDN visitors on every request.
 Project-URL: Homepage, https://vpndetection.io
 Project-URL: Source, https://github.com/vpndetection-io/sdk-python-fastapi
@@ -20,8 +20,9 @@ Classifier: Topic :: Security
 Classifier: Typing :: Typed
 Requires-Python: >=3.11
 Requires-Dist: starlette>=0.37
-Requires-Dist: vpndetection<6,>=5.5.3
+Requires-Dist: vpndetection<6,>=5.6.0
 Provides-Extra: dev
+Requires-Dist: fastapi>=0.115; extra == 'dev'
 Requires-Dist: mypy>=1.11; extra == 'dev'
 Requires-Dist: pytest>=8; extra == 'dev'
 Requires-Dist: ruff>=0.6; extra == 'dev'
@@ -92,6 +93,21 @@ Values are matched by equality, strings without regard to case. A list means any
 
 Replace the refusal with `on_blocked`.
 
+### Blocking one endpoint
+
+`block_condition` applies to every endpoint. In FastAPI, refuse a visitor on some endpoints only with the `block_if` dependency, on a path operation, a router or the app:
+
+```python
+from fastapi import Depends
+from vpndetection_fastapi import block_if
+
+
+@app.get("/checkout", dependencies=[Depends(block_if({"is_vpn": True}))])
+async def checkout(): ...
+```
+
+A refused request gets an `HTTPException`, `403` with `{"detail": "access denied"}` unless you pass `status_code` and `detail`. Declared as a parameter, the dependency hands the endpoint the answer. `block_if` takes the same condition, `fail_closed` and `on_missing_field`. It judges the answer the middleware already attached, so a visitor is looked up once however many endpoints check them, and it warns once for a member your plan doesn't include. A request `skip` claimed reaches the endpoint. The middleware still has to be added: without it, the dependency raises `RuntimeError` instead of letting everyone through.
+
 ## Where the client address comes from
 
 This is the setting that decides whether any of the above works, and it is the one thing only you can get right.

{vpndetection_fastapi-2.0.9 → vpndetection_fastapi-2.1.0}/README.md

@@ -63,6 +63,21 @@ Values are matched by equality, strings without regard to case. A list means any
 
 Replace the refusal with `on_blocked`.
 
+### Blocking one endpoint
+
+`block_condition` applies to every endpoint. In FastAPI, refuse a visitor on some endpoints only with the `block_if` dependency, on a path operation, a router or the app:
+
+```python
+from fastapi import Depends
+from vpndetection_fastapi import block_if
+
+
+@app.get("/checkout", dependencies=[Depends(block_if({"is_vpn": True}))])
+async def checkout(): ...
+```
+
+A refused request gets an `HTTPException`, `403` with `{"detail": "access denied"}` unless you pass `status_code` and `detail`. Declared as a parameter, the dependency hands the endpoint the answer. `block_if` takes the same condition, `fail_closed` and `on_missing_field`. It judges the answer the middleware already attached, so a visitor is looked up once however many endpoints check them, and it warns once for a member your plan doesn't include. A request `skip` claimed reaches the endpoint. The middleware still has to be added: without it, the dependency raises `RuntimeError` instead of letting everyone through.
+
 ## Where the client address comes from
 
 This is the setting that decides whether any of the above works, and it is the one thing only you can get right.

{vpndetection_fastapi-2.0.9 → vpndetection_fastapi-2.1.0}/pyproject.toml

@@ -24,14 +24,14 @@ classifiers = [
     "Topic :: Security",
     "Typing :: Typed",
 ]
-dependencies = ["vpndetection>=5.5.3,<6", "starlette>=0.37"]
+dependencies = ["vpndetection>=5.6.0,<6", "starlette>=0.37"]
 
 [project.urls]
 Homepage = "https://vpndetection.io"
 Source = "https://github.com/vpndetection-io/sdk-python-fastapi"
 
 [project.optional-dependencies]
-dev = ["pytest>=8", "mypy>=1.11", "ruff>=0.6"]
+dev = ["pytest>=8", "mypy>=1.11", "ruff>=0.6", "fastapi>=0.115"]
 
 [tool.hatch.build.targets.wheel]
 packages = ["src/vpndetection_fastapi"]

{vpndetection_fastapi-2.0.9 → vpndetection_fastapi-2.1.0}/src/vpndetection_fastapi/__init__.py

@@ -1,7 +1,8 @@
 """Official FastAPI and Starlette middleware for the VPNDetection API.
 
 Classifies the visitor behind each request and hangs the answer off
-``request.state.vpndetection``, where your endpoints can read it. Blocking is opt-in.
+``request.state.vpndetection``, where your endpoints can read it. Blocking is opt-in, for
+every endpoint or, in FastAPI, for one with the :func:`block_if` dependency.
 
     from fastapi import FastAPI
     from vpndetection_fastapi import VPNDetectionMiddleware
@@ -18,13 +19,17 @@ from __future__ import annotations
 from collections.abc import Awaitable, Callable
 from typing import Any
 
+from starlette.exceptions import HTTPException
 from starlette.requests import Request
 from starlette.responses import JSONResponse, Response
 from starlette.types import ASGIApp, Receive, Scope, Send
 from vpndetection.middleware import (
     AsyncCore,
+    Conditions,
+    Guard,
     IpSelector,
     Lookup,
+    MissingFieldAction,
     Options,
     RequestView,
     Selectors,
@@ -33,13 +38,18 @@ from vpndetection.middleware import (
 
 __all__ = [
     "VPNDetectionMiddleware",
+    "block_if",
     "default_ip_selector",
     "header_ip_selector",
     "lookup",
     "xff_ip_selector",
 ]
 
-__version__ = "2.0.9"
+__version__ = "2.1.0"
+
+# Set on a request ``skip`` claimed, so block_if can tell it from one the middleware
+# never saw.
+_SKIPPED = "_vpndetection_skipped"
 
 _SELECTORS: Selectors[Request] = bind_selectors(
     lambda request: RequestView(
@@ -79,6 +89,59 @@ def lookup(request: Request) -> Lookup | None:
     return getattr(request.state, "vpndetection", None)
 
 
+def block_if(
+    condition: Conditions,
+    *,
+    status_code: int = 403,
+    detail: Any = "access denied",
+    fail_closed: bool = False,
+    on_missing_field: MissingFieldAction = "warn",
+    on_warn: Callable[[str], None] | None = None,
+) -> Callable[[Request], Awaitable[Lookup | None]]:
+    """A FastAPI dependency refusing one endpoint to a visitor matching ``condition``.
+
+    The middleware's ``block_condition`` refuses on every endpoint; this refuses on the
+    path operations, routers or apps that depend on it, with an ``HTTPException`` of
+    ``status_code`` and ``detail``::
+
+        @app.get("/checkout", dependencies=[Depends(block_if({"is_vpn": True}))])
+        async def checkout(): ...
+
+    As a parameter it hands the endpoint the answer, or None for a request ``skip``
+    claimed. It judges the answer the middleware already attached, so the visitor is not
+    looked up again, and a member your plan does not serve is reported once, as the
+    middleware's own condition reports it. A condition that constrains nothing is
+    refused when the dependency is built.
+
+    A request ``skip`` claimed carries no answer and reaches the endpoint, and so does
+    one whose lookup failed unless you set ``fail_closed``. A request the middleware
+    never saw raises ``RuntimeError``: a check that silently never ran would be worse
+    than none.
+    """
+    guard = Guard(
+        condition,
+        fail_closed=fail_closed,
+        on_missing_field=on_missing_field,
+        on_warn=on_warn,
+        name="block_if",
+    )
+
+    async def dependency(request: Request) -> Lookup | None:
+        found = lookup(request)
+        if found is None:
+            if getattr(request.state, _SKIPPED, False):
+                return None
+            raise RuntimeError(
+                "vpndetection: block_if found no answer on this request; add "
+                "VPNDetectionMiddleware to the app"
+            )
+        if guard.blocks(found):
+            raise HTTPException(status_code=status_code, detail=detail)
+        return found
+
+    return dependency
+
+
 class VPNDetectionMiddleware:
     """Classify the visitor, and optionally refuse the request.
 
@@ -107,6 +170,7 @@ class VPNDetectionMiddleware:
         request = Request(scope, receive=receive)
         found = await self._core.evaluate(request)
         if found is None:
+            setattr(request.state, _SKIPPED, True)
             await self.app(scope, receive, send)
             return
         # request.state is backed by scope["state"], so this reaches the Request the

{vpndetection_fastapi-2.0.9 → vpndetection_fastapi-2.1.0}/tests/test_middleware.py

@@ -13,6 +13,7 @@ from typing import Any
 
 import httpx
 import pytest
+from fastapi import Depends, FastAPI
 from starlette.applications import Starlette
 from starlette.requests import Request
 from starlette.responses import JSONResponse
@@ -22,6 +23,7 @@ from vpndetection import AsyncVPNDetection
 
 from vpndetection_fastapi import (
     VPNDetectionMiddleware,
+    block_if,
     header_ip_selector,
     lookup,
     xff_ip_selector,
@@ -243,3 +245,117 @@ def test_corpus_conditions(case: dict[str, Any]) -> None:
     assert len(reported) == (1 if case["expect"]["missing"] else 0), case["why"]
     for member in case["expect"]["missing"]:
         assert member in reported[0], case["why"]
+
+
+def fastapi_with(guard: dict[str, Any] | None = None, **options: Any) -> FastAPI:
+    """A FastAPI app with the middleware, whose ``/guarded`` depends on
+    ``block_if(**guard)`` and ``/`` on nothing."""
+    app = FastAPI()
+    # A default rather than Annotated: under postponed annotations FastAPI resolves an
+    # annotation in module globals, where this per-app dependency does not live.
+    check = block_if(**(guard or {"condition": {"is_vpn": True}}))
+    app.add_api_route("/", index)
+
+    @app.get("/guarded")
+    async def guarded(found: Any = Depends(check)) -> dict[str, Any]:  # noqa: B008
+        return {"attached": found is not None, "ip": found.ip if found else None}
+
+    app.add_middleware(VPNDetectionMiddleware, **options)
+    return app
+
+
+def fetch(app: Any, url: str) -> tuple[int, dict[str, Any]]:
+    with TestClient(app, client=("127.0.0.1", 12345)) as client:
+        response = client.get(url)
+    return response.status_code, response.json()
+
+
+def test_block_if_refuses_only_the_endpoint_that_depends_on_it() -> None:
+    vpn = serving({"is_vpn": True, "vpn": {"provider": "nordvpn"}})
+    app = fastapi_with(client=vpn, ip_selector=fixed_ip)
+    status, body = fetch(app, "/guarded")
+    assert status == 403
+    assert body == {"detail": "access denied"}
+    status, body = fetch(app, "/")
+    assert status == 200, "the middleware itself has no condition, so other endpoints are open"
+    assert body["is_vpn"] is True
+    assert vpn.asked == [PUBLIC_IP, PUBLIC_IP], "one lookup per request, none by the dependency"
+
+    clean = serving({"is_vpn": False, "vpn": {}})
+    status, body = fetch(fastapi_with(client=clean, ip_selector=fixed_ip), "/guarded")
+    assert status == 200
+    assert body == {"attached": True, "ip": PUBLIC_IP}, "the dependency hands over the answer"
+
+
+def test_block_if_takes_its_status_and_detail() -> None:
+    vpn = serving({"is_vpn": True, "vpn": {"provider": "nordvpn"}})
+    guard = {"condition": {"is_vpn": True}, "status_code": 451, "detail": "not from a VPN"}
+    status, body = fetch(fastapi_with(guard, client=vpn, ip_selector=fixed_ip), "/guarded")
+    assert status == 451
+    assert body == {"detail": "not from a VPN"}
+
+
+def test_block_if_lets_a_skipped_request_through() -> None:
+    vpn = serving({"is_vpn": True})
+    app = fastapi_with(client=vpn, ip_selector=fixed_ip, skip=lambda request: True)
+    status, body = fetch(app, "/guarded")
+    assert status == 200
+    assert body == {"attached": False, "ip": None}
+    assert vpn.asked == []
+
+
+def test_block_if_fails_open_unless_told_to_fail_closed() -> None:
+    failing = serving({"error": "boom"}, status=500)
+    status, _ = fetch(fastapi_with(client=failing, ip_selector=fixed_ip), "/guarded")
+    assert status == 200
+
+    guard = {"condition": {"is_vpn": True}, "fail_closed": True}
+    status, body = fetch(fastapi_with(guard, client=failing, ip_selector=fixed_ip), "/guarded")
+    assert status == 403
+    assert body == {"detail": "access denied"}
+
+
+def test_block_if_without_the_middleware_is_an_error() -> None:
+    app = FastAPI()
+    check = block_if({"is_vpn": True})
+
+    @app.get("/guarded")
+    async def guarded(found: Any = Depends(check)) -> None:  # noqa: B008
+        return None
+
+    with pytest.raises(RuntimeError, match="add VPNDetectionMiddleware"):
+        fetch(app, "/guarded")
+
+
+def test_block_if_refuses_a_condition_that_constrains_nothing() -> None:
+    with pytest.raises(ValueError, match="constrains nothing"):
+        block_if({"is_vpn": False})
+
+
+def test_block_if_warns_once() -> None:
+    free = serving({"is_vpn": True})
+    warnings: list[str] = []
+    guard = {"condition": {"is_hosting": True}, "on_warn": warnings.append}
+    app = fastapi_with(guard, client=free, ip_selector=fixed_ip)
+    fetch(app, "/guarded")
+    fetch(app, "/guarded")
+    assert len(warnings) == 1
+    assert warnings[0].startswith("block_if names is_hosting")
+
+
+@pytest.mark.parametrize("case", MIDDLEWARE["conditions"], ids=lambda c: c["name"])
+def test_corpus_conditions_through_block_if(case: dict[str, Any]) -> None:
+    ip = case.get("bogon") or case["body"]["ip"]
+    client = serving({k: v for k, v in (case.get("body") or {}).items() if k != "ip"})
+    warnings: list[str] = []
+    app = fastapi_with(
+        {"condition": case["condition"], "on_warn": warnings.append},
+        client=client,
+        ip_selector=lambda _request, ip=ip: ip,
+    )
+    status, _ = fetch(app, "/guarded")
+    assert status == (403 if case["expect"]["blocked"] else 200), case["why"]
+    reported = [w for w in warnings if "does not include" in w]
+    assert len(reported) == (1 if case["expect"]["missing"] else 0), case["why"]
+    for member in case["expect"]["missing"]:
+        assert member in reported[0], case["why"]