plain 0.68.0__py3-none-any.whl → 0.101.2__py3-none-any.whl

plain/csrf/README.md

@@ -1,26 +1,44 @@
-# CSRF
+# plain.csrf
 
 **Cross-Site Request Forgery (CSRF) protection using modern request headers.**
 
 - [Overview](#overview)
-- [Usage](#usage)
-- [CSRF Exempt Paths](#csrf-exempt-paths)
-- [Trusted Origins](#trusted-origins)
+- [How it works](#how-it-works)
+- [Exempt paths](#exempt-paths)
+- [Trusted origins](#trusted-origins)
+- [FAQs](#faqs)
+- [Installation](#installation)
 
 ## Overview
 
-Plain provides modern CSRF protection based on [Filippo Valsorda's 2025 research](https://words.filippo.io/csrf/) using `Sec-Fetch-Site` headers and origin validation.
+Plain provides modern CSRF protection based on [Filippo Valsorda's 2025 research](https://words.filippo.io/csrf/) using `Sec-Fetch-Site` headers and origin validation. The protection is automatic and requires no changes to your forms or templates.
 
-## Usage
+The [`CsrfViewMiddleware`](./middleware.py#CsrfViewMiddleware) runs on every request and blocks cross-origin `POST`, `PUT`, `PATCH`, and `DELETE` requests. Safe methods like `GET`, `HEAD`, and `OPTIONS` are always allowed.
 
-The `CsrfViewMiddleware` is [automatically installed](../internal/handlers/base.py#BUILTIN_BEFORE_MIDDLEWARE) and works transparently. **No changes to your forms or templates are needed.**
+## How it works
 
-## CSRF Exempt Paths
+The middleware uses a layered approach to validate requests:
 
-In some cases, you may need to disable CSRF protection for specific paths (like API endpoints or webhooks). Configure exempt paths using regex patterns in your settings:
+1. **Safe methods pass through** - `GET`, `HEAD`, and `OPTIONS` requests are always allowed since they should not modify server state.
+
+2. **Exempt paths skip validation** - Paths matching patterns in `CSRF_EXEMPT_PATHS` bypass all CSRF checks.
+
+3. **Trusted origins are allowed** - Requests from origins in `CSRF_TRUSTED_ORIGINS` pass through.
+
+4. **Sec-Fetch-Site header check** - Modern browsers send this header indicating the request origin:
+    - `same-origin` or `none`: Allowed (request came from your site or was user-initiated)
+    - `cross-site` or `same-site`: Blocked (request came from another domain or subdomain)
+
+5. **Origin header fallback** - For older browsers without `Sec-Fetch-Site`, the middleware compares the `Origin` header against the request's `Host`.
+
+6. **Non-browser requests pass** - Requests without either header (like curl or API clients) are allowed since they are not subject to browser CSRF attacks.
+
+## Exempt paths
+
+You can disable CSRF protection for specific paths using regex patterns. This is useful for API endpoints, webhooks, or health checks that receive requests from external services.
 
 ```python
-# settings.py
+# app/settings.py
 CSRF_EXEMPT_PATHS = [
     r"^/api/",             # All API endpoints
     r"^/api/v\d+/",        # Versioned APIs: /api/v1/, /api/v2/, etc.
@@ -30,41 +48,22 @@ CSRF_EXEMPT_PATHS = [
 ]
 ```
 
-**Pattern Matching**: Exempt paths use Python regex patterns with `re.search()` against the full URL path including the leading slash.
-
-**Examples:**
+Patterns use Python regex with `re.search()` against the full URL path including the leading slash.
 
-- `r"^/api/"` - matches `/api/users/`, `/api/posts/`
-- `r"/webhooks/.*"` - matches `/webhooks/github/push`, `/webhooks/stripe/payment`
-- `r"/health$"` - matches `/health` but not `/health-check`
-- `r"^/api/v\d+/"` - matches `/api/v1/users/`, `/api/v2/posts/`
+**Pattern examples:**
 
-**Common Use Cases:**
+| Pattern           | Matches                      | Does not match  |
+| ----------------- | ---------------------------- | --------------- |
+| `r"^/api/"`       | `/api/users/`, `/api/posts/` | `/v2/api/`      |
+| `r"/webhooks/.*"` | `/webhooks/github/push`      | `/webhook/`     |
+| `r"/health$"`     | `/health`                    | `/health-check` |
 
-```python
-CSRF_EXEMPT_PATHS = [
-    # API endpoints (often consumed by JavaScript/mobile apps)
-    r"^/api/",
-
-    # Webhooks (external services posting data)
-    r"/webhooks/.*",
-
-    # Health checks and monitoring
-    r"/health$",
-    r"/status$",
-    r"/metrics$",
-
-    # File uploads (if using direct POST)
-    r"/upload/",
-]
-```
+## Trusted origins
 
-## Trusted Origins
-
-In some cases, you may need to allow requests from specific external origins (like API clients or mobile apps). You can configure trusted origins in your settings:
+You can allow requests from specific external origins that you trust completely.
 
 ```python
-# settings.py
+# app/settings.py
 CSRF_TRUSTED_ORIGINS = [
     "https://api.example.com",
     "https://mobile.example.com:8443",
@@ -72,4 +71,30 @@ CSRF_TRUSTED_ORIGINS = [
 ]
 ```
 
-**Important**: Trusted origins bypass **all** CSRF protection. Only add origins you completely trust, as they can make requests that appear to come from your users.
+Each origin should be a full URL with scheme (e.g., `https://example.com`). Include the port if it's non-standard.
+
+**Warning**: Trusted origins bypass all CSRF protection. Only add origins you completely control or trust, as they can make requests that appear to come from your users.
+
+## FAQs
+
+#### Why does Plain use Sec-Fetch-Site instead of CSRF tokens?
+
+Token-based CSRF protection requires embedding tokens in forms and validating them on the server. This adds complexity to your templates and requires careful handling of token rotation. Modern browsers provide the `Sec-Fetch-Site` header which tells the server whether a request is same-origin, making tokens unnecessary. The header approach is simpler, more reliable, and cannot be leaked through XSS vulnerabilities like tokens can.
+
+#### What about HTTP sites during development?
+
+The `Sec-Fetch-Site` header is only sent by browsers to HTTPS and localhost origins. For development on localhost, CSRF protection works normally. For HTTP origins on other hosts, the middleware falls back to `Origin` header validation.
+
+#### Why are same-site requests (like subdomains) blocked?
+
+Plain uses same-origin protection rather than same-site protection. Subdomains can have different trust levels than your main domain. For example, `user-content.example.com` should not be able to make authenticated requests to `app.example.com`. If you need to allow requests from a subdomain, add it to `CSRF_TRUSTED_ORIGINS`.
+
+#### How do I debug CSRF rejections?
+
+When a request is rejected, the middleware raises a `SuspiciousOperationError400` with a detailed message explaining why. Check your server logs for messages like "CSRF rejected: Cross-origin request from Sec-Fetch-Site: cross-site" to understand the cause.
+
+## Installation
+
+This module is included with the `plain` package and enabled by default. No additional installation or configuration is required.
+
+The middleware is automatically added to the request handling pipeline through [`BUILTIN_BEFORE_MIDDLEWARE`](../internal/handlers/base.py#BUILTIN_BEFORE_MIDDLEWARE).

plain/csrf/middleware.py

@@ -1,16 +1,18 @@
-import logging
+from __future__ import annotations
+
 import re
+from collections.abc import Callable
+from typing import TYPE_CHECKING
 from urllib.parse import urlparse
 
-from plain.logs.utils import log_response
+from plain.http import HttpMiddleware, SuspiciousOperationError400
 from plain.runtime import settings
 
-from .views import CsrfFailureView
-
-logger = logging.getLogger("plain.security.csrf")
+if TYPE_CHECKING:
+    from plain.http import Request, Response
 
 
-class CsrfViewMiddleware:
+class CsrfViewMiddleware(HttpMiddleware):
     """
     Modern CSRF protection middleware using Sec-Fetch-Site headers and origin validation.
     Based on Filippo Valsorda's 2025 research (https://words.filippo.io/csrf/).
@@ -19,31 +21,33 @@ class CsrfViewMiddleware:
     like subdomains can have different trust levels and are rejected.
     """
 
-    def __init__(self, get_response):
-        self.get_response = get_response
+    def __init__(self, get_response: Callable[[Request], Response]):
+        super().__init__(get_response)
 
         # Compile CSRF exempt patterns once for performance
-        self.csrf_exempt_patterns = [re.compile(r) for r in settings.CSRF_EXEMPT_PATHS]
+        self.csrf_exempt_patterns: list[re.Pattern[str]] = [
+            re.compile(r) for r in settings.CSRF_EXEMPT_PATHS
+        ]
 
-    def __call__(self, request):
+    def process_request(self, request: Request) -> Response:
         allowed, reason = self.should_allow_request(request)
 
-        if allowed:
-            return self.get_response(request)
-        else:
-            return self.reject(request, reason)
+        if not allowed:
+            raise SuspiciousOperationError400(reason)
 
-    def should_allow_request(self, request) -> tuple[bool, str]:
+        return self.get_response(request)
+
+    def should_allow_request(self, request: Request) -> tuple[bool, str]:
         # 1. Allow safe methods (GET, HEAD, OPTIONS)
         if request.method in ("GET", "HEAD", "OPTIONS"):
-            return True, f"Safe HTTP method: {request.method}"
+            return True, f"CSRF allowed: Safe HTTP method: {request.method}"
 
         # 2. Path-based exemption (regex patterns)
         for pattern in self.csrf_exempt_patterns:
             if pattern.search(request.path_info):
                 return (
                     True,
-                    f"Path {request.path_info} matches exempt pattern {pattern.pattern}",
+                    f"CSRF allowed: Path {request.path_info} matches exempt pattern {pattern.pattern}",
                 )
 
         origin = request.headers.get("Origin")
@@ -52,25 +56,25 @@ class CsrfViewMiddleware:
         # 3. Check trusted origins allow-list
 
         if origin and origin in settings.CSRF_TRUSTED_ORIGINS:
-            return True, f"Trusted origin: {origin}"
+            return True, f"CSRF allowed: Trusted origin: {origin}"
 
         # 4. Primary protection: Check Sec-Fetch-Site header
         if sec_fetch_site in ("same-origin", "none"):
             return (
                 True,
-                f"Same-origin request from Sec-Fetch-Site: {sec_fetch_site}",
+                f"CSRF allowed: Same-origin request from Sec-Fetch-Site: {sec_fetch_site}",
             )
         elif sec_fetch_site in ("cross-site", "same-site"):
             return (
                 False,
-                f"Cross-origin request detected from Sec-Fetch-Site: {sec_fetch_site}",
+                f"CSRF rejected: Cross-origin request from Sec-Fetch-Site: {sec_fetch_site}",
             )
 
         # 5. No fetch metadata or Origin headers - allow (non-browser requests)
         if not origin and not sec_fetch_site:
             return (
                 True,
-                "No Origin or Sec-Fetch-Site header - likely non-browser or old browser",
+                "CSRF allowed: No Origin or Sec-Fetch-Site header - likely non-browser or old browser",
             )
 
         # 6. Fallback: Origin vs Host comparison for older browsers
@@ -78,7 +82,7 @@ class CsrfViewMiddleware:
         # (Origin shows :443, request sees :80 if TLS terminated upstream).
         # HSTS helps here; otherwise add external origins to CSRF_TRUSTED_ORIGINS.
         if origin == "null":
-            return False, "Cross-origin request detected - null Origin header"
+            return False, "CSRF rejected: Null Origin header"
 
         if (parsed_origin := urlparse(origin)) and (host := request.host):
             try:
@@ -101,33 +105,39 @@ class CsrfViewMiddleware:
                 # Compare hostname and port (scheme-agnostic)
                 # Both origin_host and request_host are normalized by urlparse (IPv6 brackets stripped)
                 if origin_host and origin_port and request_host and request_port:
-                    if (
-                        origin_host.lower() == request_host.lower()
-                        and origin_port == int(request_port)
-                    ):
+                    host_match = origin_host.lower() == request_host.lower()
+                    port_match = origin_port == int(request_port)
+
+                    if host_match and port_match:
                         return (
                             True,
-                            f"Same-origin request - Origin {origin} matches Host {host}",
+                            f"CSRF allowed: Same-origin request - Origin {origin} matches Host {host}",
+                        )
+
+                    # Build detailed error message based on what mismatched
+                    if host_match:
+                        # Port mismatch only - show ports since they're relevant
+                        return (
+                            False,
+                            f"CSRF rejected: Origin {origin_host}:{origin_port} does not match Host {request_host}:{request_port} (port mismatch)",
+                        )
+                    elif port_match:
+                        # Host mismatch only - no need to show ports
+                        return (
+                            False,
+                            f"CSRF rejected: Origin {origin_host} does not match Host {request_host}",
+                        )
+                    else:
+                        # Both mismatch - show full details
+                        return (
+                            False,
+                            f"CSRF rejected: Origin {origin_host}:{origin_port} does not match Host {request_host}:{request_port}",
                         )
             except ValueError:
                 pass
 
-        # Origin present but doesn't match host
+        # Origin present but couldn't parse/compare properly
         return (
             False,
-            f"Cross-origin request detected - Origin {origin} does not match Host",
-        )
-
-    def reject(self, request, reason):
-        """Reject a request with a 403 Forbidden response."""
-
-        response = CsrfFailureView.as_view()(request, reason=reason)
-        log_response(
-            "Forbidden (%s): %s",
-            reason,
-            request.path,
-            response=response,
-            request=request,
-            logger=logger,
+            f"CSRF rejected: Origin {origin} could not be validated against Host {request.host}",
         )
-        return response

plain/debug.py

@@ -1,4 +1,7 @@
+from __future__ import annotations
+
 from pprint import pformat
+from typing import Any, NoReturn
 
 from markupsafe import Markup, escape
 
@@ -6,7 +9,7 @@ from plain.http import Response
 from plain.views.exceptions import ResponseException
 
 
-def dd(*objs):
+def dd(*objs: Any) -> NoReturn:
     """
     Dump and die.
 
@@ -25,5 +28,5 @@ def dd(*objs):
     response = Response()
     response.status_code = 500
     response.content = combined_dump_str
-    response.content_type = "text/html"
+    response.headers["Content-Type"] = "text/html"
     raise ResponseException(response)

plain/exceptions.py

@@ -2,11 +2,15 @@
 Global Plain exception and warning classes.
 """
 
+from __future__ import annotations
+
 import operator
+from collections.abc import Iterator
+from typing import Any
 
 from plain.utils.hashable import make_hashable
 
-# MARK: Configuration and Registry
+# MARK: Configuration and Package Registry
 
 
 class PackageRegistryNotReady(Exception):
@@ -21,94 +25,6 @@ class ImproperlyConfigured(Exception):
     pass
 
 
-# MARK: Model and Field Errors
-
-
-class FieldDoesNotExist(Exception):
-    """The requested model field does not exist"""
-
-    pass
-
-
-class FieldError(Exception):
-    """Some kind of problem with a model field."""
-
-    pass
-
-
-class ObjectDoesNotExist(Exception):
-    """The requested object does not exist"""
-
-    pass
-
-
-class MultipleObjectsReturned(Exception):
-    """The query returned multiple objects when only one was expected."""
-
-    pass
-
-
-# MARK: Security and Suspicious Operations
-
-
-class SuspiciousOperation(Exception):
-    """The user did something suspicious"""
-
-
-class SuspiciousMultipartForm(SuspiciousOperation):
-    """Suspect MIME request in multipart form data"""
-
-    pass
-
-
-class SuspiciousFileOperation(SuspiciousOperation):
-    """A Suspicious filesystem operation was attempted"""
-
-    pass
-
-
-class TooManyFieldsSent(SuspiciousOperation):
-    """
-    The number of fields in a GET or POST request exceeded
-    settings.DATA_UPLOAD_MAX_NUMBER_FIELDS.
-    """
-
-    pass
-
-
-class TooManyFilesSent(SuspiciousOperation):
-    """
-    The number of fields in a GET or POST request exceeded
-    settings.DATA_UPLOAD_MAX_NUMBER_FILES.
-    """
-
-    pass
-
-
-class RequestDataTooBig(SuspiciousOperation):
-    """
-    The size of the request (excluding any file uploads) exceeded
-    settings.DATA_UPLOAD_MAX_MEMORY_SIZE.
-    """
-
-    pass
-
-
-# MARK: HTTP and Request Errors
-
-
-class BadRequest(Exception):
-    """The request is malformed and cannot be processed."""
-
-    pass
-
-
-class PermissionDenied(Exception):
-    """The user did not have permission to do that"""
-
-    pass
-
-
 # MARK: Validation
 
 NON_FIELD_ERRORS = "__all__"
@@ -117,7 +33,12 @@ NON_FIELD_ERRORS = "__all__"
 class ValidationError(Exception):
     """An error while validating data."""
 
-    def __init__(self, message, code=None, params=None):
+    def __init__(
+        self,
+        message: str | list[Any] | dict[str, Any] | ValidationError,
+        code: str | None = None,
+        params: dict[str, Any] | None = None,
+    ):
         """
         The `message` argument can be a single error, a list of errors, or a
         dictionary that maps field names to lists of errors. What we define as
@@ -161,12 +82,14 @@ class ValidationError(Exception):
             self.error_list = [self]
 
     @property
-    def messages(self):
+    def messages(self) -> list[str]:
         if hasattr(self, "error_dict"):
-            return sum(dict(self).values(), [])
+            return sum(dict(self).values(), [])  # type: ignore[arg-type]
         return list(self)
 
-    def update_error_dict(self, error_dict):
+    def update_error_dict(
+        self, error_dict: dict[str, list[ValidationError]]
+    ) -> dict[str, list[ValidationError]]:
         if hasattr(self, "error_dict"):
             for field, error_list in self.error_dict.items():
                 error_dict.setdefault(field, []).extend(error_list)
@@ -174,7 +97,7 @@ class ValidationError(Exception):
             error_dict.setdefault(NON_FIELD_ERRORS, []).extend(self.error_list)
         return error_dict
 
-    def __iter__(self):
+    def __iter__(self) -> Iterator[tuple[str, list[str]] | str]:
         if hasattr(self, "error_dict"):
             for field, errors in self.error_dict.items():
                 yield field, list(ValidationError(errors))
@@ -185,20 +108,20 @@ class ValidationError(Exception):
                     message %= error.params
                 yield str(message)
 
-    def __str__(self):
+    def __str__(self) -> str:
         if hasattr(self, "error_dict"):
-            return repr(dict(self))
+            return repr(dict(self))  # type: ignore[arg-type]
         return repr(list(self))
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         return f"ValidationError({self})"
 
-    def __eq__(self, other):
+    def __eq__(self, other: object) -> bool:
         if not isinstance(other, ValidationError):
             return NotImplemented
         return hash(self) == hash(other)
 
-    def __hash__(self):
+    def __hash__(self) -> int:
         if hasattr(self, "message"):
             return hash(
                 (
@@ -210,18 +133,3 @@ class ValidationError(Exception):
         if hasattr(self, "error_dict"):
             return hash(make_hashable(self.error_dict))
         return hash(tuple(sorted(self.error_list, key=operator.attrgetter("message"))))
-
-
-# MARK: Database
-
-
-class EmptyResultSet(Exception):
-    """A database query predicate is impossible."""
-
-    pass
-
-
-class FullResultSet(Exception):
-    """A database query predicate is matches everything."""
-
-    pass