| name | file-upload |
| description | Use when creating, updating, reviewing, or debugging file uploads, image uploads, document uploads, attachments, storage, signed URLs, file validation, multipart upload, or upload security. |
File Upload
Use this skill for safe file upload and storage flows.
Rules
- Follow the project’s existing upload and storage pattern.
- Do not add a new storage provider, upload parser, image processor, queue system, or validation library unless already used or explicitly requested.
- Never trust client-provided filename, MIME type, extension, size, metadata, ownership, or storage path.
- Validate files server-side.
- Enforce file size limits.
- Allow only expected file types.
- Generate safe storage names.
- Keep uploaded files private by default unless the project intentionally uses public assets.
- Check authorization before upload, preview, download, delete, replace, or signed URL generation.
- Do not expose private storage paths.
- Preserve existing response, error, logging, and test patterns.
- Avoid unrelated refactors.
Inspect First
Before changing upload code, check existing patterns for:
- upload parser
- storage provider
- metadata model
- filename strategy
- allowed types and size limits
- signed URL behavior
- public/private access rules
- ownership or tenant scope
- cleanup behavior
- test style
Implementation Checklist
- Identify the upload field and accepted file types.
- Reuse existing upload/storage helpers.
- Validate authentication and permission.
- Validate file presence, size, MIME type, extension, and content when supported.
- Reject mismatched or unsupported files.
- Generate a safe filename/key.
- Store original filename only as metadata if needed.
- Save trusted metadata.
- Return only safe IDs or approved URLs.
- Clean up temporary or partial files after success/failure.
- Add or update relevant tests.
Security Rules
- Do not allow client-controlled storage paths.
- Prevent path traversal.
- Do not log file contents, private URLs, signed URLs, secrets, tokens, or storage keys.
- Do not store passwords, secrets, payment data, private keys, or tokens as normal uploads.
- Treat SVG, HTML, executable files, and document metadata as risky unless explicitly supported and sanitized.
- Strip metadata or scan files when the project has that pipeline.
- Serve private files only through authorized access.
Access Rules
- Users must not access another user’s private files.
- Organization or tenant files must verify membership and permissions.
- File ownership must be stored and enforced server-side.
- Signed or temporary URLs must expire when used.
- Public files must be intentionally public.
Error Handling
Use the project’s existing error format.
Common defaults:
| Case | Status |
|---|
| Missing file | 400 |
| Invalid type | 400 |
| File too large | 413 |
| Missing authentication | 401 |
| Forbidden | 403 |
| File not found | 404 |
| Storage failure | 503 |
Do not expose storage internals, raw provider errors, private paths, or secrets.
Tests
Cover relevant paths:
- valid upload
- missing file
- oversized file
- unsupported type
- MIME/content mismatch
- unauthorized upload
- forbidden file access
- signed URL generation
- storage failure
- metadata saved
- cleanup after failure
