docs: warn against untrusted paths in UploadedFile move()/store() (#10446)

Author: michalsn

system/HTTP/Files/UploadedFile.php

@@ -122,7 +122,9 @@ public function __construct(string $path, string $originalName, ?string $mimeTyp
      * @see http://php.net/is_uploaded_file
      * @see http://php.net/move_uploaded_file
      *
-     * @param string      $targetPath Path to which to move the uploaded file.
+     * @param string      $targetPath Path to which to move the uploaded file. This is NOT sanitized. Never build it from
+     *                                untrusted input: a value containing "../" can move the file outside the intended
+     *                                directory. Use a path controlled by your application.
      * @param string|null $name       The name to rename the file to. When null, the client-provided name is used and sanitized.
      *                                A caller-supplied name is NOT sanitized.
      * @param bool        $overwrite  State for indicating whether to overwrite the previously generated file with the same
@@ -347,8 +349,10 @@ public function isValid(): bool
      * By default, upload files are saved in writable/uploads directory. The YYYYMMDD folder
      * and random file name will be created.
      *
-     * @param string|null $folderName the folder name to writable/uploads directory.
-     * @param string|null $fileName   the name to rename the file to.
+     * @param string|null $folderName the folder name to writable/uploads directory. This is NOT sanitized. Never build
+     *                                it from untrusted input: a value containing "../" can move the file outside the
+     *                                uploads directory.
+     * @param string|null $fileName   the name to rename the file to. A caller-supplied name is NOT sanitized.
      *
      * @return string file full path
      */

user_guide_src/source/libraries/uploaded_files.rst

@@ -331,6 +331,16 @@ In PHP versions below 8.1, this returns ``null``
 Moving Files
 ============
 
+.. warning::
+    Do not let user input directly decide the destination directory. The ``$targetPath`` argument of ``move()`` and the
+    ``$folderName`` argument of ``store()`` are never sanitized, so an attacker-controlled value containing ``../`` can
+    move the uploaded file outside the intended directory. Use directories controlled by your application.
+
+    Filenames are only sanitized by default: ``move()`` sanitizes the client-provided name when the ``$name`` argument is
+    omitted, and ``store()`` generates a random name when ``$fileName`` is omitted. A caller-supplied ``$name`` or
+    ``$fileName`` is NOT sanitized, so if you pass one, generate it yourself or sanitize it with
+    :php:func:`sanitize_filename`.
+
 with Original Filename
 ----------------------