coffeehouse-common 0.15.1__tar.gz

coffeehouse_common-0.15.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ruben Sukiasyan
+
+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 OF OTHER DEALINGS IN THE
+SOFTWARE.

coffeehouse_common-0.15.1/PKG-INFO

@@ -0,0 +1,170 @@
+Metadata-Version: 2.4
+Name: coffeehouse-common
+Version: 0.15.1
+Summary: Shared CSRF, security headers, logging, observability, flash messages, role-cleanup, and Auth client for Coffee House FastAPI apps
+Author-email: Ruben Sukiasyan <rubsksn@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2026 Ruben Sukiasyan
+        
+        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 OF OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/coffeehouse-tools/coffeehouse-common
+Project-URL: Repository, https://github.com/coffeehouse-tools/coffeehouse-common
+Project-URL: Issues, https://github.com/coffeehouse-tools/coffeehouse-common/issues
+Project-URL: Changelog, https://github.com/coffeehouse-tools/coffeehouse-common/blob/master/CHANGELOG.md
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Classifier: Framework :: FastAPI
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: itsdangerous==2.2.0
+Requires-Dist: starlette>=0.38.0
+Requires-Dist: starlette-csrf==3.0.0
+Requires-Dist: SQLAlchemy>=2.0
+Requires-Dist: requests>=2.31
+Requires-Dist: sentry-sdk<3.0,>=2.20
+Provides-Extra: testing
+Requires-Dist: pytest>=8.0; extra == "testing"
+Requires-Dist: PyJWT>=2.8; extra == "testing"
+Requires-Dist: httpx>=0.27; extra == "testing"
+Requires-Dist: python-multipart>=0.0.9; extra == "testing"
+Dynamic: license-file
+
+# coffeehouse-common
+
+Shared Python package for Coffee House ecosystem FastAPI apps:
+
+- `coffeehouse_common.csrf` — `CSRFMiddleware` subclass (form body + header + safe body replay)
+- `coffeehouse_common.security_middleware` — `SecurityHeadersMiddleware` (raw ASGI)
+- `coffeehouse_common.logging_config` — `RequestIdMiddleware` (raw ASGI), `RequestIdFilter`, `configure_logging`, `get_request_id`
+- `coffeehouse_common.observability` — `init_sentry(app_slug)` Sentry SDK bootstrap; reads `SENTRY_DSN` from env (no-op when unset), tags events with `app_slug`, drops 4xx HTTP/CSRF noise, keeps 5xx
+
+**v0.3.0+** implements security headers and request ID middleware as **raw ASGI** (not `BaseHTTPMiddleware`) so streaming responses are not fully buffered. **v0.3.1** sets `X-Frame-Options: SAMEORIGIN` (same-origin iframes allowed; third-party framing blocked). Logs include a per-request correlation id when `configure_logging()` + `RequestIdMiddleware` are used.
+
+## Install
+
+From GitHub (pinned tag):
+
+```bash
+pip install "coffeehouse-common @ git+https://github.com/rubencfh/coffeehouse-common.git@v0.9.0"
+```
+
+Local editable install:
+
+```bash
+pip install -e ../coffeehouse-common
+```
+
+## Development
+
+Set up the repo for local development + testing:
+
+```bash
+git clone https://github.com/rubencfh/coffeehouse-common.git
+cd coffeehouse-common
+pip install -e ".[testing]"
+pip install -r requirements-dev.txt
+pre-commit install
+```
+
+Run the full test suite (with coverage, fails under 70%):
+
+```bash
+pytest
+```
+
+Run the pre-commit hooks against all files (format, lint, secret scan, syntax check):
+
+```bash
+pre-commit run --all-files
+```
+
+Individual checks:
+
+```bash
+ruff format --check .          # formatting
+ruff check .                   # linting
+mypy coffeehouse_common        # type-checking (lenient baseline)
+bandit -c pyproject.toml -r coffeehouse_common coffeehouse_testing  # SAST
+pip-audit -r requirements-dev.txt                                    # SCA
+```
+
+CI runs the same checks on every push / PR via `.github/workflows/ci.yml`.
+See `coffeehouse-ecosystem/docs/pipeline.md` for the broader pipeline.
+
+### Shared test fixtures
+
+The `coffeehouse_testing` subpackage ships with this repo and provides shared
+pytest fixtures that consumer apps import in their own `tests/conftest.py`:
+
+```python
+from coffeehouse_testing.jwt_factory import jwt_factory
+from coffeehouse_testing.client import authed_client
+from coffeehouse_testing.db import postgres_container, clean_db  # noqa: F401
+from coffeehouse_testing.auth_stub import make_auth_stub, build_roles_manifest
+```
+
+All heavy dependencies (PyJWT, testcontainers, starlette) are loaded lazily —
+import the modules you need in tests and the import errors only fire if the
+underlying package is not installed.
+
+## Usage
+
+```python
+from coffeehouse_common.csrf import CSRFMiddleware
+from coffeehouse_common.logging_config import RequestIdMiddleware, configure_logging
+from coffeehouse_common.observability import init_sentry
+from coffeehouse_common.security_middleware import SecurityHeadersMiddleware
+
+configure_logging()  # once at startup; attaches RequestIdFilter for %(request_id)s
+init_sentry(app_slug="auth")  # no-op if SENTRY_DSN is unset
+```
+
+`init_sentry` reads `SENTRY_DSN`, `RAILWAY_ENVIRONMENT_NAME` (or `ENVIRONMENT`),
+and `RAILWAY_GIT_COMMIT_SHA` from the environment. Errors-only sample rate by
+default (`traces_sample_rate=0.0`). 401/403/404/405 responses, 4xx
+`HTTPException`s, and `CSRFError`s are dropped client-side so they don't burn
+the Sentry quota. 5xx HTTPExceptions and any other exception class are kept.
+Pass `extra_ignored_status_codes=` / `extra_ignored_exceptions=` to extend the
+filter per app.
+
+Explicit dependency: **`itsdangerous`** (CSRF token signing).
+
+See `CONVENTIONS.md` in the `coffeehouse-ecosystem` repo for middleware order and CSRF patterns.
+
+## First-time publish (maintainers)
+
+1. Create an empty repo on GitHub: `rubencfh/coffeehouse-common`
+2. From this directory:
+
+```bash
+git remote add origin https://github.com/rubencfh/coffeehouse-common.git
+git push -u origin master
+git push origin v0.9.0
+```
+
+Until the repo and tag exist, app Docker builds that `pip install` from GitHub will fail. For local dev, use editable install (above).

