Subidas seguras de archivos en Next.js con Uppy y Templates firmados de Transloadit

Separa la autorización de la aplicación de la ejecución de la subida

El navegador es un solicitante no confiable, incluso cuando la interfaz forma parte de tu aplicación Next.js. Un Client Component puede contener la Auth Key pública y un ID de Template, pero nunca debe contener el Auth Secret del Workspace, credenciales de almacenamiento sin procesar ni autorización para elegir Steps de procesamiento arbitrarios. Mantén el Auth Secret detrás de un Route Handler y haz que ese endpoint decida si el usuario actual de la aplicación puede iniciar esta subida específica.

Esa decisión es independiente de la integridad de la solicitud de Transloadit. Una firma válida demuestra que tu servidor aprobó los parámetros serializados de la Assembly durante un periodo limitado; no demuestra que la persona que solicita una firma a tu servidor sea propietaria de un proyecto, se mantenga dentro del cupo, haya superado una verificación de CSRF o pueda publicar el resultado. El adaptador de autorización de la aplicación debe aplicar esas reglas antes de firmar. El Template guardado limita entonces lo que Transloadit ejecutará.

Bloquea el Template antes de exponer el formulario de subida

Crea el flujo de trabajo de procesamiento como un Template guardado. Establece allow_steps_override en false para que un navegador no pueda enviar Steps de reemplazo junto con su template_id. Activa «Exigir una firma válida» en este Template o exige firmas correctas para todo el Workspace. Son controles distintos: el Template bloqueado fija el grafo de procesamiento, mientras que la aplicación obligatoria de firmas rechaza los parámetros firmados que se hayan alterado, hayan vencido o no sean válidos por cualquier otro motivo. Tu aplicación sigue decidiendo qué usuario puede recibir esos parámetros.

Repite en el límite de procesamiento las comprobaciones de cliente de bajo costo aplicadas en la interfaz. El ejemplo limita cada archivo a 50 MiB, limita cada Assembly a cinco archivos y usa /file/filter con los metadatos MIME detectados, en lugar de confiar en el nombre del archivo o en la declaración del navegador. Adapta la lista exacta de elementos permitidos al producto. Añade verificación, análisis de malware, cuarentena o revisión humana cuando el riesgo del contenido lo requiera; ninguna comprobación MIME por sí sola hace seguro el contenido arbitrario de los usuarios.

El valor user_uploads identifica las credenciales de Template almacenadas en el Workspace. Concede a esa entidad externa únicamente las operaciones de almacenamiento, el bucket y las rutas que requiere este flujo de trabajo. El navegador no recibe ni firma la clave de acceso subyacente. Así, la rotación de credenciales puede realizarse independientemente del paquete de Next.js, pero debe coordinarse porque afecta a todos los Templates que hacen referencia al registro.

{
  "allow_steps_override": false,
  "auth": {
    "max_number_of_files": 5,
    "max_size": 52428800
  },
  "notify_url": "https://app.example.com/api/transloadit-notifications",
  "steps": {
    ":original": {
      "robot": "/upload/handle"
    },
    "accepted_images": {
      "use": ":original",
      "robot": "/file/filter",
      "accepts": [
        ["${file.mime}", "regex", "^(image/jpeg|image/png|image/webp)$"]
      ],
      "error_on_decline": true,
      "error_msg": "Only JPEG, PNG, and WebP images are accepted"
    },
    "stored": {
      "use": "accepted_images",
      "robot": "/s3/store",
      "credentials": "user_uploads"
    }
  }
}

Firma una solicitud de corta duración en un módulo server-only

Mantén la configuración del servidor en variables de entorno sin el prefijo NEXT_PUBLIC_ e importa server-only al principio del módulo de firma. Next.js hará que la compilación falle si el código del cliente importa ese módulo. El marcador es una medida de protección útil, no un gestor de secretos: las políticas de acceso de producción, el enmascaramiento de datos sensibles en los registros, el aislamiento del entorno de vista previa y la rotación de la credencial siguen siendo importantes.

