upload.handles - Opaque Upload Handles

Opaque per-wizard upload handles.

This module provides a small server-side mapping between opaque handles and UploadSession instances. The mapping is stored in the authenticated user’s Django session.

This allows the frontend to refer to an active upload session by an opaque handle without ever seeing the underlying UploadSession.token. The security model is analogous to Django’s CSRF token: an opaque value the client echoes back, validated against per-session server state.

upload.handles.HANDLE_TTL_SECONDS = 3600

How long a handle remains valid without being re-registered or resolved. One hour by default — long enough for normal upload flows, short enough that a leaked handle becomes useless quickly.

upload.handles.register_handle(request: HttpRequest, upload_session: UploadSession) → str

Register an upload session against an opaque handle in the user’s session.

If a (non-expired) handle already exists for this upload session, that handle is returned and its timestamp is refreshed. Otherwise, a fresh handle is generated.

Expired entries are pruned opportunistically.

Parameters:

  • request – The incoming HTTP request whose request.session will store the handle mapping.

  • upload_session – The upload session to register.

Returns:

The opaque handle string that should be sent to the client.

upload.handles.resolve_handle(request: HttpRequest, handle: str) → UploadSession | None

Resolve a handle back to an UploadSession.

The lookup is constrained to upload sessions owned by the authenticated user, so even if a handle is leaked across users it cannot be used to access another user’s session. The handle’s timestamp is refreshed on every successful resolution so active uploads keep it alive.

Parameters:

  • request – The incoming HTTP request.

  • handle – The opaque handle previously returned by register_handle().

Returns:

The matching UploadSession, or None if the handle is unknown, expired, or its session does not belong to the user.