coffeehouse_common-0.15.1/README.md

@@ -0,0 +1,114 @@
+# coffeehouse-common
+
+Shared Python package for Coffee House ecosystem FastAPI apps:
+
+- `coffeehouse_common.csrf` — `CSRFMiddleware` subclass (form body + header + safe body replay)
+- `coffeehouse_common.security_middleware` — `SecurityHeadersMiddleware` (raw ASGI)
+- `coffeehouse_common.logging_config` — `RequestIdMiddleware` (raw ASGI), `RequestIdFilter`, `configure_logging`, `get_request_id`
+- `coffeehouse_common.observability` — `init_sentry(app_slug)` Sentry SDK bootstrap; reads `SENTRY_DSN` from env (no-op when unset), tags events with `app_slug`, drops 4xx HTTP/CSRF noise, keeps 5xx
+
+**v0.3.0+** implements security headers and request ID middleware as **raw ASGI** (not `BaseHTTPMiddleware`) so streaming responses are not fully buffered. **v0.3.1** sets `X-Frame-Options: SAMEORIGIN` (same-origin iframes allowed; third-party framing blocked). Logs include a per-request correlation id when `configure_logging()` + `RequestIdMiddleware` are used.
+
+## Install
+
+From GitHub (pinned tag):
+
+```bash
+pip install "coffeehouse-common @ git+https://github.com/rubencfh/coffeehouse-common.git@v0.9.0"
+```
+
+Local editable install:
+
+```bash
+pip install -e ../coffeehouse-common
+```
+
+## Development
+
+Set up the repo for local development + testing:
+
+```bash
+git clone https://github.com/rubencfh/coffeehouse-common.git
+cd coffeehouse-common
+pip install -e ".[testing]"
+pip install -r requirements-dev.txt
+pre-commit install
+```
+
+Run the full test suite (with coverage, fails under 70%):
+
+```bash
+pytest
+```
+
+Run the pre-commit hooks against all files (format, lint, secret scan, syntax check):
+
+```bash
+pre-commit run --all-files
+```
+
+Individual checks:
+
+```bash
+ruff format --check .          # formatting
+ruff check .                   # linting
+mypy coffeehouse_common        # type-checking (lenient baseline)
+bandit -c pyproject.toml -r coffeehouse_common coffeehouse_testing  # SAST
+pip-audit -r requirements-dev.txt                                    # SCA
+```
+
+CI runs the same checks on every push / PR via `.github/workflows/ci.yml`.
+See `coffeehouse-ecosystem/docs/pipeline.md` for the broader pipeline.
+
+### Shared test fixtures
+
+The `coffeehouse_testing` subpackage ships with this repo and provides shared
+pytest fixtures that consumer apps import in their own `tests/conftest.py`:
+
+```python
+from coffeehouse_testing.jwt_factory import jwt_factory
+from coffeehouse_testing.client import authed_client
+from coffeehouse_testing.db import postgres_container, clean_db  # noqa: F401
+from coffeehouse_testing.auth_stub import make_auth_stub, build_roles_manifest
+```
+
+All heavy dependencies (PyJWT, testcontainers, starlette) are loaded lazily —
+import the modules you need in tests and the import errors only fire if the
+underlying package is not installed.
+
+## Usage
+
+```python
+from coffeehouse_common.csrf import CSRFMiddleware
+from coffeehouse_common.logging_config import RequestIdMiddleware, configure_logging
+from coffeehouse_common.observability import init_sentry
+from coffeehouse_common.security_middleware import SecurityHeadersMiddleware
+
+configure_logging()  # once at startup; attaches RequestIdFilter for %(request_id)s
+init_sentry(app_slug="auth")  # no-op if SENTRY_DSN is unset
+```
+
+`init_sentry` reads `SENTRY_DSN`, `RAILWAY_ENVIRONMENT_NAME` (or `ENVIRONMENT`),
+and `RAILWAY_GIT_COMMIT_SHA` from the environment. Errors-only sample rate by
+default (`traces_sample_rate=0.0`). 401/403/404/405 responses, 4xx
+`HTTPException`s, and `CSRFError`s are dropped client-side so they don't burn
+the Sentry quota. 5xx HTTPExceptions and any other exception class are kept.
+Pass `extra_ignored_status_codes=` / `extra_ignored_exceptions=` to extend the
+filter per app.
+
+Explicit dependency: **`itsdangerous`** (CSRF token signing).
+
+See `CONVENTIONS.md` in the `coffeehouse-ecosystem` repo for middleware order and CSRF patterns.
+
+## First-time publish (maintainers)
+
+1. Create an empty repo on GitHub: `rubencfh/coffeehouse-common`
+2. From this directory:
+
+```bash
+git remote add origin https://github.com/rubencfh/coffeehouse-common.git
+git push -u origin master
+git push origin v0.9.0
+```
+
+Until the repo and tag exist, app Docker builds that `pip install` from GitHub will fail. For local dev, use editable install (above).

