Validación de Subidas en Node.js: Tipo, Tamaño y Contenido
Valida subidas de archivos en Node.js con multer — límites de tamaño, verificación de MIME, magic bytes y escaneo de virus para APIs Express.
Visión General
Las subidas de archivos son una de las vías más fáciles de comprometer un servidor. Si no las controlas, un atacante puede subir un webshell, sobrescribir archivos del sistema o ejecutar código en tu máquina — y el header Content-Type no lo va a impedir, porque lo escribe el cliente y puede declarar cualquier cosa. Esta receta monta las verificaciones que de verdad importan en una app Express con multer: límites de tamaño y cantidad, filtrado de extensión y MIME, verificación de magic bytes, límites de dimensiones de imagen y dónde encaja el escaneo de virus. Para la versión agnóstica con ejemplos en Python y Java, mira Validación de Subida de Archivos; esta es la implementación en Node.js.
Cuándo Usar
Llega a este montaje cuando se cumpla alguna de estas condiciones:
- Expones un endpoint que acepta archivos de usuarios — avatares, facturas, CSV, adjuntos.
- Necesitas restringir las subidas a una lista corta de tipos (solo imágenes, solo PDF).
- Quieres limitar tamaño y cantidad antes de que te coman el disco o la RAM.
- No puedes confiar en el
Content-Typedeclarado — o sea, siempre — y necesitas comprobar qué es realmente el archivo. - Sáltate el pipeline completo si las subidas solo llegan de servicios internos de confianza dentro de tu red. Ahí suele bastar un límite de tamaño más un antivirus; la validación de contenido por capas solo añade latencia que no necesitas.
Solución
Todo lo de abajo corre sobre multer 2.x. La rama 1.x está deprecada y arrastra vulnerabilidades conocidas, así que instala con la major fijada:
npm install multer@^2
Configuración básica de multer con límite de tamaño
const express = require("express");
const multer = require("multer");
const path = require("path");
const app = express();
const storage = multer.diskStorage({
destination: (req, file, cb) => {
cb(null, "uploads/");
},
filename: (req, file, cb) => {
const uniqueSuffix = Date.now() + "-" + Math.round(Math.random() * 1e9);
const ext = path.extname(file.originalname);
cb(null, file.fieldname + "-" + uniqueSuffix + ext);
}
});
const upload = multer({
storage: storage,
limits: {
fileSize: 5 * 1024 * 1024, // 5 MB
files: 1
}
});
app.post("/api/upload", upload.single("file"), (req, res) => {
if (!req.file) {
return res.status(400).json({ error: "No file uploaded" });
}
res.json({
filename: req.file.filename,
size: req.file.size,
mimetype: req.file.mimetype
});
});
app.listen(3000, () => console.log("Server running on port 3000"));
Validación de tipo de archivo con file filter
const ALLOWED_MIMETYPES = [
"image/jpeg",
"image/png",
"image/gif",
"image/webp",
"application/pdf"
];
const ALLOWED_EXTENSIONS = [".jpg", ".jpeg", ".png", ".gif", ".webp", ".pdf"];
const fileFilter = (req, file, cb) => {
const ext = path.extname(file.originalname).toLowerCase();
if (!ALLOWED_MIMETYPES.includes(file.mimetype)) {
return cb(new Error(`MIME type ${file.mimetype} is not allowed`), false);
}
if (!ALLOWED_EXTENSIONS.includes(ext)) {
return cb(new Error(`Extension ${ext} is not allowed`), false);
}
cb(null, true);
};
const upload = multer({
storage: multer.diskStorage({
destination: "uploads/",
filename: (req, file, cb) => {
const safeName = path.basename(file.originalname).replace(/[^a-zA-Z0-9.-]/g, "_");
const uniqueSuffix = Date.now() + "-" + Math.round(Math.random() * 1e9);
cb(null, uniqueSuffix + "-" + safeName);
}
}),
limits: {
fileSize: 5 * 1024 * 1024,
files: 5
},
fileFilter: fileFilter
});
app.post("/api/upload", upload.array("files", 5), (req, res) => {
const files = req.files.map(f => ({
filename: f.filename,
size: f.size,
mimetype: f.mimetype
}));
res.json({ uploaded: files });
});
// Los errores de multer y los del fileFilter llegan al mismo middleware — hay que distinguirlos
app.use((err, req, res, next) => {
if (err instanceof multer.MulterError) {
if (err.code === "LIMIT_FILE_SIZE") {
return res.status(413).json({ error: "File too large. Max size: 5MB" });
}
if (err.code === "LIMIT_FILE_COUNT") {
return res.status(400).json({ error: "Too many files. Max: 5" });
}
if (err.code === "LIMIT_UNEXPECTED_FILE") {
return res.status(400).json({ error: "Unexpected field name" });
}
return res.status(400).json({ error: err.message });
}
if (err) {
return res.status(400).json({ error: err.message });
}
next();
});
Verificación de MIME type basada en contenido
La versión manual de abajo enseña cómo es una verificación de firma por dentro. Fíjate en webp: es un contenedor RIFF, así que su etiqueta WEBP vive en los bytes 8–11. Comprobar el offset 0 dejaría pasar cualquier archivo RIFF, incluidos WAV y AVI.
const express = require("express");
const multer = require("multer");
const fs = require("fs");
const path = require("path");
const app = express();
const MAGIC_BYTES = {
"image/jpeg": { offset: 0, bytes: [0xff, 0xd8, 0xff] },
"image/png": { offset: 0, bytes: [0x89, 0x50, 0x4e, 0x47] },
"image/gif": { offset: 0, bytes: [0x47, 0x49, 0x46, 0x38] },
"application/pdf": { offset: 0, bytes: [0x25, 0x50, 0x44, 0x46] },
"image/webp": { offset: 8, bytes: [0x57, 0x45, 0x42, 0x50] } // "WEBP" después del header RIFF
};
function verifyMagicBytes(filePath, expectedMime) {
const expected = MAGIC_BYTES[expectedMime];
if (!expected) {
return Promise.resolve(true); // no hay firma definida para este tipo
}
return new Promise((resolve, reject) => {
fs.open(filePath, "r", (err, fd) => {
if (err) return reject(err);
const length = expected.offset + expected.bytes.length;
const buffer = Buffer.alloc(length);
fs.read(fd, buffer, 0, length, 0, (readErr) => {
fs.close(fd, () => {
if (readErr) return reject(readErr);
const matches = expected.bytes.every(
(byte, i) => buffer[expected.offset + i] === byte
);
resolve(matches);
});
});
});
});
}
const upload = multer({
storage: multer.diskStorage({
destination: "uploads/",
filename: (req, file, cb) => {
cb(null, Date.now() + "-" + file.originalname);
}
}),
limits: { fileSize: 5 * 1024 * 1024 },
fileFilter: (req, file, cb) => {
if (MAGIC_BYTES[file.mimetype]) {
cb(null, true);
} else {
cb(new Error("File type not allowed"), false);
}
}
});
app.post("/api/upload", upload.single("file"), async (req, res) => {
try {
const isValid = await verifyMagicBytes(req.file.path, req.file.mimetype);
if (!isValid) {
fs.unlinkSync(req.file.path);
return res.status(415).json({
error: "File content does not match declared type",
declared: req.file.mimetype
});
}
res.json({
filename: req.file.filename,
size: req.file.size,
mimetype: req.file.mimetype,
verified: true
});
} catch (err) {
res.status(500).json({ error: "File verification failed" });
}
});
app.listen(3000);
Verificación de contenido con el paquete file-type
Las firmas escritas a mano solo cubren los formatos que recuerdas añadir. El paquete file-type detecta cientos — incluidos los contenedores problemáticos — y es lo que usan la mayoría de servicios en producción. Es solo ESM, así que impórtalo con import() dinámico desde CommonJS:
app.post("/api/upload", upload.single("file"), async (req, res) => {
const { fileTypeFromFile } = await import("file-type");
const detected = await fileTypeFromFile(req.file.path);
const allowed = ["image/jpeg", "image/png", "image/webp", "application/pdf"];
if (!detected || !allowed.includes(detected.mime)) {
fs.unlinkSync(req.file.path);
return res.status(415).json({
error: "File content does not match an allowed type",
declared: req.file.mimetype,
detected: detected ? detected.mime : null
});
}
res.json({ filename: req.file.filename, mime: detected.mime, verified: true });
});
Un matiz que conviene saber: file-type inspecciona la firma del archivo, no su contenido. Un PNG estructuralmente válido igual puede esconder un exploit en los datos — para eso está la capa de antivirus del FAQ.
Validación de dimensiones de imagen con Sharp
const express = require("express");
const multer = require("multer");
const sharp = require("sharp");
const app = express();
const upload = multer({
storage: multer.memoryStorage(),
limits: { fileSize: 5 * 1024 * 1024 },
fileFilter: (req, file, cb) => {
if (file.mimetype.startsWith("image/")) {
cb(null, true);
} else {
cb(new Error("Only images allowed"), false);
}
}
});
app.post("/api/avatar", upload.single("avatar"), async (req, res) => {
try {
const metadata = await sharp(req.file.buffer).metadata();
if (metadata.width > 2000 || metadata.height > 2000) {
return res.status(400).json({
error: "Image too large. Max dimensions: 2000x2000",
actual: `${metadata.width}x${metadata.height}`
});
}
if (metadata.width < 100 || metadata.height < 100) {
return res.status(400).json({
error: "Image too small. Min dimensions: 100x100",
actual: `${metadata.width}x${metadata.height}`
});
}
const processedImage = await sharp(req.file.buffer)
.resize(256, 256, { fit: "cover" })
.jpeg({ quality: 80 })
.toBuffer();
// Aquí persistes processedImage en disco o S3
res.json({
message: "Avatar uploaded",
original: `${metadata.width}x${metadata.height}`,
processed: "256x256"
});
} catch (err) {
res.status(400).json({ error: "Invalid image file" });
}
});
app.listen(3000);
Middleware completo de subida con todas las validaciones
const express = require("express");
const multer = require("multer");
const fs = require("fs");
const path = require("path");
const app = express();
const CONFIG = {
maxFileSize: 5 * 1024 * 1024,
maxFiles: 5,
allowedMimetypes: ["image/jpeg", "image/png", "image/webp", "application/pdf"],
allowedExtensions: [".jpg", ".jpeg", ".png", ".webp", ".pdf"],
uploadDir: "uploads/"
};
// Los overrides se fusionan con CONFIG: cada llamada solo declara lo que cambia
function createUploadMiddleware(overrides = {}) {
const config = { ...CONFIG, ...overrides };
const fileFilter = (req, file, cb) => {
const ext = path.extname(file.originalname).toLowerCase();
if (!config.allowedMimetypes.includes(file.mimetype)) {
return cb(new Error(`MIME type ${file.mimetype} not allowed`), false);
}
if (!config.allowedExtensions.includes(ext)) {
return cb(new Error(`Extension ${ext} not allowed`), false);
}
cb(null, true);
};
const storage = multer.diskStorage({
destination: (req, file, cb) => {
fs.mkdirSync(config.uploadDir, { recursive: true });
cb(null, config.uploadDir);
},
filename: (req, file, cb) => {
const safeName = path.basename(file.originalname)
.replace(/[^a-zA-Z0-9.-]/g, "_")
.substring(0, 100);
cb(null, `${Date.now()}-${safeName}`);
}
});
return multer({
storage,
limits: {
fileSize: config.maxFileSize,
files: config.maxFiles
},
fileFilter
});
}
const uploadMiddleware = createUploadMiddleware();
app.post("/api/documents", uploadMiddleware.array("files", 5), async (req, res) => {
const { fileTypeFromFile } = await import("file-type");
for (const f of req.files) {
const detected = await fileTypeFromFile(f.path);
if (!detected || !CONFIG.allowedMimetypes.includes(detected.mime)) {
fs.unlinkSync(f.path);
return res.status(415).json({ error: `${f.originalname}: content not allowed` });
}
}
const results = req.files.map(f => ({
filename: f.filename,
size: f.size,
path: f.path
}));
res.json({ uploaded: results });
});
Explicación
La validación de subidas trabaja en cinco capas, de la más barata a la más cara. Conviene que los rechazos baratos ocurran antes que los costosos — no tiene sentido parsear un archivo que nunca iba a estar permitido.
- Límites de tamaño — las opciones
fileSizeyfilesle dicen a multer que rechace archivos y lotes excedidos antes de que toquen el disco. - Verificación de extensión — la extensión es tu primer filtro, pero falsificarla es trivial, así que trátala como un filtro de conveniencia, no como una frontera de seguridad.
- Verificación de MIME type — multer lee el
Content-Typeque manda el cliente. También es falsificable, pero sigue atrapando errores honestos y ataques perezosos. - Magic bytes — los primeros bytes del archivo dicen lo que realmente es. Un JPEG siempre abre con
FF D8 FF; un PDF con%PDF. Aquí es donde caen las subidas disfrazadas. - Inspección de contenido — dimensiones de imagen con Sharp, o un parseo completo/antivirus para lo más delicado. Es la capa más cara, por eso va la última.
La sanitización del nombre de archivo no es una capa sino una regla que aplica en todas: todo lo que venga en originalname — incluido ../ — es entrada del atacante hasta que lo limpies.
Cuando una capa rechaza un archivo, el cliente merece una respuesta precisa. Multer expone sus rechazos como códigos MulterError; mapéalos a códigos de estado que le digan al llamador qué falló:
| Código MulterError | Significado | Estado |
|---|---|---|
LIMIT_FILE_SIZE | Archivo por encima de fileSize | 413 |
LIMIT_FILE_COUNT | Demasiados archivos | 400 |
LIMIT_UNEXPECTED_FILE | Nombre de campo incorrecto | 400 |
LIMIT_PART_COUNT | Demasiadas partes multipart | 400 |
En producción aplican unas reglas extra. Las subidas van fuera del web root — o directo a S3/GCS — para que un .js o .php no pueda ejecutarse en el servidor web. Los límites del proxy también cuentan: nginx rechaza por defecto cualquier cosa que supere client_max_body_size (1 MB) antes de que Express la vea siquiera. Y las subidas son solo una superficie de entrada — combina esta receta con validación de inputs y sanitización de entrada de usuario para cubrir el resto del cuerpo de la petición.
Variantes
| Capa de Validación | Método | Fiabilidad | Coste |
|---|---|---|---|
| Extensión | Verificación de string | Baja (falsificable) | Despreciable |
| MIME type | Header Content-Type | Media (falsificable) | Despreciable |
| Magic bytes | Lectura de firma manual o file-type | Alta | Bajo (primeros N bytes) |
| Escaneo de contenido | Parseo completo (Sharp, pdf-lib) | Muy alta | Medio |
| Escaneo de virus | ClamAV / servicio externo | Muy alta | Alto (asíncrono) |
Mejores Prácticas
- Fija multer en 2.x (
npm install multer@^2). La rama 1.x tiene vulnerabilidades conocidas y ya no recibe parches. - Usa
diskStoragepara cualquier cosa de más de ~1 MB. ReservamemoryStoragepara archivos pequeños que procesas al momento, como el avatar de arriba — los buffers van directos a la RAM. - Sanitiza cada nombre de archivo antes de que toque el disco. Quita separadores de ruta y limita la longitud; el
../enoriginalnamees el truco más viejo que existe. - Define límites de
fileSizey defiles. Un tope de tamaño solo no detiene una petición con miles de archivos pequeños. - Verifica el contenido con
file-typeo magic bytes. El tipo declarado por sí solo no prueba nada. - Guarda las subidas fuera del web root, o envíalas directo a object storage. Servir archivos de usuarios desde el directorio de tu app es como se ejecutan los webshells.
- Pasa las imágenes por Sharp aunque las dimensiones parezcan bien — el procesado elimina los datos GPS del EXIF que los usuarios rara vez quieren compartir.
- Pon rate limit en los endpoints de subida. La validación cuesta CPU por petición, así que una ruta de subida sin throttle es un blanco fácil de DoS — la checklist de seguridad de endpoints cubre esto y el resto de la superficie del endpoint.
Errores Comunes
- Confiar en el header
Content-Type. Lo escribe el cliente; es una declaración, no un hecho. - Guardar archivos con el
originalnamesin sanitizar. Un../../etc/passwden ese campo puede sobrescribir archivos del sistema. - Usar
memoryStoragecon subidas grandes. Diez archivos de 50 MB en paralelo y el proceso se queda sin RAM. - Olvidar el límite de
files, y una sola petición puede traer miles de archivos. - Servir las subidas desde el mismo directorio que el código de la aplicación — el camino clásico hacia la ejecución de código.
- Verificar solo
RIFFpara webp. WAV y AVI comparten esa cabecera de contenedor; comprueba la etiquetaWEBPen los bytes 8–11 o deja quefile-typelo resuelva. - Quedarse en multer 1.x porque todavía funciona. Arrastra vulnerabilidades conocidas — actualiza.
Lecturas Recomendadas
Código complementario: el repo complementario tiene el middleware completo y el ejemplo de avatar como apps ejecutables.
- OWASP File Upload Cheat Sheet — la referencia canónica de la validación de subidas por capas.
- file-type — detección de firma para cientos de formatos, solo ESM.
- multer en GitHub — referencia de motores de almacenamiento,
limitsyfileFilter.
Preguntas frecuentes
¿Cómo subo archivos directamente a S3 en vez de disco local?
Cambia multer.diskStorage por multer-s3:
const multerS3 = require("multer-s3");
const { S3Client } = require("@aws-sdk/client-s3");
const s3 = new S3Client({ region: "us-east-1" });
const upload = multer({
storage: multerS3({
s3: s3,
bucket: "my-bucket",
key: (req, file, cb) => {
cb(null, `uploads/${Date.now()}-${file.originalname}`);
}
}),
limits: { fileSize: 5 * 1024 * 1024 }
});
La verificación de contenido se complica aquí — el archivo nunca aterriza en tu disco — así que ejecuta file-type sobre el stream en buffer o valida el objeto en S3 después de la subida.
¿Cómo escaneo archivos subidos en busca de virus?
Conecta el paquete clamscan a un demonio local de ClamAV y ejecútalo después de que multer guarde el archivo:
const NodeClam = require("clamscan");
const clamscan = new NodeClam().init({
clamscan: { path: "/usr/bin/clamscan" }
});
async function scanFile(filePath) {
const { isInfected } = await clamscan.scanFile(filePath);
if (isInfected) {
fs.unlinkSync(filePath);
throw new Error("File infected");
}
}
Escanea de forma asíncrona siempre que puedas — mantener la petición abierta durante un escaneo completo añade segundos de latencia a cada subida.
¿Debo usar memoryStorage o diskStorage?
Usa memoryStorage para archivos pequeños (menos de ~1 MB) que necesitan procesado inmediato, como redimensionar un avatar. Todo lo demás va a diskStorage — los buffers viven en RAM, así que unas pocas subidas grandes en paralelo sobre memoryStorage la agotan rápido.
¿Cómo manejo múltiples tipos de archivo con diferentes límites?
Construye un middleware por tipo. La factoría fusiona tus overrides con los valores por defecto, así que solo declaras lo que cambia:
const imageUpload = createUploadMiddleware({
allowedMimetypes: ["image/jpeg", "image/png"],
allowedExtensions: [".jpg", ".png"],
maxFileSize: 2 * 1024 * 1024
});
const docUpload = createUploadMiddleware({
allowedMimetypes: ["application/pdf"],
allowedExtensions: [".pdf"],
maxFileSize: 10 * 1024 * 1024
});
app.post("/api/images", imageUpload.single("image"), imageHandler);
app.post("/api/docs", docUpload.single("doc"), docHandler);
Recursos Relacionados
Validación de Subida de Archivos
Cómo manejar subidas de archivos de forma segura con validación de tamaño, tipo y contenido.
RecipeSubida de Archivos Drag and Drop en JavaScript con HTML5
Implementa subida de archivos drag and drop nativa con HTML5 en JavaScript: zona de arrastre, validación, barra de progreso y vistas previas.
RecipeValidación de Input: Schemas en 3 Lenguajes
Valida el input de usuarios en el límite de la API con librerías de schemas. Ejemplos con Pydantic, Zod y Jakarta Validation, sanitización y errores estructurados.
RecipeSanitizar Input de Usuario
Cómo sanitizar y validar input de usuario en Python, Java y JavaScript para prevenir ataques de inyección.
DocPlantilla de Checklist de Seguridad para Endpoints
Una plantilla de checklist para endurecer laptops, estaciones de trabajo y dispositivos móviles que acceden a datos y sistemas corporativos.