Turnstileはウィジェット表示で完成しない、保護する送信をサーバーで検証する

フォームにTurnstileのウィジェットが表示されても、保護されている証拠にはなりません。Cloudflareのサーバー側検証のドキュメントは、Siteverifyによるトークン確認を求めています。確認なしで送信を受け付けるアプリケーションでは、ブラウザー上の成功表示から信頼できるサーバー判断は得られません。

目標は明確です。ブラウザーが合格したと言うだけで、保護対象の処理を進めないことです。最初にサーバーの判断を構築・テストし、次にウィジェットと利用者の再試行経路をつなげます。このガイドは実装・検証する手順を示すもので、ClickSyrupが読者のアプリをテストしたという意味ではありません。

ブラウザーからサーバーまでトークンを追う

Cloudflareの開始ガイドは、公開するsitekeyと非公開のsecret keyを区別しています。sitekeyはクライアント側に配置し、secretはサーバーが検証に使います。試作品を動かすためだけに、secretをブラウザーコード、公開リポジトリ、利用者に見える設定ファイルへ入れてはいけません。

ブラウザーがフォームとトークンを送ったら、バックエンドから固定のSiteverifyエンドポイントへ、必須項目のsecretとtokenを送ります。HTTPリクエストが完了したことを許可と見なさず、応答内容を検証してください。保護する処理を実行する前に、アプリケーションは確認結果を得る必要があります。

メール送信、レコード作成、依頼の受け付けといった業務処理は、その判断の後に置きます。処理してからトークンを確認するのでは順序が逆です。フロントエンドとバックエンドの双方が「相手が実施している」と思い込まないよう、実装チケットに順序を明記してください。

トークンがない場合、拒否された場合、検証応答を得られない場合を意識して扱います。そのまま処理を受け付けないでください。正当な利用者には使える再試行経路を用意し、適切な未送信入力を保持しつつ、機密データを診断ログへ残さないようにします。長いメッセージを失うことは改善すべき体験上の問題であり、検証を省く理由ではありません。

有効期限と再利用は別にテストする

Cloudflareは、トークンの有効期間を300秒、検証を一回限りとしています。期限切れまたは検証済みのトークンではtimeout-or-duplicateが返ることがあります。ページを開いた直後に得たトークンは、長いフォームを入力し終わる頃には使えない可能性があります。

ウィジェット成功直後に送信するだけでなく、入力に時間がかかる場合をテストしてください。新しいトークンを取得でき、業務処理を意図せず繰り返すことなく再試行できるかを確認します。通常の遅れから回復するために、利用者がトークンの仕組みを理解する必要はありません。

トークンの再利用と業務処理の冪等性は分けて考えます。有効なトークンだけでは、ネットワーク再試行やダブルクリック後に同じレコードが二つ作られないとは保証できません。必要な場合は業務処理自体が重複リクエストを認識するよう設計し、ウィジェットとは別にテストします。

バックエンドで検証呼び出しを再試行する場合は、同じトークンを無制限に検証できると仮定せず、APIで文書化された再試行・冪等性の仕組みを使います。ブラウザー送信、Siteverifyへのリクエスト、業務トランザクションのどの層を繰り返すかを明記してください。混同すると断続的な不具合を説明しにくくなります。

成功だけでなく、想定したホストとアクションを確認する

検証応答にはhostnameや、設定した場合のactionなどの文脈情報が含まれます。アプリケーションが定義した期待値と比較してください。信頼できない同じフォームから送られた値を「期待するホストやアクション」にすると、リクエスト自身が満たすべきルールを決めてしまいます。

Cloudflareのホスト名管理ガイドは、ウィジェットを使えるホストの認可方法を説明しています。ルートドメインを追加するとサブドメインも認可される点にも注意しています。範囲を意図して選び、ステージングから本番へ移るときに見直してください。ウィジェット設定とサーバー確認は、無関係な環境ではなく、想定した配備先を認める必要があります。

Turnstileは一つの層にすぎません。認証は利用者を識別し、認可は可能な操作を決めます。アプリケーションには引き続き入力検証と適切なリクエスト制御が必要です。チャレンジ成功を理由に任意のデータを受け付けたり、他人のアカウントへの操作を許可したりしてはいけません。

ページ配信の経路も点検します。キャッシュを使う場合、アカウント固有の応答や機密状態を共有キャッシュに入れないよう、Cloudflareキャッシュのガイドで説明する区別を守ってください。チャレンジが動いていても、別のキャッシュ設定による情報公開は直りません。

公開前に失敗ケースを証明する

Cloudflareは、成功・失敗を制御できるテストキーと実装ガイドを提供しています。これらの文書化された認証情報は適切なテスト環境で使い、本番保護には使わないでください。実際の訪問者チャレンジの結果に依存せず、再現可能な試験を行うためのものです。

正常送信、トークンなし、検証失敗、期限切れ、検証済みトークンの再利用、想定外のホストやアクションを含む受け入れ記録を作ります。各ケースで、利用者への表示と、バックエンドが実際に処理したかどうかを記録してください。安心させるメッセージだけでは、何も受け付けていない証拠になりません。

検証サービスの停止も計画に加え、公開前に利用者への動作を決めます。サービス復旧後の回復も確認してください。フォーム処理、リバースプロキシ、secret、配備環境を変更した後は特に、サイトの保守ルーチンへこれらの確認を組み込みます。

公開の基準はウィジェットのスクリーンショットではありません。許可された要求が意図どおり一度実行され、拒否された要求では保護対象の処理が実行されず、secretがサーバーに残り、正当な利用者が明確に再試行できるという再現可能な結果です。それが、見える部品の追加と保護の実施の違いです。