django-datastar 0.1.0__py3-none-any.whl

django_datastar/__init__.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+from .middleware import DatastarDetails
+from .middleware import DatastarHttpRequest
+from .middleware import DatastarMiddleware
+from .middleware import is_datastar
+
+__all__ = [
+    "DatastarDetails",
+    "DatastarHttpRequest",
+    "DatastarMiddleware",
+    "is_datastar",
+]

django_datastar/apps.py

@@ -0,0 +1,8 @@
+from __future__ import annotations
+
+from django.apps import AppConfig
+
+
+class DjangoDatastarConfig(AppConfig):
+    name = "django_datastar"
+    verbose_name = "Django Datastar"

django_datastar/middleware.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+from collections.abc import Awaitable
+from collections.abc import Callable
+from typing import cast
+
+from asgiref.sync import iscoroutinefunction
+from asgiref.sync import markcoroutinefunction
+from django.http import HttpRequest
+from django.http.response import HttpResponseBase
+
+_SyncGetResponse = Callable[[HttpRequest], HttpResponseBase]
+_AsyncGetResponse = Callable[[HttpRequest], Awaitable[HttpResponseBase]]
+_GetResponse = _SyncGetResponse | _AsyncGetResponse
+
+
+def is_datastar(request: HttpRequest) -> bool:
+    """Return whether a request has Datastar's canonical marker header.
+
+    The marker is client-controlled and must not authorize a request or bypass
+    CSRF. Cacheable views that vary by this result should use
+    ``@vary_on_headers("Datastar-Request")``.
+    """
+    return request.headers.get("Datastar-Request") == "true"
+
+
+class DatastarDetails:
+    """Datastar metadata attached to a Django request."""
+
+    def __init__(self, request: HttpRequest) -> None:
+        self.request = request
+
+    def __bool__(self) -> bool:
+        return is_datastar(self.request)
+
+
+class DatastarHttpRequest(HttpRequest):
+    """Typing contract for a request processed by :class:`DatastarMiddleware`.
+
+    Django continues to create the request object. Use this class as a view
+    annotation when the middleware is installed; do not use it for runtime
+    ``isinstance`` checks.
+    """
+
+    datastar: DatastarDetails
+
+
+class DatastarMiddleware:
+    """Attach Datastar request metadata in sync and async middleware chains."""
+
+    sync_capable = True
+    async_capable = True
+
+    def __init__(self, get_response: _GetResponse) -> None:
+        self.get_response = get_response
+        self._async_mode = iscoroutinefunction(get_response)
+
+        if self._async_mode:
+            markcoroutinefunction(self)
+
+    def __call__(
+        self,
+        request: HttpRequest,
+    ) -> HttpResponseBase | Awaitable[HttpResponseBase]:
+        if self._async_mode:
+            return self.__acall__(request)
+
+        self._attach_details(request)
+        get_response = cast("_SyncGetResponse", self.get_response)
+        return get_response(request)
+
+    async def __acall__(self, request: HttpRequest) -> HttpResponseBase:
+        self._attach_details(request)
+        get_response = cast("_AsyncGetResponse", self.get_response)
+        return await get_response(request)
+
+    @staticmethod
+    def _attach_details(request: HttpRequest) -> None:
+        typed_request = cast("DatastarHttpRequest", request)
+        typed_request.datastar = DatastarDetails(request)

django_datastar/static/django_datastar/datastar-csrf.js