El SDK de Node añade la Auth Key configurada, serializa los parámetros y devuelve exactamente esa cadena params con su firma. Devuelve ambos valores sin cambios. Analizar la cadena, añadir un campo o volver a serializarla en un orden diferente después de firmarla genera un payload distinto que debe rechazarse. El ejemplo establece un vencimiento de cinco minutos porque Uppy solicita las opciones inmediatamente antes de crear la Assembly y añade un nonce nuevo para cada autorización.

Selecciona el Template en el servidor. No aceptes template_id, steps, notify_url, credenciales de exportación ni valores de transformación sin límites del cuerpo de la solicitud para firmarlos sin más. Si el producto realmente ofrece varios flujos de trabajo de subida, asigna una operación pequeña del nivel de la aplicación, como avatar o product-gallery, a un Template y a límites incluidos en una lista de permitidos después de comprobar el permiso del usuario.

import 'server-only'

import { randomUUID } from 'node:crypto'

import { Transloadit } from 'transloadit'

export interface AssemblyOptions {
  params: string
  signature: string
}

type TransloaditEnvironmentName =
  | 'TRANSLOADIT_KEY'
  | 'TRANSLOADIT_SECRET'
  | 'TRANSLOADIT_TEMPLATE_ID'

function readServerEnvironment(name: TransloaditEnvironmentName): string {
  const value = process.env[name]
  if (value == null || value === '') {
    throw new Error('Missing Transloadit server configuration')
  }

  return value
}

const templateId = readServerEnvironment('TRANSLOADIT_TEMPLATE_ID')
const transloadit = new Transloadit({
  authKey: readServerEnvironment('TRANSLOADIT_KEY'),
  authSecret: readServerEnvironment('TRANSLOADIT_SECRET'),
})

export function createAssemblyOptions(): AssemblyOptions {
  const requestParameters = {
    auth: {
      expires: new Date(Date.now() + 5 * 60 * 1000).toISOString(),
      nonce: randomUUID(),
    },
    template_id: templateId,
  }

  return transloadit.calcSignature(requestParameters)
}

Protege el endpoint de firma del App Router

Se puede acceder a un Route Handler como a cualquier otro endpoint HTTP. La función authorizeUpload del ejemplo es deliberadamente específica de la aplicación: conéctala con la biblioteca de sesiones existente del proyecto, las comprobaciones de propiedad de los recursos, la estrategia de CSRF y el limitador de tasa de solicitudes compartido. Devuelve la denegación antes de generar la firma. En aplicaciones multiinquilino, aplica los límites tanto por inquilino como por usuario y comprueba qué inquilino será propietario del recurso resultante.

La ruta no acepta parámetros arbitrarios de Assembly y marca la respuesta correcta como no-store. Su mensaje público de fallo es genérico de manera intencional. Registra en el servidor un identificador interno de solicitud o de traza, la categoría de la decisión y el ID del actor, pero no devuelvas al navegador trazas de pila, identificadores de cuenta, cuerpos de respuestas de terceros ni detalles de la credencial. Deja que los fallos inesperados utilicen la gestión centralizada de errores saneados de la aplicación, en lugar de envolver cada llamada en un bloque catch que genere ruido.

Limitar la tasa de solicitudes de la ruta de firma controla la creación de Assemblies, pero no sustituye los límites de facturación de la cuenta, los límites de archivos del Template ni las cuotas de la aplicación. Aplica los tres. Una firma es una capacidad de corta duración: cualquiera que obtenga el payload firmado completo puede intentar enviarlo mientras siga siendo válido. Por eso, envíalo solo mediante HTTPS y evita que se conserve en datos analíticos, almacenamiento del navegador, URL y registros.

import type { NextRequest } from 'next/server'

import { NextResponse } from 'next/server'

import { authorizeUpload } from '../../../server/upload-authorization'
import {
  type AssemblyOptions,
  createAssemblyOptions,
} from '../../../server/transloadit-options'

