@arraypress/turnstile

Verify Cloudflare Turnstile CAPTCHA tokens. Two functions, zero dependencies.

Uses the Fetch API — works in Cloudflare Workers, Node.js 18+, Deno, Bun, and browsers.

Installation

npm install @arraypress/turnstile

Usage

import { verify } from '@arraypress/turnstile';

const token = formData.get('cf-turnstile-response');
const valid = await verify(token, 'your-secret-key');

if (!valid) {
  return new Response('CAPTCHA verification failed', { status: 403 });
}

API

verify(token, secretKey, options?)

Verify a Turnstile token. Returns true if valid, false otherwise. Fails closed — network errors, missing token, or missing secret all return false.

Options:

• remoteip — Client IP address (improves accuracy).
• idempotencyKey — Idempotency key for replay protection.

// With client IP
const valid = await verify(token, secretKey, {
  remoteip: request.headers.get('CF-Connecting-IP'),
});

verifyDetailed(token, secretKey, options?)

Same as verify but returns the full Cloudflare response object. Useful for logging and debugging.

import { verifyDetailed } from '@arraypress/turnstile';

const result = await verifyDetailed(token, secretKey);
// {
//   success: true,
//   challenge_ts: '2024-01-01T00:00:00Z',
//   hostname: 'example.com',
//   'error-codes': [],
// }

if (!result.success) {
  console.log('Turnstile errors:', result['error-codes']);
}

Returns an error object (without hitting Cloudflare) when token or secret is missing:

await verifyDetailed('', secretKey);
// { success: false, 'error-codes': ['missing-input-response'] }

Returns a fetch error object on network failure:

// { success: false, 'error-codes': ['fetch-error'], message: 'Connection refused' }

License

MIT