modern-csrf 2026.10.20__tar.gz

modern_csrf-2026.10.20/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 George Macon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

modern_csrf-2026.10.20/PKG-INFO

@@ -0,0 +1,103 @@
+Metadata-Version: 2.4
+Name: modern-csrf
+Version: 2026.10.20
+Summary: Modern anti-CSRF middleware
+License-Expression: MIT
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: asgi
+Requires-Dist: asgiref>=3.10.0; extra == "asgi"
+Dynamic: license-file
+
+# Block Cross-Origin Requests
+
+This project implements the modern [Cross-Site Request Forgery (CSRF)][csrf] defenses
+as [described][valsorda] by Filippo Valsorda.
+This is the [Fetch metadata approach][mdn-csrf-fetch] described on MDN.
+Unsafe cross-origin requests are rejected with a 403 Forbidden status by default.
+
+[csrf]: https://developer.mozilla.org/en-US/docs/Web/Security/Attacks/CSRF
+[valsorda]: https://words.filippo.io/csrf/
+[mdn-csrf-fetch]: https://developer.mozilla.org/en-US/docs/Web/Security/Attacks/CSRF#fetch_metadata
+
+This approach protects users of browsers less than a few years old
+(and anyone using an older browser than that likely has worse problems to worry about).
+This approach is useful
+because it can be cleanly implemented as a middleware
+without requiring close coordination with the application.
+That doesn't mean that you can't use CSRF tokens too.
+
+## How it works
+
+The specific checks performed are:
+
+1.  Allow requests with one of the safe HTTP methods: `GET`, `HEAD`, or `OPTIONS`.
+1.  Allow requests from trusted origins.
+1.  If the `Sec-Fetch-Site` header is set,
+    allow requests with `Sec-Fetch-Site` set to `same-origin` or `none`, and
+    reject other requests.
+1.  Allow requests with neither of the `Sec-Fetch-Site` or `Origin` headers set.
+1.  If the `Origin` and `Host` headers are both set,
+    allow requests where the host-and-port portion of the origin matches the host.
+1.  Reject any remaining requests.
+
+## Things to watch out for
+
+In order for your application to be protected by this middleware,
+you *must not* change the application state
+in response to a request with one of the ["safe" methods][safe]
+(`GET`, `HEAD`, `OPTIONS`).
+Note that this is not an additional requirement because
+there are other places within the HTTP stack
+where this assumption already exists.
+For example,
+requests with these methods may be automatically retried
+without user intervention.
+
+[safe]: https://developer.mozilla.org/en-US/docs/Glossary/Safe/HTTP
+
+For this to work well,
+your application should be served from a [trustworthy origin][trustworthy],
+i.e. over HTTPS or via localhost.
+There may be false rejections if you do not use a trustworthy origin.
+
+[trustworthy]: https://www.w3.org/TR/secure-contexts/#is-origin-trustworthy
+
+## Protecting your application
+
+Two versions of the middleware are provided:
+a [Web Server Gateway Interface (WSGI)][wsgi] middleware
+`modern_csrf.wsgi.BlockCrossOriginRequests`,
+and an [Asynchronous Server Gateway Interface (ASGI)][asgi] middleware,
+`modern_csrf.asgi.BlockCrossOriginRequests`.
+Both versions have the same basic shape:
+the middleware is constructed with the next application as the first argument,
+and can be configured by setting keyword arguments.
+The available configuration parameters are:
+
+*   `trusted_origins`:
+    A collection of origins from which requests are always allowed.
+    An "origin" is specified as `scheme://host[:port]` string
+    and must match *exactly*, including case.
+    
+    Default: `()` (i.e. no trusted origins)
+    
+    Example: `["https://example.com", "https://example.net:1234"]`
+    
+*   `reject_handler`:
+    An application used to reject requests that should be rejected.
+    
+    The default value returns a 403 Forbidden status with a fixed message.
+    
+*   `log_rejected_requests`:
+    Should detailed information about rejected requests be logged?
+    For WSGI, the message is written to the WSGI error stream.
+    For ASGI, the message is logged via the standard library logging infrastructure.
+    
+    Default: `False`
+    
+    Example: `True`
+    
+[wsgi]: https://peps.python.org/pep-3333/
+[asgi]: https://asgi.readthedocs.io/en/latest/

