Cloudflare Turnstile から移行する
Caputchin は Cloudflare Turnstile と同じ 2 つの部分のモデルを使います。トークンを生むページ上のウィジェットと、それを確認するサーバー側のチェックです。なので移行は、書き直しではなく、ほとんど機械的な入れ替えです。Turnstile は、共通のプロバイダーの中で Caputchin に最も近いものです。どちらもリスクのスコアではなく権威ある合格/不合格を返すので、再調整するしきい値がありません。このガイドは各部品の前後を示します。
まだ Caputchin のアカウントとサイトキーを作っていなければ、先に アカウントを作成 してください。ページのための 公開鍵（cpt_pub_...）と、バックエンドのための シークレット（cpt_sec_...）が要ります。Turnstile のサイトキーとシークレットキーと同じ分割です。
メンタルモデルは変わらない
Turnstile の周りにすでに作ったすべて、ウィジェットをレンダリングし、トークンを集め、それをサーバーに POST し、リクエストを信頼する前にそれを検証することは、そのままです。変わるのは名前とエンドポイントだけです。
1. クライアントのスニペットを入れ替える
| Turnstile | Caputchin | |
|---|---|---|
| スクリプト | <script src="https://challenges.cloudflare.com/turnstile/v0/api.js" async defer> | <script src="https://cdn.jsdelivr.net/npm/@caputchin/widget@3/dist/widget.js"> |
| 要素 | <div class="cf-turnstile" data-sitekey="..."> | <caputchin-widget sitekey="cpt_pub_..."> |
| フォームのトークンフィールド | cf-turnstile-response（自動注入） | caputchin-token（自動注入） |
| JS でトークンを読む | turnstile.getResponse() | pass イベント の detail.token |
Turnstile と同じく、Caputchin のウィジェットは、それが座るフォームに 隠しのトークンフィールドを自動注入 するので、フォームがすでに通常の POST をしていたなら、変えるのは要素と、バックエンドが読むフィールド名だけです。完全なクライアントの設定は ウィジェットを追加 を、CDN と npm の選択 を参照してください。
2. サーバーの検証を入れ替える
ここが 2 つが最も近いところです。リクエストとレスポンスの形が、ほぼフィールドごとに揃います。
| Turnstile | Caputchin | |
|---|---|---|
| エンドポイント | POST https://challenges.cloudflare.com/turnstile/v0/siteverify | POST https://caputchin.com/api/v1/siteverify |
| リクエストのフィールド | secret、response | secret、response（同一） |
| レスポンス | { success, challenge_ts, hostname, "error-codes", action, cdata } | { success, challenge_ts, hostname, error-codes } |
| 信頼のルール | success === true のときだけ動く | success === true のときだけ動く（同一） |
ほとんどのスタックで、検証のコードへの唯一の変更は URL とシークレットの値です。どちらもすでに success で分岐するので、移植するスコアのしきい値はありません。Turnstile も検証の呼び出しに JSON を受け付けます。まさに Caputchin と同じなので、ボディの形はそのまま持ち越されます。エラーコードを含む完全なリクエスト/レスポンスのリファレンスは バックエンドでトークンを検証 に、フレームワークのスニペットは バックエンドの例 にあります。
Turnstile の連携がレスポンスから action や cdata を読んでいたなら、Caputchin には直接の同等物がないことに注意してください。それらは、あなたがウィジェットに設定する Turnstile 固有のラベルです。Caputchin の類似のメタデータ（どのゲームが遊ばれたか、そのスコア）は、レスポンスの platform ブロックにあり、情報用のみです。
持ち越されるもの、良くなるもの
- なおクリーンな合格/不合格。 最も単純な信頼のルール
if (success)を保ち、維持する確率もしきい値もありません。 - あなたが Turnstile を選んだプライバシーの姿勢、保たれる。 Caputchin は IP、User-Agent、フィンガープリント、行動テレメトリを集めません。プロトコルには訪問者の識別子を置く場所がありません。哲学 を参照。
- 任意のゲーム。 不可視の、または管理されたチャレンジの代わりに、検証を、訪問者が実際に遊ぶ短いゲームに変えられ、それが AI のソルバーに対して持ちこたえる部分です。ゲームを追加 を参照。
- 厳格な CSP は厳格なまま。 Caputchin はきつい Content-Security-Policy の下で走ります。ポリシーを緩めるのではなく、少数のオリジンを許可します。Caputchin がゲームをどうサンドボックス化するか を参照。
落とし穴
- 2 つのキー、2 つの家。 公開鍵（
cpt_pub_...）はページに、シークレット（cpt_sec_...）はサーバー側だけに留まります。まさに Turnstile の規律です。シークレットをブラウザに出荷しないでください。 - トークンは一度きり。 Turnstile と同じく、トークンは一度検証されます。キャッシュもリプレイもしないでください。
- バックエンドが読むフィールド名を変える。 隠しフィールドは
cf-turnstile-responseではなくcaputchin-tokenです。よくある一行の見落としです。 action/cdataなし。 それらで分岐していたなら、そのロジックをほかへ移してください。Caputchin はそれらを運びません。
あわせて読む
- ウィジェットを追加：完全なクライアントの設定。
- バックエンドでトークンを検証：権威ある
siteverifyのリファレンス。 - バックエンドの例：各言語での検証の呼び出し。
- ゲームを追加：検証をゲームに変える。