uploadshield 2.0.0__py3-none-any.whl

uploadshield/django/checks.py

@@ -0,0 +1,148 @@
+"""Django system checks (``manage.py check``) for configuration mistakes."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from django.conf import settings
+from django.core import checks
+from django.core.exceptions import ImproperlyConfigured
+
+from uploadshield.checks import ImageIntegrity, YaraRules
+from uploadshield.checks.image import PILLOW_FORMATS
+
+from .conf import SETTING, load_config
+
+if TYPE_CHECKING:
+    from uploadshield.policy import Policy
+
+__all__ = ["check_configuration"]
+
+_HANDLER = "uploadshield.django.handlers.ValidatingUploadHandler"
+
+
+def _uses_our_handler400() -> bool:
+    from importlib import import_module
+
+    from django.utils.module_loading import import_string
+
+    from .views import bad_request
+
+    urlconf = getattr(settings, "ROOT_URLCONF", None)
+    if not urlconf:
+        return False
+    try:
+        handler = getattr(import_module(urlconf), "handler400", None)
+        if isinstance(handler, str):
+            handler = import_string(handler)
+    except ImportError:
+        return False
+    return handler is bad_request
+
+
+def _distinct_policies(config: Any) -> list[Policy]:
+    seen: dict[Policy, None] = {}
+    candidates = [*config.policies.values(), config.default_policy]
+    candidates += [policy for _, policy in config.view_policies]
+    for policy in candidates:
+        if policy is not None:
+            seen.setdefault(policy, None)
+    return list(seen)
+
+
+def _policy_messages(policy: Policy) -> list[checks.CheckMessage]:
+    label = policy.name or repr(policy)
+    found: list[checks.CheckMessage] = []
+    for component in (*policy.checks, *policy.sanitizers):
+        if missing := component.missing_dependencies():
+            found.append(
+                checks.Error(
+                    f"Upload policy {label!r} uses {type(component).__name__}, which requires "
+                    f"the missing module(s): {', '.join(missing)}.",
+                    hint="Install the matching extra, e.g. uv add 'uploadshield[images,yara]'.",
+                    id="uploadshield.E002",
+                )
+            )
+        elif isinstance(component, YaraRules):
+            try:
+                component.compile()
+            except Exception as exc:
+                found.append(
+                    checks.Error(
+                        f"YARA rules of upload policy {label!r} do not compile: {exc}",
+                        id="uploadshield.E003",
+                    )
+                )
+    raster = any(policy.allows_mime(mime) for mime in PILLOW_FORMATS)
+    uses_pillow = any(isinstance(c, ImageIntegrity) for c in policy.content_checks)
+    if raster and uses_pillow and ImageIntegrity.missing_dependencies():
+        found.append(
+            checks.Warning(
+                f"Upload policy {label!r} accepts images but Pillow is not installed, so image "
+                "integrity checks are skipped.",
+                hint="uv add 'uploadshield[images]'",
+                id="uploadshield.W002",
+            )
+        )
+    return found
+
+
+@checks.register(checks.Tags.security)
+def check_configuration(app_configs: Any = None, **kwargs: Any) -> list[checks.CheckMessage]:
+    try:
+        config = load_config()
+    except ImproperlyConfigured as exc:
+        return [checks.Error(str(exc), obj=SETTING, id="uploadshield.E001")]
+
+    messages: list[checks.CheckMessage] = []
+    for policy in _distinct_policies(config):
+        messages += _policy_messages(policy)
+
+    handlers = list(getattr(settings, "FILE_UPLOAD_HANDLERS", []))
+    if _HANDLER not in handlers:
+        messages.append(
+            checks.Info(
+                "ValidatingUploadHandler is not installed: only views with @validate_uploads, "
+                "fields with FileValidator/ValidatedFileField and ValidatingStorage are protected.",
+                hint=f"Set FILE_UPLOAD_HANDLERS = [{_HANDLER!r}] for project-wide protection.",
+                id="uploadshield.I001",
+            )
+        )
+        if config.max_upload_size is not None:
+            messages.append(
+                checks.Warning(
+                    f"{SETTING}['MAX_UPLOAD_SIZE'] has no effect without ValidatingUploadHandler.",
+                    id="uploadshield.W003",
+                )
+            )
+    else:
+        if handlers.index(_HANDLER) != 0:
+            messages.append(
+                checks.Warning(
+                    "Upload handlers before ValidatingUploadHandler receive (and may store) file "
+                    "data before it is validated.",
+                    hint="Make ValidatingUploadHandler the only entry of FILE_UPLOAD_HANDLERS and "
+                    f"list the others in {SETTING}['UPLOAD_HANDLERS'].",
+                    id="uploadshield.W004",
+                )
+            )
+        if len(handlers) > 1:
+            messages.append(
+                checks.Warning(
+                    "Upload handlers listed next to ValidatingUploadHandler never receive data; it "
+                    f"delegates storage to {SETTING}['UPLOAD_HANDLERS'] instead.",
+                    hint=f"Move {[h for h in handlers if h != _HANDLER]!r} to "
+                    f"{SETTING}['UPLOAD_HANDLERS'].",
+                    id="uploadshield.W001",
+                )
+            )
+        if not _uses_our_handler400():
+            messages.append(
+                checks.Info(
+                    "Rejected uploads are answered by your handler400 with a generic 400 page.",
+                    hint="Set handler400 = 'uploadshield.django.views.bad_request' in your "
+                    "root URLconf for 413/415 status codes and JSON/HTML error details.",
+                    id="uploadshield.I002",
+                )
+            )
+    return messages

uploadshield/django/cli.py

@@ -0,0 +1,36 @@
+"""The command line's bridge into a Django project (``uploadshield ... --django``).
+
+The only place that calls ``django.setup()``: the command line itself stays free of
+Django imports and loads this module only when asked to.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .conf import Config
+
+__all__ = ["configure"]
+
+
+def configure(settings: str | None = None) -> Config:
+    """Set Django up with ``settings`` (or ``DJANGO_SETTINGS_MODULE``); return the config.
+
+    Raises ``ImproperlyConfigured`` and import errors unchanged, for the caller to report.
+    """
+    if settings:
+        os.environ["DJANGO_SETTINGS_MODULE"] = settings
+    if not os.environ.get("DJANGO_SETTINGS_MODULE"):
+        from django.core.exceptions import ImproperlyConfigured
+
+        raise ImproperlyConfigured(
+            "no settings: pass --settings myproject.settings or set DJANGO_SETTINGS_MODULE"
+        )
+    import django
+
+    django.setup()
+    from .conf import get_config
+
+    return get_config()

