Chapter 18 — Form Data & File Uploads

The why

User-supplied files are the single highest-risk input your backend will ever accept. A .jpg that contains a PHP shell, a .xlsx with a 1 KB body that decompresses into 5 GB, a filename that navigates to ../../etc/passwd — all of these come in through your upload endpoint. This chapter is how you survive them.

Three flavors of request body

The browser or mobile app does not send "data" — it sends bytes with a Content-Type header that tells your server how to read those bytes.

NestJS — wiring up a multipart endpoint

NestJS uses multer under the hood via @nestjs/platform-express.

import {
  Controller, Post, UploadedFile, UseInterceptors, BadRequestException, Body,
} from '@nestjs/common';
import { FileInterceptor } from '@nestjs/platform-express';
import { memoryStorage } from 'multer

• FileInterceptor('document', ...) — the form field name MUST be document.
• FilesInterceptor('docs', 5, ...) — multiple files in one field (max 5).
• FileFieldsInterceptor([{name:'photo'},{name:'pdf'}]) — different fields, each with their own files.

Validating files — six checks every upload must pass

1. Size limit (cheap — do first)

Already enforced by limits.fileSize. Reject early so you never buffer a huge file.

2. Filename — never trust it

The original filename is attacker-controlled. Do not save it as-is, do not use it in S3 keys, do not echo it back unsanitised in HTML.

// ❌ Path traversal — attacker uploads "../../etc/passwd"
const dest = path.join('/uploads', file.originalname);
 
// ✅ Generate a new name; preserve only the extension after sanitising it
import { extname } from 'path';
import { v4 as

3. MIME type — declared vs actual

file.mimetype is what the client claims. An attacker can send whatever they want. This is not sufficient — move to step 4.

4. Magic bytes — read the actual file

Every real file format starts with a known byte signature. PDFs start with %PDF-. JPEGs start with FF D8 FF. A .jpg file that contains a PHP web shell will fail this check.

import { fileTypeFromBuffer } from 'file-type';
 
const detected = await fileTypeFromBuffer(file.buffer);
if (!detected) throw new BadRequestException('Unrecognised file');
 
const allowed =

5. Image dimensions / pixel-bomb protection

A 100 KB PNG can decode into a 1 GB bitmap (a "decompression bomb") and crash your image processor. Cap dimensions before any processing.

import sharp from 'sharp';
const meta = await sharp(file.buffer).metadata();
if ((meta.width ?? 0) > 8000 || (meta.height ?? 0

6. Antivirus scan

Run uploaded files through ClamAV (free, self-hosted) or a cloud AV API. Run the scan before the file becomes accessible to other users. Enqueue it as an async job (Chapter 15) and mark virus_scan_status when it completes.

Mixing JSON and files — the "stringified JSON" pattern

A common need: upload a document AND submit a structured object alongside it. With multipart/form-data, every field is a string — you cannot send nested JSON natively.

document: <File>
payload:  '{"customer_id":"abc","remarks":"front of PAN"}'   ← stringified

@Post('document')
@UseInterceptors(FileInterceptor('document'))
async upload(
  @UploadedFile() file: Express

Memory storage vs disk storage

In this project: always use memoryStorage() and stream to S3. The local disk on an app container vanishes on every deploy.

Set all limits — even the ones you "don't need"

{
  fileSize: 5 * 1024 * 1024,   // 5 MB per file
  files: 5,                    // max 5 files per request
  fields: 20,                  // max 20 non-file fields
  fieldNameSize: 100,
  fieldSize: 1024 * 100,       // 100 KB per text field

Without these, a single request can DoS your server with a million tiny fields.

The canonical upload pattern

Once validation passes, the flow is always the same:

1. Validate file (size, magic bytes, AV)
2. Compute a key:                             kyc/{user_id}/{uuid}.{ext}
3. Upload to S3 (server-side encrypted, private)
4. INSERT a row into the `documents` table:
     id, owner_id, type, s3_key, content_type,
     size_bytes, sha256_hash, virus_scan_status
5. Return the document ID to the client (NOT the S3 URL)

Why store metadata in the DB and bytes in S3? Because databases are slow and expensive at storing blobs, you want to query documents via SQL, and you may want different retention for the DB row vs. the S3 object.

Common mistakes

One thing to remember