Handle file uploads and downloads safely
An upload is untrusted input that is large, binary, and often stored for years. Limit it
before you read it, verify what it really is, write it under a name you chose, atomically,
in a place that cannot execute, and serve it back with headers that stop the browser
guessing. Source: OWASP File Upload Cheat Sheet; OWASP ASVS 5 V5 (file handling).
Steps
- Use the repo's storage and upload path. Object storage with presigned URLs, a
local store behind an abstraction, or existing multipart middleware. Call
search_lore for bucket layout, key naming and size limits. Do not add a second
storage mechanism.
- Authorise and limit before reading. Check the caller may upload here (the
security-authz skill) and that the form is CSRF-protected if cookie-authenticated.
Enforce a maximum body size at the edge (proxy and framework), a maximum part count,
and a request timeout; reject with 413 without buffering. Stream to storage; never
hold a whole file in memory. For presigned uploads, sign the exact key,
Content-Type and size limit (a content-length-range POST-policy condition, or a
signed Content-Length for PUT), with a short expiry.
- Validate content, not labels. Allow-list extensions (after normalising case and
rejecting double extensions like
x.jpg.php, NUL bytes and :), check the declared
Content-Type against the allow-list, then detect the real type from the bytes
(magic numbers) and reject any mismatch. None of these alone is sufficient.
- Defuse the dangerous formats. Images: cap pixel dimensions before decoding
(decompression bombs), then decode and re-encode to strip metadata and payloads.
Archives: cap total uncompressed size and entry count, and reject entries whose
resolved path escapes the target directory (zip slip). SVG, HTML and XML are active
content: refuse them, sanitise them, or serve them only as attachments; parse XML with
external entities disabled (XXE). CSV/XLSX imports: cap rows and cell size, treat every
cell as untrusted text, and on export prefix cells starting with
=, +, -, @,
tab or CR with ' (formula injection).
- Generate the storage key; never trust the filename. Key = random id (UUID) plus
an extension derived from the detected type. Keep the original name only as
sanitised display metadata (length-capped, no path separators, no leading dot).
- Write atomically and collision-free. Concurrent uploads are normal. Write to a
unique temporary key (random suffix, never a timestamp or the user's name), then
rename/commit to the final key; object storage
PUT is already atomic per key. Insert
the metadata row in the same transaction that marks the file available, or use a
pending → available status so a half-written file is never served. Replacing a file
(a new avatar) writes a new key and swaps the pointer with a conditional update
(WHERE version = ?); it never overwrites bytes in place. Orphaned temp objects are
swept by a job (the scheduled-jobs skill).
- Store where nothing executes. Object storage or a directory outside the web root,
no execute permission, no per-directory config overrides; private by default and
access-checked on every read.
- Serve safely. Presigned GET with a short expiry, or an authenticated route that
sets
Content-Disposition: attachment for anything not meant to render inline, the
stored detected Content-Type, X-Content-Type-Options: nosniff, and ideally a
separate cookieless origin with a restrictive CSP (default-src 'none') so a
malicious file cannot run in the app's origin.
- Scan and quarantine where the repo requires it (malware scan, CDR, moderation)
asynchronously through a job (the
background-jobs skill); the file stays
unavailable until cleared.
Tests (one per behaviour, each exercising it for real)
- Oversize body rejected with
413 before the handler reads it; part-count cap enforced.
- Extension/type mismatch, double extension, and a renamed executable are rejected.
- Traversal filenames (
../../x, ..\\x, NUL) never reach the storage key.
- Valid upload is stored under a generated key and its metadata row exists.
- Concurrency: N (≥ 20) parallel uploads of the same filename by the same user all
succeed with distinct keys, no
500, no truncated or cross-wired bytes (compare
hashes). Two concurrent replacements of the same avatar leave exactly one winner and
no orphaned pointer. Build it with the concurrency-and-async skill's step 9 recipe.
- Failure: an upload aborted mid-stream leaves no
available row and no file served.
- Download headers are exact; another user's file is refused (
403/404).
- Import caps rows; export formula-prefixes dangerous cells; zip-slip entry rejected.
Done when
Every test above that the ticket's surface touches passes, and each acceptance
criterion has evidence recorded via the record-evidence skill (the command and its
passing output, not prose).
Review checklist
Capture lore
This skill is one of the places durable, reusable knowledge naturally surfaces:
While placing storage you learn the bucket layout, the size limits and the separate origin user content is served from. That kind of fact is lore. Capture it via the lore-capture
protocol in your brief (CLAUDE.factory.md, step 11 "Memory contribution"):
call the Memory MCP suggest_lore once at the close of your work — reusable
conventions, gotchas, decisions, and boundaries only, never per-ticket trivia.
1---2name: file-uploads3description: Use when a ticket lets users send files — avatars, documents, CSV imports, attachments — or serves them back, and the path must be safe against oversized, malicious, or mis-typed content, store files outside the web root or in object storage, and never trust the client's filename or content type. Invoke for "let users upload X", "add an import", "serve the attachment", or any multipart or presigned-URL work.4stack: [node, python, go, java, rust, csharp, kotlin, ruby, react, web]5area: backend6metadata:7 source: https://skillmd.com/skills/tmj-90/file-uploads8---910# Handle file uploads and downloads safely1112An upload is untrusted input that is large, binary, and often stored for years. Limit it13before you read it, verify what it really is, write it under a name you chose, atomically,14in a place that cannot execute, and serve it back with headers that stop the browser15guessing. Source: OWASP File Upload Cheat Sheet; OWASP ASVS 5 V5 (file handling).1617## Steps18191. **Use the repo's storage and upload path.** Object storage with presigned URLs, a20 local store behind an abstraction, or existing multipart middleware. Call21 `search_lore` for bucket layout, key naming and size limits. Do not add a second22 storage mechanism.232. **Authorise and limit before reading.** Check the caller may upload here (the24 `security-authz` skill) and that the form is CSRF-protected if cookie-authenticated.25 Enforce a maximum body size at the edge (proxy and framework), a maximum part count,26 and a request timeout; reject with `413` without buffering. Stream to storage; never27 hold a whole file in memory. For presigned uploads, sign the exact key,28 `Content-Type` and size limit (a `content-length-range` POST-policy condition, or a29 signed `Content-Length` for PUT), with a short expiry.303. **Validate content, not labels.** Allow-list extensions (after normalising case and31 rejecting double extensions like `x.jpg.php`, NUL bytes and `:`), check the declared32 `Content-Type` against the allow-list, then detect the real type from the bytes33 (magic numbers) and reject any mismatch. None of these alone is sufficient.344. **Defuse the dangerous formats.** Images: cap pixel dimensions before decoding35 (decompression bombs), then decode and re-encode to strip metadata and payloads.36 Archives: cap total uncompressed size and entry count, and reject entries whose37 resolved path escapes the target directory (zip slip). SVG, HTML and XML are active38 content: refuse them, sanitise them, or serve them only as attachments; parse XML with39 external entities disabled (XXE). CSV/XLSX imports: cap rows and cell size, treat every40 cell as untrusted text, and on export prefix cells starting with `=`, `+`, `-`, `@`,41 tab or CR with `'` (formula injection).425. **Generate the storage key; never trust the filename.** Key = random id (UUID) plus43 an extension derived from the detected type. Keep the original name only as44 sanitised display metadata (length-capped, no path separators, no leading dot).456. **Write atomically and collision-free.** Concurrent uploads are normal. Write to a46 unique temporary key (random suffix, never a timestamp or the user's name), then47 rename/commit to the final key; object storage `PUT` is already atomic per key. Insert48 the metadata row in the same transaction that marks the file available, or use a49 `pending → available` status so a half-written file is never served. Replacing a file50 (a new avatar) writes a new key and swaps the pointer with a conditional update51 (`WHERE version = ?`); it never overwrites bytes in place. Orphaned temp objects are52 swept by a job (the `scheduled-jobs` skill).537. **Store where nothing executes.** Object storage or a directory outside the web root,54 no execute permission, no per-directory config overrides; private by default and55 access-checked on every read.568. **Serve safely.** Presigned GET with a short expiry, or an authenticated route that57 sets `Content-Disposition: attachment` for anything not meant to render inline, the58 stored detected `Content-Type`, `X-Content-Type-Options: nosniff`, and ideally a59 separate cookieless origin with a restrictive CSP (`default-src 'none'`) so a60 malicious file cannot run in the app's origin.619. **Scan and quarantine where the repo requires it** (malware scan, CDR, moderation)62 asynchronously through a job (the `background-jobs` skill); the file stays63 unavailable until cleared.6465## Tests (one per behaviour, each exercising it for real)6667- Oversize body rejected with `413` before the handler reads it; part-count cap enforced.68- Extension/type mismatch, double extension, and a renamed executable are rejected.69- Traversal filenames (`../../x`, `..\\x`, NUL) never reach the storage key.70- Valid upload is stored under a generated key and its metadata row exists.71- **Concurrency:** N (≥ 20) parallel uploads of the same filename by the same user all72 succeed with distinct keys, no `500`, no truncated or cross-wired bytes (compare73 hashes). Two concurrent replacements of the same avatar leave exactly one winner and74 no orphaned pointer. Build it with the `concurrency-and-async` skill's step 9 recipe.75- **Failure:** an upload aborted mid-stream leaves no `available` row and no file served.76- Download headers are exact; another user's file is refused (`403`/`404`).77- Import caps rows; export formula-prefixes dangerous cells; zip-slip entry rejected.7879## Done when8081Every test above that the ticket's surface touches passes, and each acceptance82criterion has evidence recorded via the `record-evidence` skill (the command and its83passing output, not prose).8485## Review checklist8687- [ ] Limits enforced before the body is read; streaming, not buffering.88- [ ] Allow-list plus byte sniffing; dangerous formats re-encoded, refused, or attachment-only.89- [ ] Generated storage keys; unique temp names; atomic commit; no in-place overwrite.90- [ ] Private storage, authorised reads, `nosniff`, `Content-Disposition`, separate origin.91- [ ] A concurrent-upload test and an aborted-upload test exist and pass.9293## Capture lore9495This skill is one of the places durable, reusable knowledge naturally surfaces:96**While placing storage you learn the bucket layout, the size limits and the separate origin user content is served from.** That kind of fact is *lore*. Capture it via the **lore-capture97protocol in your brief** (`CLAUDE.factory.md`, step 11 "Memory contribution"):98call the Memory MCP `suggest_lore` once at the close of your work — reusable99conventions, gotchas, decisions, and boundaries only, never per-ticket trivia.