plain 0.82.0__tar.gz → 0.83.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plain
-Version: 0.82.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.82.0 → plain-0.83.0}/plain/CHANGELOG.md

@@ -1,5 +1,16 @@
 # 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

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.82.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.82.0 → plain-0.83.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "plain"
-version = "0.82.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.82.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
-```