modern_csrf-2026.10.20/README.md

@@ -0,0 +1,91 @@
+# Block Cross-Origin Requests
+
+This project implements the modern [Cross-Site Request Forgery (CSRF)][csrf] defenses
+as [described][valsorda] by Filippo Valsorda.
+This is the [Fetch metadata approach][mdn-csrf-fetch] described on MDN.
+Unsafe cross-origin requests are rejected with a 403 Forbidden status by default.
+
+[csrf]: https://developer.mozilla.org/en-US/docs/Web/Security/Attacks/CSRF
+[valsorda]: https://words.filippo.io/csrf/
+[mdn-csrf-fetch]: https://developer.mozilla.org/en-US/docs/Web/Security/Attacks/CSRF#fetch_metadata
+
+This approach protects users of browsers less than a few years old
+(and anyone using an older browser than that likely has worse problems to worry about).
+This approach is useful
+because it can be cleanly implemented as a middleware
+without requiring close coordination with the application.
+That doesn't mean that you can't use CSRF tokens too.
+
+## How it works
+
+The specific checks performed are:
+
+1.  Allow requests with one of the safe HTTP methods: `GET`, `HEAD`, or `OPTIONS`.
+1.  Allow requests from trusted origins.
+1.  If the `Sec-Fetch-Site` header is set,
+    allow requests with `Sec-Fetch-Site` set to `same-origin` or `none`, and
+    reject other requests.
+1.  Allow requests with neither of the `Sec-Fetch-Site` or `Origin` headers set.
+1.  If the `Origin` and `Host` headers are both set,
+    allow requests where the host-and-port portion of the origin matches the host.
+1.  Reject any remaining requests.
+
+## Things to watch out for
+
+In order for your application to be protected by this middleware,
+you *must not* change the application state
+in response to a request with one of the ["safe" methods][safe]
+(`GET`, `HEAD`, `OPTIONS`).
+Note that this is not an additional requirement because
+there are other places within the HTTP stack
+where this assumption already exists.
+For example,
+requests with these methods may be automatically retried
+without user intervention.
+
+[safe]: https://developer.mozilla.org/en-US/docs/Glossary/Safe/HTTP
+
+For this to work well,
+your application should be served from a [trustworthy origin][trustworthy],
+i.e. over HTTPS or via localhost.
+There may be false rejections if you do not use a trustworthy origin.
+
+[trustworthy]: https://www.w3.org/TR/secure-contexts/#is-origin-trustworthy
+
+## Protecting your application
+
+Two versions of the middleware are provided:
+a [Web Server Gateway Interface (WSGI)][wsgi] middleware
+`modern_csrf.wsgi.BlockCrossOriginRequests`,
+and an [Asynchronous Server Gateway Interface (ASGI)][asgi] middleware,
+`modern_csrf.asgi.BlockCrossOriginRequests`.
+Both versions have the same basic shape:
+the middleware is constructed with the next application as the first argument,
+and can be configured by setting keyword arguments.
+The available configuration parameters are:
+
+*   `trusted_origins`:
+    A collection of origins from which requests are always allowed.
+    An "origin" is specified as `scheme://host[:port]` string
+    and must match *exactly*, including case.
+    
+    Default: `()` (i.e. no trusted origins)
+    
+    Example: `["https://example.com", "https://example.net:1234"]`
+    
+*   `reject_handler`:
+    An application used to reject requests that should be rejected.
+    
+    The default value returns a 403 Forbidden status with a fixed message.
+    
+*   `log_rejected_requests`:
+    Should detailed information about rejected requests be logged?
+    For WSGI, the message is written to the WSGI error stream.
+    For ASGI, the message is logged via the standard library logging infrastructure.
+    
+    Default: `False`
+    
+    Example: `True`
+    
+[wsgi]: https://peps.python.org/pep-3333/
+[asgi]: https://asgi.readthedocs.io/en/latest/

modern_csrf-2026.10.20/pyproject.toml

