Implement secure file uploads

File uploads are a classic source of breaches and outages. Typical failures: trusting the file extension or the client's Content-Type, so an HTML or SVG file with script is served from the app's own domain; using the user's file name in the storage path (path traversal, overwrites, leaking names); streaming large files through the app server until it runs out of memory; signed upload URLs with no size limit or a long expiry; files that are uploaded but never attached to anything, piling up forever; and serving uploads publicly when they should be private. A sound design uploads straight to object storage with short-lived, constrained credentials, validates the actual bytes after upload, quarantines until scanned, and only then makes the file available.

Implement file uploads for this use case:

Storage: s3-compatible Only if [STACK] is given: Stack: [STACK] Only if [MAX_SIZE] is given: Maximum size: [MAX_SIZE]

1. Read the repo's storage client, auth, models, background jobs and config, and reuse them. If the allowed file types, maximum size or who may read the files are not clear from the use case, ask before implementing.
2. Implement this flow:
3. Request: the client asks the API for an upload, sending the intended file name, size and declared type. The API checks authorization, the allowed type list and the size, creates an upload record in a pending state, and generates a random object key under a quarantine prefix (for example pending/<uuid>); never use the user's file name in the key.
4. Upload: the API returns a short-lived signed URL (minutes, not hours) that is constrained as tightly as the storage allows: a presigned POST policy with a content-length range and fixed content type for S3-compatible stores, or the equivalent conditions on other providers. For files above the provider's single-request limit, or large files on mobile networks, use multipart or resumable uploads.
5. Confirm: the client tells the API the upload finished (or a storage event notifies it). The API checks the object exists and its real size matches.
6. Validate and scan: a background job reads the file's magic bytes to detect the real type and rejects mismatches, enforces content rules (image dimensions, page count, CSV row limit), calls a malware-scan hook (an interface with a no-op implementation for development and a place to plug in a scanner), and for images re-encodes them to strip metadata such as GPS location and neutralise polyglot files.
7. Promote: clean files move to the final prefix and the record becomes available; failed files are deleted or kept in quarantine with the reason, and the user gets a clear error.
8. Serve files safely: private by default with short-lived signed download URLs after an authorization check; Content-Disposition: attachment for anything that is not a safe inline type; the correct Content-Type plus X-Content-Type-Options: nosniff; and ideally a separate domain for user content. Store the original file name only as sanitised metadata for display.
9. Clean up orphans: a storage lifecycle rule that expires objects under the pending prefix after a day or so, plus a scheduled job that removes pending records with no object and objects whose owning record was deleted.
10. Configure CORS on the bucket for the web origin only, with just the methods and headers the upload needs.
11. Write tests: the request endpoint rejects disallowed types, oversize files and unauthorised users; the signed URL has the expected constraints and expiry; the validation job rejects a file whose magic bytes do not match its declared type; a scan failure leaves the file unavailable; promotion makes it available; download requires authorization; and cleanup removes expired pending uploads. Use a local emulator or a fake storage client; no real cloud calls.
12. Run the tests and linter and report the real results.

• Never accept SVG, HTML or other active content for inline display unless the use case requires it; if it does, say how it will be sanitised or served from an isolated domain.
• Never trust the client's file name, extension or Content-Type for security decisions.
• Never make the bucket public to make uploads work.
• Do not claim a malware scanner is integrated if only the hook exists; say what is left to wire up.
• Do only what was asked. If you notice something else worth changing, mention it in one line at the end instead of changing it.
• Keep the change as small as it can be while still being correct.
• Before saying the work is done, run the check that proves it (tests, build, type check or the command the user gave) and report the real result.
• If you could not run a check, say so plainly and say which one.

Flow

A Mermaid sequence diagram of request, upload, confirm, scan, promote and download.

Changes

One line per file.

Security checks

Table: threat, control, where it is implemented.

Tests

One line per test and the real result of the run.

Configuration

Allowed types, size limits, URL expiries, prefixes, lifecycle rule and CORS settings.

Operational notes

What to monitor (quarantine backlog, rejection rate, scan failures) and what is still to wire up.