Django Time-Token File Storage
==============================
This is a simple extension to Django's `FileSystemStorage` that adds a URL
parameter carrying a shared token, which is only valid for a defined period
of time.
Additionally, a like-wise time-constrained file upload slot mechanism is
available.
Functionality
-------------
File storage with token-secured URLs
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This is a drop-in replacement for the Django `FileSystemStorage`, usable if
media files are served by Django itself. It does currently not work if media
files are served from an independent web server.
The storage and its accompanying view do the following:
* When a URL to a storage file is generated, a HMAC-based token is generated
* The token and the timestamp when it was generated are appended as request
parameters to the URL
* Upon retrieval of the file through the accompanying view, the requested
file name and the passed timestamp are used to recalculate the HMAC-based
token
* Only if the tokens match, and a configured timeout has not passed, is the
file served
The signature-based token ensures that the token is invalidated when:
* The filename changes
* The timestamp changes
* The mtime of the file changes
* The `SECRET_KEY` changes
Time-constrained uplaod slot
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The upload slot mechanism can be used to generically handle file uploads
by clients that can not upload files with a regular request. One example
for this is a client using GraphQL to talk to Django, because GraphQL
does not support file uploads and rather suggests to do uplaods
out-of-band.
With Titofisto's upload slot mechanism, calling code can request a secure
URL which it can hand out to a client. When the client POSTs its file
to the endpoint, a previously provided callback is called to handle the
uploaded file.
Installation
------------
To add `django-titofisto`_ to a project, first add it as dependency to your
project, e.g. using `poetry`_::
$ poetry add django-titofisto
`django-titofisto` will use the base `FileSystemStorage` for almost everything,
including determining the `MEDIA_ROOT`. It merely adds a token as URL parameter
to whatever the base `FileSystemStorage.url()` method returns.
Add the following to your settings::
DEFAULT_FILE_STORAGE = "titofisto.TitofistoStorage"
TITOFISTO_TIMEOUT = 3600 # optional, this is the default
TITOFISTO_PARAM = "titofisto_token" # optional, this is the default
Add the following to your URL config::
from django.conf import settings
from django.urls import include, path
urlpatterns += [
path(settings.MEDIA_URL.removeprefix("/"), include("titofisto.urls")),
]
Django will start serving media files under the configured `MEDIA_URL`.
Provide public media files
~~~~~~~~~~~~~~~~~~~~~~~~~~
Sometimes, there might be media files, for example favicons,
you want to be accessible without any authentication. Per default,
`django-titofisto` will serve all files stored in the directory `public` without a token.
You can disable or configure this behavior using these settings::
TITOFISTO_USE_PUBLIC_NAMESPACE = True # optional, this is the default
TITOFISTO_PUBLIC_NAMESPACE = "public/" # optional, this is the default
Use the time-constrained upload slot
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To enable the file upload mechanism, a setting must be set, because the
default `upload/` prefix could potentially shadow expected media file
URLs::
TITOFISTO_ENABLE_UPLOAD = True
TITOFISTO_UPLOAD_NAMESPACE = "titofisto/upload/"
A simplified example for using the upload slot mechanism is::
from titofisto.views import TitofistoUploadView
def handle_file(request, pk):
instance = MyModel.objects.get(pk=pk)
instance.photo = request.FILES["photo"]
instance.save()
# This gets an uplaod URL to pass on to the client
# On upload, the handler above will be called, with 15 as positional argument
upload_url = TitofistoUploadView.get_upload_slot(
"mymodule.handle_file",
(15,)
)
Credits
-------
`django-titofisto` was developed for the `AlekSIS`_ school information system by
its team::
Copyright © 2021, 2023 Dominik George <dominik.george@teckids.org>
Copyright © 2021 Jonathan Weth <dev@jonathanweth.de>
.. _django-titofisto: https://edugit.org/AlekSIS/libs/django-titofisto
.. _poetry: https://python-poetry.org/
.. _Django's cache framework: https://docs.djangoproject.com/en/3.2/topics/cache/
.. _AlekSIS: https://aleksis.org/
Raw data
{
"_id": null,
"home_page": "https://edugit.org/AlekSIS/libs/django-titofisto",
"name": "django-titofisto",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.9,<4.0",
"maintainer_email": "",
"keywords": "django,storage,media,secure",
"author": "Dominik George",
"author_email": "dominik.george@teckids.org",
"download_url": "https://files.pythonhosted.org/packages/22/be/1cb639c6ce9738574cb0281416d27d3223a74412ea833795c7357a6959f6/django_titofisto-1.1.0.tar.gz",
"platform": null,
"description": "Django Time-Token File Storage\n==============================\n\nThis is a simple extension to Django's `FileSystemStorage` that adds a URL\nparameter carrying a shared token, which is only valid for a defined period\nof time.\n\nAdditionally, a like-wise time-constrained file upload slot mechanism is\navailable.\n\nFunctionality\n-------------\n\nFile storage with token-secured URLs\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nThis is a drop-in replacement for the Django `FileSystemStorage`, usable if\nmedia files are served by Django itself. It does currently not work if media\nfiles are served from an independent web server.\n\nThe storage and its accompanying view do the following:\n\n* When a URL to a storage file is generated, a HMAC-based token is generated\n* The token and the timestamp when it was generated are appended as request\n parameters to the URL\n* Upon retrieval of the file through the accompanying view, the requested\n file name and the passed timestamp are used to recalculate the HMAC-based\n token\n* Only if the tokens match, and a configured timeout has not passed, is the\n file served\n\nThe signature-based token ensures that the token is invalidated when:\n\n* The filename changes\n* The timestamp changes\n* The mtime of the file changes\n* The `SECRET_KEY` changes\n\nTime-constrained uplaod slot\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nThe upload slot mechanism can be used to generically handle file uploads\nby clients that can not upload files with a regular request. One example\nfor this is a client using GraphQL to talk to Django, because GraphQL\ndoes not support file uploads and rather suggests to do uplaods\nout-of-band.\n\nWith Titofisto's upload slot mechanism, calling code can request a secure\nURL which it can hand out to a client. When the client POSTs its file\nto the endpoint, a previously provided callback is called to handle the\nuploaded file.\n\nInstallation\n------------\n\nTo add `django-titofisto`_ to a project, first add it as dependency to your\nproject, e.g. using `poetry`_::\n\n $ poetry add django-titofisto\n\n`django-titofisto` will use the base `FileSystemStorage` for almost everything,\nincluding determining the `MEDIA_ROOT`. It merely adds a token as URL parameter\nto whatever the base `FileSystemStorage.url()` method returns.\n\nAdd the following to your settings::\n\n DEFAULT_FILE_STORAGE = \"titofisto.TitofistoStorage\"\n TITOFISTO_TIMEOUT = 3600 # optional, this is the default\n TITOFISTO_PARAM = \"titofisto_token\" # optional, this is the default\n\nAdd the following to your URL config::\n\n from django.conf import settings\n from django.urls import include, path\n\n urlpatterns += [\n path(settings.MEDIA_URL.removeprefix(\"/\"), include(\"titofisto.urls\")),\n ]\n\nDjango will start serving media files under the configured `MEDIA_URL`.\n\nProvide public media files\n~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nSometimes, there might be media files, for example favicons,\nyou want to be accessible without any authentication. Per default,\n`django-titofisto` will serve all files stored in the directory `public` without a token.\nYou can disable or configure this behavior using these settings::\n\n TITOFISTO_USE_PUBLIC_NAMESPACE = True # optional, this is the default\n TITOFISTO_PUBLIC_NAMESPACE = \"public/\" # optional, this is the default\n\nUse the time-constrained upload slot\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nTo enable the file upload mechanism, a setting must be set, because the\ndefault `upload/` prefix could potentially shadow expected media file\nURLs::\n\n TITOFISTO_ENABLE_UPLOAD = True\n TITOFISTO_UPLOAD_NAMESPACE = \"titofisto/upload/\"\n\nA simplified example for using the upload slot mechanism is::\n\n from titofisto.views import TitofistoUploadView\n\n def handle_file(request, pk):\n instance = MyModel.objects.get(pk=pk)\n instance.photo = request.FILES[\"photo\"]\n instance.save()\n\n # This gets an uplaod URL to pass on to the client\n # On upload, the handler above will be called, with 15 as positional argument\n upload_url = TitofistoUploadView.get_upload_slot(\n \"mymodule.handle_file\",\n (15,)\n )\n\nCredits\n-------\n\n`django-titofisto` was developed for the `AlekSIS`_ school information system by\nits team::\n\n Copyright \u00a9 2021, 2023 Dominik George <dominik.george@teckids.org>\n Copyright \u00a9 2021 Jonathan Weth <dev@jonathanweth.de>\n\n.. _django-titofisto: https://edugit.org/AlekSIS/libs/django-titofisto\n.. _poetry: https://python-poetry.org/\n.. _Django's cache framework: https://docs.djangoproject.com/en/3.2/topics/cache/\n.. _AlekSIS: https://aleksis.org/\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Django Time-Token File Storage",
"version": "1.1.0",
"project_urls": {
"Homepage": "https://edugit.org/AlekSIS/libs/django-titofisto",
"Repository": "https://edugit.org/AlekSIS/libs/django-titofisto"
},
"split_keywords": [
"django",
"storage",
"media",
"secure"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "79b0f6c2a4093f363d5a5dfe0e308fd2ee11e5c2fd2654207f0bff922c82b7fa",
"md5": "30612933791e6756fc6dae8e007f86ac",
"sha256": "bd5de96e54617b1da70b624f0942b14d1dfcb0cf5a15e800f2167f81ebd322b7"
},
"downloads": -1,
"filename": "django_titofisto-1.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "30612933791e6756fc6dae8e007f86ac",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9,<4.0",
"size": 18086,
"upload_time": "2023-12-04T23:26:53",
"upload_time_iso_8601": "2023-12-04T23:26:53.106338Z",
"url": "https://files.pythonhosted.org/packages/79/b0/f6c2a4093f363d5a5dfe0e308fd2ee11e5c2fd2654207f0bff922c82b7fa/django_titofisto-1.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "22be1cb639c6ce9738574cb0281416d27d3223a74412ea833795c7357a6959f6",
"md5": "8d40859c0ce5d90c4c3fa3ca031f624d",
"sha256": "4a96745995a48b1d86125c6e07805336232abef4ef8c05c9a977bfe6a6a5d44b"
},
"downloads": -1,
"filename": "django_titofisto-1.1.0.tar.gz",
"has_sig": false,
"md5_digest": "8d40859c0ce5d90c4c3fa3ca031f624d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9,<4.0",
"size": 12728,
"upload_time": "2023-12-04T23:26:55",
"upload_time_iso_8601": "2023-12-04T23:26:55.022911Z",
"url": "https://files.pythonhosted.org/packages/22/be/1cb639c6ce9738574cb0281416d27d3223a74412ea833795c7357a6959f6/django_titofisto-1.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-12-04 23:26:55",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "django-titofisto"
}
JSON