@@ -0,0 +1,34 @@
+[project]
+name = "modern-csrf"
+version = "2026.10.20"
+description = "Modern anti-CSRF middleware"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+dependencies = []
+
+[project.optional-dependencies]
+asgi = [
+    "asgiref>=3.10.0",
+]
+
+[build-system]
+requires = ["setuptools >= 77.0.3"]
+build-backend = "setuptools.build_meta"
+
+[dependency-groups]
+dev = [
+    "mypy>=1.18.2",
+    "python-lsp-ruff>=2.3.0",
+    "python-lsp-server>=1.13.1",
+]
+
+[tool.ruff.lint]
+select = ["E4", "E7", "E9", "F", "I"]
+
+[tool.mypy]
+files = [
+    "src/**/*.py",
+]
+disallow_untyped_defs = true

modern_csrf-2026.10.20/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

modern_csrf-2026.10.20/src/modern_csrf/asgi.py

@@ -0,0 +1,96 @@
+import logging
+from collections.abc import Awaitable, Container
+
+from asgiref.compatibility import guarantee_single_callable
+from asgiref.typing import (
+    ASGI3Application,
+    ASGIApplication,
+    ASGIReceiveCallable,
+    ASGISendCallable,
+    HTTPScope,
+    Scope,
+)
+
+from modern_csrf.base import should_accept_request
+
+log = logging.getLogger(__name__)
+
+
+async def default_reject_handler(
+    scope: Scope, receive: ASGIReceiveCallable, send: ASGISendCallable
+) -> None:
+    await send(
+        {
+            "type": "http.response.start",
+            "status": 403,
+            "headers": [(b"Content-Type", b"text/plain")],
+            "trailers": False,
+        }
+    )
+    await send(
+        {
+            "type": "http.response.body",
+            "body": b"Unexpected cross-origin request forbidden.",
+            "more_body": False,
+        }
+    )
+
+
+class BlockCrossOriginRequests:
+    app: ASGI3Application
+    trusted_origins: Container[str]
+    reject_handler: ASGI3Application
+    log_rejected_requests: bool
+    _asgi_single_callable: bool
+
+    def __init__(
+        self,
+        app: ASGIApplication,
+        *,
+        trusted_origins: Container[str] = (),
+        reject_handler: ASGIApplication = default_reject_handler,
+        log_rejected_requests: bool = False,
+    ) -> None:
+        self.app = guarantee_single_callable(app)
+        self.trusted_origins = trusted_origins
+        self.reject_handler = guarantee_single_callable(reject_handler)
+        self.log_rejected_requests = log_rejected_requests
+
+        # This is a hint to asgiref,
+        # which would otherwise be confused by our `__call__` not being async.
+        self._asgi_single_callable = True
+
+    def __call__(
+        self, scope: Scope, receive: ASGIReceiveCallable, send: ASGISendCallable
+    ) -> Awaitable[None]:
+        if scope["type"] != "http":
+            return self.app(scope, receive, send)
+
+        http_scope: HTTPScope = scope
+
+        method = http_scope["method"]
+        origin: str | None = None
+        sec_fetch_site: str | None = None
+        host: str | None = None
+
+        for name, value in http_scope["headers"]:
+            name = name.lower()
+            if name == b"origin":
+                origin = value.decode("ascii")
+            elif name == b"sec-fetch-site":
+                sec_fetch_site = value.decode("ascii")
+            elif name == b"host":
+                host = value.decode("ascii")
+
+        if should_accept_request(
+            method=method,
+            origin=origin,
+            sec_fetch_site=sec_fetch_site,
+            host=host,
+            trusted_origins=self.trusted_origins,
+        ):
+            return self.app(scope, receive, send)
+        else:
+            if self.log_rejected_requests:
+                log.error("Rejecting unexpected cross-origin request: %r", scope)
+            return self.reject_handler(scope, receive, send)

modern_csrf-2026.10.20/src/modern_csrf/base.py

