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

plain/cli/upgrade.py

@@ -5,68 +5,42 @@ from pathlib import Path
 
 import click
 
-from .agent.prompt import prompt_agent
+from .runtime import without_runtime_setup
 
 LOCK_FILE = Path("uv.lock")
 
 
+@without_runtime_setup
 @click.command()
 @click.argument("packages", nargs=-1)
-@click.option(
-    "--diff", is_flag=True, help="Read versions from unstaged uv.lock changes"
-)
-@click.option(
-    "--agent-command",
-    envvar="PLAIN_AGENT_COMMAND",
-    help="Run command with generated prompt",
-)
-@click.option(
-    "--print",
-    "print_only",
-    is_flag=True,
-    help="Print the prompt without running the agent",
-)
-def upgrade(
-    packages: tuple[str, ...],
-    diff: bool,
-    agent_command: str | None = None,
-    print_only: bool = False,
-) -> None:
-    """Upgrade Plain packages with the help of an agent."""
+def upgrade(packages: tuple[str, ...]) -> None:
+    """Upgrade Plain packages"""
     if not packages:
-        click.secho("Getting installed packages...", bold=True, err=True)
+        click.secho("Getting installed packages...", bold=True)
         packages = tuple(sorted(get_installed_plain_packages()))
         for pkg in packages:
-            click.secho(f"- {click.style(pkg, fg='yellow')}", err=True)
-        click.echo(err=True)
+            click.secho(f"- {click.style(pkg, fg='yellow')}")
+        click.echo()
 
     if not packages:
         raise click.UsageError("No plain packages found or specified.")
 
-    if diff:
-        before_after = versions_from_diff(packages)
-    else:
-        before_after = upgrade_packages(packages)
+    before_after = upgrade_packages(packages)
 
