File uploads are protected by GlobalPostFileUploadGuard, a request filter that validates uploaded files before controller code runs. Its job is to reject dangerous uploads early using extension checks, MIME checks, magic-byte inspection, filename validation, and size limits.

Overview

When it runs

The filter returns immediately unless all of the following are true:

1. The request method is POST

   Non-POST requests are ignored by the guard.

2. The request actually contains uploaded files

   If $request->getFiles() is empty, the filter exits without doing anything.

3. Each uploaded file is valid enough to inspect

   Oversized uploads that fail at the PHP upload layer are still blocked and logged with a specific reason.

The filter also recurses through nested file input arrays, so it protects both single-file and multi-file form structures.

Allowed file types

The allowlist is defined through $allowedMimeMap. The filter resolves an expected MIME from the client extension and rejects any extension that does not map to an approved MIME.

Blocked extensions

The guard maintains a large denylist in $blockedExtensions to stop common executable, script, archive, config, and sensitive file types.

Multiple extensions are handled defensively. If a filename like invoice.php.pdf or report.jpg.js contains any blocked extension in its middle segments, the file is rejected.

Validation flow

Each uploaded file passes through this validation order:

1. Upload validity check

   If PHP reports an invalid upload and the error is a server/form size issue, the guard blocks immediately.

2. Filename safety check

   Rejects null bytes, path separators, and filenames longer than 255 characters.

3. Multiple-extension detection

   Rejects files that hide blocked extensions inside multi-part names.

4. Forbidden extension check

   Rejects uploads whose client extension is directly on the blocked list.

5. File size limit

   The hard application limit is 25 MB.

6. Real MIME detection

   Uses PHP finfo(FILEINFO_MIME_TYPE) on the temporary uploaded file.

7. Expected MIME resolution

   Maps the client extension to one expected MIME from the allowlist.

8. Magic byte validation

   Checks the actual file header against known signatures for supported formats.

9. Strict MIME match

   The detected MIME must match the expected MIME exactly; generic fallback MIME values are not accepted.

if ($request->getMethod() !== 'post') {
    return;
}

$files = $request->getFiles();
if (empty($files)) {
    return;
}

Magic bytes check

The guard performs deep header checks using $magicBytes for several formats:

There is also an scanForEmbeddedCode() method in the filter, but its invocation is currently commented out. The active protection path today is the filename, extension, MIME, and magic-byte validation sequence.

Route coverage

This guard is registered in two relevant places:

$routes->group("employeeRest", ["filter" => ['GlobalPostFileUploadGuard', 'ratelimit', 'appSignature', 'authJWT']], function ($routes) {
    // upload-related endpoints live here
});

Blocked response

When the filter rejects a file, it logs a critical event and immediately sends a JSON error response with HTTP 403.

{
  "status": "error",
  "message": "File upload rejected: Security policy violation. Reason: MIME-extension mismatch.",
  "debug": "MIME-extension mismatch"
}

The log entry includes the block reason, client IP, URI, input field, original filename, MIME, extension, and size.

Operational notes

1. Controller code never sees blocked files

   The filter sends the response directly and exits, so later controller logic does not run for rejected uploads.

2. Client extension alone is never trusted

   The extension is only used to resolve the expected MIME; the real file MIME and header still have to match.

3. 25 MB is the app-level limit

   Server-side PHP upload limits can still reject larger files earlier, and the filter explicitly handles that error path.

4. False positives are possible if MIME support differs by environment

   Because the check is strict, any environment mismatch in MIME detection can cause a block until the allowlist is updated deliberately.