StackPractices
intermediate Por Mathias Paulenko

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-Type declarado — 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 fileSize y files le 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-Type que 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 MulterErrorSignificadoEstado
LIMIT_FILE_SIZEArchivo por encima de fileSize413
LIMIT_FILE_COUNTDemasiados archivos400
LIMIT_UNEXPECTED_FILENombre de campo incorrecto400
LIMIT_PART_COUNTDemasiadas partes multipart400
flowchart diagram: Subida del cliente

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ónMétodoFiabilidadCoste
ExtensiónVerificación de stringBaja (falsificable)Despreciable
MIME typeHeader Content-TypeMedia (falsificable)Despreciable
Magic bytesLectura de firma manual o file-typeAltaBajo (primeros N bytes)
Escaneo de contenidoParseo completo (Sharp, pdf-lib)Muy altaMedio
Escaneo de virusClamAV / servicio externoMuy altaAlto (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 diskStorage para cualquier cosa de más de ~1 MB. Reserva memoryStorage para 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 ../ en originalname es el truco más viejo que existe.
  • Define límites de fileSize y de files. Un tope de tamaño solo no detiene una petición con miles de archivos pequeños.
  • Verifica el contenido con file-type o 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 originalname sin sanitizar. Un ../../etc/passwd en ese campo puede sobrescribir archivos del sistema.
  • Usar memoryStorage con 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 RIFF para webp. WAV y AVI comparten esa cabecera de contenedor; comprueba la etiqueta WEBP en los bytes 8–11 o deja que file-type lo 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.

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);