uploadshield/django/conf.py

@@ -0,0 +1,189 @@
+"""The ``UPLOADSHIELD`` setting: parsing, validation and policy lookup."""
+
+from __future__ import annotations
+
+import fnmatch
+import functools
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+from types import MappingProxyType
+from typing import TYPE_CHECKING, Any
+
+from django.conf import settings
+from django.core.exceptions import ImproperlyConfigured
+from django.core.signals import setting_changed
+from django.dispatch import receiver
+from django.utils.module_loading import import_string
+
+from uploadshield.policy import Policy
+from uploadshield.presets import BUILTIN_POLICIES
+from uploadshield.web import PolicyLookupError, resolve_policy
+
+if TYPE_CHECKING:
+    from django.http import HttpRequest, HttpResponse
+
+    from .service import UploadValidation
+
+__all__ = ["MODES", "ON_REJECT", "SETTING", "Config", "PolicyRef", "get_config", "load_config"]
+
+SETTING = "UPLOADSHIELD"
+#: ``enforce`` rejects, ``report`` only logs/signals what would be rejected, ``off``
+#: disables request-level validation (field validators keep working).
+MODES = ("enforce", "report", "off")
+#: ``reject`` aborts the request (400/413/415); ``field`` replaces the file with an empty
+#: placeholder so forms report the error next to the field.
+ON_REJECT = ("reject", "field")
+_OWN_HANDLER = "uploadshield.django.handlers.ValidatingUploadHandler"
+
+PolicyRef = str | Policy
+RejectionHandler = Callable[["HttpRequest", "UploadValidation"], "HttpResponse"]
+
+_DEFAULTS: dict[str, Any] = {
+    "MODE": "enforce",
+    "DEFAULT_POLICY": "default",
+    "POLICIES": {},
+    "VIEW_POLICIES": {},
+    "REJECTION_HANDLER": "uploadshield.django.responses.reject",
+    "EXPOSE_DETAILS": False,
+    "NORMALIZE_CONTENT_TYPE": True,
+    "MAX_UPLOAD_SIZE": None,
+    "ON_REJECT": "reject",
+    # Where ValidatingUploadHandler stores incoming data (Django's defaults).
+    "UPLOAD_HANDLERS": [
+        "django.core.files.uploadhandler.MemoryFileUploadHandler",
+        "django.core.files.uploadhandler.TemporaryFileUploadHandler",
+    ],
+    "MESSAGES": {},
+}
+
+
+@dataclass(frozen=True)
+class Config:
+    mode: str
+    default_policy: Policy | None
+    policies: Mapping[str, Policy]
+    view_policies: tuple[tuple[str, Policy | None], ...]
+    rejection_handler: RejectionHandler
+    expose_details: bool
+    normalize_content_type: bool
+    max_upload_size: int | None
+    messages: Mapping[str, str]
+    on_reject: str
+    upload_handlers: tuple[str, ...]
+
+    def resolve(self, ref: PolicyRef) -> Policy:
+        """Resolve a policy object, a registered name, or a dotted import path."""
+        return _resolve(ref, self.policies)
+
+    def policy_for_view_name(self, view_name: str | None) -> tuple[bool, Policy | None]:
+        """``(matched, policy)`` for the first ``VIEW_POLICIES`` glob matching the name."""
+        if view_name:
+            for pattern, policy in self.view_policies:
+                if fnmatch.fnmatchcase(view_name, pattern):
+                    return True, policy
+        return False, None
+
+
+def _resolve(ref: PolicyRef, policies: Mapping[str, Policy]) -> Policy:
+    try:
+        return resolve_policy(ref, policies)
+    except PolicyLookupError as exc:
+        raise ImproperlyConfigured(str(exc)) from exc
+
+
+def load_config() -> Config:
+    """Build a :class:`Config` from settings, raising ``ImproperlyConfigured`` on errors."""
+    raw = getattr(settings, SETTING, {})
+    if not isinstance(raw, Mapping):
+        raise ImproperlyConfigured(f"{SETTING} must be a dict")
+    unknown = set(raw) - set(_DEFAULTS)
+    if unknown:
+        raise ImproperlyConfigured(
+            f"Unknown {SETTING} keys: {', '.join(sorted(unknown))}. "
+            f"Valid keys: {', '.join(_DEFAULTS)}."
+        )
+    values = {**_DEFAULTS, **raw}
+
+    mode = values["MODE"]
+    if mode not in MODES:
+        raise ImproperlyConfigured(f"{SETTING}['MODE'] must be one of {MODES}, got {mode!r}")
+
+    policies: dict[str, Policy] = dict(BUILTIN_POLICIES)
+    for name, policy in dict(values["POLICIES"]).items():
+        if not isinstance(policy, Policy):
+            raise ImproperlyConfigured(
+                f"{SETTING}['POLICIES'][{name!r}] must be a Policy, got {type(policy).__name__}"
+            )
+        policies[name] = policy
+
+    default_ref = values["DEFAULT_POLICY"]
+    default_policy = None if default_ref is None else _resolve(default_ref, policies)
+    view_policies = tuple(
+        (pattern, None if ref is None else _resolve(ref, policies))
+        for pattern, ref in dict(values["VIEW_POLICIES"]).items()
+    )
+
+    handler = values["REJECTION_HANDLER"]
+    if isinstance(handler, str):
+        try:
+            handler = import_string(handler)
+        except ImportError as exc:
+            raise ImproperlyConfigured(f"Cannot import REJECTION_HANDLER: {exc}") from exc
+    if not callable(handler):
+        raise ImproperlyConfigured(f"{SETTING}['REJECTION_HANDLER'] must be callable")
+
+    max_upload = values["MAX_UPLOAD_SIZE"]
+    if max_upload is not None and (not isinstance(max_upload, int) or max_upload <= 0):
+        raise ImproperlyConfigured(f"{SETTING}['MAX_UPLOAD_SIZE'] must be a positive int")
+
+    return Config(
+        mode=mode,
+        default_policy=default_policy,
+        policies=MappingProxyType(policies),
+        view_policies=view_policies,
+        rejection_handler=handler,
+        expose_details=bool(values["EXPOSE_DETAILS"]),
+        normalize_content_type=bool(values["NORMALIZE_CONTENT_TYPE"]),
+        max_upload_size=max_upload,
+        messages=MappingProxyType({str(k): v for k, v in dict(values["MESSAGES"]).items()}),
+        on_reject=_check_on_reject(values["ON_REJECT"]),
+        upload_handlers=_check_upload_handlers(values["UPLOAD_HANDLERS"]),
+    )
+
+
+def _check_on_reject(value: Any) -> str:
+    if value not in ON_REJECT:
+        raise ImproperlyConfigured(f"{SETTING}['ON_REJECT'] must be one of {ON_REJECT}")
+    return value
+
+
+def _check_upload_handlers(paths: Any) -> tuple[str, ...]:
+    from django.core.files.uploadhandler import FileUploadHandler
+
+    if isinstance(paths, str) or not paths:
+        raise ImproperlyConfigured(f"{SETTING}['UPLOAD_HANDLERS'] must be a non-empty list")
+    for path in paths:
+        if path == _OWN_HANDLER:
+            raise ImproperlyConfigured(
+                f"{SETTING}['UPLOAD_HANDLERS'] lists the handlers ValidatingUploadHandler "
+                "delegates to; it must not contain ValidatingUploadHandler itself"
+            )
+        try:
+            handler = import_string(path)
+        except ImportError as exc:
+            raise ImproperlyConfigured(f"Cannot import upload handler {path!r}: {exc}") from exc
+        if not (isinstance(handler, type) and issubclass(handler, FileUploadHandler)):
+            raise ImproperlyConfigured(f"{path!r} is not a FileUploadHandler subclass")
+    return tuple(paths)
+
+
+@functools.cache
+def get_config() -> Config:
+    """The cached configuration (rebuilt when the setting changes, e.g. in tests)."""
+    return load_config()
+
+
+@receiver(setting_changed)
+def _reset_config(*, setting: str, **_: Any) -> None:
+    if setting == SETTING:
+        get_config.cache_clear()

