kernia-django 0.1.0__tar.gz

kernia_django-0.1.0/.gitignore

@@ -0,0 +1,38 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+.uv/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+dist/
+build/
+
+# Editors
+.idea/
+.vscode/
+*.swp
+.DS_Store
+
+# Docs build output
+/site/
+docs/site/
+
+# Internal tooling (not part of the public repo)
+scripts/audit_layout.py
+scripts/setup_kernia_dns.sh
+spec/
+
+# Local
+
+.projects/cache
+.projects/vault
+.projects/state.test.json
+.projects/state.local.test.json
+.env
+.env.local
+.env.test

kernia_django-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Advantch
+
+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.

kernia_django-0.1.0/PKG-INFO

@@ -0,0 +1,72 @@
+Metadata-Version: 2.4
+Name: kernia-django
+Version: 0.1.0
+Summary: Django integration
+Project-URL: Homepage, https://kernia.dev
+Project-URL: Documentation, https://kernia.dev/docs
+Project-URL: Source, https://github.com/advantch/kernia
+Project-URL: Issues, https://github.com/advantch/kernia/issues
+Project-URL: Changelog, https://github.com/advantch/kernia/releases
+Author: Advantch
+License-Expression: MIT
+License-File: LICENSE
+Keywords: asgi,authentication,authorization,django,fastapi,oauth,passkeys,security,sessions,sso,starlette
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP :: Session
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: anyio>=4
+Requires-Dist: django>=4.2
+Requires-Dist: kernia>=0.1.0
+Description-Content-Type: text/markdown
+
+# kernia-django
+
+Django integration for Kernia. Mounts the auth router, populates `request.kernia_session` and `request.kernia_user`, and provides a view decorator for protected views.
+
+Part of [Kernia](https://kernia.dev), a framework-agnostic authentication library for Python.
+
+## Installation
+
+    pip install kernia-django
+
+## Usage
+
+Add the app to `INSTALLED_APPS` and the middleware, then splice the auth routes into `urls.py`:
+
+```python
+# urls.py
+from django.urls import path
+from kernia_django import setup
+from myproject.auth import auth   # your init(KerniaOptions(...)) instance
+
+urlpatterns = [
+    *setup(auth, url_prefix="/api/auth"),
+]
+```
+
+```python
+# views.py
+from kernia_django import require_session
+
+@require_session
+def me(request):
+    return JsonResponse({"user_id": request.kernia_user["id"]})
+```
+
+Django is sync-by-default; the bridge uses `asgiref.sync.async_to_sync` to call the async core.
+
+## Documentation
+
+Full documentation at [kernia.dev/docs](https://kernia.dev/docs). Source at [github.com/advantch/kernia](https://github.com/advantch/kernia).
+
+## License
+
+MIT

kernia_django-0.1.0/README.md

@@ -0,0 +1,43 @@
+# kernia-django
+
+Django integration for Kernia. Mounts the auth router, populates `request.kernia_session` and `request.kernia_user`, and provides a view decorator for protected views.
+
+Part of [Kernia](https://kernia.dev), a framework-agnostic authentication library for Python.
+
+## Installation
+
+    pip install kernia-django
+
+## Usage
+
+Add the app to `INSTALLED_APPS` and the middleware, then splice the auth routes into `urls.py`:
+
+```python
+# urls.py
+from django.urls import path
+from kernia_django import setup
+from myproject.auth import auth   # your init(KerniaOptions(...)) instance
+
+urlpatterns = [
+    *setup(auth, url_prefix="/api/auth"),
+]
+```
+
+```python
+# views.py
+from kernia_django import require_session
+
+@require_session
+def me(request):
+    return JsonResponse({"user_id": request.kernia_user["id"]})
+```
+
+Django is sync-by-default; the bridge uses `asgiref.sync.async_to_sync` to call the async core.
+
+## Documentation
+
+Full documentation at [kernia.dev/docs](https://kernia.dev/docs). Source at [github.com/advantch/kernia](https://github.com/advantch/kernia).
+
+## License
+
+MIT

kernia_django-0.1.0/pyproject.toml

@@ -0,0 +1,56 @@
+[project]
+name = "kernia-django"
+version = "0.1.0"
+description = "Django integration"
+requires-python = ">=3.11"
+dependencies = [
+    "kernia>=0.1.0",
+    "django>=4.2",
+    "anyio>=4",
+]
+readme = "README.md"
+license = "MIT"
+license-files = [
+    "LICENSE",
+]
+authors = [
+    {name = "Advantch"},
+]
+keywords = [
+    "authentication",
+    "authorization",
+    "sessions",
+    "oauth",
+    "passkeys",
+    "sso",
+    "asgi",
+    "fastapi",
+    "starlette",
+    "django",
+    "security",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Internet :: WWW/HTTP :: Session",
+    "Topic :: Security",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://kernia.dev"
+Documentation = "https://kernia.dev/docs"
+Source = "https://github.com/advantch/kernia"
+Issues = "https://github.com/advantch/kernia/issues"
+Changelog = "https://github.com/advantch/kernia/releases"
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/kernia_django"]

kernia_django-0.1.0/src/kernia_django/__init__.py

@@ -0,0 +1,29 @@
+"""Django integration for Kernia.
+
+Public surface:
+
+* :class:`apps.KerniaConfig` — Django app config (add to ``INSTALLED_APPS``).
+* :class:`middleware.KerniaMiddleware` — populates
+  ``request.kernia_session`` / ``request.kernia_user``.
+* :func:`decorators.require_session` — 401-JSON view decorator.
+* :class:`views.KerniaView` — class-based view that forwards to the
+  Kernia ASGI router.
+* :func:`setup` — convenience that returns urlpatterns for the auth router.
+
+Django is sync-by-default; the bridge uses ``asgiref.sync.async_to_sync`` to
+call the async core. Each Kernia request pays one thread hop.
+"""
+
+from kernia_django.decorators import require_session
+from kernia_django.middleware import KerniaMiddleware
+from kernia_django.views import KerniaView, setup
+
+default_app_config = "kernia_django.apps.KerniaConfig"
+
+__all__ = [
+    "KerniaMiddleware",
+    "KerniaView",
+    "default_app_config",
+    "require_session",
+    "setup",
+]

kernia_django-0.1.0/src/kernia_django/apps.py

@@ -0,0 +1,24 @@
+"""Django app config for kernia-django.
+
+Importing this module triggers no Django machinery; the config is only loaded
+once the user adds ``kernia_django`` to ``INSTALLED_APPS``.
+"""
+
+from __future__ import annotations
+
+from django.apps import AppConfig
+
+
+class KerniaConfig(AppConfig):
+    """Standard Django app config — no ready-hook side effects.
+
+    The auth instance lives on whatever the user passes into ``setup()`` /
+    ``KerniaView.as_view(auth=...)``. We deliberately don't read it from
+    settings here so users can construct the ``Kernia`` object at module
+    load time without forcing a Django settings dependency on the core.
+    """
+
+    name = "kernia_django"
+    label = "kernia_django"
+    verbose_name = "Better Auth"
+    default_auto_field = "django.db.models.BigAutoField"

kernia_django-0.1.0/src/kernia_django/decorators.py

@@ -0,0 +1,27 @@
+"""View decorators."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from functools import wraps
+from typing import Any
+
+from django.http import HttpRequest, JsonResponse
+
+
+def require_session(view_func: Callable[..., Any]) -> Callable[..., Any]:
+    """Return 401 JSON if ``request.kernia_session`` is not set.
+
+    Relies on :class:`KerniaMiddleware` having already populated the
+    attribute. Without the middleware in ``MIDDLEWARE`` the attribute will not
+    exist; we treat that as unauthenticated as well (fail-closed).
+    """
+
+    @wraps(view_func)
+    def wrapper(request: HttpRequest, *args: Any, **kwargs: Any) -> Any:
+        session = getattr(request, "kernia_session", None)
+        if session is None:
+            return JsonResponse({"error": "UNAUTHORIZED"}, status=401)
+        return view_func(request, *args, **kwargs)
+
+    return wrapper

kernia_django-0.1.0/src/kernia_django/middleware.py

@@ -0,0 +1,83 @@
+"""Django middleware that hydrates ``request.kernia_session``.
+
+The middleware reads the session cookie, resolves it through the Kernia
+core, and attaches the result (which may be ``None``) under a dedicated
+namespace so Django's own auth/session stack remains untouched.
+
+Because Django middleware runs sync by default, we cross the async boundary
+with :func:`asgiref.sync.async_to_sync`. That is a thread hop per request —
+the same trade-off documented on :class:`KerniaView`.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from asgiref.sync import async_to_sync
+from django.http import HttpRequest
+from django.utils.deprecation import MiddlewareMixin
+from kernia.auth import Kernia
+from kernia.integrations.session import (
+    SESSION_COOKIE_NAME,
+    resolve_session,
+)
+
+
+class KerniaMiddleware(MiddlewareMixin):
+    """Attach ``request.kernia_session`` and ``request.kernia_user``.
+
+    The auth instance is sourced from ``settings.KERNIA`` (the user's
+    own ``Kernia`` object). Falling back to a no-op if the setting isn't
+    configured keeps the middleware importable from tests that don't wire it.
+    """
+
+    def process_request(self, request: HttpRequest) -> None:
+        auth = self._auth_from_settings()
+        request.kernia_session = None  # type: ignore[attr-defined]
+        request.kernia_user = None  # type: ignore[attr-defined]
+        if auth is None:
+            return
+        cookie = request.COOKIES.get(SESSION_COOKIE_NAME)
+        if not cookie:
+            return
+        session = async_to_sync(resolve_session)(auth, cookie)
+        if session is None:
+            return
+        request.kernia_session = session  # type: ignore[attr-defined]
+        # Lazily resolve the user only when asked; many requests just need the
+        # session id. We expose a thin callable proxy via attribute access.
+        request.kernia_user = _UserAccessor(auth, session.user_id)  # type: ignore[attr-defined]
+
+    @staticmethod
+    def _auth_from_settings() -> Kernia | None:
+        from django.conf import settings
+
+        return getattr(settings, "KERNIA", None)
+
+
+class _UserAccessor:
+    """Lazy user lookup.
+
+    ``request.kernia_user`` is a callable that loads the user row on first
+    access; we keep it lazy so the middleware only pays for the session lookup
+    unless the view actually wants the user.
+    """
+
+    def __init__(self, auth: Kernia, user_id: str) -> None:
+        self._auth = auth
+        self._user_id = user_id
+        self._cached: dict[str, Any] | None = None
+
+    @property
+    def id(self) -> str:
+        return self._user_id
+
+    def load(self) -> dict[str, Any] | None:
+        if self._cached is None:
+            from kernia.types.adapter import Where
+
+            self._cached = async_to_sync(self._auth.context.adapter.find_one)(
+                model="user",
+                where=(Where(field="id", value=self._user_id),),
+            )
+        return self._cached

kernia_django-0.1.0/src/kernia_django/views.py

@@ -0,0 +1,211 @@
+"""Django view that bridges to the Kernia ASGI router.
+
+Approach: Django's request/response objects are a different shape from ASGI, so
+the bridge converts a Django ``HttpRequest`` into an ASGI ``scope`` + receive
+queue, drives the inner router, and reassembles the response body / headers
+into a Django ``HttpResponse``.
+
+The bridge is sync at the Django edge (``View.dispatch`` is sync by default)
+and async on the inside. We use ``asgiref.sync.async_to_sync`` to cross the
+boundary. Every Kernia request therefore costs one thread hop. This is a
+known and intentional tradeoff: Django remains sync-friendly without forcing
+ASGI workers on the user.
+"""
+
+from __future__ import annotations
+
+from http.cookies import SimpleCookie
+from typing import Any, ClassVar
+
+from asgiref.sync import async_to_sync
+from django.http import HttpRequest, HttpResponse
+from django.urls import path
+from django.views import View
+from kernia.auth import Kernia
+from kernia.integrations.session import strip_base_path
+
+
+def django_request_to_scope(
+    request: HttpRequest,
+    *,
+    base_path: str = "",
+) -> dict[str, Any]:
+    """Translate a Django HttpRequest into an ASGI HTTP scope.
+
+    ``base_path`` is the mount prefix the auth router was registered under; we
+    strip it from ``path`` so the inner router sees canonical relative paths
+    (e.g. ``/sign-in/email``). Set to ``""`` to leave the path alone.
+    """
+    full_path = request.path
+    # Build a minimal ASGI HTTP scope. We don't try to be exhaustive — only the
+    # fields Kernia actually reads (path, method, headers, query_string,
+    # raw_path, scheme, client).
+    headers: list[tuple[bytes, bytes]] = []
+    for key, value in request.META.items():
+        if key.startswith("HTTP_"):
+            name = key[5:].replace("_", "-").lower().encode("latin-1")
+            headers.append((name, str(value).encode("latin-1")))
+        elif key in ("CONTENT_TYPE", "CONTENT_LENGTH") and value:
+            name = key.replace("_", "-").lower().encode("latin-1")
+            headers.append((name, str(value).encode("latin-1")))
+
+    # Django's request.GET is already parsed; the router doesn't need it as a
+    # mapping, but does inspect raw query_string from scope.
+    query_string = request.META.get("QUERY_STRING", "")
+    if isinstance(query_string, str):
+        query_string = query_string.encode("latin-1")
+
+    scope: dict[str, Any] = {
+        "type": "http",
+        "asgi": {"version": "3.0", "spec_version": "2.3"},
+        "http_version": "1.1",
+        "method": request.method or "GET",
+        "scheme": request.scheme or "http",
+        "path": full_path,
+        "raw_path": full_path.encode("latin-1"),
+        "query_string": query_string,
+        "root_path": "",
+        "headers": headers,
+        "server": (request.get_host().split(":")[0], request.get_port() or 80),
+        "client": (request.META.get("REMOTE_ADDR", "") or "", 0),
+    }
+    if base_path:
+        scope = strip_base_path(scope, base_path)
+    return scope
+
+
+async def _drive(
+    inner: Any,
+    scope: dict[str, Any],
+    body: bytes,
+) -> tuple[int, list[tuple[bytes, bytes]], bytes]:
+    """Drive a single HTTP exchange against an ASGI app, return the response."""
+    sent_body = bytearray()
+    status: int = 500
+    headers: list[tuple[bytes, bytes]] = []
+
+    request_sent = False
+
+    async def receive() -> dict[str, Any]:
+        nonlocal request_sent
+        if not request_sent:
+            request_sent = True
+            return {"type": "http.request", "body": body, "more_body": False}
+        # If the app asks for more we report disconnect to avoid hanging.
+        return {"type": "http.disconnect"}
+
+    async def send(message: dict[str, Any]) -> None:
+        nonlocal status, headers
+        if message["type"] == "http.response.start":
+            status = int(message["status"])
+            headers = list(message.get("headers", []))
+        elif message["type"] == "http.response.body":
+            chunk = message.get("body", b"") or b""
+            sent_body.extend(chunk)
+
+    await inner(scope, receive, send)
+    return status, headers, bytes(sent_body)
+
+
+class KerniaView(View):
+    """Class-based view that funnels every method onto the auth router.
+
+    Usage::
+
+        KerniaView.as_view(auth=my_auth, base_path="/api/auth")
+    """
+
+    auth: Kernia | None = None
+    base_path: str = "/api/auth"
+
+    http_method_names: ClassVar[list[str]] = [
+        "get",
+        "post",
+        "put",
+        "patch",
+        "delete",
+        "head",
+        "options",
+    ]
+
+    def dispatch(self, request: HttpRequest, *args: Any, **kwargs: Any) -> HttpResponse:
+        if self.auth is None:
+            raise RuntimeError("KerniaView requires an `auth` kwarg passed via .as_view()")
+        # ``rest`` is captured by the URL pattern; rebuild the full path because
+        # the inner router decides routing from scope["path"].
+        rest = kwargs.get("rest", "")
+        full_path = self.base_path.rstrip("/") + "/" + rest if rest else self.base_path
+        # Rewrite the Django request's path so the scope mirrors what would
+        # have been hit if Django were ASGI-native.
+        request.path = full_path
+        request.path_info = full_path
+
+        inner = self.auth.router.mount()
+        scope = django_request_to_scope(request, base_path=self.base_path.rstrip("/"))
+        body = request.body or b""
+
+        status, headers, response_body = async_to_sync(_drive)(inner, scope, body)
+
+        # Build Django response. Pull Content-Type for HttpResponse's ctor;
+        # parse Set-Cookie lines into response.cookies so Django emits each
+        # cookie on its own header (joining Set-Cookie with commas is broken
+        # for cookies whose attributes contain commas, e.g. ``Expires``).
+        content_type = None
+        cookie_lines: list[str] = []
+        remaining: list[tuple[bytes, bytes]] = []
+        for k, v in headers:
+            name = k.decode("latin-1")
+            value = v.decode("latin-1")
+            if name.lower() == "content-type" and content_type is None:
+                content_type = value
+            elif name.lower() == "set-cookie":
+                cookie_lines.append(value)
+            else:
+                remaining.append((k, v))
+
+        resp = HttpResponse(
+            response_body,
+            status=status,
+            content_type=content_type,
+        )
+        for k, v in remaining:
+            resp.headers[k.decode("latin-1")] = v.decode("latin-1")
+        for line in cookie_lines:
+            jar: SimpleCookie = SimpleCookie()
+            jar.load(line)
+            for morsel in jar.values():
+                resp.cookies[morsel.key] = morsel.value
+                for attr in (
+                    "expires",
+                    "path",
+                    "domain",
+                    "secure",
+                    "httponly",
+                    "samesite",
+                    "max-age",
+                ):
+                    if morsel[attr]:
+                        resp.cookies[morsel.key][attr] = morsel[attr]
+        return resp
+
+
+def setup(
+    auth: Kernia,
+    url_prefix: str = "/api/auth",
+) -> list[Any]:
+    """Return a list of urlpatterns ready to splice into ``urls.py``.
+
+    The patterns use a catch-all ``<path:rest>`` so every sub-route under the
+    prefix lands on ``KerniaView``.
+    """
+    prefix = url_prefix.strip("/")
+    return [
+        path(
+            f"{prefix}/<path:rest>",
+            KerniaView.as_view(auth=auth, base_path="/" + prefix),
+        ),
+        path(
+            f"{prefix}",
+            KerniaView.as_view(auth=auth, base_path="/" + prefix),
+        ),
+    ]

kernia_django-0.1.0/tests/test_django_unit.py

@@ -0,0 +1,88 @@
+"""Unit tests for the Django request → ASGI scope translator."""
+
+from __future__ import annotations
+
+import pytest
+
+pytest.importorskip("django")
+
+import django
+from django.conf import settings
+
+
+def _ensure_django() -> None:
+    if not settings.configured:
+        settings.configure(
+            DEBUG=True,
+            SECRET_KEY="test-secret",
+            DATABASES={
+                "default": {
+                    "ENGINE": "django.db.backends.sqlite3",
+                    "NAME": ":memory:",
+                }
+            },
+            INSTALLED_APPS=["kernia_django"],
+            MIDDLEWARE=[],
+            ROOT_URLCONF=None,
+            ALLOWED_HOSTS=["*"],
+            USE_TZ=True,
+        )
+        django.setup()
+
+
+_ensure_django()
+
+from django.test import RequestFactory  # noqa: E402
+from kernia_django.views import django_request_to_scope  # noqa: E402
+
+
+def test_translator_basic_get() -> None:
+    rf = RequestFactory()
+    req = rf.get(
+        "/api/auth/get-session?foo=bar",
+        HTTP_COOKIE="better-auth.session_token=abc",
+        HTTP_X_CUSTOM="yes",
+    )
+    scope = django_request_to_scope(req)
+    assert scope["type"] == "http"
+    assert scope["method"] == "GET"
+    assert scope["path"] == "/api/auth/get-session"
+    assert scope["query_string"] == b"foo=bar"
+    headers = dict(scope["headers"])
+    assert headers[b"cookie"] == b"better-auth.session_token=abc"
+    assert headers[b"x-custom"] == b"yes"
+
+
+def test_translator_strips_base_path() -> None:
+    rf = RequestFactory()
+    req = rf.get("/api/auth/sign-in/email")
+    scope = django_request_to_scope(req, base_path="/api/auth")
+    assert scope["path"] == "/sign-in/email"
+
+
+def test_translator_post_includes_content_type() -> None:
+    rf = RequestFactory()
+    req = rf.post(
+        "/api/auth/sign-up/email",
+        data='{"email":"x@y.com"}',
+        content_type="application/json",
+    )
+    scope = django_request_to_scope(req, base_path="/api/auth")
+    assert scope["method"] == "POST"
+    assert scope["path"] == "/sign-up/email"
+    headers = dict(scope["headers"])
+    assert headers[b"content-type"] == b"application/json"
+
+
+def test_translator_root_path_becomes_slash() -> None:
+    rf = RequestFactory()
+    req = rf.get("/api/auth")
+    scope = django_request_to_scope(req, base_path="/api/auth")
+    assert scope["path"] == "/"
+
+
+def test_translator_non_matching_base_path_unchanged() -> None:
+    rf = RequestFactory()
+    req = rf.get("/elsewhere")
+    scope = django_request_to_scope(req, base_path="/api/auth")
+    assert scope["path"] == "/elsewhere"