channels-jwt-subprotocol 1.0.0__py3-none-any.whl

channels_jwt_subprotocol/__init__.py

@@ -0,0 +1,20 @@
+"""Authenticate Django Channels WebSockets with a JWT sent as a subprotocol."""
+from .consumer import CLOSE_UNAUTHENTICATED, AsyncJWTSubprotocolMixin, JWTSubprotocolMixin
+from .middleware import (
+    DEFAULT_MARKER,
+    SCOPE_KEY,
+    JWTSubprotocolMiddleware,
+    token_from_subprotocols,
+)
+
+__all__ = [
+    "CLOSE_UNAUTHENTICATED",
+    "DEFAULT_MARKER",
+    "SCOPE_KEY",
+    "AsyncJWTSubprotocolMixin",
+    "JWTSubprotocolMiddleware",
+    "JWTSubprotocolMixin",
+    "token_from_subprotocols",
+]
+
+__version__ = "1.0.0"

channels_jwt_subprotocol/consumer.py

@@ -0,0 +1,72 @@
+"""Consumer helpers: echo the marker on accept, and refuse with a code that arrives.
+
+Two handshake details decide whether the browser gets what you meant:
+
+* If the client offered subprotocols, the server must answer with one of them.
+  Answer with none and the browser fails the connection (close code 1006).
+  Answer with the token and the token now sits in a response header.
+* A ``close()`` before ``accept()`` is not a WebSocket close frame. Daphne and
+  Uvicorn answer the upgrade with an HTTP 403, so the close code never reaches
+  the client, which sees 1006 again, the same as a dropped network. To send a
+  code the client can act on, accept first and close second.
+
+Accepting before refusing admits nothing as long as the consumer joins no
+group and sends no frame first, but the browser's ``onopen`` does fire. Mark
+the client as connected on a message the server sends after a successful
+accept, not on ``onopen``.
+"""
+from .middleware import SCOPE_KEY
+
+#: Close code for "this token is not good, renew it and reconnect".
+CLOSE_UNAUTHENTICATED = 4401
+
+
+def _offered_marker(scope):
+    return scope.get(SCOPE_KEY)
+
+
+class _Base:
+    close_unauthenticated_code = CLOSE_UNAUTHENTICATED
+
+    def is_authenticated(self):
+        user = self.scope.get("user")
+        return bool(user is not None and getattr(user, "is_authenticated", False))
+
+
+class AsyncJWTSubprotocolMixin(_Base):
+    """For ``AsyncWebsocketConsumer`` and ``AsyncJsonWebsocketConsumer``.
+
+    Usage::
+
+        class Feed(AsyncJWTSubprotocolMixin, AsyncJsonWebsocketConsumer):
+            async def connect(self):
+                if not self.is_authenticated():
+                    return await self.refuse()
+                await self.accept_authenticated()
+    """
+
+    async def accept_authenticated(self, headers=None):
+        """Accept, echoing the marker if the client offered it."""
+        # ``headers`` is passed only when given: Channels 4.0's accept() has no
+        # such parameter.
+        kwargs = {"headers": headers} if headers else {}
+        await self.accept(subprotocol=_offered_marker(self.scope), **kwargs)
+
+    async def refuse(self, code=None):
+        """Accept, then close with ``code`` (4401 by default)."""
+        await self.accept(subprotocol=_offered_marker(self.scope))
+        await self.close(code=code or self.close_unauthenticated_code)
+
+
+class JWTSubprotocolMixin(_Base):
+    """For the synchronous ``WebsocketConsumer`` and ``JsonWebsocketConsumer``."""
+
+    def accept_authenticated(self, headers=None):
+        """Accept, echoing the marker if the client offered it."""
+        kwargs = {"headers": headers} if headers else {}
+        self.accept(subprotocol=_offered_marker(self.scope), **kwargs)
+
+    def refuse(self, code=None):
+        """Accept, then close with ``code`` (4401 by default)."""
+        self.accept(subprotocol=_offered_marker(self.scope))
+        self.close(code=code or self.close_unauthenticated_code)

channels_jwt_subprotocol/middleware.py