@@ -0,0 +1,49 @@
+from collections.abc import Container
+
+
+def should_accept_request(
+    method: str,
+    origin: str | None,
+    sec_fetch_site: str | None,
+    host: str | None,
+    trusted_origins: Container[str],
+) -> bool:
+    """Should the HTTP request be accepted?
+
+    This evaluates a request based on the fetch metadata headers
+    and returns ``True`` if it should be accepted and ``False`` otherwise.
+    Requests
+
+    1. Should be accepted if they use a safe HTTP method.
+    2. Should be accepted if they are from a trusted origin.
+    3. Should be accepted
+       if the browser indicates that it is not a cross-origin request,
+       and rejected if the browser indicates that it is a cross-origin request.
+    4. Should be accepted if the request is not from a web browser.
+    5. Should be accepted if the host matches the origin.
+       (Since non-trustworthy origins (i.e. http:) don't send the Sec-* headers.)
+
+    all other requests are rejected.
+
+    """
+    if method in ("GET", "HEAD", "OPTIONS"):
+        return True
+
+    if origin in trusted_origins:
+        return True
+
+    if sec_fetch_site is not None:
+        if sec_fetch_site in ("same-origin", "none"):
+            return True
+        else:
+            return False
+
+    if sec_fetch_site is None and origin is None:
+        return True
+
+    if origin is not None and host is not None:
+        scheme, sep, host_with_port = origin.partition("://")
+        if host_with_port == host:
+            return True
+
+    return False

modern_csrf-2026.10.20/src/modern_csrf/wsgi.py

@@ -0,0 +1,56 @@
+from collections.abc import Container, Iterable
+from wsgiref.types import ErrorStream, StartResponse, WSGIApplication, WSGIEnvironment
+
+from modern_csrf.base import should_accept_request
+
+
+def default_reject_handler(
+    environ: WSGIEnvironment, start_response: StartResponse
+) -> Iterable[bytes]:
+    start_response("403 Forbidden", [("Content-Type", "text/plain")])
+    return [b"Unexpected cross-origin request forbidden."]
+
+
+class BlockCrossOriginRequests:
+    app: WSGIApplication
+    trusted_origins: Container[str]
+    reject_handler: WSGIApplication
+    log_rejected_requests: bool
+
+    def __init__(
+        self,
+        app: WSGIApplication,
+        *,
+        trusted_origins: Container[str] = (),
+        reject_handler: WSGIApplication = default_reject_handler,
+        log_rejected_requests: bool = False,
+    ) -> None:
+        self.app = app
+        self.trusted_origins = trusted_origins
+        self.reject_handler = reject_handler
+        self.log_rejected_requests = log_rejected_requests
+
+    def __call__(
+        self, environ: WSGIEnvironment, start_response: StartResponse
+    ) -> Iterable[bytes]:
+        method = environ["REQUEST_METHOD"]
+        origin = environ.get("HTTP_ORIGIN")
+        sec_fetch_site = environ.get("HTTP_SEC_FETCH_SITE")
+        host = environ.get("HTTP_HOST")
+
+        if should_accept_request(
+            method=method,
+            origin=origin,
+            sec_fetch_site=sec_fetch_site,
+            host=host,
+            trusted_origins=self.trusted_origins,
+        ):
+            return self.app(environ, start_response)
+        else:
+            if self.log_rejected_requests:
+                errors: ErrorStream = environ["wsgi.errors"]
+                errors.write(
+                    f"Rejecting unexpected cross-origin request: {environ!r}\n"
+                )
+                errors.flush()
+            return self.reject_handler(environ, start_response)

modern_csrf-2026.10.20/src/modern_csrf.egg-info/PKG-INFO