interface ErrorResponse {
  error: string
}

export async function POST(
  request: NextRequest,
): Promise<NextResponse<AssemblyOptions | ErrorResponse>> {
  const permission = await authorizeUpload(request)
  if (!permission.allowed) {
    return NextResponse.json({ error: 'Upload not allowed' }, { status: 403 })
  }

  return NextResponse.json(createAssemblyOptions(), {
    headers: { 'Cache-Control': 'no-store' },
  })
}

Monta Uppy una sola vez dentro de un Client Component

Uppy necesita API del navegador, por lo que el componente de subida se encuentra detrás de un límite use client. Crea una sola vez la instancia de Uppy mediante un inicializador de estado diferido. Volver a crearla durante el renderizado descarta los archivos seleccionados y rompe el control del ciclo de vida. Este componente destruye la instancia cuando controla todo el ciclo de vida de la subida. Si las subidas deben continuar al navegar entre rutas, eleva la instancia a un proveedor del cliente con un ciclo de vida más largo y destrúyela cuando finalice ese proveedor.

La función asíncrona assemblyOptions llama a la ruta protegida mientras Uppy prepara la subida. Comprueba response.ok, gestiona de forma segura el JSON malformado, valida la estructura de la respuesta y solo muestra un error de autorización estable para el usuario. El Dashboard de Uppy proporciona la interfaz de selección, progreso, cancelación y errores, mientras que el plugin de Transloadit crea la Assembly y envía los archivos mediante una infraestructura de subidas reanudables. La secuencia acotada de tiempos de reintento ayuda ante fallos temporales sin reintentar indefinidamente.

Esos reintentos funcionan mientras esta instancia de Uppy siga activa. No permiten que el componente mostrado recupere los archivos seleccionados ni el estado de la Assembly después de recargar la página. Si la recuperación tras una recarga es un requisito del producto, configura y prueba Golden Retriever u otro diseño de persistencia documentado con el plugin de Transloadit; no deduzcas esa capacidad únicamente del protocolo tus ni de retryDelays.

Los límites del navegador reflejan los del Template para ofrecer una respuesta rápida, pero no constituyen el límite de seguridad. Quien realiza la llamada puede omitir el componente, y los metadatos de los archivos pueden ser falsos. Mantén en el Template bloqueado las comprobaciones autoritativas de cantidad de archivos, tamaño en bytes y contenido detectado, así como la política de exportación. Decide también si cancelar en el navegador debe cancelar solo la transferencia, la Assembly o el registro del recurso en la aplicación; después, prueba esa decisión en lugar de suponer que los tres estados son idénticos.

'use client'

import Uppy from '@uppy/core'
import Dashboard from '@uppy/react/dashboard'
import Transloadit from '@uppy/transloadit'
import { type ReactNode, useEffect, useState } from 'react'
import { z } from 'zod'

import '@uppy/core/css/style.min.css'
import '@uppy/dashboard/css/style.min.css'

const assemblyOptionsSchema = z.object({
  params: z.string().min(1),
  signature: z.string().regex(/^(sha1|sha256|sha384):[0-9a-f]+$/),
})

async function fetchAssemblyOptions(): Promise<z.infer<typeof assemblyOptionsSchema>> {
  const response = await fetch('/api/transloadit-params', {
    method: 'POST',
    headers: { Accept: 'application/json' },
  })

  if (!response.ok) {
    throw new Error('Could not authorize this upload. Try again.')
  }

  const responseBody: unknown = await response.json().catch(() => null)
  const parsedOptions = assemblyOptionsSchema.safeParse(responseBody)
  if (!parsedOptions.success) {
    throw new Error('Could not authorize this upload. Try again.')
  }

  return parsedOptions.data
}

function createUppy(): Uppy {
  return new Uppy({
    restrictions: {
      allowedFileTypes: ['image/jpeg', 'image/png', 'image/webp'],
      maxFileSize: 50 * 1024 * 1024,
      maxNumberOfFiles: 5,
    },
  }).use(Transloadit, {
    assemblyOptions: fetchAssemblyOptions,
    retryDelays: [0, 1_000, 3_000, 5_000],
    waitForEncoding: false,
  })
}

