duck.http.middlewares.contrib.jwt

JWT middleware for Duck.

The JWT is extracted once on the initial HTTP handshake and attached to the request as request.JWT. Lively events share that same request object and only need to re-encode and push the token if the payload was mutated — no HTTP headers can be written mid-WebSocket.

Module Contents

Classes

JWTMiddleware

Extracts, validates, and delivers JWTs across HTTP and Lively WebSocket flows.

Data

TRANSPORT_COOKIE
TRANSPORT_HEADER
VALID_TRANSPORTS

API

class duck.http.middlewares.contrib.jwt.JWTMiddleware

Bases: duck.http.middlewares.BaseMiddleware

Extracts, validates, and delivers JWTs across HTTP and Lively WebSocket flows.

HTTP flow: process_request — extract the raw token from the configured transport (cookie or header), build a JWTStore, and attach it to request.JWT.

process_response — if the payload was modified, re-encode the token and
                   write it back via ``Set-Cookie`` or a response header.

… admonition:: Notes

The store is lazy — JWTStore.load() decodes the token on first payload access, not on construction. Expired or missing tokens result in an empty, unauthenticated store rather than a hard error, so views can decide how to respond.

debug_message: str

‘JWTMiddleware: JWT Error’

classmethod get_raw_token_from_request(request: duck.http.request.HttpRequest, token_type: str = 'access') → Optional[str]

Extracts the raw JWT string from the incoming request.

Reads from whichever transport is configured in settings — either a named cookie or a custom HTTP header.

Parameters:

• request – The incoming Duck HTTP request.

• token_type – The type of token. Whether access or refresh.

Returns:

The raw token string, or None if absent.

Return type:

Optional[str]

classmethod process_request(request: duck.http.request.HttpRequest) → int

Builds and attaches a JWTStore to the request.

Expired or invalid tokens are swallowed here — the store is attached as empty so downstream views receive a consistent request.JWT object regardless of token state.

Parameters:

request – The incoming HTTP request.

Returns:

cls.request_ok always — JWT errors are non-fatal at this stage.

Return type:

int

classmethod process_response(response, request: duck.http.request.HttpRequest)

Re-encodes and delivers the JWT if the payload was modified.

For cookie transport, writes a Set-Cookie header. For header transport, sets the configured response header.

Parameters:

• response – The outgoing Duck HTTP response object.

• request – The corresponding HTTP request.

classmethod resolve_transport() → str

Reads and validates JWT_TRANSPORT from settings.

Returns:

The normalised transport string ("cookie" or "header").

Return type:

str

Raises:

ValueError – If the setting is missing or not a recognised transport.

classmethod write_cookie(response: duck.http.response.HttpResponse, request: duck.http.request.HttpRequest, token: str, token_type: str = 'access')

Writes the JWT as a Set-Cookie header on the HTTP response.

Parameters:

• response – The Duck HTTP response object.

• request – The HTTP request to get JWTStore from.

• token – The encoded JWT string.

• token_type – The type of token, whether access or refresh.

duck.http.middlewares.contrib.jwt.TRANSPORT_COOKIE

‘cookie’

duck.http.middlewares.contrib.jwt.TRANSPORT_HEADER

‘header’

duck.http.middlewares.contrib.jwt.VALID_TRANSPORTS

()