django-datastar 0.1.0__tar.gz

django_datastar-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+.coverage
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.venv/
+__pycache__/
+build/
+dist/
+docs/_build/
+*.egg-info/

django_datastar-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Marcus A. Lee
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

django_datastar-0.1.0/PKG-INFO

@@ -0,0 +1,170 @@
+Metadata-Version: 2.5
+Name: django-datastar
+Version: 0.1.0
+Summary: Request metadata and opt-in CSRF integration for Django and Datastar
+Project-URL: Documentation, https://django-datastar.readthedocs.io/
+Project-URL: Repository, https://github.com/MarcusL11/django_datastar
+Project-URL: Issues, https://github.com/MarcusL11/django_datastar/issues
+Author-email: "Marcus A. Lee" <hello@marcusalee.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 5.2
+Classifier: Framework :: Django :: 6.0
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: django<6.1,>=5.2
+Provides-Extra: docs
+Requires-Dist: furo>=2024.8.6; extra == 'docs'
+Requires-Dist: sphinx>=8.1; extra == 'docs'
+Provides-Extra: tests
+Requires-Dist: django-stubs>=5.2; extra == 'tests'
+Requires-Dist: mypy>=1.15; extra == 'tests'
+Requires-Dist: pytest-django>=4.10; extra == 'tests'
+Requires-Dist: pytest>=8.3; extra == 'tests'
+Description-Content-Type: text/markdown
+
+# django-datastar
+
+`django-datastar` provides small, focused integration points between Django and
+[Datastar](https://data-star.dev/):
+
+- exact request classification through `Datastar-Request: true`;
+- sync/async middleware-backed `request.datastar` metadata; and
+- an opt-in bridge that supplies Django CSRF tokens to qualifying Datastar
+  backend-action requests.
+
+It does not provide Datastar response or SSE APIs. Use
+[`datastar-py`](https://github.com/starfederation/datastar/tree/main/sdk/python)
+as a companion when those APIs are needed.
+
+> The `Datastar-Request` header is client-controlled metadata. Never use it for
+> authentication, authorization, permissions, or a CSRF bypass.
+
+## Installation
+
+Install the package from PyPI:
+
+```console
+python -m pip install django-datastar
+```
+
+To install a development checkout instead, run `python -m pip install .` from
+the repository root.
+
+Add the middleware before Django's CSRF middleware:
+
+```python
+MIDDLEWARE = [
+    # ...
+    "django_datastar.middleware.DatastarMiddleware",
+    "django.middleware.csrf.CsrfViewMiddleware",
+    # ...
+]
+```
+
+Use either the helper or the attached details in a view:
+
+```python
+from django.http import HttpResponse
+from django_datastar import DatastarHttpRequest
+
+
+def update(request: DatastarHttpRequest) -> HttpResponse:
+    if request.datastar:
+        return HttpResponse("Datastar request")
+    return HttpResponse("ordinary request")
+```
+
+`DatastarHttpRequest` is an annotation for requests processed by the middleware;
+Django still creates the actual request object.
+
+When middleware-backed request details are not needed, classify a request directly:
+
+```python
+from django.http import HttpRequest
+from django.http import HttpResponse
+from django_datastar import is_datastar
+
+
+def update(request: HttpRequest) -> HttpResponse:
+    if is_datastar(request):
+        return HttpResponse("Datastar request")
+    return HttpResponse("ordinary request")
+```
+
+## Automatic CSRF headers
+
+The bridge is optional. Add the app when you want its template tag and static
+module:
+
+```python
+INSTALLED_APPS = [
+    # ...
+    "django_datastar",
+]
+```
+
+Load the tag before your chosen Datastar bundle:
+
+```django
+{% load django_datastar static %}
+
+{% datastar_csrf %}
+<script type="module" src="{% static 'js/datastar.js' %}"></script>
+```
+
+For nonce-based Content Security Policies:
+
+```django
+{% datastar_csrf nonce=request.csp_nonce %}
+```
+
+The tag calls Django's CSRF token machinery and emits a masked token in the DOM,
+so it works with `CSRF_COOKIE_HTTPONLY=True`. The external module reads that token
+at request time and injects `X-CSRFToken` only when all of these conditions hold:
+
+- the effective method is unsafe;
+- `Datastar-Request` is exactly `true`;
+- the effective target is same-origin;
+- the request mode is compatible with `same-origin`;
+- no CSRF header was supplied explicitly; and
+- a DOM token is present.
+
+Django's `CsrfViewMiddleware` remains solely responsible for validation. The
+bridge assumes Datastar resolves `window.fetch` at request time; see the
+[compatibility documentation](https://django-datastar.readthedocs.io/en/latest/compatibility.html)
+before upgrading Datastar.
+
+## Documentation
+
+Build the documentation locally with:
+
+```console
+python -m pip install ".[docs]"
+sphinx-build -W --keep-going -b html docs docs/_build/html
+```
+
+## Development
+
+```console
+uv sync --group dev
+uv run pytest
+node --test tests/test_datastar_csrf.mjs
+uv run ruff check .
+uv run ruff format --check .
+uv run mypy
+```
+
+Node is contributor and CI tooling only. It is not a runtime dependency for
+Django applications.
+
+## License
+
+MIT

django_datastar-0.1.0/README.md

@@ -0,0 +1,138 @@
+# django-datastar
+
+`django-datastar` provides small, focused integration points between Django and
+[Datastar](https://data-star.dev/):
+
+- exact request classification through `Datastar-Request: true`;
+- sync/async middleware-backed `request.datastar` metadata; and
+- an opt-in bridge that supplies Django CSRF tokens to qualifying Datastar
+  backend-action requests.
+
+It does not provide Datastar response or SSE APIs. Use
+[`datastar-py`](https://github.com/starfederation/datastar/tree/main/sdk/python)
+as a companion when those APIs are needed.
+
+> The `Datastar-Request` header is client-controlled metadata. Never use it for
+> authentication, authorization, permissions, or a CSRF bypass.
+
+## Installation
+
+Install the package from PyPI:
+
+```console
+python -m pip install django-datastar
+```
+
+To install a development checkout instead, run `python -m pip install .` from
+the repository root.
+
+Add the middleware before Django's CSRF middleware:
+
+```python
+MIDDLEWARE = [
+    # ...
+    "django_datastar.middleware.DatastarMiddleware",
+    "django.middleware.csrf.CsrfViewMiddleware",
+    # ...
+]
+```
+
+Use either the helper or the attached details in a view:
+
+```python
+from django.http import HttpResponse
+from django_datastar import DatastarHttpRequest
+
+
+def update(request: DatastarHttpRequest) -> HttpResponse:
+    if request.datastar:
+        return HttpResponse("Datastar request")
+    return HttpResponse("ordinary request")
+```
+
+`DatastarHttpRequest` is an annotation for requests processed by the middleware;
+Django still creates the actual request object.
+
+When middleware-backed request details are not needed, classify a request directly:
+
+```python
+from django.http import HttpRequest
+from django.http import HttpResponse
+from django_datastar import is_datastar
+
+
+def update(request: HttpRequest) -> HttpResponse:
+    if is_datastar(request):
+        return HttpResponse("Datastar request")
+    return HttpResponse("ordinary request")
+```
+
+## Automatic CSRF headers
+
+The bridge is optional. Add the app when you want its template tag and static
+module:
+
+```python
+INSTALLED_APPS = [
+    # ...
+    "django_datastar",
+]
+```
+
+Load the tag before your chosen Datastar bundle:
+
+```django
+{% load django_datastar static %}
+
+{% datastar_csrf %}
+<script type="module" src="{% static 'js/datastar.js' %}"></script>
+```
+
+For nonce-based Content Security Policies:
+
+```django
+{% datastar_csrf nonce=request.csp_nonce %}
+```
+
+The tag calls Django's CSRF token machinery and emits a masked token in the DOM,
+so it works with `CSRF_COOKIE_HTTPONLY=True`. The external module reads that token
+at request time and injects `X-CSRFToken` only when all of these conditions hold:
+
+- the effective method is unsafe;
+- `Datastar-Request` is exactly `true`;
+- the effective target is same-origin;
+- the request mode is compatible with `same-origin`;
+- no CSRF header was supplied explicitly; and
+- a DOM token is present.
+
+Django's `CsrfViewMiddleware` remains solely responsible for validation. The
+bridge assumes Datastar resolves `window.fetch` at request time; see the
+[compatibility documentation](https://django-datastar.readthedocs.io/en/latest/compatibility.html)
+before upgrading Datastar.
+
+## Documentation
+
+Build the documentation locally with:
+
+```console
+python -m pip install ".[docs]"
+sphinx-build -W --keep-going -b html docs docs/_build/html
+```
+
+## Development
+
+```console
+uv sync --group dev
+uv run pytest
+node --test tests/test_datastar_csrf.mjs
+uv run ruff check .
+uv run ruff format --check .
+uv run mypy
+```
+
+Node is contributor and CI tooling only. It is not a runtime dependency for
+Django applications.
+
+## License
+
+MIT

django_datastar-0.1.0/docs/api.rst

@@ -0,0 +1,13 @@
+API reference
+=============
+
+.. autofunction:: django_datastar.is_datastar
+
+.. autoclass:: django_datastar.DatastarDetails
+   :members:
+
+.. autoclass:: django_datastar.DatastarHttpRequest
+   :members:
+
+.. autoclass:: django_datastar.DatastarMiddleware
+   :members:

django_datastar-0.1.0/docs/compatibility.rst

@@ -0,0 +1,63 @@
+Compatibility
+=============
+
+Supported matrix
+----------------
+
+The initial compatibility target is:
+
+.. list-table::
+   :header-rows: 1
+
+   * - Python
+     - Django 5.2
+     - Django 6.0
+   * - 3.12
+     - tested
+     - tested
+   * - 3.13
+     - tested
+     - tested
+   * - 3.14
+     - tested
+     - tested
+
+All six combinations pass locally and in CI against the built wheel. The
+runtime dependency is ``Django>=5.2,<6.1``. Node 20 and 22 test the JavaScript
+extracted from the wheel in CI; consuming Django projects do not need Node.
+
+Datastar and global fetch
+-------------------------
+
+The CSRF bridge wraps ``window.fetch`` before the consumer's Datastar module
+loads. Compatibility therefore assumes that the Datastar bundle resolves the
+global fetch function when it sends a request rather than capturing an earlier
+reference or using another transport.
+
+Keep the bridge script before Datastar and repeat a real-browser Network-panel
+check when upgrading Datastar. Confirm that an unsafe same-origin backend action
+contains both ``Datastar-Request: true`` and ``X-CSRFToken`` and is accepted by
+Django.
+
+Companion Python package
+------------------------
+
+``datastar-py`` supplies response and SSE helpers and can be installed
+separately. This package neither imports nor pins it.
+
+Extraction acceptance
+---------------------
+
+Before the first release, build a wheel and install it into the original Django
+application that proved the behavior. Replace the local middleware and static
+bridge with the package, render ``{% datastar_csrf %}``, and run that
+application's focused tests, Node tests, full suite, lint, formatting, Django
+checks, and staticfiles collection.
+
+Then repeat the real-browser backend-action check. Verify the exact marker and
+masked CSRF header, successful Django response, truthy ``request.datastar``, and
+continued rejection of missing or invalid tokens. Include a temporary
+same-origin endpoint that redirects to a second local origin: the qualifying
+fetch must reject in ``same-origin`` mode, and the second origin must receive
+neither the redirected request nor the CSRF header. Do not remove the local
+implementation until the package-backed path passes.

django_datastar-0.1.0/docs/conf.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+from importlib.metadata import version as package_version
+
+project = "django-datastar"
+author = "Marcus A. Lee"
+release = package_version("django-datastar")
+version = release
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.intersphinx",
+]
+
+intersphinx_mapping = {
+    "django": ("https://docs.djangoproject.com/en/stable/", None),
+    "python": ("https://docs.python.org/3/", None),
+}
+
+templates_path = ["_templates"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+html_theme = "furo"

django_datastar-0.1.0/docs/csrf.rst

@@ -0,0 +1,64 @@
+Automatic CSRF bridge
+=====================
+
+Django's ``CsrfViewMiddleware`` remains authoritative. This bridge does not
+validate tokens, exempt views, or bypass Django's protection. It only supplies
+a masked token to a narrow class of requests.
+
+Template setup
+--------------
+
+Load the package tag and render it before the consumer's Datastar module:
+
+.. code-block:: django
+
+   {% load django_datastar static %}
+
+   {% datastar_csrf %}
+   <script type="module" src="{% static 'js/datastar.js' %}"></script>
+
+The tag requires a request-aware template context. It calls Django's
+``get_token(request)`` and renders:
+
+* ``<meta name="datastar-csrf-token" ...>`` containing the escaped masked token;
+* the namespaced ``django_datastar/datastar-csrf.js`` external module.
+
+Calling Django's token machinery maintains the CSRF cookie and ``Vary: Cookie``
+response behavior. Because JavaScript reads the masked DOM token rather than the
+cookie, ``CSRF_COOKIE_HTTPONLY=True`` is supported.
+
+The order is required: the bridge wraps ``window.fetch``, so it must execute
+before Datastar's module initializes.
+
+Content Security Policy
+-----------------------
+
+A conventional ``script-src 'self'`` policy can permit the packaged same-origin
+external module. For a nonce-based policy, pass the nonce explicitly:
+
+.. code-block:: django
+
+   {% datastar_csrf nonce=request.csp_nonce %}
+
+The nonce value is escaped as an HTML attribute. The package emits no inline
+JavaScript. Applications remain responsible for their complete CSP and for
+configuring their static asset origin.
+
+Injection rules
+---------------
+
+The bridge adds ``X-CSRFToken`` only when the effective request:
+
+* uses an unsafe method;
+* has ``Datastar-Request`` with the exact value ``true``;
+* targets ``window.location.origin``;
+* has a request mode compatible with ``same-origin``;
+* has no explicit case-insensitive CSRF header; and
+* has a current DOM token.
+
+It resolves URL, method, headers, and mode from both ``Request`` input and
+``fetch`` init overrides. Token-bearing requests use or preserve
+``mode: "same-origin"``. Accessor-backed ``RequestInit`` members are left to
+native ``fetch`` unchanged rather than being read or rebound by the bridge. If
+the request cannot be safely inspected or transformed, ordinary ``fetch``
+behavior is used without modifying the input.

django_datastar-0.1.0/docs/index.rst

@@ -0,0 +1,23 @@
+django-datastar
+===============
+
+``django-datastar`` provides request metadata and an opt-in automatic CSRF
+bridge for Django applications using Datastar.
+
+It deliberately does not duplicate Datastar response or SSE APIs. The
+``datastar-py`` project can be used alongside it when those APIs are needed.
+
+.. warning::
+
+   ``Datastar-Request: true`` is client-controlled metadata. It is never an
+   authentication, authorization, permission, or CSRF boundary.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents
+
+   installation
+   csrf
+   security
+   compatibility
+   api

django_datastar-0.1.0/docs/installation.rst

@@ -0,0 +1,80 @@
+Installation
+============
+
+Install the package from PyPI:
+
+.. code-block:: console
+
+   python -m pip install django-datastar
+
+To install a development checkout instead, run ``python -m pip install .`` from
+the repository root.
+
+Request metadata
+----------------
+
+Add the middleware before Django's CSRF middleware:
+
+.. code-block:: python
+
+   MIDDLEWARE = [
+       # ...
+       "django_datastar.middleware.DatastarMiddleware",
+       "django.middleware.csrf.CsrfViewMiddleware",
+       # ...
+   ]
+
+Every request that reaches the rest of the middleware chain then has a
+``datastar`` details object. Its truth value is true only when the
+``Datastar-Request`` header value is exactly ``true``.
+
+For a typed view annotation:
+
+.. code-block:: python
+
+   from django.http import HttpResponse
+   from django_datastar import DatastarHttpRequest
+
+   def update(request: DatastarHttpRequest) -> HttpResponse:
+       if request.datastar:
+           return HttpResponse("Datastar request")
+       return HttpResponse("ordinary request")
+
+``DatastarHttpRequest`` describes the middleware-added attribute for type
+checkers. Django continues to construct its normal request object; do not use
+the annotation class as a runtime ``isinstance`` test.
+
+Direct request classification
+-----------------------------
+
+Use ``is_datastar`` when middleware-backed request details are not needed:
+
+.. code-block:: python
+
+   from django.http import HttpRequest
+   from django.http import HttpResponse
+   from django_datastar import is_datastar
+
+   def update(request: HttpRequest) -> HttpResponse:
+       if is_datastar(request):
+           return HttpResponse("Datastar request")
+       return HttpResponse("ordinary request")
+
+The helper and ``request.datastar`` use the same exact, case-sensitive header
+check. The header remains client-controlled metadata and must not authorize a
+request or bypass CSRF protection.
+
+Optional CSRF bridge
+--------------------
+
+To use the template tag and packaged static module, add the app:
+
+.. code-block:: python
+
+   INSTALLED_APPS = [
+       # ...
+       "django_datastar",
+   ]
+
+Django's ``staticfiles`` app and a normal staticfiles deployment are required.
+Continue with :doc:`csrf` for template setup.

django_datastar-0.1.0/docs/security.rst

@@ -0,0 +1,43 @@
+Security
+========
+
+Untrusted marker
+----------------
+
+The ``Datastar-Request`` header can be sent by any client. Its exact ``true``
+value identifies the request format; it does not prove that Datastar, this
+package, or a trusted browser originated the request.
+
+Never use the marker or ``request.datastar`` to:
+
+* authenticate a user;
+* grant a permission;
+* authorize an operation;
+* skip CSRF checks; or
+* weaken any other security control.
+
+Normal Django authentication, authorization, method, origin, and CSRF controls
+must still run.
+
+CSRF authority
+--------------
+
+``CsrfViewMiddleware`` performs all server-side CSRF validation. A missing,
+invalid, or inapplicable token is rejected exactly as it would be without this
+package. Do not decorate Datastar endpoints with ``csrf_exempt`` merely because
+the bridge is installed.
+
+Header disclosure boundary
+--------------------------
+
+The browser bridge limits token injection to same-origin effective targets and
+sets ``mode: "same-origin"``. Cross-origin, explicitly incompatible-mode, safe,
+unmarked, and uninspectable requests pass through unchanged. Explicit CSRF
+headers always win and are not validated or replaced by the bridge.
+
+Caching
+-------
+
+If a cacheable response changes according to ``request.datastar``, include the
+marker in the cache key, for example with Django's
+``vary_on_headers("Datastar-Request")`` decorator.