# Turnstile을 이용한 TanStack Start 폼 스팸 방지 > 클라이언트 IP를 위한 함수 미들웨어, 토큰 버킷, 서버 함수에서 검증하는 Turnstile, CSP로 TanStack Start 폼을 스팸으로부터 보호하세요. 2026-10-25 게시 · https://ikiform.com/ko/guides/spam-protection/tanstack-start 클라이언트 IP와 출처를 한 번 읽어 모든 서버 함수에 컨텍스트로 넘기는 함수 미들웨어를 추가하세요. 서버 함수에서는 입력을 검증하고, IP별 버킷에서 토큰을 하나 꺼내고, siteverify로 Turnstile 토큰을 검증한 뒤, 허니팟과 함께 필드를 전달합니다. Start가 설치하는 CSRF 미들웨어는 유지하고, `src/start.ts`를 만든다면 직접 다시 추가하세요. ## TanStack Start에서 다른 점 서버 함수는 동일 출처 RPC 엔드포인트입니다. Start는 `Sec-Fetch-Site`, `Origin`, `Referer`를 확인하는 CSRF 미들웨어로 다른 사이트로부터 서버 함수를 보호하며, 이 미들웨어는 다른 곳의 페이지가 방문자의 브라우저를 통해 POST하는 것을 막습니다. 원하는 헤더를 무엇이든 보낼 수 있는 스크립트는 막지 못합니다. 그래서 스팸 검사는 여전히 함수 안에 있어야 합니다. 이를 위한 Start의 기본 구성 요소는 미들웨어입니다. 함수 미들웨어는 검증기와 핸들러보다 먼저 실행되고, 요청 헤더를 읽을 수 있으며, `context`를 통해 핸들러에 값을 넘깁니다. IP 조회를 한 번만 작성하면 사이트의 모든 폼이 이를 사용합니다. 다이어그램: TanStack Start 서버 함수 앞의 미들웨어 체인 1. 브라우저나 스크립트가 서버 함수의 URL로 POST합니다. 2. Start의 CSRF 미들웨어는 여러분의 출처에서 왔다고 증명할 수 없는 POST를 거부합니다. 3. 방문자 미들웨어가 클라이언트 IP와 Origin 헤더를 읽어 컨텍스트로 넘깁니다. 4. 검증기가 핸들러보다 먼저 입력을 정규화합니다. 5. 핸들러가 해당 IP의 버킷에서 토큰을 하나 꺼냅니다. 남은 토큰이 없으면 나중에 다시 시도하라는 결과를 반환합니다. 6. Turnstile 토큰을 검증한 뒤 필드를 Ikiform으로 전달하고, Ikiform이 저장하고 허니팟 점수를 매깁니다. 각 계층은 다음 계층보다 저렴합니다. 거부된 POST는 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`(문서에는 Functions의 `context.ip`만 나와 있지만 Netlify 직원이 권장하는 헤더), Cloudflare는 `cf-connecting-ip`입니다. nginx 뒤에서 직접 운영하는 Node 서버라면 nginx가 설정하는 헤더를 쓰고, nginx를 우회해 앱에 접근할 수 없게 하세요. 미들웨어는 방문자의 `Origin`도 넘깁니다. Ikiform으로 가는 서버 측 fetch는 이 헤더를 보내지 않는데, Ikiform은 이를 읽어 무료 `localhost` 테스트를 알아보기 때문입니다. ## IP별 토큰 버킷 고정 구간에서는 스크립트가 한 분의 끝에 허용량 전부를 보내고 다음 분의 시작에 또 보낼 수 있습니다. 토큰 버킷은 시도를 하나씩 회복하므로, 오타를 고치는 사람은 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에서는 함수 인스턴스마다 맵이 따로 있어 실제 제한을 알 수 없습니다. 그런 곳에서는 [레이트 리밋 페이지](https://ikiform.com/ko/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." }; }); ``` - 검증기는 핸들러보다 먼저 실행되며 입력을 정규화하기만 합니다. 필드 오류는 폼이 해당 입력 옆에 표시할 수 있는 결과로 돌아옵니다. - 저렴한 검사부터 합니다. 이메일과 길이 검사는 비용이 없고, 버킷은 맵 조회 한 번, siteverify는 네트워크 호출 한 번입니다. - `action`은 `support`여야 합니다. 다른 위젯용으로 여러분의 site key로 발급된 토큰은 거부됩니다. - 허니팟 `_gotcha`는 여기서 확인하지 않고 전달하므로, 채워진 경우 검토할 수 있는 스팸으로 저장됩니다. > 서버 측 버전은 시크릿 키로 POST하므로 Ikiform은 **Allowed domains**와 자체 사람 확인을 건너뜁니다. 그러면 모든 POST가 서버의 IP에서 오고, 방문자당 분당 5건인 Standard 제한이 모든 방문자를 합쳐서 셉니다. 서버를 거쳐 POST하는 폼에는 Relaxed 또는 Custom [레이트 리밋](https://ikiform.com/ko/docs/rate-limits.md)을 고르고, `IKIFORM_SECRET_KEY`는 서버 전용 환경 변수에 두세요. ## 라우트와 위젯 위젯은 작은 훅에서 명시적으로 렌더링됩니다. 모듈 수준의 프라미스가 스크립트를 한 번만 불러오므로 클라이언트 내비게이션 중에 라우트가 여러 번 마운트되어도 괜찮으며, 토큰은 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 (