Cloudflare Turnstile設置プラグイン(4.2/4.3系)

Cloudflare Turnstile のウィジェットを、EC-CUBE のログイン・会員登録・お問い合わせ・購入画面など8 か所に設置できるプラグインです。設置する画面は管理画面のトグルで1 画面ずつ ON / OFF できます。

複数ステップのフォームでは入力画面にウィジェットを表示し、確認画面からの送信時にも「入力画面で判定を通過したか」をサーバー側で再確認します。確認画面を飛ばした不正な直接送信も遮断します。

標準テーマ(default / admin)ではキーを設定するだけで表示されます。EC-CUBE 本体のファイルは一切変更しません。EC-CUBE 4.2.x / 4.3.x に 1 パッケージで対応します。

• 画面ごとの ON / OFF:8 つの設置箇所を、管理画面のトグルで個別に切り替えられます
• サーバー側での検証:ウィジェットを置くだけでなく、送信されたトークンを Cloudflare に問い合わせて検証します
• シークレットキーの暗号化保存:データベースに平文で保存しません。設定画面にも再表示しません
• 接続テスト:設定画面から実際に Cloudflare へ問い合わせ、キーの誤りをその場で確認できます
• テンプレート診断:テーマが標準と異なる画面を検出し、設定画面に警告を表示します
• 障害時は止めない:Cloudflare へ到達できないときは判定をスキップして処理を通します。トークンが無い・不正な場合は必ず遮断します
• 表示のカスタマイズ:テーマ(自動/ライト/ダーク)、サイズ(標準/可変幅/小)、表示言語、表示タイミングを選べます
• 多言語:日本語・英語のロケールファイルを同梱(店舗の表示言語に追従)
• 本体非改修:EC-CUBE 本体のファイルは変更しません

設定項目ごとに、ウィジェットが表示される画面と判定のタイミングは次のとおりです。

• 会員ログイン(初期値 有効):マイページログイン/カートログイン — ログインボタン押下時
• 会員登録(初期値 有効):会員登録の入力画面 — 確認画面へ進むボタン(標準テーマでは「同意する」)の押下時
• お問い合わせ(初期値 有効):お問い合わせの入力画面 — 「確認ページへ」押下時
• パスワード再発行(初期値 有効):申請画面 — 送信時
• パスワード再設定(初期値 無効):再設定画面 — 送信時
• 非会員購入 お客様情報(初期値 有効):お客様情報入力画面 — 「次へ」押下時
• ご注文手続き(初期値 無効):ご注文手続き画面(会員・非会員とも) — 「確認する」押下時
• 管理画面ログイン(初期値 無効):管理画面のログイン画面 — ログインボタン押下時

会員登録・お問い合わせ・ご注文手続きでは、ウィジェットは入力画面に表示されます。確認画面には表示されません。 お客様にとって表示位置が画面ごとにばらつかず、迷いにくくなります。

「会員ログイン」はマイページとカートで共通の設定です。どちらの画面もログインの送信先が同じであるため、片方だけを保護することはできません。

EC-CUBE の会員登録・お問い合わせ・購入は、入力 → 確認 → 完了と画面が進みます。このとき「どの画面まで進んだか」はリクエストのパラメータで指定されているだけなので、入力画面にウィジェットを置くだけでは、確認画面を飛ばして完了処理へ直接送信する経路が残ります。

本プラグインは 2 段階で確認します。

• 入力画面の送信時に Cloudflare へ問い合わせて判定する
• 判定に成功したことをサーバー側で 30 分間だけ記憶し、次の送信で1 回だけ使う(使うと記憶は消える)

これにより、1 回の判定で成立する送信は 1 件だけになります。確認画面を経由しない直接送信は遮断され、ブラウザの戻るボタンによる二重登録も起こりません。

ご注文手続きで判定に失敗した場合も、購入エラー画面には遷移せず、カートの内容を保持したままご注文手続き画面へ戻ります。 お客様はそのまま操作をやり直せます。

