Zod на API Routes Next.js: strict, strip и что на самом деле защищает от лишних полей
Какую проблему решаем
Две атаки, о которых обычно говорят в связке со строгой валидацией:
- Mass assignment. Клиент присылает
{"name":"Ivan","role":"admin"}в эндпоинт обновления профиля, а сервер делаетdb.user.update({ data: body }). Полеroleпроходит в базу. - Prototype pollution. В теле есть ключ
__proto__илиconstructor.prototype, и код рекурсивно сливает его в объект через самописныйdeepMerge, меняя прототипObject.
Обе уязвимости возникают не из-за отсутствия .strict(), а из-за того, что сервер использует сырое тело запроса. Если вы валидируете через Zod и дальше работаете только с результатом parse, лишние ключи туда не попадут даже без strict: по умолчанию z.object их отбрасывает (режим strip).
Три режима объекта
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" } — опасно для входных данныхВ Zod 4 те же режимы доступны как отдельные конструкторы z.strictObject({...}) и z.looseObject({...}); методы .strict() и .passthrough() сохранены для совместимости. Выберите один стиль на проект.
Зачем тогда strict? Он превращает молчаливое удаление в явную ошибку. Клиент, который опечатался в имени поля (emial вместо email), получает 400 с указанием ключа, а не «успешное» сохранение без email. Для внутренних API и форм это экономит часы отладки.
Шаблон обработчика
// 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 });
}Детали, которые часто упускают:
- `strict` не рекурсивен. Вложенный
z.objectвнутри строгого объекта остаётся в режиме strip. ПоэтомуAddressобъявлен отдельно как строгий. - `req.json()` бросает исключение на некорректном JSON. Без
try/catchклиент получит 500 вместо 400. - `safeParse` вместо `parse` — чтобы не ловить исключения для обычных ошибок пользователя.
- Ответ тоже фильтруется. Возвращайте явный набор полей, а не весь объект пользователя с хешем пароля.
Query-параметры и формы
Всё, что приходит из searchParams и FormData, — строки. Используйте приведение:
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 теряет повторяющиеся параметры (?tag=a&tag=b). Если они нужны, собирайте массив через searchParams.getAll("tag") отдельно.
Как диагностировать
- Клиент жалуется на 400 после релиза мобильного приложения: новая версия шлёт дополнительное поле, а схема строгая. Посмотрите
issuesв ответе — там будет путь к ключу. - Поле «не сохраняется», ошибок нет: схема не строгая, и ключ называется иначе, чем ожидаете. Временно включите
strictи повторите запрос. - В логах
__proto__в ключах — сканер ищет prototype pollution. Если используетеparsed.data, это шум; проверьте, нет ли в коде слияния сырых объектов.
Когда strict мешает
Вебхуки внешних сервисов (платёжные системы, мессенджеры) регулярно добавляют новые поля. Строгая схема на них превратит безобидное обновление провайдера в отказ обработки. Для таких входов используйте режим strip и описывайте только нужные поля. То же для публичных API с обратной совместимостью: строгая схема на старых версиях эндпоинтов может ломать клиентов, которые отправляют поля из новых версий.