turnstile
@rtorcato/cf-common/turnstile checks a Turnstile token against Cloudflare's
siteverify endpoint. The widget on your page produces the token. Your Worker
has to verify it before trusting the request.
import { assertTurnstile, verifyTurnstile } from '@rtorcato/cf-common/turnstile'
Keep the secret key out of source: wrangler secret put TURNSTILE_SECRET.
Assert
assertTurnstile returns the result when the challenge passed and throws a 403
CloudflareError when it didn't. Past this line, the token is valid.
import { requireEnv } from '@rtorcato/cf-common/env'
import { defineFetch } from '@rtorcato/cf-common/http'
import { clientIp } from '@rtorcato/cf-common/request'
export default defineFetch<Env>(async (request, env) => {
const form = await request.formData()
const token = String(form.get('cf-turnstile-response') ?? '')
await assertTurnstile(token, requireEnv(env, 'TURNSTILE_SECRET'), {
remoteip: clientIp(request) ?? undefined,
})
return Response.json({ ok: true })
})
The error's code is Turnstile's first error code (invalid-input-response,
timeout-or-duplicate, …), or TURNSTILE_FAILED when none is given. It is
exposed, so the client sees it.
Verify
verifyTurnstile takes the same arguments and returns the raw siteverify
result without throwing on a failed challenge. Use it when you want to branch:
const result = await verifyTurnstile(token, secret)
if (!result.success) {
console.log('turnstile failed', result['error-codes'])
return error(403, 'Failed challenge')
}
The result also carries hostname, action, cdata and challenge_ts, so you
can check the token came from your site and form.
When the call fails
If siteverify itself returns a non-2xx status, both functions throw a 502
CloudflareError with code TURNSTILE_HTTP_ERROR. That is an outage, not a
failed challenge.
Good to know
- A token is single use and expires after a few minutes. A second check of the
same token fails with
timeout-or-duplicate. remoteipis optional. Pass it to have Cloudflare compare it with the visitor that solved the challenge.- Cloudflare publishes test site keys and secrets that always pass or always fail. Use them in development and tests.
For a runnable walkthrough, see the /turnstile route in apps/example. See the
turnstile API reference for every option.