@@ -0,0 +1,103 @@
+Metadata-Version: 2.4
+Name: modern-csrf
+Version: 2026.10.20
+Summary: Modern anti-CSRF middleware
+License-Expression: MIT
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: asgi
+Requires-Dist: asgiref>=3.10.0; extra == "asgi"
+Dynamic: license-file
+
+# Block Cross-Origin Requests
+
+This project implements the modern [Cross-Site Request Forgery (CSRF)][csrf] defenses
+as [described][valsorda] by Filippo Valsorda.
+This is the [Fetch metadata approach][mdn-csrf-fetch] described on MDN.
+Unsafe cross-origin requests are rejected with a 403 Forbidden status by default.
+
+[csrf]: https://developer.mozilla.org/en-US/docs/Web/Security/Attacks/CSRF
+[valsorda]: https://words.filippo.io/csrf/
+[mdn-csrf-fetch]: https://developer.mozilla.org/en-US/docs/Web/Security/Attacks/CSRF#fetch_metadata
+
+This approach protects users of browsers less than a few years old
+(and anyone using an older browser than that likely has worse problems to worry about).
+This approach is useful
+because it can be cleanly implemented as a middleware
+without requiring close coordination with the application.
+That doesn't mean that you can't use CSRF tokens too.
+
+## How it works
+
+The specific checks performed are:
+
+1.  Allow requests with one of the safe HTTP methods: `GET`, `HEAD`, or `OPTIONS`.
+1.  Allow requests from trusted origins.
+1.  If the `Sec-Fetch-Site` header is set,
+    allow requests with `Sec-Fetch-Site` set to `same-origin` or `none`, and
+    reject other requests.
+1.  Allow requests with neither of the `Sec-Fetch-Site` or `Origin` headers set.
+1.  If the `Origin` and `Host` headers are both set,
+    allow requests where the host-and-port portion of the origin matches the host.
+1.  Reject any remaining requests.
+
+## Things to watch out for
+
+In order for your application to be protected by this middleware,
+you *must not* change the application state
+in response to a request with one of the ["safe" methods][safe]
+(`GET`, `HEAD`, `OPTIONS`).
+Note that this is not an additional requirement because
+there are other places within the HTTP stack
+where this assumption already exists.
+For example,
+requests with these methods may be automatically retried
+without user intervention.
+
+[safe]: https://developer.mozilla.org/en-US/docs/Glossary/Safe/HTTP
+
+For this to work well,
+your application should be served from a [trustworthy origin][trustworthy],
+i.e. over HTTPS or via localhost.
+There may be false rejections if you do not use a trustworthy origin.
+
+[trustworthy]: https://www.w3.org/TR/secure-contexts/#is-origin-trustworthy
+
+## Protecting your application
+
+Two versions of the middleware are provided:
+a [Web Server Gateway Interface (WSGI)][wsgi] middleware
+`modern_csrf.wsgi.BlockCrossOriginRequests`,
+and an [Asynchronous Server Gateway Interface (ASGI)][asgi] middleware,
+`modern_csrf.asgi.BlockCrossOriginRequests`.
+Both versions have the same basic shape:
+the middleware is constructed with the next application as the first argument,
+and can be configured by setting keyword arguments.
+The available configuration parameters are:
+
+*   `trusted_origins`:
+    A collection of origins from which requests are always allowed.
+    An "origin" is specified as `scheme://host[:port]` string
+    and must match *exactly*, including case.
+    
+    Default: `()` (i.e. no trusted origins)
+    
+    Example: `["https://example.com", "https://example.net:1234"]`
+    
+*   `reject_handler`:
+    An application used to reject requests that should be rejected.
+    
+    The default value returns a 403 Forbidden status with a fixed message.
+    
+*   `log_rejected_requests`:
+    Should detailed information about rejected requests be logged?
+    For WSGI, the message is written to the WSGI error stream.
+    For ASGI, the message is logged via the standard library logging infrastructure.
+    
+    Default: `False`
+    
+    Example: `True`
+    
+[wsgi]: https://peps.python.org/pep-3333/
+[asgi]: https://asgi.readthedocs.io/en/latest/

modern_csrf-2026.10.20/src/modern_csrf.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENSE
+README.md
+pyproject.toml
+src/modern_csrf/__init__.py
+src/modern_csrf/asgi.py
+src/modern_csrf/base.py
+src/modern_csrf/py.typed
+src/modern_csrf/wsgi.py
+src/modern_csrf.egg-info/PKG-INFO
+src/modern_csrf.egg-info/SOURCES.txt
+src/modern_csrf.egg-info/dependency_links.txt
+src/modern_csrf.egg-info/requires.txt
+src/modern_csrf.egg-info/top_level.txt

modern_csrf-2026.10.20/src/modern_csrf.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

modern_csrf-2026.10.20/src/modern_csrf.egg-info/requires.txt

@@ -0,0 +1,3 @@
+
+[asgi]
+asgiref>=3.10.0

modern_csrf-2026.10.20/src/modern_csrf.egg-info/top_level.txt

@@ -0,0 +1 @@
+modern_csrf