@@ -0,0 +1,117 @@
+"""ASGI middleware that authenticates a WebSocket from a JWT sent as a subprotocol.
+
+A browser cannot set an ``Authorization`` header on a WebSocket handshake. The
+two places left for a token are the query string and the
+``Sec-WebSocket-Protocol`` header. The query string is part of the request line,
+which access logs, proxies and CDNs record by default. A subprotocol travels as
+a request header, which they do not.
+
+The client offers two subprotocols, a fixed marker and the token right after it::
+
+    new WebSocket(url, ["jwt", accessToken])
+
+The middleware finds the marker, takes the value that follows it as the token,
+and puts the resolved user in ``scope["user"]``. It also records the marker in
+``scope["jwt_subprotocol"]`` so the consumer can echo it back on ``accept()``:
+the server has to answer with one of the offered values, and it must be the
+marker, never the token.
+"""
+from django.core.exceptions import ImproperlyConfigured
+
+DEFAULT_MARKER = "jwt"
+SCOPE_KEY = "jwt_subprotocol"
+
+
+def token_from_subprotocols(subprotocols, marker=DEFAULT_MARKER):
+    """Return the value offered right after ``marker``, or ``None``.
+
+    ``None`` when the marker is absent, when nothing follows it, or when the
+    value after it is the marker again. Other subprotocols the client offers
+    before the marker are ignored, so a client can still negotiate an
+    application protocol alongside the token.
+    """
+    values = [str(p) for p in (subprotocols or [])]
+    try:
+        index = values.index(marker)
+    except ValueError:
+        return None
+    if index + 1 >= len(values):
+        return None
+    token = values[index + 1]
+    if not token or token == marker:
+        return None
+    return token
+
+
+def _anonymous_user():
+    from django.contrib.auth.models import AnonymousUser
+
+    return AnonymousUser()
+
+
+def _simplejwt_resolver():
+    """Build the default resolver on top of SimpleJWT's ``JWTAuthentication``.
+
+    It reuses the class that already authenticates the REST API, so the signing
+    key, the expiry, the token type and the user's ``is_active`` flag are
+    checked by the same code in both places.
+    """
+    try:
+        from rest_framework_simplejwt.authentication import JWTAuthentication
+        from rest_framework_simplejwt.exceptions import (
+            AuthenticationFailed,
+            InvalidToken,
+            TokenError,
+        )
+    except ImportError as exc:  # pragma: no cover - exercised without simplejwt
+        raise ImproperlyConfigured(
+            "JWTSubprotocolMiddleware needs djangorestframework-simplejwt for "
+            "its default token check. Install it, or pass get_user=..."
+        ) from exc
+
+    from channels.db import database_sync_to_async
+
+    @database_sync_to_async
+    def resolve(raw_token):
+        backend = JWTAuthentication()
+        try:
+            return backend.get_user(backend.get_validated_token(raw_token))
+        except (AuthenticationFailed, InvalidToken, TokenError):
+            return _anonymous_user()
+
+    return resolve
+
+
+class JWTSubprotocolMiddleware:
+    """Populate ``scope["user"]`` from a JWT offered as a WebSocket subprotocol.
+
+    ``get_user`` is an async callable that takes the raw token and returns a
+    user, or ``AnonymousUser`` for a token it refuses. Leave it out to validate
+    with SimpleJWT.
+
+    When the client offers the marker, the token decides ``scope["user"]``: a
+    missing or refused token gives ``AnonymousUser`` even if an earlier
+    middleware had already set a user. When the client does not offer the
+    marker at all, an existing ``scope["user"]`` is left alone, so this can sit
+    inside ``AuthMiddlewareStack`` for apps that also use session cookies.
+    """
+
+    def __init__(self, inner, marker=DEFAULT_MARKER, get_user=None):
+        if not marker:
+            raise ValueError("marker must be a non-empty string")
+        self.inner = inner
+        self.marker = marker
+        self.get_user = get_user or _simplejwt_resolver()
+
+    async def __call__(self, scope, receive, send):
+        if scope.get("type") == "websocket":
+            subprotocols = scope.get("subprotocols") or []
+            if self.marker in [str(p) for p in subprotocols]:
+                scope = dict(scope)
+                scope[SCOPE_KEY] = self.marker
+                token = token_from_subprotocols(subprotocols, self.marker)
+                scope["user"] = await self.get_user(token) if token else _anonymous_user()
+            elif "user" not in scope:
+                scope = dict(scope)
+                scope["user"] = _anonymous_user()
+        return await self.inner(scope, receive, send)

channels_jwt_subprotocol-1.0.0.dist-info/METADATA

