home / skills / hoangnguyen0403 / agent-skills-standard / file-uploads

file-uploads skill

safe

This skill securely handles file uploads in NestJS with validation, streaming to S3, and async processing to prevent DoS and scale.

npx playbooks add skill hoangnguyen0403/agent-skills-standard --skill file-uploads

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

1.3 KB

---
name: NestJS File Uploads
description: Secure file handling, Validation, and S3 streaming.
metadata:
  labels: [nestjs, upload, multer, s3]
  triggers:
    files: ['**/*.controller.ts']
    keywords: [FileInterceptor, Multer, S3, UploadedFile]
---

# File Upload Patterns

## **Priority: P0 (FOUNDATIONAL)**

Secure file upload handling with validation and storage patterns.

- **Magic Bytes**: NEVER trust `content-type` header or file extension.
  - **Tool**: Use `file-type` or `mmmagic` to verify the actual buffer signature.
- **Limits**: Set strict `limits: { fileSize: 5000000 }` (5MB) in Multer config to prevent DoS.

## Streaming (Scalability)

- **Memory Warning**: Default Multer `MemoryStorage` crashes servers with large files.
- **Pattern**: Use **Streaming** for any file > 10MB.
  - **Library**: `multer-s3` (direct upload to bucket) or `busboy` (raw stream processing).
  - **Architecture**:
    1. Client requests Signed URL from API.
    2. Client uploads directly to S3/GCS (Bypassing API server completely).
    3. **Pro Tip**: This is the only way to scale file uploads infinitely.

## Processing

- **Async**: Don't process images/videos in the HTTP Request.
- **Flow**:
  1. Upload file.
  2. Push `FileUploadedEvent` to Queue (BullMQ).
  3. Worker downloads, resizes/converts, and re-uploads.

Overview

This skill codifies secure and scalable file upload patterns for NestJS applications using TypeScript. It focuses on validation with magic-byte checks, strict request limits, streaming uploads for large files, and asynchronous processing with queues and workers. The guidance helps prevent DoS, avoid memory exhaustion, and enable infinite scaling via direct-to-cloud uploads.

How this skill works

The skill inspects incoming file buffers to verify actual file type using signature libraries (file-type or mmmagic) rather than trusting content-type or file extensions. It enforces strict Multer limits for small uploads and switches to streaming patterns (multer-s3 or busboy) for larger payloads. After upload, a FileUploadedEvent is pushed to a queue (BullMQ) so background workers can process and re-upload derivatives asynchronously.

When to use it

Handling user-submitted files where security and content validation are required
High-volume or large-file uploads that can exhaust server memory
Architectures that must scale uploads beyond single-server throughput
Workflows that require post-upload processing (resize, transcode, virus scan)
When regulatory or product constraints require strict size/type enforcement

Best practices

Always validate using magic bytes (file-type or mmmagic) and reject mismatches
Set strict Multer limits (e.g., fileSize: 5_000_000) for in-server uploads
Use streaming/direct-to-cloud uploads (signed URLs + S3/GCS) for files > 10MB
Never process large files inside HTTP handlers—push work to a queue (BullMQ)
Use workers to download, transform, and re-upload files asynchronously

Example use cases

A web app that accepts profile pictures: validate image signature, limit size, and enqueue resizing jobs
Mobile clients that request signed S3 URLs to upload multimedia directly, bypassing API servers
Video platform that streams uploads to S3, enqueues transcode jobs, and stores manifests
API that accepts small documents in-server with strict size/type checks and Sandboxed worker processing

FAQ

Why not trust content-type or file extension?

Those headers and extensions can be spoofed; magic-byte inspection verifies the real format to prevent malicious uploads.

When should I use streaming vs memory storage?

Use memory storage for tiny files under strict limits; use streaming or direct-to-cloud uploads for files larger than ~10MB to avoid memory and stability issues.