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. 서버 verify 바꾸기
둘이 가장 가까운 곳입니다. 요청과 응답 모양이 거의 필드별로 줄을 맞춥니다.
| 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도 Caputchin과 똑같이 verify 호출에 JSON을 받으니, 본문 모양이 그대로 옮겨 갑니다. 오류 코드를 포함한 전체 요청/응답 레퍼런스는 백엔드에서 토큰 검증하기에 있고; 프레임워크 스니펫은 백엔드 예제에 있습니다.
Turnstile 연동이 응답에서 action이나 cdata를 읽었다면, Caputchin에는 직접적인 등가물이 없음에 유의하세요; 그것들은 당신이 위젯에 설정하는 Turnstile 고유의 라벨입니다. Caputchin의 유사한 메타데이터(어떤 게임을 했는지, 그 점수)는 응답의 platform 블록에 살며 정보 제공용일 뿐입니다.
옮겨 가는 것, 그리고 나아지는 것
- 여전히 깔끔한 통과/실패. 가능한 한 가장 단순한 신뢰 규칙,
if (success)를 유지하며, 유지할 확률이나 임계값이 없습니다. - 당신이 Turnstile을 고른 그 프라이버시 자세, 유지됨. Caputchin은 IP도, User-Agent도, 지문도, 행동 텔레메트리도 수집하지 않습니다; 프로토콜에 방문자 식별자를 둘 곳이 없습니다. 철학을 보세요.
- 선택적 게임. 보이지 않거나 관리형인 챌린지 대신, 검증을 방문자가 진짜로 하는 짧은 게임으로 바꿀 수 있으며, 그것이 AI 풀이기에 버티는 부분입니다. 게임 추가를 보세요.
- 엄격한 CSP는 엄격한 채로. Caputchin은 빡빡한 Content-Security-Policy 아래에서 돌아갑니다; 정책을 느슨하게 하는 대신 몇 개의 오리진을 허용합니다. Caputchin이 게임을 샌드박싱하는 방법을 보세요.
함정
- 두 키, 두 집. 공개 키(
cpt_pub_...)는 페이지에; 시크릿(cpt_sec_...)은 서버 측에만, 바로 Turnstile의 규율입니다. 시크릿을 브라우저로 보내지 마세요. - 토큰은 일회용. Turnstile처럼, 토큰은 한 번 검증합니다. 그것을 캐시하거나 리플레이하지 마세요.
- 백엔드가 읽는 필드 이름을 바꾸세요. 숨겨진 필드는
cf-turnstile-response가 아니라caputchin-token이며, 흔한 한 줄 실수입니다. action/cdata없음. 그것들로 분기했다면, 그 로직을 다른 곳으로 옮기세요; Caputchin은 그것들을 지니지 않습니다.
함께 보기
- 위젯 추가: 전체 클라이언트 설정.
- 백엔드에서 토큰 검증하기: 권위 있는
siteverify레퍼런스. - 백엔드 예제: 각 언어로 된 verify 호출.
- 게임 추가: 검증을 게임으로 바꾸기.