Resolve findings from the security hardening audit

[jakejackson1]

The 4.0.0 security hardening release.

Storage stages each upload to a temporary file and moves it into place rather than writing to the destination directly, applies a default extension deny-list, and refuses traversal, dotfiles, control and bidi characters, Windows device names and symlinked destinations. Validation\FileType pairs an extension with the media type sniffed from the contents. Filenames and extensions are sanitized, including in the strings getErrors() returns. Stored files get mode 0640, and upload() now requires something to validate against.

373 tests, green on all eight supported PHP versions. PHPStan level 9 over src and tests.

Breaking changes

UPGRADE.md is the step-by-step guide. The ones most likely to bite:

• The deny-list refuses a file whose own extension is on it, markup such as .html and .svg included. Only the last dot-separated component counts as an extension, so release.config.zip is fine and release.config is not. A deny-list entry containing dots is now split into components, so blockExtensions(['tar.gz']) blocks tar and gz where it previously blocked nothing.

• blockExtensions() takes a required, non-empty list. No argument no longer means the default set, and [] throws. allowAnyExtension() is the only way to turn the deny-list off, so a missing config value can't silently disable it.

• Two size units changed meaning. '5MB' parsed as 5 bytes and now parses as 5 MiB, so any KB/MB/GB limit becomes much larger. A unit outside B/K/M/G now throws rather than being read as bytes — '1T' was a one-byte bound that rejected everything while reading as a generous one. Check every Validation\Size bound.

• Four developer errors changed exception type, all previously Upload\Exception — the type isValid() catches and formats into getErrors(), so a typo in your own source reached the end user as a rejected upload. upload() with no validations and createFromFactory() with a bad factory now throw \LogicException; getHash() with an unsupported algorithm throws \InvalidArgumentException; __call() for an unknown method throws \BadMethodCallException. isValid() also re-throws \LogicException from a validator rather than absorbing it. Code catching Upload\Exception specifically around upload() needs \LogicException too. The catch (\Exception $e) in the README is unaffected.

• The storage collision message changed. 'File already exists' now names the file in the way, since sanitizing is many-to-one and the old wording couldn't say which name collided. Update anything matching the old string.

• FileInfoInterface's three setters no longer declare a return type. They declared : FileInfo, the concrete class, so an implementation that didn't extend FileInfo compiled and then raised a TypeError on the first setter call — the interface was only implementable by subclasses of the class it was meant to abstract. If yours declares : FileInfo to match, delete it or the TypeError is unchanged. StorageInterface::upload()'s return value is specified for the first time as well: a locator your storage defines, which is why the README's unlink() rollback suits FileSystem and not necessarily yours.

New: GravityPdf\Upload\Filename

Filename rules are applied at two altitudes with two different outcomes — FileInfo rewrites a client-supplied name, Storage\FileSystem refuses one that still breaks a rule, because a FileInfoInterface is a public extension point and inventing a filename isn't storage's job.

That split is deliberate; the two layers disagreeing about what the rules are was not. Both control-character filters covered C0 alone, and each had to be found and fixed separately. Filename declares MAX_LENGTH, MAX_EXTENSION_LENGTH, CONTROL_CHARACTERS, BIDI_CONTROLS and RESERVED_WINDOWS_NAMES once and owns the operations both layers share, including the dot-splitting that decides where a component ends. Neither caller splits a filename for itself any more.

Review passes

Five passes over the work. Every fix carries a test verified to fail against the code before it.

Audit — seven reviewers, 20 findings and 4 untested failure branches. The two that mattered: the README claimed beforeUpload couldn't dodge validation, when it runs after validation so a name set there is never validated; and the FileInfoInterface setters above.

Cleanup — reuse, simplification, layering. Found a docblock of mine claiming blockExtensions()'s polarity "cannot change now" when the method is new and unreleased, two exception types still contradicting the taxonomy the audit had just set, and setNameWithExtension() re-fitting a name the next line overwrote at 34% of FileInfo construction cost.

Method audit — a naming and suitability pass over the 40 methods this release adds, which turned up a deny-list bypass. The extension and reserved-name checks ran inside resolveFilename(), which is protected and documented as the seam for changing how names are chosen, so a subclass overriding it dropped both refusals while saying nothing about extensions:

FileSystem   refused Files with the extension "php" cannot be stored
MyStorage    STORED  shell.php

Both checks now run in upload() against whatever the seam returns, both are private, and a test pins it. The same pass renamed methods that misdescribed themselves — getUploadedFiles() → getUploadedLocators(), normalizeExtension() → acceptExtension(), Filename::sanitize() → sanitizeName(), and seven more — and dropped ten methods to private. Nothing renamed had ever shipped.

Documentation — every claim in the README, changelog and upgrade guide executed against the 3.1.0 baseline rather than reasoned about. It caught a regression the cleanup pass introduced: the mbstring gate had been collapsed from function_exists() to extension_loaded('mbstring') on the grounds that five checks were "one fact". They aren't — symfony/polyfill-mbstring is userland, defines every mb_* function and registers no extension, so every polyfilled install would have silently skipped the UTF-8 repair while three documents promised the polyfill works. It also found three changelog claims that were false about 3.1.0, four describing fixes to code that never shipped, and a blank line that broke the FileInfo API table.

Prose. A final pass over UPGRADE.md, the changelog's 4.0.0 section and the README, which were burying each instruction under the reasoning for it and, in the changelog's case, running a paragraph per bullet where that file's own 3.0.0 and 2.0.0 sections use one terse line. Roughly a quarter shorter across the three, with every backtick-quoted identifier diffed old against new to catch anything lost in the compression. It also turned up a rendering bug: the unescaped | in the README's list of Windows-disallowed characters was splitting that table cell into a phantom column, since GFM does not exempt code spans from pipe parsing.