スパム対策

初心者向けのウォークスルー

前提条件: 以下の 2 つの初心者向けガイドを読み、Web ローカルのセットアップを完了し、エディターでルートにあるこのモノリポジトリを開きます。 Web 設定は apps/web/.env.local に属します。 Next.js はルート .env を読み取りません。デフォルトのフェイク モードの /dashboard はデータベースなしのデモです。 /auth には移行されたデータベースが必要です。

簡単に説明すると、ワークスペースは 1 つのチームの個別のユーザー、データ、設定です。サーバーは信頼できるバックエンドです。プロバイダー キーがブラウザーや電話コードに含まれないようにします。移行は、テーブルを作成または更新する、バージョン管理されたデータベースの変更です。 AI モデルは答えを返すエンジンです。モデル カタログは、使用可能なモデル ID と価格のサーバーのリストです。プロバイダーは、AI、電子メール、請求サービスなどの外部サービスです。資格は、ワークスペースで機能を使用できるようにする付与です。 Webhook は、あるサービスが別のサービスの URL に送信するメッセージです。

1. 正確なローカル/デプロイされたホスト名に対してターンスタイル テスト ウィジェットを作成します。 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/ ミラーを読み取るように依頼します。ここで指定されている正確なソース ファイルを調べてください。ファイルをリストし、編集前にチェックします。ワークスペースの所有権とサーバーのみの秘密を保持します。そして差分を見せてください。必要な動作、入力フィールドと出力フィールド、許可されるロール、予想される成功とエラー、テスト アカウント、プロバイダー、またはデバイスを指定します。サンプル値を使用します。絶対に本当の秘密を貼り付けないでください。

• 始める前に

【端末の基本】(/docs/web/terminal-basics)

• Webローカル設定
• エージェント プロンプトとプロジェクト メモリ

両方のキーを有効にする

CAPTCHA_PROVIDER=off がデフォルトです。 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 はプロセス全体で 1 つの検証器を構成し、トークンを 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 でローカル開発が開いたままになること、シークレットがクライアントバンドルやログに決して出ないことを検証します。