uploadshield/django/decorators.py

@@ -0,0 +1,204 @@
+"""Per-view configuration: ``@validate_uploads`` and ``@skip_upload_validation``."""
+
+from __future__ import annotations
+
+import functools
+import inspect
+import sys
+from collections.abc import Callable, Mapping
+from typing import TYPE_CHECKING, Any, Literal, Protocol, TypeVar, cast, overload
+
+from asgiref.sync import sync_to_async
+from django.views import View
+
+from .service import SKIP, USE_DEFAULT, VIEW_ATTR, ViewSpec, rejection_response, validate_request
+
+if TYPE_CHECKING:
+    from django.http import HttpRequest, HttpResponse
+
+    from .conf import PolicyRef
+    from .handlers import ValidatingUploadHandler
+    from .service import UploadValidation
+
+__all__ = ["skip_upload_validation", "validate_uploads"]
+
+if sys.version_info >= (3, 12):
+    from inspect import iscoroutinefunction
+else:  # asgiref also recognises markcoroutinefunction() on Python 3.11
+    from asgiref.sync import iscoroutinefunction
+
+V = TypeVar("V", bound=Callable[..., Any])
+RejectHandler = Callable[["HttpRequest", "UploadValidation"], "HttpResponse"]
+
+
+class ViewDecorator(Protocol):
+    """What ``validate_uploads(...)`` returns: preserves the decorated view's type."""
+
+    def __call__(self, view: V, /) -> V: ...
+
+
+def _check(request: HttpRequest, spec: ViewSpec) -> HttpResponse | None:
+    """Validate the request unless ``ValidatingUploadHandler`` will -> rejection or None.
+
+    With the handler installed nothing needs to happen up front: it reads this view's
+    spec and validates whenever the body is parsed (by the view, a form or DRF).  A
+    multipart POST that was already parsed (before routing), or that Django will parse
+    without the handler, is validated here.  Any other body without the handler (DRF's
+    PUT/PATCH and raw file uploads, which Django never parses) gets a handler for this
+    request, so it is validated while whatever parser reads it.
+    """
+    if spec.mode == "off":
+        return None
+    # DRF's Request (``@api_view``) wraps the HttpRequest; its own ``_files`` says nothing
+    # about whether Django parsed the body.
+    request = getattr(request, "_request", request)
+    parsed = hasattr(request, "_files")
+    handler = _installed_handler(request)
+    if handler is not None and not parsed:
+        # Routing may not see this decorator (DRF, method_decorator): tell the handler.
+        handler.use_spec(spec)
+    if request.method == "POST" and request.content_type == "multipart/form-data":
+        if parsed or handler is None:
+            return rejection_response(request, validate_request(request, spec), spec)
+    elif not parsed and handler is None:
+        _install_handler(request, spec)
+    return None
+
+
+def _installed_handler(request: HttpRequest) -> ValidatingUploadHandler | None:
+    from .handlers import ValidatingUploadHandler
+
+    for handler in request.upload_handlers:
+        if isinstance(handler, ValidatingUploadHandler):
+            return handler
+    return None
+
+
+def _install_handler(request: HttpRequest, spec: ViewSpec) -> None:
+    from .handlers import ValidatingUploadHandler
+
+    inner = list(request.upload_handlers)
+    request.upload_handlers = [ValidatingUploadHandler(request, inner=inner, spec=spec)]
+
+
+async def _acheck(request: HttpRequest, spec: ViewSpec) -> HttpResponse | None:
+    # Parsing the body and running checks is blocking work: keep it off the event loop.
+    return await sync_to_async(_check)(request, spec)
+
+
+def _wrap_function(view: Callable[..., Any], spec: ViewSpec) -> Callable[..., Any]:
+    if iscoroutinefunction(view):  # ty: ignore[deprecated] - asgiref branch on 3.11
+
+        @functools.wraps(view)
+        async def async_view(request: HttpRequest, *args: Any, **kwargs: Any) -> Any:
+            if (response := await _acheck(request, spec)) is not None:
+                return response
+            return await view(request, *args, **kwargs)
+
+        wrapped: Callable[..., Any] = async_view
+    else:
+
+        @functools.wraps(view)
+        def sync_view(request: HttpRequest, *args: Any, **kwargs: Any) -> Any:
+            if (response := _check(request, spec)) is not None:
+                return response
+            return view(request, *args, **kwargs)
+
+        wrapped = sync_view
+    setattr(wrapped, VIEW_ATTR, spec)
+    return wrapped
+
+
+def _wrap_class(cls: type[View], spec: ViewSpec) -> type[View]:
+    dispatch = cls.dispatch
+    try:
+        is_async = bool(cls.view_is_async)
+    except Exception:
+        is_async = False
+
+    if is_async:
+
+        @functools.wraps(dispatch)
+        async def async_dispatch(self: Any, request: HttpRequest, *args: Any, **kwargs: Any) -> Any:
+            if (response := await _acheck(request, spec)) is not None:
+                return response
+            # View.dispatch returns the handler's coroutine for async views.
+            response = dispatch(self, request, *args, **kwargs)
+            return await response if inspect.isawaitable(response) else response
+
+        cls.dispatch = async_dispatch  # ty: ignore[invalid-assignment]
+    else:
+
+        @functools.wraps(dispatch)
+        def sync_dispatch(self: Any, request: HttpRequest, *args: Any, **kwargs: Any) -> Any:
+            if (response := _check(request, spec)) is not None:
+                return response
+            return dispatch(self, request, *args, **kwargs)
+
+        cls.dispatch = sync_dispatch  # ty: ignore[invalid-assignment]
+    setattr(cls, VIEW_ATTR, spec)
+    return cls
+
+
+def _apply(view: V, spec: ViewSpec) -> V:
+    if isinstance(view, type):
+        if not issubclass(view, View):
+            raise TypeError(f"{view.__name__} is not a Django class-based view")
+        return cast("V", _wrap_class(view, spec))
+    return cast("V", _wrap_function(view, spec))
+
+
+@overload
+def validate_uploads(policy: V, /) -> V: ...
+@overload
+def validate_uploads(
+    policy: PolicyRef | None = ...,
+    /,
+    *,
+    fields: Mapping[str, PolicyRef | None] | None = ...,
+    mode: str | None = ...,
+    on_reject: RejectHandler | Literal["reject", "field"] | None = ...,
+) -> ViewDecorator: ...
+def validate_uploads(
+    policy: Any = USE_DEFAULT,
+    /,
+    *,
+    fields: Mapping[str, PolicyRef | None] | None = None,
+    mode: str | None = None,
+    on_reject: RejectHandler | Literal["reject", "field"] | None = None,
+) -> Any:
+    """Validate the files uploaded to a view (function or class-based, sync or async).
+
+    ``policy`` is a :class:`~uploadshield.Policy`, a name from
+    ``UPLOADSHIELD["POLICIES"]``/the presets, or a dotted path; ``fields``
+    overrides it per form field (``None`` skips a field).  ``mode`` overrides the
+    global ``MODE``.  ``on_reject`` decides what a refusal looks like:
+
+    * ``"reject"`` (default ``ON_REJECT``): the request is answered with 400/413/415;
+    * ``"field"``: the file is replaced by an empty placeholder and the view runs, so
+      the form reports the error next to the field;
+    * a callable ``(request, validation) -> HttpResponse``, e.g.
+      :func:`~uploadshield.django.redirect_with_messages`.
+
+    ``ValidatingUploadHandler`` reads these settings while the body streams in.  Without
+    the handler, the decorator validates ``request.FILES`` itself before calling the
+    view, so it also works on its own.
+
+    ::
+
+        @validate_uploads("images")
+        def avatar(request): ...
+
+        @validate_uploads(fields={"cv": "pdf", "photo": "sanitized_images"})
+        class ApplicationView(FormView): ...
+    """
+    if callable(policy):  # bare ``@validate_uploads``
+        return _apply(policy, ViewSpec())
+    spec = ViewSpec(policy=policy, fields=fields or {}, mode=mode, on_reject=on_reject)
+    return functools.partial(_apply, spec=spec)
+
+
+def skip_upload_validation(view: V) -> V:
+    """Exempt a view from upload validation (like ``csrf_exempt``)."""
+    setattr(view, VIEW_ATTR, SKIP)
+    return view

