스팸 방지

초보자 연습

전제 조건: 아래 두 개의 초보자 가이드를 읽고, 웹 로컬 설정을 완료하고, 편집기의 루트에서 이 모노레포를 엽니다. 웹 설정은 apps/web/.env.local에 속합니다. Next.js는 ​​루트 .env를 읽지 않습니다. 기본 가짜 모드의 /dashboard는 데이터베이스가 없는 데모입니다. /auth에는 마이그레이션된 데이터베이스가 필요합니다.

빠른 용어: 작업 영역은 한 팀의 별도 사용자, 데이터 및 설정입니다. 서버는 신뢰할 수 있는 백엔드입니다. 제공업체 키를 브라우저 및 전화 코드에 보관하세요. 마이그레이션은 테이블을 생성하거나 업데이트하는 버전이 지정된 데이터베이스 변경입니다. AI 모델은 응답하는 엔진입니다. 모델 카탈로그는 서버의 사용 가능한 모델 ID 및 가격 목록입니다. 공급자는 AI, 이메일, 청구 서비스와 같은 외부 서비스입니다. 자격은 작업 영역에서 기능을 사용할 수 있도록 하는 부여입니다. 웹훅은 한 서비스가 다른 서비스의 URL에 보내는 메시지입니다.

1. 정확한 로컬/배포된 호스트 이름에 대한 Turnstile 테스트 위젯을 만듭니다. apps/web/.env.local에서 CAPTCHA_PROVIDER=turnstile 및 NEXT_PUBLIC_TURNSTILE_SITE_KEY를 설정합니다. TURNSTILE_SECRET_KEY를 서버 비밀 저장소에만 넣으세요.

2. 다시 시작하고 테스트 문의 양식을 제출하세요.

3. 챌린지와 성공적인 유효한 토큰 응답을 기대합니다. 모든 요청이 실패하면 호스트 이름과 키 쌍을 비교하십시오. 비밀 키를 절대 노출하지 마세요.

사용자 정의 코드의 경우 제공된 prompts/README.md로 시작하고 가장 가까운 프롬프트(앱 화면의 경우 prompts/new-app-screen.md, 공개 페이지의 경우 prompts/new-landing-page.md)를 복사합니다. 서버, 데이터베이스 또는 공급자 작업의 경우 코딩 에이전트에게 이 가이드의 작업을 제공하고 AGENTS.md, .ai/PROJECT_CONTEXT.md 및 일치하는 .ai/ 미러를 읽도록 요청하세요. 여기에 이름이 지정된 정확한 소스 파일을 검사하십시오. 편집하기 전에 파일을 나열하고 확인합니다. 작업 공간 소유권과 서버 전용 비밀을 보존합니다. 차이점을 보여주세요. 원하는 동작, 입력 및 출력 필드, 허용된 역할, 예상되는 성공 및 오류, 테스트 계정, 공급자 또는 장치를 알려주십시오. 샘플 값을 사용하십시오. 절대 진짜 비밀을 붙여넣지 마세요.

• 시작하기 전에
• 단말기 기본사항
• 웹 로컬 설정
• 에이전트 프롬프트 및 프로젝트 메모리

두 키 모두 활성화

CAPTCHA_PROVIDER=off가 기본값입니다. turnstile를 선택하고 Turnstile 애플리케이션에서 일치하는 호스트 이름을 구성한 후 두 키를 모두 제공하세요. NEXT_PUBLIC_TURNSTILE_SITE_KEY는 공개입니다. TURNSTILE_SECRET_KEY는 서버 검증자에서만 사용됩니다.

CAPTCHA_PROVIDER=turnstile
NEXT_PUBLIC_TURNSTILE_SITE_KEY=your-site-key
# TURNSTILE_SECRET_KEY belongs in the server secret store.

보호된 표면을 보존하세요

게이트에는 연락처/뉴스레터 양식과 Better Auth 로그인, 가입, OTP 및 비밀번호 재설정 자격 증명 엔드포인트가 포함됩니다. 유효성 검사/속도 제한을 보완합니다. 이는 세션 또는 작업 공간 인증을 대체하지 않습니다.

거부 및 복구 확인

유효한 토큰, 누락/만료/잘못된 토큰, 확인자 실패 및 클라이언트 위젯 재설정 후 재시도를 테스트합니다. 실행 가능한 사람이 직접 확인하는 사본 및 키보드 액세스를 유지하세요. 공급자를 전환하기 전에 선택한 인증 엔진의 적용 범위를 검사하세요.

• 보호된 양식
• 인증 엔진 차이점

설치 및 설정

CAPTCHA_PROVIDER가 검증기를 선택합니다: off(기본값 — 로컬 개발은 자격 증명 없이 유지) 또는 turnstile. turnstile을 켜면 서버의 TURNSTILE_SECRET_KEY와 클라이언트 위젯의 NEXT_PUBLIC_TURNSTILE_SITE_KEY가 필요합니다 — 하나라도 없으면 config 스키마가 시작을 실패시킵니다.

apps/web/src/captcha.ts는 프로세스 전체의 검증기 하나를 구성해 토큰을 10초 타임아웃으로 Cloudflare siteverify 엔드포인트에 POST하고 실패 시 닫힙니다 — 검증 불가한 토큰은 사람임의 증거로 취급되지 않습니다.

CAPTCHA_PROVIDER=turnstile
TURNSTILE_SECRET_KEY=…           # server-only
NEXT_PUBLIC_TURNSTILE_SITE_KEY=…

Guarded: sign-in/up, OTP send, reset,
contact + newsletter forms

구현 워크플로

CaptchaWidget(src/captcha-widget.tsx)이 위젯을 렌더링하고 cf-turnstile-response 필드를 부모 폼에 주입하며, 인증 클라이언트 호출은 x-captcha-response 헤더로 토큰을 전달합니다. contact와 newsletter 액션은 쓰기 전에 검증합니다 — 실패한 검사는 lead를 만들지 않고 status=captcha를 반환합니다.

packages/auth는 프로바이더가 켜져 있을 때 better-auth의 captcha 플러그인을 마운트합니다. CAPTCHA_ENDPOINTS는 자격 증명 입력과 토큰 발급 라우트 — 로그인, 가입, OTP 발송, 비밀번호 재설정 — 를 커버합니다. check-verification-otp 같은 소비 엔드포인트는 목록에서 제외됩니다: 거기서는 OTP나 토큰 자체가 증거입니다.

검증 및 문제 해결

보호된 각 폼을 토큰 없이, 그리고 잘못된 토큰으로 제출하세요 — 둘 다 실패 시 닫혀야 합니다. siteverify에 도달할 수 없을 때 통과가 아닌 거부가 되는지, provider=off가 로컬 개발을 열어 두는지, 시크릿이 클라이언트 번들이나 로그에 절대 도달하지 않는지 확인하세요.