plain 0.81.0__tar.gz → 0.83.0__tar.gz

{plain-0.81.0 → plain-0.83.0}/PKG-INFO

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

{plain-0.81.0 → plain-0.83.0}/plain/CHANGELOG.md

@@ -1,5 +1,29 @@
 # plain changelog
 
+## [0.83.0](https://github.com/dropseed/plain/releases/plain@0.83.0) (2025-10-29)
+
+### What's changed
+
+- Added comprehensive Content Security Policy (CSP) documentation explaining how to use nonces with inline scripts and styles ([784f3dd972](https://github.com/dropseed/plain/commit/784f3dd972))
+- The `json_script` utility function now accepts an optional `nonce` parameter for CSP-compliant inline JSON scripts ([784f3dd972](https://github.com/dropseed/plain/commit/784f3dd972))
+
+### Upgrade instructions
+
+- Any `|json_script` usages need to make sure the second argument is a nonce, not a custom encoder (which is now third)
+
+## [0.82.0](https://github.com/dropseed/plain/releases/plain@0.82.0) (2025-10-29)
+
+### What's changed
+
+- The `DEFAULT_RESPONSE_HEADERS` setting can now be a callable that accepts a request argument, enabling dynamic header generation per request ([cb92905834](https://github.com/dropseed/plain/commit/cb92905834))
+- Added `request.csp_nonce` cached property for generating Content Security Policy nonces ([75071dcc70](https://github.com/dropseed/plain/commit/75071dcc70))
+- Simplified the preflight command by moving `plain preflight check` back to `plain preflight` ([40c2c4560e](https://github.com/dropseed/plain/commit/40c2c4560e))
+
+### Upgrade instructions
+
+- If you use `plain preflight check`, update to `plain preflight` (the `check` subcommand has been removed for simplicity)
+- If you use `plain preflight check --deploy`, update to `plain preflight --deploy`
+
 ## [0.81.0](https://github.com/dropseed/plain/releases/plain@0.81.0) (2025-10-22)
 
 ### What's changed

{plain-0.81.0 → plain-0.83.0}/plain/cli/preflight.py

@@ -5,21 +5,13 @@ import click
 
 from plain import preflight
 from plain.packages import packages_registry
-from plain.preflight.registry import checks_registry
-from plain.runtime import settings
 
 
-@click.group("preflight")
-def preflight_cli() -> None:
-    """Run or manage preflight checks."""
-    pass
-
-
-@preflight_cli.command("check")
+@click.command("preflight")
 @click.option(
     "--deploy",
     is_flag=True,
-    help="Check deployment settings.",
+    help="Include deployment checks.",
 )
 @click.option(
     "--format",
@@ -32,14 +24,13 @@ def preflight_cli() -> None:
     is_flag=True,
     help="Hide progress output and warnings, only show errors.",
 )
-def check_command(deploy: bool, format: str, quiet: bool) -> None:
+def preflight_cli(deploy: bool, format: str, quiet: bool) -> None:
     """
-    Use the system check framework to validate entire Plain project.
+    Run preflight checks to validate your Plain project.
     Exit with error code if any errors are found. Warnings do not cause failure.
     """
     # Auto-discover and load preflight checks
     packages_registry.autodiscover_modules("preflight", include_app=True)
-
     if not quiet:
         click.secho("Running preflight checks...", dim=True, italic=True, err=True)
 
@@ -200,48 +191,3 @@ def check_command(deploy: bool, format: str, quiet: bool) -> None:
     # Exit with error if there are any errors (not warnings)
     if has_errors:
         sys.exit(1)
-
-
-@preflight_cli.command("list")
-def list_checks() -> None:
-    """List all available preflight checks."""
-    packages_registry.autodiscover_modules("preflight", include_app=True)
-
-    regular = []
-    deployment = []
-    silenced_checks = settings.PREFLIGHT_SILENCED_CHECKS
-
-    for name, (check_class, deploy) in sorted(checks_registry.checks.items()):
-        # Use class docstring as description
-        description = check_class.__doc__ or "No description"
-        # Get first line of docstring
-        description = description.strip().split("\n")[0]
-
-        is_silenced = name in silenced_checks
-        if deploy:
-            deployment.append((name, description, is_silenced))
-        else:
-            regular.append((name, description, is_silenced))
-
-    if regular:
-        click.echo("Regular checks:")
-        for name, description, is_silenced in regular:
-            silenced_text = (
-                click.style(" (silenced)", fg="red", dim=True) if is_silenced else ""
-            )
-            click.echo(
-                f"  {click.style(name)}: {click.style(description, dim=True)}{silenced_text}"
-            )
-
-    if deployment:
-        click.echo("\nDeployment checks:")
-        for name, description, is_silenced in deployment:
-            silenced_text = (
-                click.style(" (silenced)", fg="red", dim=True) if is_silenced else ""
-            )
-            click.echo(
-                f"  {click.style(name)}: {click.style(description, dim=True)}{silenced_text}"
-            )
-
-    if not regular and not deployment:
-        click.echo("No preflight checks found.")

plain-0.83.0/plain/http/README.md

@@ -0,0 +1,89 @@
+# HTTP
+
+**HTTP request and response handling.**
+
+- [Overview](#overview)
+- [Content Security Policy (CSP)](#content-security-policy-csp)
+
+## Overview
+
+Typically you will interact with [Request](request.py#Request) and [Response](response.py#ResponseBase) objects in your views and middleware.
+
+```python
+from plain.views import View
+from plain.http import Response
+
+class ExampleView(View):
+    def get(self):
+        # Accessing a request header
+        print(self.request.headers.get("Example-Header"))
+
+        # Accessing a query parameter
+        print(self.request.query_params.get("example"))
+
+        # Creating a response
+        response = Response("Hello, world!", status_code=200)
+
+        # Setting a response header
+        response.headers["Example-Header"] = "Example Value"
+
+        return response
+```
+
+## Content Security Policy (CSP)
+
+Plain includes built-in support for Content Security Policy (CSP) through nonces, allowing you to use strict CSP policies without `'unsafe-inline'`.
+
+Each request generates a unique cryptographically secure nonce available via [`request.csp_nonce`](request.py#Request.csp_nonce):
+
+### Configuring CSP Headers
+
+Set `DEFAULT_RESPONSE_HEADERS` as a callable function to generate dynamic CSP headers with nonces:
+
+```python
+# app/settings.py
+def DEFAULT_RESPONSE_HEADERS(request):
+    """
+    Dynamic response headers with CSP nonces.
+    """
+    nonce = request.csp_nonce
+    return {
+        "Content-Security-Policy": (
+            f"default-src 'self'; "
+            f"script-src 'self' 'nonce-{nonce}'; "
+            f"style-src 'self' 'nonce-{nonce}'; "
+            f"img-src 'self' data:; "
+            f"font-src 'self'; "
+            f"connect-src 'self'; "
+            f"frame-ancestors 'self'; "
+            f"base-uri 'self'; "
+            f"form-action 'self'"
+        ),
+    }
+```
+
+Use tools like [Google's CSP Evaluator](https://csp-evaluator.withgoogle.com/) to analyze your CSP policy and identify potential security issues or misconfigurations.
+
+### Using Nonces in Templates
+
+Add the nonce attribute to inline scripts and styles in your templates:
+
+```html
+<!-- Inline script with nonce -->
+<script nonce="{{ request.csp_nonce }}">
+    console.log("This script is allowed by CSP");
+</script>
+
+<!-- Inline style with nonce -->
+<style nonce="{{ request.csp_nonce }}">
+    .example { color: red; }
+</style>
+```
+
+External scripts and stylesheets loaded from `'self'` don't need nonces:
+
+```html
+<!-- External scripts/styles work with 'self' directive -->
+<script src="/assets/app.js"></script>
+<link rel="stylesheet" href="/assets/app.css">
+```

{plain-0.81.0 → plain-0.83.0}/plain/http/request.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 import codecs
 import copy
 import json
+import secrets
 import uuid
 from collections.abc import Iterator
 from functools import cached_property
@@ -101,6 +102,16 @@ class Request:
     def headers(self) -> RequestHeaders:
         return RequestHeaders(self.meta)
 
+    @cached_property
+    def csp_nonce(self) -> str:
+        """Generate a cryptographically secure nonce for Content Security Policy.
+
+        The nonce is generated once per request and cached. It can be used in
+        CSP headers and templates to allow specific inline scripts/styles while
+        blocking others.
+        """
+        return secrets.token_urlsafe(16)
+
     @cached_property
     def accepted_types(self) -> list[MediaType]:
         """Return accepted media types sorted by quality value (highest first).

{plain-0.81.0 → plain-0.83.0}/plain/internal/middleware/headers.py

@@ -13,8 +13,15 @@ class DefaultHeadersMiddleware(HttpMiddleware):
     def process_request(self, request: Request) -> Response:
         response = self.get_response(request)
 
-        for header, value in settings.DEFAULT_RESPONSE_HEADERS.items():
-            # Since we don't have a good way to *remote* default response headers,
+        # Support callable DEFAULT_RESPONSE_HEADERS for dynamic header generation
+        # (e.g., CSP nonces that change per request)
+        if callable(settings.DEFAULT_RESPONSE_HEADERS):
+            default_headers = settings.DEFAULT_RESPONSE_HEADERS(request)
+        else:
+            default_headers = settings.DEFAULT_RESPONSE_HEADERS
+
+        for header, value in default_headers.items():
+            # Since we don't have a good way to *remove* default response headers,
             # use allow users to set them to an empty string to indicate they should be removed.
             if header in response.headers and response.headers[header] == "":
                 del response.headers[header]

plain-0.83.0/plain/preflight/README.md

@@ -0,0 +1,83 @@
+# Preflight
+
+**System checks for Plain applications.**
+
+- [Overview](#overview)
+- [Development](#development)
+- [Deployment](#deployment)
+- [Custom preflight checks](#custom-preflight-checks)
+- [Silencing preflight checks](#silencing-preflight-checks)
+
+## Overview
+
+Preflight checks help identify issues with your settings or environment before running your application.
+
+```bash
+plain preflight
+```
+
+## Development
+
+If you use [`plain.dev`](/plain-dev/README.md) for local development, the Plain preflight command is run automatically when you run `plain dev`.
+
+## Deployment
+
+The `plain preflight` command should often be part of your deployment process. Make sure to add the `--deploy` flag to the command to run checks that are only relevant in a production environment.
+
+```bash
+plain preflight --deploy
+```
+
+## Custom preflight checks
+
+Use the `@register_check` decorator to add your own preflight check to the system. Create a class that inherits from `PreflightCheck` and implements a `run()` method that returns a list of `PreflightResult` objects.
+
+```python
+from plain.preflight import PreflightCheck, PreflightResult, register_check
+
+
+@register_check("custom.example")
+class CustomCheck(PreflightCheck):
+    """Description of what this check validates."""
+
+    def run(self) -> list[PreflightResult]:
+        # Your check logic here
+        if some_condition:
+            return [
+                PreflightResult(
+                    fix="This is a custom error message.",
+                    id="custom.example_failed",
+                )
+            ]
+        return []
+```
+
+For deployment-specific checks, add `deploy=True` to the decorator.
+
+```python
+@register_check("custom.deploy_example", deploy=True)
+class CustomDeployCheck(PreflightCheck):
+    """Description of what this deployment check validates."""
+
+    def run(self) -> list[PreflightResult]:
+        # Your deployment check logic here
+        if some_deploy_condition:
+            return [
+                PreflightResult(
+                    fix="This is a custom error message for deployment.",
+                    id="custom.deploy_example_failed",
+                )
+            ]
+        return []
+```
+
+## Silencing preflight checks
+
+The `settings.PREFLIGHT_SILENCED_CHECKS` setting can be used to silence individual checks by their ID (ex. `security.E020`).
+
+```python
+# app/settings.py
+PREFLIGHT_SILENCED_CHECKS = [
+    "security.E020",  # Allow empty ALLOWED_HOSTS in deployment
+]
+```

{plain-0.81.0 → plain-0.83.0}/plain/utils/html.py

@@ -34,25 +34,30 @@ _json_script_escapes = {
 def json_script(
     value: Any,
     element_id: str | None = None,
+    nonce: str = "",
     encoder: type[json.JSONEncoder] | None = None,
 ) -> SafeString:
     """
     Escape all the HTML/XML special characters with their unicode escapes, so
     value is safe to be output anywhere except for inside a tag attribute. Wrap
     the escaped JSON in a script tag.
+
+    Args:
+        value: The data to encode as JSON
+        element_id: Optional ID attribute for the script tag
+        nonce: Optional CSP nonce for inline script tags
+        encoder: Optional custom JSON encoder class
     """
     from plain.json import PlainJSONEncoder
 
     json_str = json.dumps(value, cls=encoder or PlainJSONEncoder).translate(
         _json_script_escapes
     )
-    if element_id:
-        template = '<script id="{}" type="application/json">{}</script>'
-        args = (element_id, mark_safe(json_str))
-    else:
-        template = '<script type="application/json">{}</script>'
-        args = (mark_safe(json_str),)
-    return format_html(template, *args)
+    id_attr = f' id="{element_id}"' if element_id else ""
+    nonce_attr = f' nonce="{nonce}"' if nonce else ""
+    return mark_safe(
+        f'<script{id_attr}{nonce_attr} type="application/json">{json_str}</script>'
+    )
 
 
 def conditional_escape(text: Any) -> SafeString | str:

{plain-0.81.0 → plain-0.83.0}/pyproject.toml

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

plain-0.81.0/plain/http/README.md

@@ -1,30 +0,0 @@
-# HTTP
-
-**HTTP request and response handling.**
-
-- [Overview](#overview)
-
-## Overview
-
-Typically you will interact with [Request](request.py#Request) and [Response](response.py#ResponseBase) objects in your views and middleware.
-
-```python
-from plain.views import View
-from plain.http import Response
-
-class ExampleView(View):
-    def get(self):
-        # Accessing a request header
-        print(self.request.headers.get("Example-Header"))
-
-        # Accessing a query parameter
-        print(self.request.query_params.get("example"))
-
-        # Creating a response
-        response = Response("Hello, world!", status_code=200)
-
-        # Setting a response header
-        response.headers["Example-Header"] = "Example Value"
-
-        return response
-```

plain-0.81.0/plain/preflight/README.md

@@ -1,61 +0,0 @@
-# Preflight
-
-**System checks for Plain applications.**
-
-- [Overview](#overview)
-- [Development](#development)
-- [Deployment](#deployment)
-- [Custom preflight checks](#custom-preflight-checks)
-- [Silencing preflight checks](#silencing-preflight-checks)
-
-## Overview
-
-Preflight checks help identify issues with your settings or environment before running your application.
-
-```bash
-plain preflight check
-```
-
-## Development
-
-If you use [`plain.dev`](/plain-dev/README.md) for local development, the Plain preflight command is run automatically when you run `plain dev`.
-
-## Deployment
-
-The `plain preflight check` command should often be part of your deployment process. Make sure to add the `--deploy` flag to the command to run checks that are only relevant in a production environment.
-
-```bash
-plain preflight check --deploy
-```
-
-## Custom preflight checks
-
-Use the `@register_check` decorator to add your own preflight check to the system. Just make sure that particular Python module is somehow imported so the check registration runs.
-
-```python
-from plain.preflight import register_check, Error
-
-
-@register_check
-def custom_check(package_configs, **kwargs):
-    return Error("This is a custom error message.", id="custom.C001")
-```
-
-For deployment-specific checks, add the `deploy` argument to the decorator.
-
-```python
-@register_check(deploy=True)
-def custom_deploy_check(package_configs, **kwargs):
-    return Error("This is a custom error message for deployment.", id="custom.D001")
-```
-
-## Silencing preflight checks
-
-The `settings.PREFLIGHT_SILENCED_CHECKS` setting can be used to silence individual checks by their ID (ex. `security.E020`).
-
-```python
-# app/settings.py
-PREFLIGHT_SILENCED_CHECKS = [
-    "security.E020",  # Allow empty ALLOWED_HOSTS in deployment
-]
-```