判定に失敗したときのメッセージは、ウィジェットのすぐ下に通常のエラーと同じ表示で出ます。

• キー設定:サイトキーとシークレットキーを入力します。シークレットキーは暗号化して保存され、保存後は画面に表示されません。変更するときだけ入力してください
• 接続テスト:保存済みのキーで実際に Cloudflare へ問い合わせます。シークレットキーの誤り、通信の遮断などを、公開前にその場で確認できます
• テンプレート診断:有効にした画面のテンプレートが標準と異なる場合、その項目に警告を表示します。カスタムテーマや決済プラグインによる差し替えに気づけます
• 管理画面ログインの保護:管理画面のログイン画面にもウィジェットを設置できます。万一ログインできなくなった場合は、同梱のコマンドで解除できます

インストール例(コマンドライン):

• bin/console eccube:plugin:install --code=CSTurnstile42
• bin/console eccube:plugin:enable --code=CSTurnstile42
• bin/console cache:clear --no-warmup

管理画面ログインの解除コマンド:

• bin/console cs-turnstile42:admin-login:disable

管理画面ログイン:キーの設定に誤りがあると、管理者ご自身がログインできなくなります。有効にする前に必ず接続テストを実行し、有効にした直後は別のブラウザでログインできることをご確認ください。万一の場合は同梱のコマンドで解除できます。

ご注文手続き:決済プラグインがこの画面を独自のテンプレートに差し替えている場合、ウィジェットが表示されないことがあります。その状態で有効にすると、お客様が注文を完了できなくなります。ウィジェットの動作は有効にしないと確認できないため、本番と同じ決済プラグインを導入したテスト環境で、有効にしてテスト購入を行ってから本番に反映してください。設定画面の診断でも警告を表示します。

無効化:Turnstile の表示と判定が停止しますが、設定データは残ります。再有効化すれば設定はそのまま復帰します。一時的に止めたい場合はこちらをご利用ください。

アンインストール(削除):サイトキー・シークレットキー・画面ごとの設定がすべて削除され、元に戻せません。EC-CUBE 標準の削除確認ダイアログではこの旨は表示されません。

また、EC-CUBE の認証キー(.env の ECCUBE_AUTH_MAGIC)を変更すると、保存済みのシークレットキーを復号できなくなります。その場合は設定画面で再入力してください。

対応 EC-CUBE バージョン:4.2.x / 4.3.x(4.4 以降は対象外。将来版は別商品を予定)

必要なもの:Cloudflare のアカウントと、Turnstile のサイトキー・シークレットキー。発行はお客様側で行っていただきます(本プラグインには含まれません)。無料枠および利用条件は Cloudflare の規約に従います。

ネットワーク:サーバーから challenges.cloudflare.com への HTTPS アウトバウンド通信が必要です。接続できない場合は判定をスキップして処理を通します(ログに記録されます)。

プライバシー:判定にあたり、アクセス元の IP アドレスが Cloudflare, Inc. に送信されます。会員の氏名・メールアドレス・注文内容は送信されません。プライバシーポリシーへの記載をご検討ください(記載例をマニュアルに掲載しています)。

データベース:EC-CUBE 公式要件の PostgreSQL / MySQL / SQLite に対応しています。

検証環境:EC-CUBE 4.2.3-p2 および 4.3.1-p1(いずれも PHP 8.1 / MySQL)で動作確認済み。PostgreSQL / SQLite でもインストールから設定の保存・削除まで確認しています。

テーマ:標準テーマ(default / admin)はキーの設定だけで表示されます。テンプレートを独自に改修している場合は、同梱マニュアルのコピペ手順(1 行)をご利用ください。4.2 / 4.3 で同じ手順が使えます。

他プラグイン:他の CAPTCHA プラグイン(reCAPTCHA など)と同一画面で併用しないでください。二重に表示され、いずれかの判定で必ず失敗します。

本体非改修:EC-CUBE 本体ファイルは変更しません。プラグインのみで機能を提供します。