Subir archivos a S3 desde Next.js con URLs prefirmadas (y sin abrir el bucket)
El navegador sube directo a S3 o Garage con una URL prefirmada que genera tu servidor: clave, tipo, CORS, tamaño y comprobación al terminar.
Este blog es de CREA.MBA, un boilerplate de Next.js con auth, pagos y panel de admin ya montados. Ver qué incluye
Hay dos formas de subir un archivo desde una app de Next.js a un almacenamiento compatible con S3. La primera es mandarlo a tu servidor y que el servidor lo suba: sencillo, pero cada archivo atraviesa tu app, ocupa memoria y choca con los límites de tamaño del cuerpo de la petición. La segunda es que el navegador lo suba directamente al bucket, con una URL que tu servidor firma y que solo sirve para esa subida.
Esta segunda opción, la de las URLs prefirmadas (presigned URLs), es la que conviene en cuanto los archivos pasan de unos pocos megas. Aquí la montamos con el SDK v3 de AWS, el App Router y Better Auth para la sesión. Funciona igual contra AWS S3, Cloudflare R2 o un Garage en tu propio servidor, que es lo que usa el boilerplate de CREA.MBA.
Cómo funciona una URL prefirmada
- El navegador pide a tu servidor permiso para subir un archivo, con su nombre, tipo y tamaño.
- El servidor comprueba la sesión y las reglas (tipo permitido, tamaño máximo, cuota del usuario), decide la clave del objeto y firma una petición
PUTcon sus credenciales. - El navegador hace el
PUTdirectamente al almacenamiento, con el archivo en el cuerpo. - El navegador avisa a tu servidor de que ha terminado, y el servidor comprueba que el objeto existe y es lo que dijo ser.
Las credenciales de S3 nunca salen del servidor. La URL firmada lleva en la query la firma, la fecha y la caducidad, y solo vale para esa clave, ese método y esas cabeceras firmadas.
El cliente de S3
// src/lib/storage/s3.ts
import { S3Client } from '@aws-sdk/client-s3';
export const s3 = new S3Client({
region: process.env.S3_REGION || 'auto',
endpoint: process.env.S3_ENDPOINT,
credentials: {
accessKeyId: process.env.S3_ACCESS_KEY_ID!,
secretAccessKey: process.env.S3_SECRET_ACCESS_KEY!,
},
forcePathStyle: process.env.S3_FORCE_PATH_STYLE === 'true',
// Sin esto, las URLs prefirmadas de PUT llevan un checksum CRC32 de un cuerpo vacío
requestChecksumCalculation: 'WHEN_REQUIRED',
});Tres ajustes que con un almacenamiento distinto de AWS (y a veces con el propio AWS) dan problemas:
S3_REGION. El SDK firma incluyendo la región. Garage, por ejemplo, tiene la suya en el parámetros3_regionde su configuración (en los ejemplos de su documentación y en el del boilerplate,garage), y si el cliente firma con otra, Garage rechaza la petición con un error de cabecera de autorización. La firma es correcta en sí misma, pero está hecha para otra región.S3_FORCE_PATH_STYLE. Contrue, las URLs sonhttps://s3.tudominio.com/bucket/claveen vez dehttps://bucket.s3.tudominio.com/clave. En un servidor propio suele ser lo cómodo, porque no necesitas un subdominio por bucket.requestChecksumCalculation. Desde la versión 3.729.0, el SDK añade por defecto un checksum CRC32 a las peticiones. En una URL prefirmada paraPUTeso se traduce en un parámetrox-amz-checksum-crc32=AAAAAA==, que es el CRC32 de un cuerpo vacío: el SDK no conoce el archivo cuando firma. Hay quien lo ve fallar conSignatureDoesNotMatchy quien con un error de cabecera no soportada en almacenamientos compatibles. Con'WHEN_REQUIRED'el SDK solo calcula checksums cuando la operación lo exige y la URL sale limpia. Merece la pena generar una URL y mirarla antes de dar el código por bueno.
El endpoint que firma
// src/app/api/uploads/presign/route.ts
import { randomUUID } from 'node:crypto';
import { headers } from 'next/headers';
import { PutObjectCommand } from '@aws-sdk/client-s3';
import { getSignedUrl } from '@aws-sdk/s3-request-presigner';
import { z } from 'zod';
import { auth } from '@/lib/auth/server';
import { db } from '@/lib/db/client';
import { s3 } from '@/lib/storage/s3';
import { ALLOWED_TYPES, MAX_BYTES } from '@/lib/storage/limits';
// limits.ts:
// export const ALLOWED_TYPES = { 'image/png': 'png', 'image/jpeg': 'jpg',
// 'image/webp': 'webp', 'application/pdf': 'pdf' } as const;
// export const MAX_BYTES = 10 * 1024 * 1024; // 10 MB
const schema = z.object({
contentType: z.enum(Object.keys(ALLOWED_TYPES) as [keyof typeof ALLOWED_TYPES]),
size: z.number().int().positive().max(MAX_BYTES),
});
export async function POST(req: Request) {
const session = await auth.api.getSession({ headers: await headers() });
if (!session) return Response.json({ error: 'Unauthorized' }, { status: 401 });
const parsed = schema.safeParse(await req.json());
if (!parsed.success) return Response.json({ error: 'Invalid file' }, { status: 400 });
const { contentType, size } = parsed.data;
const key = `users/${session.user.id}/${randomUUID()}.${ALLOWED_TYPES[contentType]}`;
const uploadUrl = await getSignedUrl(
s3,
new PutObjectCommand({
Bucket: process.env.S3_BUCKET_NAME!,
Key: key,
ContentType: contentType,
ContentLength: size,
}),
// content-type no se firma por defecto; content-length sí, si lo pasas
{ expiresIn: 300, signableHeaders: new Set(['content-type']) },
);
await db.upload.create({
data: { key, userId: session.user.id, contentType, declaredSize: size, status: 'PENDING' },
});
return Response.json({ uploadUrl, key });
}Cuatro decisiones de este endpoint que importan más que el código en sí.
La clave la decide el servidor. Nunca uses el nombre que manda el cliente como clave. Un ../ o un nombre que coincide con el archivo de otro usuario son problemas que no quieres tener. Un UUID dentro de un prefijo por usuario evita colisiones y deja claro de quién es cada objeto. El nombre original, si lo necesitas para mostrarlo, va a la base de datos.
El tipo y el tamaño van firmados. Aquí hay una sorpresa: poner ContentType en el comando no basta. Si generas la URL con las opciones por defecto y miras el parámetro X-Amz-SignedHeaders, verás que solo contiene host. Para que el tipo forme parte de la firma hay que pedirlo con signableHeaders. Con ContentLength pasa lo contrario: si lo incluyes en el comando, el SDK lo firma sin que se lo pidas. Con los dos firmados, la URL queda así: X-Amz-SignedHeaders=content-length;content-type;host. El navegador tiene que mandar ese tipo y un cuerpo de ese mismo tamaño (el Content-Length lo calcula el propio navegador a partir del archivo). Si no coinciden, la firma falla y el almacenamiento rechaza la subida. Así un usuario no puede pedir permiso para un PNG de 200 KB y subir un HTML de 2 GB.
La URL caduca pronto. Cinco minutos bastan para empezar una subida. Una URL que vale una hora es una URL que puede acabar en un log, en un historial o en manos de otra persona durante una hora.
Queda un registro de la subida. Con una fila PENDING en un modelo Upload propio sabes qué subidas se pidieron y no se completaron, y puedes limpiar los objetos huérfanos más adelante.
Comprobar al terminar, de todas formas
El esquema de Zod valida el tamaño que el cliente dice que tiene el archivo, y la firma obliga a que el cuerpo mida eso. Pero cada almacenamiento compatible con S3 implementa la verificación de firmas a su manera, y no conviene que la seguridad de tu app dependa de un detalle que no has probado en el tuyo. (La alternativa clásica, un POST prefirmado con una condición content-length-range en la política, tiene el mismo problema: Garage, por ejemplo, implementa PostObject según su página de compatibilidad, pero no detalla qué condiciones hace cumplir).
La comprobación que funciona en cualquier sitio es la del final: cuando el navegador avisa de que ha subido el archivo, el servidor pide los metadatos del objeto con HeadObject y compara tamaño y tipo reales con lo que se autorizó. Si no cuadran, lo borra.
// src/app/api/uploads/complete/route.ts
import { DeleteObjectCommand, HeadObjectCommand } from '@aws-sdk/client-s3';
import { headers } from 'next/headers';
import { auth } from '@/lib/auth/server';
import { db } from '@/lib/db/client';
import { s3 } from '@/lib/storage/s3';
export async function POST(req: Request) {
const session = await auth.api.getSession({ headers: await headers() });
if (!session) return Response.json({ error: 'Unauthorized' }, { status: 401 });
const { key } = await req.json();
const upload = await db.upload.findFirst({
where: { key, userId: session.user.id, status: 'PENDING' },
});
if (!upload) return Response.json({ error: 'Not found' }, { status: 404 });
const head = await s3.send(
new HeadObjectCommand({ Bucket: process.env.S3_BUCKET_NAME!, Key: key }),
);
if (head.ContentLength !== upload.declaredSize || head.ContentType !== upload.contentType) {
await s3.send(new DeleteObjectCommand({ Bucket: process.env.S3_BUCKET_NAME!, Key: key }));
await db.upload.update({ where: { id: upload.id }, data: { status: 'REJECTED' } });
return Response.json({ error: 'Invalid file' }, { status: 400 });
}
await db.upload.update({
where: { id: upload.id },
data: { status: 'READY', size: head.ContentLength },
});
return Response.json({ ok: true });
}Fíjate en el where: { key, userId: session.user.id }: un usuario solo puede confirmar sus propias subidas. Es la misma regla que contamos en cada usuario ve solo sus datos.
Y una advertencia sobre el tipo: ContentType es solo una cabecera, y nadie ha mirado todavía qué hay dentro del archivo. Si tu app procesa los archivos (redimensiona imágenes, extrae texto de PDFs), valida el contenido real al procesarlo.
La subida desde el navegador
async function uploadFile(file: File) {
const res = await fetch('/api/uploads/presign', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ contentType: file.type, size: file.size }),
});
if (!res.ok) throw new Error('No se pudo preparar la subida');
const { uploadUrl, key } = await res.json();
const put = await fetch(uploadUrl, {
method: 'PUT',
headers: { 'Content-Type': file.type },
body: file,
});
if (!put.ok) throw new Error('La subida ha fallado');
await fetch('/api/uploads/complete', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ key }),
});
return key;
}El Content-Type del PUT tiene que ser el mismo que se firmó, letra por letra. Y si la subida falla con SignatureDoesNotMatch, lo primero es comparar las cabeceras que manda el navegador (pestaña de red) con las que aparecen en X-Amz-SignedHeaders. fetch no da progreso de subida; si necesitas una barra de progreso, usa XMLHttpRequest y su evento upload.onprogress.
CORS: el error que solo ves en el navegador
Un PUT desde tu dominio a s3.tudominio.com es una petición entre orígenes. El navegador manda primero una petición OPTIONS (el preflight) y, si el bucket no tiene una regla CORS que permita tu origen, el método PUT y la cabecera Content-Type, la subida se corta antes de empezar. Con curl todo funciona, porque curl no aplica CORS, y eso despista bastante.
La regla mínima, aplicada con cualquier cliente de S3 (PutBucketCors, que Garage también implementa):
{
"CORSRules": [
{
"AllowedOrigins": ["https://tudominio.com"],
"AllowedMethods": ["PUT"],
"AllowedHeaders": ["Content-Type"],
"MaxAgeSeconds": 3000
}
]
}aws s3api put-bucket-cors --bucket mi-bucket \
--cors-configuration file://cors.json \
--endpoint-url https://s3.tudominio.comPutBucketCors sustituye toda la configuración, así que incluye en el fichero todas las reglas que quieras conservar. Y añade http://localhost:3000 solo en el bucket de desarrollo.
Servir los archivos: público o firmado
Subir es la mitad. Para leer, depende del tipo de archivo:
- Archivos públicos (avatares, imágenes de un blog): un bucket o un dominio de CDN con lectura pública. Con Garage hay un detalle poco evidente: la API S3 no admite acceso anónimo, y la lectura pública se sirve desde su endpoint web, con el bucket en modo website y un alias que coincide con el nombre del dominio. Lo contamos con detalle en la migración de MinIO a Garage con Coolify.
- Archivos privados (facturas, documentos de los usuarios): el bucket se queda cerrado y el servidor genera una URL prefirmada de lectura con
GetObjectCommandcada vez que el usuario la pide, después de comprobar que el archivo es suyo.
Lo que te llevas
- El navegador sube directo al almacenamiento; tu servidor solo firma y verifica.
- La clave la decide el servidor y la URL caduca en minutos.
ContentTypeno se firma por defecto: pídelo consignableHeaders.ContentLength, si lo pasas, sí.- Con el SDK v3 reciente,
requestChecksumCalculation: 'WHEN_REQUIRED'para que la URL no lleve un checksum vacío. - Aun así, comprueba tamaño y tipo con
HeadObjectal terminar. - Sin regla CORS en el bucket, la subida falla en el navegador aunque
curlfuncione. - Con Garage, la región del cliente tiene que coincidir con la del servidor.
El boilerplate de CREA.MBA trae el cliente de S3 configurado por variables de entorno y Garage en el docker-compose de desarrollo, con su script de configuración inicial, así que en local el almacenamiento funciona tras un bun storage:setup.
¿Subes los archivos de tus usuarios pasando por el servidor o directo al bucket?
¿Te gustó este artículo?
Suscríbete para más tutoriales y tips sobre crear productos con IA