file-upload

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