Zod en API Routes Next.js: estricto, strip y lo que realmente protege contra campos adicionales
¿Qué problema estamos resolviendo?
Dos ataques que normalmente se analizan junto con una validación estricta son:
- Asignación masiva. El cliente envía
{"name":"Ivan","role":"admin"}al punto final de actualización del perfil y el servidor envíadb.user.update({ data: body }). El camporoleingresa a la base de datos. - Contaminación del prototipo. El cuerpo contiene la clave
__proto__oconstructor.prototype, y el código la fusiona recursivamente en un objeto a través de undeepMergeautoescrito, cambiando el prototipoObject.
Ambas vulnerabilidades surgen no de la ausencia de .strict(), sino del hecho de que el servidor utiliza un cuerpo de solicitud sin formato. Si validas a través de Zod y luego trabajas solo con el resultado de parse, las claves adicionales no llegarán incluso sin strict: de forma predeterminada, z.object las descarta (modo strip).
Tres modos de objeto
import { z } from "zod";
const Base = { name: z.string().min(1).max(100) };
z.object(Base).parse({ name: "a", role: "admin" });
// { name: "a" } — role молча удалён
z.object(Base).strict().parse({ name: "a", role: "admin" });
// ZodError: unrecognized key "role"
z.object(Base).passthrough().parse({ name: "a", role: "admin" });
// { name: "a", role: "admin" } — опасно для входных данныхEn Zod 4, los mismos modos están disponibles como constructores separados z.strictObject({...}) y z.looseObject({...}); Los métodos .strict() y .passthrough() se conservan por motivos de compatibilidad. Seleccione un estilo por proyecto.
¿Por qué entonces strict? Convierte una eliminación silenciosa en un error claro. Un cliente que escribió mal un nombre de campo (emial en lugar de email) recibe 400 con la clave, en lugar de un guardado "exitoso" sin correo electrónico. Para formularios y API internos, esto ahorra horas de depuración.
Plantilla de controlador
// app/api/profile/route.ts
import { z } from "zod";
import { NextResponse } from "next/server";
import { getSession } from "@/lib/auth";
import { db } from "@/lib/db";
const Address = z.strictObject({
city: z.string().max(80),
street: z.string().max(120),
});
const UpdateProfile = z.strictObject({
name: z.string().trim().min(1).max(100).optional(),
email: z.email().optional(), // в Zod 3: z.string().email()
address: Address.optional(),
});
export async function PATCH(req: Request) {
const session = await getSession();
if (!session) return NextResponse.json({ error: "unauthorized" }, { status: 401 });
let json: unknown;
try {
json = await req.json();
} catch {
return NextResponse.json({ error: "invalid JSON" }, { status: 400 });
}
const parsed = UpdateProfile.safeParse(json);
if (!parsed.success) {
return NextResponse.json(
{ error: "validation", issues: parsed.error.issues.map(i => ({ path: i.path, message: i.message })) },
{ status: 400 }
);
}
// только parsed.data, никогда json
const user = await db.user.update({ where: { id: session.userId }, data: parsed.data });
return NextResponse.json({ id: user.id, name: user.name, email: user.email });
}Detalles que a menudo se pasan por alto:
- `strict` no es recursivo. Un
z.objectanidado dentro de un objeto estricto permanece en modo de eliminación. Por lo tanto,Addressse declara por separado como estricto. - `req.json()` arroja una excepción en JSON no válido. Sin
try/catchel cliente recibirá 500 en lugar de 400. - `safeParse` en lugar de `parse` - para evitar detectar excepciones por errores normales del usuario.
- La respuesta también se filtra. Devuelve un conjunto explícito de campos, no el objeto de usuario completo con el hash de contraseña.
Parámetros y formularios de consulta
Todo lo que proviene de searchParams y FormData son cadenas. Utilice un yeso:
const ListQuery = z.strictObject({
page: z.coerce.number().int().min(1).default(1),
limit: z.coerce.number().int().min(1).max(100).default(20),
q: z.string().max(200).optional(),
});
const query = ListQuery.safeParse(Object.fromEntries(new URL(req.url).searchParams));Object.fromEntries pierde parámetros duplicados (?tag=a&tag=b). Si son necesarios, recopile la matriz mediante searchParams.getAll("tag") por separado.
Cómo diagnosticar
- Un cliente se queja de 400 después del lanzamiento de una aplicación móvil: la nueva versión envía un campo adicional, pero el esquema es estricto. Mire
issuesen la respuesta: la ruta a la clave estará allí. - El campo "no se guarda", no hay errores: el esquema no es estricto y la clave se llama de manera diferente a lo esperado. Habilite temporalmente
stricty vuelva a intentar la solicitud. - En los registros
__proto__en las claves, el escáner busca contaminación del prototipo. Si usasparsed.data, es ruido; Verifique si hay objetos sin formato en el código de combinación.
Cuando lo estricto se interpone en el camino
Los webhooks de servicios externos (sistemas de pago, mensajería instantánea) añaden periódicamente nuevos campos. Un esquema estricto sobre ellos convertirá una actualización inofensiva del proveedor en una falla de procesamiento. Para tales entradas, utilice el modo de franja y describa solo los campos necesarios. Lo mismo ocurre con las API públicas con compatibilidad con versiones anteriores: un esquema estricto en versiones antiguas de puntos finales puede dañar a los clientes que envían campos desde nuevas versiones.