# File uploads ## What this builds File uploads for a web app. The browser sends a file straight to storage, so large files never pass through the app's servers. The app checks what arrived, keeps files private, hands them out only to people allowed to see them, and deletes what nobody uses. Read `spekkr.inputs.json` first. A file is at most `max_file_mb` megabytes, of 1,000,000 bytes each, and one of `allowed_types`. `storage` says where files are kept. `image_previews` decides whether R8 exists and `scan_hook` whether R7 does. This spec needs the app to know who is signed in. It does not build sign-in. ## Out of scope - Uploads that resume after a dropped connection. - Editing, cropping or converting files. - A scanner for malware. R7 is the place to plug one in. ## Requirements Each requirement has an id. Tests name the id they cover. ### R1. Start an upload - The browser sends the file's name, size and type to `POST /api/uploads`. - The app refuses a size over `max_file_mb` megabytes, a size of zero and a type not in `allowed_types`, each with its own message. - Otherwise it records a pending file and answers with an address to send the file to. The address works for 15 minutes, for that size and that type only. - The place the file is stored under is random. It never contains the file's name or anything else the uploader chose. - A person can start at most 20 uploads a minute. - The app refuses to start if `allowed_types` contains `image/svg+xml`, `text/html` or any type that is not in the table in `design.md`. Accept when: a file of the stated size and type can be sent to the address, a larger file or another type is refused by storage itself, and the address stops working after 15 minutes. ### R2. Finish and check - The browser calls `POST /api/uploads/ID/complete` when the file is sent. - The app looks at the stored file. Its size must equal the size that was stated, and its first bytes must match the stated type, by the table in `design.md`. - A file that fails is deleted from storage and marked rejected, and the browser gets the reason. - A file that passes becomes ready, or goes to R7 if `scan_hook` is on. Accept when: a text file named `photo.png` and stated as `image/png` is rejected and gone from storage, and a real PNG passes. ### R3. Download - Stored files are never public. Nothing can be fetched from storage without a signed address from the app. - `GET /files/ID` asks one function, `can_read(user, file)`, and answers 404 when it says no. As built, only the uploader can read a file. The person's app replaces the function. - When it says yes, the answer is a redirect to a signed address that works for 5 minutes. - Files are sent as attachments, with the cleaned name from R4. Only PNG, JPEG, GIF, WebP and PDF may be shown in the browser instead, and only when asked for with `?inline=1`. - Every file is served with `X-Content-Type-Options: nosniff` and the type that was checked in R2. Accept when: a person who may not read a file gets 404, the signed address stops working after 5 minutes, and no file can be fetched from storage without one. ### R4. File names - The name the uploader gave is kept for display and for downloads only. - It is cleaned first: path separators and control characters are removed, leading dots are removed, and it is cut to 200 characters with its extension kept. - A name that is empty after cleaning becomes `file` plus the extension for its type. Accept when: `../../etc/passwd`, a name with a newline in it and a name of 500 characters each come out as given in the table in `design.md`. ### R5. Attach, and delete what is not used - App code calls `attach(file, record)` to tie a ready file to something in the app, and `detach` to untie it. - A ready file that is still not attached after 24 hours is deleted. So is a pending upload that was never finished. - Deleting a record deletes its files. A file is deleted from storage first and from the database after, so a failure leaves a row to retry from, never a stored file that nothing points to. Accept when: an unattached file is gone after 24 hours, an attached one stays, and a deletion that fails halfway is completed by the next clean-up run. ### R6. Files on local disk Only if `storage` is `local_disk`. - The address from R1 is a route on the app itself. It carries a signed token with the file's id, size, type and expiry. - The route writes the body to disk as it arrives and stops with status 413 as soon as more bytes than stated have come in. - Files live in a folder outside anything the web server serves. A file's path is built from its random key and nothing else. - Downloads are sent by the app, after the same check as R3. Accept when: a body one byte longer than stated is refused and leaves no file, and no request can read or write outside the storage folder. ### R7. Hold files until they are scanned Only if `scan_hook` is on. - A file that passes R2 is marked scanning and handed to one function, `scan(file)`, which answers clean or infected. As built it answers clean. - A scanning file cannot be downloaded or attached. An infected file is deleted from storage and marked rejected. Accept when: with a test scanner that flags one file, that file is never downloadable and the others become ready. ### R8. Previews of images Only if `image_previews` is on. - For PNG, JPEG and WebP files the app makes a preview, at most 512 pixels on its long side, encoded afresh so nothing hidden in the original is carried over. - An image of more than 50 million pixels is not decoded. It has no preview. - A preview is private in the same way as its file. Accept when: a 4000 by 3000 pixel image gets a 512 by 384 preview with no location data, and an image that states 100,000 by 100,000 pixels is not decoded. ### R9. The upload control - A control that takes files by picking or by dropping, shows progress for each file, lets an upload be cancelled, and shows errors in words. - It checks size and type before sending, to save the person time. The checks on the server are the ones that count. Accept when: the control works with a keyboard alone and at a 360 pixel wide screen, and a file that is too large is refused before any of it is sent. ## Definition of done - Every acceptance check above has an automated test, and all tests pass. Tests run against a local stand-in for storage, with no outside network. - A README explains how to set the secrets, how to replace `can_read`, and how to run the tests.