plain 0.57.0__tar.gz → 0.58.0__tar.gz

{plain-0.57.0 → plain-0.58.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plain
-Version: 0.57.0
+Version: 0.58.0
 Summary: A web framework for building products with Python.
 Author-email: Dave Gaeddert <dave.gaeddert@dropseed.dev>
 License-File: LICENSE

{plain-0.57.0 → plain-0.58.0}/plain/CHANGELOG.md

@@ -1,5 +1,20 @@
 # plain changelog
 
+## [0.58.0](https://github.com/dropseed/plain/releases/plain@0.58.0) (2025-08-19)
+
+### What's changed
+
+- Complete rewrite of CSRF protection using modern Sec-Fetch-Site headers and origin validation ([955150800c](https://github.com/dropseed/plain/commit/955150800c))
+- Replaced CSRF view mixin with path-based exemptions using `CSRF_EXEMPT_PATHS` setting ([2a50a9154e](https://github.com/dropseed/plain/commit/2a50a9154e))
+- Renamed `HTTPS_REDIRECT_EXEMPT` to `HTTPS_REDIRECT_EXEMPT_PATHS` with leading slash requirement ([b53d3bb7a7](https://github.com/dropseed/plain/commit/b53d3bb7a7))
+- Agent commands now print prompts directly when running in Claude Code or Codex Sandbox environments ([6eaed8ae3b](https://github.com/dropseed/plain/commit/6eaed8ae3b))
+
+### Upgrade instructions
+
+- Remove any usage of `CsrfExemptViewMixin` and `request.csrf_exempt` and add exempt paths to the `CSRF_EXEMPT_PATHS` setting instead (ex. `CSRF_EXEMPT_PATHS = [r"^/api/", r"/webhooks/.*"]` -- but consider first whether the view still needs CSRF exemption under the new implementation)
+- Replace `HTTPS_REDIRECT_EXEMPT` with `HTTPS_REDIRECT_EXEMPT_PATHS` and ensure patterns include leading slash (ex. `[r"^/health$", r"/api/internal/.*"]`)
+- Remove all CSRF cookie and token related settings - the new implementation doesn't use cookies or tokens (ex. `{{ csrf_input }}` and `{{ csrf_token }}`)
+
 ## [0.57.0](https://github.com/dropseed/plain/releases/plain@0.57.0) (2025-08-15)
 
 ### What's changed

{plain-0.57.0 → plain-0.58.0}/plain/cli/agent.py

@@ -1,3 +1,4 @@
+import os
 import shlex
 import subprocess
 
@@ -20,6 +21,11 @@ def prompt_agent(
         True if the agent command succeeded (or no agent command was provided),
         False if the agent command failed.
     """
+    # Check if running inside an agent and just print the prompt if so
+    if os.environ.get("CLAUDECODE") or os.environ.get("CODEX_SANDBOX"):
+        click.echo(prompt)
+        return True
+
     if print_only or not agent_command:
         click.echo(prompt)
         if not print_only:

plain-0.58.0/plain/csrf/README.md

@@ -0,0 +1,75 @@
+# 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)
+
+## 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.
+
+## Usage
+
+The `CsrfViewMiddleware` is [automatically installed](../internal/handlers/base.py#BUILTIN_BEFORE_MIDDLEWARE) and works transparently. **No changes to your forms or templates are needed.**
+
+## CSRF Exempt Paths
+
+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:
+
+```python
+# settings.py
+CSRF_EXEMPT_PATHS = [
+    r"^/api/",             # All API endpoints
+    r"^/api/v\d+/",        # Versioned APIs: /api/v1/, /api/v2/, etc.
+    r"/webhooks/.*",       # All webhook paths
+    r"/webhooks/github/",  # Specific webhook
+    r"/health$",           # Exact match for /health endpoint
+]
+```
+
+**Pattern Matching**: Exempt paths use Python regex patterns with `re.search()` against the full URL path including the leading slash.
+
+**Examples:**
+
+- `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/`
+
+**Common Use Cases:**
+
+```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
+
+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:
+
+```python
+# settings.py
+CSRF_TRUSTED_ORIGINS = [
+    "https://api.example.com",
+    "https://mobile.example.com:8443",
+    "https://trusted-partner.com",
+]
+```
+
+**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.

plain-0.58.0/plain/csrf/middleware.py

@@ -0,0 +1,134 @@
+import logging
+import re
+from urllib.parse import urlparse
+
+from plain.exceptions import DisallowedHost
+from plain.logs import log_response
+from plain.runtime import settings
+
+from .views import CsrfFailureView
+
+logger = logging.getLogger("plain.security.csrf")
+
+
+class CsrfViewMiddleware:
+    """
+    Modern CSRF protection middleware using Sec-Fetch-Site headers and origin validation.
+    Based on Filippo Valsorda's 2025 research (https://words.filippo.io/csrf/).
+
+    Note: This provides same-origin (not same-site) protection. Same-site origins
+    like subdomains can have different trust levels and are rejected.
+    """
+
+    def __init__(self, get_response):
+        self.get_response = get_response
+
+        # Compile CSRF exempt patterns once for performance
+        self.csrf_exempt_patterns = [re.compile(r) for r in settings.CSRF_EXEMPT_PATHS]
+
+    def __call__(self, request):
+        allowed, reason = self.should_allow_request(request)
+
+        if allowed:
+            return self.get_response(request)
+        else:
+            return self.reject(request, reason)
+
+    def should_allow_request(self, 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}"
+
+        # 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}",
+                )
+
+        origin = request.headers.get("Origin")
+        sec_fetch_site = request.headers.get("Sec-Fetch-Site", "").lower()
+
+        # 3. Check trusted origins allow-list
+
+        if origin and origin in settings.CSRF_TRUSTED_ORIGINS:
+            return True, f"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}",
+            )
+        elif sec_fetch_site in ("cross-site", "same-site"):
+            return (
+                False,
+                f"Cross-origin request detected 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",
+            )
+
+        # 6. Fallback: Origin vs Host comparison for older browsers
+        # Note: On pre-2023 browsers, HTTP→HTTPS transitions may cause mismatches
+        # (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"
+
+        try:
+            if (parsed_origin := urlparse(origin)) and (host := request.get_host()):
+                # Scheme-agnostic host:port comparison
+                origin_host = parsed_origin.hostname
+                origin_port = parsed_origin.port or (
+                    80
+                    if parsed_origin.scheme == "http"
+                    else 443
+                    if parsed_origin.scheme == "https"
+                    else None
+                )
+
+                # Extract hostname from request host (similar to how we parse origin)
+                # Use a fake scheme since we only care about host parsing
+                parsed_host = urlparse(f"http://{host}")
+                request_host = parsed_host.hostname or host
+                request_port = request.get_port()
+
+                # 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)
+                    ):
+                        return (
+                            True,
+                            f"Same-origin request - Origin {origin} matches Host {host}",
+                        )
+        except (ValueError, DisallowedHost):
+            pass
+
+        # Origin present but doesn't match host
+        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,
+        )
+        return response

{plain-0.57.0 → plain-0.58.0}/plain/exceptions.py

@@ -6,6 +6,23 @@ import operator
 
 from plain.utils.hashable import make_hashable
 
+# MARK: Configuration and Registry
+
+
+class PackageRegistryNotReady(Exception):
+    """The plain.packages registry is not populated yet"""
+
+    pass
+
+
+class ImproperlyConfigured(Exception):
+    """Plain is somehow improperly configured"""
+
+    pass
+
+
+# MARK: Model and Field Errors
+
 
 class FieldDoesNotExist(Exception):
     """The requested model field does not exist"""
@@ -13,8 +30,8 @@ class FieldDoesNotExist(Exception):
     pass
 
 
-class PackageRegistryNotReady(Exception):
-    """The plain.packages registry is not populated yet"""
+class FieldError(Exception):
+    """Some kind of problem with a model field."""
 
     pass
 
@@ -31,6 +48,9 @@ class MultipleObjectsReturned(Exception):
     pass
 
 
+# MARK: Security and Suspicious Operations
+
+
 class SuspiciousOperation(Exception):
     """The user did something suspicious"""
 
@@ -80,6 +100,9 @@ class RequestDataTooBig(SuspiciousOperation):
     pass
 
 
+# MARK: HTTP and Request Errors
+
+
 class BadRequest(Exception):
     """The request is malformed and cannot be processed."""
 
@@ -92,17 +115,7 @@ class PermissionDenied(Exception):
     pass
 
 
-class ImproperlyConfigured(Exception):
-    """Plain is somehow improperly configured"""
-
-    pass
-
-
-class FieldError(Exception):
-    """Some kind of problem with a model field."""
-
-    pass
-
+# MARK: Validation
 
 NON_FIELD_ERRORS = "__all__"
 
@@ -205,6 +218,9 @@ class ValidationError(Exception):
         return hash(tuple(sorted(self.error_list, key=operator.attrgetter("message"))))
 
 
+# MARK: Database
+
+
 class EmptyResultSet(Exception):
     """A database query predicate is impossible."""
 

{plain-0.57.0 → plain-0.58.0}/plain/forms/README.md

@@ -33,8 +33,6 @@ Then in your template, you can render the form fields.
 {% block content %}
 
 <form method="post">
-    {{ csrf_input }}
-
     <!-- Render general form errors -->
     {% for error in form.non_field_errors %}
     <div>{{ error }}</div>

{plain-0.57.0 → plain-0.58.0}/plain/internal/middleware/https.py

@@ -12,7 +12,7 @@ class HttpsRedirectMiddleware:
         self.https_redirect_enabled = settings.HTTPS_REDIRECT_ENABLED
         self.https_redirect_host = settings.HTTPS_REDIRECT_HOST
         self.https_redirect_exempt = [
-            re.compile(r) for r in settings.HTTPS_REDIRECT_EXEMPT
+            re.compile(r) for r in settings.HTTPS_REDIRECT_EXEMPT_PATHS
         ]
 
     def __call__(self, request):
@@ -26,11 +26,13 @@ class HttpsRedirectMiddleware:
         return self.get_response(request)
 
     def maybe_https_redirect(self, request):
-        path = request.path.lstrip("/")
         if (
             self.https_redirect_enabled
             and not request.is_https()
-            and not any(pattern.search(path) for pattern in self.https_redirect_exempt)
+            and not any(
+                pattern.search(request.path_info)
+                for pattern in self.https_redirect_exempt
+            )
         ):
             host = self.https_redirect_host or request.get_host()
             return ResponseRedirect(

{plain-0.57.0 → plain-0.58.0}/plain/runtime/global_settings.py

@@ -3,31 +3,20 @@ Default Plain settings. Override these with settings in the module pointed to
 by the PLAIN_SETTINGS_MODULE environment variable.
 """
 
-####################
-# CORE             #
-####################
+# MARK: Core Settings
 
 DEBUG: bool = False
 
-# Hosts/domain names that are valid for this site.
-# "*" matches anything, ".example.com" matches example.com and all subdomains
-ALLOWED_HOSTS: list[str] = []
-
-# Local time zone for this installation. All choices can be found here:
-# https://en.wikipedia.org/wiki/List_of_tz_zones_by_name (although not all
-# systems may support all possibilities). This is interpreted as the default
-# user time zone.
-TIME_ZONE: str = "UTC"
-
-# Default charset to use for all Response objects, if a MIME type isn't
-# manually specified. It's used to construct the Content-Type header.
-DEFAULT_CHARSET = "utf-8"
-
 # List of strings representing installed packages.
 INSTALLED_PACKAGES: list[str] = []
 
-# Whether to append trailing slashes to URLs.
-APPEND_SLASH = True
+URLS_ROUTER: str
+
+# MARK: HTTP and Security
+
+# Hosts/domain names that are valid for this site.
+# "*" matches anything, ".example.com" matches example.com and all subdomains
+ALLOWED_HOSTS: list[str] = []
 
 # Default headers for all responses.
 DEFAULT_RESPONSE_HEADERS = {
@@ -42,7 +31,13 @@ DEFAULT_RESPONSE_HEADERS = {
 
 # Whether to redirect all non-HTTPS requests to HTTPS.
 HTTPS_REDIRECT_ENABLED = True
-HTTPS_REDIRECT_EXEMPT = []
+
+# Regex patterns for paths that should be exempt from HTTPS redirect
+# Examples: [r"^/health$", r"/api/internal/.*", r"/dev/.*"]
+HTTPS_REDIRECT_EXEMPT_PATHS: list[str] = []
+
+# Custom host to redirect to for HTTPS. If None, uses the same host as the request.
+# Useful for redirecting to a different domain (e.g., "secure.example.com")
 HTTPS_REDIRECT_HOST = None
 
 # If your Plain app is behind a proxy that sets a header to specify secure
@@ -68,7 +63,24 @@ SECRET_KEY: str
 # secret key rotation.
 SECRET_KEY_FALLBACKS: list[str] = []
 
-URLS_ROUTER: str
+# MARK: Internationalization
+
+# Local time zone for this installation. All choices can be found here:
+# https://en.wikipedia.org/wiki/List_of_tz_zones_by_name (although not all
+# systems may support all possibilities). This is interpreted as the default
+# user time zone.
+TIME_ZONE: str = "UTC"
+
+# Default charset to use for all Response objects, if a MIME type isn't
+# manually specified. It's used to construct the Content-Type header.
+DEFAULT_CHARSET = "utf-8"
+
+# MARK: URL Configuration
+
+# Whether to append trailing slashes to URLs.
+APPEND_SLASH = True
+
+# MARK: File Uploads
 
 # List of upload handler classes to be applied in order.
 FILE_UPLOAD_HANDLERS = [
@@ -100,41 +112,30 @@ FILE_UPLOAD_TEMP_DIR = None
 # User-defined overrides for error views by status code
 HTTP_ERROR_VIEWS: dict[int] = {}
 
-##############
-# MIDDLEWARE #
-##############
+# MARK: Middleware
 
 # List of middleware to use. Order is important; in the request phase, these
 # middleware will be applied in the order given, and in the response
 # phase the middleware will be applied in reverse order.
 MIDDLEWARE: list[str] = []
 
-########
-# CSRF #
-########
-
-# Settings for CSRF cookie.
-CSRF_COOKIE_NAME = "csrftoken"
-CSRF_COOKIE_AGE = 60 * 60 * 24 * 7 * 52  # 1 year
-CSRF_COOKIE_DOMAIN = None
-CSRF_COOKIE_PATH = "/"
-CSRF_COOKIE_SECURE = True
-CSRF_COOKIE_HTTPONLY = False
-CSRF_COOKIE_SAMESITE = "Lax"
-CSRF_HEADER_NAME = "CSRF-Token"
-CSRF_FIELD_NAME = "_csrftoken"
+# MARK: CSRF
+
+# A list of trusted origins for unsafe (POST/PUT/DELETE etc.) requests.
+# These origins will be allowed regardless of the normal CSRF checks.
+# Each origin should be a full origin like "https://example.com" or "https://sub.example.com:8080"
 CSRF_TRUSTED_ORIGINS: list[str] = []
 
-###########
-# LOGGING #
-###########
+# Regex patterns for paths that should be exempt from CSRF protection
+# Examples: [r"^/api/", r"/webhooks/.*", r"/health$"]
+CSRF_EXEMPT_PATHS: list[str] = []
+
+# MARK: Logging
 
 # Custom logging configuration.
 LOGGING = {}
 
-###############
-# ASSETS #
-###############
+# MARK: Assets
 
 # Whether to redirect the original asset path to the fingerprinted path.
 ASSETS_REDIRECT_ORIGINAL = True
@@ -143,9 +144,7 @@ ASSETS_REDIRECT_ORIGINAL = True
 # Ex. "https://cdn.example.com/assets/"
 ASSETS_BASE_URL: str = ""
 
-####################
-# PREFLIGHT CHECKS #
-####################
+# MARK: Preflight Checks
 
 # List of all issues generated by system checks that should be silenced. Light
 # issues like warnings, infos or debugs will not generate a message. Silencing
@@ -153,14 +152,10 @@ ASSETS_BASE_URL: str = ""
 # message, but Plain will not stop you from e.g. running server.
 PREFLIGHT_SILENCED_CHECKS = []
 
-#############
-# Templates #
-#############
+# MARK: Templates
 
 TEMPLATES_JINJA_ENVIRONMENT = "plain.templates.jinja.DefaultEnvironment"
 
-#########
-# Shell #
-#########
+# MARK: Shell
 
 SHELL_IMPORT: str = ""

{plain-0.57.0 → plain-0.58.0}/plain/templates/README.md

@@ -70,7 +70,6 @@ class HTMXJSExtension(InclusionTagExtension):
 
     def get_context(self, context, *args, **kwargs):
         return {
-            "csrf_token": context["csrf_token"],
             "DEBUG": settings.DEBUG,
             "extensions": kwargs.get("extensions", []),
         }

{plain-0.57.0 → plain-0.58.0}/plain/test/client.py

@@ -114,8 +114,7 @@ class ClientHandler(BaseHandler):
     the originating WSGIRequest attached to its ``wsgi_request`` attribute.
     """
 
-    def __init__(self, enforce_csrf_checks=True, *args, **kwargs):
-        self.enforce_csrf_checks = enforce_csrf_checks
+    def __init__(self, *args, **kwargs):
         super().__init__(*args, **kwargs)
 
     def __call__(self, environ):
@@ -126,12 +125,6 @@ class ClientHandler(BaseHandler):
 
         request_started.send(sender=self.__class__, environ=environ)
         request = WSGIRequest(environ)
-        # sneaky little hack so that we can easily get round
-        # CsrfViewMiddleware.  This makes life easier, and is probably
-        # required for backwards compatibility with external tests against
-        # admin views.
-        if not self.enforce_csrf_checks:
-            request.csrf_exempt = True
 
         # Request goes through middleware.
         response = self.get_response(request)
@@ -420,14 +413,13 @@ class Client(RequestFactory):
 
     def __init__(
         self,
-        enforce_csrf_checks=False,
         raise_request_exception=True,
         *,
         headers=None,
         **defaults,
     ):
         super().__init__(headers=headers, **defaults)
-        self.handler = ClientHandler(enforce_csrf_checks)
+        self.handler = ClientHandler()
         self.raise_request_exception = raise_request_exception
         self.exc_info = None
         self.extra = None

{plain-0.57.0 → plain-0.58.0}/plain/views/README.md

@@ -142,8 +142,6 @@ Rendering forms is done directly in the HTML.
 {% block content %}
 
 <form method="post">
-    {{ csrf_input }}
-
     <!-- Render general form errors -->
     {% for error in form.non_field_errors %}
     <div>{{ error }}</div>

{plain-0.57.0 → plain-0.58.0}/plain/views/templates.py

@@ -1,27 +1,11 @@
-from plain.csrf.middleware import get_token
 from plain.exceptions import ImproperlyConfigured
 from plain.http import Response
 from plain.runtime import settings
 from plain.templates import Template, TemplateFileMissing
-from plain.utils.functional import lazy
-from plain.utils.html import format_html
-from plain.utils.safestring import SafeString
 
 from .base import View
 
 
-def csrf_input(request):
-    return format_html(
-        '<input type="hidden" name="{}" value="{}">',
-        settings.CSRF_FIELD_NAME,
-        get_token(request),
-    )
-
-
-csrf_input_lazy = lazy(csrf_input, SafeString, str)
-csrf_token_lazy = lazy(get_token, str)
-
-
 class TemplateView(View):
     """
     Render a template.
@@ -37,8 +21,6 @@ class TemplateView(View):
         return {
             "request": self.request,
             "template_names": self.get_template_names(),
-            "csrf_input": csrf_input_lazy(self.request),
-            "csrf_token": csrf_token_lazy(self.request),
             "DEBUG": settings.DEBUG,
         }
 

{plain-0.57.0 → plain-0.58.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "plain"
-version = "0.57.0"
+version = "0.58.0"
 description = "A web framework for building products with Python."
 authors = [{name = "Dave Gaeddert", email = "dave.gaeddert@dropseed.dev"}]
 readme = "README.md"