File uploads

Uploads that go straight from the browser to your storage, with size and type checks, private downloads and nothing left orphaned.

This is an app part spec on Spekkr, published by vex. It is listed with the other specs. Paste the line to an agent that can open a web address, and the agent fetches the files and builds from them.

Spec
vex/file-uploads
Version
0.1.2
Published by
vex
Updated
15 Nov 2026

Build this spec

Build the spec at https://spekkr.com/vex/file-uploads/start.md.

Paste this to your AI agent. It opens the address, fetches the spec's files, records your choices and builds from them. Nothing to install, no account.

Published by vex.

What does the result look like?

File uploads: strongroom ready to sendFile uploads: strongroom queueFile uploads: strongroom mobileFile uploads: strongroom sign in

What can I customize?

Database
Where files are kept A bucket that speaks the S3 API, or a folder on the server.

Your choices go into the line you copy. Anything else is yours to edit, but it leaves the tested path.

What do I get?

  • spec.md Requirements and acceptance criteria.

    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.
    # 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.
    

    Open spec.md as plain text

  • design.md Data model, rules and flows.

    Design

    This file fixes the parts that are easy to get wrong. Choose the language and framework that fit the person's project; nothing here depends on them.

    Data model

    Use the database in the database input.

    TableColumns
    filesid, uploader_id, storage_key (unique), preview_key, name, media_type, size, state, reject_reason, created_at, ready_at, deleted_at
    file_attachmentsfile_id, record_type, record_id; primary key on all three

    state is one of pending, scanning, ready, rejected and deleting.

    Types and their first bytes

    A type in the allowed_types input must be in this table. Bytes are in hexadecimal.

    TypeExtensionThe file starts with
    image/png.png89 50 4E 47 0D 0A 1A 0A
    image/jpeg.jpgFF D8 FF
    image/gif.gif47 49 46 38 37 61 or 47 49 46 38 39 61
    image/webp.webp52 49 46 46, then any 4 bytes, then 57 45 42 50
    application/pdf.pdf25 50 44 46 2D
    application/zip.zip50 4B 03 04
    text/plain.txtNo fixed start. The first 4,096 bytes must be valid UTF-8 with no zero byte.
    text/csv.csvThe same rule as text/plain.

    Office documents are zip files and cannot be told apart by their first bytes. To allow them, add their types here with the zip start, and serve them as attachments only.

    The signed address

    With storage set to s3_compatible, the address in R1 is a presigned PUT with Content-Length and Content-Type among the signed headers, so storage refuses any other size or type. Read only the first 16 bytes back for R2, with a range request, and the size from the object's metadata.

    The bucket blocks all public access. Its CORS rule allows PUT from the app's own origin only.

    Names

    Name givenName kept
    ../../etc/passwdetcpasswd
    report then a newline then .pdfreport.pdf
    .htaccesshtaccess
    500 letters a then .png196 letters a then .png
    An empty name, type image/pngfile.png

    In the Content-Disposition header, send the name both ways: an ASCII fallback with anything else replaced by _, and filename*=UTF-8'' with the real name percent-encoded.

    Deleting

    1. Set state to deleting.
    2. Delete the stored file and its preview. A file that is already gone counts as deleted.
    3. Delete the row.

    A clean-up run once an hour starts this for unattached and unfinished files older than 24 hours, and finishes it for rows left in deleting.

    Configuration

    SecretPurpose
    DATABASE_URLConnection string for the chosen database.
    STORAGE_ENDPOINTAddress of the storage service. Not needed for local_disk.
    STORAGE_BUCKETName of the bucket. Not needed for local_disk.
    STORAGE_ACCESS_KEY_IDStorage credentials. Not needed for local_disk.
    STORAGE_SECRET_ACCESS_KEYStorage credentials. Not needed for local_disk.

    Who is signed in

    The spec reaches the app's sign-in through one function, current_user(request). It answers with the person's id, and says whether they are an administrator where this spec asks. In the person's app it reads their session.

    When there is no app yet, build this stand-in and nothing more: a page that lists two seeded people, one of them an administrator, with a button for each that sets a signed cookie naming them. The stand-in refuses to start in production.

    What this spec leaves to you

    Where this spec names something, use that name, so that two builds of it agree. Where it does not, the choice is yours. List what you chose in the README.

    # Design
    
    This file fixes the parts that are easy to get wrong. Choose the language and
    framework that fit the person's project; nothing here depends on them.
    
    ## Data model
    
    Use the database in the `database` input.
    
    | Table | Columns |
    | --- | --- |
    | `files` | `id`, `uploader_id`, `storage_key` (unique), `preview_key`, `name`, `media_type`, `size`, `state`, `reject_reason`, `created_at`, `ready_at`, `deleted_at` |
    | `file_attachments` | `file_id`, `record_type`, `record_id`; primary key on all three |
    
    `state` is one of `pending`, `scanning`, `ready`, `rejected` and `deleting`.
    
    ## Types and their first bytes
    
    A type in the `allowed_types` input must be in this table. Bytes are in
    hexadecimal.
    
    | Type | Extension | The file starts with |
    | --- | --- | --- |
    | `image/png` | `.png` | `89 50 4E 47 0D 0A 1A 0A` |
    | `image/jpeg` | `.jpg` | `FF D8 FF` |
    | `image/gif` | `.gif` | `47 49 46 38 37 61` or `47 49 46 38 39 61` |
    | `image/webp` | `.webp` | `52 49 46 46`, then any 4 bytes, then `57 45 42 50` |
    | `application/pdf` | `.pdf` | `25 50 44 46 2D` |
    | `application/zip` | `.zip` | `50 4B 03 04` |
    | `text/plain` | `.txt` | No fixed start. The first 4,096 bytes must be valid UTF-8 with no zero byte. |
    | `text/csv` | `.csv` | The same rule as `text/plain`. |
    
    Office documents are zip files and cannot be told apart by their first bytes. To
    allow them, add their types here with the zip start, and serve them as attachments
    only.
    
    ## The signed address
    
    With `storage` set to `s3_compatible`, the address in R1 is a presigned `PUT` with
    `Content-Length` and `Content-Type` among the signed headers, so storage refuses
    any other size or type. Read only the first 16 bytes back for R2, with a range
    request, and the size from the object's metadata.
    
    The bucket blocks all public access. Its CORS rule allows `PUT` from the app's own
    origin only.
    
    ## Names
    
    | Name given | Name kept |
    | --- | --- |
    | `../../etc/passwd` | `etcpasswd` |
    | `report` then a newline then `.pdf` | `report.pdf` |
    | `.htaccess` | `htaccess` |
    | 500 letters `a` then `.png` | 196 letters `a` then `.png` |
    | An empty name, type `image/png` | `file.png` |
    
    In the `Content-Disposition` header, send the name both ways: an ASCII fallback
    with anything else replaced by `_`, and `filename*=UTF-8''` with the real name
    percent-encoded.
    
    ## Deleting
    
    1. Set `state` to `deleting`.
    2. Delete the stored file and its preview. A file that is already gone counts as
       deleted.
    3. Delete the row.
    
    A clean-up run once an hour starts this for unattached and unfinished files older
    than 24 hours, and finishes it for rows left in `deleting`.
    
    ## Configuration
    
    | Secret | Purpose |
    | --- | --- |
    | `DATABASE_URL` | Connection string for the chosen database. |
    | `STORAGE_ENDPOINT` | Address of the storage service. Not needed for `local_disk`. |
    | `STORAGE_BUCKET` | Name of the bucket. Not needed for `local_disk`. |
    | `STORAGE_ACCESS_KEY_ID` | Storage credentials. Not needed for `local_disk`. |
    | `STORAGE_SECRET_ACCESS_KEY` | Storage credentials. Not needed for `local_disk`. |
    
    ## Who is signed in
    
    The spec reaches the app's sign-in through one function, `current_user(request)`.
    It answers with the person's id, and says whether they are an administrator where
    this spec asks. In the person's app it reads their session.
    
    When there is no app yet, build this stand-in and nothing more: a page that lists
    two seeded people, one of them an administrator, with a button for each that sets
    a signed cookie naming them. The stand-in refuses to start in production.
    
    ## What this spec leaves to you
    
    Where this spec names something, use that name, so that two builds of it agree.
    Where it does not, the choice is yours. List what you chose in the README.
    

    Open design.md as plain text

  • tasks.md Build tasks in order, each with a check.

    Tasks

    Work in order. Finish a task's check before starting the next.

    1. Set up. Add the tables in design.md and a local stand-in for storage that tests can use. If there is no app yet, build the smallest one: a signed-in user. Check: migrations run from empty and a test stores and reads back one object.
    2. Types and names (R4). Two pure functions: one from the first bytes to a type, one that cleans a name. Check: tests cover every row of both tables in design.md.
    3. Start an upload (R1). Use the max_file_mb and allowed_types inputs. Check: the R1 acceptance tests pass.
    4. Finish and check (R2). Check: the R2 acceptance tests pass.
    5. Local disk (R6). Only if storage is local_disk. Check: the R6 acceptance tests pass.
    6. Download (R3). Check: the R3 acceptance tests pass.
    7. Attach and clean up (R5). With a clock that tests can set. Check: the R5 acceptance tests pass.
    8. Scan hook (R7). Only if scan_hook is on. Check: the R7 acceptance tests pass.
    9. Previews (R8). Only if image_previews is on. Check: the R8 acceptance tests pass.
    10. The upload control (R9). Check: the control can be used with a keyboard alone and at 360 pixels wide.
    11. Finish. Write the README and run the whole test suite. Check: every item under "Definition of done" in spec.md is true.
    # Tasks
    
    Work in order. Finish a task's check before starting the next.
    
    1. **Set up.** Add the tables in `design.md` and a local stand-in for storage that
       tests can use. If there is no app yet, build the smallest one: a signed-in user.
       Check: migrations run from empty and a test stores and reads back one object.
    
    2. **Types and names (R4).** Two pure functions: one from the first bytes to a
       type, one that cleans a name.
       Check: tests cover every row of both tables in `design.md`.
    
    3. **Start an upload (R1).** Use the `max_file_mb` and `allowed_types` inputs.
       Check: the R1 acceptance tests pass.
    
    4. **Finish and check (R2).**
       Check: the R2 acceptance tests pass.
    
    5. **Local disk (R6).** Only if `storage` is `local_disk`.
       Check: the R6 acceptance tests pass.
    
    6. **Download (R3).**
       Check: the R3 acceptance tests pass.
    
    7. **Attach and clean up (R5).** With a clock that tests can set.
       Check: the R5 acceptance tests pass.
    
    8. **Scan hook (R7).** Only if `scan_hook` is on.
       Check: the R7 acceptance tests pass.
    
    9. **Previews (R8).** Only if `image_previews` is on.
       Check: the R8 acceptance tests pass.
    
    10. **The upload control (R9).**
        Check: the control can be used with a keyboard alone and at 360 pixels wide.
    
    11. **Finish.** Write the README and run the whole test suite.
        Check: every item under "Definition of done" in `spec.md` is true.
    

    Open tasks.md as plain text

Is it for me?

Platforms
web, backend

What does it need?

Accounts
A storage bucket that speaks the S3 API, unless files are kept on local disk
Agent permissions
shell, network
Secrets it reads
DATABASE_URL STORAGE_ENDPOINT STORAGE_BUCKET STORAGE_ACCESS_KEY_ID STORAGE_SECRET_ACCESS_KEY

What changed?

  • 0.1.215 Nov 2026Names what it builds.
  • 0.1.114 Nov 2026Says "person" where it said "buyer".
  • 0.1.014 Nov 2026Moved from dwrtz/file-uploads.

For agents: start.md says how to build this spec, spec.json holds everything on this page, and bundle.tar.gz holds its files.