@@ -0,0 +1,204 @@
+Metadata-Version: 2.4
+Name: channels-jwt-subprotocol
+Version: 1.0.0
+Summary: Authenticate Django Channels WebSockets with a JWT sent as a subprotocol, so the token never lands in the URL or in access logs.
+Author-email: TheLoops <support@theloops.live>
+License-Expression: MIT
+Project-URL: Homepage, https://theloops.live/engineering/channels-jwt-subprotocol
+Project-URL: Source, https://github.com/YouPanel/channels-jwt-subprotocol
+Keywords: django,channels,websocket,jwt,simplejwt,authentication,subprotocol
+Classifier: Programming Language :: Python :: 3
+Classifier: Framework :: Django
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Internet :: WWW/HTTP
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: channels>=4.0
+Requires-Dist: Django>=4.2
+Provides-Extra: simplejwt
+Requires-Dist: djangorestframework-simplejwt>=5.0; extra == "simplejwt"
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Requires-Dist: djangorestframework-simplejwt>=5.0; extra == "test"
+Requires-Dist: daphne>=4.0; extra == "test"
+Requires-Dist: uvicorn>=0.30; extra == "test"
+Requires-Dist: websockets>=14; extra == "test"
+Dynamic: license-file
+
+# channels-jwt-subprotocol
+
+Authenticate [Django Channels](https://channels.readthedocs.io/) WebSockets with a JWT sent as a
+**subprotocol**, so the token never appears in the URL.
+
+A browser cannot set an `Authorization` header on a WebSocket handshake. The usual workaround puts
+the token in the query string, `wss://example.com/ws/?token=…`, and the query string is part of the
+request line that nginx, load balancers and CDNs write to their access logs by default. An access
+token lives for minutes; a log line lives for months.
+
+The `Sec-WebSocket-Protocol` header is the other place a browser lets you put a value, and access
+logs do not record it by default. This package reads the token from there, validates it with
+[SimpleJWT](https://github.com/jazzband/djangorestframework-simplejwt) (or any check you supply),
+and handles the two handshake details that otherwise fail silently:
+
+- **The server must echo a subprotocol the client offered.** Echo nothing and the browser drops the
+  connection; echo the token and it ends up in a response header. The middleware records a fixed
+  marker, and the consumer helpers echo the marker, never the token.
+- **A close code sent before `accept()` never reaches the client.** Daphne and Uvicorn answer the
+  upgrade with an HTTP 403 instead, and the browser sees code 1006, the same as a dropped network.
+  `refuse()` accepts first and then closes, so the client receives `4401` and knows to renew its
+  token.
+
+## Install
+
+```bash
+pip install "channels-jwt-subprotocol[simplejwt]"
+```
+
+Python 3.10+, Django 4.2+, Channels 4.0+. Leave out `[simplejwt]` if you validate tokens yourself.
+
+## Use
+
+**Client.** Offer the marker `jwt`, then the token:
+
+```js
+const ws = new WebSocket('wss://example.com/ws/feed/', ['jwt', accessToken])
+```
+
+A JWT is made of base64url segments and dots, which are all valid subprotocol characters. An invalid
+value makes the constructor throw a `SyntaxError`, so treat a throw like a failed connect.
+
+**ASGI.** Wrap your WebSocket router:
+
+```python
+# asgi.py
+from channels.routing import ProtocolTypeRouter, URLRouter
+from channels.security.websocket import AllowedHostsOriginValidator
+from django.core.asgi import get_asgi_application
+
+django_asgi_app = get_asgi_application()
+
+from channels_jwt_subprotocol import JWTSubprotocolMiddleware  # noqa: E402
+from myapp.routing import websocket_urlpatterns  # noqa: E402
+
+application = ProtocolTypeRouter({
+    "http": django_asgi_app,
+    "websocket": AllowedHostsOriginValidator(
+        JWTSubprotocolMiddleware(URLRouter(websocket_urlpatterns))
+    ),
+})
+```
+
+**Consumer.** Use the mixin's `accept_authenticated()` and `refuse()` instead of calling `accept()`
+and `close()` yourself:
+
+```python
+from channels.generic.websocket import AsyncJsonWebsocketConsumer
+from channels_jwt_subprotocol import AsyncJWTSubprotocolMixin
+
+
+class FeedConsumer(AsyncJWTSubprotocolMixin, AsyncJsonWebsocketConsumer):
+    async def connect(self):
+        if not self.is_authenticated():
+            return await self.refuse()          # accept, then close with 4401
+        await self.accept_authenticated()       # echoes "jwt", never the token
+        await self.send_json({"type": "connected"})
+```
+
+`JWTSubprotocolMixin` is the same for the synchronous `WebsocketConsumer` and
+`JsonWebsocketConsumer`.
+
+**Client, on close.** Because the server accepts before it refuses, `onopen` fires for a socket that is
+about to be closed. Treat the connection as live when the server's own first message arrives, and
+renew the token on `4401`:
+
+```js
+ws.onmessage = (e) => {
+  if (JSON.parse(e.data).type === 'connected') markLive()
+}
+ws.onclose = (e) => {
+  if (e.code === 4401) return renewTokenThenReconnect()   // refused: a new token may help
+  scheduleRetry()                                         // network: back off and retry
+}
+```
+
+If a freshly renewed token is refused too, back off instead of renewing again, or a deactivated
+account turns into a loop against your refresh endpoint.
+
+## Behaviour
+
+| Client offers | `scope["user"]` | Consumer with `refuse()` |
+|---|---|---|
+| `["jwt", <valid access token>]` | the token's user | accepted, echoes `jwt` |
+| `["jwt", <expired, refresh, garbage token>]` | `AnonymousUser` | accepted with `jwt`, closed `4401` |
+| `["jwt"]` | `AnonymousUser` | accepted with `jwt`, closed `4401` |
+| nothing, or no `jwt` marker | unchanged, or `AnonymousUser` if unset | accepted, closed `4401` |
+
+The token is the value **immediately after** the marker, so a client can offer an application
+protocol too: `['graphql-transport-ws', 'jwt', token]`. If you do, accept with that protocol yourself,
+as the server may echo only one value.
+
+When the marker is offered, the token decides the user, even if an earlier middleware already set
+one. When it is not, an existing `scope["user"]` is left alone, so the middleware can sit inside
+`AuthMiddlewareStack` for apps that also use session cookies.
+
+The default check is SimpleJWT's `JWTAuthentication`, the class that already guards your REST API:
+same signing key, expiry, token type and `is_active` rule, no second implementation to drift.
+
+## Options
+
+```python
+JWTSubprotocolMiddleware(inner, marker="jwt", get_user=None)
+```
+
+- `marker`: the fixed value the client offers before the token. Use the same one in the client.
+- `get_user`: an async callable `get_user(raw_token) -> user`. Return `AnonymousUser()` to refuse.
+  Use it for a non-SimpleJWT token, or to add your own checks.
+
+```python
+from channels.db import database_sync_to_async
+from django.contrib.auth.models import AnonymousUser
+
+
+@database_sync_to_async
+def get_user(raw_token):
+    user = verify_with_your_identity_provider(raw_token)
+    return user or AnonymousUser()
+
+
+application = JWTSubprotocolMiddleware(router, get_user=get_user)
+```
+
+The refusal code is `CLOSE_UNAUTHENTICATED` (`4401`). Override `close_unauthenticated_code` on the
+consumer, or pass `refuse(code=...)`.
+
+## What this does not do
+
+- **It authenticates the handshake only.** A socket opened with a token that has two minutes left
+  stays open after the token expires. Renew near-expiry tokens before connecting, and close sockets
+  yourself if your app needs revocation to take effect immediately.
+- **It is not encryption.** Use `wss://`. The point is that the token is not written to logs by
+  default, not that it is hidden from anything on the connection.
+- **Check your own logging.** A proxy configured to log request headers will log this one too.
+
+## Tests
+
+```bash
+pip install -e ".[test]"
+pytest
+```
+
+The suite includes live tests that start Daphne and Uvicorn on a local port and connect with the
+`websockets` client, which is how the HTTP 403 for a close before `accept()`, and the `4401` that
+arrives after accepting, are checked against real servers rather than assumed. They pass on Daphne
+4.0 and 4.2, Uvicorn 0.30 and 0.54, Channels 4.0 and 4.3.
+
+## Background
+
+Written for the dashboard of [TheLoops](https://theloops.live), where one socket per tab pushes the
+status of 24/7 streams. The long version, including the nginx and idle-timeout parts, is in
+[Django Channels: JWT auth without the token in the URL](https://theloops.live/engineering/django-channels-jwt-websocket).
+
+## License
+
+MIT

channels_jwt_subprotocol-1.0.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+channels_jwt_subprotocol/__init__.py,sha256=uaqK00n3SUOgs34eXpjJ9X7LJ79-f6sS_iKmNGc9YwI,521
+channels_jwt_subprotocol/consumer.py,sha256=1jIZ0tQb-LZAMQ5cFJIJ6Kq4Yj2mEO8vRtezudLpFew,2943
+channels_jwt_subprotocol/middleware.py,sha256=Wk69tEwpVDGi448GSdU8VZD3Xarb5OyAStdIP1IwfBQ,4626
+channels_jwt_subprotocol-1.0.0.dist-info/licenses/LICENSE,sha256=Hf_XVAg044frNSZSzzufuXD9PA3q78GX83yQA3rPKq4,1089
+channels_jwt_subprotocol-1.0.0.dist-info/METADATA,sha256=IrWzyrbx_GroIZLRViCXvks8y5tTQKTgtKPhCSIbeVk,8460
+channels_jwt_subprotocol-1.0.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+channels_jwt_subprotocol-1.0.0.dist-info/top_level.txt,sha256=SkRMTD4tOMas1_9hBT2nYidBmDlz2mNUB49WU6DcjG0,25
+channels_jwt_subprotocol-1.0.0.dist-info/RECORD,,

channels_jwt_subprotocol-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

channels_jwt_subprotocol-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TheLoops (https://theloops.live)
+
+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.

channels_jwt_subprotocol-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+channels_jwt_subprotocol