# Turnstile を使った TanStack Start フォームのスパム対策 > TanStack Start のフォームをスパムから守る方法。クライアント IP 用の関数ミドルウェア、トークンバケット、サーバー関数での Turnstile 検証、CSP。 公開日 2026-10-25 · https://ikiform.com/ja/guides/spam-protection/tanstack-start クライアント IP とオリジンを 1 回だけ読み、コンテキストとしてすべてのサーバー関数に渡す関数ミドルウェアを追加します。サーバー関数では入力を検証し、IP ごとのバケットからトークンを 1 つ取り、siteverify で Turnstile のトークンを検証してから、ハニーポットと一緒にフィールドを転送します。Start が組み込む CSRF ミドルウェアは残し、`src/start.ts` を作成する場合は自分で追加し直してください。 ## TanStack Start ならではの違い サーバー関数は同一オリジンの RPC エンドポイントです。Start は `Sec-Fetch-Site`、`Origin`、`Referer` を確認する CSRF ミドルウェアで他のサイトから保護しており、別のページが訪問者のブラウザー経由で送信することを防ぎます。ただし、好きなヘッダーを送れるスクリプトは防げません。そのため、スパムのチェックはやはり関数の中に置く必要があります。 これを実現する Start 自身の部品がミドルウェアです。関数ミドルウェアはバリデーターとハンドラーより前に実行され、リクエストヘッダーを読み、`context` を通じてハンドラーに値を渡せます。IP の取得を 1 回書けば、サイトのすべてのフォームで使えます。 図: TanStack Start のサーバー関数の前に並ぶミドルウェアの連鎖 1. ブラウザーかスクリプトが、サーバー関数の URL に送信します。 2. Start の CSRF ミドルウェアは、自分のオリジンから来たと証明できない送信を拒否します。 3. 訪問者ミドルウェアがクライアント IP と Origin ヘッダーを読み、コンテキストとして渡します。 4. バリデーターが、ハンドラーに渡る前に入力を正規化します。 5. ハンドラーはその IP のバケットからトークンを 1 つ取ります。残っていなければ、後でリトライするよう伝える結果を返します。 6. Turnstile のトークンを検証してから、フィールドを Ikiform に転送します。Ikiform が保存し、ハニーポットを評価します。 各層は次の層よりコストが低く、拒否された送信が siteverify や Ikiform に届くことはありません。 ## プロジェクトの準備 `ファイル`: ```text src/ routes/ support.tsx lib/ use-turnstile.ts server/ bucket.ts visitor.ts support.ts start.ts .env ``` `.env`: ```bash VITE_TURNSTILE_SITE_KEY=1x00000000000000000000AA TURNSTILE_SECRET_KEY=1x0000000000000000000000000000000AA IKIFORM_SECRET_KEY=ik_sk_your_secret_key CLIENT_IP_HEADER=x-forwarded-for ``` - Vite がブラウザーに公開するのは `VITE_` で始まる変数だけで、`import.meta.env` から読みます。シークレットには接頭辞がないので、サーバー上の `process.env` にしか存在しません。 - テスト用のキーは `localhost` を含むどのホストでも通ります。環境ごとに本物のキーに差し替えてください。 ## クライアント IP 用の関数ミドルウェア `src/server/visitor.ts`: ```ts import { createMiddleware } from "@tanstack/react-start"; import { getRequestHeader } from "@tanstack/react-start/server"; const HEADER = process.env.CLIENT_IP_HEADER ?? "x-forwarded-for"; export const visitor = createMiddleware({ type: "function" }).server(async ({ next }) => { const ip = getRequestHeader(HEADER)?.split(",")[0]?.trim() || "unknown"; return next({ context: { ip, origin: getRequestHeader("origin") ?? null } }); }); ``` `CLIENT_IP_HEADER` には、ホストが上書きするヘッダーを設定します。Vercel では `x-forwarded-for`、Netlify では `x-nf-client-connection-ip`（Netlify のスタッフが推奨しているものですが、ドキュメントに記載があるのは Functions の `context.ip` だけです）、Cloudflare では `cf-connecting-ip` です。nginx の背後にある自前の Node サーバーなら、nginx が設定するヘッダーを使い、nginx を経由せずにアプリへ到達できないようにしてください。このミドルウェアは訪問者の `Origin` も渡します。サーバー側から Ikiform への fetch はこれを送らず、Ikiform は無料の `localhost` テストを判定するためにこれを読むからです。 ## IP ごとのトークンバケット 固定ウィンドウでは、スクリプトが 1 分の終わりに上限いっぱいまで送り、次の 1 分の始めにもう一度送れてしまいます。トークンバケットは 1 回分ずつ回復するので、入力ミスを直す人が待つのは 1 分ではなく数秒です: `src/server/bucket.ts`: ```ts const CAPACITY = 3; const REFILL_MS = 20_000; const buckets = new Map(); export function take(key: string, now = Date.now()) { const saved = buckets.get(key) ?? { tokens: CAPACITY, at: now }; const tokens = Math.min(CAPACITY, saved.tokens + (now - saved.at) / REFILL_MS); if (tokens < 1) { buckets.set(key, { tokens, at: now }); return { ok: false, retryAfter: Math.ceil(((1 - tokens) * REFILL_MS) / 1000) }; } if (buckets.size > 50_000) buckets.clear(); buckets.set(key, { tokens: tokens - 1, at: now }); return { ok: true, retryAfter: 0 }; } ``` このカウンターはメモリ上にあり、コンテナで動かす `node .output/server/index.mjs` のような長時間動く単一サーバーなら正確です。Vercel や Netlify では関数のインスタンスごとに別々の Map を持つので、実際の上限はわかりません。その場合は[レート制限のページ](https://ikiform.com/ja/guides/spam-protection/rate-limiting.md)のようにバケットを Redis に移し、`take(key)` の形はそのままにします。 ## サーバー関数 `src/server/support.ts`: ```ts import { createServerFn } from "@tanstack/react-start"; import { take } from "./bucket"; import { visitor } from "./visitor"; const TOPICS = ["billing", "bug", "account", "other"]; const EMAIL = /^[^\s@]+@[^\s@]+\.[^\s@]+$/; export interface SupportInput { email: string; topic: string; message: string; _gotcha: string; token: string; } export type SupportResult = { ok: true } | { ok: false; field?: "email" | "message"; message: string }; async function isHuman(token: string, ip: string) { try { const response = await fetch("https://challenges.cloudflare.com/turnstile/v0/siteverify", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ secret: process.env.TURNSTILE_SECRET_KEY, response: token, remoteip: ip }), }); const verdict = (await response.json()) as { success: boolean; action?: string }; return verdict.success && verdict.action === "support"; } catch { return false; } } export const sendSupportRequest = createServerFn({ method: "POST" }) .middleware([visitor]) .validator((input: SupportInput) => ({ email: String(input.email ?? "").trim(), topic: TOPICS.includes(input.topic) ? input.topic : "other", message: String(input.message ?? "").trim().slice(0, 5000), _gotcha: String(input._gotcha ?? ""), token: String(input.token ?? "").slice(0, 2048), })) .handler(async ({ data, context }): Promise => { if (!EMAIL.test(data.email)) return { ok: false, field: "email", message: "Enter an address we can reply to." }; if (data.message.length < 10) return { ok: false, field: "message", message: "Tell us a little more." }; const limit = take(context.ip); if (!limit.ok) return { ok: false, message: `Too many requests. Try again in ${limit.retryAfter} seconds.` }; if (!(await isHuman(data.token, context.ip))) return { ok: false, message: "We couldn't confirm you're human." }; const { token: _token, ...fields } = data; const response = await fetch("https://ikiform.com/f/frm_xxxxxxxxxxxxxxxx", { method: "POST", headers: { Accept: "application/json", "Content-Type": "application/json", Authorization: `Bearer ${process.env.IKIFORM_SECRET_KEY}`, ...(context.origin ? { Origin: context.origin } : {}), }, body: JSON.stringify(fields), }).catch(() => null); return response?.ok ? { ok: true } : { ok: false, message: "Your request didn't send. Try again." }; }); ``` - バリデーターはハンドラーより前に実行され、入力を正規化するだけです。フィールドエラーは、フォームが該当する入力欄の横に表示できる結果として返ります。 - 安いチェックから先に行います。メールアドレスと長さのチェックはコストゼロ、バケットは Map の参照 1 回、siteverify はネットワーク呼び出し 1 回です。 - `action` は `support` でなければなりません。同じサイトキーで別のウィジェット用に発行されたトークンは拒否されます。 - ハニーポットの `_gotcha` はここではチェックせずに転送するので、入力されていればスパムとして保存され、後から確認できます。 > サーバー側の版はシークレットキーで送信するので、Ikiform は **Allowed domains** と自身の人間確認をスキップします。すべての送信がサーバーの IP から届くため、訪問者ごとに 1 分 5 件という Standard の制限は全訪問者の合計で数えられます。サーバー経由で送信するフォームには Relaxed か Custom の[レート制限](https://ikiform.com/ja/docs/rate-limits.md)を選び、`IKIFORM_SECRET_KEY` はサーバー専用の環境変数に置いてください。 ## ルートとウィジェット ウィジェットは小さなフックから明示的にレンダリングします。モジュールレベルの Promise によって、クライアント側のナビゲーションでルートが何度マウントされてもスクリプトは 1 回しか読み込まれず、トークンは Turnstile の `callback` で届きます: `src/lib/use-turnstile.ts`: ```ts import { useCallback, useEffect, useRef, useState } from "react"; interface Api { render( container: HTMLElement, options: { sitekey: string; action: string; callback: (token: string) => void; "expired-callback": () => void }, ): string; reset(widgetId: string): void; remove(widgetId: string): void; } let loading: Promise | undefined; function load() { loading ??= new Promise((resolve, reject) => { const script = document.createElement("script"); script.src = "https://challenges.cloudflare.com/turnstile/v0/api.js?render=explicit"; script.async = true; script.onload = () => { const api = (window as Window & { turnstile?: Api }).turnstile; if (api) resolve(api); else reject(new Error("Turnstile did not load")); }; script.onerror = () => reject(new Error("Turnstile did not load")); document.head.append(script); }); return loading; } export function useTurnstile(sitekey: string, action: string) { const ref = useRef(null); const api = useRef(null); const widget = useRef(null); const [token, setToken] = useState(""); useEffect(() => { let live = true; load().then((turnstile) => { if (!live || !ref.current) return; api.current = turnstile; widget.current = turnstile.render(ref.current, { sitekey, action, callback: setToken, "expired-callback": () => setToken(""), }); }); return () => { live = false; if (widget.current) api.current?.remove(widget.current); widget.current = null; }; }, [sitekey, action]); const reset = useCallback(() => { setToken(""); if (widget.current) api.current?.reset(widget.current); }, []); return { ref, token, reset }; } ``` `src/routes/support.tsx`: ```tsx import { createFileRoute } from "@tanstack/react-router"; import { useServerFn } from "@tanstack/react-start"; import { type FormEvent, useState } from "react"; import { useTurnstile } from "../lib/use-turnstile"; import { type SupportResult, sendSupportRequest } from "../server/support"; export const Route = createFileRoute("/support")({ component: Support }); function Support() { const send = useServerFn(sendSupportRequest); const turnstile = useTurnstile(import.meta.env.VITE_TURNSTILE_SITE_KEY, "support"); const [result, setResult] = useState(null); const [pending, setPending] = useState(false); async function onSubmit(event: FormEvent) { event.preventDefault(); const form = new FormData(event.currentTarget); setPending(true); try { setResult( await send({ data: { email: String(form.get("email") ?? ""), topic: String(form.get("topic") ?? ""), message: String(form.get("message") ?? ""), _gotcha: String(form.get("_gotcha") ?? ""), token: turnstile.token, }, }), ); } catch { setResult({ ok: false, message: "Couldn't reach the server. Try again." }); } finally { setPending(false); turnstile.reset(); } } if (result?.ok) return

Got it. We'll reply by email within a day.

; const error = result && !result.ok ? result : null; return (