-    # Remove all packages that were not upgraded
-    before_after = {
+    # Show what was upgraded
+    upgraded = {
         pkg: versions
         for pkg, versions in before_after.items()
         if versions[0] != versions[1]
     }
 
-    if not before_after:
-        click.secho(
-            "No packages were upgraded. If uv.lock has already been updated, use --diff instead.",
-            fg="green",
-            err=True,
-        )
+    if not upgraded:
+        click.secho("All packages already at latest version.", fg="green")
         return
 
-    prompt = build_prompt(before_after)
-    success = prompt_agent(prompt, agent_command, print_only)
-    if not success:
-        raise click.Abort()
+    click.secho("Upgraded packages:", bold=True)
+    for pkg, (before, after) in upgraded.items():
+        click.echo(f"  {pkg}: {before} -> {after}")
 
 
 def get_installed_plain_packages() -> list[str]:
@@ -90,29 +64,6 @@ def parse_lock_versions(lock_text: str, packages: set[str]) -> dict[str, str]:
     return versions
 
 
-def versions_from_diff(
-    packages: tuple[str, ...],
-) -> dict[str, tuple[str | None, str | None]]:
-    result = subprocess.run(
-        ["git", "status", "--porcelain", str(LOCK_FILE)], capture_output=True, text=True
-    )
-    if not result.stdout.strip():
-        raise click.UsageError(
-            "--diff specified but uv.lock has no uncommitted changes"
-        )
-
-    prev_text = subprocess.run(
-        ["git", "show", f"HEAD:{LOCK_FILE}"], capture_output=True, text=True, check=True
-    ).stdout
-    current_text = LOCK_FILE.read_text()
-
-    packages_set = set(packages)
-    before = parse_lock_versions(prev_text, packages_set)
-    after = parse_lock_versions(current_text, packages_set)
-
-    return {pkg: (before.get(pkg), after.get(pkg)) for pkg in packages}
-
-
 def upgrade_packages(
     packages: tuple[str, ...],
 ) -> dict[str, tuple[str | None, str | None]]:
@@ -122,47 +73,9 @@ def upgrade_packages(
     for pkg in packages:
         upgrade_args.extend(["--upgrade-package", pkg])
 
-    click.secho("Upgrading with uv sync...", bold=True, err=True)
+    click.secho("Upgrading with uv sync...", bold=True)
     subprocess.run(upgrade_args, check=True, stdout=sys.stderr)
-    click.echo(err=True)
+    click.echo()
 
     after = parse_lock_versions(LOCK_FILE.read_text(), set(packages))
     return {pkg: (before.get(pkg), after.get(pkg)) for pkg in packages}
-
-
-def build_prompt(before_after: dict[str, tuple[str | None, str | None]]) -> str:
-    lines = [
-        "These packages have been updated and may require additional changes to the code:",
-        "",
-    ]
-    for pkg, (before, after) in before_after.items():
-        lines.append(f"- {pkg}: {before} -> {after}")
-
-    lines.extend(
-        [
-            "",
-            "## Instructions",
-            "",
-            "1. **Process each package systematically:**",
-            "   - For each package, run: `uv run plain-changelog {package} --from {before} --to {after}`",
-            "   - Read the 'Upgrade instructions' section carefully",
-            "   - If it says 'No changes required', skip to the next package",
-            "   - Apply any required code changes as specified",
-            "",
-            "2. **Important guidelines:**",
-            "   - Process ALL packages before testing or validation",
-            "   - After all packages are updated, run `uv run plain fix --unsafe-fixes` and `uv run plain pre-commit` to check results",
-            "   - DO NOT commit any changes",
-            "   - Keep code changes minimal and focused - avoid unnecessary comments",
-            "",
-            "3. **Available tools:**",
-            "   - Python shell: `uv run python`",
-            "   - If you have a subagents feature and there are more than three packages here, use subagents",
-            "",
-            "4. **Workflow:**",
-            "   - Review changelog for each package → Apply changes → Move to next package",
-            "   - Only after all packages: run pre-commit checks",
-            "   - Report any issues or conflicts encountered",
-        ]
-    )
-    return "\n".join(lines)

plain/cli/urls.py

@@ -1,16 +1,19 @@
+from __future__ import annotations
+
+from collections.abc import Iterator
+
 import click
 
 
 @click.group()
-def urls():
-    """URL related commands"""
-    pass
+def urls() -> None:
+    """URL configuration commands"""
 
 
 @urls.command("list")
 @click.option("--flat", is_flag=True, help="List all URLs in a flat list")
-def list_urls(flat):
-    """Print all URL patterns under settings.URLS_ROUTER"""
+def list_urls(flat: bool) -> None:
+    """List all URL patterns"""
     from plain.runtime import settings
     from plain.urls import URLResolver, get_resolver
 
@@ -20,7 +23,9 @@ def list_urls(flat):
     resolver = get_resolver(settings.URLS_ROUTER)
     if flat:
 
-        def flat_list(patterns, prefix="", curr_ns=""):
+        def flat_list(
+            patterns: list, prefix: str = "", curr_ns: str = ""
+        ) -> Iterator[str]:
             for pattern in patterns:
                 full_pattern = f"{prefix}{pattern.pattern}"
                 if isinstance(pattern, URLResolver):
@@ -50,7 +55,7 @@ def list_urls(flat):
             click.echo(p)
     else:
 
-        def print_tree(patterns, prefix="", curr_ns=""):
+        def print_tree(patterns: list, prefix: str = "", curr_ns: str = "") -> None:
             count = len(patterns)
             for idx, pattern in enumerate(patterns):
                 is_last = idx == (count - 1)

plain/cli/utils.py

@@ -4,12 +4,12 @@ from plain.utils.crypto import get_random_string
 
 
 @click.group()
-def utils():
-    pass
+def utils() -> None:
+    """Utility commands"""
 
 
 @utils.command()
-def generate_secret_key():
+def generate_secret_key() -> None:
     """Generate a new secret key"""
     new_secret_key = get_random_string(50)
     click.echo(new_secret_key)

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)