Refuse the extension a whitespace-only name hid

[jakejackson1]

Description

Three findings from a security audit of src/.

1. Deny-list bypass — a whitespace-only first component swallowed the extension

Filename::extensionComponents() normalized before it dropped the first dot-separated field:

return array_slice(self::normalizeComponents($filename), 1);

normalizeComponents() drops a field that is nothing but spaces, so " .php" normalized to ['php'] and the array_slice() took that for the name. FileSystem::refuseBlockedExtensions() got an empty list and wrote the file:

STORED   " .php"       -> …/uploads/ .php
STORED   " .htaccess"  -> …/uploads/ .htaccess
STORED   " .svg"       -> …/uploads/ .svg

" .php" is a live PHP file — Apache's mod_mime splits the name on dots and maps the php field to the handler, and nginx's location ~ \.php$ matches it.

None of the other refusals covered it: refuseUnsafeName() checks for a leading dot, not a leading space, and deviceComponent(" .php") trims to ''.

It splits with a bounded explode() now, so the first field is dropped whatever it holds — the field deviceComponent() takes:

$parts = explode('.', $filename, 2);

return isset($parts[1]) ? self::normalizeComponents($parts[1]) : [];

Not reachable with the shipped classes. FileInfo::setName() trims '.-_ ' and rewrites interior dots, so its output never has an empty first field — " .php" in becomes unnamed-file.php out, which is refused. It is reachable from a FileInfoInterface of your own or a resolveFilename() override, which is the case those three refusals exist for and what the README promises they cover.

FileSystemTest::testOverridingTheNamingSeamDoesNotDropTheNameRefusals() shows the empty-component drop was already known for a leading dot and compensated for in refuseUnsafeName(). The compensation just didn't reach a leading space.

2. Nine deny-list additions with a documented execution path

asis (Apache mod_asis serves the file as a complete HTTP response, so the uploader writes its Content-Type and Location), erb, rhtml (Ruby templates), htr, idc, printer (legacy IIS ISAPI), cfm, cfml, cfc (ColdFusion). EXECUTABLE_EXTENSIONS goes 59 → 68.

3. getErrors() entries were unbounded in length

FileList::describeKey() cut a key at MAX_LENGTH; File::renderMessage() applied no cap, so a validation of your own with a runaway message floods whatever renders the list. Filename::sanitizeForDisplay() now bounds its result at a new MAX_DISPLAY_LENGTH (2048) — not MAX_LENGTH, because a message naming a long allow-list back to the developer is legitimately longer than a filename. The bound is a parameter, so describeKey() names the 255 a field name gets rather than cutting for itself.

Documentation kept in step

Fixing (1) falsified a rationale carried in four places — refuseUnsafeName()'s docblock, the test pinning it, CHANGELOG.md and CLAUDE.md all said the leading-dot refusal exists because extensionComponents() cannot see a dotfile's extension. It can now: .htaccess splits to ['htaccess']. The refusal still earns its place for the other half of the reason — a deny-list of extensions does not cover .env — and all four now say that.

The README's sanitizeForDisplay() row said "No length limit", and its deny-list prose carried a hand-counted "The first ten groups" that nothing verifies (the pinning test scrapes backticked words, not group labels). Both corrected.

4.0.0 is unreleased, so the bypass was never in a tagged release and gets no CHANGELOG.md entry of its own; the executable-extension count and the getErrors() sanitizing bullet were updated in place.

Testing instructions

composer phpunit        # 565 tests, 1 skip (the cross-file-system one)
composer phpstan        # level 9, src + tests
composer lint
composer check-syntax
composer i18n:pot       # regenerates with no diff
composer psr7-readme
composer translator-readme

vendor/bin/phpunit --exclude-group mbstring also passes, and git archive HEAD | tar -t | sed 's:/.*::' | sort -u is unchanged.

New regression coverage:

• FilenameTest::provideNamesToSplit() — 9 cases on the splitter, including the whitespace-only name
• FileSystemTest::providerNamesThatHideABlockedExtension() — ' .php' through a full upload()
• FilenameTest::provideTextToSanitize() — the display bound, and that it is not a filename budget
• FilenameTest::testSanitizeTextRepairsASequenceTheBoundSplits() — the cut is a byte cut, so the UTF-8 repair runs after it
• FileTest::testARunawayValidationMessageIsBounded() — a validator throwing 100 KB yields a 2048-byte getErrors() entry

To reproduce the original bypass, check out main and store a FileInfoInterface whose getNameWithExtension() returns " .php".

🤖 Generated with Claude Code