plain 0.82.0__py3-none-any.whl → 0.84.0__py3-none-any.whl

plain/CHANGELOG.md

@@ -1,5 +1,44 @@
 # plain changelog
 
+## [0.84.0](https://github.com/dropseed/plain/releases/plain@0.84.0) (2025-10-29)
+
+### What's changed
+
+- The `DEFAULT_RESPONSE_HEADERS` setting now supports format string placeholders (e.g., `{request.csp_nonce}`) for dynamic header values instead of requiring a callable function ([5199383128](https://github.com/dropseed/plain/commit/5199383128))
+- Views can now set headers to `None` to explicitly remove default response headers ([5199383128](https://github.com/dropseed/plain/commit/5199383128))
+- Added comprehensive documentation for customizing default response headers including override, remove, and extend patterns ([5199383128](https://github.com/dropseed/plain/commit/5199383128))
+
+### Upgrade instructions
+
+- If you have `DEFAULT_RESPONSE_HEADERS` configured as a callable function, convert it to a dictionary with format string placeholders:
+
+    ```python
+    # Before:
+    def DEFAULT_RESPONSE_HEADERS(request):
+        nonce = request.csp_nonce
+        return {
+            "Content-Security-Policy": f"script-src 'self' 'nonce-{nonce}'",
+        }
+
+    # After:
+    DEFAULT_RESPONSE_HEADERS = {
+        "Content-Security-Policy": "script-src 'self' 'nonce-{request.csp_nonce}'",
+    }
+    ```
+
+- If you were overriding default headers to empty strings (`""`) to remove them, change those to `None` instead
+
+## [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/http/README.md

@@ -3,6 +3,8 @@
 **HTTP request and response handling.**
 
 - [Overview](#overview)
+- [Content Security Policy (CSP)](#content-security-policy-csp)
+- [Customizing Default Response Headers](#customizing-default-response-headers)
 
 ## Overview
 
@@ -28,3 +30,113 @@ class ExampleView(View):
 
         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
+
+Include CSP in `DEFAULT_RESPONSE_HEADERS` using `{request.csp_nonce}` placeholders for dynamic nonces:
+
+```python
+# app/settings.py
+DEFAULT_RESPONSE_HEADERS = {
+    "Content-Security-Policy": (
+        "default-src 'self'; "
+        "script-src 'self' 'nonce-{request.csp_nonce}'; "
+        "style-src 'self' 'nonce-{request.csp_nonce}'; "
+        "img-src 'self' data:; "
+        "font-src 'self'; "
+        "connect-src 'self'; "
+        "frame-ancestors 'self'; "
+        "base-uri 'self'; "
+        "form-action 'self'"
+    ),
+    # Other default headers...
+    "X-Frame-Options": "DENY",
+}
+```
+
+The `{request.csp_nonce}` placeholder will be replaced with a unique nonce for each request.
+
+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">
+```
+
+## Customizing Default Response Headers
+
+Plain applies default response headers to all responses via `DEFAULT_RESPONSE_HEADERS` in settings. Views can customize these headers in several ways:
+
+### Override Default Headers
+
+Set the header to a different value in your view:
+
+```python
+class MyView(View):
+    def get(self):
+        response = Response("content")
+        # Override the default X-Frame-Options: DENY
+        response.headers["X-Frame-Options"] = "SAMEORIGIN"
+        return response
+```
+
+### Remove Default Headers
+
+Set the header to `None` to prevent it from being applied:
+
+```python
+class EmbeddableView(View):
+    def get(self):
+        response = Response("content")
+        # Remove X-Frame-Options entirely to allow embedding
+        response.headers["X-Frame-Options"] = None
+        return response
+```
+
+### Extend Default Headers
+
+Read the default value from settings, modify it, then set it in your view:
+
+```python
+from plain.runtime import settings
+
+class MyView(View):
+    def get(self):
+        response = Response("content")
+
+        # Get the default CSP policy
+        if csp := settings.DEFAULT_RESPONSE_HEADERS.get("Content-Security-Policy"):
+            # Format it with the current request to resolve placeholders
+            csp = csp.format(request=self.request)
+            # Extend with additional sources
+            response.headers["Content-Security-Policy"] = (
+                f"{csp}; script-src https://analytics.example.com"
+            )
+
+        return response
+```

plain/internal/middleware/headers.py

@@ -10,24 +10,46 @@ if TYPE_CHECKING:
 
 
 class DefaultHeadersMiddleware(HttpMiddleware):
+    """
+    Applies default response headers from settings.DEFAULT_RESPONSE_HEADERS.
+
+    This middleware runs after the view executes and applies default headers
+    to the response using setdefault(), which means:
+    - Headers already set by the view won't be overridden
+    - Headers not set by the view will use the default value
+
+    View Customization Patterns:
+    - Use default: Don't set the header (middleware applies it)
+    - Override: Set the header to a different value
+    - Remove: Set the header to None (middleware will delete it)
+    - Extend: Read from settings.DEFAULT_RESPONSE_HEADERS, modify, then set
+
+    Format Strings:
+    Header values can include {request.attribute} placeholders for dynamic
+    content. Example: 'nonce-{request.csp_nonce}' will be formatted with
+    the request's csp_nonce value. Headers without placeholders are used as-is.
+
+    None Removal:
+    Views can set a header to None to opt-out of that default header entirely.
+    The middleware will delete any header set to None, preventing the default
+    from being applied.
+    """
+
     def process_request(self, request: Request) -> Response:
+        # Get the response from the view (and any inner middleware)
         response = self.get_response(request)
 
-        # 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] == "":
+        # Apply default headers to the response
+        for header, value in settings.DEFAULT_RESPONSE_HEADERS.items():
+            if header not in response.headers:
+                # Header not set - apply default
+                if "{" in value:
+                    response.headers[header] = value.format(request=request)
+                else:
+                    response.headers[header] = value
+            elif response.headers[header] is None:
+                # Header explicitly set to None by view - remove it
                 del response.headers[header]
-                continue
-
-            response.headers.setdefault(header, value)
 
         # Add the Content-Length header to non-streaming responses if not
         # already set.

plain/runtime/global_settings.py

@@ -27,8 +27,12 @@ URLS_ROUTER: str
 ALLOWED_HOSTS: list[str] = []
 
 # Default headers for all responses.
-DEFAULT_RESPONSE_HEADERS = {
-    # "Content-Security-Policy": "default-src 'self'",
+# Header values can include {request.attribute} placeholders for dynamic content.
+# Example: "script-src 'nonce-{request.csp_nonce}'" will use the request's nonce.
+# Views can override, remove, or extend these headers - see plain/http/README.md
+# for customization patterns.
+DEFAULT_RESPONSE_HEADERS: dict = {
+    # "Content-Security-Policy": "default-src 'self'; script-src 'self' 'nonce-{request.csp_nonce}'",
     # https://hstspreload.org/
     # "Strict-Transport-Security": "max-age=31536000; includeSubDomains; preload",
     "Cross-Origin-Opener-Policy": "same-origin",

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.dist-info → plain-0.84.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plain
-Version: 0.82.0
+Version: 0.84.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.dist-info → plain-0.84.0.dist-info}/RECORD

@@ -1,5 +1,5 @@
 plain/AGENTS.md,sha256=As6EFSWWHJ9lYIxb2LMRqNRteH45SRs7a_VFslzF53M,1046
-plain/CHANGELOG.md,sha256=LafG-4y2ZZGMobjIsHK5Iob3e47rA_umHo__6KUA1rI,33085
+plain/CHANGELOG.md,sha256=wZ16yVxfhEgl-6T5SGrjiEqMtie_jZqTPd6bc7smcAI,35041
 plain/README.md,sha256=VvzhXNvf4I6ddmjBP9AExxxFXxs7RwyoxdgFm-W5dsg,4072
 plain/__main__.py,sha256=GK39854Lc_LO_JP8DzY9Y2MIQ4cQEl7SXFJy244-lC8,110
 plain/debug.py,sha256=C2OnFHtRGMrpCiHSt-P2r58JypgQZ62qzDBpV4mhtFM,855
@@ -56,7 +56,7 @@ plain/forms/boundfield.py,sha256=PEquPRn1BoVd4ZkIin8tjkBzRDMv-41wO8qHV0S1shg,196
 plain/forms/exceptions.py,sha256=MuMUF-33Qsc_HWk5zI3rcWzdvXzQbEOKAZvJKkbrL58,320
 plain/forms/fields.py,sha256=GQSTI6-eaHivIXj3TQSw2LpyWMbN0NZ-SHjUO_oxqeA,37132
 plain/forms/forms.py,sha256=GnJWzjIXOPByfrdiqjjo4xdKdkBw1gBD6Hq4mg73gHQ,11259
-plain/http/README.md,sha256=32uuWbarAcG_qmP-Fltk-_26HFKfY3dBdlrO2FDb7D0,756
+plain/http/README.md,sha256=HP0m45CKhtA5Jmc65VhMZCYEH9ATK7BfBvkHwUASnwA,4221
 plain/http/__init__.py,sha256=gUTIGh-GbSIlh3SP-Db-XAOX4P_j2hh2445w8Cm-zKQ,1032
 plain/http/cookie.py,sha256=x13G3LIr0jxnPK1NQRptmi0DrAq9PsivQnQTm4LKaW0,2191
 plain/http/middleware.py,sha256=TPs585IIFjgp-5uUAJtIoigH6uwTS3FJqwFSsQdayd4,960
@@ -78,7 +78,7 @@ plain/internal/handlers/base.py,sha256=ZlpOYqd45X0wPYlmxHwXR5kyCkWBB6ZJeSGZka5VA
 plain/internal/handlers/exception.py,sha256=P7oTqVtKoIHBOxCml1BSgNBV_rQWyCHlO5hS87NVjXo,4872
 plain/internal/handlers/wsgi.py,sha256=d2Hcs4fzTSir6OvtpVromTw0RmmFAqTL4_EaBjoHtNU,8919
 plain/internal/middleware/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-plain/internal/middleware/headers.py,sha256=z3rmjIGGYV5JcAfAUm3tcdG34OFoEfYukJrwZsq7JIo,1425
+plain/internal/middleware/headers.py,sha256=fX8iMOeecqSyI7y-IIQ_w4OUFRJpgMvUr_xtUzI7IUQ,2361
 plain/internal/middleware/hosts.py,sha256=UXMts7cKA9ocOK-J8DAcZPbKYQtfVyLSLH2QQX3mKjM,5895
 plain/internal/middleware/https.py,sha256=8n990O0Ej5cRrBlfAnLW2nZ2mx0wn0002C4HuRhVpsM,1117
 plain/internal/middleware/slash.py,sha256=V_rTb9v8uMUR_N2TLETBwlJFItoL4WD9JnRyFaFs878,3073
@@ -102,7 +102,7 @@ plain/preflight/security.py,sha256=nMbflO2LN49oKAAaa-tYvuweNB0RWv1z3w9niU037n0,3
 plain/preflight/urls.py,sha256=Asw_vq-70NRqr15yuBAYL0JCZ04liumORYT3I3KmF_k,437
 plain/runtime/README.md,sha256=ZZ3NPTjtxwyfw1V827YNwkWc8MiH5rWiy27HrN13qZ8,4819
 plain/runtime/__init__.py,sha256=dvF5ipRckVf6LQgY4kdxE_dTlCdncuawQf3o5EqLq9k,2524
-plain/runtime/global_settings.py,sha256=3nYptasBjcodSR2Nq8Pm0KViPpvIS4SDOTShr5294Kk,5413
+plain/runtime/global_settings.py,sha256=BVkLDWA2i4kbtjQabFdJ4cYhVrt-mU8UqZdBRz7cbwU,5741
 plain/runtime/user_settings.py,sha256=Tbd0J6bxp18tKmFsQcdlxeFhUQU68PYtsswzQ2IcfNc,11467
 plain/runtime/utils.py,sha256=sHOv9SWCalBtg32GtZofimM2XaQtf_jAyyf6RQuOlGc,851
 plain/server/LICENSE,sha256=Xt_dw4qYwQI9qSi2u8yMZeb4HuMRp5tESRKhtvvJBgA,1707
@@ -167,7 +167,7 @@ plain/utils/duration.py,sha256=QBFh-iLvRXuw0N0UUdFqabeJvZVqkgFME_c2gRSLwhI,1340
 plain/utils/encoding.py,sha256=40siECldXUFyZ_IkyQCeOkyQuXb7i4Rpys3nFWFHnuc,4482
 plain/utils/functional.py,sha256=HqRXyM6R3Sl9IbhGl6t-DdFwtfr05IYmq7rgFCWV_2U,14650
 plain/utils/hashable.py,sha256=1Kh_SFxsaR2d3xQMNEtHb4eKSHugtNt66iZ3ZvKjt50,811
-plain/utils/html.py,sha256=x9kruRAzs9mIJ3XlSmVcxIXOy-lSupZ4J3J0KlWr1Rc,4028
+plain/utils/html.py,sha256=ctgzowSi_NkytPOw3FvyqEIXgOE-52trkTFPjiGvGVg,4202
 plain/utils/http.py,sha256=P7dkgWpC28Bm-_VNuj57VN8j8AdbaDu1CKxoggwBpKo,5847
 plain/utils/inspect.py,sha256=wbWDAiVa4MW4lwJZz-mvU8Db-I0Nq5DhHh9ew5w81EE,1480
 plain/utils/ipv6.py,sha256=TLOQVN0aqKGM4eS_HwarTgO-bGIql-k5AipDPgtQdCA,1352
@@ -188,8 +188,8 @@ plain/views/forms.py,sha256=ESZOXuo6IeYixp1RZvPb94KplkowRiwO2eGJCM6zJI0,2400
 plain/views/objects.py,sha256=5y0PoPPo07dQTTcJ_9kZcx0iI1O7regsooAIK4VqXQ0,5579
 plain/views/redirect.py,sha256=mIpSAFcaEyeLDyv4Fr6g_ektduG4Wfa6s6L-rkdazmM,2154
 plain/views/templates.py,sha256=9LgDMCv4C7JzLiyw8jHF-i4350ukwgixC_9y4faEGu0,1885
-plain-0.82.0.dist-info/METADATA,sha256=Az4gbY6JEIaJb3xC12DeYjEl2fezGU6GXHx64Ku1WLs,4516
-plain-0.82.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-plain-0.82.0.dist-info/entry_points.txt,sha256=1Ys2lsSeMepD1vz8RSrJopna0RQfUd951vYvCRsvl6A,45
-plain-0.82.0.dist-info/licenses/LICENSE,sha256=m0D5O7QoH9l5Vz_rrX_9r-C8d9UNr_ciK6Qwac7o6yo,3175
-plain-0.82.0.dist-info/RECORD,,
+plain-0.84.0.dist-info/METADATA,sha256=UQ9z1_Z0yZvZ2Gj5xnSE75cfoPSH4Ia05Rc3NKaVFng,4516
+plain-0.84.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+plain-0.84.0.dist-info/entry_points.txt,sha256=1Ys2lsSeMepD1vz8RSrJopna0RQfUd951vYvCRsvl6A,45
+plain-0.84.0.dist-info/licenses/LICENSE,sha256=m0D5O7QoH9l5Vz_rrX_9r-C8d9UNr_ciK6Qwac7o6yo,3175
+plain-0.84.0.dist-info/RECORD,,