export function UploadForm(): ReactNode {
  const [uppy] = useState(createUppy)

  useEffect(() => {
    return () => uppy.destroy()
  }, [uppy])

  return <Dashboard height={420} proudlyDisplayPoweredByUppy={false} uppy={uppy} />
}

Concilia el progreso, los reintentos y la finalización

El progreso de la transferencia y el progreso del procesamiento responden preguntas diferentes. Con waitForEncoding: false, la interfaz puede finalizar después de que los bytes lleguen a Transloadit mientras continúan la validación, la transformación y la exportación. Escucha transloadit:assembly-created y asocia el ID de la Assembly con un registro pendiente de la aplicación. Así, una navegación puede interrumpir la observación en el navegador sin perder la identidad necesaria para la conciliación.

Incluye un notify_url fijo en el Template controlado por el servidor para gestionar la finalización asíncrona. El controlador de notificaciones debe verificar la firma mediante el Auth Secret asociado con la Auth Key de la Assembly, validar la carga útil, vincular el ID de la Assembly con el registro pendiente esperado y aplicar los resultados de forma idempotente antes de devolver una respuesta correcta. Las notificaciones pueden reintentarse, por lo que un duplicado debe confirmar el estado terminal existente en lugar de crear otro recurso o evento de publicación.

Usa waitForEncoding: true solo para flujos de trabajo cortos en los que el usuario deba permanecer en la página y el código del navegador necesite realmente los resultados finales. Incluso entonces, conserva una ruta de recuperación del lado del servidor porque las pestañas se cierran y las conexiones desaparecen. Una tarea programada de conciliación puede consultar las Assemblies no terminales cuyas notificaciones no se recibieron. Separa la política de reintentos según el fallo: reanuda la transferencia tras una interrupción de red, solicita nuevas opciones firmadas cuando venzan antes de crear la Assembly y detente ante un rechazo de la política hasta que el usuario cambie el archivo.

Prueba los controles como atacante y como usuario cuya operación fue interrumpida

Prueba el endpoint de firma sin una sesión, con el inquilino incorrecto, con un token CSRF ausente o no válido cuando corresponda, por encima de su límite de tasa de solicitudes y después de revocar el permiso. Confirma que ninguna respuesta ni ningún registro contenga el Auth Secret, credenciales de Template, una traza de pila o el error sin procesar de una dependencia. Intenta reemplazar el template_id, añadir steps, extender auth.expires y enviar opciones firmadas después de que hayan vencido; los controles de firma o de Template deberían rechazar la solicitud no válida.

Prueba un JPEG permitido, un tipo MIME no permitido con una extensión de imagen, un archivo demasiado grande, demasiados archivos, un archivo de cero bytes, una pérdida de conexión en varios desplazamientos, la recarga del navegador, la cancelación, una autorización vencida, una notificación duplicada, la denegación del almacenamiento y un fallo de procesamiento posterior a la subida. Confirma que el comportamiento al recargar coincida con el diseño de persistencia, en lugar de suponer que la recuperación es automática. Verifica con el teclado y las tecnologías de asistencia que los anuncios de progreso y errores sean accesibles; después, inspecciona el almacenamiento temporal y los registros de la aplicación para detectar filtraciones o estados pendientes permanentes.

Supervisa las denegaciones de firmas, las decisiones de limitación de la tasa de solicitudes, las tasas de creación y fallo de Assemblies, la recuperación de subidas, la latencia del procesamiento, la antigüedad de las notificaciones, los errores de almacenamiento y la antigüedad de los registros pendientes sin registrar payloads protegidos. Genera alertas ante cambios sostenidos, no ante equivocaciones individuales de los usuarios. Conserva el ID del Template y una versión del flujo de trabajo administrada por la aplicación en los registros operativos, porque un Template guardado puede cambiar con el tiempo.