From a3e2bc758266efe0ac377562f9b1ceb78d863bf5 Mon Sep 17 00:00:00 2001
From: Jake Jackson <jake@gravitypdf.com>
Date: Wed, 29 Jul 2026 12:22:33 +1000
Subject: [PATCH] Security Hardening

---
 .github/README.md                        | 432 +++++++++++++++++---
 .github/workflows/php-syntax.yml         |  16 +-
 .github/workflows/phpcs.yml              |  16 +-
 .github/workflows/phpstan.yml            |  16 +-
 .github/workflows/phpunit.yml            |  29 +-
 CHANGELOG.md                             |  77 +++-
 UPGRADE.md                               | 201 +++++++++
 composer.json                            |   5 +-
 src/Upload/Exception.php                 |  20 +-
 src/Upload/File.php                      | 177 +++++++-
 src/Upload/FileInfo.php                  | 168 +++++++-
 src/Upload/FileInfoInterface.php         |   2 +-
 src/Upload/Storage/FileSystem.php        | 321 ++++++++++++++-
 src/Upload/Validation/Extension.php      |   8 +-
 src/Upload/Validation/FileType.php       | 178 ++++++++
 src/Upload/Validation/Mimetype.php       |   8 +-
 src/Upload/Validation/Size.php           |   9 +-
 tests/Upload/ExceptionTest.php           |  40 ++
 tests/Upload/FileInfoTest.php            | 217 +++++++++-
 tests/Upload/FileTest.php                | 311 ++++++++++++++
 tests/Upload/Storage/FileSystemTest.php  | 494 ++++++++++++++++++++++-
 tests/Upload/Validation/FileTypeTest.php | 209 ++++++++++
 22 files changed, 2787 insertions(+), 167 deletions(-)
 create mode 100644 UPGRADE.md
 create mode 100644 src/Upload/Validation/FileType.php
 create mode 100644 tests/Upload/ExceptionTest.php
 create mode 100644 tests/Upload/Validation/FileTypeTest.php