@@ -0,0 +1,154 @@
+const BRIDGE_INSTALLATION = Symbol.for("django-datastar.csrf-bridge");
+const CSRF_HEADER = "X-CSRFToken";
+const CSRF_META_SELECTOR = 'meta[name="datastar-csrf-token"]';
+const DATASTAR_REQUEST_HEADER = "Datastar-Request";
+const SAFE_METHODS = new Set(["GET", "HEAD", "OPTIONS", "TRACE"]);
+const REQUEST_URL_GETTER = Object.getOwnPropertyDescriptor(
+  Request.prototype,
+  "url",
+).get;
+
+function installDatastarCsrfBridge() {
+  if (window[BRIDGE_INSTALLATION]) {
+    return;
+  }
+
+  const nativeFetch = window.fetch.bind(window);
+  window.fetch = createDatastarCsrfFetch(nativeFetch);
+  Object.defineProperty(window, BRIDGE_INSTALLATION, { value: true });
+}
+
+function createDatastarCsrfFetch(nativeFetch) {
+  return (...args) => {
+    const [input, init] = args;
+    let csrfInit;
+
+    try {
+      csrfInit = csrfRequestInitFor(input, init);
+    } catch {
+      return nativeFetch(...args);
+    }
+
+    if (!csrfInit) {
+      return nativeFetch(...args);
+    }
+
+    return nativeFetch(input, csrfInit);
+  };
+}
+
+function csrfRequestInitFor(input, init) {
+  if (hasAccessorRequestInitMember(init)) {
+    return null;
+  }
+
+  const request = effectiveRequest(input, init);
+  if (!requiresCsrfHeader(request)) {
+    return null;
+  }
+
+  const token = csrfTokenFromDom();
+  return token ? withCsrfHeader(init, request.headers, token) : null;
+}
+
+function effectiveRequest(input, init) {
+  return {
+    input,
+    init,
+    headers: effectiveHeaders(input, init),
+    method: effectiveMethod(input, init),
+    url: effectiveUrl(input),
+  };
+}
+
+function requiresCsrfHeader(request) {
+  return (
+    request.headers.get(DATASTAR_REQUEST_HEADER) === "true" &&
+    !request.headers.has(CSRF_HEADER) &&
+    !SAFE_METHODS.has(request.method) &&
+    request.url.origin === window.location.origin &&
+    hasCompatibleMode(request.input, request.init)
+  );
+}
+
+function withCsrfHeader(init, headers, token) {
+  headers.set(CSRF_HEADER, token);
+  const csrfInit = Object.create(init ?? null);
+  Object.defineProperties(csrfInit, {
+    headers: { enumerable: true, value: headers },
+    mode: { enumerable: true, value: "same-origin" },
+  });
+  return csrfInit;
+}
+
+function effectiveHeaders(input, init) {
+  if (init?.headers !== undefined) {
+    return new Headers(init.headers);
+  }
+
+  return new Headers(isRequest(input) ? input.headers : undefined);
+}
+
+function effectiveMethod(input, init) {
+  const initMethod = init?.method;
+  const method =
+    initMethod !== undefined
+      ? initMethod
+      : isRequest(input)
+        ? input.method
+        : "GET";
+  return String(method).toUpperCase();
+}
+
+function effectiveUrl(input) {
+  const url = isRequest(input) ? input.url : input;
+  return new URL(url, document.baseURI);
+}
+
+function hasCompatibleMode(input, init) {
+  if (init?.mode !== undefined) {
+    return init.mode === "same-origin";
+  }
+
+  return !isRequest(input) || input.mode === "same-origin";
+}
+
+function csrfTokenFromDom() {
+  return document.querySelector(CSRF_META_SELECTOR)?.getAttribute("content") || "";
+}
+
+function hasAccessorRequestInitMember(init) {
+  if (init === undefined || init === null) {
+    return false;
+  }
+
+  if (typeof init !== "object" && typeof init !== "function") {
+    return true;
+  }
+
+  let owner = init;
+  while (owner !== null && owner !== Object.prototype) {
+    const descriptors = Object.values(Object.getOwnPropertyDescriptors(owner));
+    if (
+      descriptors.some(
+        (descriptor) =>
+          descriptor.get !== undefined || descriptor.set !== undefined,
+      )
+    ) {
+      return true;
+    }
+    owner = Object.getPrototypeOf(owner);
+  }
+  return false;
+}
+
+function isRequest(input) {
+  try {
+    REQUEST_URL_GETTER.call(input);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+installDatastarCsrfBridge();

django_datastar/templatetags/django_datastar.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+from django import template
+from django.http import HttpRequest
+from django.middleware.csrf import get_token
+from django.templatetags.static import static
+from django.utils.html import escape
+from django.utils.html import format_html
+from django.utils.safestring import SafeString
+
+register = template.Library()
+
+
+@register.simple_tag(takes_context=True)
+def datastar_csrf(
+    context: template.Context,
+    nonce: object | None = None,
+) -> SafeString:
+    """Render the masked CSRF token and Datastar fetch bridge module."""
+    request = getattr(context, "request", None)
+    if not isinstance(request, HttpRequest):
+        raise template.TemplateSyntaxError(
+            "{% datastar_csrf %} requires a request-aware template context."
+        )
+
+    token = get_token(request)
+    meta = format_html(
+        '<meta name="datastar-csrf-token" content="{}" />',
+        token,
+    )
+    script_url = static("django_datastar/datastar-csrf.js")
+    script = _script_element(script_url, nonce)
+    return format_html("{}\n{}", meta, script)
+
+
+def _script_element(script_url: str, nonce: object | None) -> SafeString:
+    if nonce is None:
+        return format_html('<script type="module" src="{}"></script>', script_url)
+
+    return format_html(
+        '<script type="module" src="{}" nonce="{}"></script>',
+        script_url,
+        escape(nonce),
+    )

django_datastar-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,11 @@
+django_datastar/__init__.py,sha256=QbtE3iNVEFRlzsgHTYKgTz5Evu54T9Qval0bFhEfl7E,309
+django_datastar/apps.py,sha256=dbFIfNS4ZE83SmfWJHvW23TjbVX3vbyXYfM5Ry1J8sg,177
+django_datastar/middleware.py,sha256=iFqFL4ht_DSuUlopnC8R6A6h-SEI5bxygiZph9v170g,2603
+django_datastar/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+django_datastar/static/django_datastar/datastar-csrf.js,sha256=Q_JAxGJTena94Dtl0FIN9rrueJBlkcuQI6XKUClsX1U,3755
+django_datastar/templatetags/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+django_datastar/templatetags/django_datastar.py,sha256=tpWwrDRCZYf-zjvvulVoeC44Hi1EtjEs0KSn-cC9BhA,1398
+django_datastar-0.1.0.dist-info/METADATA,sha256=BhIeJ9cJRGS_4YDfNJd1wVC2vaD3SHBvDjQpPZ3Ar9A,4943
+django_datastar-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+django_datastar-0.1.0.dist-info/licenses/LICENSE,sha256=STFRmHA7eloSbM0gNFGVzABChKCG84hCoJhQPzXuoKI,1070
+django_datastar-0.1.0.dist-info/RECORD,,

django_datastar-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

django_datastar-0.1.0.dist-info/licenses/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.