API Routes Next.js の Zod: strict、strip、そして実際に余分なフィールドから保護するもの
私たちはどのような問題を解決しているのでしょうか?
通常、厳密な検証と併せて議論される 2 つの攻撃は次のとおりです。
- 一括割り当て。 クライアントは
{"name":"Ivan","role":"admin"}をプロファイル更新エンドポイントに送信し、サーバーはdb.user.update({ data: body })を実行します。roleフィールドがデータベースに保存されます。 - プロトタイプ汚染 本体にはキー
__proto__またはconstructor.prototypeが含まれており、コードはそれを自己作成のdeepMergeを通じて再帰的にオブジェクトにマージし、プロトタイプObjectを変更します。
どちらの脆弱性も .strict() がないことが原因ではなく、サーバーが生のリクエスト本文を使用しているという事実から発生します。 Zod を介して検証し、parse の結果のみを操作する場合、strict がなくても追加のキーは取得されません。デフォルトでは、z.object はそれらを破棄します (ストリップ モード)。
3 つのオブジェクト モード
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() メソッドは互換性のために残されています。プロジェクトごとに 1 つのスタイルを選択します。
ではなぜ strict なのでしょうか?サイレント削除が明らかなエラーに変わります。フィールド名のスペルを間違えたクライアント (email ではなく emial) は、電子メールなしで「成功した」保存ではなく、キー付きの 400 を受け取ります。内部 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` は再帰的ではありません。 strict オブジェクト内のネストされた
z.objectはストリップ モードのままです。したがって、Addressは別に厳密として宣言されます。 - `req.json()` は無効な JSON に対して例外をスローします。
try/catchがない場合、クライアントは 400 ではなく 500 を受け取ります。 - `parse` ではなく
safeParse- 通常のユーザー エラーの例外をキャッチするのを避けるため。 - 応答もフィルタリングされます。 パスワード ハッシュを含むユーザー オブジェクト全体ではなく、フィールドの明示的なセットを返します。
クエリパラメータとフォーム
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__で、スキャナーはプロトタイプの汚染を探します。parsed.dataを使用するとノイズになります。マージ コードに生のオブジェクトがあるかどうかを確認します。
厳密さが邪魔になる場合
外部サービス (支払いシステム、インスタント メッセンジャー) の Webhook では、定期的に新しいフィールドが追加されます。これらに対する厳格なスキームにより、無害なプロバイダーの更新が処理エラーに変わります。このような入力にはストリップモードを使用し、必要なフィールドのみを記述します。下位互換性のあるパブリック API についても同様です。古いバージョンのエンドポイントで厳密なスキームを使用すると、新しいバージョンからフィールドを送信するクライアントが機能しなくなる可能性があります。