uploadshield/django/exceptions.py

@@ -0,0 +1,39 @@
+"""The exception raised when an upload is refused."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from django.core.exceptions import SuspiciousOperation
+from django.http.multipartparser import MultiPartParserError
+
+if TYPE_CHECKING:
+    from .service import UploadValidation
+
+__all__ = ["UploadRejected"]
+
+
+class UploadRejected(MultiPartParserError, SuspiciousOperation):  # noqa: N818 - Django naming
+    """An uploaded file violated its policy.
+
+    Raised by ``ValidatingUploadHandler`` while Django parses the request body, and by
+    ``ValidatingStorage`` on ``save()``.  The base classes are chosen for Django's own
+    handling:
+
+    * ``MultiPartParserError``: Django answers with ``handler400`` (also when
+      ``DEBUG=True``) and marks the body as unparseable, so code that catches the
+      exception and reads ``request.FILES`` again gets nothing. DRF turns it into its
+      standard 400 ``ParseError``.
+    * ``SuspiciousOperation``: like Django's ``TooManyFilesSent``, a refused upload is
+      a security event.
+
+    Point ``handler400`` at ``uploadshield.django.views.bad_request`` for
+    413/415 status codes and JSON/HTML bodies.
+    """
+
+    def __init__(self, validation: UploadValidation) -> None:
+        self.validation = validation
+        summary = "; ".join(
+            f"{o.result.name!r} ({', '.join(o.result.codes)})" for o in validation.rejected
+        )
+        super().__init__(f"Upload rejected: {summary or 'no details'}")

uploadshield/django/forms.py

@@ -0,0 +1,40 @@
+"""A form field that validates *and* sanitizes uploads."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from django import forms
+from django.core.files.uploadedfile import UploadedFile
+
+from .conf import PolicyRef, get_config
+from .service import build_replacement, field_rejection, validate_file
+
+__all__ = ["ValidatedFileField"]
+
+
+class ValidatedFileField(forms.FileField):
+    """``forms.FileField`` that runs a policy and returns the sanitized file.
+
+    Errors appear next to the field like any other form error, which is the best
+    experience for HTML forms.  ``cleaned_data`` holds the sanitized upload (e.g. a
+    re-encoded image under a random name) with ``content_type`` set from the
+    detected type, never from the client.
+    """
+
+    def __init__(self, *args: Any, policy: PolicyRef = "default", **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+        self.policy = policy
+
+    def clean(self, data: Any, initial: Any = None) -> Any:
+        value = super().clean(data, initial)
+        if not isinstance(value, UploadedFile):
+            return value  # empty, cleared, or the initial (already stored) file
+        config = get_config()
+        policy = config.resolve(self.policy)
+        result = validate_file(value, policy)
+        if result is None:
+            return value
+        if not result.ok:
+            raise field_rejection(result, policy, config)
+        return build_replacement(value, result, policy)