diff --git a/.github/README.md b/.github/README.md
index f7f4cc6..a3db3c0 100644
--- a/.github/README.md
+++ b/.github/README.md
@@ -3,99 +3,439 @@
 [![codecov](https://codecov.io/gh/GravityPDF/Upload/branch/main/graph/badge.svg)](https://codecov.io/gh/GravityPDF/Upload)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 
-This component simplifies file validation and uploading.
+A PHP library to validate and save uploaded files.
 
 **Why was this library forked?**
 
 * Original library was abandoned (untouched since 2018)
-* Adjusted namespace from \Upload to \GravityPdf\Upload
-* Bumped minimum PHP version to 7.3+
-* Sanitized filename and extension, and add UTF-8 filename support
+* Safe defaults: existing files are never overwritten, executable and markup extensions are
+  never written, stored files get mode `0640`, and `upload()` requires validation
+* `Validation\FileType` requires the extension and mimetype to match
+* Sanitizes filenames and extensions, with UTF-8 filename support
+* Stops path traversal, symlinked destinations, dotfiles and control characters in
+  filenames, and writes through a staged file moved into place rather than writing to the
+  destination directly
 * Strict type checking
 * Added `FileSystem::getDirectory()` and `FileInfo::setNameWithExtension()` methods
 * Included unreleased code from upstream repo
+* Bumped minimum PHP version to 7.3+
 * PSR-12 Code Formatting
 * Automated tools: PHPUnit, PHPStan, PHPCS, and PHP Syntax Checker
 
-TODO: [PSR-7 and PSR-17 support (help wanted)](https://github.com/GravityPDF/Upload/issues/8)
-
 ## Installation
 
 ```
 composer require gravitypdf/upload
 ```
 
+### Requirements
+
+PHP 7.3 to 8.5 and `ext-fileinfo`. Optional but recommended: `ext-mbstring` (or `symfony/polyfill-mbstring`) so filenames can be guaranteed UTF-8.
+
+Migrating from `codeguy/upload`? Version 3.x of this package is a drop-in replacement:
+update your imports from `\Upload\…` to `\GravityPdf\Upload\…`.
+
+Upgrading from 3.x? Version 4.0 turns new protections on by default. The
+[upgrade guide](https://github.com/GravityPDF/Upload/blob/main/UPGRADE.md) covers what
+changed and what to check.
+
 ## Usage
 
+### Single-file upload
+
 Assume a file is uploaded with this HTML form:
 
 ```html
 <form method="POST" enctype="multipart/form-data">
-    <input type="file" name="foo" value=""/>
+    <input type="file" name="avatar"/>
     <input type="submit" value="Upload File"/>
 </form>
 ```
 
-When the HTML form is submitted, the server-side PHP code can validate and upload the file like this:
+Server-side, validate the upload, rename it, and store it:
 
 ```php
-$storage = new \GravityPdf\Upload\Storage\FileSystem('/path/to/directory');
-// To override existing files when uploading, pass `true` as the second parameter
-// $storage = new \GravityPdf\Upload\Storage\FileSystem('/path/to/directory', true);
-$file = new \GravityPdf\Upload\File('foo', $storage);
+use GravityPdf\Upload\File;
+use GravityPdf\Upload\Storage\FileSystem;
+use GravityPdf\Upload\Validation\FileType;
+use GravityPdf\Upload\Validation\Size;
 
-// Validate file upload
-// MimeType List => http://www.iana.org/assignments/media-types/media-types.xhtml
-$file->addValidations([
-    // Ensure file is of type "image/png"
-    new \GravityPdf\Upload\Validation\Mimetype('image/png'),
-    new \GravityPdf\Upload\Validation\Extension('png'),
+// Store uploads where the web server will not execute or serve them directly
+$storage = new FileSystem('/path/to/uploads');
 
-    //You can also add multi mimetype validation or extensions
-    //new \GravityPdf\Upload\Validation\Mimetype(['image/png', 'image/gif'])
-    //new \GravityPdf\Upload\Validation\Extension(['png', 'gif']),
+// Reads $_FILES['avatar']
+$file = new File('avatar', $storage);
 
-    // Ensure file is no larger than 5M (use "B", "K", M", or "G")
-    new \GravityPdf\Upload\Validation\Size('5M'),
+// upload() refuses to run unless at least one validation is added
+$file->addValidations([
+    new FileType('png', 'image/png'), // extension and file contents must both say PNG
+    new Size('2M'),                   // max 2 MiB ("B", "K", "M" or "G")
 ]);
 
-// Access data about the file
-// If upload accepts multiple files an array will be returned for each of these
+// isValid() also checks is_uploaded_file(), so call it before reading any metadata
+if ($file->isValid() === false) {
+    foreach ($file->getErrors() as $message) {
+        echo htmlspecialchars($message, ENT_QUOTES, 'UTF-8'), '<br>'; // always escape on output
+    }
+
+    return;
+}
+
+// Store under a random name; keep the client's (sanitized) name for display only
+$displayName = $file->getNameWithExtension();
+$file->setName(bin2hex(random_bytes(16)));
+
+try {
+    $file->upload();
+
+    $storedPath = $file->getUploadedFiles()[0];
+} catch (\Exception $e) {
+    // Validation has already passed, so this is a storage failure: the destination
+    // exists, the extension is blocked, or the disk is full
+}
+```
+
+`FileType` accepts any registered
+[IANA media type](https://www.iana.org/assignments/media-types/media-types.xhtml), such as
+`image/png` or `application/pdf`.
+
+### Reading file metadata
+
+```php
 $data = [
-    'name' => $file->getNameWithExtension(),
-    'extension' => $file->getExtension(),
-    'mime' => $file->getMimetype(),
-    'size' => $file->getSize(),
-    'md5' => $file->getMd5(),
-    'dimensions' => $file->getDimensions(),
+    'name'       => $file->getNameWithExtension(), // sanitized client name; display only
+    'extension'  => $file->getExtension(),
+    'mime'       => $file->getMimetype(),          // sniffed from the contents, not the client's claim
+    'size'       => $file->getSize(),              // bytes, or false if the file is unreadable
+    'hash'       => $file->getHash(),              // sha256 unless you pass another algorithm
+    'dimensions' => $file->getDimensions(),        // ['width' => int, 'height' => int]
 ];
+```
+
+These calls are forwarded to every file in the collection. With one file you get the value
+back, with several you get an array of values, and with none you get `null`. When a field
+accepts multiple files, read metadata per file instead.
+
+### Multi-file upload
+
+```html
+<form method="POST" enctype="multipart/form-data">
+    <input type="file" name="photos[]" multiple/>
+    <input type="submit" value="Upload Files"/>
+</form>
+```
+
+The `$_FILES` key drops the brackets: `new File('photos', $storage)`. `File` acts as a
+collection of the individual files, so `count()`, `foreach` and array offsets all work. A
+file that failed to transfer (too large, nothing selected) is left out, and its error
+message is already in `getErrors()`.
+
+```php
+use GravityPdf\Upload\File;
+use GravityPdf\Upload\Storage\FileSystem;
+use GravityPdf\Upload\Validation\FileType;
+use GravityPdf\Upload\Validation\Size;
+
+$storage = new FileSystem('/path/to/uploads');
+$file = new File('photos', $storage);
+
+$file->addValidations([
+    // One format per call, otherwise every extension is paired with every media type
+    (new FileType(['jpg', 'jpeg'], 'image/jpeg'))
+        ->allow('png', 'image/png')
+        ->allow('webp', 'image/webp'),
+    new Size('10M'),
+]);
+
+// An empty collection has nothing to fail validation, so check the count as well
+if (count($file) === 0 || $file->isValid() === false) {
+    foreach ($file->getErrors() as $message) {
+        echo htmlspecialchars($message, ENT_QUOTES, 'UTF-8'), '<br>';
+    }
 
-// If you have an upload field that accepts multiple files you can access each file's info individually
-$firstFileName = $file[0]->getNameWithExtension();
-if(isset($file[1])) {
-    $secondFileName = $file[1]->getNameWithExtension();
+    return;
 }
 
-// or loop over all files for this key
-foreach($file as $i => $upload) {
-    $name = $upload->getNameWithExtension();
-    $upload->setName('file-'.$i);
+// Rename each file server-side, keeping the client names for display
+$manifest = [];
+foreach ($file as $photo) {
+    $displayName = $photo->getNameWithExtension();
+    $photo->setName(bin2hex(random_bytes(16)));
+
+    $manifest[] = [
+        'display' => $displayName,
+        'stored'  => $photo->getNameWithExtension(),
+        'hash'    => $photo->getHash(),
+    ];
 }
 
-// Try to upload file(s)
 try {
-    // Success!
     $file->upload();
 } catch (\Exception $e) {
-    // Validation errors
-    $errors = $file->getErrors();
-    if(count($errors) === 0) {
-        // Failed for another reason, like the file already exists
-        $error = $e->getMessage();
+    // Multi-file uploads are not atomic: earlier files may already be on disk.
+    // getUploadedFiles() lists what was written so the batch can be rolled back.
+    foreach ($file->getUploadedFiles() as $uploadedPath) {
+        unlink($uploadedPath);
+    }
+
+    return;
+}
+```
+
+Individual files are also reachable by offset. Check with `isset($file[0])` first, because
+files that failed to transfer are missing from the collection.
+
+### Lifecycle callbacks
+
+Four optional hooks fire once per file, each receiving that file's `FileInfoInterface`:
+`beforeValidate`, `afterValidate`, `beforeUpload` and `afterUpload`. Use them for per-file
+work like renaming or audit logging without writing your own loops:
+
+```php
+use GravityPdf\Upload\FileInfoInterface;
+
+$file->beforeUpload(static function (FileInfoInterface $fileInfo): void {
+    $fileInfo->setName(bin2hex(random_bytes(16)));
+});
+
+$file->afterUpload(static function (FileInfoInterface $fileInfo): void {
+    error_log(sprintf('Stored upload as %s', $fileInfo->getNameWithExtension()));
+});
+```
+
+Renaming in `beforeUpload` cannot dodge validation. `upload()` re-runs every validation,
+and the storage deny-list is checked against the final name when the file is written.
+
+### Custom validation rules
+
+Implement `ValidationInterface` and throw `GravityPdf\Upload\Exception` to reject a file.
+The exception message is what `getErrors()` shows the end user:
+
+```php
+use GravityPdf\Upload\Exception;
+use GravityPdf\Upload\FileInfoInterface;
+use GravityPdf\Upload\ValidationInterface;
+
+class MaxDimensions implements ValidationInterface
+{
+    private $maxWidth;
+    private $maxHeight;
+
+    public function __construct(int $maxWidth, int $maxHeight)
+    {
+        $this->maxWidth = $maxWidth;
+        $this->maxHeight = $maxHeight;
+    }
+
+    public function validate(FileInfoInterface $fileInfo): void
+    {
+        $size = $fileInfo->getDimensions();
+
+        if ($size['width'] > $this->maxWidth || $size['height'] > $this->maxHeight) {
+            throw new Exception(
+                sprintf('Image must be no larger than %dx%d pixels', $this->maxWidth, $this->maxHeight),
+                $fileInfo
+            );
+        }
+    }
+}
+
+$file->addValidation(new MaxDimensions(2048, 2048));
+```
+
+Failures accumulate rather than abort: every validation runs against every file, and
+`getErrors()` reports them all at once. Throwing anything other than
+`GravityPdf\Upload\Exception` is caught too, but its message is dropped because PHP
+runtime messages can leak server paths.
+
+### Custom storage backends
+
+Implement `StorageInterface` to store files somewhere other than the local filesystem:
+read from `$fileInfo->getPathname()`, return the destination, and throw
+`GravityPdf\Upload\Exception` on failure.
+
+```php
+use GravityPdf\Upload\FileInfoInterface;
+use GravityPdf\Upload\StorageInterface;
+
+class ObjectStorage implements StorageInterface
+{
+    public function upload(FileInfoInterface $fileInfo): string
+    {
+        $key = 'uploads/' . $fileInfo->getNameWithExtension();
+
+        // ... stream $fileInfo->getPathname() to your object store ...
+
+        return $key;
     }
 }
 ```
 
+The protections described under "Security notes" (the extension deny-list, the
+`basename()` reduction, the symlink refusal, the staged write) live in
+`Storage\FileSystem`. A custom backend needs equivalents of its own.
+
+## Security notes
+
+**Prefer `FileType` over `Mimetype` and `Extension` separately.** Those two check independent
+lists, so content sniffed as `image/gif` stored as `avatar.png` satisfies both. `FileType`
+requires the extension and the contents to describe the same format.
+
+**Generate storage names server-side.** Sanitizing normalises client names, so `report.txt`
+and `report!.txt` both land on `report.txt`. A server-side name avoids the collision and the
+predictable destination:
+
+```php
+$file->setName(bin2hex(random_bytes(16)));   // keep the client name as display metadata only
+```
+
+**Sanitizing is not escaping.** Unsafe characters are rewritten, not escaped. Escape on
+output and use parameterised queries. This applies to `getErrors()`.
+
+**Call `isValid()` before reading metadata.** It performs the `is_uploaded_file()` check;
+the metadata accessors do not. This matters where `$_FILES` is rebuilt by something other
+than the PHP SAPI (PSR-7 bridges, test harnesses, middleware).
+
+**Serve uploads from a directory the web server won't execute.** The storage defaults below
+are backstops, not a substitute for that.
+
+### Extensions blocked by default
+
+`FileSystem` refuses to write these, whatever the validations allowed. The check runs against
+the sanitized extension about to be written and throws `\GravityPdf\Upload\Exception` rather
+than recording a validation error.
+
+| Group | Extensions |
+|---|---|
+| PHP | `php` `php2` `php3` `php4` `php5` `php6` `php7` `php8` `phps` `phtml` `phtm` `phar` `pht` `inc` |
+| Server-side includes | `shtml` `shtm` `stm` |
+| CGI and scripts | `cgi` `fcgi` `pl` `py` `rb` `sh` `bash` `ps1` |
+| Java | `jsp` `jspx` `jspf` `jsw` `jsv` `jshtml` `jar` `war` |
+| ASP / ASP.NET | `asp` `aspx` `asa` `asax` `ascx` `ashx` `asmx` `cer` `cshtml` `vbhtml` |
+| Windows binaries | `exe` `dll` `com` `bat` `cmd` `msi` `scr` `vbs` `ws` `wsf` `hta` |
+| Server configuration | `htaccess` `htpasswd` `ini` `conf` `config` |
+| Markup and script | `html` `htm` `xhtml` `xht` `xhtm` `svg` `svgz` `xml` `xsl` `xslt` `js` `mjs` `swf` `mht` `mhtml` |
+
+The first seven groups are `FileSystem::EXECUTABLE_EXTENSIONS`, which a server runs. The last
+is `FileSystem::MARKUP_EXTENSIONS`, which a browser renders: serving one of those from your own
+origin is stored XSS, and SVG belongs there because it carries `<script>` and event handlers.
+
+The list is not exhaustive. To extend rather than replace it:
+
+```php
+$storage->blockExtensions(
+    array_merge(\GravityPdf\Upload\Storage\FileSystem::defaultBlockedExtensions(), ['csv'])
+);
+```
+
+To accept SVG, take the group you want and sanitize the file contents yourself:
+
+```php
+$storage->blockExtensions(\GravityPdf\Upload\Storage\FileSystem::EXECUTABLE_EXTENSIONS);
+```
+
+### Turning the defaults off
+
+Each is a separate call, so turning one off leaves the others in place:
+
+```php
+$storage = new \GravityPdf\Upload\Storage\FileSystem('/path/to/directory', true); // allow overwriting
+$storage->blockExtensions([]);   // store any extension, including .php
+$storage->setMode(null);         // let the process umask decide, usually world-readable
+
+$file->allowUnvalidatedUploads(); // store whatever is submitted, without validating it
+```
+
+## API reference
+
+All classes live in the `GravityPdf\Upload` namespace.
+
+### File
+
+The entry point. `new File(string $key, StorageInterface $storage)` reads `$_FILES[$key]`
+into a collection of `FileInfoInterface` objects, handling both the single-file and the
+`name="foo[]"` multi-file shape. It throws `RuntimeException` when `file_uploads` is disabled in
+php.ini, and `InvalidArgumentException` when the key is not in `$_FILES`.
+
+| Method | Description |
+|---|---|
+| `addValidation(ValidationInterface $validation): File` | Add a single validation rule. Chainable, as are all setters below. |
+| `addValidations(array $validations): File` | Add several validation rules at once. |
+| `getValidations(): ValidationInterface[]` | The rules added so far. |
+| `isValid(): bool` | Runs `is_uploaded_file()` plus every validation against every file, accumulating failures. Idempotent: each call resets the error list to the construction-time errors and re-validates. |
+| `getErrors(): string[]` | All failures from the last `isValid()` run plus any files that failed to transfer, as `"filename: message"`. Sanitized, but must still be escaped on output. |
+| `upload(): bool` | Re-validates, then stores each file via the storage backend. Throws `Exception` when no validations are configured, when validation fails (details in `getErrors()`), or when storage fails (details in the exception message). |
+| `getUploadedFiles(): string[]` | Destination paths written by the most recent `upload()`. Multi-file uploads are not atomic; after a storage failure this lists what needs rolling back. |
+| `allowUnvalidatedUploads(): File` | Let `upload()` proceed with no validations configured. Deliberately greppable in an audit. |
+| `beforeValidate(callable $callback): File` | Hook run per file before its validations. All four hooks receive that file's `FileInfoInterface`. |
+| `afterValidate(callable $callback): File` | Hook run per file after its validations. |
+| `beforeUpload(callable $callback): File` | Hook run per file before storage. |
+| `afterUpload(callable $callback): File` | Hook run per file after storage. |
+| `File::humanReadableToBytes(string $input): int` | Static helper that converts `'5M'` to `5242880`. Accepts B/K/M/G with an optional trailing `B`, and fractions like `'0.5M'`. Throws `InvalidArgumentException` on unparseable input. |
+
+`File` also implements `Countable`, `ArrayAccess` and `IteratorAggregate` over its
+`FileInfoInterface` objects, and forwards any other method call to them: with one file the
+call returns that file's value, with several it returns an array of values, and with none it
+returns `null`.
+
+### FileInfo
+
+The per-file value object; extends `SplFileInfo` and implements `FileInfoInterface`, so path
+accessors such as `getPathname()` are available alongside these:
+
+| Method | Description |
+|---|---|
+| `getName(): string` / `setName(string $name): FileInfo` | Name without extension. `setName()` **sanitizes**: unsafe characters become `-`, characters that reorder, break or hide the text around them (bidi overrides, zero-width marks, line and paragraph separators, the BOM) are deleted, reserved Windows device names are blanked, the result is truncated to 255 bytes and falls back to `unnamed-file`. With `ext-mbstring` the truncation lands on a character boundary and the result is forced to valid UTF-8; see [Requirements](#requirements). |
+| `getExtension(): string` / `setExtension(string $ext): FileInfo` | Extension without the leading dot. `setExtension()` **validates**: anything not lowercase-alphanumeric after trimming, or longer than `FileInfo::MAX_EXTENSION_LENGTH` (32) bytes, is discarded entirely, leaving no extension, rather than being rewritten into something the client never sent. |
+| `getNameWithExtension(): string` / `setNameWithExtension(string $name): FileInfo` | Both parts together; the setter splits the input and applies the two rules above. |
+| `getMimetype(): string` | Media type sniffed from the file contents via `ext-fileinfo`, not the client-supplied value. |
+| `getSize(): int\|false` | Size in bytes, or `false` when the file cannot be read. |
+| `getHash(string $algorithm = 'sha256'): string` | File hash; empty string when the file cannot be read. Throws `Exception` for an algorithm this PHP build does not support. |
+| `getDimensions(): array` | `['width' => int, 'height' => int]`; both `0` for non-images. |
+| `isUploadedFile(): bool` | Wraps `is_uploaded_file()`. Called by `File::isValid()`. |
+| `FileInfo::setFactory(callable $factory): void` | Static: install a factory `File` uses to build each `FileInfoInterface`. This is the seam for substituting test doubles, since the constructor is `final`, and it is process-wide state. |
+| `FileInfo::resetFactory(): void` | Static: clear an installed factory. |
+
+### Storage\FileSystem
+
+The shipped `StorageInterface` implementation; stores files in a local directory.
+`new FileSystem(string $directory, bool $overwrite = false)` throws
+`InvalidArgumentException` when the directory does not exist or is not writable. The
+constructor enables the deny-list and the `0640` file mode; see "Turning the defaults off".
+
+| Method | Description |
+|---|---|
+| `upload(FileInfoInterface $fileInfo): string` | Store the file and return its destination path. Reduces the name to a `basename()`, drops trailing dots and spaces, refuses names starting with `.` or containing control characters, refuses a blocked extension in any dot-separated component, and refuses a symlinked destination. Writes to a staged file in the same directory and moves it into place, so the stored file appears under its final name complete and already at the configured mode. With `$overwrite = false` the destination is claimed with an exclusive create first, so concurrent requests cannot both win. Throws `Exception` on any refusal. |
+| `blockExtensions(?array $extensions = null): FileSystem` | Set the extensions that are never written, checked against the sanitized extension at the write. `null` (the default) means `defaultBlockedExtensions()`; `[]` disables the check. |
+| `setMode(?int $mode): FileSystem` | Permissions applied to each stored file, default `FileSystem::DEFAULT_MODE` (`0640`). `null` leaves the mode to the process umask. |
+| `getDirectory(): string` | The destination directory, without trailing slash. |
+| `FileSystem::defaultBlockedExtensions(): string[]` | Static: `EXECUTABLE_EXTENSIONS` merged with `MARKUP_EXTENSIONS`, the table under "Extensions blocked by default". |
+
+### Validations
+
+Each implements `ValidationInterface` and throws `Exception` on failure.
+
+| Class | Description |
+|---|---|
+| `Validation\FileType($extensions, $mimetypes)` | Requires the file's extension and its sniffed contents to describe the same format. Either argument accepts a string or an array; chain `allow($extensions, $mimetypes)` to accept additional formats, one format per call. |
+| `Validation\Size($maxSize, $minSize = 0)` | Inclusive size bounds, as bytes or human-readable strings (`'5M'`). |
+| `Validation\Extension($extensions)` | **Deprecated** since 4.0.0. Checks the extension alone, which says nothing about the contents. Use `FileType`. |
+| `Validation\Mimetype($mimetypes)` | **Deprecated** since 4.0.0. Checks the sniffed type alone, which a polyglot file satisfies trivially. Use `FileType`. |
+
+### Exception
+
+`GravityPdf\Upload\Exception` extends `\Exception` and is thrown by validations, storage and
+`File::upload()`. `getFileInfo(): ?FileInfoInterface` returns the offending file, so a caller
+can tell which file in a multi-file upload failed.
+
+### Interfaces
+
+| Interface | Contract |
+|---|---|
+| `StorageInterface` | `upload(FileInfoInterface $fileInfo): string` stores the file, returns the destination path, and throws on failure. |
+| `ValidationInterface` | `validate(FileInfoInterface $fileInfo): void` signals failure by throwing `Exception`, never by returning a value. |
+| `FileInfoInterface` | The per-file value object contract listed under `FileInfo`, for supplying your own implementation via `FileInfo::setFactory()`. |
+
 ## Authors
 
 * [Josh Lockhart](https://github.com/codeguy)
diff --git a/.github/workflows/php-syntax.yml b/.github/workflows/php-syntax.yml
index 119dd4d..cc52561 100644
--- a/.github/workflows/php-syntax.yml
+++ b/.github/workflows/php-syntax.yml
@@ -6,6 +6,10 @@ on:
       - main
   pull_request:
 
+# The workflows only read the repository; nothing needs a write-capable GITHUB_TOKEN.
+permissions:
+  contents: read
+
 # Cancels all previous workflow runs for pull requests that have not completed.
 concurrency:
   # The concurrency group contains the workflow name and the branch name for pull requests
@@ -24,10 +28,10 @@ jobs:
 
     steps:
       - name: Checkout
-        uses: actions/checkout@v6
+        uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6.0.0
 
       - name: Install PHP
-        uses: shivammathur/setup-php@v2
+        uses: shivammathur/setup-php@f3e473d116dcccaddc5834248c87452386958240 # v2.35.5
         with:
           php-version: ${{ matrix.php }}
 
@@ -42,14 +46,14 @@ jobs:
       # http://man7.org/linux/man-pages/man1/date.1.html
       - name: "Get last Monday's date"
         id: get-date
-        run: echo "::set-output name=date::$(/bin/date -u --date='last Mon' "+%F")"
+        run: echo "date=$(/bin/date -u --date='last Mon' "+%F")" >> "$GITHUB_OUTPUT"
 
       - name: Get Composer cache directory
         id: composer-cache
-        run: echo "::set-output name=dir::$(composer config cache-files-dir)"
+        run: echo "dir=$(composer config cache-files-dir)" >> "$GITHUB_OUTPUT"
 
       - name: Cache Composer dependencies
-        uses: actions/cache@v5
+        uses: actions/cache@caa296126883cff596d87d8935842f9db880ef25 # v5.0.4
         env:
           cache-name: cache-composer-dependencies
         with:
@@ -58,7 +62,7 @@ jobs:
 
 
       - name: Install Composer dependencies
-        run: composer install
+        run: composer install --no-scripts
 
       - name: Check PHP Syntax
         run: composer run check-syntax
diff --git a/.github/workflows/phpcs.yml b/.github/workflows/phpcs.yml
index 12b999b..2e2b7dd 100644
--- a/.github/workflows/phpcs.yml
+++ b/.github/workflows/phpcs.yml
@@ -6,6 +6,10 @@ on:
       - main
   pull_request:
 
+# The workflows only read the repository; nothing needs a write-capable GITHUB_TOKEN.
+permissions:
+  contents: read
+
 # Cancels all previous workflow runs for pull requests that have not completed.
 concurrency:
   # The concurrency group contains the workflow name and the branch name for pull requests
@@ -19,10 +23,10 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v6
+        uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6.0.0
 
       - name: Install PHP
-        uses: shivammathur/setup-php@v2
+        uses: shivammathur/setup-php@f3e473d116dcccaddc5834248c87452386958240 # v2.35.5
         with:
           php-version: 7.3
 
@@ -37,14 +41,14 @@ jobs:
       # http://man7.org/linux/man-pages/man1/date.1.html
       - name: "Get last Monday's date"
         id: get-date
-        run: echo "::set-output name=date::$(/bin/date -u --date='last Mon' "+%F")"
+        run: echo "date=$(/bin/date -u --date='last Mon' "+%F")" >> "$GITHUB_OUTPUT"
 
       - name: Get Composer cache directory
         id: composer-cache
-        run: echo "::set-output name=dir::$(composer config cache-files-dir)"
+        run: echo "dir=$(composer config cache-files-dir)" >> "$GITHUB_OUTPUT"
 
       - name: Cache Composer dependencies
-        uses: actions/cache@v5
+        uses: actions/cache@caa296126883cff596d87d8935842f9db880ef25 # v5.0.4
         env:
           cache-name: cache-composer-dependencies
         with:
@@ -52,7 +56,7 @@ jobs:
           key: ${{ runner.os }}-php-7.3-date-${{ steps.get-date.outputs.date }}-composer-${{ hashFiles('**/composer.json') }}
 
       - name: Install Composer dependencies
-        run: composer install
+        run: composer install --no-scripts
 
       - name: Run PHPUnit tests
         run: composer run lint
diff --git a/.github/workflows/phpstan.yml b/.github/workflows/phpstan.yml
index 7fcbdfb..5f01417 100644
--- a/.github/workflows/phpstan.yml
+++ b/.github/workflows/phpstan.yml
@@ -6,6 +6,10 @@ on:
       - main
   pull_request:
 
+# The workflows only read the repository; nothing needs a write-capable GITHUB_TOKEN.
+permissions:
+  contents: read
+
 # Cancels all previous workflow runs for pull requests that have not completed.
 concurrency:
   # The concurrency group contains the workflow name and the branch name for pull requests
@@ -19,10 +23,10 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v6
+        uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6.0.0
 
       - name: Install PHP
-        uses: shivammathur/setup-php@v2
+        uses: shivammathur/setup-php@f3e473d116dcccaddc5834248c87452386958240 # v2.35.5
         with:
           php-version: 7.3
 
@@ -37,14 +41,14 @@ jobs:
       # http://man7.org/linux/man-pages/man1/date.1.html
       - name: "Get last Monday's date"
         id: get-date
-        run: echo "::set-output name=date::$(/bin/date -u --date='last Mon' "+%F")"
+        run: echo "date=$(/bin/date -u --date='last Mon' "+%F")" >> "$GITHUB_OUTPUT"
 
       - name: Get Composer cache directory
         id: composer-cache
-        run: echo "::set-output name=dir::$(composer config cache-files-dir)"
+        run: echo "dir=$(composer config cache-files-dir)" >> "$GITHUB_OUTPUT"
 
       - name: Cache Composer dependencies
-        uses: actions/cache@v5
+        uses: actions/cache@caa296126883cff596d87d8935842f9db880ef25 # v5.0.4
         env:
           cache-name: cache-composer-dependencies
         with:
@@ -52,7 +56,7 @@ jobs:
           key: ${{ runner.os }}-php-7.3-date-${{ steps.get-date.outputs.date }}-composer-${{ hashFiles('**/composer.json') }}
 
       - name: Install Composer dependencies
-        run: composer install
+        run: composer install --no-scripts
 
       - name: Run PHPUnit tests
         run: composer run phpstan
diff --git a/.github/workflows/phpunit.yml b/.github/workflows/phpunit.yml
index ebc60a2..dabd97e 100644
--- a/.github/workflows/phpunit.yml
+++ b/.github/workflows/phpunit.yml
@@ -6,6 +6,10 @@ on:
       - main
   pull_request:
 
+# The workflows only read the repository; nothing needs a write-capable GITHUB_TOKEN.
+permissions:
+  contents: read
+
 # Cancels all previous workflow runs for pull requests that have not completed.
 concurrency:
   # The concurrency group contains the workflow name and the branch name for pull requests
@@ -28,10 +32,10 @@ jobs:
 
     steps:
       - name: Checkout
-        uses: actions/checkout@v6
+        uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6.0.0
 
       - name: Install PHP
-        uses: shivammathur/setup-php@v2
+        uses: shivammathur/setup-php@f3e473d116dcccaddc5834248c87452386958240 # v2.35.5
         with:
           php-version: ${{ matrix.php }}
 
@@ -46,14 +50,14 @@ jobs:
       # http://man7.org/linux/man-pages/man1/date.1.html
       - name: "Get last Monday's date"
         id: get-date
-        run: echo "::set-output name=date::$(/bin/date -u --date='last Mon' "+%F")"
+        run: echo "date=$(/bin/date -u --date='last Mon' "+%F")" >> "$GITHUB_OUTPUT"
 
       - name: Get Composer cache directory
         id: composer-cache
-        run: echo "::set-output name=dir::$(composer config cache-files-dir)"
+        run: echo "dir=$(composer config cache-files-dir)" >> "$GITHUB_OUTPUT"
 
       - name: Cache Composer dependencies
-        uses: actions/cache@v5
+        uses: actions/cache@caa296126883cff596d87d8935842f9db880ef25 # v5.0.4
         env:
           cache-name: cache-composer-dependencies
         with:
@@ -61,13 +65,20 @@ jobs:
           key: ${{ runner.os }}-php-${{ matrix.php }}-date-${{ steps.get-date.outputs.date }}-composer-${{ hashFiles('**/composer.json') }}
 
       - name: Install Composer dependencies
-        run: composer install
+        run: composer install --no-scripts
 
       - name: Run PHPUnit tests
         run: vendor/bin/phpunit
 
       - name: Run (xDebug) tests
         if: ${{ matrix.report }}
-        run: |
-          vendor/bin/phpunit --verbose --coverage-clover=tmp/coverage/report-xml/php-coverage1.xml
-          bash <(curl -s https://codecov.io/bash);
+        run: vendor/bin/phpunit --verbose --coverage-clover=tmp/coverage/report-xml/php-coverage1.xml
+
+      # Replaces `bash <(curl -s https://codecov.io/bash)` — an unpinned remote script piped
+      # into bash, which was compromised in April 2021 and has since been sunset by Codecov.
+      - name: Upload coverage to Codecov
+        if: ${{ matrix.report }}
+        uses: codecov/codecov-action@0fb7174895f61a3b6b78fc075e0cd60383518dac # v5.5.1
+        with:
+          files: tmp/coverage/report-xml/php-coverage1.xml
+          token: ${{ secrets.CODECOV_TOKEN }}
diff --git a/CHANGELOG.md b/CHANGELOG.md
index cc341ba..5d71b7c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,3 +1,78 @@
+# Upload 4.0.0
+
+This update focuses on security-hardening, and the library has new protections enabled by default. A step-by-step upgrade guide is in [UPGRADE.md](https://github.com/GravityPDF/Upload/blob/main/UPGRADE.md).
+
+## Defaults That Changed
+
+* **A default extension deny-list is on.** `FileSystem` now refuses to write files with the extensions in `FileSystem::defaultBlockedExtensions()`
+* **The deny-list now covers markup as well as executables.** The 15 in `FileSystem::MARKUP_EXTENSIONS` (`html`, `htm`, `xhtml`, `xht`, `xhtm`, `svg`, `svgz`, `xml`, `xsl`, `xslt`, `js`, `mjs`, `swf`, `mht`, `mhtml`) join the 59 in `EXECUTABLE_EXTENSIONS` for a default list of 74. A server does not execute the markup ones, but serving them from your own origin is a stored XSS risk. **If you accept SVG or HTML uploads, pass `FileSystem::EXECUTABLE_EXTENSIONS` and sanitize the contents yourself**
+* **Stored files get mode `0640`** (`FileSystem::DEFAULT_MODE`), where 3.x left the mode to the process umask
+* **`File::upload()` refuses when no validations have been added**
+* **`FileSystem::upload()` rejects a destination beginning with a dot, and any name containing control characters**
+* **The deny-list is checked against every dot-separated component of the name**, not only the extension `pathinfo()` returns, because a web server does not necessarily read a name the same way. `archive.config.zip` is refused while `config` is on the list. Trailing dots and spaces are removed from the name before it is checked and before it is written. The first component is not treated as an extension, so a file called `php` is still stored
+* **`File::upload()` refuses when the collection is empty.** Validations pass vacuously when there is nothing to run them against, so it previously returned `true` having stored nothing. A failed transfer is unchanged and still reports `'File validation failed'` with the detail in `getErrors()`
+
+## Security Fixes
+
+* **`\GravityPdf\Upload\FileInfo::setExtension()` no longer rewrites an invalid extension into a valid one.** Stripping the disallowed characters could produce an extension the client never sent. An extension that is not lowercase-alphanumeric once trimmed is now discarded, and the file is stored with **no extension**
+* **`FileInfo::setExtension()` discards an extension longer than `FileInfo::MAX_EXTENSION_LENGTH` (32 bytes).** The extension counts against the same 255 byte limit as the name, and a long enough one could push the stored filename past it
+* **`FileInfo::setName()` removes `\x7F` (DEL)**, completing the set of control characters it already removed. A name containing it passed `isValid()` and then failed at `upload()` with nothing in `getErrors()` to explain why
+* **`FileInfo::setName()` removes the characters that reorder, break or hide the text around them** — bidi overrides (`U+202A`–`U+202E`), isolates (`U+2066`–`U+2069`), zero-width marks (`U+200B`–`U+200F`), the line and paragraph separators (`U+2028`, `U+2029`) and the BOM (`U+FEFF`). A stored name is read by people, in admin listings, emails and log lines, and these let it display as something other than what it is
+* **`\GravityPdf\Upload\Storage\FileSystem::upload()` now reduces the destination to a basename** and rejects `''`, `.`, `..` and names containing a null byte
+* **`FileSystem::upload()` refuses to write to a destination that is a symbolic link**
+* **Uploads are written through a staged file rather than straight to the destination.** The file goes to a temporary name inside the destination directory and is then moved onto the destination in a single operation, which does not follow a symbolic link standing there. The stored file appears under its final name only once it is complete and already carries the configured mode
+* **The overwrite guard is atomic with respect to two requests creating the same name.** With `overwrite = false`, the existence check and the create are a single exclusive operation instead of two separate steps, the file that operation creates is verified to be the destination itself, and a placeholder left by a failed move is cleaned up
+* **A `chmod()` that fails is no longer ignored.** The mode is applied to the staged file and the upload is abandoned if it cannot be set, rather than storing the file at whatever the umask allowed while reporting the documented `0640`
+* **`blockExtensions()` accepts and removes a leading dot.** The values compared against the list never carry one, so `blockExtensions(['.php'])` blocked nothing while appearing to tighten the list. **Check any custom list you pass**
+* **`Validation\FileType::allow()` rejects empty strings, not just empty arrays.** `new FileType('png', '')` registered an empty media type instead of throwing, and an empty media type is what `getMimetype()` reports for a file it cannot read. Whitespace-only values and a lone `.` are rejected the same way, and a leading dot on an extension is accepted and removed
+* **Raw `$_FILES[…]['name']` no longer reaches `getErrors()`.** The `File` constructor's error path now sanitizes the client-supplied filename like every other error string. Escaping on output still applies
+* **`getHash()`, `getMimetype()`, `getSize()` and `getDimensions()` no longer fault on a missing file.** They return `''`/`false`/`0` when there is no readable file behind the pathname
+* **`\GravityPdf\Upload\File::isValid()` absorbs non-`Upload\Exception` throwables** from validators instead of letting one abort the batch. The recorded message omits the original text, because PHP runtime messages can contain server paths
+
+## Breaking Changes
+
+* `FileInfo::setExtension()` discards non-alphanumeric extensions rather than stripping characters from them (see above). Files that previously landed with a synthesized extension now land with none
+* Windows reserved names are matched against the whole extension instead of as a substring. `doc.conf` kept its extension as `f` and `ico.icon` as `i`; both are now preserved intact (`conf`, `icon`). `x.aux` is still blanked, because `aux` is itself a reserved device name
+* `File::__construct()` no longer creates a `FileInfo` for a single file that failed to upload, matching what the multi-file branch has always done. `count($file)` is now `0` rather than `1` for e.g. `UPLOAD_ERR_NO_FILE`, and reading metadata on it no longer raises an uncaught `ValueError`
+* `File::isValid()` resets the error list to the errors recorded during construction instead of appending to whatever the previous call left behind. The `if (!$file->isValid()) {…} $file->upload();` pattern calls it twice, since `upload()` calls it again, and no longer reports every error twice. Validations are still re-run on every call, so that renaming a file between `isValid()` and `upload()` cannot skip revalidation
+* `File::humanReadableToBytes()` now throws `InvalidArgumentException` on input it cannot parse. `'abc'` and `''` previously evaluated to `0`, which silently configures a `Size` bound that rejects every upload. A negative size such as `'-5M'` throws for the same reason; it previously produced a negative bound.
+* **`File::humanReadableToBytes()` now understands a trailing `B`, which changes an existing limit.** `'5MB'` previously parsed as 5 bytes, because `substr($input, -1)` saw only the `B`. It now parses as 5 MiB, matching what `Validation\Size`'s docblock has always advertised. **If you pass a `MB`/`KB`/`GB` suffixed size anywhere, your effective limit becomes much larger.** Sizes without the trailing `B` are unaffected.
+* `File::humanReadableToBytes()` supports fractions (`'0.5M'` → `524288`, previously `0`) and clamps to `PHP_INT_MAX` instead of raising a `TypeError` on very large inputs.
+* `File::offsetSet()` throws `InvalidArgumentException` unless the value is a `FileInfoInterface`. The type was previously only a docblock, so `$file[0] = 'string';` succeeded and then faulted inside `isValid()`.
+* **`FileInfo::getMd5()` has been removed**, from `FileInfo` and from `FileInfoInterface`. Call `getHash('md5')` if you need the same digest for a non-security purpose.
+* **`FileInfo::getHash()` defaults to `sha256` instead of `md5`**, and is now declared on `FileInfoInterface`. A call to `getHash()` with no argument returns a different string than it did in 3.x.
+* `FileInfo::getHash()` throws `\GravityPdf\Upload\Exception` for an algorithm not in `hash_algos()`, rather than a `ValueError`, and returns `''` on an unreadable file (it previously raised a `TypeError`).
+* `FileInfo::getSize()` returns `false` for an unreadable file, matching the `int|false` that `FileInfoInterface` documents. On PHP 8 `SplFileInfo::getSize()` throws instead.
+* Sanitized filenames are valid UTF-8 where `ext-mbstring` is loaded (now under `suggest`; `symfony/polyfill-mbstring` also works). Without it, truncation can still split a multibyte character, as in 3.x.
+* `\GravityPdf\Upload\Exception::__construct()` now declares `string $message`. It was untyped while the rest of the codebase is strict.
+
+## New Features
+
+* `\GravityPdf\Upload\Validation\FileType($extensions, $mimetypes)`: pairs the extension with the sniffed media type and requires them to agree. `Validation\Extension` and `Validation\Mimetype` check two independent allow-lists, so given `Extension(['png', 'gif'])` and `Mimetype(['image/png', 'image/gif'])` a file sniffed as `image/gif` and stored as `avatar.png` satisfies both. Either side accepts a list, so `new FileType(['jpg', 'jpeg'], 'image/jpeg')` covers one format; chain `allow($extensions, $mimetypes)` for further formats rather than widening a single call, which would pair every extension with every media type. The two existing validators are unchanged and still exported.
+* `\GravityPdf\Upload\Storage\FileSystem::blockExtensions(?array $extensions = null)`: the deny-list applied at the write, independent of whichever validations the caller configured. Passing `null` (or nothing) uses `defaultBlockedExtensions()`. An allow-list via `Validation\FileType` remains the primary control.
+* `\GravityPdf\Upload\Storage\FileSystem::defaultBlockedExtensions(): string[]`: `EXECUTABLE_EXTENSIONS` merged with `MARKUP_EXTENSIONS`. A method rather than a constant because constant expressions cannot call `array_merge()` on PHP 7.3.
+* `\GravityPdf\Upload\Storage\FileSystem::setMode(?int $mode)`: permissions for stored files, defaulting to `FileSystem::DEFAULT_MODE`.
+* `\GravityPdf\Upload\File::allowUnvalidatedUploads(): File`: the opt-out for the new requirement that `upload()` has something to validate against.
+* `\GravityPdf\Upload\File::getUploadedFiles(): string[]`: the destination paths written by the most recent `upload()` call. A multi-file upload is not atomic; when a later file fails, this is how a caller finds out what was already committed to disk. `getErrors()` is empty in that case, because a storage failure is not a validation failure.
+* `\GravityPdf\Upload\FileInfo::resetFactory(): void`: clears a factory installed with `setFactory()`. There was previously no supported way to undo it in a long-lived process or between tests.
+* `\GravityPdf\Upload\Exception::__construct()` accepts `$code` and `$previous`, so the exception chain is no longer discarded.
+
+## Deprecations
+
+Both still work and neither raises a runtime notice.
+
+* `\GravityPdf\Upload\Validation\Extension` and `\GravityPdf\Upload\Validation\Mimetype` are deprecated in favour of `Validation\FileType`. Used side by side they check independent allow-lists, which is the gap `FileType` closes.
+
+## Bug Fixes
+
+* `mb_detect_encoding()` is called with an explicit detect order and falls back to UTF-8. An application that removed ASCII from its `mb_detect_order()` turned every high-byte filename into an uncaught `ValueError` from `mb_strcut()`.
+* A file named `0` keeps its name. `empty('0')` is true, so it was replaced with `unnamed-file`.
+* A field named `f[0][0]` no longer emits "Array to string conversion" or reports the file as `"Array: …"`. It nests `$_FILES` one level deeper than either shape `File` understands, so the entry is an array where a path belongs; those entries are now skipped with an error recorded.
+* `Validation\FileType` lowercases the media type it reads from the file before comparing. It already lowercased the configured list, so a custom `FileInfoInterface` returning `IMAGE/PNG` failed against `image/png`. The shipped `FileInfo` lowercases in `getMimetype()` and was unaffected.
+* `FileSystem::upload()` distinguishes a destination it could not create from one that already exists. A directory removed or de-permissioned after the constructor checked it reported `'File already exists'`, sending the caller into a rename-and-retry loop that could not succeed. It now throws `'Destination file could not be created'`.
+* `Validation\Size` reports a file whose size cannot be determined as a validation error instead of letting `SplFileInfo::getSize()`'s `RuntimeException` escape.
+* Corrected `@throws RuntimeException` annotations on the shipped validators to `@throws \GravityPdf\Upload\Exception`, which is what they actually throw.
+
 # Upload 3.0.0
 
 ## Breaking Changes
@@ -51,4 +126,4 @@
 *
 
 ## Bug Fixes
-* Resolved PHP 8.1 warnings
\ No newline at end of file
+* Resolved PHP 8.1 warnings
diff --git a/UPGRADE.md b/UPGRADE.md
new file mode 100644
index 0000000..27e4c9b
--- /dev/null
+++ b/UPGRADE.md
@@ -0,0 +1,201 @@
+# Upgrading from 3.x to 4.0
+
+4.0 is a security-hardening release. Most of the API is unchanged, but new protections are
+on by default and can refuse uploads that 3.x accepted, so work through this guide before
+deploying. The [changelog](CHANGELOG.md) is the complete record.
+
+Coming from the original `codeguy/upload` package? Replace the `\Upload` namespace prefix
+with `\GravityPdf\Upload` to get the 3.x API, then continue here.
+
+## 1. Update the package
+
+```bash
+composer require gravitypdf/upload:^4.0
+```
+
+4.0 runs on PHP 7.3 through 8.5 and still requires only `ext-fileinfo`. `ext-mbstring` is
+now listed under `suggest`: it is optional, but without it sanitized filenames are not
+guaranteed to be valid UTF-8. See
+[Requirements](.github/README.md#requirements).
+
+## 2. `upload()` now requires a validation
+
+Calling `upload()` with no validations configured throws `\GravityPdf\Upload\Exception`.
+Add at least one validation, or opt out:
+
+```php
+use GravityPdf\Upload\Validation\FileType;
+
+$file->addValidation(new FileType('pdf', 'application/pdf'));
+
+// Or keep the 3.x behaviour of storing whatever arrives
+$file->allowUnvalidatedUploads();
+```
+
+## 3. Executable and markup extensions are refused by default
+
+`Storage\FileSystem` no longer writes a file whose extension is in
+`FileSystem::defaultBlockedExtensions()`: extensions a server executes or reads as
+configuration (`php`, `cgi`, `exe`, `htaccess`, `config`) plus markup a browser renders
+(`html`, `svg`, `js`, `xml`). The full table is in the
+[README](.github/README.md#extensions-blocked-by-default). The refusal throws
+`\GravityPdf\Upload\Exception` from `upload()`; it is not a validation error and does not
+appear in `getErrors()`.
+
+**Every dot-separated component of the name is checked, not only the extension.** A web
+server does not necessarily read a filename the way `pathinfo()` does, so a blocked word
+anywhere between dots is refused — including in names you may consider ordinary, such as
+`release.config.zip`. If that affects you, narrow the list:
+
+```php
+$storage->blockExtensions(
+    array_diff(\GravityPdf\Upload\Storage\FileSystem::defaultBlockedExtensions(), ['config'])
+);
+```
+
+Trailing dots and spaces are removed from the name before it is checked and before it is
+written, so `report.txt.` is stored as `report.txt`. The first component is never treated as
+an extension, so a file called `php` is still stored.
+
+Most applications can leave this alone. If you accept one of the blocked formats:
+
+```php
+use GravityPdf\Upload\Storage\FileSystem;
+
+// Accept markup such as SVG and HTML, and sanitize the contents yourself
+$storage->blockExtensions(FileSystem::EXECUTABLE_EXTENSIONS);
+
+// Or restore the 3.x behaviour of writing any extension
+$storage->blockExtensions([]);
+```
+
+## 4. Stored files get mode `0640`
+
+3.x left file permissions to the process umask, which commonly produced a world-readable
+`0644`. 4.0 applies `0640` (owner read/write, group read) to every stored file. If another
+user account serves or processes the uploads, give it access:
+
+```php
+// Pick the mode you need, or pass null to leave it to the umask as 3.x did
+$storage->setMode(0644);
+```
+
+## 5. `'5MB'` now parses as 5 MiB, not 5 bytes
+
+`File::humanReadableToBytes()`, which `Validation\Size` uses, now understands a trailing
+`B`. 3.x read only the final character, so `'5MB'` evaluated to 5 bytes; it now
+evaluates to the 5 MiB that `Validation\Size` always documented. Check any size bound with
+a `KB`/`MB`/`GB` suffix, because its effective limit becomes much larger. Sizes without
+the trailing `B` are unchanged. Unparseable input such as `'abc'` now throws
+`InvalidArgumentException` instead of silently becoming `0`, and fractions like `'0.5M'`
+work.
+
+## 6. `getMd5()` is gone and `getHash()` now means SHA-256
+
+`FileInfo::getMd5()` has been removed from both `FileInfo` and `FileInfoInterface`, and
+`getHash()` defaults to `sha256`:
+
+```php
+$hash = $fileInfo->getMd5();        // 3.x
+$hash = $fileInfo->getHash('md5');  // 4.0: the same digest
+$hash = $fileInfo->getHash();       // 4.0: SHA-256
+```
+
+If you compare new uploads against digests stored by 3.x, pass `'md5'` or migrate the
+stored values.
+
+## 7. A failed transfer leaves the collection empty
+
+When nothing was selected or the file exceeded PHP's own limits, 3.x still created a
+`FileInfo` for a single-file field, and reading its metadata raised an uncaught error. 4.0
+leaves the failed file out of the collection, matching what multi-file fields have always
+done: `count($file)` is `0`, forwarded metadata calls return `null`, and the error message
+is already in `getErrors()`. Check the count before reading any metadata:
+
+```php
+if (count($file) === 0 || $file->isValid() === false) {
+    // getErrors() explains what went wrong
+    return;
+}
+```
+
+## 8. Invalid extensions are discarded, not repaired
+
+`FileInfo::setExtension()` lowercases and trims the extension, then discards it when
+anything other than letters and digits remains. 3.x deleted the offending characters, which
+could build an extension the client never sent. A file that previously landed with a
+repaired extension now lands with none; if your application requires an extension, a
+`FileType` validation rejects those files up front.
+
+## 9. Swap `Extension` and `Mimetype` for `FileType` (recommended)
+
+`Validation\Extension` and `Validation\Mimetype` still work and raise no runtime notice,
+but they are deprecated. Side by side they check two independent allow-lists;
+`Validation\FileType` requires the extension and the sniffed contents to describe the same
+format:
+
+```php
+use GravityPdf\Upload\Validation\Extension;
+use GravityPdf\Upload\Validation\FileType;
+use GravityPdf\Upload\Validation\Mimetype;
+
+// 3.x
+$file->addValidations([
+    new Extension(['png', 'gif']),
+    new Mimetype(['image/png', 'image/gif']),
+]);
+
+// 4.0
+$file->addValidation(
+    (new FileType('png', 'image/png'))->allow('gif', 'image/gif')
+);
+```
+
+Keep to one format per `allow()` call, otherwise every extension is paired with every
+media type.
+
+## 10. If you implement the library's interfaces
+
+* `FileInfoInterface` now declares `getHash(string $algorithm = 'sha256'): string` and no
+  longer declares `getMd5()`, so custom implementations need updating.
+* `Storage\FileSystem` reduces the name a `FileInfoInterface` returns to its `basename()`,
+  refuses a name that begins with a dot or contains control characters, and refuses a
+  symlinked destination. A name can no longer select a subdirectory; construct the
+  `FileSystem` with the subdirectory instead.
+* Custom validators should throw `\GravityPdf\Upload\Exception` to report a message. Any
+  other throwable is still caught, but its message is left out of `getErrors()` because
+  PHP runtime messages can contain server paths.
+* `Exception::__construct()` now declares `string $message` and accepts `$code` and
+  `$previous`, so a subclass constructor must match the new signature.
+
+## Everything else
+
+Smaller changes, each listed in full in the [changelog](CHANGELOG.md):
+
+* `getHash()`, `getMimetype()`, `getSize()` and `getDimensions()` return `''`/`false`/`0`
+  for an unreadable file instead of raising an error.
+* `isValid()` resets the error list on each call, so the usual `isValid()` then `upload()`
+  sequence no longer reports every error twice.
+* `$file[0] = $value` throws `InvalidArgumentException` unless the value is a
+  `FileInfoInterface`.
+* Sanitized filenames are always valid UTF-8, so they survive `json_encode()` and
+  `utf8mb4` database columns.
+* Windows reserved names are matched against the whole extension, so `doc.conf` keeps
+  `conf` where 3.x cut it down to `f`.
+* With `overwrite` off (the unchanged default), the existence check and the create are one
+  exclusive operation, so two concurrent requests can no longer both win the same
+  destination.
+* The upload is written to a temporary name inside the destination directory and moved into
+  place, rather than written to the destination directly, so it is never visible under its
+  final name half-written or at the wrong mode. A `chmod()` that fails now abandons the
+  upload instead of silently storing the file at the umask's mode. If you watch the upload
+  directory for new files, note the transient `upload-<random>.part` entries.
+* `upload()` throws when the collection is empty rather than returning `true` having stored
+  nothing. Check `count($file)` if an empty file field is a valid outcome for your form.
+* `Validation\FileType` rejects an empty string on either side, where it previously only
+  rejected an empty array. `new FileType('png', '')` now throws `InvalidArgumentException`.
+  A leading dot on an extension is accepted and removed, in `FileType::allow()` and in
+  `FileSystem::blockExtensions()` alike.
+* `FileInfo::setExtension()` discards an extension longer than 32 bytes
+  (`FileInfo::MAX_EXTENSION_LENGTH`), and `setName()` strips `\x7F` along with bidi
+  overrides, zero-width marks, line and paragraph separators, and the BOM.
diff --git a/composer.json b/composer.json
index edc87f9..a5ca071 100644
--- a/composer.json
+++ b/composer.json
@@ -28,11 +28,14 @@
     "php": "^7.3 || ~8.0.0 || ~8.1.0 || ~8.2.0 || ~8.3.0 || ~8.4.0 || ~8.5.0",
     "ext-fileinfo": "*"
   },
+  "suggest": {
+    "ext-mbstring": "Truncates sanitized filenames on a character boundary and guarantees they are valid UTF-8"
+  },
   "require-dev": {
     "yoast/phpunit-polyfills": "^1.0",
     "php-parallel-lint/php-parallel-lint": "^1.3",
     "phpstan/phpstan": "^1.8",
-    "squizlabs/php_codesniffer": "*"
+    "squizlabs/php_codesniffer": "^4.0"
   },
   "autoload": {
     "psr-4": {
diff --git a/src/Upload/Exception.php b/src/Upload/Exception.php
index 4675384..3596b6a 100644
--- a/src/Upload/Exception.php
+++ b/src/Upload/Exception.php
@@ -5,7 +5,13 @@
 namespace GravityPdf\Upload;
 
 use RuntimeException;
+use Throwable;
 
+/**
+ * @internal Extends RuntimeException for backwards compatibility with v1/v2. A consumer
+ * catching `\RuntimeException` broadly cannot tell a validation failure from a PHP-level
+ * runtime error. Catch `\GravityPdf\Upload\Exception` to distinguish them.
+ */
 class Exception extends RuntimeException
 {
     /**
@@ -18,18 +24,24 @@ class Exception extends RuntimeException
      *
      * @param string $message The Exception message
      * @param FileInfoInterface|null $fileInfo The related file instance
+     * @param int $code The Exception code
+     * @param Throwable|null $previous The exception that caused this one, for chaining
      */
-    public function __construct($message, ?FileInfoInterface $fileInfo = null)
-    {
+    public function __construct(
+        string $message,
+        ?FileInfoInterface $fileInfo = null,
+        int $code = 0,
+        ?Throwable $previous = null
+    ) {
         $this->fileInfo = $fileInfo;
 
-        parent::__construct($message);
+        parent::__construct($message, $code, $previous);
     }
 
     /**
      * Get related file
      *
-     * @return FileInfoInterface
+     * @return FileInfoInterface|null Null when the failure is not about one particular file
      */
     public function getFileInfo(): ?FileInfoInterface
     {
diff --git a/src/Upload/File.php b/src/Upload/File.php
index b4ded7b..087fdeb 100644
--- a/src/Upload/File.php
+++ b/src/Upload/File.php
@@ -99,6 +99,24 @@ class File implements ArrayAccess, IteratorAggregate, Countable
      */
     protected $errors = [];
 
+    /**
+     * Has the caller accepted storing files without validating them?
+     * @var bool
+     */
+    protected $allowUnvalidated = false;
+
+    /**
+     * Errors recorded during construction, which `isValid()` must not discard
+     * @var string[]
+     */
+    protected $constructorErrors = [];
+
+    /**
+     * Destination paths written by the most recent `upload()` call
+     * @var string[]
+     */
+    protected $uploadedFiles = [];
+
     /**
      * Before validation callback
      * @var callable
@@ -146,11 +164,19 @@ public function __construct(string $key, StorageInterface $storage)
         // Collect file info
         if (is_array($_FILES[$key]['tmp_name']) === true) {
             foreach ($_FILES[$key]['tmp_name'] as $index => $tmpName) {
+                /* A field named `f[0][0]` nests `$_FILES` one level deeper than the two shapes
+                   this class knows, so the entry is an array where a path belongs. There is no
+                   single upload to represent, and casting it emits "Array to string conversion"
+                   and reports the file as "Array". Remote input, so it must not warn. */
+                if (is_string($tmpName) === false || is_string($_FILES[$key]['name'][$index] ?? null) === false) {
+                    $this->errors[] = 'An uploaded file was sent in a format that cannot be read';
+                    continue;
+                }
+
                 if ($_FILES[$key]['error'][$index] !== UPLOAD_ERR_OK) {
-                    $this->errors[] = sprintf(
-                        '%s: %s',
-                        $_FILES[$key]['name'][$index],
-                        static::$errorCodeMessages[$_FILES[$key]['error'][$index]] ?? 'Unknown Error'
+                    $this->errors[] = $this->uploadErrorMessage(
+                        (string)$_FILES[$key]['name'][$index],
+                        (int)$_FILES[$key]['error'][$index]
                     );
                     continue;
                 }
@@ -161,36 +187,74 @@ public function __construct(string $key, StorageInterface $storage)
                 );
             }
         } else {
+            /* A failed upload has no file behind it: `tmp_name` is '' for UPLOAD_ERR_NO_FILE.
+               Skip construction here, as the multi-file branch above does. */
             if ($_FILES[$key]['error'] !== UPLOAD_ERR_OK) {
-                $this->errors[] = sprintf(
-                    '%s: %s',
-                    $_FILES[$key]['name'],
-                    static::$errorCodeMessages[$_FILES[$key]['error']] ?? 'Unknown Error'
+                $this->errors[] = $this->uploadErrorMessage(
+                    (string)$_FILES[$key]['name'],
+                    (int)$_FILES[$key]['error']
+                );
+            } else {
+                $this->objects[] = FileInfo::createFromFactory(
+                    $_FILES[$key]['tmp_name'],
+                    $_FILES[$key]['name']
                 );
             }
-
-            $this->objects[] = FileInfo::createFromFactory(
-                $_FILES[$key]['tmp_name'],
-                $_FILES[$key]['name']
-            );
         }
 
+        $this->constructorErrors = $this->errors;
         $this->storage = $storage;
     }
 
+    /**
+     * Build an error string for a `$_FILES` entry that never became an upload
+     *
+     * Sanitizes the filename so every string in `$this->errors` has the same guarantee. This
+     * was the one path that emitted raw `$_FILES[…]['name']`, which the README encourages
+     * callers to render directly.
+     *
+     * Uses `FileInfo` rather than the factory: the guarantee is the library's own, so it must
+     * not depend on an implementation a caller installed with `FileInfo::setFactory()`.
+     *
+     * @param string $name The raw client-supplied filename
+     * @param int $errorCode One of the UPLOAD_ERR_* constants
+     * @return string
+     */
+    protected function uploadErrorMessage(string $name, int $errorCode): string
+    {
+        return sprintf(
+            '%s: %s',
+            (new FileInfo('', $name))->getNameWithExtension(),
+            static::$errorCodeMessages[$errorCode] ?? 'Unknown Error'
+        );
+    }
+
     /********************************************************************************
      * Callbacks
      *******************************************************************************/
 
     /**
-     * Convert human readable file size (e.g. "10K" or "3M") into bytes
+     * Convert human readable file size (e.g. "10K", "3M" or "5MB") into bytes
+     *
+     * Fractions are supported ("0.5M"), an optional trailing "B" is accepted, and an
+     * unrecognised unit is treated as bytes. Unparseable input raises instead of evaluating to
+     * zero, which would configure a `Size` bound of 0 bytes and reject every upload.
      *
      * @param string $input
      * @return int
+     * @throws InvalidArgumentException If the input cannot be parsed as a file size
      */
     public static function humanReadableToBytes(string $input): int
     {
-        $number = (int)$input;
+        if (preg_match('/^\s*(\d+(?:\.\d+)?)\s*([a-z])?b?\s*$/i', $input, $matches) !== 1) {
+            throw new InvalidArgumentException(
+                sprintf(
+                    'Could not parse "%s" as a file size. Expected a positive number, '
+                    . 'optionally followed by B, K, M or G.',
+                    $input
+                )
+            );
+        }
 
         $units = [
             'b' => 1,
@@ -199,13 +263,15 @@ public static function humanReadableToBytes(string $input): int
             'g' => 1073741824,
         ];
 
-        $unit = strtolower(substr($input, -1));
+        $unit = strtolower($matches[2] ?? '');
+        $number = (float)$matches[1] * ($units[$unit] ?? 1);
 
-        if (isset($units[$unit])) {
-            $number *= $units[$unit];
+        /* Returning a float here is a TypeError; a bound larger than PHP can count is PHP_INT_MAX */
+        if ($number >= (float)PHP_INT_MAX) {
+            return PHP_INT_MAX;
         }
 
-        return $number;
+        return (int)$number;
     }
 
     /**
@@ -302,6 +368,22 @@ public function getValidations(): array
         return $this->validations;
     }
 
+    /**
+     * Permit `upload()` to run with no validations configured
+     *
+     * `upload()` otherwise refuses, because an upload endpoint that validates nothing is
+     * usually an unfinished one rather than a decision. Call this where it really is a
+     * decision, so that the intent is visible to the next reader and greppable in an audit.
+     *
+     * @return File Self
+     */
+    public function allowUnvalidatedUploads(): File
+    {
+        $this->allowUnvalidated = true;
+
+        return $this;
+    }
+
     /**
      * Get file validation errors
      *
@@ -349,23 +431,54 @@ public function __call(string $name, array $arguments)
      * Upload file (delegated to storage object)
      *
      * @return bool
-     * @throws Exception|\Exception If validation fails
+     * @throws Exception|\Exception If validation fails, or if nothing has been configured to
+     *                              validate against
      */
     public function upload(): bool
     {
+        if (count($this->validations) === 0 && $this->allowUnvalidated === false) {
+            throw new Exception(
+                'No validations have been added. Add at least one (Validation\FileType and '
+                . 'Validation\Size cover most cases), or call allowUnvalidatedUploads() to '
+                . 'store whatever is submitted.'
+            );
+        }
+
         if ($this->isValid() === false) {
             throw new Exception('File validation failed');
         }
 
+        /* Every validation passes vacuously when there is nothing to run them against, so
+           without this the method reports success having stored nothing. It sits after
+           isValid(), so a transfer that failed still reports through getErrors(). */
+        if (count($this->objects) === 0) {
+            throw new Exception('There are no files to upload');
+        }
+
+        $this->uploadedFiles = [];
+
         foreach ($this->objects as $fileInfo) {
             $this->applyCallback('beforeUploadCallback', $fileInfo);
-            $this->storage->upload($fileInfo);
+            $this->uploadedFiles[] = $this->storage->upload($fileInfo);
             $this->applyCallback('afterUploadCallback', $fileInfo);
         }
 
         return true;
     }
 
+    /**
+     * Destination paths written by the most recent `upload()` call
+     *
+     * A multi-file upload is not atomic, and `getErrors()` stays empty when a storage failure
+     * aborts it, so this is how a caller finds out what is already on disk.
+     *
+     * @return string[]
+     */
+    public function getUploadedFiles(): array
+    {
+        return $this->uploadedFiles;
+    }
+
     /**
      * Is this collection valid and without errors?
      *
@@ -374,6 +487,10 @@ public function upload(): bool
      */
     public function isValid(): bool
     {
+        /* Reset rather than append: upload() calls isValid() again, so the
+           `if (!$file->isValid()) {…} $file->upload();` pattern would double every error */
+        $this->errors = $this->constructorErrors;
+
         foreach ($this->objects as $fileInfo) {
             // Before validation callback
             $this->applyCallback('beforeValidationCallback', $fileInfo);
@@ -398,6 +515,16 @@ public function isValid(): bool
                         $fileInfo->getNameWithExtension(),
                         $e->getMessage()
                     );
+                } catch (\Throwable $e) {
+                    /* ValidationInterface is an extension point, so absorb rather than let one
+                       validator abort the batch and bypass error accumulation. The message is
+                       dropped because PHP runtime messages can contain absolute paths, and
+                       getErrors() is documented as something callers show to end users */
+                    $this->errors[] = sprintf(
+                        '%s: Validation could not be completed (%s)',
+                        $fileInfo->getNameWithExtension(),
+                        get_class($e)
+                    );
                 }
             }
 
@@ -461,9 +588,17 @@ public function offsetGet($offset)
      * @param mixed $offset
      * @param FileInfoInterface $value
      * @return void
+     * @throws InvalidArgumentException If the value is not a FileInfoInterface
      */
     public function offsetSet($offset, $value): void
     {
+        /* The type in the docblock is not enforced at runtime; anything else faults later, inside isValid() */
+        if (!$value instanceof FileInfoInterface) {
+            throw new InvalidArgumentException(
+                'Value must be an instance of ' . FileInfoInterface::class
+            );
+        }
+
         $this->objects[$offset] = $value;
     }
 
diff --git a/src/Upload/FileInfo.php b/src/Upload/FileInfo.php
index dadc7e3..424e92d 100644
--- a/src/Upload/FileInfo.php
+++ b/src/Upload/FileInfo.php
@@ -47,6 +47,14 @@
  */
 class FileInfo extends SplFileInfo implements FileInfoInterface
 {
+    /**
+     * Longest extension `setExtension()` will keep, in bytes
+     *
+     * Comfortably past every extension in real use, and short enough that it cannot crowd the
+     * name out of the 255 byte limit a stored file has to stay under.
+     */
+    public const MAX_EXTENSION_LENGTH = 32;
+
     /**
      * Factory method that returns new instance of \FileInfoInterface
      * @var callable|null
@@ -90,6 +98,18 @@ public static function setFactory(callable $callable): void
         static::$factory = $callable;
     }
 
+    /**
+     * Clear any factory previously installed with `setFactory()`
+     *
+     * The factory is process-wide state. Long-lived processes (and test suites) need a
+     * supported way to put it back, otherwise every subsequent `File` in the process is
+     * built by whatever code called `setFactory()` last.
+     */
+    public static function resetFactory(): void
+    {
+        static::$factory = null;
+    }
+
     public static function createFromFactory(string $tmpName, ?string $name = null): FileInfoInterface
     {
         if (is_callable(static::$factory)) {
@@ -140,12 +160,25 @@ public function setName(string $name): FileInfo
 
     protected function sanitizeName(string $name): string
     {
+        /* Delete the characters that reorder, break or hide the text around them: they carry no
+           visual content of their own, so `resume\u{202E}gpj.exe` renders as `resumeexe.jpg` in
+           an admin listing, an email or a log line while the stored file is still the
+           executable. U+2028 and U+2029 are in the range for the reason `\x00-\x1F` is below:
+           they end a line for readers that honour them. Matched as UTF-8 bytes rather than with
+           the `u` modifier, because the name is not known to be valid UTF-8 until
+           forceValidUtf8() below. */
+        $name = (string) preg_replace(
+            '/\xE2\x80[\x8B-\x8F\xA8-\xAE]|\xE2\x81[\xA6-\xA9]|\xEF\xBB\xBF/',
+            '',
+            $name
+        );
+
         $name = str_replace(['%20', '+', '.'], '-', $name); //replaces encoded space, +, or .
         $name = (string) preg_replace('/[\r\n\t-]+/', '-', $name); //replace tab or new line characters
         $name = (string) preg_replace(
             '~
         [%<>:"/\\\|?*]|          # @internal 1.
-        [\x00-\x1F]|            # @internal 2.
+        [\x00-\x1F\x7F]|        # @internal 2.
         [#\[\]@!$&\'()+,;=]|    # @internal 3.
         [{}^\~`]                # @internal 4.
         ~x',
@@ -185,18 +218,56 @@ protected function sanitizeName(string $name): string
 
         /* Use multibyte aware functions, if the server supports it */
         if (function_exists('mb_strcut') && function_exists('mb_detect_encoding')) {
-            $name = mb_strcut($name, 0, $maxLength, (string)mb_detect_encoding($name));
+            /* Explicit detect order, not the ambient `mb_detect_order()`: an application that
+               drops ASCII from that list turns every high-byte filename into a ValueError */
+            $encoding = mb_detect_encoding($name, ['ASCII', 'UTF-8']);
+            $name = mb_strcut($name, 0, $maxLength, $encoding !== false ? $encoding : 'UTF-8');
         } else {
             $name = substr($name, 0, $maxLength);
         }
 
-        if (empty($name)) {
+        /* Byte-wise sanitizing and truncation can split a multibyte sequence */
+        if (
+            function_exists('mb_check_encoding')
+            && function_exists('mb_convert_encoding')
+            && function_exists('mb_substitute_character')
+        ) {
+            $name = $this->forceValidUtf8($name);
+        }
+
+        /* Not empty(): a file legitimately called `0` is not an unnamed one */
+        if ($name === '') {
             $name = 'unnamed-file';
         }
 
         return $name;
     }
 
+    /**
+     * Drop any byte sequence that is not valid UTF-8
+     *
+     * Removing a reserved character that sits inside a multibyte sequence orphans the
+     * remaining bytes, and an invalid-UTF-8 filename makes `json_encode()` return `false`
+     * and breaks inserts into `utf8mb4` columns.
+     *
+     * @param string $name
+     * @return string
+     */
+    protected function forceValidUtf8(string $name): string
+    {
+        if (mb_check_encoding($name, 'UTF-8')) {
+            return $name;
+        }
+
+        /* 'none' drops the offending bytes instead of replacing them with a substitute char */
+        $substitute = mb_substitute_character();
+        mb_substitute_character('none');
+        $name = (string)mb_convert_encoding($name, 'UTF-8', 'UTF-8');
+        mb_substitute_character($substitute);
+
+        return $name;
+    }
+
     /**
      * Get file extension (without dot prefix)
      *
@@ -210,18 +281,39 @@ public function getExtension(): string
     /**
      * Set file extension (without dot prefix)
      *
-     * Sanitize the extension (lowercase, alphanumeric)
+     * The extension must already be lowercase-alphanumeric once trimmed. Anything else is
+     * discarded, leaving the file with no extension at all.
+     *
+     * @internal This used to delete the disallowed characters instead. Deletion normalises, so
+     * it could produce an extension the client never sent: `avatar.p-h-p` became `avatar.php`,
+     * defeating both a caller's own deny-list on the raw filename and any web server configured
+     * to execute `.php`. A file stored with no extension is not executed, so discarding is the
+     * safe outcome.
      *
      * @param string $extension
      * @return FileInfo Self
      */
     public function setExtension(string $extension): FileInfo
     {
-        $extension = strtolower($extension);
-        $extension = trim((string)preg_replace('/[^a-z0-9]/', '', $extension));
+        $extension = strtolower(trim($extension));
+
+        /* `D`, so that `$` cannot be satisfied by a trailing newline */
+        if (preg_match('/^[a-z0-9]*$/D', $extension) !== 1) {
+            $extension = '';
+        }
 
-        /* Remove Windows reserved extensions */
-        $extension = str_replace($this->getReservedWindowsNames(), '', $extension);
+        /* An extension is part of the 255 byte budget setName() divides up, and an alphanumeric
+           one has nothing else bounding its length. Left uncapped, `photo.` followed by 300
+           letters spends the whole budget on the extension and the name is stored past the
+           limit. Discarded rather than cut down, for the reason above. */
+        if (strlen($extension) > self::MAX_EXTENSION_LENGTH) {
+            $extension = '';
+        }
+
+        /* Discard Windows reserved extensions; the rule is about the whole value, not a substring */
+        if (in_array($extension, $this->getReservedWindowsNames(), true)) {
+            $extension = '';
+        }
 
         $this->extension = $extension;
 
@@ -294,7 +386,7 @@ public function setNameWithExtension(string $name): FileInfo
      */
     public function getMimetype(): string
     {
-        if (empty($this->mimetype)) {
+        if (empty($this->mimetype) && $this->isReadableFile()) {
             $finfo = new finfo(FILEINFO_MIME);
             $mimetype = $finfo->file($this->getPathname());
             $mimetypeParts = (array)preg_split('/\s*[;,]\s*/', (string)$mimetype);
@@ -309,24 +401,46 @@ public function getMimetype(): string
     }
 
     /**
-     * Get md5
+     * Get a specified hash
      *
-     * @return string
+     * The default is SHA-256. MD5 is still reachable as `getHash('md5')`, but chosen-prefix
+     * collisions against it are practical, so it cannot carry an integrity or identity
+     * decision about content someone else supplied.
+     *
+     * @param string $algorithm Any algorithm supported by `hash_algos()`
+     * @return string Empty string if the file cannot be read
+     * @throws Exception If the algorithm is not supported by this PHP build
      */
-    public function getMd5(): string
+    public function getHash(string $algorithm = 'sha256'): string
     {
-        return (string)md5_file($this->getPathname());
+        if (!in_array(strtolower($algorithm), hash_algos(), true)) {
+            throw new Exception(sprintf('Unsupported hashing algorithm: %s', $algorithm), $this);
+        }
+
+        if (!$this->isReadableFile()) {
+            return '';
+        }
+
+        return (string)hash_file($algorithm, $this->getPathname());
     }
 
     /**
-     * Get a specified hash
+     * Get file size in bytes
      *
-     * @param string $algorithm
-     * @return string
+     * `SplFileInfo::getSize()` throws a `RuntimeException` when the file cannot be stat'd.
+     * `FileInfoInterface` documents `int|false`, so an unreadable file reports `false`
+     * rather than aborting a validation run.
+     *
+     * @return int|false
      */
-    public function getHash(string $algorithm = 'md5'): string
+    #[\ReturnTypeWillChange]
+    public function getSize()
     {
-        return hash_file($algorithm, $this->getPathname());
+        if (!$this->isReadableFile()) {
+            return false;
+        }
+
+        return parent::getSize();
     }
 
     /**
@@ -336,7 +450,7 @@ public function getHash(string $algorithm = 'md5'): string
      */
     public function getDimensions(): array
     {
-        $imageSize = getimagesize($this->getPathname());
+        $imageSize = $this->isReadableFile() ? getimagesize($this->getPathname()) : false;
         if (!$imageSize) {
             $imageSize = [0,0];
         }
@@ -359,4 +473,20 @@ public function isUploadedFile(): bool
     {
         return is_uploaded_file($this->getPathname());
     }
+
+    /**
+     * Is there actually a readable file behind this pathname?
+     *
+     * A `FileInfo` can legitimately wrap a path that no longer resolves, so the metadata
+     * accessors check this first and degrade instead of raising `ValueError`/`RuntimeException`
+     * from the underlying extension.
+     *
+     * @return bool
+     */
+    protected function isReadableFile(): bool
+    {
+        $pathname = $this->getPathname();
+
+        return $pathname !== '' && is_file($pathname) && is_readable($pathname);
+    }
 }
diff --git a/src/Upload/FileInfoInterface.php b/src/Upload/FileInfoInterface.php
index cb0cbe7..d06c5cb 100644
--- a/src/Upload/FileInfoInterface.php
+++ b/src/Upload/FileInfoInterface.php
@@ -75,7 +75,7 @@ public function getMimetype(): string;
      */
     public function getSize();
 
-    public function getMd5(): string;
+    public function getHash(string $algorithm = 'sha256'): string;
 
     /**
      * @return array<string, int|float>
diff --git a/src/Upload/Storage/FileSystem.php b/src/Upload/Storage/FileSystem.php
index ebc6b5a..64c9bfe 100644
--- a/src/Upload/Storage/FileSystem.php
+++ b/src/Upload/Storage/FileSystem.php
@@ -44,12 +44,63 @@
  *
  * This class uploads files to a designated directory on the filesystem.
  *
+ * Three protections are on by default and each has to be turned off explicitly: existing files
+ * are never overwritten (`$overwrite`), the extensions in `defaultBlockedExtensions()` are
+ * never written (`blockExtensions([])`), and stored files get `DEFAULT_MODE` rather than
+ * whatever the process umask allows (`setMode(null)`).
+ *
  * @author  Josh Lockhart <info@joshlockhart.com>
  * @since   1.0.0
  * @package Upload
  */
 class FileSystem implements StorageInterface
 {
+    /**
+     * Extensions a web server is commonly configured to execute or read as configuration
+     *
+     * Also covers client-side binary formats. The list is not exhaustive; an allow-list via
+     * `\GravityPdf\Upload\Validation\FileType` is the primary control.
+     *
+     * @var string[]
+     */
+    public const EXECUTABLE_EXTENSIONS = [
+        'php', 'php2', 'php3', 'php4', 'php5', 'php6', 'php7', 'php8', 'phps', 'phtml', 'phtm',
+        'phar', 'pht', 'inc',
+        'shtml', 'shtm', 'stm',
+        'cgi', 'fcgi', 'pl', 'py', 'rb', 'sh', 'bash', 'ps1',
+        'jsp', 'jspx', 'jspf', 'jsw', 'jsv', 'jshtml', 'jar', 'war',
+        'asp', 'aspx', 'asa', 'asax', 'ascx', 'ashx', 'asmx', 'cer', 'cshtml', 'vbhtml',
+        'exe', 'dll', 'com', 'bat', 'cmd', 'msi', 'scr', 'vbs', 'ws', 'wsf', 'hta',
+        'htaccess', 'htpasswd', 'ini', 'conf', 'config',
+    ];
+
+    /**
+     * Extensions a browser renders as markup or runs as script
+     *
+     * These are not executed by the server, so the risk is stored XSS: a request for the
+     * uploaded file returns markup that runs in the origin serving it, with access to that
+     * origin's cookies and storage. SVG counts, because it carries `<script>` and event
+     * handler attributes.
+     *
+     * @var string[]
+     */
+    public const MARKUP_EXTENSIONS = [
+        'html', 'htm', 'xhtml', 'xht', 'xhtm',
+        'svg', 'svgz',
+        'xml', 'xsl', 'xslt',
+        'js', 'mjs',
+        'swf',
+        'mht', 'mhtml',
+    ];
+
+    /**
+     * Permissions applied to a stored file unless `setMode()` says otherwise
+     *
+     * Owner read/write and group read. `move_uploaded_file()` otherwise leaves the mode to the
+     * process umask, which on a typical `022` lands the file world-readable.
+     */
+    public const DEFAULT_MODE = 0640;
+
     /**
      * Path to upload destination directory (with trailing slash)
      * @var string
@@ -62,6 +113,18 @@ class FileSystem implements StorageInterface
      */
     protected $overwrite;
 
+    /**
+     * Extensions that may never be written (lowercase, without leading dot)
+     * @var string[]
+     */
+    protected $blockedExtensions = [];
+
+    /**
+     * Permissions to apply to the stored file, or null to leave the process umask in charge
+     * @var int|null
+     */
+    protected $mode;
+
     /**
      * Constructor
      *
@@ -82,28 +145,278 @@ public function __construct(string $directory, bool $overwrite = false)
 
         $this->directory = rtrim($directory, '/') . DIRECTORY_SEPARATOR;
         $this->overwrite = $overwrite;
+
+        $this->blockExtensions();
+        $this->setMode(self::DEFAULT_MODE);
+    }
+
+    /**
+     * The extensions refused unless `blockExtensions()` is given a list of its own
+     *
+     * A method rather than a constant because constant expressions cannot call `array_merge()`
+     * on PHP 7.3.
+     *
+     * @return string[]
+     */
+    public static function defaultBlockedExtensions(): array
+    {
+        return array_merge(self::EXECUTABLE_EXTENSIONS, self::MARKUP_EXTENSIONS);
+    }
+
+    /**
+     * Refuse to store files with any of these extensions
+     *
+     * On by default. This is a last line of defence that applies no matter which validations
+     * the caller configured, and it runs against the *sanitized* extension that is actually
+     * about to be written to disk.
+     *
+     * A leading dot is accepted and removed. The values compared against it never carry one, so
+     * taking `['.php']` at face value would quietly block nothing while the caller believes
+     * they tightened the list.
+     *
+     * @param string[]|null $extensions Extensions with or without leading dots, or null for the
+     *                                  default set
+     * @return FileSystem Self
+     *
+     * @example $storage->blockExtensions(['php', 'phtml']);
+     * @example $storage->blockExtensions(array_merge(FileSystem::defaultBlockedExtensions(), ['csv']));
+     * @example $storage->blockExtensions([]); // store anything, including .php
+     */
+    public function blockExtensions(?array $extensions = null): FileSystem
+    {
+        if ($extensions === null) {
+            $extensions = self::defaultBlockedExtensions();
+        }
+
+        $this->blockedExtensions = array_map(
+            static function (string $extension): string {
+                return ltrim(strtolower(trim($extension)), '.');
+            },
+            $extensions
+        );
+
+        return $this;
+    }
+
+    /**
+     * Set the permissions applied to each stored file
+     *
+     * Defaults to `self::DEFAULT_MODE`. Pass `null` to leave the mode to the process umask,
+     * which is what `move_uploaded_file()` does on its own.
+     *
+     * @param int|null $mode
+     * @return FileSystem Self
+     */
+    public function setMode(?int $mode): FileSystem
+    {
+        $this->mode = $mode;
+
+        return $this;
     }
 
     /**
      * Upload
      *
+     * The file is written to an unpredictable name inside the destination directory and then
+     * `rename()`d onto the destination. `rename()` replaces the directory entry rather than
+     * following it, so the bytes never travel through a symbolic link someone planted at the
+     * destination, and the file only appears under its final name once it is complete and
+     * already carries the configured mode.
+     *
      * @param FileInfoInterface $fileInfo
      * @return string
+     * @throws Exception If the file cannot be stored safely
      */
     public function upload(FileInfoInterface $fileInfo): string
     {
-        $destinationFile = $this->directory . $fileInfo->getNameWithExtension();
-        if ($this->overwrite === false && is_file($destinationFile) === true) {
-            throw new Exception('File already exists', $fileInfo);
+        $destinationFile = $this->directory . $this->resolveFilename($fileInfo);
+
+        /* `is_file()` follows symlinks, so it cannot see a dangling one. This reports the
+           ordinary case with a message that says what is wrong; it is not what makes the write
+           safe, because anything checked here can change before the write happens. */
+        if (is_link($destinationFile)) {
+            throw new Exception('Destination is a symbolic link', $fileInfo);
+        }
+
+        $stagingFile = $this->stagingPath($fileInfo);
+
+        if ($this->overwrite === false) {
+            $this->reserveDestination($destinationFile, $fileInfo);
         }
 
-        if ($this->moveUploadedFile($fileInfo->getPathname(), $destinationFile) === false) {
+        if ($this->moveUploadedFile($fileInfo->getPathname(), $stagingFile) === false) {
+            $this->discard($stagingFile, $destinationFile);
+
+            throw new Exception('File could not be moved to final destination.', $fileInfo);
+        }
+
+        /* On the staged file, so there is no moment where the finished upload is readable
+           under its final name at the umask's mode instead of this one */
+        if ($this->mode !== null && @chmod($stagingFile, $this->mode) === false) {
+            $this->discard($stagingFile, $destinationFile);
+
+            throw new Exception('Permissions could not be applied to the stored file', $fileInfo);
+        }
+
+        if (@rename($stagingFile, $destinationFile) === false) {
+            $this->discard($stagingFile, $destinationFile);
+
             throw new Exception('File could not be moved to final destination.', $fileInfo);
         }
 
         return $destinationFile;
     }
 
+    /**
+     * A name in the destination directory that nobody else can predict
+     *
+     * `move_uploaded_file()` renames when the temporary directory and the upload directory share
+     * a file system and falls back to a stream copy when they do not, and that copy follows a
+     * symlink at the destination. Sending it to a name an attacker cannot guess is what removes
+     * the race; the `rename()` that follows never resolves a link.
+     *
+     * @param FileInfoInterface $fileInfo
+     * @return string
+     * @throws Exception If the platform cannot produce random bytes
+     */
+    protected function stagingPath(FileInfoInterface $fileInfo): string
+    {
+        try {
+            $unique = bin2hex(random_bytes(16));
+        } catch (\Throwable $e) {
+            throw new Exception('Could not generate a temporary file name', $fileInfo, 0, $e);
+        }
+
+        return $this->directory . 'upload-' . $unique . '.part';
+    }
+
+    /**
+     * Claim the destination name for this upload before anything is written
+     *
+     * @param string $destinationFile
+     * @param FileInfoInterface $fileInfo
+     * @return void
+     * @throws Exception If the name is taken, or cannot be claimed safely
+     */
+    protected function reserveDestination(string $destinationFile, FileInfoInterface $fileInfo): void
+    {
+        /* O_EXCL combines the existence check and the create into one operation. Checking
+           is_file() first lets two concurrent requests both pass it. */
+        $handle = @fopen($destinationFile, 'xb');
+
+        if (!is_resource($handle)) {
+            /* `x` also fails when the directory has been removed or its permissions changed
+               since the constructor checked it. Calling that a collision sends the caller down
+               a rename-and-retry path that cannot succeed. */
+            if (file_exists($destinationFile) || is_link($destinationFile)) {
+                throw new Exception('File already exists', $fileInfo);
+            }
+
+            throw new Exception('Destination file could not be created', $fileInfo);
+        }
+
+        $opened = fstat($handle);
+        fclose($handle);
+
+        /* PHP resolves the path through its own stream layer before the exclusive create, so
+           `x` follows a symlink where the underlying O_EXCL refuses one. What was just created
+           is the destination only if the directory entry is that same file; a symlink has an
+           inode of its own, so a mismatch means the name was a link. */
+        $entry = @lstat($destinationFile);
+
+        if (
+            $opened === false
+            || $entry === false
+            || $opened['dev'] !== $entry['dev']
+            || $opened['ino'] !== $entry['ino']
+        ) {
+            throw new Exception('Destination is a symbolic link', $fileInfo);
+        }
+    }
+
+    /**
+     * Remove what a failed upload left behind
+     *
+     * The destination is only this upload's to remove when `overwrite` is off, where it holds
+     * the placeholder `reserveDestination()` created. With overwriting on, whatever is there
+     * belongs to someone else and the upload has not touched it.
+     *
+     * @param string $stagingFile
+     * @param string $destinationFile
+     * @return void
+     */
+    protected function discard(string $stagingFile, string $destinationFile): void
+    {
+        @unlink($stagingFile);
+
+        if ($this->overwrite === false) {
+            @unlink($destinationFile);
+        }
+    }
+
+    /**
+     * Reduce a `FileInfoInterface` name to a filename that stays in the upload directory
+     *
+     * `FileInfoInterface` is a public extension point, so the name arriving here is only as
+     * trustworthy as the implementation the caller (or `FileInfo::setFactory()`) installed.
+     * This class should not assume sanitizing happened elsewhere.
+     *
+     * @param FileInfoInterface $fileInfo
+     * @return string
+     * @throws Exception If the name cannot be reduced to a safe filename
+     */
+    protected function resolveFilename(FileInfoInterface $fileInfo): string
+    {
+        $filename = basename(str_replace('\\', '/', $fileInfo->getNameWithExtension()));
+
+        /* Windows drops trailing dots and spaces when it resolves a name, so `evil.php.` and
+           `evil.php ` both open `evil.php`. Take them off here, so that what is checked below
+           is the name the file system will actually answer to. */
+        $filename = rtrim($filename, " .");
+
+        /* basename() has removed every separator. What remains to reject are the values that
+           are not usable filenames: the two directory entries, a name hidden from the shell
+           globbing and directory listings a cleanup script relies on, and the control
+           characters that let a name forge a line in a log or a terminal. */
+        if ($filename === '' || strpos($filename, '.') === 0 || preg_match('/[\x00-\x1F\x7F]/', $filename) === 1) {
+            throw new Exception('Invalid destination file name', $fileInfo);
+        }
+
+        $this->refuseBlockedExtensions($filename, $fileInfo);
+
+        return $filename;
+    }
+
+    /**
+     * Refuse a name carrying a blocked extension anywhere in it
+     *
+     * Every dot-separated component is checked, not just the last one, because a server does not
+     * necessarily read the name the way `pathinfo()` does: Apache's `AddHandler`/`AddType` match
+     * any dot component, so `evil.php.jpg` is served as PHP on a configuration that maps `.php`.
+     *
+     * @param string $filename A name already reduced to a basename with no trailing dots or spaces
+     * @param FileInfoInterface $fileInfo
+     * @return void
+     * @throws Exception If any component is on the deny-list
+     */
+    protected function refuseBlockedExtensions(string $filename, FileInfoInterface $fileInfo): void
+    {
+        /* Drop the first component: it is the name itself, and a file called `php` is not a
+           file that runs as PHP. */
+        $components = array_slice(explode('.', strtolower($filename)), 1);
+
+        foreach ($components as $component) {
+            $component = trim($component);
+
+            if (in_array($component, $this->blockedExtensions, true)) {
+                throw new Exception(
+                    sprintf('Files with the extension "%s" cannot be stored', $component),
+                    $fileInfo
+                );
+            }
+        }
+    }
+
     /**
      * Get directory (without trailing slash)
      *
diff --git a/src/Upload/Validation/Extension.php b/src/Upload/Validation/Extension.php
index 290a4ad..9f306bb 100644
--- a/src/Upload/Validation/Extension.php
+++ b/src/Upload/Validation/Extension.php
@@ -34,7 +34,6 @@
 
 namespace GravityPdf\Upload\Validation;
 
-use RuntimeException;
 use GravityPdf\Upload\Exception;
 use GravityPdf\Upload\FileInfoInterface;
 use GravityPdf\Upload\ValidationInterface;
@@ -45,8 +44,9 @@
  * This class validates an uploads file extension. It takes file extension with out dot
  * or array of extensions. For example: 'png' or array('jpg', 'png', 'gif').
  *
- * @internal WARNING! Validation only by file extension not very secure.
- * Always use in conjunction with GravityPdf\Upload\Validation\Mimetype
+ * @deprecated 4.0.0 Use GravityPdf\Upload\Validation\FileType, which constrains the contents
+ * as well and requires the two to agree. Checking the extension on its own says nothing about
+ * what the file holds. This class still works and has no runtime deprecation notice.
  *
  * @author  Alex Kucherenko <kucherenko.email@gmail.com>
  * @package Upload
@@ -79,7 +79,7 @@ public function __construct($allowedExtensions)
      * Validate
      *
      * @param FileInfoInterface $fileInfo
-     * @throws RuntimeException         If validation fails
+     * @throws Exception If validation fails
      */
     public function validate(FileInfoInterface $fileInfo): void
     {
diff --git a/src/Upload/Validation/FileType.php b/src/Upload/Validation/FileType.php
new file mode 100644
index 0000000..3c4d29c
--- /dev/null
+++ b/src/Upload/Validation/FileType.php
@@ -0,0 +1,178 @@
+<?php
+
+/**
+ * Upload
+ *
+ * @author      Josh Lockhart <info@joshlockhart.com>
+ * @copyright   2012 Josh Lockhart
+ * @link        http://www.joshlockhart.com
+ * @version     2.0.0
+ *
+ * MIT LICENSE
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining
+ * a copy of this software and associated documentation files (the
+ * "Software"), to deal in the Software without restriction, including
+ * without limitation the rights to use, copy, modify, merge, publish,
+ * distribute, sublicense, and/or sell copies of the Software, and to
+ * permit persons to whom the Software is furnished to do so, subject to
+ * the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be
+ * included in all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+ * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+ * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+ * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+ * LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+ * OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+ * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+
+declare(strict_types=1);
+
+namespace GravityPdf\Upload\Validation;
+
+use GravityPdf\Upload\Exception;
+use GravityPdf\Upload\FileInfoInterface;
+use GravityPdf\Upload\ValidationInterface;
+use InvalidArgumentException;
+
+/**
+ * Validate File Extension Against Media Type
+ *
+ * Checks the extension and the sniffed media type together, and requires them to agree.
+ *
+ * `Extension` and `Mimetype` used side by side check two independent allow-lists, so a file
+ * satisfies both without the two answers describing the same format: given
+ * `Extension(['png', 'gif'])` and `Mimetype(['image/png', 'image/gif'])`, content sniffed as
+ * `image/gif` stored as `avatar.png` passes. This class pairs them instead, so the bytes on
+ * disk have to match what the stored extension claims.
+ *
+ * Describe one format per call. Both sides accept a list, so `['jpg', 'jpeg']` can share
+ * `image/jpeg`, but two formats in a single call pair every extension with every media type
+ * and hand back the looseness this class exists to remove.
+ *
+ * @example new FileType(['jpg', 'jpeg'], 'image/jpeg')
+ * @example (new FileType('png', 'image/png'))->allow(['tif', 'tiff'], 'image/tiff')
+ *
+ * @author  Gravity PDF <support@gravitypdf.com>
+ * @package Upload
+ */
+class FileType implements ValidationInterface
+{
+    /**
+     * Allowed extensions, each mapped to the media types it may hold
+     * @var array<string, string[]>
+     */
+    protected $allowedTypes = [];
+
+    /**
+     * Constructor
+     *
+     * @param string|string[] $extensions Allowed file extensions without leading dots
+     * @param string|string[] $mimetypes  Media types the extensions above may hold
+     */
+    public function __construct($extensions, $mimetypes)
+    {
+        $this->allow($extensions, $mimetypes);
+    }
+
+    /**
+     * Pair another set of extensions with the media types they may hold
+     *
+     * Extensions already registered gain the media types given here rather than replacing them.
+     *
+     * @param string|string[] $extensions Allowed file extensions without leading dots
+     * @param string|string[] $mimetypes  Media types the extensions above may hold
+     *
+     * @throws InvalidArgumentException If either side is empty, which would silently reject
+     *                                  every upload
+     */
+    public function allow($extensions, $mimetypes): FileType
+    {
+        $extensions = $this->normalize($extensions, true);
+        $mimetypes = $this->normalize($mimetypes, false);
+
+        if (count($extensions) === 0 || count($mimetypes) === 0) {
+            throw new InvalidArgumentException('Expected at least one extension and one mimetype');
+        }
+
+        foreach ($extensions as $extension) {
+            $existing = $this->allowedTypes[$extension] ?? [];
+
+            $this->allowedTypes[$extension] = array_values(array_unique(array_merge($existing, $mimetypes)));
+        }
+
+        return $this;
+    }
+
+    /**
+     * Reduce one side of an `allow()` call to the values it actually configures
+     *
+     * Empty strings are dropped rather than registered. `(array)''` is a list of one, so it
+     * would otherwise slip past the guard that `[]` trips and pair the extension with the empty
+     * media type `getMimetype()` returns for a file it cannot read — an unreadable `avatar.png`
+     * passing a check written to require a real PNG.
+     *
+     * @param string|string[] $values
+     * @param bool $isExtension Extensions are compared against `getExtension()`, which never
+     *                          carries a leading dot, so accept and remove one
+     * @return string[]
+     */
+    protected function normalize($values, bool $isExtension): array
+    {
+        $normalized = [];
+
+        foreach ((array)$values as $value) {
+            $value = strtolower(trim((string)$value));
+
+            if ($isExtension) {
+                $value = ltrim($value, '.');
+            }
+
+            if ($value !== '') {
+                $normalized[] = $value;
+            }
+        }
+
+        return $normalized;
+    }
+
+    /**
+     * Validate
+     *
+     * @param FileInfoInterface $fileInfo
+     * @throws Exception If validation fails
+     */
+    public function validate(FileInfoInterface $fileInfo): void
+    {
+        $extension = strtolower(trim($fileInfo->getExtension()));
+
+        if (!isset($this->allowedTypes[$extension])) {
+            throw new Exception(
+                sprintf(
+                    'Invalid file extension. Must be one of: %s',
+                    implode(', ', array_keys($this->allowedTypes))
+                ),
+                $fileInfo
+            );
+        }
+
+        /* Lowercased to match the configured list, which `normalize()` has already folded. The
+           shipped FileInfo lowercases in getMimetype(), a custom FileInfoInterface need not. */
+        $mimetype = strtolower(trim($fileInfo->getMimetype()));
+
+        if (!in_array($mimetype, $this->allowedTypes[$extension], true)) {
+            throw new Exception(
+                sprintf(
+                    'File contents do not match the "%s" extension. Must be one of: %s',
+                    $extension,
+                    implode(', ', $this->allowedTypes[$extension])
+                ),
+                $fileInfo
+            );
+        }
+    }
+}
diff --git a/src/Upload/Validation/Mimetype.php b/src/Upload/Validation/Mimetype.php
index 83498e8..97b2644 100644
--- a/src/Upload/Validation/Mimetype.php
+++ b/src/Upload/Validation/Mimetype.php
@@ -34,7 +34,6 @@
 
 namespace GravityPdf\Upload\Validation;
 
-use RuntimeException;
 use GravityPdf\Upload\Exception;
 use GravityPdf\Upload\FileInfoInterface;
 use GravityPdf\Upload\ValidationInterface;
@@ -44,6 +43,11 @@
  *
  * This class validates an upload's media type (e.g. "image/png").
  *
+ * @deprecated 4.0.0 Use GravityPdf\Upload\Validation\FileType, which constrains the stored
+ * extension as well and requires the two to agree. `finfo` inspects the leading bytes, which a
+ * polyglot satisfies trivially: a file that begins "GIF89a" and continues with PHP is reported
+ * as image/gif. This class still works and has no runtime deprecation notice.
+ *
  * @author  Josh Lockhart <info@joshlockhart.com>
  * @since   1.0.0
  * @package Upload
@@ -73,7 +77,7 @@ public function __construct($mimetypes)
      * Validate
      *
      * @param FileInfoInterface $fileInfo
-     * @throws RuntimeException          If validation fails
+     * @throws Exception If validation fails
      */
     public function validate(FileInfoInterface $fileInfo): void
     {
diff --git a/src/Upload/Validation/Size.php b/src/Upload/Validation/Size.php
index 08a7a55..87eaaa1 100644
--- a/src/Upload/Validation/Size.php
+++ b/src/Upload/Validation/Size.php
@@ -34,7 +34,6 @@
 
 namespace GravityPdf\Upload\Validation;
 
-use RuntimeException;
 use GravityPdf\Upload\Exception;
 use GravityPdf\Upload\File;
 use GravityPdf\Upload\FileInfoInterface;
@@ -90,12 +89,18 @@ public function __construct($maxSize, $minSize = 0)
      * Validate
      *
      * @param FileInfoInterface $fileInfo
-     * @throws RuntimeException          If validation fails
+     * @throws Exception If validation fails
      */
     public function validate(FileInfoInterface $fileInfo): void
     {
         $fileSize = $fileInfo->getSize();
 
+        /* On PHP 8 SplFileInfo::getSize() throws instead of returning false, so a file that no
+           longer stats would otherwise abort the whole batch rather than record an error */
+        if ($fileSize === false) {
+            throw new Exception('File size could not be determined', $fileInfo);
+        }
+
         if ($fileSize < $this->minSize) {
             throw new Exception(
                 sprintf('File size is too small. Must be greater than or equal to: %s', $this->minSize),
diff --git a/tests/Upload/ExceptionTest.php b/tests/Upload/ExceptionTest.php
new file mode 100644
index 0000000..ba8b2ec
--- /dev/null
+++ b/tests/Upload/ExceptionTest.php
@@ -0,0 +1,40 @@
+<?php
+
+namespace GravityPdf\Upload;
+
+use RuntimeException;
+use Yoast\PHPUnitPolyfills\TestCases\TestCase;
+
+class ExceptionTest extends TestCase
+{
+    public function testCarriesTheOffendingFileInfo(): void
+    {
+        $fileInfo = new FileInfo(__DIR__ . '/assets/foo.txt', 'foo.txt');
+        $exception = new Exception('Invalid file extension', $fileInfo);
+
+        $this->assertSame('Invalid file extension', $exception->getMessage());
+        $this->assertSame($fileInfo, $exception->getFileInfo());
+    }
+
+    public function testFileInfoIsOptional(): void
+    {
+        $this->assertNull((new Exception('File validation failed'))->getFileInfo());
+    }
+
+    public function testPreservesCodeAndExceptionChain(): void
+    {
+        $previous = new RuntimeException('stat failed');
+        $exception = new Exception('File size could not be determined', null, 7, $previous);
+
+        $this->assertSame(7, $exception->getCode());
+        $this->assertSame($previous, $exception->getPrevious());
+    }
+
+    /**
+     * Consumers on v1/v2 catch \RuntimeException, so the parent must not change.
+     */
+    public function testRemainsARuntimeException(): void
+    {
+        $this->assertInstanceOf(RuntimeException::class, new Exception('File already exists'));
+    }
+}
diff --git a/tests/Upload/FileInfoTest.php b/tests/Upload/FileInfoTest.php
index b335173..f40deeb 100644
--- a/tests/Upload/FileInfoTest.php
+++ b/tests/Upload/FileInfoTest.php
@@ -25,6 +25,15 @@ public function set_up()
         $this->fileWithoutExtension = new FileInfo(__DIR__ . '/assets/foo_wo_ext', 'foo_wo_ext');
     }
 
+    /* phpcs:ignore */
+    public function tear_down()
+    {
+        /* The factory is process-wide state; leaving it set leaks into every later test */
+        FileInfo::resetFactory();
+
+        parent::tear_down();
+    }
+
     public function testGetName(): void
     {
         $this->assertSame('foo', $this->fileWithExtension->getName());
@@ -60,22 +69,20 @@ public function testGetMimetype(): void
         $this->assertSame('text/plain', $this->fileWithExtension->getMimetype());
     }
 
-    public function testGetMd5(): void
-    {
-        $hash = md5_file(__DIR__ . '/assets/foo.txt');
-
-        $this->assertSame($hash, $this->fileWithExtension->getMd5());
-    }
-
     public function testGetHash(): void
     {
         $sha1Hash = hash_file('sha1', __DIR__ . '/assets/foo.txt');
         $this->assertSame($sha1Hash, $this->fileWithExtension->getHash('sha1'));
 
         $md5Hash = hash_file('md5', __DIR__ . '/assets/foo.txt');
-
         $this->assertSame($md5Hash, $this->fileWithExtension->getHash('md5'));
-        $this->assertSame($md5Hash, $this->fileWithExtension->getHash());
+    }
+
+    public function testGetHashDefaultsToSha256(): void
+    {
+        $sha256Hash = hash_file('sha256', __DIR__ . '/assets/foo.txt');
+
+        $this->assertSame($sha256Hash, $this->fileWithExtension->getHash());
     }
 
     /**
@@ -106,9 +113,9 @@ public function providerSetNameSanitizing(): array
         return [
             0 => ['àáâãäåæçèéêëìíîïñòóôõöøùúûüýÿ', 'png', 'àáâãäåæçèéêëìíîïñòóôõöøùúûüýÿ.png'],
             1 => ['საბეჭდი_მანქანა', 'txt', 'საბეჭდი_მანქანა.txt'],
-            2 => ['unencoded space', 'php20', 'unencoded space.php%20'],
-            3 => ['encoded-space', 'php0a', 'encoded-space.php%0a'],
-            4 => ['plus-space', 'php0d0a', 'plus+space.php%0d%0a'],
+            2 => ['unencoded space', '', 'unencoded space.php%20'],
+            3 => ['encoded-space', '', 'encoded-space.php%0a'],
+            4 => ['plus-space', '', 'plus+space.php%0d%0a'],
             5 => ['multi-space', 'php', 'multi %20 +space.php/'],
             6 => ['file name-php', '', 'file   name.php.\\'],
             7 => ['file_name', '', 'file___name . '],
@@ -118,11 +125,11 @@ public function providerSetNameSanitizing(): array
             11 => ['file- - name', 'php7', 'file-- - name.php7'],
             12 => ['file - _ - name', 'php5', 'file - _ - name.Php5'],
             13 => ['file- name-php', '', 'file-- name.php...'],
-            14 => ['file', 'name', 'file-- . --.-.--name'],
+            14 => ['file', '', 'file-- . --.-.--name'],
             15 => ['file -name', '', 'file ..name ..'],
             16 => ['file name', 'txt', ' . file name . .txt'],
             17 => ['file', 'name', ' file . name '],
-            18 => ['file', 'name', '_file . name_'],
+            18 => ['file', '', '_file . name_'],
             19 => ['a-t-t', '', 'a----t----t'],
             20 => ['a-t-t-php-x00', 'png', 'a----t----t----.php\x00.png'],
             21 => ['a t', '', 'a          t'],
@@ -134,7 +141,7 @@ public function providerSetNameSanitizing(): array
             27 => ['sample file', '', ' ../sample file'],
             28 => ['sample file', 'txt', ' ../sample file.txt'],
             29 => ['sample file', '', ' ./sample file'],
-            30 => ['unnamed-file', 'samplefile', ' . sample file'],
+            30 => ['unnamed-file', '', ' . sample file'],
             31 => ['Sample File-s', '', '"Sample File\'s'],
             32 => ['S-am-ple-20 - -File', 'txt', 'S@{am}^(ple)!$20 %<>:" \|?*[File]#.txt'],
             33 => [str_repeat('A', 251), 'txt', str_repeat('A', 300) . '.txt'],
@@ -147,9 +154,187 @@ public function providerSetNameSanitizing(): array
             40 => ['file-con', 'txt', 'file-con.txt'],
             41 => ['lol', 'png', '../../../tmp/lol.png'],
             42 => ['sleep-10', 'jpg', 'sleep(10)-- -.jpg'],
-            43 => ['svg onload-alert-document', 'domain', '<svg onload=alert(document.domain)>'],
+            43 => ['svg onload-alert-document', '', '<svg onload=alert(document.domain)>'],
             44 => ['sleep 10', '', '; sleep 10;'],
             45 => ['This-Is-My-Sample', 'txt', 'This\\Is\\My\\Sample.txt'],
+
+            /* An extension is never rewritten into a different one; see testExtensionIsNeverSynthesized */
+            46 => ['evil', '', 'evil.p-h-p'],
+            47 => ['evil', '', 'evil.p h p'],
+            48 => ['evil', '', 'evil.p;h;p'],
+
+            /* Reserved Windows names are matched whole, not as substrings */
+            49 => ['doc', 'conf', 'doc.conf'],
+            50 => ['ico', 'icon', 'ico.icon'],
+            51 => ['x', '', 'x.aux'], /* `aux` is a reserved device name, so blanking is correct */
+            52 => ['archive-tar', 'gz', 'archive.tar.gz'],
+
+            /* Trailing whitespace should not cost the file its extension */
+            53 => ['report', 'txt', 'report.txt '],
+
+            /* DEL is the byte the storage layer rejects outright, so the sanitizer has to be
+               the thing that removes it */
+            54 => ['report', 'txt', "report\x7f.txt"],
+            55 => ['a-t', 'txt', "a\x7f\x7ft.txt"],
+
+            /* Characters that reorder or hide what renders around them. The name is the part a
+               person reads in an admin listing, an email or a log line. */
+            56 => ['resumegpj', 'exe', "resume\u{202E}gpj.exe"],
+            57 => ['invoice', 'pdf', "in\u{200B}voice.pdf"],
+            58 => ['report', 'txt', "\u{FEFF}report.txt"],
+            59 => ['photo', 'jpg', "\u{2066}photo\u{2069}.jpg"],
+
+            /* Line terminators for anything that honours them, the same reason \x00-\x1F goes */
+            63 => ['reportlog', 'txt', "report\u{2028}log.txt"],
+            64 => ['report', 'txt', "report\u{2029}.txt"],
+
+            /* `0` is a name, not the absence of one */
+            60 => ['0', 'txt', '0.txt'],
+            61 => ['0', '', '0'],
+
+            /* An alphanumeric extension has nothing else bounding its length, so it would
+               otherwise spend the whole 255 byte budget and push the name past the limit */
+            62 => ['photo', '', 'photo.' . str_repeat('a', 300)],
+        ];
+    }
+
+    /**
+     * @dataProvider providerExtensionLengths
+     */
+    public function testExtensionLengthIsCapped(int $length, string $expected): void
+    {
+        $file = new FileInfo(__DIR__ . '/assets/foo.txt', 'photo.' . str_repeat('a', $length));
+
+        $this->assertSame($expected, $file->getExtension());
+    }
+
+    /**
+     * @return array<string, array<int, int|string>>
+     */
+    public function providerExtensionLengths(): array
+    {
+        return [
+            'under the cap' => [8, str_repeat('a', 8)],
+            'at the cap' => [FileInfo::MAX_EXTENSION_LENGTH, str_repeat('a', FileInfo::MAX_EXTENSION_LENGTH)],
+            'over the cap' => [FileInfo::MAX_EXTENSION_LENGTH + 1, ''],
+            'far over the cap' => [300, ''],
+        ];
+    }
+
+    /**
+     * The extension is part of the same 255 byte budget as the name, including when the name
+     * falls back to `unnamed-file` after the budget has been divided up.
+     *
+     * @dataProvider providerOversizedNames
+     */
+    public function testStoredNameStaysWithin255Bytes(string $filename): void
+    {
+        $file = new FileInfo(__DIR__ . '/assets/foo.txt', $filename);
+
+        $this->assertLessThanOrEqual(255, strlen($file->getNameWithExtension()));
+    }
+
+    /**
+     * @return array<string, array<int, string>>
+     */
+    public function providerOversizedNames(): array
+    {
+        return [
+            'long name' => [str_repeat('A', 300) . '.txt'],
+            'long extension' => ['photo.' . str_repeat('a', 300)],
+            'long both' => [str_repeat('A', 300) . '.' . str_repeat('a', 300)],
+            'long extension, no name left' => ['.' . str_repeat('a', 300)],
+            'long extension, name blanked' => ['con.' . str_repeat('a', 300)],
+        ];
+    }
+
+    /**
+     * Deleting the disallowed characters normalises, so it can turn a harmless extension into a
+     * dangerous one. Discarding cannot produce an extension the client never sent.
+     *
+     * @dataProvider providerSynthesizableExtensions
+     */
+    public function testExtensionIsNeverSynthesized(string $filename): void
+    {
+        $file = new FileInfo(__DIR__ . '/assets/foo.txt', $filename);
+
+        $this->assertSame('', $file->getExtension());
+        $this->assertStringEndsNotWith('.php', $file->getNameWithExtension());
+    }
+
+    /**
+     * @return array<int, array<int,string>>
+     */
+    public function providerSynthesizableExtensions(): array
+    {
+        return [
+            ['evil.p-h-p'],
+            ['evil.p"h"p'],
+            ['evil.p<h>p'],
+            ['evil.p;h;p'],
+            ['evil.p+h+p'],
+            ['evil.p h p'],
+            ["evil.p\x00hp"],
+            ['evil.php%20'],
         ];
     }
+
+    /**
+     * An extension that is already alphanumeric is kept verbatim, including the multi-extension
+     * case where only the final part counts.
+     */
+    public function testLegitimateExtensionsSurvive(): void
+    {
+        $file = new FileInfo(__DIR__ . '/assets/foo.txt', 'evil.p.h.p');
+
+        $this->assertSame('p', $file->getExtension());
+        $this->assertSame('evil-p-h.p', $file->getNameWithExtension());
+    }
+
+    public function testSanitizedNameIsAlwaysValidUtf8(): void
+    {
+        /* "\xC3" opens a 2-byte sequence completed by "(", which is stripped as URI reserved */
+        $file = new FileInfo(__DIR__ . '/assets/foo.txt', "\xC3\x28.png");
+
+        $this->assertTrue(mb_check_encoding($file->getName(), 'UTF-8'));
+        $this->assertTrue(mb_check_encoding($file->getNameWithExtension(), 'UTF-8'));
+        $this->assertNotSame(false, json_encode($file->getNameWithExtension()));
+    }
+
+    public function testMetadataAccessorsDegradeOnUnreadableFile(): void
+    {
+        $file = new FileInfo('', 'missing.txt');
+
+        $this->assertSame('', $file->getMimetype());
+        $this->assertSame('', $file->getHash());
+        $this->assertSame('', $file->getHash('md5'));
+        $this->assertSame(false, $file->getSize());
+        $this->assertSame(['width' => 0, 'height' => 0], $file->getDimensions());
+    }
+
+    public function testGetHashRejectsUnsupportedAlgorithm(): void
+    {
+        $this->expectException(Exception::class);
+        $this->expectExceptionMessage('Unsupported hashing algorithm: bogus');
+
+        $this->fileWithExtension->getHash('bogus');
+    }
+
+    public function testResetFactory(): void
+    {
+        /* A distinguishable subclass, so the assertions can tell the factory from the
+           default `new static()` path */
+        FileInfo::setFactory(static function ($tmpName, $name) {
+            return new class ($tmpName, $name) extends FileInfo {
+            };
+        });
+
+        $fromFactory = FileInfo::createFromFactory(__DIR__ . '/assets/foo.txt', 'foo.txt');
+        $this->assertNotSame(FileInfo::class, get_class($fromFactory));
+
+        FileInfo::resetFactory();
+
+        $afterReset = FileInfo::createFromFactory(__DIR__ . '/assets/foo.txt', 'foo.txt');
+        $this->assertSame(FileInfo::class, get_class($afterReset));
+    }
 }
diff --git a/tests/Upload/FileTest.php b/tests/Upload/FileTest.php
index f1a1b92..3cdb3ce 100644
--- a/tests/Upload/FileTest.php
+++ b/tests/Upload/FileTest.php
@@ -75,6 +75,15 @@ public function set_up()
         ];
     }
 
+    /* phpcs:ignore */
+    public function tear_down()
+    {
+        /* The factory is process-wide state; leaving it set leaks into every later test */
+        FileInfo::resetFactory();
+
+        parent::tear_down();
+    }
+
     /********************************************************************************
      * Construction tests
      *******************************************************************************/
@@ -183,6 +192,7 @@ public function testCallbacks(): void
         $file->afterValidate($callbackAfterValidate);
         $file->beforeUpload($callbackBeforeUpload);
         $file->afterUpload($callbackAfterUpload);
+        $file->allowUnvalidatedUploads();
         $file->upload();
     }
 
@@ -314,6 +324,7 @@ public function testMultipleGetErrors(): void
     public function testWillUploadIfValid(): void
     {
         $file = new File('single', $this->storage);
+        $file->addValidation(new Mimetype(['text/plain']));
         $this->assertTrue($file->isValid());
 
         try {
@@ -330,10 +341,31 @@ public function testWillNotUploadIfInvalid(): void
         $this->expectExceptionMessage('File validation failed');
 
         $file = new File('bad', $this->storage);
+        $file->addValidation(new Mimetype(['text/plain']));
         $this->assertFalse($file->isValid());
         $file->upload();
     }
 
+    /**
+     * An endpoint that validates nothing stores whatever is submitted, which is more often an
+     * unfinished endpoint than a decision.
+     */
+    public function testUploadRefusesWhenNothingHasBeenConfiguredToValidate(): void
+    {
+        $this->expectException(Exception::class);
+        $this->expectExceptionMessage('No validations have been added');
+
+        (new File('single', $this->storage))->upload();
+    }
+
+    public function testAllowUnvalidatedUploadsMakesItADecision(): void
+    {
+        $file = new File('single', $this->storage);
+        $file->allowUnvalidatedUploads();
+
+        $this->assertTrue($file->upload());
+    }
+
     /********************************************************************************
      * Helper tests
      *******************************************************************************/
@@ -346,4 +378,283 @@ public function testParsesHumanFriendlyFileSizes(): void
         $this->assertEquals(107374182400, File::humanReadableToBytes('100G'));
         $this->assertEquals(100, File::humanReadableToBytes('100F')); // <-- Unrecognized. Assume bytes.
     }
+
+    public function testParsesFractionalAndSuffixedFileSizes(): void
+    {
+        $this->assertSame(524288, File::humanReadableToBytes('0.5M'));
+        $this->assertSame(1536, File::humanReadableToBytes('1.5K'));
+
+        /* The Size docblock has always advertised "5MB"; it used to evaluate to 5 bytes */
+        $this->assertSame(5242880, File::humanReadableToBytes('5MB'));
+        $this->assertSame(102400, File::humanReadableToBytes('100KB'));
+        $this->assertSame(100, File::humanReadableToBytes(' 100 '));
+    }
+
+    public function testOversizedFileSizeIsClampedRatherThanFatal(): void
+    {
+        $this->assertSame(PHP_INT_MAX, File::humanReadableToBytes('1000000000000G'));
+    }
+
+    /**
+     * @dataProvider providerUnparseableFileSizes
+     */
+    public function testRejectsUnparseableFileSizes(string $input): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+
+        File::humanReadableToBytes($input);
+    }
+
+    /**
+     * @return array<int, array<int, string>>
+     */
+    public function providerUnparseableFileSizes(): array
+    {
+        return [
+            ['abc'],
+            ['-5M'],
+            [''],
+            ['M'],
+        ];
+    }
+
+    /********************************************************************************
+     * Hardening regression tests
+     *******************************************************************************/
+
+    /**
+     * Every other filename reaching getErrors() has been sanitized. The constructor's error
+     * path was the exception, and the README tells callers to display getErrors().
+     */
+    public function testConstructorErrorSanitizesTheClientFilename(): void
+    {
+        $_FILES['xss'] = [
+            'name' => '<img src=x onerror=alert(document.domain)>.png',
+            'tmp_name' => '',
+            'error' => UPLOAD_ERR_INI_SIZE,
+        ];
+
+        $errors = (new File('xss', $this->storage))->getErrors();
+
+        $this->assertCount(1, $errors);
+        $this->assertStringNotContainsString('<', $errors[0]);
+        $this->assertStringNotContainsString('>', $errors[0]);
+        $this->assertStringContainsString('exceeds the upload_max_filesize', $errors[0]);
+    }
+
+    /**
+     * Submitting a form with an empty file input yields UPLOAD_ERR_NO_FILE and an empty
+     * tmp_name. The single-file branch used to build a FileInfo for it anyway, so the
+     * README's documented "read the metadata" flow raised an uncaught ValueError.
+     */
+    public function testEmptyFileInputDoesNotProduceAFileInfo(): void
+    {
+        $_FILES['empty'] = [
+            'name' => '',
+            'tmp_name' => '',
+            'error' => UPLOAD_ERR_NO_FILE,
+        ];
+
+        $file = new File('empty', $this->storage);
+
+        $this->assertCount(0, $file);
+        $this->assertFalse($file->isValid());
+        $this->assertNull($file->getMimetype());
+        $this->assertCount(1, $file->getErrors());
+    }
+
+    /**
+     * The single-file and multi-file shapes must agree for the same logical condition.
+     */
+    public function testEmptyFileInputBehavesTheSameForBothFormShapes(): void
+    {
+        $_FILES['single_empty'] = ['name' => '', 'tmp_name' => '', 'error' => UPLOAD_ERR_NO_FILE];
+        $_FILES['multi_empty'] = ['name' => [''], 'tmp_name' => [''], 'error' => [UPLOAD_ERR_NO_FILE]];
+
+        $single = new File('single_empty', $this->storage);
+        $multi = new File('multi_empty', $this->storage);
+
+        $this->assertSame(count($multi), count($single));
+        $this->assertSame($multi->getErrors(), $single->getErrors());
+    }
+
+    /**
+     * Every validation passes when there is nothing to run it against, so `upload()` reported
+     * success having written nothing, and a caller reading that as "the file arrived" was
+     * misled.
+     */
+    public function testUploadRefusesWhenThereIsNothingToStore(): void
+    {
+        $_FILES['none'] = ['name' => [], 'tmp_name' => [], 'error' => []];
+
+        $file = new File('none', $this->storage);
+        $file->allowUnvalidatedUploads();
+
+        $this->assertCount(0, $file);
+        $this->assertTrue($file->isValid());
+        $this->assertSame([], $file->getErrors());
+
+        $this->expectException(Exception::class);
+        $this->expectExceptionMessage('There are no files to upload');
+
+        $file->upload();
+    }
+
+    /**
+     * That guard sits after isValid(), so a transfer that failed is still reported the way it
+     * always was, with the detail in getErrors() rather than in the exception message.
+     */
+    public function testFailedTransferIsStillReportedAsAValidationFailure(): void
+    {
+        $file = new File('bad', $this->storage);
+        $file->allowUnvalidatedUploads();
+
+        try {
+            $file->upload();
+            $this->fail('Expected the failed transfer to throw');
+        } catch (Exception $e) {
+            $this->assertSame('File validation failed', $e->getMessage());
+        }
+
+        $this->assertCount(1, $file->getErrors());
+    }
+
+    /**
+     * A field named `f[0][0]` nests $_FILES one level deeper than either shape this class
+     * knows. It is remote input, so it has to fail without emitting "Array to string
+     * conversion" and without reporting the file as "Array".
+     */
+    public function testNestedFileInputIsRejectedWithoutAWarning(): void
+    {
+        $_FILES['nested'] = [
+            'name' => [['evil.txt']],
+            'tmp_name' => [[$this->assetsDirectory . '/foo.txt']],
+            'error' => [[UPLOAD_ERR_OK]],
+        ];
+
+        /** @var string[] $raised */
+        $raised = [];
+        set_error_handler(static function (int $severity, string $message) use (&$raised): bool {
+            $raised[] = $message;
+
+            return true;
+        });
+
+        try {
+            $file = new File('nested', $this->storage);
+        } finally {
+            restore_error_handler();
+        }
+
+        $this->assertSame([], $raised);
+        $this->assertCount(0, $file);
+        $this->assertFalse($file->isValid());
+        $this->assertCount(1, $file->getErrors());
+        $this->assertStringNotContainsString('Array', $file->getErrors()[0]);
+    }
+
+    public function testIsValidDoesNotDuplicateErrorsWhenCalledTwice(): void
+    {
+        $file = new File('single', $this->storage);
+        $file->addValidation(new Mimetype(['text/csv']));
+
+        $this->assertFalse($file->isValid());
+        $this->assertFalse($file->isValid());
+
+        $this->assertCount(1, $file->getErrors());
+    }
+
+    public function testConstructorErrorsSurviveRevalidation(): void
+    {
+        $file = new File('bad', $this->storage);
+
+        $this->assertFalse($file->isValid());
+        $this->assertFalse($file->isValid());
+
+        $this->assertCount(1, $file->getErrors());
+    }
+
+    /**
+     * ValidationInterface is an extension point, so a validator throwing something other
+     * than Upload\Exception must not abort the batch and bypass error accumulation.
+     */
+    public function testValidatorThrowingUnexpectedlyIsRecordedNotPropagated(): void
+    {
+        $file = new File('multiple', $this->storage);
+        $file->addValidation(new class implements ValidationInterface {
+            public function validate(FileInfoInterface $fileInfo): void
+            {
+                throw new \RuntimeException('stat failed for /private/tmp/phpXXXX');
+            }
+        });
+
+        $this->assertFalse($file->isValid());
+
+        $errors = $file->getErrors();
+        $this->assertCount(2, $errors);
+        foreach ($errors as $error) {
+            $this->assertStringContainsString('Validation could not be completed', $error);
+            /* PHP runtime messages can contain absolute paths */
+            $this->assertStringNotContainsString('/private/tmp', $error);
+        }
+    }
+
+    public function testOffsetSetRejectsNonFileInfo(): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+        $this->expectExceptionMessage('Value must be an instance of');
+
+        $file = new File('single', $this->storage);
+        $file[0] = 'not-a-file-info'; /* @phpstan-ignore-line */
+    }
+
+    /**
+     * A multi-file upload is not atomic, so a caller needs to know what was already written
+     * when a later file fails.
+     */
+    public function testGetUploadedFilesReportsWhatWasWrittenBeforeAFailure(): void
+    {
+        $storage = $this->getMockBuilder(FileSystem::class)
+            ->setConstructorArgs([$this->assetsDirectory])
+            ->onlyMethods(['upload'])
+            ->getMock();
+
+        $storage
+            ->method('upload')
+            ->willReturnOnConsecutiveCalls(
+                '/tmp/uploads/foo.txt',
+                $this->throwException(new Exception('File already exists'))
+            );
+
+        $file = new File('multiple', $storage);
+        $file->allowUnvalidatedUploads();
+
+        try {
+            $file->upload();
+            $this->fail('Expected the second file to fail');
+        } catch (Exception $e) {
+            $this->assertSame('File already exists', $e->getMessage());
+        }
+
+        $this->assertSame(['/tmp/uploads/foo.txt'], $file->getUploadedFiles());
+        $this->assertCount(0, $file->getErrors());
+    }
+
+    public function testGetUploadedFilesOnSuccess(): void
+    {
+        $storage = $this->getMockBuilder(FileSystem::class)
+            ->setConstructorArgs([$this->assetsDirectory])
+            ->onlyMethods(['upload'])
+            ->getMock();
+
+        $storage
+            ->method('upload')
+            ->willReturnOnConsecutiveCalls('/tmp/uploads/foo.txt', '/tmp/uploads/bar.txt');
+
+        $file = new File('multiple', $storage);
+        $file->allowUnvalidatedUploads();
+        $file->upload();
+
+        $this->assertSame(['/tmp/uploads/foo.txt', '/tmp/uploads/bar.txt'], $file->getUploadedFiles());
+    }
 }
diff --git a/tests/Upload/Storage/FileSystemTest.php b/tests/Upload/Storage/FileSystemTest.php
index ca1c1d0..812f2cf 100644
--- a/tests/Upload/Storage/FileSystemTest.php
+++ b/tests/Upload/Storage/FileSystemTest.php
@@ -14,6 +14,12 @@ class FileSystemTest extends TestCase
      */
     protected $assetsDirectory;
 
+    /**
+     * Scratch directories created by makeWorkingDirectory(), removed in tear_down()
+     * @var string[]
+     */
+    protected $workingDirectories = [];
+
     /* phpcs:ignore */
     public function set_up()
     {
@@ -30,6 +36,27 @@ public function set_up()
         ];
     }
 
+    /* phpcs:ignore */
+    public function tear_down()
+    {
+        foreach ($this->workingDirectories as $workingDirectory) {
+            /* A test is free to remove its own working directory */
+            if (is_dir($workingDirectory)) {
+                /* scandir() rather than glob(), which does not report dangling symlinks */
+                foreach ($this->entriesIn($workingDirectory) as $entry) {
+                    @unlink($workingDirectory . '/' . $entry);
+                }
+            }
+
+            @rmdir($workingDirectory);
+            @rmdir(dirname($workingDirectory));
+        }
+
+        $this->workingDirectories = [];
+
+        parent::tear_down();
+    }
+
     public function testInstantiationWithValidDirectory(): void
     {
         try {
@@ -70,50 +97,479 @@ public function testWillNotOverwriteFile(): void
      */
     public function testWillOverwriteFile(): void
     {
+        $workingDirectory = $this->makeWorkingDirectory();
+        file_put_contents($workingDirectory . '/foo.txt', 'the file that was already there');
+
+        $storage = $this->makeStorage($workingDirectory, true);
+        $storage->upload(new FileInfo($this->assetsDirectory . '/foo.txt', 'foo.txt'));
+
+        $this->assertStringEqualsFile(
+            $workingDirectory . '/foo.txt',
+            (string)file_get_contents($this->assetsDirectory . '/foo.txt')
+        );
+    }
+
+    /**
+     * A `FileInfoInterface` is a public extension point, so the storage layer must not
+     * assume the name it is handed was sanitized by `FileInfo`.
+     */
+    public function testRejectsTraversalInFileName(): void
+    {
+        $workingDirectory = $this->makeWorkingDirectory();
+        $escapeTarget = dirname($workingDirectory) . '/escaped.txt';
+
+        $storage = $this->makeStorage($workingDirectory, true);
+        $fileInfo = $this->makeHostileFileInfo('../escaped.txt');
+
+        $storage->upload($fileInfo);
+
+        $this->assertFileDoesNotExist($escapeTarget);
+        $this->assertFileExists($workingDirectory . '/escaped.txt');
+    }
+
+    /**
+     * @dataProvider providerUnusableFileNames
+     */
+    public function testRejectsUnusableFileNames(string $name): void
+    {
+        $this->expectException(Exception::class);
+        $this->expectExceptionMessage('Invalid destination file name');
+
+        $storage = $this->makeStorage($this->makeWorkingDirectory(), true);
+        $storage->upload($this->makeHostileFileInfo($name));
+    }
+
+    /**
+     * @return array<string, array<int, string>>
+     */
+    public function providerUnusableFileNames(): array
+    {
+        return [
+            'empty' => [''],
+            'this directory' => ['.'],
+            'parent directory' => ['..'],
+            'separator only' => ['/'],
+            'traversal only' => ['../..'],
+            /* PHP 8 raises a ValueError for a null byte in a path, so reject it as our own error */
+            'null byte' => ["shell.php\0.png"],
+
+            /* Hidden from the shell globbing and directory listings a cleanup script uses */
+            'dotfile' => ['.env'],
+            'dotfile with an allowed extension' => ['.hidden.txt'],
+
+            /* A name that can forge a line in a log, or move the cursor in a terminal */
+            'newline' => ["report\n2024-01-01 INFO all clear.txt"],
+            'escape sequence' => ["report\x1b[2Kfake.txt"],
+            'delete' => ["report\x7f.txt"],
+        ];
+    }
+
+    public function testRefusesToWriteThroughASymlink(): void
+    {
+        $workingDirectory = $this->makeWorkingDirectory();
+        $target = $workingDirectory . '/target.txt';
+        symlink($target, $workingDirectory . '/link.txt');
+
+        $this->expectException(Exception::class);
+        $this->expectExceptionMessage('Destination is a symbolic link');
+
+        $storage = $this->makeStorage($workingDirectory, true);
+        $storage->upload($this->makeHostileFileInfo('link.txt'));
+    }
+
+    /**
+     * With `overwrite = false` the collision check and the create must be one operation,
+     * otherwise two concurrent requests both pass the check.
+     */
+    public function testExclusiveCreateDetectsDanglingSymlink(): void
+    {
+        $workingDirectory = $this->makeWorkingDirectory();
+        symlink($workingDirectory . '/does-not-exist', $workingDirectory . '/dangling.txt');
+
+        $this->expectException(Exception::class);
+        $this->expectExceptionMessage('Destination is a symbolic link');
+
+        $storage = $this->makeStorage($workingDirectory, false);
+        $storage->upload($this->makeHostileFileInfo('dangling.txt'));
+    }
+
+    public function testFailedMoveDoesNotLeaveAPlaceholderBehind(): void
+    {
+        $workingDirectory = $this->makeWorkingDirectory();
+
         $storage = $this->getMockBuilder(FileSystem::class)
-            ->setConstructorArgs([$this->assetsDirectory, true])
+            ->setConstructorArgs([$workingDirectory, false])
             ->onlyMethods(['moveUploadedFile'])
             ->getMock();
 
         $storage
             ->method('moveUploadedFile')
-            ->willReturn(true);
+            ->willReturn(false);
 
-        $fileInfo = $this->getMockBuilder(FileInfo::class)
-            ->setConstructorArgs([dirname(__DIR__) . '/assets/foo.txt', 'foo.txt'])
-            ->onlyMethods(['isUploadedFile'])
+        try {
+            $storage->upload(new FileInfo($this->assetsDirectory . '/foo.txt', 'foo.txt'));
+            $this->fail('Expected the failed move to throw');
+        } catch (Exception $e) {
+            $this->assertSame('File could not be moved to final destination.', $e->getMessage());
+        }
+
+        $this->assertFileDoesNotExist($workingDirectory . '/foo.txt');
+
+        /* Neither the reserved destination nor the staging file the upload was headed for */
+        $this->assertSame([], $this->entriesIn($workingDirectory));
+    }
+
+    /**
+     * Nothing checked before the write can be relied on at the moment of the write: the entry
+     * can change in between. What keeps the upload out of a symlinked target is that the bytes
+     * go to a staged name and are `rename()`d on, which replaces the entry rather than
+     * resolving it. The stub stands in for an attacker winning that race.
+     */
+    public function testSymlinkPlantedDuringTheWriteIsReplacedNotFollowed(): void
+    {
+        $workingDirectory = $this->makeWorkingDirectory();
+        $target = $workingDirectory . '/target.txt';
+        file_put_contents($target, 'the file the attacker chose');
+
+        $storage = $this->getMockBuilder(FileSystem::class)
+            ->setConstructorArgs([$workingDirectory, false])
+            ->onlyMethods(['moveUploadedFile'])
+            ->getMock();
+
+        $storage
+            ->method('moveUploadedFile')
+            ->willReturnCallback(
+                static function (string $source, string $destination) use ($workingDirectory, $target): bool {
+                    unlink($workingDirectory . '/upload.txt');
+                    symlink($target, $workingDirectory . '/upload.txt');
+
+                    return copy($source, $destination);
+                }
+            );
+
+        $storage->upload($this->makeHostileFileInfo('upload.txt'));
+
+        $this->assertStringEqualsFile($target, 'the file the attacker chose');
+        $this->assertFalse(is_link($workingDirectory . '/upload.txt'));
+        $this->assertStringEqualsFile(
+            $workingDirectory . '/upload.txt',
+            (string)file_get_contents($this->assetsDirectory . '/foo.txt')
+        );
+    }
+
+    /**
+     * An upload that cannot be staged must not leave the finished file readable anyway, and a
+     * mode that could not be applied is not the `0640` the class documents.
+     */
+    public function testFileIsNotStoredWhenTheModeCannotBeApplied(): void
+    {
+        $workingDirectory = $this->makeWorkingDirectory();
+
+        $storage = $this->getMockBuilder(FileSystem::class)
+            ->setConstructorArgs([$workingDirectory, false])
+            ->onlyMethods(['moveUploadedFile'])
             ->getMock();
 
-        $fileInfo
-            ->method('isUploadedFile')
+        /* Report the move as done without producing the staged file, so the chmod that follows
+           has nothing to act on */
+        $storage
+            ->method('moveUploadedFile')
             ->willReturn(true);
 
         try {
-            $storage->upload($fileInfo);
-            $this->assertTrue(true);
+            $storage->upload($this->makeHostileFileInfo('private.txt'));
+            $this->fail('Expected the failed chmod to throw');
         } catch (Exception $e) {
-            $this->fail('Unexpected exception thrown');
+            $this->assertSame('Permissions could not be applied to the stored file', $e->getMessage());
         }
+
+        $this->assertSame([], $this->entriesIn($workingDirectory));
     }
 
-    public function testReturnsUploadedFileName(): void
+    /**
+     * `x` mode fails for reasons other than the name being taken. Reporting those as a
+     * collision sends the caller into a rename-and-retry loop that cannot succeed.
+     */
+    public function testCreateFailureThatIsNotACollisionIsReportedAsItself(): void
+    {
+        $workingDirectory = $this->makeWorkingDirectory();
+        $storage = $this->makeStorage($workingDirectory, false);
+
+        /* Gone since the constructor checked it */
+        rmdir($workingDirectory);
+
+        $this->expectException(Exception::class);
+        $this->expectExceptionMessage('Destination file could not be created');
+
+        $storage->upload($this->makeHostileFileInfo('foo.txt'));
+    }
+
+    public function testBlockedExtensionsAreRefused(): void
+    {
+        $storage = $this->makeStorage($this->makeWorkingDirectory(), true)->blockExtensions();
+
+        $this->expectException(Exception::class);
+        $this->expectExceptionMessage('Files with the extension "php" cannot be stored');
+
+        $storage->upload($this->makeHostileFileInfo('shell.php'));
+    }
+
+    /**
+     * @dataProvider providerDefaultBlockedExtensions
+     */
+    public function testBlockingIsOnByDefault(string $name, string $extension): void
+    {
+        $this->expectException(Exception::class);
+        $this->expectExceptionMessage(sprintf('Files with the extension "%s" cannot be stored', $extension));
+
+        $storage = $this->makeStorage($this->makeWorkingDirectory(), true);
+        $storage->upload($this->makeHostileFileInfo($name));
+    }
+
+    /**
+     * @return array<string, array<int, string>>
+     */
+    public function providerDefaultBlockedExtensions(): array
+    {
+        return [
+            'server executes it' => ['shell.php', 'php'],
+            'server reads it as configuration' => ['config.ini', 'ini'],
+            'browser renders it as markup' => ['stored-xss.html', 'html'],
+            'browser runs script inside it' => ['logo.svg', 'svg'],
+        ];
+    }
+
+    public function testBlockingCanBeTurnedOff(): void
+    {
+        $workingDirectory = $this->makeWorkingDirectory();
+        $storage = $this->makeStorage($workingDirectory, true)->blockExtensions([]);
+
+        $storage->upload($this->makeHostileFileInfo('shell.php'));
+
+        $this->assertFileExists($workingDirectory . '/shell.php');
+    }
+
+    public function testBlockedExtensionsAcceptACustomList(): void
+    {
+        $workingDirectory = $this->makeWorkingDirectory();
+        $storage = $this->makeStorage($workingDirectory, true)->blockExtensions(['exe']);
+
+        /* `php` is not on this caller's list, so it is allowed through */
+        $storage->upload($this->makeHostileFileInfo('shell.php'));
+        $this->assertFileExists($workingDirectory . '/shell.php');
+
+        $this->expectException(Exception::class);
+        $this->expectExceptionMessage('Files with the extension "exe" cannot be stored');
+        $storage->upload($this->makeHostileFileInfo('installer.exe'));
+    }
+
+    /**
+     * `pathinfo()` reads the name the way PHP splits it. A server does not have to agree, and
+     * where it does not, the extension that decides how the file is served is one `pathinfo()`
+     * never returned.
+     *
+     * @dataProvider providerNamesThatHideABlockedExtension
+     */
+    public function testDenyListCoversExtensionsPathinfoDoesNotReturn(string $name): void
+    {
+        $this->expectException(Exception::class);
+        $this->expectExceptionMessage('Files with the extension "php" cannot be stored');
+
+        $storage = $this->makeStorage($this->makeWorkingDirectory(), true);
+        $storage->upload($this->makeHostileFileInfo($name));
+    }
+
+    /**
+     * @return array<string, array<int, string>>
+     */
+    public function providerNamesThatHideABlockedExtension(): array
+    {
+        return [
+            /* Windows resolves both of these to `evil.php` */
+            'trailing dot' => ['evil.php.'],
+            'trailing space' => ['evil.php '],
+            'trailing dots and spaces' => ['evil.php . '],
+
+            /* Apache's AddHandler and AddType match any dot component, not just the last */
+            'inner extension' => ['evil.php.jpg'],
+            'inner extension among several' => ['evil.php.tar.gz'],
+            'inner extension with padding' => ['evil.php .jpg'],
+        ];
+    }
+
+    /**
+     * A name is not a blocked extension, so a file called `php` is storable.
+     */
+    public function testDenyListDoesNotApplyToTheNameItself(): void
+    {
+        $workingDirectory = $this->makeWorkingDirectory();
+        $storage = $this->makeStorage($workingDirectory, true);
+
+        $storage->upload($this->makeHostileFileInfo('php'));
+
+        $this->assertFileExists($workingDirectory . '/php');
+    }
+
+    /**
+     * Trailing dots and spaces are taken off the stored name too, so that what is on disk is
+     * the name that was checked.
+     */
+    public function testTrailingDotsAndSpacesAreNotStored(): void
+    {
+        $workingDirectory = $this->makeWorkingDirectory();
+        $storage = $this->makeStorage($workingDirectory, true);
+
+        $this->assertSame(
+            $workingDirectory . '/report.txt',
+            $storage->upload($this->makeHostileFileInfo('report.txt. '))
+        );
+    }
+
+    /**
+     * The values compared against the list never carry a leading dot, so keeping one would
+     * block nothing while the caller believes they tightened the list.
+     */
+    public function testBlockedExtensionsAcceptALeadingDot(): void
+    {
+        $storage = $this->makeStorage($this->makeWorkingDirectory(), true)->blockExtensions(['.php', '.exe']);
+
+        $this->expectException(Exception::class);
+        $this->expectExceptionMessage('Files with the extension "php" cannot be stored');
+
+        $storage->upload($this->makeHostileFileInfo('pwn.php'));
+    }
+
+    /**
+     * The deny-list is documented in two places and will drift.
+     */
+    public function testReadmeDocumentsTheDefaultDenyList(): void
+    {
+        $readme = (string)file_get_contents(dirname(__DIR__, 3) . '/.github/README.md');
+
+        if (preg_match('/### Extensions blocked by default(.*?)```/s', $readme, $section) !== 1) {
+            $this->fail('The README no longer has an "Extensions blocked by default" table');
+        }
+
+        /* Backticked lowercase words only, which skips `blockExtensions()` and the constant names */
+        preg_match_all('/`([a-z0-9]+)`/', $section[1], $matches);
+
+        $this->assertSame(
+            FileSystem::defaultBlockedExtensions(),
+            $matches[1],
+            'The README table and FileSystem::defaultBlockedExtensions() have drifted apart'
+        );
+    }
+
+    public function testSetModeAppliesPermissions(): void
+    {
+        $workingDirectory = $this->makeWorkingDirectory();
+        $storage = $this->makeStorage($workingDirectory, true)->setMode(0600);
+
+        $storage->upload($this->makeHostileFileInfo('private.txt'));
+
+        $this->assertSame('0600', $this->modeOf($workingDirectory . '/private.txt'));
+    }
+
+    public function testDefaultModeIsAppliedWithoutBeingAskedFor(): void
+    {
+        $workingDirectory = $this->makeWorkingDirectory();
+        $storage = $this->makeStorage($workingDirectory, true);
+
+        $storage->upload($this->makeHostileFileInfo('default.txt'));
+
+        $this->assertSame('0640', $this->modeOf($workingDirectory . '/default.txt'));
+    }
+
+    /**
+     * `setMode(null)` hands the mode back to the process umask, which is what
+     * `move_uploaded_file()` does on its own.
+     */
+    public function testModeCanBeHandedBackToTheUmask(): void
+    {
+        $workingDirectory = $this->makeWorkingDirectory();
+        $storage = $this->makeStorage($workingDirectory, true)->setMode(null);
+
+        $umask = umask(0022);
+        $storage->upload($this->makeHostileFileInfo('umask.txt'));
+        umask($umask);
+
+        $this->assertNotSame('0640', $this->modeOf($workingDirectory . '/umask.txt'));
+    }
+
+    protected function modeOf(string $path): string
+    {
+        return substr(sprintf('%o', fileperms($path)), -4);
+    }
+
+    /**
+     * @return string[]
+     */
+    protected function entriesIn(string $directory): array
+    {
+        $entries = scandir($directory);
+
+        return $entries === false ? [] : array_values(array_diff($entries, ['.', '..']));
+    }
+
+    /**
+     * A scratch directory that is removed again in tear_down()
+     */
+    protected function makeWorkingDirectory(): string
+    {
+        $workingDirectory = sys_get_temp_dir() . '/upload-test-' . uniqid('', true) . '/uploads';
+        mkdir($workingDirectory, 0777, true);
+        $this->workingDirectories[] = $workingDirectory;
+
+        return $workingDirectory;
+    }
+
+    /**
+     * A real `FileSystem` with only `move_uploaded_file()` swapped for a copy, so the
+     * destination-resolution logic under test runs unmodified without a POST upload.
+     *
+     * @return FileSystem&\PHPUnit\Framework\MockObject\MockObject
+     */
+    protected function makeStorage(string $directory, bool $overwrite)
     {
         $storage = $this->getMockBuilder(FileSystem::class)
-            ->setConstructorArgs([$this->assetsDirectory, true])
+            ->setConstructorArgs([$directory, $overwrite])
             ->onlyMethods(['moveUploadedFile'])
             ->getMock();
 
         $storage
             ->method('moveUploadedFile')
-            ->willReturn(true);
+            ->willReturnCallback(static function (string $source, string $destination): bool {
+                return copy($source, $destination);
+            });
 
-        $fileName = dirname(__DIR__) . '/assets/foo.txt';
+        return $storage;
+    }
 
-        $fileInfo = new FileInfo(
-            $fileName
-        );
+    /**
+     * Returns whatever name it is given, standing in for a third-party implementation that
+     * does none of `FileInfo`'s sanitizing.
+     */
+    protected function makeHostileFileInfo(string $name): FileInfo
+    {
+        $fileInfo = $this->getMockBuilder(FileInfo::class)
+            ->setConstructorArgs([$this->assetsDirectory . '/foo.txt', 'foo.txt'])
+            ->onlyMethods(['getNameWithExtension'])
+            ->getMock();
 
-        $this->assertSame($fileName, $storage->upload($fileInfo));
-        $this->assertSame($this->assetsDirectory, $storage->getDirectory());
+        $fileInfo->method('getNameWithExtension')->willReturn($name);
+
+        return $fileInfo;
+    }
+
+    public function testReturnsUploadedFileName(): void
+    {
+        $workingDirectory = $this->makeWorkingDirectory();
+        $storage = $this->makeStorage($workingDirectory, true);
+
+        $this->assertSame(
+            $workingDirectory . '/foo.txt',
+            $storage->upload(new FileInfo($this->assetsDirectory . '/foo.txt', 'foo.txt'))
+        );
+        $this->assertSame($workingDirectory, $storage->getDirectory());
     }
 }
diff --git a/tests/Upload/Validation/FileTypeTest.php b/tests/Upload/Validation/FileTypeTest.php
new file mode 100644
index 0000000..360ffc6
--- /dev/null
+++ b/tests/Upload/Validation/FileTypeTest.php
@@ -0,0 +1,209 @@
+<?php
+
+namespace GravityPdf\Upload\Validation;
+
+use GravityPdf\Upload\Exception;
+use GravityPdf\Upload\FileInfo;
+use InvalidArgumentException;
+use Yoast\PHPUnitPolyfills\TestCases\TestCase;
+
+class FileTypeTest extends TestCase
+{
+    /**
+     * @var string
+     */
+    private $assetsDirectory;
+
+    /* phpcs:ignore */
+    public function set_up()
+    {
+        parent::set_up();
+
+        $this->assetsDirectory = dirname(__DIR__) . '/assets';
+    }
+
+    public function testMatchingExtensionAndMimetypePasses(): void
+    {
+        $file = new FileInfo($this->assetsDirectory . '/foo.png', 'foo.png');
+        $validation = new FileType('png', 'image/png');
+
+        $validation->validate($file);
+
+        $this->assertTrue(true);
+    }
+
+    public function testExtensionNotOnTheListIsRejected(): void
+    {
+        $this->expectException(Exception::class);
+        $this->expectExceptionMessage('Invalid file extension. Must be one of: png, gif');
+
+        $file = new FileInfo($this->assetsDirectory . '/foo.txt', 'foo.txt');
+
+        (new FileType('png', 'image/png'))
+            ->allow('gif', 'image/gif')
+            ->validate($file);
+    }
+
+    /**
+     * A file named `.png` whose contents sniff as text/plain, which is the shape a polyglot
+     * takes once it is stored under an extension the web server will hand to an interpreter.
+     */
+    public function testMimetypeMustMatchTheExtension(): void
+    {
+        $this->expectException(Exception::class);
+        $this->expectExceptionMessage('File contents do not match the "png" extension. Must be one of: image/png');
+
+        $file = new FileInfo($this->assetsDirectory . '/foo.txt', 'foo.png');
+        $validation = new FileType('png', 'image/png');
+        $validation->validate($file);
+    }
+
+    /**
+     * The gap this class closes: `Extension` and `Mimetype` check independent allow-lists, so
+     * a file passes both while the two answers describe different formats. Each `allow()` call
+     * covers one format, which is what keeps the pairing from widening into a cross product.
+     */
+    public function testCrossedPairPassesExtensionAndMimetypeSeparately(): void
+    {
+        $file = new FileInfo($this->assetsDirectory . '/foo.txt', 'foo.png');
+
+        (new Extension(['png', 'txt']))->validate($file);
+        (new Mimetype(['image/png', 'text/plain']))->validate($file);
+
+        $this->expectException(Exception::class);
+
+        (new FileType('png', 'image/png'))
+            ->allow('txt', 'text/plain')
+            ->validate($file);
+    }
+
+    public function testSeveralExtensionsShareOneMimetype(): void
+    {
+        $validation = new FileType(['txt', 'text'], 'text/plain');
+
+        $validation->validate(new FileInfo($this->assetsDirectory . '/foo.txt', 'foo.txt'));
+        $validation->validate(new FileInfo($this->assetsDirectory . '/foo.txt', 'foo.text'));
+
+        $this->assertTrue(true);
+    }
+
+    public function testOneExtensionAcceptsSeveralMimetypes(): void
+    {
+        $validation = new FileType('txt', ['text/csv', 'text/plain']);
+
+        $validation->validate(new FileInfo($this->assetsDirectory . '/foo.txt', 'foo.txt'));
+
+        $this->assertTrue(true);
+    }
+
+    public function testRepeatedExtensionGainsMimetypesRatherThanReplacingThem(): void
+    {
+        $validation = (new FileType('txt', 'text/csv'))->allow('txt', 'text/plain');
+
+        $validation->validate(new FileInfo($this->assetsDirectory . '/foo.txt', 'foo.txt'));
+
+        $this->assertTrue(true);
+    }
+
+    public function testInputIsCaseFolded(): void
+    {
+        $validation = new FileType('TXT', 'TEXT/PLAIN');
+
+        $validation->validate(new FileInfo($this->assetsDirectory . '/foo.txt', 'foo.txt'));
+
+        $this->assertTrue(true);
+    }
+
+    /**
+     * `FileInfo::setExtension()` blanks an extension it cannot accept, so the file arrives here
+     * with nothing to pair against.
+     */
+    public function testFileWithNoExtensionIsRejected(): void
+    {
+        $this->expectException(Exception::class);
+        $this->expectExceptionMessage('Invalid file extension. Must be one of: png');
+
+        $file = new FileInfo($this->assetsDirectory . '/foo.png', 'evil.p-h-p');
+        $validation = new FileType('png', 'image/png');
+        $validation->validate($file);
+    }
+
+    /**
+     * @dataProvider providerEmptySides
+     *
+     * @param string|string[] $extensions
+     * @param string|string[] $mimetypes
+     */
+    public function testAnEmptySideIsRejected($extensions, $mimetypes): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+        $this->expectExceptionMessage('Expected at least one extension and one mimetype');
+
+        new FileType($extensions, $mimetypes);
+    }
+
+    /**
+     * @return array<string, array<int, string|string[]>>
+     */
+    public function providerEmptySides(): array
+    {
+        return [
+            'no extensions' => [[], 'image/png'],
+            'no mimetypes' => ['png', []],
+
+            /* `(array)''` is a list of one, so an empty string reaches the same misconfiguration
+               the guard exists to catch without tripping the count. It matters because
+               getMimetype() answers '' for a file it cannot read, so `FileType('png', '')`
+               would accept an unreadable avatar.png as a PNG. */
+            'empty mimetype' => ['png', ''],
+            'empty extension' => ['', 'image/png'],
+            'list of empty strings' => [['', ''], 'image/png'],
+            'whitespace only' => ['png', '   '],
+
+            /* A leading dot is all that is left of an extension once it is removed */
+            'dot only' => ['.', 'image/png'],
+        ];
+    }
+
+    /**
+     * `getExtension()` never carries a leading dot, so keeping one would pair the media type
+     * with an extension no file can have and reject every upload.
+     */
+    public function testExtensionsAcceptALeadingDot(): void
+    {
+        $validation = new FileType('.png', 'image/png');
+
+        $validation->validate(new FileInfo($this->assetsDirectory . '/foo.png', 'foo.png'));
+
+        $this->assertTrue(true);
+    }
+
+    /**
+     * The configured list is folded, so the value compared against it has to be folded too. The
+     * shipped FileInfo lowercases in getMimetype(); a custom FileInfoInterface need not.
+     */
+    public function testMimetypeFromTheFileIsCaseFolded(): void
+    {
+        $file = $this->getMockBuilder(FileInfo::class)
+            ->setConstructorArgs([$this->assetsDirectory . '/foo.png', 'foo.png'])
+            ->onlyMethods(['getMimetype'])
+            ->getMock();
+
+        $file->method('getMimetype')->willReturn('IMAGE/PNG');
+
+        (new FileType('png', 'image/png'))->validate($file);
+
+        $this->assertTrue(true);
+    }
+
+    /**
+     * An unreadable file reports no media type, which must not satisfy a pairing.
+     */
+    public function testFileWithNoDetectableMimetypeIsRejected(): void
+    {
+        $this->expectException(Exception::class);
+        $this->expectExceptionMessage('File contents do not match the "png" extension');
+
+        (new FileType('png', 'image/png'))->validate(new FileInfo('', 'avatar.png'));
+    }
+}