coffeehouse_common-0.15.1/coffeehouse_common/__init__.py

@@ -0,0 +1,6 @@
+"""Shared middleware, CSRF, flash messages, observability, and role-cleanup for Coffee House FastAPI apps."""
+
+from coffeehouse_common.paths import PathEscapeError as PathEscapeError
+from coffeehouse_common.paths import safe_under as safe_under
+
+__version__ = "0.13.0"

coffeehouse_common-0.15.1/coffeehouse_common/auth_client.py

@@ -0,0 +1,187 @@
+"""Shared Auth Service API client for consumer apps.
+
+Consolidated from identical per-repo ``app/auth_client.py`` modules that existed
+in Grind, Digi, and Beany. Each consumer's module is now a one-line re-export
+shim — the logic lives here.
+
+Exposes two endpoints that consumer admin UIs need:
+
+- :func:`fetch_roles(app_slug)` — live role catalog from
+  ``GET /api/apps/{slug}/roles``, so admin-created roles in Auth UI appear in
+  the consumer's matrix without a redeploy.
+- :func:`fetch_departments()` — live department vocabulary from
+  ``GET /api/departments`` (global, not per-app), for dept-baseline matrix
+  rendering. Added after Auth migration 009 moved ``department`` from role
+  level to user level.
+
+Both endpoints are authenticated with the same ``X-Deploy-Key`` (the consumer's
+``SYNC_ROLES_API_KEY``). Results are cached in-process for
+``CACHE_TTL_SECONDS`` seconds; failures raise :class:`AuthRolesUnavailable` so
+admin matrix pages can render an explicit error banner rather than fall back
+to a stale list. Consumer apps set ``AUTH_INTERNAL_URL`` (server-to-server
+URL, e.g. Docker / Railway internal) or ``AUTH_SERVICE_URL``; the former takes
+precedence when set.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import time
+from copy import deepcopy
+from typing import Any
+
+import requests
+
+_log = logging.getLogger(__name__)
+
+CACHE_TTL_SECONDS = 60
+_cache: dict[str, tuple[float, list[dict[str, Any]]]] = {}
+
+
+class AuthRolesUnavailable(RuntimeError):
+    """Raised when an Auth endpoint cannot be reached or returns non-2xx."""
+
+
+def _sync_roles_api_key() -> str:
+    # Read lazily so tests that monkeypatch os.environ work cleanly.
+    return (os.environ.get("SYNC_ROLES_API_KEY") or "").strip()
+
+
+def _auth_base() -> str:
+    # AUTH_INTERNAL_URL preferred for server-to-server (Docker / Railway);
+    # AUTH_SERVICE_URL for everything else. Trim each candidate before OR-ing
+    # so a whitespace-only AUTH_INTERNAL_URL still falls back to AUTH_SERVICE_URL.
+    internal = (os.environ.get("AUTH_INTERNAL_URL") or "").strip()
+    service = (os.environ.get("AUTH_SERVICE_URL") or "").strip()
+    return (internal or service).rstrip("/")
+
+
+def fetch_roles(app_slug: str, *, include_inactive: bool = False) -> list[dict[str, Any]]:
+    """Return the live role catalog for ``app_slug`` from Auth.
+
+    Results are cached in-process for ``CACHE_TTL_SECONDS``. Raises
+    :class:`AuthRolesUnavailable` on network failure or non-2xx response;
+    callers render an error banner rather than fall back to a stale list.
+    """
+    cache_key = f"roles:{app_slug}:{include_inactive}"
+    now = time.monotonic()
+    cached = _cache.get(cache_key)
+    if cached and now - cached[0] < CACHE_TTL_SECONDS:
+        return deepcopy(cached[1])
+
+    base = _auth_base()
+    if not base:
+        raise AuthRolesUnavailable("AUTH_SERVICE_URL / AUTH_INTERNAL_URL is not configured")
+    api_key = _sync_roles_api_key()
+    if not api_key:
+        raise AuthRolesUnavailable("SYNC_ROLES_API_KEY is not configured")
+
+    url = f"{base}/api/apps/{app_slug}/roles"
+    params = {"include_inactive": "true"} if include_inactive else None
+    try:
+        resp = requests.get(
+            url,
+            params=params,
+            headers={"X-Deploy-Key": api_key},
+            timeout=5,
+        )
+    except requests.RequestException as e:
+        _log.warning("auth_client.fetch_roles: network failure for %s: %s", app_slug, e)
+        raise AuthRolesUnavailable(str(e)) from e
+
+    if resp.status_code >= 400:
+        _log.warning(
+            "auth_client.fetch_roles: %s returned %d: %s",
+            url,
+            resp.status_code,
+            resp.text[:200],
+        )
+        raise AuthRolesUnavailable(f"HTTP {resp.status_code} from Auth")
+
+    try:
+        roles = resp.json()
+    except ValueError as e:
+        _log.warning("auth_client.fetch_roles: invalid JSON from %s: %s", url, e)
+        raise AuthRolesUnavailable("Auth returned invalid JSON") from e
+    if not isinstance(roles, list):
+        raise AuthRolesUnavailable("Auth returned non-list payload")
+    _cache[cache_key] = (now, deepcopy(roles))
+    return roles
+
+
+UNASSIGNED_DEPT_SLUG = "unassigned"
+
+
+def fetch_departments(*, include_unassigned: bool = False) -> list[dict[str, Any]]:
+    """Return the live department catalog from Auth's ``GET /api/departments``.
+
+    Since Auth migration 009 departments are a user-level attribute; role
+    definitions no longer carry ``department``. Consumer admin UIs read the
+    vocabulary directly from this endpoint. Shares the same 60s cache slot +
+    ``X-Deploy-Key`` credential as :func:`fetch_roles`. Raises
+    :class:`AuthRolesUnavailable` on network failure or non-2xx response.
+
+    The ``unassigned`` sentinel dept is excluded by default because consumer
+    runtime code (``get_app_dept`` in each app) maps that slug to ``None`` to
+    deny baseline inheritance to users who haven't been assigned a real dept.
+    Rendering the sentinel alongside real depts in admin matrices created a
+    silent no-op trap: baselines set on the ``unassigned`` row were stored in
+    the DB but never applied at request time. Callers that genuinely need the
+    full list (Auth's own admin UI) pass ``include_unassigned=True``.
+    """
+    cache_key = "departments"
+    now = time.monotonic()
+    cached = _cache.get(cache_key)
+    if cached and now - cached[0] < CACHE_TTL_SECONDS:
+        return _filter_unassigned(deepcopy(cached[1]), include_unassigned)
+
+    base = _auth_base()
+    if not base:
+        raise AuthRolesUnavailable("AUTH_SERVICE_URL / AUTH_INTERNAL_URL is not configured")
+    api_key = _sync_roles_api_key()
+    if not api_key:
+        raise AuthRolesUnavailable("SYNC_ROLES_API_KEY is not configured")
+
+    url = f"{base}/api/departments"
+    try:
+        resp = requests.get(
+            url,
+            headers={"X-Deploy-Key": api_key},
+            timeout=5,
+        )
+    except requests.RequestException as e:
+        _log.warning("auth_client.fetch_departments: network failure: %s", e)
+        raise AuthRolesUnavailable(str(e)) from e
+
+    if resp.status_code >= 400:
+        _log.warning(
+            "auth_client.fetch_departments: %s returned %d: %s",
+            url,
+            resp.status_code,
+            resp.text[:200],
+        )
+        raise AuthRolesUnavailable(f"HTTP {resp.status_code} from Auth")
+
+    try:
+        depts = resp.json()
+    except ValueError as e:
+        _log.warning("auth_client.fetch_departments: invalid JSON from %s: %s", url, e)
+        raise AuthRolesUnavailable("Auth returned invalid JSON") from e
+    if not isinstance(depts, list):
+        raise AuthRolesUnavailable("Auth returned non-list payload")
+    _cache[cache_key] = (now, deepcopy(depts))
+    return _filter_unassigned(depts, include_unassigned)
+
+
+def _filter_unassigned(
+    depts: list[dict[str, Any]], include_unassigned: bool
+) -> list[dict[str, Any]]:
+    if include_unassigned:
+        return list(depts)
+    return [d for d in depts if d.get("slug") != UNASSIGNED_DEPT_SLUG]
+
+
+def invalidate_cache() -> None:
+    """Drop all cached role/department payloads (e.g. after admin edits Auth)."""
+    _cache.clear()

coffeehouse_common-0.15.1/coffeehouse_common/csrf.py

@@ -0,0 +1,162 @@
+"""
+CSRF middleware that accepts the token from form body (HTML forms)
+in addition to the x-csrftoken header (AJAX / HTMX).
+
+Improvements over starlette-csrf's base middleware:
+  1. Reads the token from form data (not just the x-csrftoken header).
+  2. Replays the request body so downstream handlers can read it.
+  3. Detects stale/invalid cookies (e.g. signed with an old secret after
+     a secret-key rotation or environment change) and replaces them.
+  4. Only injects Set-Cookie on http.response.start (not body messages).
+  5. Treats two body-parsing edge cases as expected user-input friction
+     rather than 5xx server bugs:
+       - ``ClientDisconnect`` (client closed the TCP connection mid-POST):
+         abandon the request silently — there is no socket left to reply
+         to. Logged at INFO so it is visible without burning Sentry quota.
+       - ``MultipartParseError`` (malformed multipart body, almost always
+         a scanner / bot probe): respond with 400 instead of bubbling.
+"""
+
+import functools
+import http.cookies
+import logging
+
+from itsdangerous import BadSignature
+from multipart.exceptions import MultipartParseError
+from starlette.datastructures import MutableHeaders
+from starlette.requests import ClientDisconnect, Request
+from starlette.responses import PlainTextResponse
+from starlette.types import Message, Receive, Scope, Send
+from starlette_csrf.middleware import CSRFMiddleware as _Base
+
+logger = logging.getLogger(__name__)
+
+
+class CSRFMiddleware(_Base):
+    def _cookie_is_valid(self, token: str) -> bool:
+        try:
+            self.serializer.loads(token)
+            return True
+        except (BadSignature, Exception):
+            return False
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        # CSRF only applies to HTTP requests. WebSocket has its own origin
+        # check during the handshake, and lifespan has no client at all.
+        # `Request(scope, receive)` below asserts scope["type"] == "http"; if
+        # we let any other scope through, we crash the connection (Sentry
+        # COFFEEHOUSE-BEANY-1: AssertionError on /ws/socket.io/ in Chainlit).
+        if scope["type"] != "http":
+            await self.app(scope, receive, send)
+            return
+
+        request = Request(scope, receive)
+        csrf_cookie = request.cookies.get(self.cookie_name)
+
+        if self._url_is_required(request.url) or (
+            request.method not in self.safe_methods
+            and not self._url_is_exempt(request.url)
+            and self._has_sensitive_cookies(request.cookies)
+        ):
+            try:
+                body = await request.body()
+                submitted_csrf_token = await self._get_submitted_csrf_token(request)
+            except ClientDisconnect:
+                # Client closed the connection before the body finished
+                # transferring. The socket is gone — there's no client left
+                # to send a 400/500 to, so we abandon the request without
+                # propagating the exception. Logged at INFO so the event is
+                # visible in container logs without filling the Sentry quota
+                # (before_send filter cannot see this — it never reaches
+                # sentry_sdk because we don't re-raise).
+                logger.info(
+                    "csrf middleware: client disconnected before body read complete "
+                    "(method=%s url=%s)",
+                    request.method,
+                    request.url,
+                )
+                return
+            except MultipartParseError as exc:
+                # Malformed multipart body — almost always a scanner probing
+                # the public POST surface. Reply 400 rather than bubbling a
+                # 500 to the error middleware (and Sentry). Inline the
+                # response construction so the local `response` name doesn't
+                # leak into the outer scope (mypy would then narrow it to
+                # PlainTextResponse and reject the later Response assignment
+                # in the token-mismatch branch below).
+                logger.info(
+                    "csrf middleware: malformed multipart body (method=%s url=%s err=%s)",
+                    request.method,
+                    request.url,
+                    exc,
+                )
+                await PlainTextResponse("Invalid request body", status_code=400)(
+                    scope, receive, send
+                )
+                return
+
+            if (
+                not csrf_cookie
+                or not submitted_csrf_token
+                or not self._csrf_tokens_match(csrf_cookie, submitted_csrf_token)
+            ):
+                response = self._get_error_response(request)
+                error_send = functools.partial(
+                    self._send_with_refresh,
+                    send=send,
+                    scope=scope,
+                )
+                await response(scope, receive, error_send)
+                return
+
+            async def replay_receive() -> Message:
+                return {"type": "http.request", "body": body, "more_body": False}
+
+            receive = replay_receive
+
+        send = functools.partial(self._send_with_refresh, send=send, scope=scope)
+        await self.app(scope, receive, send)
+
+    async def _send_with_refresh(
+        self,
+        message: Message,
+        *,
+        send: Send,
+        scope: Scope,
+    ) -> None:
+        if message.get("type") == "http.response.start":
+            request = Request(scope)
+            csrf_cookie = request.cookies.get(self.cookie_name)
+
+            needs_new = csrf_cookie is None or not self._cookie_is_valid(csrf_cookie)
+            if needs_new:
+                message.setdefault("headers", [])
+                headers = MutableHeaders(scope=message)
+                cookie: http.cookies.BaseCookie[str] = http.cookies.SimpleCookie()
+                name = self.cookie_name
+                cookie[name] = self._generate_csrf_token()
+                cookie[name]["path"] = self.cookie_path
+                cookie[name]["secure"] = self.cookie_secure
+                cookie[name]["httponly"] = self.cookie_httponly
+                cookie[name]["samesite"] = self.cookie_samesite
+                if self.cookie_domain is not None:
+                    cookie[name]["domain"] = self.cookie_domain
+                headers.append("set-cookie", cookie.output(header="").strip())
+
+        await send(message)
+
+    async def _get_submitted_csrf_token(self, request: Request) -> str | None:
+        token = request.headers.get(self.header_name)
+        if token:
+            return token
+        content_type = request.headers.get("content-type", "")
+        if (
+            "application/x-www-form-urlencoded" in content_type
+            or "multipart/form-data" in content_type
+        ):
+            form = await request.form()
+            value = form.get(self.cookie_name)
+            # form.get() can return UploadFile, str, or None. Only accept strings
+            # (an UploadFile "csrftoken" is nonsensical and should be rejected).
+            return value if isinstance(value, str) else None
+        return None